Skip to content

Commit

Permalink
docs: Update electrostatic/magnetostatics docs
Browse files Browse the repository at this point in the history
Provide working code samples, add missing list of P3M papers,
cleanup outdated documentation.
  • Loading branch information
jngrad committed Aug 19, 2020
1 parent 001c3c7 commit 4d1ad9a
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 11 deletions.
18 changes: 10 additions & 8 deletions doc/sphinx/electrostatics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -35,20 +35,22 @@ Note that using the electrostatic interaction also requires assigning charges to
the particles via the particle property
:py:attr:`espressomd.particle_data.ParticleHandle.q`.

This example shows the general usage of an electrostatic method ``<SOLVER>``.
All of them need the Bjerrum length and a set of other required parameters.
First, an instance of the solver is created and only after adding it to the actors
list, it is activated. Internally the method calls a tuning routine on
activation to achieve the given accuracy::
All solvers need a prefactor and a set of other required parameters.
This example shows the general usage of the electrostatic method ``P3M``.
An instance of the solver is created and added to the actors list, at which
point it will be automatically activated. This activation will internally
call a tuning function to achieve the requested accuracy::

import espressomd
from espressomd import electrostatics
import espressomd.electrostatics

system = espressomd.System(box_l=[10, 10, 10])
solver = electrostatics.<SOLVER>(prefactor=C, <ADDITIONAL REQUIRED PARAMETERS>)
system.time_step = 0.01
system.part.add(pos=[[0, 0, 0], [1, 1, 1]], q=[-1, 1])
solver = espressomd.electrostatics.P3M(prefactor=2, accuracy=1e-3)
system.actors.add(solver)

where the prefactor :math:`C` is defined as in Eqn. :eq:`coulomb_prefactor`
where the prefactor is defined as :math:`C` in Eqn. :eq:`coulomb_prefactor`.

.. _Coulomb P3M:

Expand Down
13 changes: 10 additions & 3 deletions doc/sphinx/magnetostatics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,15 @@ relative permittivity of the background material, respectively.

Magnetostatic interactions are activated via the actor framework::

from espressomd.magnetostatics import DipolarDirectSumCpu
import espressomd
import espressomd.magnetostatics

direct_sum = DipolarDirectSumCpu(prefactor=1)
system = espressomd.System(box_l=[10, 10, 10])
system.time_step = 0.01
system.part.add(pos=[[0, 0, 0], [1, 1, 1]],
rotation=2 * [(1, 1, 1)], dip=2 * [(1, 0, 0)])

direct_sum = espressomd.magnetostatics.DipolarDirectSumCpu(prefactor=1)
system.actors.add(direct_sum)
# ...
system.actors.remove(direct_sum)
Expand All @@ -49,7 +55,8 @@ Dipolar P3M
This is the dipolar version of the P3M algorithm, described in :cite:`cerda08d`.

Make sure that you know the relevance of the P3M parameters before using
P3M! If you are not sure, read the following references
P3M! If you are not sure, read the following references:
:cite:`ewald21,hockney88,kolafa92,deserno98a,deserno98b,deserno00,deserno00a,cerda08d`.

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

Expand Down

0 comments on commit 4d1ad9a

Please sign in to comment.