Skip to content
Permalink
Browse files

Update Sphinx documentation

Fix broken internal and external links, remove documentation of
recently deleted Python samples, cleanup Sphinx syntax, fix typos.
  • Loading branch information...
jngrad committed Sep 30, 2019
1 parent d25a4c9 commit ea658e1794803a8aba284865baf621661e30010b

Large diffs are not rendered by default.

@@ -10,7 +10,7 @@ Analysis
calculation and data accumulation performed in the core.
- :ref:`Observables and correlators`: This provides a more flexible concept of
in-core analysis, where a certain observable (:ref:`Available observables`),
a rule for data accumulation (ref Accumulators) and/or correlation (:ref:`Correlations`) can be defined.
a rule for data accumulation (:ref:`Accumulators`) and/or correlation (:ref:`Correlations`) can be defined.


.. _Direct analysis routines:
@@ -462,7 +462,7 @@ Errors

Common to all algorithms of the MMM family is that accuracy is cheap
with respect to computation time. More precisely, the maximal pairwise
error, i.e. the maximal error of the :math:`\psi` expression, decreases
error, i.e. the maximal error of the :math:`\psi` expression decreases
exponentially with the cutoffs. In turn, the computation time grows
logarithmically with the accuracy. This is quite in contrast to the
Ewald methods, for which decreasing the error bound can lead to
@@ -481,10 +481,12 @@ additional error source.

.. figure:: figures/elc-errordist.pdf
:alt: Error distribution of the ELC method.
:align: center
:height: 6.00000cm

Error distribution of the ELC method.

Figure [fig:ELC-error] shows the error distribution of the ELC method
The figure shows the error distribution of the ELC method
for a gap size of :math:`10\%` of the total system height. For MMM2D and
MMM1D the error distribution is less homogeneous, however, also here it
is always better to have some extra precision, especially since it is
@@ -150,7 +150,7 @@ Getting the minimal distance to a constraint

Calculates the smallest distance to all interacting
constraints that can be repulsive (wall, cylinder, sphere, rhomboid,
maze, pore, slitpore). Negative distances mean that the position is
pore, slitpore). Negative distances mean that the position is
within the area that particles should not access. Helpful to find
initial configurations.

@@ -455,7 +455,7 @@ Pictured is an example constraint with a ``Hollowcone`` shape created with ::
system.constraints.add(shape=hollowcone, particle_type=0, penetrable=True)


For the shapes ``wall``, ``sphere``, ``cylinder``, ``rhomboid``, ``maze``,
For the shapes ``wall``, ``sphere``, ``cylinder``, ``rhomboid``,
``pore`` and ``stomatocyte``, constraints are able to be penetrated if
``penetrable`` is set to ``True``. Otherwise, when the ``penetrable`` option is
ignored or is set to ``False``, the constraint cannot be violated, i.e. no
@@ -568,17 +568,17 @@ Constant fields
~~~~~~~~~~~~~~~

These are fields that are constant in space or simple linear functions
of the position. The available fields are
of the position. The available fields are:

:class:`espressomd.constraints.HomogeneousMagneticField`
:class:`espressomd.constraints.ElectricPlaneWave`
:class:`espressomd.constraints.LinearElectricPotential`
:class:`espressomd.constraints.HomogeneousFlowField`
:class:`espressomd.constraints.Gravity`
* :class:`espressomd.constraints.HomogeneousMagneticField`
* :class:`espressomd.constraints.ElectricPlaneWave`
* :class:`espressomd.constraints.LinearElectricPotential`
* :class:`espressomd.constraints.HomogeneousFlowField`
* :class:`espressomd.constraints.Gravity`

a detailed description can be found in the class documentation.
A detailed description can be found in the class documentation.

please be aware of the fact that a constant per particle force can be
Please be aware of the fact that a constant per-particle force can be
set via the ``ext_force`` property of the particles and is not provided
here.

@@ -591,8 +591,8 @@ which has to be provided by the user. The fields differ by how
they couple to particles, for a detailed description see their respective
class documentation.

:class:`espressomd.constraints.ForceField`
:class:`espressomd.constraints.PotentialField`
:class:`espressomd.constraints.ElectricPotential`
:class:`espressomd.constraints.FlowField`
* :class:`espressomd.constraints.ForceField`
* :class:`espressomd.constraints.PotentialField`
* :class:`espressomd.constraints.ElectricPotential`
* :class:`espressomd.constraints.FlowField`

@@ -66,7 +66,7 @@ installed on your system. In |es|, you can check if it is compiled in by
checking for the feature ``FFTW`` with ``espressomd.features``.
P3M requires full periodicity (1 1 1). Make sure that you know the relevance of the
P3M parameters before using P3M! If you are not sure, read the following
references
references:
:cite:`ewald21,hockney88,kolafa92,deserno98a,deserno98b,deserno00,deserno00a,cerda08d`.

