# 9. Magnetostatics / Dipolar interactions¶

## 9.1. Dipolar interaction¶

ESPResSo contains methods to calculate the interactions between point dipoles

$U^{Dip}(\vec{r}) = D \cdot \left( \frac{(\vec{\mu}_i \cdot \vec{\mu}_j)}{r^3} - \frac{3 (\vec{\mu}_i \cdot \vec{r}) (\vec{\mu}_j \cdot \vec{r}) }{r^5} \right)$

where $$r=|\vec{r}|$$. The prefactor $$D$$ is can be set by the user and is given by

(1)$D =\frac{\mu_0 \mu}{4\pi}$

where $$\mu_0$$ and $$\mu$$ are the vacuum permittivity and the relative permittivity of the background material, respectively.

Magnetostatic interactions are activated via the actor framework:

from espressomd.magnetostatics import DipolarDirectSumCpu

direct_sum = DipolarDirectSumCpu(prefactor=1)
# ...
system.actors.remove(direct_sum)


The magnetostatics algorithms for periodic boundary conditions require some knowledge to use them properly. Uneducated use can result in completely unphysical simulations.

### 9.1.1. Dipolar P3M¶

This is the dipolar version of the P3M algorithm, described in [CerdaBLH08]. It is interfaced via espressomd.magnetostatics.DipolarP3M.

Make sure that you know the relevance of the P3M parameters before using P3M! If you are not sure, read the following references

Note that dipolar P3M does not work with non-cubic boxes.

The parameters of the dipolar P3M method can be tuned automatically, by providing accuracy=<TARGET_ACCURACY> to the method. It is also possible to pass a subset of the method parameters such as mesh. In that case, only the omitted parameters are tuned:

import espressomd.magnetostatics as magnetostatics
p3m = magnetostatics.DipolarP3M(prefactor=1, mesh=32, accuracy=1E-4)


It is important to note that the error estimates given in [CBLCHolm08] used in the tuning contain assumptions about the system. In particular, a homogeneous system is assumed. If this is no longer the case during the simulation, actual force and torque errors can be significantly larger.

### 9.1.2. Dipolar Layer Correction (DLC)¶

espressomd.magnetostatic_extensions.DLC

The dipolar layer correction (DLC) is used in conjunction with the dipolar P3M method to calculate dipolar interactions in a 2D-periodic system. It is based on [Bro04] and the dipolar version of Electrostatic Layer Correction (ELC).

Usage notes:

• The non-periodic direction is always the z-direction.
• The method relies on a slab of the simulation box perpendicular to the z-direction not to contain particles. The size in z-direction of this slab is controlled by the gap_size parameter. The user has to ensure that no particles enter this region by means of constraints or by fixing the particles’ z-coordinate. When there is no empty slab of the specified size, the method will silently produce wrong results.
• The method can be tuned using the accuracy parameter. In contrast to the electrostatic method, it refers to the energy. Furthermore, it is assumed that all dipole moment are as large as the largest of the dipoles in the system.

The method is used as follows:

import espressomd.magnetostatics as magnetostatics
import espressomd.magnetostatic_extensions as magnetostatic_extensions

p3m = magnetostatics.DipolarP3M(prefactor=1, accuracy=1E-4)
dlc = magnetostatic_extensions.DLC(maxPWerror=1E-5, gap_size=2.)


## 9.2. Dipolar direct sum¶

This interaction calculates energies and forces between dipoles by explicitly summing over all pairs. For the directions in which the system is periodic (as defined by system.periodicity), it applies the minimum image convention, i.e. the interaction is effectively cut off at half a box length.

The direct summation methods are mainly intended for non-periodic systems which cannot be solved using the dipolar P3M method. Due to the long-range nature of dipolar interactions, Direct summation with minimum image convention does not yield good accuracy with periodic systems.

Two methods are available:

To use the methods, create an instance of either espressomd.magnetostatics.DipolarDirectSumCpu or espressomd.magnetostatics.DipolarDirectSumGpu and add it to the system’s list of active actors. The only required parameter is the Prefactor (1):

from espressomd.magnetostatics import DipolarDirectSumGpu
dds = DipolarDirectSumGpu(bjerrum_length=1)


For testing purposes, a variant of the dipolar direct sum is available which adds periodic copies to the system in periodic directions (espressomd.magnetostatics.DipolarDirectSumWithReplica).

As it is very slow, this method is not intended to do simulations, but rather to check the results you get from more efficient methods like P3M.

## 9.3. Barnes-Hut octree sum on gpu¶

This interaction calculates energies and forces between dipoles by summing over the spatial octree cells (aka leaves). Far enough cells are considered as a single dipole with a cumulative vector in the cell center of mass. Parameters which determine that the cell is far enough are $$I_{\mathrm{tol}}^2$$ and $$\varepsilon^2$$ which define a fraction of the cell and an additive distance respectively. For the detailed description of the Barnes-Hut method application to the dipole-dipole interactions, please refer to [PLD+13].

To use the method, create an instance of espressomd.magnetostatics.DipolarBarnesHutGpu and add it to the system’s list of active actors:

from espressomd.magnetostatics import DipolarBarnesHutGpu
bh = DipolarBarnesHutGpu(prefactor=pf_dds_gpu, epssq=200.0, itolsq=8.0)


## 9.4. Scafacos Magnetostatics¶

Espresso can use the methods from the Scafacos Scalable fast Coulomb solvers library for dipoles, if the methods support dipolar calculations. The feature SCAFACOS_DIPOLES has to be added to myconfig.hpp to activate this feature. At the time of this writing (Feb 2018) dipolar calculations are only included in the dipolar branch of the Scafacos code.

To use SCAFACOS, create an instance of espressomd.magnetostatics.Scafacos and add it to the list of active actors. Three parameters have to be specified:

• method_name: name of the SCAFACOS method being used.
• method_params: dictionary containing the method-specific parameters
• bjerrum_length

The method-specific parameters are described in the SCAFACOS manual. Additionally, methods supporting tuning have the parameter tolerance_field which sets the desired root mean square accuracy for the electric field

For details of the various methods and their parameters please refer to the SCAFACOS manual. To use this feature, SCAFACOS has to be built as a shared library. SCAFACOS can be used only once, either for Coulomb or for dipolar interactions.