Update Sphinx documentation

Fix broken internal and external links, remove documentation of
recently deleted Python samples, cleanup Sphinx syntax, fix typos.

doc/sphinx/analysis.rst

@@ -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:

doc/sphinx/appendix.rst

@@ -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

doc/sphinx/constraints.rst

@@ -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`
 

doc/sphinx/electrostatics.rst

@@ -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

doc/sphinx/inter_bonded.rst

@@ -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.

doc/sphinx/inter_non-bonded.rst

@@ -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}

doc/sphinx/introduction.rst

@@ -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`

doc/sphinx/io.rst

@@ -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:
 

doc/sphinx/lb.rst

@@ -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

doc/sphinx/magnetostatics.rst

@@ -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.
 

doc/sphinx/particles.rst

@@ -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