.. _Tuning Coulomb P3M:
@@ -81,11 +81,12 @@ This can be useful to speed up the tuning during testing or if the parameters
are already known.

To prevent the automatic tuning, set the ``tune`` parameter to ``False``.
To manually tune or retune P3M, call :meth:`espresso.electrostatics.P3M.Tune`.
To manually tune or retune P3M, call :meth:`espressomd.electrostatics.P3M.tune
<espressomd.electrostatics.ElectrostaticInteraction.tune>`.
Note, however, that this is a method the P3M object inherited from
:attr:`espressomd.electrostatics.ElectrostaticInteraction`.
All parameters passed to the method are fixed in the tuning routine. If not
specified in the ``Tune()`` method, the parameters ``prefactor`` and
specified in the ``tune()`` method, the parameters ``prefactor`` and
``accuracy`` are reused.

It is not easy to calculate the various parameters of the P3M method
@@ -127,7 +128,8 @@ It uses the same parameters and interface functionality as the CPU version of
the solver. It should be noted that this does not always provide significant
increase in performance. Furthermore it computes the far field interactions
with only single precision which limits the maximum precision. The algorithm
does not work in combination with the electrostatic extensions :ref:`Dielectric interfaces with the ICC algorithm`
does not work in combination with the electrostatic extensions
:ref:`Dielectric interfaces with the ICC* algorithm <Dielectric interfaces with the ICC algorithm>`
and :ref:`Electrostatic Layer Correction (ELC)`.

.. _Debye-Hückel potential:
@@ -265,7 +267,7 @@ MMM2D

MMM2D is an electrostatics solver for explicit 2D periodic systems.
It can account for different dielectric jumps on both sides of the
non-periodic direction. MMM2D Coulomb method needs periodicity 1 1 0 and the
non-periodic direction. MMM2D Coulomb method needs periodicity (1 1 0) and the
layered cell system. The performance of the method depends on the number of
slices of the cell system, which has to be tuned manually. It is
automatically ensured that the maximal pairwise error is smaller than
@@ -332,7 +334,7 @@ method in computational order N. Currently, it only supports P3M. This means,
that you will first have to set up the P3M algorithm before using ELC. The
algorithm is definitely faster than MMM2D for larger numbers of particles
(:math:`>400` at reasonable accuracy requirements). The periodicity has to be
set to ``1 1 1`` still, *ELC* cancels the electrostatic contribution of the
set to (1 1 1) still, *ELC* cancels the electrostatic contribution of the
periodic replica in **z-direction**. Make sure that you read the papers on ELC
(:cite:`arnold02c,arnold02d,tyagi08a`) before using it. ELC is an |es| actor
and is used with::
@@ -366,15 +368,15 @@ Parameters are:
forces/energies in *ELC* and is therefore only possible with the
``const_pot`` option.
* ``const_pot``:
As described, setting this to ``1`` leads to fully metallic boundaries and
As described, setting this to ``True`` leads to fully metallic boundaries and
behaves just like the mmm2d parameter of the same name: It maintains a
constant potential ``pot_diff`` by countering the total dipole moment of
the system and adding a homogeneous electric field according to
``pot_diff``.
* ``pot_diff``:
Used in conjunction with ``const_pot`` set to 1, this sets the potential difference
between the boundaries in the z-direction between ``z=0`` and
``z = box_l[2] - gap_size``.
Used in conjunction with ``const_pot`` set to ``True``, this sets the
potential difference between the boundaries in the z-direction between
``z=0`` and ``z = box_l[2] - gap_size``.
* ``far_cut``:
The setting of the far cutoff is only intended for testing and allows to
directly set the cutoff. In this case, the maximal pairwise error is
@@ -423,7 +425,7 @@ parameters.
mmm1d = MMM1D(prefactor=C, maxPWerror=err)

where the prefactor :math:`C` is defined in Eqn. :eq:`coulomb_prefactor`.
MMM1D Coulomb method for systems with periodicity 0 0 1. Needs the
MMM1D Coulomb method for systems with periodicity (0 0 1). Needs the
nsquared cell system (see section :ref:`Cellsystems`). The first form sets parameters
manually. The switch radius determines at which xy-distance the force
calculation switches from the near to the far formula. The Bessel cutoff
@@ -150,7 +150,7 @@ A pairwise Coulomb interaction can be instantiated via
This creates a bond with a Coulomb pair potential between particles ``0`` and ``1``.
It is given by

.. math:: V(r) = \frac{\alpha q_1 q_2}{r},
.. math:: V(r) = \alpha \frac{q_1 q_2}{r},

