Skip to content
Permalink
Browse files

Fix Sphinx documentation

Remove obsolete warning on the rhomboid shape. Fix Sphinx syntax:
`word` should be avoided (creates an HTML tag <cite>), replaced
by *word* (italic via <em>), ``word`` (teletype via <span>) or
:func:`word` (link). Fix math formula and function argument types.
  • Loading branch information...
jngrad committed Sep 30, 2019
1 parent bea93fd commit d25a4c9290be03bd72eaa2927075fd31c8074b3f
@@ -21,7 +21,7 @@ The collision detection is controlled via the :attr:`espressomd.system.System.co

Several modes are available for different types of binding.

* ``"bind_centers"``: adds a pair-bond between two particles at their first collision. By making the bonded interaction `stiff` enough, the particles can be held together after the collision. Note that the particles can still slide on each others' surface, as the pair bond is not directional. This mode is set up as follows::
* ``"bind_centers"``: adds a pair-bond between two particles at their first collision. By making the bonded interaction *stiff* enough, the particles can be held together after the collision. Note that the particles can still slide on each others' surface, as the pair bond is not directional. This mode is set up as follows::

import espressomd
from espressomd.interactions import HarmonicBond
@@ -64,13 +64,13 @@ Several modes are available for different types of binding.
* ``part_type_vs`` is the particle type assigned to the virtual sites created on collision. In nearly all cases, no non-bonded interactions should be defined for this particle type.
* ``vs_placement`` controls, where on the line connecting the centers of the colliding particles, the virtual sites are placed. A value of 0 means that the virtual sites are placed at the same position as the colliding particles on which they are based. A value of 0.5 will result in the virtual sites being placed ad the mid-point between the two colliding particles. A value of 1 will result the virtual site associated to the first colliding particle to be placed at the position of the second colliding particle. In most cases, 0.5, is a good choice. Then, the bond connecting the virtual sites should have an equilibrium length of zero.

* ``"glue_to_surface"``: This mode is used to irreversibly attach small particles to the surface of a big particle. It is asymmetric in that several small particles can be bound to a big particle but not vice versa. The small particles can change type after collision to make them `inert`. On collision, a single virtual site is placed and related to the big particle. Then, a bond (``bond_centers``) connects the big and the small particle. A second bond (``bond_vs``) connects the virtual site and the small particle. Further required parameters are:
* ``"glue_to_surface"``: This mode is used to irreversibly attach small particles to the surface of a big particle. It is asymmetric in that several small particles can be bound to a big particle but not vice versa. The small particles can change type after collision to make them *inert*. On collision, a single virtual site is placed and related to the big particle. Then, a bond (``bond_centers``) connects the big and the small particle. A second bond (``bond_vs``) connects the virtual site and the small particle. Further required parameters are:

* ``part_type_to_attach_vs_to``: Type of the particle to which the virtual site is attached, i.e., the `big` particle.
* ``part_type_to_be_glued``: Type of the particle bound to the virtual site (the `small` particle).
* ``part_type_after_glueing``: The type assigned to the particle bound to the virtual site (`small` particle) after the collision.
* ``part_type_to_attach_vs_to``: Type of the particle to which the virtual site is attached, i.e., the *big* particle.
* ``part_type_to_be_glued``: Type of the particle bound to the virtual site (the *small* particle).
* ``part_type_after_glueing``: The type assigned to the particle bound to the virtual site (*small* particle) after the collision.
* ``part_type_vs``: Particle type assigned to the virtual site created during the collision.
* ``distance_glued_particle_to_vs``: Distance of the virtual site to the particle being bound to it (`small` particle).
* ``distance_glued_particle_to_vs``: Distance of the virtual site to the particle being bound to it (*small* particle).

Note: When the type of a particle is changed on collision, this makes the
particle inert with regards to further collision. Should a particle of
@@ -119,7 +119,7 @@ The following limitations currently apply for the collision detection:
* The ``"bind at point of collision"`` approach cannot handle collisions
between virtual sites

..

.. _Lees-Edwards boundary conditions:

Lees-Edwards boundary conditions
@@ -1367,8 +1367,8 @@ least the following options: ``agrid``, ``lb_density``, ``viscosity``, ``frictio
used to modify the behavior of the LB fluid. Note that the command does
not allow the user to set the time step parameter as is the case for the
lattice Boltzmann command, this parameter is instead taken directly from the value set for
:attr:`espressomd.system.System.time_step`. The LB `mass density` is set independently from the
electrokinetic `number densities`, since the LB fluid serves only as a
:attr:`espressomd.system.System.time_step`. The LB *mass density* is set independently from the
electrokinetic *number densities*, since the LB fluid serves only as a
medium through which hydrodynamic interactions are propagated, as will
be explained further in the next paragraph. If no ``lb_density`` is specified, then our
algorithm assumes ``lb_density= 1.0``. The two 'new' parameters are the temperature ``T`` at
@@ -1508,8 +1508,8 @@ visualization software such as ParaView [5]_ and Mayavi2 [6]_.
species.print_vtk_density(path)

These commands are similar to the above. They enable the
export of diffusive species properties, namely: `density` and `flux`, which specify the
number density and flux of species `species`, respectively.
export of diffusive species properties, namely: ``density`` and ``flux``, which specify the
number density and flux of species ``species``, respectively.

.. _Local Quantities:

@@ -1526,7 +1526,7 @@ A single node can be addressed using three integer values
which run from 0 to ``dim_x/agrid``, ``dim_y/agrid``, and ``dim_z/agrid``, respectively. The
velocity, electrostatic potential and the pressure of a LB fluid node can be obtained this way.

The local `density` and `flux` of a species can be obtained in the same fashion:
The local ``density`` and ``flux`` of a species can be obtained in the same fashion:

::

@@ -147,7 +147,7 @@ Two arrays are returned corresponding to the normalized distribution and the bin
~~~~~~~~~~~~~~~~~~
.. todo:: This feature is not implemented
analyze radial\_density\_map
analyze radial_density_map
Returns the radial density of particles around a given axis. Parameters
are:
@@ -231,7 +231,7 @@ index_radial index_axial pos_radial pos_axial binvolume density v_ra
0 1 0.05 0.25 0.0314159 31.831 1.41421 1 0 0 0
============= ============ =========== ========== ========= ======= ======== ======== ======= ========= =======

As one can see the columns `density`, `v_radial` and `v_axial` appear twice.
As one can see the columns **density**, **v_radial** and **v_axial** appear twice.
The order of appearance corresponds to the order of the types in the argument ``types``.
For example if was set to ``types=[0, 1]`` then the first triple is associated to type 0 and
the second triple to type 1.
@@ -288,8 +288,8 @@ Structure factor
Calculate the structure factor for given types.

Returns the spherically averaged structure factor :math:`S(q)` of
particles specified in . :math:`S(q)` is calculated for all possible
wave vectors, :math:`\frac{2\pi}{L} <= q <= \frac{2\pi}{L}` `order`.
particles specified in ``sf_types``. :math:`S(q)` is calculated for all possible
wave vectors :math:`\frac{2\pi}{L} \leq q \leq \frac{2\pi}{L}` up to ``sf_order``.

..
.. _Van-Hove autocorrelation function:
@@ -415,7 +415,7 @@ electrostatic interactions in P3M, the :math:`k`-space contribution is implement
The implementation of the Coulomb P3M pressure is tested against LAMMPS.

Four-body dihedral potentials are not included. Except of
VIRTUAL\_SITES\_RELATIVE constraints all other
``VIRTUAL_SITES_RELATIVE`` constraints all other
constraints of any kind are not currently accounted for in the pressure
calculations. The pressure is no longer correct, e.g., when particles
are confined to a plane.
@@ -713,8 +713,8 @@ all available observables in :mod:`espressomd.observables`.

- :class:`~espressomd.observables.BondDihedrals`: Dihedral angles between bond triples on a polymer chain.

- :class:`~espressomd.observables.CosPersistenceAngles`: Cosine of angles between bonds. The `i`-th value in the result vector corresponds to the cosine of the angle between
bonds that are separated by `i` bonds. This observable might be useful for measuring the persistence length of a polymer.
- :class:`~espressomd.observables.CosPersistenceAngles`: Cosine of angles between bonds. The ``i``-th value in the result vector corresponds to the cosine of the angle between
bonds that are separated by ``i`` bonds. This observable might be useful for measuring the persistence length of a polymer.

- Profile observables sampling the spatial profile of various quantities:

@@ -382,27 +382,25 @@ three-dimensionally periodic systems with spherical summation order for
two-dimensional periodicity. The basic idea is to expand the two
dimensional slab system of height h in the non-periodic z-coordinate to
a system with periodicity in all three dimensions, with a period of
:math:`\lambda_z>h`, which leaves an empty gap of height
:math:`\delta=\lambda_z -
h` above the particles in the simulation box.
:math:`\lambda_z > h`, which leaves an empty gap of height
:math:`\delta = \lambda_z - h` above the particles in the simulation box.

Since the electrostatic potential is only finite if the total system is
charge neutral, the additional image layers (those layers above or below
the original slab system) are charge neutral, too. Now let us consider
the n-th image layer which has an offset of :math:`n\lambda_z` to the
original layer. If :math:`n\lambda_z` is large enough, each particle of
charge :math:`q\_j` at position :math:`(x_j,y_j,z_j+n\lambda_z)` and its
charge :math:`q_j` at position :math:`(x_j,y_j,z_j+n\lambda_z)` and its
replicas in the xy-plane can be viewed as constituting a homogeneous
charged sheet of charge density
:math:`\sigma_j = \frac{q_j}{\lambda_x\lambda_y}`. The potential of such
a charged sheet at distance z is :math:`2\pi \sigma_j
|z|`. Now we consider the contribution from a pair of image layers
located at :math:`\pm n\lambda_z`, n>0 to the energy of a charge q\_i at
a charged sheet at distance :math:`z` is :math:`2\pi \sigma_j |z|`.
Now we consider the contribution from a pair of image layers
located at :math:`\pm n\lambda_z`, n>0 to the energy of a charge :math:`q_i` at
position :math:`(x_i,y_i,z_i)` in the central layer. Since
:math:`|z_j - z_i| <
n\lambda_z`, we have
:math:`|z_j - z_i + n\lambda_z| = n\lambda_z + z_j -
z_i` and :math:`|z_j - z_i - n\lambda_z|= n\lambda_z - z_j + z_i`, and
:math:`|z_j - z_i| < n\lambda_z`, we have
:math:`|z_j - z_i + n\lambda_z| = n\lambda_z + z_j - z_i`
and :math:`|z_j - z_i - n\lambda_z|= n\lambda_z - z_j + z_i`, and
hence the interaction energy from those two image layers with the charge
:math:`q_i` vanishes by charge neutrality:

@@ -239,7 +239,7 @@ rst_prolog = """
"""
# Style ESPResSo
rst_epilog = """
.. |es| replace:: `ESPResSo`
.. |es| replace:: *ESPResSo*
"""
# Re-enable grouping of arguments in numpydoc
# https://github.com/sphinx-doc/sphinx/issues/2227
@@ -269,8 +269,6 @@ Pictured is an example constraint with a ``Cylinder`` shape created with ::
:class:`espressomd.shapes.Rhomboid`
A rhomboid or parallelepiped.

:todo: `This shape is currently broken. Please do not use.`

The resulting surface is a rhomboid, 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:
@@ -544,18 +542,18 @@ define nodes which are part of a boundary, please refer to :ref:`Using shapes
as lattice Boltzmann boundary`.


..
.. _Creating a harmonic trap:
.. _Creating a harmonic trap:

Creating a harmonic trap
------------------------
Creating a harmonic trap
------------------------
:todo: `This feature is not yet implemented.`
.. todo:: This feature is not yet implemented.
Calculates a spring force for all particles, where the equilibrium
position of the spring is at and its force constant is . A more
flexible trap can be constructed with constraints, but this one runs on
the GPU.
Calculates a spring force for all particles, where the equilibrium
position of the spring is at and its force constant is . A more
flexible trap can be constructed with constraints, but this one runs on
the GPU.
.. _External Fields:

@@ -674,7 +674,7 @@ targets are available:
subdirectory.
``sphinx``
Creates the `sphinx` code documentation in the :file:`doc/sphinx`
Creates the ``sphinx`` code documentation in the :file:`doc/sphinx`
subdirectory.
``tutorials``
@@ -147,7 +147,7 @@ A pairwise Coulomb interaction can be instantiated via
system.bonded_inter.add(bonded_coulomb)
system.part[0].add_bond((bonded_coulomb, 1))

This creates a bond with a Coulomb pair potential between particles `0` and `1`.
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},
@@ -686,7 +686,7 @@ setting up the Drude particles, so the simple call::

given the :class:`espressomd.System() <espressomd.system.System>` object, uses this information to create all
necessary Thole interactions. The method calculates the mixed scaling
coefficient `s` and creates the non-bonded Thole interactions between the
coefficient ``s`` and creates the non-bonded Thole interactions between the
collected types to cover all the Drude-Drude, Drude-core and core-core
combinations. No further calls of :meth:`~espressomd.drude_helpers.add_drude_particle_to_core` should
follow. Set ``verbose`` to ``True`` to print out the coefficients, charge factors
@@ -259,7 +259,7 @@ and then adding it to the system: ::
.. rubric:: Integration

So far we just *added* particles and interactions, but did not propagate the
system. This is done by the `integrator`. It uses by default the velocity
system. This is done by the *integrator*. It uses by default the velocity
Verlet algorithm and is already created by the system class. To perform an
integration step, just execute::

@@ -47,9 +47,9 @@ Checkpointing is implemented by the :class:`espressomd.checkpointing.Checkpoint`
from espressomd import checkpointing
checkpoint = checkpointing.Checkpoint(checkpoint_id="mycheckpoint", checkpoint_path=".")

Here, `checkpoint_id` denotes the identifier for a checkpoint. Legal characters for an id
Here, ``checkpoint_id`` denotes the identifier for a checkpoint. Legal characters for an id
are "0-9", "a-zA-Z", "-", "_".
The parameter `checkpoint_path`, specifies the relative or absolute path where the checkpoints are
The parameter ``checkpoint_path``, specifies the relative or absolute path where the checkpoints are
stored. The current working directory is assumed, when this parameter is skipped.

After the simulation system and user variables are set up, they can be
@@ -66,7 +66,7 @@ To give an example::
checkpoint.register("my_var")
# ...

will register the user variable `my_var` and the instance of the simulation system. The checkpoint can be saved via::
will register the user variable ``my_var`` and the instance of the simulation system. The checkpoint can be saved via::


checkpoint.save()
@@ -96,11 +96,11 @@ The checkpointing instance itself will also be restored. I.e., the same variable

Be aware of the following limitations:

* Checkpointing makes use of the `pickle` python package. Objects will only be restored as far as they support pickling. This is the case for Python's basic data types, `numpy` arrays and many other objects. Still, pickling support cannot be taken for granted.
* Checkpointing makes use of the ``pickle`` python package. Objects will only be restored as far as they support pickling. This is the case for Python's basic data types, ``numpy`` arrays and many other objects. Still, pickling support cannot be taken for granted.

* Pickling support of the Espresso system instance and contained objects such as bonded and non-bonded interactions and electrostatics methods. However, there are many more combinations of active interactions and algorithms then can be tested.

* The active actors, i.e., the content of `system.actors`, are checkpointed. For lattice Boltzmann fluids, this only includes the parameters such as the lattice constant (`agrid`). The actual flow field has to be saved separately with the lattice-Boltzmann specific methods
* The active actors, i.e., the content of ``system.actors``, are checkpointed. For lattice Boltzmann fluids, this only includes the parameters such as the lattice constant (``agrid``). The actual flow field has to be saved separately with the lattice-Boltzmann specific methods
:meth:`espressomd.lb.HydrodynamicInteraction.save_checkpoint`
and loaded via :meth:`espressomd.lb.HydrodynamicInteraction.load_checkpoint` after restoring the checkpoint

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

0 comments on commit d25a4c9

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