From 83f09d126ae5c3b530c2f2f7d53768f895e453c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 11:49:20 +0100 Subject: [PATCH 01/12] Remove mention of inexistent OIF features These features were removed in #3385. --- doc/sphinx/advanced_methods.rst | 5 ++--- doc/sphinx/installation.rst | 4 ---- doc/sphinx/inter_bonded.rst | 10 ---------- 3 files changed, 2 insertions(+), 17 deletions(-) diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index a2bc9b18f7e..38ad2c3feef 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/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 diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst index 10d62079881..2510ab0fafc 100644 --- a/doc/sphinx/installation.rst +++ b/doc/sphinx/installation.rst @@ -488,10 +488,6 @@ Fluid dynamics and fluid structure interaction - ``EK_DOUBLE_PREC`` -- ``OIF_LOCAL_FORCES`` - -- ``OIF_GLOBAL_FORCES`` - .. _Interaction features: diff --git a/doc/sphinx/inter_bonded.rst b/doc/sphinx/inter_bonded.rst index 0ad322c561f..431b0eea5d0 100644 --- a/doc/sphinx/inter_bonded.rst +++ b/doc/sphinx/inter_bonded.rst @@ -466,11 +466,6 @@ modeling objects are described in section :ref:`Object-in-fluid`. OIF local forces ~~~~~~~~~~~~~~~~ -.. note:: - - Requires ``OIF_GLOBAL_FORCES`` feature. - - OIF local forces are available through the :class:`espressomd.interactions.OifLocalForces` class. This type of interaction is available for closed 3D immersed objects flowing in the LB flow. @@ -598,11 +593,6 @@ larger than :math:`\pi`, then the inner angle is concave. OIF global forces ~~~~~~~~~~~~~~~~~ -.. note:: - - Requires ``OIF_GLOBAL_FORCES`` feature. - - OIF global forces are available through the :class:`espressomd.interactions.OifGlobalForces` class. From 33a278ea4d1f97869d362e15b0d15d8d365ffb7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 11:53:32 +0100 Subject: [PATCH 02/12] Fix cylinder shapes documentation error The length parameter is the full cylinder length since 6a1ff855858. --- doc/sphinx/constraints.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/sphinx/constraints.rst b/doc/sphinx/constraints.rst index a7f8a22f7e4..f441b24bec6 100644 --- a/doc/sphinx/constraints.rst +++ b/doc/sphinx/constraints.rst @@ -246,8 +246,8 @@ Pictured is an example constraint with an ``Ellipsoid`` shape created with :: :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. +The resulting surface is 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. @@ -403,7 +403,7 @@ Pictured is an example constraint with a ``Slitpore`` shape created with :: The resulting surface is a cylinder capped by hemispheres on both ends. 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. From 13751f26de8cd54729a84e329ff76e22aa46bd38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 13:58:39 +0100 Subject: [PATCH 03/12] Document OpenGL visual artifact for SimplePore --- doc/sphinx/constraints.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/sphinx/constraints.rst b/doc/sphinx/constraints.rst index f441b24bec6..57dc5668cfa 100644 --- a/doc/sphinx/constraints.rst +++ b/doc/sphinx/constraints.rst @@ -295,6 +295,8 @@ adjacent edges, defined by the three vectors connecting the corner with its thre 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 From dfd99560f3656206c0e57666dd9a3ce895f7a2eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 14:07:43 +0100 Subject: [PATCH 04/12] Fix broken Sphinx syntax The colon symbol after each method name prevents the creation of internal links to these methods. --- src/python/espressomd/cluster_analysis.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/python/espressomd/cluster_analysis.py b/src/python/espressomd/cluster_analysis.py index cb0633e362b..7a36ad71398 100644 --- a/src/python/espressomd/cluster_analysis.py +++ b/src/python/espressomd/cluster_analysis.py @@ -25,22 +25,22 @@ class Cluster(ScriptInterfaceHelper): Methods ------- - particle_ids(): + particle_ids() Returns list of particle ids in the cluster - particles(): + particles() Returns an instance of ParticleSlice containing the particles in the cluster - size(): + size() Returns the number of particles in the cluster - center_of_mass(): + center_of_mass() center of mass of the cluster - longest_distance(): + longest_distance() Longest distance between any combination of two particles in the cluster - fractal_dimension(dr=None): + fractal_dimension(dr=None) estimates the cluster's fractal dimension by fitting the number of particles :math:`n` in spheres of growing radius around the center of mass to :math:`c*r_g^d`, where :math:`r_g` is the radius of gyration of the From bc6a7f2e2c4bc296b8b6481e07976bc609ff32c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 14:27:45 +0100 Subject: [PATCH 05/12] Document external features External features cannot be added to the myconfig file and need to be activated using CMake flags. --- doc/sphinx/installation.rst | 27 ++++++++++++++++++----- doc/sphinx/io.rst | 4 ++++ src/python/espressomd/cluster_analysis.py | 4 ++++ 3 files changed, 30 insertions(+), 5 deletions(-) diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst index 2510ab0fafc..338b3d07214 100644 --- a/doc/sphinx/installation.rst +++ b/doc/sphinx/installation.rst @@ -445,10 +445,6 @@ General features - ``COLLISION_DETECTION`` Allows particles to be bound on collision. -- ``H5MD`` Allows to write data to H5MD formatted hdf5 files. - - .. seealso:: :ref:`Writing H5MD-files` - In addition, there are switches that enable additional features in the integrator or thermostat: @@ -566,6 +562,27 @@ Some of the above features are marked as EXPERIMENTAL. Activating these features +External features +^^^^^^^^^^^^^^^^^ + +External features cannot be added to the :file:`myconfig.hpp` file by the user. +They are added by CMake if the corresponding dependency was found on the +system. Some of these external features are optional and must be activated +using a CMake flag (see :ref:`Options and Variables`). + +- ``CUDA`` Enables GPU-specific features. + +- ``FFTW`` Enables features relying on the fast Fourier transforms, e.g. P3M. + +- ``H5MD`` Write data to H5MD-formatted hdf5 files (see :ref:`Writing H5MD-files`) + +- ``SCAFACOS`` Enables features relying on the ScaFaCoS library (see + :ref:`ScaFaCoS electrostatics`, :ref:`ScaFaCoS magnetostatics`). + +- ``GSL`` Enables features relying on the GNU Scientific Library, e.g. + :meth:`espressomd.cluster_analysis.Cluster.fractal_dimension`. + + .. _cmake: cmake @@ -644,7 +661,7 @@ options are available: * ``WITH_TESTS``: Enable tests -* ``WITH_SCAFACOS``: Build with Scafacos support +* ``WITH_SCAFACOS``: Build with ScaFaCoS support * ``WITH_VALGRIND_INSTRUMENTATION``: Build with valgrind instrumentation markers diff --git a/doc/sphinx/io.rst b/doc/sphinx/io.rst index dbc865bcad8..d6e9aaced9c 100644 --- a/doc/sphinx/io.rst +++ b/doc/sphinx/io.rst @@ -119,6 +119,10 @@ For additional methods of the checkpointing class, see :class:`espressomd.checkp Writing H5MD-files ------------------ +.. note:: + + Requires ``H5MD`` external feature, enabled with ``-DWITH_HDF5=ON``. + For large amounts of data it's a good idea to store it in the hdf5 (H5MD is based on hdf5) file format (see https://www.hdfgroup.org/ for details). Currently |es| supports some basic functions for writing simulation diff --git a/src/python/espressomd/cluster_analysis.py b/src/python/espressomd/cluster_analysis.py index 7a36ad71398..c86a50915ce 100644 --- a/src/python/espressomd/cluster_analysis.py +++ b/src/python/espressomd/cluster_analysis.py @@ -46,6 +46,10 @@ class Cluster(ScriptInterfaceHelper): to :math:`c*r_g^d`, where :math:`r_g` is the radius of gyration of the particles within the sphere, and :math:`d` is the fractal dimension. + .. note:: + + Requires ``GSL`` external feature, enabled with ``-DWITH_GSL=ON``. + Parameters ---------- dr: From 040819f5ac2e8968c5a45ee4f60506156c037f5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 14:51:30 +0100 Subject: [PATCH 06/12] Re-organize installation instructions --- doc/sphinx/installation.rst | 179 +++++++++++++++++++----------------- 1 file changed, 93 insertions(+), 86 deletions(-) diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst index 338b3d07214..6cd01a1d9a9 100644 --- a/doc/sphinx/installation.rst +++ b/doc/sphinx/installation.rst @@ -286,80 +286,6 @@ invocation is implementation dependent, but in many cases, such as where ```` is the number of processors to be used. -.. _Configuring: - -Configuring ------------ - -.. _myconfig.hpp\: Activating and deactivating features: - -:file:`myconfig.hpp`: Activating and deactivating features -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -|es| has a large number of features that can be compiled into the binary. -However, it is not recommended to actually compile in all possible -features, as this will slow down |es| significantly. Instead, compile in only -the features that are actually required. A strong gain in speed can be -achieved by disabling all non-bonded interactions except for a single -one, e.g. ``LENNARD_JONES``. For developers, it is also possible to turn on or off a -number of debugging messages. The features and debug messages can be -controlled via a configuration header file that contains C-preprocessor -declarations. Subsection :ref:`Features` describes all available features. If a -file named :file:`myconfig.hpp` is present in the build directory when ``cmake`` -is run, all features defined in it will be compiled in. If no such file exists, -the configuration file :file:`src/config/myconfig-default.hpp` will be used -instead, which turns on the default features. - -When you distinguish between the build and the source directory, the -configuration header can be put in either of these. Note, however, that -when a configuration header is found in both directories, the one in the -build directory will be used. - -By default, the configuration header is called :file:`myconfig.hpp`. -The configuration header can be used to compile different binary -versions of with a different set of features from the same source -directory. Suppose that you have a source directory :file:`$srcdir` and two -build directories :file:`$builddir1` and :file:`$builddir2` that contain -different configuration headers: - -* :file:`$builddir1/myconfig.hpp`: - - .. code-block:: c++ - - #define ELECTROSTATICS - #define LENNARD_JONES - -* :file:`$builddir2/myconfig.hpp`: - - .. code-block:: c++ - - #define LJCOS - -Then you can simply compile two different versions of |es| via: - -.. code-block:: bash - - cd builddir1 - cmake .. - make - - cd builddir2 - cmake .. - make - -To see what features were activated in :file:`myconfig.hpp`, run: - -.. code-block:: bash - - ./pypresso - -and then in the Python interpreter: - -.. code-block:: python - - import espressomd - print(espressomd.features()) - .. _Features: Features @@ -377,6 +303,7 @@ activate ``FEATURE``, add the following line to the header file: #define FEATURE + .. _General features: General features @@ -407,7 +334,7 @@ General features .. seealso:: :ref:`Setting up particles` .. note:: - Note, that when the feature is activated, every particle has three + When this feature is activated, every particle has three additional degrees of freedom, which for example means that the kinetic energy changes at constant temperature is twice as large. @@ -459,8 +386,8 @@ integrator or thermostat: - ``PARTICLE_ANISOTROPY`` -.. _Fluid dynamics and fluid structure interaction: +.. _Fluid dynamics and fluid structure interaction: Fluid dynamics and fluid structure interaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -555,11 +482,10 @@ Finally, there is a flag for debugging: detected during compilation. - Features marked as experimental ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some of the above features are marked as EXPERIMENTAL. Activating these features can have unexpected side effects and some of them have known issues. If you activate any of these features, you should understand the corresponding source code and do extensive testing. Furthermore, it is necessary to define ``EXPERIMENTAL_FEATURES`` in :file:`myconfig.hpp`. +Some of the above features are marked as EXPERIMENTAL. Activating these features can have unexpected side effects and some of them have known issues. If you activate any of these features, you should understand the corresponding source code and do extensive testing. Furthermore, it is necessary to define ``EXPERIMENTAL_FEATURES`` in :file:`myconfig.hpp`. External features @@ -583,10 +509,86 @@ using a CMake flag (see :ref:`Options and Variables`). :meth:`espressomd.cluster_analysis.Cluster.fractal_dimension`. + +.. _Configuring: + +Configuring +----------- + +.. _myconfig.hpp\: Activating and deactivating features: + +:file:`myconfig.hpp`: Activating and deactivating features +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +|es| has a large number of features that can be compiled into the binary. +However, it is not recommended to actually compile in all possible +features, as this will slow down |es| significantly. Instead, compile in only +the features that are actually required. A strong gain in speed can be +achieved by disabling all non-bonded interactions except for a single +one, e.g. ``LENNARD_JONES``. For developers, it is also possible to turn on or off a +number of debugging messages. The features and debug messages can be +controlled via a configuration header file that contains C-preprocessor +declarations. Subsection :ref:`Features` describes all available features. If a +file named :file:`myconfig.hpp` is present in the build directory when ``cmake`` +is run, all features defined in it will be compiled in. If no such file exists, +the configuration file :file:`src/config/myconfig-default.hpp` will be used +instead, which turns on the default features. + +When you distinguish between the build and the source directory, the +configuration header can be put in either of these. Note, however, that +when a configuration header is found in both directories, the one in the +build directory will be used. + +By default, the configuration header is called :file:`myconfig.hpp`. +The configuration header can be used to compile different binary +versions of with a different set of features from the same source +directory. Suppose that you have a source directory :file:`$srcdir` and two +build directories :file:`$builddir1` and :file:`$builddir2` that contain +different configuration headers: + +* :file:`$builddir1/myconfig.hpp`: + + .. code-block:: c++ + + #define ELECTROSTATICS + #define LENNARD_JONES + +* :file:`$builddir2/myconfig.hpp`: + + .. code-block:: c++ + + #define LJCOS + +Then you can simply compile two different versions of |es| via: + +.. code-block:: bash + + cd builddir1 + cmake .. + make + + cd builddir2 + cmake .. + make + +To see what features were activated in :file:`myconfig.hpp`, run: + +.. code-block:: bash + + ./pypresso + +and then in the Python interpreter: + +.. code-block:: python + + import espressomd + print(espressomd.features()) + + .. _cmake: -cmake -^^^^^ +``cmake`` +^^^^^^^^^ In order to build the first step is to create a build directory in which cmake can be executed. In cmake, the *source directory* (that contains @@ -615,10 +617,11 @@ are ever modified by the build process. Afterwards |es| can be run via calling :file:`./pypresso` from the command line. + .. _ccmake: -ccmake -^^^^^^ +``ccmake`` +^^^^^^^^^^ Optionally and for easier use, the curses interface to cmake can be used to configure |es| interactively. @@ -681,10 +684,8 @@ build directory and create a new one. -.. _make\: Compiling, testing and installing: - -``make``: Compiling, testing and installing -------------------------------------------- +Compiling, testing and installing +--------------------------------- The command ``make`` is mainly used to compile the source code, but it can do a number of other things. The generic syntax of the ``make`` @@ -743,6 +744,9 @@ compilation process significantly. Running |es| ------------ +Executing a simulation script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + |es| is implemented as a Python module. This means that you need to write a python script for any task you want to perform with |es|. In this chapter, the basic structure of the interface will be explained. For a practical @@ -763,6 +767,9 @@ module to the system's python interpreter by modifying the ``$PYTHONPATH``. Please see the following chapter :ref:`Setting up the system` describing how to actually write a simulation script for |es|. +Running an interactive notebook +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Running the Jupyter interpreter requires using the ``ipypresso`` script, which is also located in the build directory (its name comes from the IPython interpreter, today known as Jupyter). To run the tutorials, you will need From aa3eaba262f24c763608858af5a921434d57b1b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 15:18:43 +0100 Subject: [PATCH 07/12] Fix rhomboid shape documentation error --- doc/sphinx/constraints.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/constraints.rst b/doc/sphinx/constraints.rst index 57dc5668cfa..6bb5cea2dda 100644 --- a/doc/sphinx/constraints.rst +++ b/doc/sphinx/constraints.rst @@ -278,7 +278,7 @@ The direction ``direction`` determines the force direction, ``-1`` for inward an :: - 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], From 5d6a1631b997001f032ee1a3cad7af3e9f3b163e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 15:19:10 +0100 Subject: [PATCH 08/12] Re-organize shapes documentation Format ":class:`shape`\n\tText1\n\nText2" (aka class link followed by an indented paragraph and a dedented paragraph) generates an HTML definition list where class names are the definition terms and Text1 the definitions, but the list is broken by the Text2 paragraphs. The broken definition list was replaced by Sphinx paragraphs. The sections were also slightly re-organized to make the two types of constraints (shapes and fields) more apparent. --- doc/sphinx/constraints.rst | 106 ++++++++++++++++++++++++------------- 1 file changed, 68 insertions(+), 38 deletions(-) diff --git a/doc/sphinx/constraints.rst b/doc/sphinx/constraints.rst index 6bb5cea2dda..d38fe80578c 100644 --- a/doc/sphinx/constraints.rst +++ b/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``, radius ``radius`` -and length ``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,13 +276,15 @@ 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. :: @@ -288,12 +299,18 @@ 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. @@ -314,10 +331,12 @@ 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`), @@ -325,7 +344,7 @@ which points in the direction of the symmetry axis and does not need to be norma 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. @@ -353,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 `. It is translationally invariant in y direction. @@ -400,10 +420,12 @@ 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 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. @@ -425,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. @@ -440,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. @@ -454,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 @@ -540,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: @@ -559,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 From ee79e568f48c0edff4846b8f6c2041f8373a57d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 15:42:47 +0100 Subject: [PATCH 09/12] Rename tutorial 06 subfolders to lowercase --- .../06-active_matter/06-active_matter.ipynb | 28 +++++++-------- doc/tutorials/06-active_matter/CMakeLists.txt | 32 +++++++++--------- .../enhanced_diffusion.py | 0 .../{EXERCISES => exercises}/flow_field.py | 0 .../rectification_geometry.py | 0 .../rectification_simulation.py | 0 .../{FIGURES => figures}/enhanced.pdf | Bin .../{FIGURES => figures}/enhanced.svg | 0 .../{FIGURES => figures}/flow_field.pdf | Bin .../{FIGURES => figures}/flow_field.svg | 0 .../{FIGURES => figures}/friction.pdf | Bin .../{FIGURES => figures}/friction.svg | 0 .../{FIGURES => figures}/friction.tex | 0 .../{FIGURES => figures}/geometry.pdf | Bin .../{FIGURES => figures}/geometry.svg | 0 .../{FIGURES => figures}/geometry.tex | 0 .../{FIGURES => figures}/pusher-puller.pdf | Bin .../{FIGURES => figures}/pusher-puller.svg | 0 .../{FIGURES => figures}/pusher-puller.tex | 0 .../{FIGURES => figures}/rectification.pdf | Bin .../{FIGURES => figures}/rectification.svg | 0 .../{FIGURES => figures}/rectify.pdf | Bin .../{FIGURES => figures}/rectify.svg | 0 .../enhanced_diffusion.py | 0 .../{SOLUTIONS => solutions}/flow_field.py | 0 .../rectification_geometry.py | 0 .../rectification_simulation.py | 0 .../{SOLUTIONS => solutions}/solutions.txt | 0 ...st_06-active_matter__enhanced_diffusion.py | 2 +- .../test_06-active_matter__flow_field.py | 2 +- ...6-active_matter__rectification_geometry.py | 2 +- ...active_matter__rectification_simulation.py | 2 +- 32 files changed, 34 insertions(+), 34 deletions(-) rename doc/tutorials/06-active_matter/{EXERCISES => exercises}/enhanced_diffusion.py (100%) rename doc/tutorials/06-active_matter/{EXERCISES => exercises}/flow_field.py (100%) rename doc/tutorials/06-active_matter/{EXERCISES => exercises}/rectification_geometry.py (100%) rename doc/tutorials/06-active_matter/{EXERCISES => exercises}/rectification_simulation.py (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/enhanced.pdf (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/enhanced.svg (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/flow_field.pdf (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/flow_field.svg (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/friction.pdf (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/friction.svg (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/friction.tex (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/geometry.pdf (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/geometry.svg (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/geometry.tex (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/pusher-puller.pdf (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/pusher-puller.svg (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/pusher-puller.tex (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/rectification.pdf (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/rectification.svg (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/rectify.pdf (100%) rename doc/tutorials/06-active_matter/{FIGURES => figures}/rectify.svg (100%) rename doc/tutorials/06-active_matter/{SOLUTIONS => solutions}/enhanced_diffusion.py (100%) rename doc/tutorials/06-active_matter/{SOLUTIONS => solutions}/flow_field.py (100%) rename doc/tutorials/06-active_matter/{SOLUTIONS => solutions}/rectification_geometry.py (100%) rename doc/tutorials/06-active_matter/{SOLUTIONS => solutions}/rectification_simulation.py (100%) rename doc/tutorials/06-active_matter/{SOLUTIONS => solutions}/solutions.txt (100%) diff --git a/doc/tutorials/06-active_matter/06-active_matter.ipynb b/doc/tutorials/06-active_matter/06-active_matter.ipynb index 8ca82f45260..b7841b3e1e3 100644 --- a/doc/tutorials/06-active_matter/06-active_matter.ipynb +++ b/doc/tutorials/06-active_matter/06-active_matter.ipynb @@ -116,7 +116,7 @@ "\n", "\n", "
", - "\n", + "\n", "
\n", "
Fig. 1: A balance of the driving force in the\n", "direction defined by the ‘director’ unit vector and the friction due to\n", @@ -200,7 +200,7 @@ "\n", "\n", "
", - "\n", + "\n", "
\n", "
Fig. 2: (a) Illustration of a sperm cell modeled\n", "using our two-point swimmer code. The head is represented by a solid particle,\n", @@ -338,7 +338,7 @@ "Please uncomment them in the myconfig.hpp and compile **ESPResSo** using this myconfig.hpp.\n", "\n", "Next you can find the tutorial files in the doc/tutorials/06-active_matter/\n", - "directory. There are two folders, one called EXERCISES and one called SOLUTIONS." + "directory. There are two folders, one called exercises and one called solutions." ] }, { @@ -346,13 +346,13 @@ "metadata": {}, "source": [ "### The Enhanced-Diffusion Tutorial\n", - "In the folder EXERCISES you will find the enhanced_diffusion.py file.\n", + "In the folder exercises you will find the enhanced_diffusion.py file.\n", "This tutorial demonstrates that our Langevin-based swimmer code captures\n", "enhanced diffusion. N.B. It is incomplete and needs your input to be evaluated\n", - "in **ESPResSo** without errors. A fully functional file exists in the SOLUTIONS\n", + "in **ESPResSo** without errors. A fully functional file exists in the solutions\n", "folder, but we recommend that you try solving the exercises on your own first.\n", "\n", - "To start the exercises, go into the EXERCISES directory and invoke the Python variant of **ESPResSo** on the script\n", + "To start the exercises, go into the exercises directory and invoke the Python variant of **ESPResSo** on the script\n", "\n", "```sh\n", "../../../../pypresso enhanced_diffusion.py 0.0\n", @@ -448,7 +448,7 @@ "\n", "\n", "
", - "\n", + "\n", "
\n", "
Fig. 3: (a) Averaged MSD with standard error for the\n", "passive and active particle. The dependence of the MSD on time ($t$) has been\n", @@ -499,7 +499,7 @@ "source": [ "### The Rectifying-Geometry Tutorial\n", "\n", - "Here, we will set up a rectifying geometry. In the folder EXERCISES you will\n", + "Here, we will set up a rectifying geometry. In the folder exercises you will\n", "find the rectification_geometry.py file. This will help you construct\n", "and visualize a rectifying geometry of a cylindrical chamber with a wedge-like\n", "obstacle in the center, see Fig. 4(a). You will first need to\n", @@ -512,7 +512,7 @@ "\n", "\n", "
", - "\n", + "\n", "
\n", "
Fig. 4: (a) Sketch of the rectifying geometry which we\n", "simulate for this tutorial. (b) The geometry of the HollowConicalFrustum\n", @@ -555,7 +555,7 @@ "\n", "\n", "
", - "\n", + "\n", "
\n", "
Fig. 5: (a) Snapshot of the rectifying geometry, as visualized with ParaView. (b) Final state for the system with 500 particles and vel=5.0. Note that there are more particles in the left-hand chamber, due to the rectification.
\n", "
\n", @@ -569,7 +569,7 @@ "### The Rectification Tutorial\n", "\n", "Now we will study the effectiveness of our rectifying geometry. In the\n", - "folder EXERCISES you will find the rectification_simulation.py file. This\n", + "folder exercises you will find the rectification_simulation.py file. This\n", "Python script will allow the user to appreciate the differences between a\n", "passive and an active ‘ideal gas’ in the above geometry. Again, you will have\n", "to complete the exercises to obtain a functioning script. N.B. Once up and\n", @@ -638,7 +638,7 @@ "\n", "\n", "
", - "\n", + "\n", "
\n", "
Fig. 6: The change in the position of the CMS for the\n", "rectifying geometry with particles. The passive system fluctuates around zero\n", @@ -703,7 +703,7 @@ "### The Flow-Field Tutorial\n", "\n", "Now we will study the flow field around a simple pusher and puller particle in\n", - "**ESPResSo**. In the folder EXERCISES you will find the flow_field.py file.\n", + "**ESPResSo**. In the folder exercises you will find the flow_field.py file.\n", "Once again, you will have to complete the excercises to obtain a functioning\n", "script. The structure of the blocks and their content should by now be\n", "straightforward for you to understand on the basis of the previous tutorials\n", @@ -712,7 +712,7 @@ "\n", "\n", "
", - "\n", + "\n", "
\n", "
Fig. 7: (a) Snapshot of the flow field around a pusher particle visualized with ParaView.
\n", "
\n", diff --git a/doc/tutorials/06-active_matter/CMakeLists.txt b/doc/tutorials/06-active_matter/CMakeLists.txt index 8b3e2811924..39b979cfecd 100644 --- a/doc/tutorials/06-active_matter/CMakeLists.txt +++ b/doc/tutorials/06-active_matter/CMakeLists.txt @@ -2,22 +2,22 @@ configure_tutorial_target( TARGET tutorial_06 DEPENDS 06-active_matter.ipynb - FIGURES/friction.svg - FIGURES/pusher-puller.svg - FIGURES/enhanced.svg - FIGURES/geometry.svg - FIGURES/rectify.svg - FIGURES/rectification.svg - FIGURES/flow_field.svg - EXERCISES/enhanced_diffusion.py - EXERCISES/flow_field.py - EXERCISES/rectification_geometry.py - EXERCISES/rectification_simulation.py - SOLUTIONS/enhanced_diffusion.py - SOLUTIONS/flow_field.py - SOLUTIONS/rectification_geometry.py - SOLUTIONS/rectification_simulation.py - SOLUTIONS/solutions.txt + figures/friction.svg + figures/pusher-puller.svg + figures/enhanced.svg + figures/geometry.svg + figures/rectify.svg + figures/rectification.svg + figures/flow_field.svg + exercises/enhanced_diffusion.py + exercises/flow_field.py + exercises/rectification_geometry.py + exercises/rectification_simulation.py + solutions/enhanced_diffusion.py + solutions/flow_field.py + solutions/rectification_geometry.py + solutions/rectification_simulation.py + solutions/solutions.txt ) nb_export(TARGET tutorial_06 SUFFIX "" FILE "06-active_matter.ipynb" HTML_RUN) diff --git a/doc/tutorials/06-active_matter/EXERCISES/enhanced_diffusion.py b/doc/tutorials/06-active_matter/exercises/enhanced_diffusion.py similarity index 100% rename from doc/tutorials/06-active_matter/EXERCISES/enhanced_diffusion.py rename to doc/tutorials/06-active_matter/exercises/enhanced_diffusion.py diff --git a/doc/tutorials/06-active_matter/EXERCISES/flow_field.py b/doc/tutorials/06-active_matter/exercises/flow_field.py similarity index 100% rename from doc/tutorials/06-active_matter/EXERCISES/flow_field.py rename to doc/tutorials/06-active_matter/exercises/flow_field.py diff --git a/doc/tutorials/06-active_matter/EXERCISES/rectification_geometry.py b/doc/tutorials/06-active_matter/exercises/rectification_geometry.py similarity index 100% rename from doc/tutorials/06-active_matter/EXERCISES/rectification_geometry.py rename to doc/tutorials/06-active_matter/exercises/rectification_geometry.py diff --git a/doc/tutorials/06-active_matter/EXERCISES/rectification_simulation.py b/doc/tutorials/06-active_matter/exercises/rectification_simulation.py similarity index 100% rename from doc/tutorials/06-active_matter/EXERCISES/rectification_simulation.py rename to doc/tutorials/06-active_matter/exercises/rectification_simulation.py diff --git a/doc/tutorials/06-active_matter/FIGURES/enhanced.pdf b/doc/tutorials/06-active_matter/figures/enhanced.pdf similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/enhanced.pdf rename to doc/tutorials/06-active_matter/figures/enhanced.pdf diff --git a/doc/tutorials/06-active_matter/FIGURES/enhanced.svg b/doc/tutorials/06-active_matter/figures/enhanced.svg similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/enhanced.svg rename to doc/tutorials/06-active_matter/figures/enhanced.svg diff --git a/doc/tutorials/06-active_matter/FIGURES/flow_field.pdf b/doc/tutorials/06-active_matter/figures/flow_field.pdf similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/flow_field.pdf rename to doc/tutorials/06-active_matter/figures/flow_field.pdf diff --git a/doc/tutorials/06-active_matter/FIGURES/flow_field.svg b/doc/tutorials/06-active_matter/figures/flow_field.svg similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/flow_field.svg rename to doc/tutorials/06-active_matter/figures/flow_field.svg diff --git a/doc/tutorials/06-active_matter/FIGURES/friction.pdf b/doc/tutorials/06-active_matter/figures/friction.pdf similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/friction.pdf rename to doc/tutorials/06-active_matter/figures/friction.pdf diff --git a/doc/tutorials/06-active_matter/FIGURES/friction.svg b/doc/tutorials/06-active_matter/figures/friction.svg similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/friction.svg rename to doc/tutorials/06-active_matter/figures/friction.svg diff --git a/doc/tutorials/06-active_matter/FIGURES/friction.tex b/doc/tutorials/06-active_matter/figures/friction.tex similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/friction.tex rename to doc/tutorials/06-active_matter/figures/friction.tex diff --git a/doc/tutorials/06-active_matter/FIGURES/geometry.pdf b/doc/tutorials/06-active_matter/figures/geometry.pdf similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/geometry.pdf rename to doc/tutorials/06-active_matter/figures/geometry.pdf diff --git a/doc/tutorials/06-active_matter/FIGURES/geometry.svg b/doc/tutorials/06-active_matter/figures/geometry.svg similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/geometry.svg rename to doc/tutorials/06-active_matter/figures/geometry.svg diff --git a/doc/tutorials/06-active_matter/FIGURES/geometry.tex b/doc/tutorials/06-active_matter/figures/geometry.tex similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/geometry.tex rename to doc/tutorials/06-active_matter/figures/geometry.tex diff --git a/doc/tutorials/06-active_matter/FIGURES/pusher-puller.pdf b/doc/tutorials/06-active_matter/figures/pusher-puller.pdf similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/pusher-puller.pdf rename to doc/tutorials/06-active_matter/figures/pusher-puller.pdf diff --git a/doc/tutorials/06-active_matter/FIGURES/pusher-puller.svg b/doc/tutorials/06-active_matter/figures/pusher-puller.svg similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/pusher-puller.svg rename to doc/tutorials/06-active_matter/figures/pusher-puller.svg diff --git a/doc/tutorials/06-active_matter/FIGURES/pusher-puller.tex b/doc/tutorials/06-active_matter/figures/pusher-puller.tex similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/pusher-puller.tex rename to doc/tutorials/06-active_matter/figures/pusher-puller.tex diff --git a/doc/tutorials/06-active_matter/FIGURES/rectification.pdf b/doc/tutorials/06-active_matter/figures/rectification.pdf similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/rectification.pdf rename to doc/tutorials/06-active_matter/figures/rectification.pdf diff --git a/doc/tutorials/06-active_matter/FIGURES/rectification.svg b/doc/tutorials/06-active_matter/figures/rectification.svg similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/rectification.svg rename to doc/tutorials/06-active_matter/figures/rectification.svg diff --git a/doc/tutorials/06-active_matter/FIGURES/rectify.pdf b/doc/tutorials/06-active_matter/figures/rectify.pdf similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/rectify.pdf rename to doc/tutorials/06-active_matter/figures/rectify.pdf diff --git a/doc/tutorials/06-active_matter/FIGURES/rectify.svg b/doc/tutorials/06-active_matter/figures/rectify.svg similarity index 100% rename from doc/tutorials/06-active_matter/FIGURES/rectify.svg rename to doc/tutorials/06-active_matter/figures/rectify.svg diff --git a/doc/tutorials/06-active_matter/SOLUTIONS/enhanced_diffusion.py b/doc/tutorials/06-active_matter/solutions/enhanced_diffusion.py similarity index 100% rename from doc/tutorials/06-active_matter/SOLUTIONS/enhanced_diffusion.py rename to doc/tutorials/06-active_matter/solutions/enhanced_diffusion.py diff --git a/doc/tutorials/06-active_matter/SOLUTIONS/flow_field.py b/doc/tutorials/06-active_matter/solutions/flow_field.py similarity index 100% rename from doc/tutorials/06-active_matter/SOLUTIONS/flow_field.py rename to doc/tutorials/06-active_matter/solutions/flow_field.py diff --git a/doc/tutorials/06-active_matter/SOLUTIONS/rectification_geometry.py b/doc/tutorials/06-active_matter/solutions/rectification_geometry.py similarity index 100% rename from doc/tutorials/06-active_matter/SOLUTIONS/rectification_geometry.py rename to doc/tutorials/06-active_matter/solutions/rectification_geometry.py diff --git a/doc/tutorials/06-active_matter/SOLUTIONS/rectification_simulation.py b/doc/tutorials/06-active_matter/solutions/rectification_simulation.py similarity index 100% rename from doc/tutorials/06-active_matter/SOLUTIONS/rectification_simulation.py rename to doc/tutorials/06-active_matter/solutions/rectification_simulation.py diff --git a/doc/tutorials/06-active_matter/SOLUTIONS/solutions.txt b/doc/tutorials/06-active_matter/solutions/solutions.txt similarity index 100% rename from doc/tutorials/06-active_matter/SOLUTIONS/solutions.txt rename to doc/tutorials/06-active_matter/solutions/solutions.txt diff --git a/testsuite/scripts/tutorials/test_06-active_matter__enhanced_diffusion.py b/testsuite/scripts/tutorials/test_06-active_matter__enhanced_diffusion.py index c382ca4bd5f..5fc48bfeb44 100644 --- a/testsuite/scripts/tutorials/test_06-active_matter__enhanced_diffusion.py +++ b/testsuite/scripts/tutorials/test_06-active_matter__enhanced_diffusion.py @@ -20,7 +20,7 @@ import os tutorial, skipIfMissingFeatures = importlib_wrapper.configure_and_import( - "@TUTORIALS_DIR@/06-active_matter/SOLUTIONS/enhanced_diffusion.py", + "@TUTORIALS_DIR@/06-active_matter/solutions/enhanced_diffusion.py", cmd_arguments=[5.0], SAMP_STEPS=500, SAMP_LENGTH=100) diff --git a/testsuite/scripts/tutorials/test_06-active_matter__flow_field.py b/testsuite/scripts/tutorials/test_06-active_matter__flow_field.py index 7417e834661..9ca1927494b 100644 --- a/testsuite/scripts/tutorials/test_06-active_matter__flow_field.py +++ b/testsuite/scripts/tutorials/test_06-active_matter__flow_field.py @@ -20,7 +20,7 @@ import os tutorial, skipIfMissingFeatures = importlib_wrapper.configure_and_import( - "@TUTORIALS_DIR@/06-active_matter/SOLUTIONS/flow_field.py", gpu=True, + "@TUTORIALS_DIR@/06-active_matter/solutions/flow_field.py", gpu=True, cmd_arguments=["pusher", 5.0], PROD_STEPS=100, PROD_LENGTH=50) diff --git a/testsuite/scripts/tutorials/test_06-active_matter__rectification_geometry.py b/testsuite/scripts/tutorials/test_06-active_matter__rectification_geometry.py index 50839d44797..62363dde3e5 100644 --- a/testsuite/scripts/tutorials/test_06-active_matter__rectification_geometry.py +++ b/testsuite/scripts/tutorials/test_06-active_matter__rectification_geometry.py @@ -20,7 +20,7 @@ import os tutorial, skipIfMissingFeatures = importlib_wrapper.configure_and_import( - "@TUTORIALS_DIR@/06-active_matter/SOLUTIONS/rectification_geometry.py", + "@TUTORIALS_DIR@/06-active_matter/solutions/rectification_geometry.py", gpu=True) diff --git a/testsuite/scripts/tutorials/test_06-active_matter__rectification_simulation.py b/testsuite/scripts/tutorials/test_06-active_matter__rectification_simulation.py index ec6cfd4a64f..c3efcb9bed7 100644 --- a/testsuite/scripts/tutorials/test_06-active_matter__rectification_simulation.py +++ b/testsuite/scripts/tutorials/test_06-active_matter__rectification_simulation.py @@ -21,7 +21,7 @@ import numpy as np tutorial, skipIfMissingFeatures = importlib_wrapper.configure_and_import( - "@TUTORIALS_DIR@/06-active_matter/SOLUTIONS/rectification_simulation.py", + "@TUTORIALS_DIR@/06-active_matter/solutions/rectification_simulation.py", cmd_arguments=[6.0], PROD_STEPS=100, PROD_LENGTH=150) From 22646ede862f449ae16be096925460b2d923a6b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 16:12:10 +0100 Subject: [PATCH 10/12] Remove inexistent constructor parameter The class ClusterStructure creates it own `_clusters` attribute using class Clusters since e4febe71b9e73. --- src/python/espressomd/cluster_analysis.py | 9 --------- 1 file changed, 9 deletions(-) diff --git a/src/python/espressomd/cluster_analysis.py b/src/python/espressomd/cluster_analysis.py index c86a50915ce..269ce169a58 100644 --- a/src/python/espressomd/cluster_analysis.py +++ b/src/python/espressomd/cluster_analysis.py @@ -80,15 +80,6 @@ class ClusterStructure(ScriptInterfaceHelper): pair_criterion: classes derived from ``_PairCriterion`` Criterion to decide whether two particles are neighbors. - clusters: behaves like a read-only dictionary - Access to individual clusters in the cluster structure either via - ``cluster[i]``, where ``i`` is a (non-consecutive) integer cluster id - or via iteration:: - - for pair in clusters: - - where pair contains the numeric id and the corresponding cluster object. - """ _so_name = "ClusterAnalysis::ClusterStructure" _so_creation_policy = "LOCAL" From 65274a5fde0e7f6c18ccaab502165ca855a1caca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 16:40:44 +0100 Subject: [PATCH 11/12] Fix broken Sphinx formatting Inconsistent indentation can cause issues in recent Sphinx versions (2.4.0+), e.g. `"""Line1\n Line2"""` (with 2 leading spaces) can cause an `Unexpected section title` error; correct formats are `"""Line1\nLine2"""` and `"""\nLine1\nLine2"""` (numpydoc). Bullet lists must have the same level of indentation as the preceding paragraph. Adding one extra indentation on a bullet list causes it to be wrapped inside a
HTML tag. --- src/python/espressomd/cluster_analysis.py | 14 +++++------ src/python/espressomd/io/mpiio.py | 16 ++++++------ src/python/espressomd/pair_criteria.py | 30 +++++++++++------------ src/python/espressomd/particle_data.pyx | 10 ++++---- 4 files changed, 35 insertions(+), 35 deletions(-) diff --git a/src/python/espressomd/cluster_analysis.py b/src/python/espressomd/cluster_analysis.py index 269ce169a58..1132d5bfe79 100644 --- a/src/python/espressomd/cluster_analysis.py +++ b/src/python/espressomd/cluster_analysis.py @@ -136,16 +136,16 @@ class Clusters: """Access to the clusters in the cluster structure. - Access is as follows: + Access is as follows: - * Number of clusters: len(clusters) - * Access a cluster via its id: clusters[id] - * Iterate over clusters:: + * Number of clusters: len(clusters) + * Access a cluster via its id: clusters[id] + * Iterate over clusters:: - for c in clusters: + for c in clusters: - where c will be a tuple containing the cluster id and the cluster object - """ + where c will be a tuple containing the cluster id and the cluster object + """ def __init__(self, cluster_structure): self.cluster_structure = cluster_structure diff --git a/src/python/espressomd/io/mpiio.py b/src/python/espressomd/io/mpiio.py index 1afa16d9402..9233b5d1f7d 100644 --- a/src/python/espressomd/io/mpiio.py +++ b/src/python/espressomd/io/mpiio.py @@ -38,14 +38,14 @@ def write(self, prefix=None, positions=False, velocities=False, Outputs binary data using MPI-IO to several files starting with prefix. Suffixes are: - - head: Information about fields that are dumped, - - pref: Information about processes: 1 int per process, - - id: Particle ids: 1 int per particle, - - pos: Position information (if dumped): 3 doubles per particle, - - vel: Velocity information (if dumped): 3 doubles per particle, - - typ: Type information (if dumped): 1 int per particle, - - bond: Bond information (if dumped): variable amount of data, - - boff: Bond offset information (if bonds are dumped): 1 int per particle. + - head: Information about fields that are dumped, + - pref: Information about processes: 1 int per process, + - id: Particle ids: 1 int per particle, + - pos: Position information (if dumped): 3 doubles per particle, + - vel: Velocity information (if dumped): 3 doubles per particle, + - typ: Type information (if dumped): 1 int per particle, + - bond: Bond information (if dumped): variable amount of data, + - boff: Bond offset information (if bonds are dumped): 1 int per particle. .. note:: Do not read the files on a machine with a different architecture! diff --git a/src/python/espressomd/pair_criteria.py b/src/python/espressomd/pair_criteria.py index e5a8e98b95c..6a3b598a3d7 100644 --- a/src/python/espressomd/pair_criteria.py +++ b/src/python/espressomd/pair_criteria.py @@ -46,13 +46,13 @@ def decide(self, p1, p2): class DistanceCriterion(_PairCriterion): """Pair criterion returning true, if particles are closer than a cutoff. - Periodic boundaries are treated via minimum image convention. + Periodic boundaries are treated via minimum image convention. - The following parameters can be passed to the constructor, changed via set_params() - and retrieved via get_params() + The following parameters can be passed to the constructor, changed via set_params() + and retrieved via get_params() - cut_off : :obj:`float` - distance cut off for the criterion + cut_off : :obj:`float` + distance cut off for the criterion """ _so_name = "PairCriteria::DistanceCriterion" _so_creation_policy = "LOCAL" @@ -63,14 +63,14 @@ class EnergyCriterion(_PairCriterion): """Pair criterion returning true, if the short range energy between the particles is >= the cutoff - Be aware that the short range energy contains the short range part of dipolar and electrostatic interactions, - but not the long range part. + Be aware that the short range energy contains the short range part of dipolar and electrostatic interactions, + but not the long range part. - The following parameters can be passed to the constructor, changed via set_params() - and retrieved via get_params() + The following parameters can be passed to the constructor, changed via set_params() + and retrieved via get_params() - cut_off : :obj:`float` - energy cut off for the criterion + cut_off : :obj:`float` + energy cut off for the criterion """ _so_name = "PairCriteria::EnergyCriterion" _so_creation_policy = "LOCAL" @@ -81,11 +81,11 @@ class BondCriterion(_PairCriterion): """Pair criterion returning true, if a pair bond of given type exists between them - The following parameters can be passed to the constructor, changed via set_params() - and retrieved via get_params() + The following parameters can be passed to the constructor, changed via set_params() + and retrieved via get_params() - bond_type : :obj:`int` - numeric type of the bond + bond_type : :obj:`int` + numeric type of the bond """ _so_name = "PairCriteria::BondCriterion" _so_creation_policy = "LOCAL" diff --git a/src/python/espressomd/particle_data.pyx b/src/python/espressomd/particle_data.pyx index 81a131c63c6..592798e4f94 100644 --- a/src/python/espressomd/particle_data.pyx +++ b/src/python/espressomd/particle_data.pyx @@ -1315,11 +1315,11 @@ cdef class ParticleHandle: """ Checks the validity of the given bond: - - If the bondtype is given as an object or a numerical id - - If all partners are of type :obj:`int` - - If the number of partners satisfies the bond - - If the bond type used exists (is lower than ``n_bonded_ia``) - - If the number of bond partners fits the bond type + - If the bondtype is given as an object or a numerical id + - If all partners are of type :obj:`int` + - If the number of partners satisfies the bond + - If the bond type used exists (is lower than ``n_bonded_ia``) + - If the number of bond partners fits the bond type Throws an exception if any of these are not met. From 092fefe2bfc41265dc09cd474a6f776023b4dadd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 6 Mar 2020 17:23:45 +0100 Subject: [PATCH 12/12] Cleanup Sphinx documentation Fix incorrect Sphinx reST syntax and correct typos. --- src/python/espressomd/accumulators.py | 16 +++---- src/python/espressomd/cluster_analysis.py | 52 ++++++++++++++--------- src/python/espressomd/pair_criteria.py | 29 ++++++++----- src/python/espressomd/particle_data.pyx | 3 +- src/python/espressomd/polymer.pyx | 6 +-- src/python/espressomd/shapes.py | 2 +- src/python/espressomd/utils.pyx | 6 ++- 7 files changed, 69 insertions(+), 45 deletions(-) diff --git a/src/python/espressomd/accumulators.py b/src/python/espressomd/accumulators.py index c05e3ba5161..42b5bc04a70 100644 --- a/src/python/espressomd/accumulators.py +++ b/src/python/espressomd/accumulators.py @@ -26,18 +26,18 @@ class MeanVarianceCalculator(ScriptInterfaceHelper): Parameters ---------- - obs : Instance of :class:`espressomd.observables.Observable`. + obs : :class:`espressomd.observables.Observable` delta_N : :obj:`int` Number of timesteps between subsequent samples for the auto update mechanism. Methods ------- - update + update() Update the accumulator (get the current values from the observable). - get_mean + get_mean() Returns the samples mean values of the respective observable with which the accumulator was initialized. - get_variance + get_variance() Returns the samples variance for the observable. """ @@ -58,17 +58,17 @@ class TimeSeries(ScriptInterfaceHelper): Parameters ---------- - obs : Instance of :class:`espressomd.observables.Observable`. + obs : :class:`espressomd.observables.Observable` delta_N : :obj:`int` Number of timesteps between subsequent samples for the auto update mechanism. Methods ------- - update + update() Update the accumulator (get the current values from the observable). - time_series + time_series() Returns the recorded values of the observable. - clear + clear() Clear the data """ diff --git a/src/python/espressomd/cluster_analysis.py b/src/python/espressomd/cluster_analysis.py index 1132d5bfe79..9b71cbdc536 100644 --- a/src/python/espressomd/cluster_analysis.py +++ b/src/python/espressomd/cluster_analysis.py @@ -21,27 +21,24 @@ @script_interface_register class Cluster(ScriptInterfaceHelper): - """Class representing a cluster of particles + """Class representing a cluster of particles. Methods ------- particle_ids() Returns list of particle ids in the cluster - particles() - Returns an instance of ParticleSlice containing the particles in the cluster - size() Returns the number of particles in the cluster center_of_mass() - center of mass of the cluster + Center of mass of the cluster longest_distance() Longest distance between any combination of two particles in the cluster fractal_dimension(dr=None) - estimates the cluster's fractal dimension by fitting the number of + Estimates the cluster's fractal dimension by fitting the number of particles :math:`n` in spheres of growing radius around the center of mass to :math:`c*r_g^d`, where :math:`r_g` is the radius of gyration of the particles within the sphere, and :math:`d` is the fractal dimension. @@ -52,13 +49,14 @@ class Cluster(ScriptInterfaceHelper): Parameters ---------- - dr: + dr: :obj:`float` Minimum increment for the radius of the spheres. Returns ------- :obj:`tuple`: - Fractal_dimension, mean_square_residual. + Fractal dimension and mean square residual. + """ _so_name = "ClusterAnalysis::Cluster" _so_bind_methods = ("particle_ids", "size", "longest_distance", @@ -67,6 +65,14 @@ class Cluster(ScriptInterfaceHelper): _so_creation_policy = "LOCAL" def particles(self): + """ + Get particles in the cluster. + + Returns + ------- + :class:`espressomd.particle_data.ParticleSlice` + + """ return ParticleSlice(self.particle_ids()) @@ -75,9 +81,9 @@ class ClusterStructure(ScriptInterfaceHelper): """Cluster structure of a simulation system, and access to cluster analysis - Attributes + Parameters ---------- - pair_criterion: classes derived from ``_PairCriterion`` + pair_criterion: :class:`espressomd.pair_criteria._PairCriterion` Criterion to decide whether two particles are neighbors. """ @@ -117,18 +123,25 @@ def cluster_ids(self): return self.call_method("cluster_ids") def cid_for_particle(self, p): - """Returns cluster id for the particle (passed as ParticleHandle or particle id)""" + """Returns cluster id for the particle. + + Parameters + ---------- + p : :obj:`espressomd.particle_data.ParticleHandle` or :obj:`int` containing the particle id + Particle. + + """ if isinstance(p, ParticleHandle): return self.call_method("cid_for_particle", pid=p.id) if isinstance(p, int): return self.call_method("cid_for_particle", pid=p) - else: - raise TypeError( - "The particle has to be passed as instance of Particle handle or as an integer particle id") + raise TypeError( + "The particle has to be passed as instance of ParticleHandle or as an integer particle id") @property def clusters(self): - """Gives access to the clusters in the cluster structure via an instance of :any:`Clusters`.""" + """Gives access to the clusters in the cluster structure via an + instance of :class:`Clusters`.""" return self._clusters @@ -138,13 +151,14 @@ class Clusters: Access is as follows: - * Number of clusters: len(clusters) - * Access a cluster via its id: clusters[id] - * Iterate over clusters:: + * number of clusters: ``len(clusters)`` + * access a cluster via its id: ``clusters[id]`` + * iterate over clusters:: for c in clusters: - where c will be a tuple containing the cluster id and the cluster object + where ``c`` will be a tuple containing the cluster id and the cluster object. + """ def __init__(self, cluster_structure): diff --git a/src/python/espressomd/pair_criteria.py b/src/python/espressomd/pair_criteria.py index 6a3b598a3d7..7c2da54212f 100644 --- a/src/python/espressomd/pair_criteria.py +++ b/src/python/espressomd/pair_criteria.py @@ -48,11 +48,13 @@ class DistanceCriterion(_PairCriterion): """Pair criterion returning true, if particles are closer than a cutoff. Periodic boundaries are treated via minimum image convention. - The following parameters can be passed to the constructor, changed via set_params() - and retrieved via get_params() + The following parameters can be passed to the constructor, changed via + ``set_params()`` and retrieved via ``get_params()``. + Parameters + ---------- cut_off : :obj:`float` - distance cut off for the criterion + distance cutoff for the criterion """ _so_name = "PairCriteria::DistanceCriterion" _so_creation_policy = "LOCAL" @@ -61,16 +63,19 @@ class DistanceCriterion(_PairCriterion): @script_interface_register class EnergyCriterion(_PairCriterion): - """Pair criterion returning true, if the short range energy between the particles is >= the cutoff + """Pair criterion returning true, if the short range energy between the + particles is superior or equal to the cutoff. - Be aware that the short range energy contains the short range part of dipolar and electrostatic interactions, - but not the long range part. + Be aware that the short range energy contains the short range part of + dipolar and electrostatic interactions, but not the long range part. - The following parameters can be passed to the constructor, changed via set_params() - and retrieved via get_params() + The following parameters can be passed to the constructor, changed via + ``set_params()`` and retrieved via ``get_params()``. + Parameters + ---------- cut_off : :obj:`float` - energy cut off for the criterion + energy cutoff for the criterion """ _so_name = "PairCriteria::EnergyCriterion" _so_creation_policy = "LOCAL" @@ -81,9 +86,11 @@ class BondCriterion(_PairCriterion): """Pair criterion returning true, if a pair bond of given type exists between them - The following parameters can be passed to the constructor, changed via set_params() - and retrieved via get_params() + The following parameters can be passed to the constructor, changed via + ``set_params()`` and retrieved via ``get_params()``. + Parameters + ---------- bond_type : :obj:`int` numeric type of the bond """ diff --git a/src/python/espressomd/particle_data.pyx b/src/python/espressomd/particle_data.pyx index 592798e4f94..cdcc5bd500b 100644 --- a/src/python/espressomd/particle_data.pyx +++ b/src/python/espressomd/particle_data.pyx @@ -1416,7 +1416,8 @@ cdef class ParticleHandle: Parameters ---------- - _bond : bond to be deleted + _bond : + bond to be deleted See Also -------- diff --git a/src/python/espressomd/polymer.pyx b/src/python/espressomd/polymer.pyx index 7540679e508..c9c9dfb1117 100644 --- a/src/python/espressomd/polymer.pyx +++ b/src/python/espressomd/polymer.pyx @@ -180,14 +180,14 @@ def setup_diamond_polymer(system=None, bond=None, MPC=0, Parameters ---------- - system : instance of :obj:`espressomd.system.System`, required + system : :class:`espressomd.system.System`, required System to which the particles will be added. - bond : instance of :obj:`espressomd.interactions.BondedInteraction`, required if ``no_bonds == False`` + bond : :class:`espressomd.interactions.BondedInteraction`, required if ``no_bonds == False`` The bond to be created between monomers. Should be compatible with the spacing ``system.box_l[0]*(0.25 * sqrt(3))/(MPC + 1)`` between monomers. no_bonds : :obj:`bool`, optional If True, the particles will only be placed in the system but not connected by bonds. - In that case, the `bond` argument can be omitted. Defaults to ``False``. + In that case, the ``bond`` argument can be omitted. Defaults to ``False``. MPC : :obj:`int`, optional Monomers per chain, where chain refers to the connection between the 8 lattice nodes of the diamond lattice. diff --git a/src/python/espressomd/shapes.py b/src/python/espressomd/shapes.py index 3c7f0438338..a6baceb033b 100644 --- a/src/python/espressomd/shapes.py +++ b/src/python/espressomd/shapes.py @@ -259,7 +259,7 @@ class HollowConicalFrustum(Shape, ScriptInterfaceHelper): r2: :obj:`float` Radius r2. length: :obj:`float` - Length of the conical frustum along `axis`. + Length of the conical frustum along ``axis``. axis: (3,) array_like of :obj:`float` Symmetry axis. center: (3,) array_like of :obj:`float` diff --git a/src/python/espressomd/utils.pyx b/src/python/espressomd/utils.pyx index 22724a70801..04fda17136b 100644 --- a/src/python/espressomd/utils.pyx +++ b/src/python/espressomd/utils.pyx @@ -43,7 +43,8 @@ cdef List[int] create_int_list_from_python_object(obj): Parameters ---------- - obj : python object which supports subscripts + obj : + python object which supports subscripts """ cdef List[int] il @@ -302,7 +303,8 @@ def is_valid_type(value, t): def requires_experimental_features(reason): - """Class decorator which makes instantiation conditional on EXPERIMENTAL_FEATURES being defined in myconfig.hpp.""" + """Class decorator which makes instantiation conditional on + ``EXPERIMENTAL_FEATURES`` being defined in myconfig.hpp.""" def exception_raiser(self, *args, **kwargs): raise Exception(