where :math:`q_1` and :math:`q_2` are the charges of the bound particles and :math:`\alpha` is the
Coulomb prefactor. This interaction has no cutoff and acts independently of other
@@ -451,8 +451,11 @@ For details of the interpolation, see :ref:`Tabulated interaction`.
Object-in-fluid interactions
----------------------------

Please cite :cite:`Cimrak2014` when using the interactions in this section in order to
simulate extended objects embedded in a LB fluid. For more details we encourage the dedicated OIF documentation available at http://cell-in-fluid.fri.uniza.sk/en/content/oif-espresso.
Please cite :cite:`Cimrak2014` when using the interactions in this section in
order to simulate extended objects embedded in a LB fluid. For more details
please consult the dedicated OIF documentation available at
`http://cell-in-fluid.fri.uniza.sk/en/content/oif-espresso
<https://web.archive.org/web/20180719231829/http://cell-in-fluid.fri.uniza.sk/en/content/oif-espresso>`_.

The following interactions are implemented in order to mimic the
mechanics of elastic or rigid objects immersed in the LB fluid flow.
@@ -581,7 +581,7 @@ only has an effect if the DPD thermostat is activated.
The interaction consists of a friction force :math:`\vec{F}_{ij}^{D}` and
a random force :math:`\vec{F}_{ij}^R` added to the other interactions
between particles :math:`i` and :math:`j`. It is decomposed into a component
parallel and perpendicular to the distance vector :math:`\vec{r}_{ij}` of the particle pair .
parallel and perpendicular to the distance vector :math:`\vec{r}_{ij}` of the particle pair.
The friction force contributions of the parallel part are

.. math:: \vec{F}_{ij}^{D} = -\gamma_\parallel w_\parallel (r_{ij}) (\hat{r}_{ij} \cdot \vec{v}_{ij}) \hat{r}_{ij}
@@ -312,30 +312,12 @@ or in the `git repository <https://github.com/espressomd/espresso/blob/python/sa
* :file:`billiard.py`
A simple billiard game, needs the Python ``pypopengl`` module

* :file:`bonds-tst.py`
Test script that manually creates and deletes different bonds between particles (see :ref:`Bonded interactions`). This script performs:

* print defined bonded interactions
* print bonds on a particle
* delete bonds by index or name
* save/load a bond to/from a variable

* :file:`cellsystem_test.py`
Test script that changes the skin depth parameter. This should not be seen as a benchmark, but rather as a rough estimate of the effect of the cellsystem.

..
.. todo:: implement the older [tune_cells] call
.. todo:: add save/load optimal cell parameters from tune_skin()
* :file:`chamber_game.py`
Lennard-Jones gas used for demonstration purposes to showcase |es|. The
game is based on the Maxwell's demon thought experiment. The snake is
controlled by a gamepad or the keyboard to move particles between chambers
against a pressure gradient.

* :file:`debye_hueckel.py`
Charged beads with a WCA interaction are simulated using the screened Debye-Hückel potential. See :ref:`Debye-Hückel potential`.

* :file:`ekboundaries.py`

* :file:`electrophoresis.py`
@@ -365,21 +347,15 @@ or in the `git repository <https://github.com/espressomd/espresso/blob/python/sa
Uses :meth:`~espressomd.analyze.Analysis.structure_factor()` to analyze a
simple Lennard-Jones liquid. See :ref:`Structure factor`.

* :file:`load_bonds.py`, :file:`store_bonds.py`
Uses the Python ``pickle`` module to store and load bond information.

* :file:`load_checkpoint.py`, :file:`save_checkpoint.py`
Basing usage of the checkpointing feature. Shows how to write/load the state of:
Basic usage of the checkpointing feature. Shows how to write/load the state of:

* custom user variables
* non bonded interactions
* non-bonded interactions
* particles
* P3M parameters
* thermostat

* :file:`load_properties.py`, :file:`store_properties.py`
Uses the Python ``pickle`` module to store and load system information.

* :file:`MDAnalysisIntegration.py`
Shows how to expose configuration to ``MDAnalysis`` at run time. The
functions of ``MDAnalysis`` can be used to perform some analysis or
@@ -403,7 +379,7 @@ or in the `git repository <https://github.com/espressomd/espresso/blob/python/sa
* :file:`slice_input.py`
Uses python array slicing to set and extract various particle properties.

* :file:`visualization.py`
* :file:`visualization_ljliquid.py`
A visualization for Mayavi/OpenGL of the LJ-liquid with interactive plotting.

* :file:`visualization_bonded.py`
@@ -415,7 +391,7 @@ or in the `git repository <https://github.com/espressomd/espresso/blob/python/sa
* :file:`visualization_npt.py`
Simple test visualization for the NPT ensemble.

* :file:`visualization_poisseuille.py`
* :file:`visualization_poiseuille.py`
Visualization for Poiseuille flow with lattice Boltzmann.

