Cleanup and restructure documentation, fix errors (#3567)

Description of changes:
- normalize filenames in tutorial 06 (fixes #3487)
- fix errors in documentation of shape parameters (fixes #3566)
- fix broken Sphinx syntax
   - broken links to C++ methods declared in the `Methods` section of numpydoc docstrings
   - broken definition list in shapes documentation
   - incorrect reStructureText syntax
- restructure section titles in installation instructions and shapes
- improve documentation of external features, such as H5MD (see today's mailing list email "H5md not available"), and remove documentation of removed features, e.g. `OIF_GLOBAL_FORCES`

doc/sphinx/advanced_methods.rst

@@ -265,10 +265,9 @@ Description of sample script
 .. note::
 
     The following features are required:
-    ``LB``, ``LB_BOUNDARIES``,
+    ``LB_BOUNDARIES``,
     ``EXTERNAL_FORCES``,
-    ``MASS``, ``OIF_LOCAL_FORCES``,
-    ``OIF_GLOBAL_FORCES``, ``SOFT_SPHERE``
+    ``MASS``, ``SOFT_SPHERE``
 
 The script described in this section is available in :file:`samples/object-in-fluid/motivation.py` and also at
 `http://cell-in-fluid.fri.uniza.sk/en/content/oif-espresso

doc/sphinx/constraints.rst

@@ -57,7 +57,7 @@ Available shapes are listed below.
 .. _Adding shape-based constraints to the system:
 
 Adding shape-based constraints to the system
---------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Usually you want to use constraints based on a shape.
 The module :mod:`espressomd.constraints` provides the class
@@ -101,7 +101,7 @@ as usual (:ref:`Non-bonded interactions`).
 .. _Deleting a constraint:
 
 Deleting a constraint
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 Constraints can be removed in a similar fashion using :meth:`espressomd.constraints.Constraints.remove` ::
 
@@ -113,7 +113,7 @@ This command will delete the specified constraint.
 .. _Getting the currently defined constraints:
 
 Getting the currently defined constraints
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 One can iterate through constraints, for example ::
 
@@ -126,7 +126,7 @@ will print the shape information for all defined constraints.
 .. _Getting the force on a constraint:
 
 Getting the force on a constraint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :meth:`espressomd.constraints.ShapeBasedConstraint.total_force`
 
@@ -145,7 +145,7 @@ For example the pressure from wall ::
 .. _Getting the minimal distance to a constraint:
 
 Getting the minimal distance to a constraint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :meth:`espressomd.constraints.ShapeBasedConstraint.min_dist`
 
@@ -155,10 +155,10 @@ pore, slitpore). Negative distances mean that the position is
 within the area that particles should not access. Helpful to find
 initial configurations.
 
-.. _Available Shapes:
+.. _Available shapes:
 
-Available Shapes
-~~~~~~~~~~~~~~~~
+Available shapes
+^^^^^^^^^^^^^^^^
 
 :class:`espressomd.shapes`
 
@@ -179,12 +179,14 @@ The following shapes can be used as constraints.
    symplectic integrators. Often, the total energy of the system increases exponentially.
 
 
+Wall
+""""
+
 :class:`espressomd.shapes.Wall`
-    An infinite plane.
 
-The resulting surface is a plane defined by the normal vector ``normal``
+An infinite plane defined by the normal vector ``normal``
 and the distance ``dist`` from the origin (in the direction of the normal vector).
-The force acts in direction of the normal.
+The force acts in the direction of the normal.
 Note that ``dist`` describes the distance from the origin in units of the normal
 vector so that the product of ``dist`` and ``normal`` is a point on the surface.
 Therefore negative distances are quite common!
@@ -204,10 +206,12 @@ are only calculated if the particle is on the side of the wall in which the
 normal vector is pointing.
 
 
+Sphere
+""""""
+
 :class:`espressomd.shapes.Sphere`
-    A sphere.
 
-The resulting surface is a sphere with center ``center`` and radius ``radius``.
+A sphere with center ``center`` and radius ``radius``.
 The direction ``direction`` determines the force direction, ``-1`` for inward
 and ``+1`` for outward.
 
@@ -224,11 +228,15 @@ Pictured is an example constraint with a ``Sphere`` shape created with ::
     system.constraints.add(shape=sphere, particle_type=0)
 
 
+Ellipsoid
+"""""""""
+
 :class:`espressomd.shapes.Ellipsoid`
-    An ellipsoid.
 
-The resulting surface is an ellipsoid of revolution with center ``center``, semiaxis ``a`` along the symmetry axis and equatorial semiaxes ``b``. The symmetry axis is aligned parallel to the x-axis.
-The direction ``direction`` determines the force direction, ``-1`` for inward and ``+1`` for outward. The distance to the surface is determined iteratively via Newton's method.
+An ellipsoid with center ``center``, semiaxis ``a`` along the symmetry axis and
+equatorial semiaxes ``b``. The symmetry axis is aligned parallel to the x-axis.
+The direction ``direction`` determines the force direction, ``-1`` for inward and ``+1`` for outward.
+The distance to the surface is determined iteratively via Newton's method.
 
 .. _shape-ellipsoid:
 
@@ -243,11 +251,12 @@ Pictured is an example constraint with an ``Ellipsoid`` shape created with ::
     system.constraints.add(shape=ellipsoid, particle_type=0)
 
 
+Cylinder
+""""""""
+
 :class:`espressomd.shapes.Cylinder`
-    A cylinder
 
-The resulting surface is a cylinder with center ``center`` and radius ``radius``.
-The ``length`` parameter is **half** of the cylinder length.
+A cylinder with center ``center``, radius ``radius`` and length ``length``.
 The ``axis`` parameter is a vector along the cylinder axis, which is normalized in the program.
 The direction ``direction`` determines the force direction, ``-1`` for inward and ``+1`` for outward.
 
@@ -267,18 +276,20 @@ Pictured is an example constraint with a ``Cylinder`` shape created with ::
                         length=30)
     system.constraints.add(shape=cylinder, particle_type=0)
 
+
+Rhomboid
+""""""""
+
 :class:`espressomd.shapes.Rhomboid`
-    A rhomboid or parallelepiped.
 
-The resulting surface is a rhomboid, defined by one corner located at ``corner``
+A rhomboid or parallelepiped, defined by one corner located at ``corner``
 and three adjacent edges, defined by the three vectors connecting the
-corner ``corner`` with its three neighboring corners:
-``a`` ``[ax ay az ]``; ``b`` ``[bx by bz]`` and ``c`` ``[cx cy cz]``.
+corner ``corner`` with its three neighboring corners: ``a``, ``b`` and ``c``.
 The direction ``direction`` determines the force direction, ``-1`` for inward and ``+1`` for outward.
 
 ::
 
-    rhomboid = Rhomboid(pos=[5.0, 5.0, 5.0],
+    rhomboid = Rhomboid(corner=[5.0, 5.0, 5.0],
                         a=[1.0, 1.0, 0.0],
                         b=[0.0, 0.0, 1.0],
                         c=[0.0, 1.0, 0.0],
@@ -288,13 +299,21 @@ The direction ``direction`` determines the force direction, ``-1`` for inward an
 creates a rhomboid defined by one corner located at ``[5.0, 5.0, 5.0]`` and three
 adjacent edges, defined by the three vectors connecting the corner with its three neighboring corners, ``(1,1,0)`` , ``(0,0,1)`` and ``(0,1,0)``.
 
+
+SimplePore
+""""""""""
+
 :class:`espressomd.shapes.SimplePore`
-    Two parallel infinite planes, connected by a cylindrical orifice. The cylinder is connected to the
-    planes by torus segments with an adjustable radius.
 
+Two parallel infinite planes, connected by a cylindrical orifice. The cylinder
+is connected to the planes by torus segments with an adjustable radius.
 
-Length and radius of the cylindrical pore can be set via the corresponding parameters (``length`` and ``radius``). The parameter ``center`` defines the central point of the pore. The orientation of the pore is given by the vector ``axis``, which points along the cylinder's symmetry axis.
+Length and radius of the cylindrical pore can be set via the corresponding parameters
+(``length`` and ``radius``). The parameter ``center`` defines the central point of the pore.
+The orientation of the pore is given by the vector ``axis``, which points along the cylinder's symmetry axis.
 The pore openings are smoothed with torus segments, the radius of which can be set using the parameter ``smoothing_radius``.
+In the OpenGL visualizer, these torus segments are rendered as a half-torus instead of a quarter-torus.
+You can safely ignore this visual artifact, in the force/energy calculation, only a quarter-torus is used.
 
 
 .. figure:: figures/shape-simplepore.png
@@ -312,18 +331,20 @@ Pictured is an example constraint with a ``SimplePore`` shape created with ::
     system.constraints.add(shape=pore, particle_type=0, penetrable=True)
 
 
+Stomatocyte
+"""""""""""
+
 :class:`espressomd.shapes.Stomatocyte`
-    A stomatocyte.
 
-The resulting surface is a stomatocyte shaped boundary.
+A stomatocyte-shaped boundary surface.
 This command should be used with care.
 The position can be any point in the simulation box and is set via the (3,) array_like parameter ``center``.
 The orientation of the (cylindrically symmetric) stomatocyte is given by an ``axis`` (a (3,) array_like of :obj:`float`),
 which points in the direction of the symmetry axis and does not need to be normalized.
 The parameters: ``outer_radius``, ``inner_radius``, and ``layer_width``, specify the shape of the stomatocyte.
 Here inappropriate choices of these parameters can yield undesired results.
 The width ``layer_width`` is used as a scaling parameter.
-That is, a stomatocyte given by ``outer_radius``:``inner_radius``:``layer_width`` = 7:3:1
+That is, a stomatocyte given by ``outer_radius:inner_radius:layer_width`` = 7:3:1
 is half the size of the stomatocyte given by 7:3:2.
 Not all choices of the parameters give reasonable values for the shape of the stomatocyte,
 but the combination 7:3:1 is a good point to start from when trying to modify the shape.
@@ -351,11 +372,12 @@ Pictured is an example constraint with a ``Stomatocyte`` shape (with a closeup o
     system.constraints.add(shape=stomatocyte, particle_type=0, penetrable=True)
 
 
+Slitpore
+""""""""
 
 :class:`espressomd.shapes.Slitpore`
-   Channel-like surface
 
-The resulting surface is T-shape channel that extends in the z-direction.
+A T-shaped channel that extends in the *z*-direction.
 The cross sectional geometry is depicted in Fig. :ref:`schematic <figure-slitpore>`.
 It is translationally invariant in y direction.
 
@@ -398,12 +420,14 @@ Pictured is an example constraint with a ``Slitpore`` shape created with ::
     system.constraints.add(shape=slitpore, particle_type=0, penetrable=True)
 
 
+SpheroCylinder
+""""""""""""""
+
 :class:`espressomd.shapes.SpheroCylinder`
-    A capsule, pill, or spherocylinder.
 
-The resulting surface is a cylinder capped by hemispheres on both ends.
+A cylinder capped by hemispheres on both ends. Generates a capsule, pill, or spherocylinder depending on the choice of parameters.
 Similar to :class:`espressomd.shapes.Cylinder`, it is positioned at ``center`` and has a radius ``radius``.
-The ``length`` parameter is **half** of the cylinder length, and does not include the contribution from the hemispherical ends.
+The ``length`` parameter is the cylinder length, and does not include the contribution from the hemispherical ends.
 The ``axis`` parameter is a vector along the cylinder axis, which is normalized in the program.
 The direction ``direction`` determines the force direction, ``-1`` for inward and ``+1`` for outward.
 
@@ -423,9 +447,13 @@ Pictured is an example constraint with a ``SpheroCylinder`` shape created with :
     system.constraints.add(shape=spherocylinder, particle_type=0)
 
 
+HollowConicalFrustum
+""""""""""""""""""""
+
 :class:`espressomd.shapes.HollowConicalFrustum`
-    The conical frustum shape is a hollow cone with round corners. The specific parameters
-    are described in the shapes class :class:`espressomd.shapes.HollowConicalFrustum`.
+
+A hollow cone with round corners. The specific parameters
+are described in the shape's class :class:`espressomd.shapes.HollowConicalFrustum`.
 
 .. figure:: figures/shape-conical_frustum.png
    :alt: Conical frustum shape schematic.
@@ -438,7 +466,11 @@ Pictured is an example constraint with a ``SpheroCylinder`` shape created with :
    :height: 6.00000cm
 
 
+Union
+"""""
+
 :class:`espressomd.shapes.Union`
+
 A meta-shape which is the union of given shapes. Note that only the regions where
 all shapes have a "positive distance" (see :ref:`Available options`) can be used for the
 union. The distance to the union is defined as the minimum distance to any contained shape.
@@ -452,7 +484,7 @@ particle can go through the constraint surface (|es| will exit if it does).
 .. _Available options:
 
 Available options
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 There are some options to help control the behaviour of shaped-based
 constraints. Some of the options, like ``direction`` need to be specified for
@@ -538,7 +570,7 @@ There is a variety of external fields, which differ by how their
 values are obtained and how they couple to particles.
 
 Constant fields
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 These are fields that are constant in space or simple linear functions
 of the position.  The available fields are:
@@ -557,7 +589,7 @@ here.
 
 
 Interpolated Force and Potential fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The values of these fields are obtained by interpolating table data,
 which has to be provided by the user. The fields differ by how