Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleanup and restructure documentation, fix errors #3567

Merged
merged 12 commits into from
Mar 6, 2020
5 changes: 2 additions & 3 deletions doc/sphinx/advanced_methods.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
112 changes: 72 additions & 40 deletions doc/sphinx/constraints.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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` ::

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

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

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

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

Expand All @@ -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!
Expand All @@ -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.

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

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

Expand All @@ -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],
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down
Loading