* :file:`visualization_constraints.py`
@@ -125,7 +125,7 @@ details). Currently |es| supports some basic functions for writing simulation
data to H5MD files. The implementation is MPI-parallelized and is capable
of dealing with varying numbers of particles.

To write data in a hdf5-file according to the H5MD proposal (http://nongnu.org/h5md/), first an object of the class
To write data in a hdf5-file according to the H5MD proposal (https://nongnu.org/h5md/), first an object of the class
:class:`espressomd.io.writer.h5md.H5md` has to be created and linked to the
respective hdf5-file. This may, for example, look like:

@@ -178,7 +178,7 @@ call the H5md objects :meth:`espressomd.io.writer.h5md.H5md.write` method withou
After the last write call, you have to call the ``close()`` method to remove
the backup file and to close the datasets etc.

H5MD files can be read and modified with the python module h5py (for documentation see `h5py <http://docs.h5py.org/en/stable/>`_). For example all positions stored in the file called "h5mdfile.h5" can be read using
H5MD files can be read and modified with the python module h5py (for documentation see `h5py <https://docs.h5py.org/en/stable/>`_). For example all positions stored in the file called "h5mdfile.h5" can be read using

.. code:: python
@@ -226,7 +226,7 @@ There exists a legacy python script in the :file:`tools` directory which can con
MPI-IO data to the now unsupported blockfile format. Check it out if you want
to post-process the data without ESPResSo.

*WARNING* Do not attempt to read these binary files on a machine with a different
*WARNING*: Do not attempt to read these binary files on a machine with a different
architecture!

.. _Writing VTF files:
@@ -366,7 +366,7 @@ Note that the |es| particles are ordered in increasing order, thus ``id=3`` corr
Writing various formats using MDAnalysis
----------------------------------------

If the MDAnalysis package (http://mdanalysis.org) is installed, it
If the MDAnalysis package (https://mdanalysis.org) is installed, it
is possible to use it to convert frames to any of the supported
configuration/trajectory formats, including PDB, GROMACS, GROMOS,
CHARMM/NAMD, AMBER, LAMMPS, ...)
@@ -396,7 +396,7 @@ using MDAnalysis. A simple example is the following:
u.load_new(eos.trajectory) # load the frame to the MDA universe
W.write_next_timestep(u.trajectory.ts) # append it to the trajectory
For other examples see samples/python/MDAnalysisIntegration.py
For other examples, see :file:`/samples/MDAnalysisIntegration.py`

.. _Parsing PDB Files:

@@ -148,8 +148,7 @@ one of::
lb.set_interpolation_order('quadratic')
A note on boundaries:

Both interpolation schemes don't take into account the physical location of the boundaries
both interpolation schemes don't take into account the physical location of the boundaries
(e.g. in the middle between two nodes for a planar wall) but will use the boundary node slip velocity
at the node position. This means that every interpolation involving at least one
boundary node will introduce an error.
@@ -392,7 +391,7 @@ Intersecting boundaries are in principle possible but must be treated
with care. In the current implementation, all nodes that are
within at least one boundary are treated as boundary nodes.

Currently, only the so called "link-bounce-back" algorithm for wall
Currently, only the so-called "link-bounce-back" algorithm for wall
nodes is available. This creates a boundary that is located
approximately midway between the lattice nodes, so in the above example ``wall[0]``
corresponds to a boundary at :math:`x=1.5`. Note that the
@@ -75,7 +75,7 @@ It is based on :cite:`brodka04a` and the dipolar version of

Usage notes:

* The non-periodic direction is always the ``z``-direction.
* 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.

@@ -382,9 +382,9 @@ To set up a virtual site,

#. Repeat the previous step with more virtual sites, if desired.

#. To update the positions of all virtual sites, call
#. To update the positions of all virtual sites, call::

system.integrator.run(0,recalc_forces=True)
system.integrator.run(0, recalc_forces=True)

Please note:

@@ -400,8 +400,9 @@ Please note:
guaranteed. Always relate a virtual site to a non-virtual particle
placed in the center of mass of the rigid arrangement of particles.

- In case you know the correct quaternions, you can also setup a
virtual site using its :attr:`espressomd.particle_data.ParticleHandle.vs_relative` and :attr:`espressomd.particle_data.ParticleHandle.virtual` attributes.
- In case you know the correct quaternions, you can also setup a virtual
site using its :attr:`espressomd.particle_data.ParticleHandle.vs_relative`
and :attr:`espressomd.particle_data.ParticleHandle.virtual` attributes.

- In a simulation on more than one CPU, the effective cell size needs
to be larger than the largest distance between a non-virtual particle

0 comments on commit ea658e1

Please sign in to comment.
You can’t perform that action at this time.