diff --git a/doc/sphinx/CMakeLists.txt b/doc/sphinx/CMakeLists.txt index e88318ebcf7..bf38f0d4d54 100644 --- a/doc/sphinx/CMakeLists.txt +++ b/doc/sphinx/CMakeLists.txt @@ -1,4 +1,4 @@ -find_package(Sphinx 1.6.6) +find_package(Sphinx 2.3.0) if(SPHINX_FOUND) # configured documentation tools and intermediate build results set(SPHINX_BASE "${CMAKE_CURRENT_BINARY_DIR}") diff --git a/doc/sphinx/_static/blockquotes.css b/doc/sphinx/_static/blockquotes.css new file mode 100644 index 00000000000..7548db82c78 --- /dev/null +++ b/doc/sphinx/_static/blockquotes.css @@ -0,0 +1,31 @@ +/* + * blockquotes.css + * ~~~~~~~~~~~~~~~ + * + * Extension for basic.css that highlights blockquotes. + * + */ + +/* -- general body styles --------------------------------------------------- */ + +div.body blockquote { + background: #f9f9f9; + border-left: 10px solid #ccc; + margin: 0.25em 10px; + padding: 0.35em 60px; + line-height: 1.45; + position: relative; + color: #383838; +} + +div.body blockquote:before { + color: #ccc; + display: block; + padding-left: 15px; + content: "\201C"; + font-size: 4.5em; + position: absolute; + left: 0px; + top: -5px; +} + diff --git a/doc/sphinx/advanced_methods.rst b/doc/sphinx/advanced_methods.rst index fe774aa398d..fdf95a3dacc 100644 --- a/doc/sphinx/advanced_methods.rst +++ b/doc/sphinx/advanced_methods.rst @@ -25,19 +25,19 @@ 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:: - import espressomd - import espressomd.interactions + import espressomd + import espressomd.interactions - system = espressomd.System(box_l=[1, 1, 1]) - bond_centers = espressomd.interactions.HarmonicBond(k=1000, r_0=) - system.bonded_inter.add(bond_centers) - system.collision_detection.set_params(mode="bind_centers", distance=, - bond_centers=bond_centers) + system = espressomd.System(box_l=[1, 1, 1]) + bond_centers = espressomd.interactions.HarmonicBond(k=1000, r_0=) + system.bonded_inter.add(bond_centers) + system.collision_detection.set_params(mode="bind_centers", distance=, + bond_centers=bond_centers) The parameters are as follows: - * ``distance`` is the distance between two particles at which the binding is triggered. This cutoff distance, ```` in the example above, is typically chosen slightly larger than the particle diameter. It is also a good choice for the equilibrium length of the bond. - * ``bond_centers`` is the bonded interaction (an instance of :class:`espressomd.interactions.HarmonicBond`) to be created between the particles. No guarantees are made regarding which of the two colliding particles gets the bond. Once there is a bond of this type on any of the colliding particles, no further binding occurs for this pair of particles. + * ``distance`` is the distance between two particles at which the binding is triggered. This cutoff distance, ```` in the example above, is typically chosen slightly larger than the particle diameter. It is also a good choice for the equilibrium length of the bond. + * ``bond_centers`` is the bonded interaction (an instance of :class:`espressomd.interactions.HarmonicBond`) to be created between the particles. No guarantees are made regarding which of the two colliding particles gets the bond. Once there is a bond of this type on any of the colliding particles, no further binding occurs for this pair of particles. * ``"bind_at_point_of_collision"``: this mode prevents sliding of the colliding particles at the contact. This is achieved by creating two virtual sites at the point of collision. They are @@ -55,16 +55,15 @@ Several modes are available for different types of binding. the point of contact or you can use :class:`espressomd.interactions.Virtual` which acts as a marker, only. The method is setup as follows:: - system.collision_detection.set_params(mode="bind_at_point_of_collision", - distance=, bond_centers=, bond_vs=, - part_type_vs=, vs_placement=) - + system.collision_detection.set_params(mode="bind_at_point_of_collision", + distance=, bond_centers=, bond_vs=, + part_type_vs=, vs_placement=) The parameters ``distance`` and ``bond_centers`` have the same meaning as in the ``"bind_centers"`` mode. The remaining parameters are as follows: - * ``bond_vs`` is the bond to be added between the two virtual sites created on collision. This is either a pair-bond with an equilibrium length matching the distance between the virtual sites, or an angle bond fully stretched in its equilibrium configuration. - * ``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. + * ``bond_vs`` is the bond to be added between the two virtual sites created on collision. This is either a pair-bond with an equilibrium length matching the distance between the virtual sites, or an angle bond fully stretched in its equilibrium configuration. + * ``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: @@ -80,9 +79,7 @@ Several modes are available for different types of binding. time step, no guarantees are made with regards to which partner is selected. In particular, there is no guarantee that the choice is unbiased. - - -- ``"bind_three_particles"`` allows for the creation of agglomerates which maintain their shape +* ``"bind_three_particles"`` allows for the creation of agglomerates which maintain their shape similarly to those create by the mode ``"bind_at_point_of_collision"``. The present approach works without virtual sites. Instead, for each two-particle collision, the surrounding is searched for a third particle. If one is found, @@ -156,9 +153,9 @@ the local fluid velocity. The immersed boundary method consists of two components, which can be used independently: - * :ref:`Inertialess lattice-Boltzmann tracers` implemented as virtual sites +* :ref:`Inertialess lattice-Boltzmann tracers` implemented as virtual sites - * Interactions providing the elastic forces for the particles forming the surface. These are described in :ref:`Immersed Boundary Method interactions`. +* Interactions providing the elastic forces for the particles forming the surface. These are described in :ref:`Immersed Boundary Method interactions`. For a more detailed description, see e.g. :cite:`guckenberger17a` or contact us. This feature probably does not work with advanced LB features such as electrokinetics. @@ -1302,7 +1299,7 @@ that your computer contains a CUDA capable GPU which is sufficiently modern. To set up a proper LB fluid using this command one has to specify at -least the following options: ``agrid``, ``lb_density``, ``viscosity``, +least the following options: ``agrid``, ``lb_density``, ``viscosity``, ``friction``, ``T``, and ``prefactor``. The other options can be 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 @@ -1456,7 +1453,7 @@ number density and flux of species ``species``, respectively. Local Quantities ^^^^^^^^^^^^^^^^ -Local quantities like velocity or fluid density for single nodes can be accessed in the same way +Local quantities like velocity or fluid density for single nodes can be accessed in the same way as for an LB fluid, see :ref:`Lattice-Boltzmann`. The only EK-specific quantity is the potential. :: @@ -1590,16 +1587,16 @@ after all Drude particles are added to the system:: espressomd.drude_helpers.setup_intramol_exclusion_bonds(, , , , ) -This function creates the requires number of bonds which are later added to the +This function creates the required number of bonds which are later added to the particles. It has to be called only once. In a molecule with :math:`N` polarizable sites, :math:`N \cdot (N-1)` bond types are needed to cover all the combinations. Parameters are: - * ````: The :class:`espressomd.System() `. - * ````: List of the Drude types within the molecule. - * ````: List of the core types within the molecule that have partial charges. - * ````: List of the partial charges on the cores. - * ````: (bool, optional) Prints out information about the created bonds (default: False) +* ````: The :class:`espressomd.System() `. +* ````: List of the Drude types within the molecule. +* ````: List of the core types within the molecule that have partial charges. +* ````: List of the partial charges on the cores. +* ````: (bool, optional) Prints out information about the created bonds (default: False) After setting up the bonds, one has to add them to each molecule with the following method:: @@ -1608,10 +1605,10 @@ following method:: This method has to be called for all molecules and needs the following parameters: - * ````: The :class:`espressomd.System() `. - * ````: The ids of the Drude particles within one molecule. - * ````: The ids of the core particles within one molecule. - * ````: (bool, optional) Prints out information about the added bonds (default: ``False``) +* ````: The :class:`espressomd.System() `. +* ````: The ids of the Drude particles within one molecule. +* ````: The ids of the core particles within one molecule. +* ````: (bool, optional) Prints out information about the added bonds (default: ``False``) Internally, this is done with the bond described in :ref:`Subtract P3M short-range bond`, that simply adds the p3m shortrange pair-force of scale :math:`- q_d q_{partial}` the to diff --git a/doc/sphinx/analysis.rst b/doc/sphinx/analysis.rst index 67aeaff8eb8..3801e1e460c 100644 --- a/doc/sphinx/analysis.rst +++ b/doc/sphinx/analysis.rst @@ -22,17 +22,17 @@ The direct analysis commands can be classified into two types: - Instantaneous analysis routines, that only take into account the current configuration of the system: - - :ref:`Energies` - - :ref:`Pressure` - - :ref:`Pressure Tensor` - - :ref:`Momentum of the System` - - :ref:`Minimal distances between particles` - - :ref:`Particles in the neighborhood` - - :ref:`Particle distribution` - - :ref:`Structure factor` - - :ref:`Center of mass` - - :ref:`Moment of inertia matrix` - - :ref:`Gyration tensor` +- :ref:`Energies` +- :ref:`Pressure` +- :ref:`Pressure Tensor` +- :ref:`Momentum of the System` +- :ref:`Minimal distances between particles` +- :ref:`Particles in the neighborhood` +- :ref:`Particle distribution` +- :ref:`Structure factor` +- :ref:`Center of mass` +- :ref:`Moment of inertia matrix` +- :ref:`Gyration tensor` .. _Energies: @@ -416,7 +416,7 @@ They require special parameters if the cylindrical coordinate system is non-stan For this purpose, use :class:`espressomd.math.CylindricalTransformationParameters` to create a consistent set of the parameters needed. Example:: import espressomd.math - + # shifted and rotated cylindrical coordinates cyl_transform_params = espressomd.math.CylindricalTransformationParameters( center=[5.0, 5.0, 0.0], axis=[0, 1, 0], orientation=[0, 0, 1]) @@ -449,7 +449,6 @@ The following list contains some of the available observables. You can find documentation for all available observables in :mod:`espressomd.observables`. - Observables working on a given set of particles: - - :class:`~espressomd.observables.ParticlePositions`: Positions of the particles - :class:`~espressomd.observables.ParticleVelocities`: Velocities of the particles @@ -463,7 +462,6 @@ documentation for all available observables in :mod:`espressomd.observables`. - :class:`~espressomd.observables.ParticleBodyAngularVelocities`: As above, but in the particles' body-fixed frame. - Observables working on a given set of particles and returning reduced quantities: - - :class:`~espressomd.observables.DipoleMoment`: Total electric dipole moment of the system obtained based on unfolded positions - :class:`~espressomd.observables.MagneticDipoleMoment`: Total magnetic dipole moment of the system based on the :attr:`espressomd.particle_data.ParticleHandle.dip` property. @@ -486,7 +484,6 @@ documentation for all available observables in :mod:`espressomd.observables`. - :class:`~espressomd.observables.RDF`: Radial distribution function. Can be used on two different sets of particles. - Profile observables sampling the spatial profile of various quantities: - - :class:`~espressomd.observables.DensityProfile` - :class:`~espressomd.observables.FluxDensityProfile` @@ -496,7 +493,6 @@ documentation for all available observables in :mod:`espressomd.observables`. - :class:`~espressomd.observables.LBVelocityProfile` - Observables sampling the cylindrical profile of various quantities: - - :class:`~espressomd.observables.CylindricalDensityProfile` - :class:`~espressomd.observables.CylindricalFluxDensityProfile` @@ -508,7 +504,6 @@ documentation for all available observables in :mod:`espressomd.observables`. - :class:`~espressomd.observables.CylindricalLBVelocityProfileAtParticlePositions` - System-wide observables - - :class:`~espressomd.observables.Energy`: Total energy (see :ref:`Energies`) - :class:`~espressomd.observables.Pressure`: Total scalar pressure (see :ref:`Pressure`) diff --git a/doc/sphinx/conf.py.in b/doc/sphinx/conf.py.in index d85f456e91e..7bbc4b4d468 100644 --- a/doc/sphinx/conf.py.in +++ b/doc/sphinx/conf.py.in @@ -15,7 +15,6 @@ # serve to show the default. import sys -import sphinx # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -228,14 +227,11 @@ htmlhelp_basename = 'ESPResSo' # -- reStructuredText options --------------------------------------------- -if sphinx.version_info[:2] < (1, 8): - autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members'] -else: - autodoc_default_options = { - 'members': None, - 'show-inheritance': None, - 'undoc-members': None, - } +autodoc_default_options = { + 'members': None, + 'show-inheritance': None, + 'undoc-members': None, +} # For sidebar toc depth rst_prolog = """ :tocdepth: 3 @@ -254,14 +250,11 @@ napoleon_use_param = False # Suppress warnings for features not compiled in # http://stackoverflow.com/questions/12206334/sphinx-autosummary-toctree-contains-reference-to-nonexisting-document-warnings autodoc_mock_imports = ['featuredefs', 'matplotlib', 'OpenGL', 'mayavi', 'pyface', 'tvtk', 'vtk'] -if sphinx.version_info[:3] < (2, 0, 1): - autodoc_mock_imports.append('MDAnalysis') +# Add custom stylesheets def setup(app): - if sphinx.version_info[:2] < (1, 8): - app.add_stylesheet('bibtex.css') - else: - app.add_css_file('bibtex.css') + app.add_css_file('bibtex.css') + app.add_css_file('blockquotes.css') # -- Options for Cython --------------------------------------------------- diff --git a/doc/sphinx/constraints.rst b/doc/sphinx/constraints.rst index c6710caa4dc..c188c81e6c8 100644 --- a/doc/sphinx/constraints.rst +++ b/doc/sphinx/constraints.rst @@ -48,17 +48,17 @@ create a wall shape you could do:: Available shapes are listed below. - - :class:`espressomd.shapes.Wall` - - :class:`espressomd.shapes.Cylinder` - - :class:`espressomd.shapes.Ellipsoid` - - :class:`espressomd.shapes.Rhomboid` - - :class:`espressomd.shapes.SimplePore` - - :class:`espressomd.shapes.Slitpore` - - :class:`espressomd.shapes.Sphere` - - :class:`espressomd.shapes.SpheroCylinder` - - :class:`espressomd.shapes.Torus` - - :class:`espressomd.shapes.HollowConicalFrustum` - - :class:`espressomd.shapes.Union` +- :class:`espressomd.shapes.Wall` +- :class:`espressomd.shapes.Cylinder` +- :class:`espressomd.shapes.Ellipsoid` +- :class:`espressomd.shapes.Rhomboid` +- :class:`espressomd.shapes.SimplePore` +- :class:`espressomd.shapes.Slitpore` +- :class:`espressomd.shapes.Sphere` +- :class:`espressomd.shapes.SpheroCylinder` +- :class:`espressomd.shapes.Torus` +- :class:`espressomd.shapes.HollowConicalFrustum` +- :class:`espressomd.shapes.Union` .. _Adding shape-based constraints to the system: @@ -453,7 +453,7 @@ are described in the shape's class :class:`espressomd.shapes.HollowConicalFrustu :alt: Visualization a HollowConicalFrustum shape with central angle :align: center :height: 6.00000cm - + .. figure:: figures/conical_frustum.png :alt: Schematic for the HollowConicalFrustum shape with labeled geometrical parameters. :align: center diff --git a/doc/sphinx/electrostatics.rst b/doc/sphinx/electrostatics.rst index 2cba0d74d2c..00b5dd8b360 100644 --- a/doc/sphinx/electrostatics.rst +++ b/doc/sphinx/electrostatics.rst @@ -136,7 +136,7 @@ Debye-Hückel potential The Debye-Hückel electrostatic potential is defined by - .. math:: U^{C-DH} = C \cdot \frac{q_1 q_2 \exp(-\kappa r)}{r}\quad \mathrm{for}\quad r For example, to print the particle's current position, call:: @@ -132,16 +132,11 @@ where nearest and next nearest neighbor interactions along a chain of bonded particles have to be omitted since they are included in the bonding potentials. Exclusions do not apply to the short range part of electrostatics and magnetostatics methods, e.g. to P3M. -:: +To create exclusions for particles pairs 0 and 1:: system.part[0].add_exclusion(1) - -Create exclusions for particles pairs 0 and 1. - -To delete the exclusion, simply use - -:: +To delete the exclusion:: system.part[0].delete_exclusion(1) @@ -170,11 +165,11 @@ The rotation of a particle is controlled via the :attr:`espressomd.particle_data import espressomd system = espressomd.System(box_l=[1, 1, 1]) system.part.add(pos=(0, 0, 0), rotation=(True, False, False)) - + The rotational state of a particle is stored as a quaternion in the :attr:`espressomd.particle_data.ParticleHandle.quat` property. For a value of (1,0,0,0), the body and space frames coincide. When setting up a particle, its orientation state is by default aligned with the space frame of the box. If your particles have a rotational symmetry, you can set up the particle direction (the symmetry axis) using the :attr:`espressomd.particle_data.ParticleHandle.director` property. -Note that then you have no control aver the initial rotation angle around the symmetry axis. +Note that then you have no control over the initial rotation angle around the symmetry axis. If your particles are anisotropic in all three directions, you can either set the :attr:`espressomd.particle_data.ParticleHandle.quat` attribute directly, or (recommended) set up all particle properties in the box frame and then use :attr:`espressomd.particle_data.ParticleHandle.rotate` to rotate the particle to the desired state before starting the simulation. Notes: @@ -348,40 +343,40 @@ to retrieve a particle slice: - By calling :meth:`espressomd.particle_data.ParticleList.add` - When adding several particles at once, a particle slice is returned instead - of a particle handle. + When adding several particles at once, a particle slice is returned instead + of a particle handle. - By slicing :py:attr:`espressomd.system.System.part` - The :class:`~espressomd.particle_data.ParticleList` supports slicing - similarly to lists and NumPy arrays, however with the distinction that - particle slices can have gaps. + The :class:`~espressomd.particle_data.ParticleList` supports slicing + similarly to lists and NumPy arrays, however with the distinction that + particle slices can have gaps. + + Using a colon returns a slice containing all particles:: - Using a colon returns a slice containing all particles:: + print(system.part[:]) - print(system.part[:]) - - To access particles with ids ranging from 0 to 9, use:: + To access particles with ids ranging from 0 to 9, use:: - system.part[0:10] + system.part[0:10] - Note that, like in other cases in Python, the lower bound is inclusive and - the upper bound is non-inclusive. The length of the slice does not have to - be 10, it can be for example 2 if there are only 2 particles in the system - with an id between 0 and 9. + Note that, like in other cases in Python, the lower bound is inclusive and + the upper bound is non-inclusive. The length of the slice does not have to + be 10, it can be for example 2 if there are only 2 particles in the system + with an id between 0 and 9. - It is also possible to get a slice containing particles of specific ids:: + It is also possible to get a slice containing particles of specific ids:: - system.part[[1, 4, 3]] + system.part[[1, 4, 3]] - would contain the particles with ids 1, 4, and 3 in that specific order. + would contain the particles with ids 1, 4, and 3 in that specific order. - By calling :meth:`espressomd.particle_data.ParticleList.select` - This is useful to filter out particles with distinct properties, e.g.:: + This is useful to filter out particles with distinct properties, e.g.:: - slice1 = system.part.select(type=0, q=1) - slice2 = system.part.select(lambda p: p.pos[0] < 0.5) + slice1 = system.part.select(type=0, q=1) + slice2 = system.part.select(lambda p: p.pos[0] < 0.5) Properties of particle slices can be accessed just like with single particles. A list of all values is returned:: @@ -394,11 +389,11 @@ Setting properties of slices can be done by - supplying a *single value* that is assigned to each entry of the slice, e.g.:: - system.part[0:10].ext_force = [1, 0, 0] + system.part[0:10].ext_force = [1, 0, 0] - supplying an *array of values* that matches the length of the slice which sets each entry individually, e.g.:: - system.part[0:3].ext_force = [[1, 0, 0], [2, 0, 0], [3, 0, 0]] + system.part[0:3].ext_force = [[1, 0, 0], [2, 0, 0], [3, 0, 0]] For list properties that have no fixed length like ``exclusions`` or ``bonds``, some care has to be taken. There, *single value* assignment also accepts lists/tuples just like setting the property of an individual particle. For example:: diff --git a/doc/sphinx/system_setup.rst b/doc/sphinx/system_setup.rst index 52fa8be2f12..d617a2304e8 100644 --- a/doc/sphinx/system_setup.rst +++ b/doc/sphinx/system_setup.rst @@ -22,47 +22,47 @@ for further calculations, you should explicitly make a copy e.g. via * :py:attr:`~espressomd.system.System.box_l` - (float[3]) Simulation box lengths of the cuboid box used by |es|. - Note that if you change the box length during the simulation, the folded - particle coordinates will remain the same, i.e., the particle stay in - the same image box, but at the same relative position in their image - box. If you want to scale the positions, use the command - :py:meth:`~espressomd.system.System.change_volume_and_rescale_particles`. + (float[3]) Simulation box lengths of the cuboid box used by |es|. + Note that if you change the box length during the simulation, the folded + particle coordinates will remain the same, i.e., the particle stay in + the same image box, but at the same relative position in their image + box. If you want to scale the positions, use the command + :py:meth:`~espressomd.system.System.change_volume_and_rescale_particles`. * :py:attr:`~espressomd.system.System.periodicity` - (int[3]) Specifies periodicity for the three directions. |es| can be instructed - to treat some dimensions as non-periodic. By default |es| assumes periodicity in - all directions which equals setting this variable to ``[True, True, True]``. - A dimension is specified as non-periodic via setting the periodicity - variable for this dimension to ``False``. E.g. Periodicity only in z-direction - is obtained by ``[False, False, True]``. Caveat: Be aware of the fact that making a - dimension non-periodic does not hinder particles from leaving the box in - this direction. In this case for keeping particles in the simulation box - a constraint has to be set. + (int[3]) Specifies periodicity for the three directions. |es| can be instructed + to treat some dimensions as non-periodic. By default |es| assumes periodicity in + all directions which equals setting this variable to ``[True, True, True]``. + A dimension is specified as non-periodic via setting the periodicity + variable for this dimension to ``False``. E.g. Periodicity only in z-direction + is obtained by ``[False, False, True]``. Caveat: Be aware of the fact that making a + dimension non-periodic does not hinder particles from leaving the box in + this direction. In this case for keeping particles in the simulation box + a constraint has to be set. * :py:attr:`~espressomd.system.System.time_step` - (float) Time step for MD integration. + (float) Time step for MD integration. * :py:attr:`~espressomd.system.System.time` - (float) The simulation time. + (float) The simulation time. * :py:attr:`~espressomd.system.System.min_global_cut` - (float) Minimal total cutoff for real space. Effectively, this plus the - :py:attr:`~espressomd.cellsystem.CellSystem.skin` is the minimally possible - cell size. |es| typically determines this value automatically, but some - algorithms, virtual sites, require you to specify it manually. + (float) Minimal total cutoff for real space. Effectively, this plus the + :py:attr:`~espressomd.cellsystem.CellSystem.skin` is the minimally possible + cell size. |es| typically determines this value automatically, but some + algorithms, virtual sites, require you to specify it manually. * :py:attr:`~espressomd.system.System.max_cut_bonded` - *read-only* Maximal cutoff of bonded real space interactions. + *read-only* Maximal cutoff of bonded real space interactions. * :py:attr:`~espressomd.system.System.max_cut_nonbonded` - *read-only* Maximal cutoff of bonded real space interactions. + *read-only* Maximal cutoff of bonded real space interactions. .. _Accessing module states: @@ -102,25 +102,25 @@ Global properties The properties of the cell system can be accessed by :class:`espressomd.system.System.cell_system`: - * :py:attr:`~espressomd.cellsystem.CellSystem.node_grid` +* :py:attr:`~espressomd.cellsystem.CellSystem.node_grid` - (int[3]) 3D node grid for real space domain decomposition (optional, if - unset an optimal set is chosen automatically). The domain decomposition - can be visualized with :file:`samples/visualization_cellsystem.py`. + (int[3]) 3D node grid for real space domain decomposition (optional, if + unset an optimal set is chosen automatically). The domain decomposition + can be visualized with :file:`samples/visualization_cellsystem.py`. - * :py:attr:`~espressomd.cellsystem.CellSystem.skin` +* :py:attr:`~espressomd.cellsystem.CellSystem.skin` - (float) Skin for the Verlet list. This value has to be set, otherwise the simulation will not start. + (float) Skin for the Verlet list. This value has to be set, otherwise the simulation will not start. Details about the cell system can be obtained by :meth:`espressomd.system.System.cell_system.get_state() `: - * ``cell_grid`` Dimension of the inner cell grid. - * ``cell_size`` Box-length of a cell. - * ``local_box_l`` Local simulation box length of the nodes. - * ``max_cut`` Maximal cutoff of real space interactions. - * ``n_nodes`` Number of nodes. - * ``type`` The current type of the cell system. - * ``verlet_reuse`` Average number of integration steps the Verlet list is re-used. +* ``cell_grid`` Dimension of the inner cell grid. +* ``cell_size`` Box-length of a cell. +* ``local_box_l`` Local simulation box length of the nodes. +* ``max_cut`` Maximal cutoff of real space interactions. +* ``n_nodes`` Number of nodes. +* ``type`` The current type of the cell system. +* ``verlet_reuse`` Average number of integration steps the Verlet list is re-used. .. _Domain decomposition: diff --git a/doc/sphinx/visualization.rst b/doc/sphinx/visualization.rst index abe7dd4a3dc..40fcd07fa71 100644 --- a/doc/sphinx/visualization.rst +++ b/doc/sphinx/visualization.rst @@ -93,12 +93,15 @@ The Mayavi visualizer is created with the following syntax: :class:`espressomd.visualization.mayaviLive()` Required parameters: - * ``system``: The :class:`espressomd.System() ` object. + +* ``system``: The :class:`espressomd.System() ` object. + Optional keywords: - * ``particle_sizes``: - * ``"auto"`` (default): The Lennard-Jones sigma value of the self-interaction is used for the particle diameter. - * ``callable``: A lambda function with one argument. Internally, the numerical particle type is passed to the lambda function to determine the particle radius. - * ``list``: A list of particle radii, indexed by the particle type. + +* ``particle_sizes``: + * ``"auto"`` (default): The Lennard-Jones sigma value of the self-interaction is used for the particle diameter. + * ``callable``: A lambda function with one argument. Internally, the numerical particle type is passed to the lambda function to determine the particle radius. + * ``list``: A list of particle radii, indexed by the particle type. .. _OpenGL visualizer: @@ -111,9 +114,12 @@ The optional keywords in ``**kwargs`` are used to adjust the appearance of the v The parameters have suitable default values for most simulations. Required parameters: - * ``system``: The :class:`espressomd.System() ` object. + +* ``system``: The :class:`espressomd.System() ` object. + Optional keywords: - * Have a look at the attribute list in :class:`espressomd.visualization.openGLLive()` + +* Have a look at the attribute list in :class:`espressomd.visualization.openGLLive()` .. note:: @@ -223,10 +229,10 @@ Visualize vectorial properties Most vectorial particle properties can be visualized by 3D-arrows on the particles: - * ``ext_force``: An external force. Activate with the keyword ``ext_force_arrows = True``. - * ``f``: The force acting on the particle. Activate with the keyword ``force_arrows = True``. - * ``v``: The velocity of the particle. Activate with the keyword ``velocity_arrows = True``. - * ``director``: A vector associated with the orientation of the particle. Activate with the keyword ``director_arrows = True``. +* ``ext_force``: An external force. Activate with the keyword ``ext_force_arrows = True``. +* ``f``: The force acting on the particle. Activate with the keyword ``force_arrows = True``. +* ``v``: The velocity of the particle. Activate with the keyword ``velocity_arrows = True``. +* ``director``: A vector associated with the orientation of the particle. Activate with the keyword ``director_arrows = True``. Arrow colors, scales and radii can be adjusted. Again, the lists specifying these quantities are indexed circularly by the numerical particle type. The @@ -274,17 +280,17 @@ Controls The camera can be controlled via mouse and keyboard: - * hold left button: rotate the system - * hold right button: translate the system - * hold middle button: zoom / roll - * mouse wheel / key pair TG: zoom - * WASD-Keyboard control (WS: move forwards/backwards, AD: move sidewards) - * Key pairs QE, RF, ZC: rotate the system - * Double click on a particle: Show particle information - * Double click in empty space: Toggle system information - * Left/Right arrows: Cycle through particles - * Space: If started with ``run(n)``, this pauses the simulation - * Enter: Creates a snapshot of the current window and saves it to :file:`_n.png` (with incrementing ``n``) +* hold left button: rotate the system +* hold right button: translate the system +* hold middle button: zoom / roll +* mouse wheel / key pair TG: zoom +* WASD-Keyboard control (WS: move forwards/backwards, AD: move sidewards) +* Key pairs QE, RF, ZC: rotate the system +* Double click on a particle: Show particle information +* Double click in empty space: Toggle system information +* Left/Right arrows: Cycle through particles +* Space: If started with ``run(n)``, this pauses the simulation +* Enter: Creates a snapshot of the current window and saves it to :file:`_n.png` (with incrementing ``n``) Additional input functionality for mouse and keyboard is possible by assigning callbacks to specified keyboard or mouse buttons. This may be useful for diff --git a/doc/tutorials/active_matter/active_matter.ipynb b/doc/tutorials/active_matter/active_matter.ipynb index 25b56345f88..2ede98d2099 100644 --- a/doc/tutorials/active_matter/active_matter.ipynb +++ b/doc/tutorials/active_matter/active_matter.ipynb @@ -42,14 +42,10 @@ "out-of-equilibrium (thermodynamically) and (can) thus defy description using\n", "the standard framework of statistical mechanics. Active systems are, however,\n", "ubiquitous. On our length scale, we encounter flocks of\n", - "birds, schools of fish, and, of course,\n", - "humans;\n", - "on the mesoscopic level examples are found in\n", - "bacteria,\n", - "sperm,\n", - "and algae;\n", + "birds, schools of fish, and, of course, humans;\n", + "on the mesoscopic level examples are found in bacteria, sperm, and algae;\n", "and on the nanoscopic level, transport along the cytoskeleton is achieved by\n", - "myosin motors. This exemplifies that range of length scales\n", + "myosin motors. This exemplifies the range of length scales\n", "which the field of active matter encompasses, as well as its diversity. Recent\n", "years have seen a huge increase in studies into systems consisting of\n", "self-propelled particles, in particular artificial ones in the colloidal\n", @@ -77,8 +73,7 @@ "the orientation of the particle is defined by a quaternion; this in turn\n", "defines a rotation matrix that acts on the particle's initial orientation\n", "(along the z-axis), which then defines the particles current orientation\n", - "through the matrix-oriented\n", - "vector.\n", + "through the matrix-oriented vector.\n", "Within the ENGINE feature there are two ways of setting up a self-propelled\n", "particle, with and without hydrodynamic interactions. The particle without\n", "hydrodynamic interactions will be discussed first, as it is the simplest case." @@ -90,12 +85,12 @@ "source": [ "### Self-Propulsion without Hydrodynamics\n", "\n", - "For this type of self-propulsion the Langevin thermostat is exploited. The\n", - "Langevin thermostat causes a particle to experience a velocity-dependent\n", - "friction. When a constant force is applied along the director,\n", + "For this type of self-propulsion the Langevin thermostat can be used. The\n", + "Langevin thermostat imposes a velocity-dependent friction on a particle.\n", + "When a constant force is applied along the director,\n", "the friction causes the particle to attain a terminal velocity, due to the balance\n", - "of driving and friction force, see Fig. 1. The exponent with\n", - "which the particle's velocity relaxes towards this value, depends on the\n", + "of driving and friction force, see Fig. 1. The exponent with\n", + "which the particle's velocity relaxes towards this value depends on the\n", "strength of the friction and the mass of the particle. The ENGINE\n", "feature implies that rotation of the particles (the ROTATION feature) is\n", "compiled into **ESPResSo**. The particle can thus reorient due to external torques or\n", @@ -484,7 +479,7 @@ "metadata": {}, "source": [ "In the second part of this tutorial you will consider the ‘rectifying’ properties of certain\n", - "asymmetric geometries on active systems. Rectification can best be understood by\n", + "asymmetric geometries on active systems. Rectification can be best understood by\n", "considering a system of passive particles first. In an equilibrium system,\n", "for which the particles are confined to an asymmetric box with hard walls, we know that the\n", "particle density is homogeneous throughout. However, in an out-of-equilibrium setting one can have a\n", @@ -496,11 +491,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The geometry we will use is a cylindrical system with a funnel dividing two halves of the box as shown in the figure below.\n", + "The geometry we will use is a cylindrical system with a funnel dividing\n", + "two halves of the box as shown in Fig. 2.\n", "\n", + "\n", "
\n", "
\n", - "
Sketch of the rectifying geometry which we\n", + "
Fig. 2: Sketch of the rectifying geometry which we\n", "simulate for this tutorial.
\n", "
\n", "
" @@ -808,7 +805,7 @@ "that active systems (bacteria, sperm, algae, but also artificial chemically\n", "powered swimmers) are force free. That is, the flow field around one of these\n", "objects does not contain a monopolar (Stokeslet) contribution. In the case of a\n", - "sperm cell, see Fig. 2(a), the reasoning is as follows.\n", + "sperm cell, see Fig. 3(a), the reasoning is as follows.\n", "The whip-like tail pushes against the fluid and the fluid pushes against the\n", "tail, at the same time the head experiences drag, pushing against the fluid and\n", "being pushed back against by the fluid. This ensures that both the swimmer and\n", @@ -819,12 +816,12 @@ "orientation, there are two types of swimmer: pushers and pullers. The\n", "distinction is made by whether the particle pulls fluid in from the front and\n", "back, and pushes it out towards its side (puller), or vice versa (pusher), see\n", - "Fig. 2(c,d).\n", + "Fig. 3(c,d).\n", "\n", "\n", "
\n", "
\n", - "
Fig. 2: (a) Illustration of a sperm cell modeled\n", + "
Fig. 3: (a) Illustration of a sperm cell modeled\n", "using our two-point swimmer code. The head is represented by a solid particle,\n", "on which a force is acting (black arrow). In the fluid a counter force is\n", "applied (white arrow). This generates a pusher-type particle. (b) Illustration\n", @@ -846,13 +843,13 @@ "or cause the particle not to move. This dipole length together with the\n", "director and the keyword pusher/puller determines where the counter\n", "force on the fluid is applied to make the system force free, see\n", - "Fig. 2(a) for an illustration of the setup. That is to\n", + "Fig. 3(a) for an illustration of the setup. That is to\n", "say, a force of magnitude `f_swim` is applied to the particle (leading\n", "to a Stokeslet in the fluid, due to friction) and a counter force is applied to\n", "compensate for this in the fluid (resulting in an extended dipole flow field,\n", "due to the second monopole). For a puller the counter force is applied in front\n", "of the particle and for a pusher it is in the back\n", - "(Fig. 2(b)).\n", + "(Fig. 3(b)).\n", "\n", "Finally, there are a few caveats to the swimming setup with hydrodynamic\n", "interactions. First, the stability of this algorithm is governed by the\n", @@ -909,7 +906,7 @@ }, "source": [ "### Exercise\n", - "* Using `HYDRO_PARAMS`, set up an Lattice-Boltzmann fluid and activate it as a thermostat (Hint: [Lattice-Boltzmann](https://espressomd.github.io/doc/lb.html#lattice-boltzmann))" + "* Using `HYDRO_PARAMS`, set up a lattice-Boltzmann fluid and activate it as a thermostat (Hint: [lattice-Boltzmann](https://espressomd.github.io/doc/lb.html#lattice-boltzmann))" ] }, { @@ -1015,7 +1012,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can also export the particle and fluid data to ``.vtk`` format to display the results with a visualization software like ``paraview``" + "We can also export the particle and fluid data to ``.vtk`` format to display the results with a visualization software like ParaView." ] }, { @@ -1032,7 +1029,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The result of such a visualization could look like this:" + "The result of such a visualization could look like Fig. 4." ] }, { @@ -1042,7 +1039,7 @@ "\n", "
\n", "
\n", - "
Snapshot of the flow field around a pusher particle visualized with ParaView.
\n", + "
Fig. 4: Snapshot of the flow field around a pusher particle visualized with ParaView.
\n", "
\n", "
" ] @@ -1056,7 +1053,7 @@ "[1] M. Ballerini, N. Cabibbo, R. Candelier, A. Cavagna, E. Cisbani, I. Giardina, V. Lecomte, A. Orlandi, G. Parisi, A. Procaccini, M. Viale, and V. Zdravkovic. Interaction ruling animal collective behavior depends on topological rather than metric distance: Evidence from a field study. *Proc. Natl. Acad. Sci.*, 105:1232, 2008. \n", "[2] Y. Katz, K. Tunstrøm, C.C. Ioannou, C. Huepe, and I.D. Couzin. Inferring the structure and dynamics of interactions in schooling fish. *Proc. Nat. Acad. Sci.*, 108(46):18720, 2011. \n", "[3] D. Helbing, I. Farkas, and T. Vicsek. Simulating dynamical features of escape panic. *Nature*, 407:487, 2000. \n", - "[4] J. Zhang, W. Klingsch, A. Schadschneider, and A. Seyfried. Experimental study of pedestrian flow through a T-junction. In Valery V. Kozlov, Alexander P. Buslaev, Alexander S. Bugaev, Marina V. Yashina, Andreas Schadschneider, and Michael Schreckenberg, editors, *Traffic and Granular Flow ’11*, page 241. Springer (Berlin/Heidelberg), 2013. \n", + "[4] J. Zhang, W. Klingsch, A. Schadschneider, and A. Seyfried. Experimental study of pedestrian flow through a T-junction. In V. V. Kozlov, A. P. Buslaev, A. S. Bugaev, M. V. Yashina, A. Schadschneider, and M. Schreckenberg, editors, *Traffic and Granular Flow ’11*, page 241. Springer (Berlin/Heidelberg), 2013. \n", "[5] J.L. Silverberg, M. Bierbaum, J.P. Sethna, and I. Cohen. Collective motion of humans in mosh and circle pits at heavy metal concerts. *Phys. Rev. Lett.*, 110:228701, 2013. \n", "[6] A. Sokolov, I.S. Aranson, J.O. Kessler, and R.E. Goldstein. Concentration dependence of the collective dynamics of swimming bacteria. *Phys. Rev. Lett.*, 98:158102, 2007. \n", "[7] J. Schwarz-Linek, C. Valeriani, A. Cacciuto, M. E. Cates, D. Marenduzzo, A. N. Morozov, and W. C. K. Poon. Phase separation and rotor self-assembly in active particle suspensions. *Proc. Nat. Acad. Sci.*, 109:4052, 2012. \n", @@ -1085,19 +1082,19 @@ "[30] M.E. Cates and J. Tailleur. Motility-induced phase separation. *Annu. Rev. Condens. Matter Phys.*, 6:219, 2015. \n", "[31] A. Arnold et al. Espresso user guide. *User Guide: ESPResSo git repository*, 3.4-dev-1404-g32d3874:1, 2015. \n", "[32] H. J. Limbach, A. Arnold, B. A. Mann, and C. Holm. ESPResSo – an extensible simulation package for research on soft matter systems. *Comp. Phys. Comm.*, 174:704, 2006. \n", - "[33] A. Arnold, O. Lenz, S. Kesselheim, R. Weeber, F. Fahrenberger, D. Roehm, P. Košovan, and C. Holm. ESPResSo 3.1 — Molecular Dynamics Software for Coarse-Grained Models. In M. Griebel and M. A. Schweitzer, editors, *Meshfree Methods for Partial Differential* *Equations VI*, volume 89 of *Lecture Notes in Computational Science and Engineering*. Springer, 2013. \n", - "[34] Sven Erik Ilse, Christian Holm, and Joost de Graaf. Surface roughness stabilizes the clustering of self-propelled triangles. *The Journal* *of Chemical Physics*, 145(13):134904, 2016. \n", - "[35] V. Lobaskin and B. Dünweg. A new model of simulating colloidal dynamics. *New J. Phys.*, 6:54, 2004. \n", - "[36] A. Chatterji and J. Horbach. Combining molecular dynamics with lattice boltzmann: A hybrid method for the simulation of (charged) colloidal systems. *J. Chem. Phys.*, 122:184903, 2005. \n", + "[33] A. Arnold, O. Lenz, S. Kesselheim, R. Weeber, F. Fahrenberger, D. Roehm, P. Košovan, and C. Holm. ESPResSo 3.1 — Molecular dynamics software for coarse-grained models. In M. Griebel and M. A. Schweitzer, editors, *Meshfree Methods for Partial Differential* *Equations VI*, volume 89 of *Lecture Notes in Computational Science and Engineering*. Springer, 2013. \n", + "[34] S. E. Ilse, C. Holm, and J. de Graaf. Surface roughness stabilizes the clustering of self-propelled triangles. *The Journal of Chemical Physics*, 145(13):134904, 2016. \n", + "[35] V. Lobaskin and B. Dünweg. A new model of simulating colloidal dynamics. *New J. Phys.*, 6:54, 2004. \n", + "[36] A. Chatterji and J. Horbach. Combining molecular dynamics with lattice Boltzmann: A hybrid method for the simulation of (charged) colloidal systems. *J. Chem. Phys.*, 122:184903, 2005. \n", "[37] L.P. Fischer, T. Peter, C. Holm, and J. de Graaf. The raspberry model for hydrodynamic interactions revisited. I. Periodic arrays of spheres and dumbbells. *J. Chem. Phys.*, 143:084107, 2015. \n", "[38] J. de Graaf, T. Peter, L.P. Fischer, and C. Holm. The raspberry model for hydrodynamic interactions revisited. II. The effect of confinement. *J. Chem. Phys.*, 143:084108, 2015. \n", - "[39] Joost de Graaf, Arnold JTM Mathijssen, Marc Fabritius, Henri Menke, Christian Holm, and Tyler N Shendruk. Understanding the onset of oscillatory swimming in microchannels. *Soft Matter*, 12(21):4704–4708, 2016. \n", - "[40] A. Einstein. Eine neue Bestimmung der Moleküldimension. *Ann. Phys.*, 19:289, 1906. \n", + "[39] J. de Graaf, A. JTM Mathijssen, M. Fabritius, H. Menke, C. Holm, and T. N Shendruk. Understanding the onset of oscillatory swimming in microchannels. *Soft Matter*, 12(21):4704–4708, 2016. \n", + "[40] A. Einstein. Eine neue Bestimmung der Moleküldimension. *Ann. Phys.*, 19:289, 1906. \n", "[42] I. Berdakin, Y. Jeyaram, V.V. Moshchalkov, L. Venken, S. Dierckx, S.J. Vanderleyden, A.V. Silhanek, C.A. Condat, and V.I. Marconi. Influence of swimming strategy on microorganism separation by asymmetric obstacles. *Phys. Rev. E*, 87:052702, 2013. \n", "[43] I. Berdakin, A.V. Silhanek, H.N. Moyano, V.I. Marconi, and C.A. Condat. Quantifying the sorting efficiency of self-propelled run-and-tumble swimmers by geometrical ratchets. *Central Euro. J. Phys.*, 12:1653, 2013. \n", "[44] S.E. Spagnolie and E. Lauga. Hydrodynamics of self-propulsion near a boundary: predictions and accuracy of far-field approximations. *J. Fluid Mech.*, 700:105, 2012. \n", "[45] A. Morozov and D. Marenduzzo. Enhanced diffusion of tracer particles in dilute bacterial suspensions. *Soft Matter*, 10:2748, 2014. \n", - "[46] Andreas Zöttl and Holger Stark. Hydrodynamics determines collective motion and phase behavior of active colloids in quasi-two-dimensional confinement. *Phys. Rev. Lett.*, 112:118101, 2014." + "[46] A. Zöttl and H. Stark. Hydrodynamics determines collective motion and phase behavior of active colloids in quasi-two-dimensional confinement. *Phys. Rev. Lett.*, 112:118101, 2014." ] } ], diff --git a/requirements.txt b/requirements.txt index 82b453882ef..8e2a4f735e9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -18,7 +18,7 @@ traitsui>=4.5.1 requests>=2.18.4 # to post on GitHub as espresso-ci lxml>=4.2.1 # to deploy tutorials # sphinx and its dependencies -sphinx>=1.6.7,!=2.1.0,!=3.0.0 +sphinx>=2.3.0,!=3.0.0 sphinxcontrib-bibtex>=0.3.5 # jupyter dependencies jupyter_contrib_nbextensions==0.5.1 diff --git a/src/python/espressomd/accumulators.py b/src/python/espressomd/accumulators.py index 03552551a09..35be7bba504 100644 --- a/src/python/espressomd/accumulators.py +++ b/src/python/espressomd/accumulators.py @@ -103,93 +103,94 @@ def time_series(self): class Correlator(ScriptInterfaceHelper): """ - Calculates correlations based on results from observables. + Calculates the correlation of two observables :math:`A` and :math:`B`, + or of one observable against itself (i.e. :math:`B = A`). + The correlation can be compressed using the :ref:`multiple tau correlation + algorithm
`. - Parameters - ---------- - obs1 : :class:`espressomd.observables.Observable` - The observable :math:`A` to be correlated with :math:`B` (``obs2``). - If ``obs2`` is omitted, autocorrelation of ``obs1`` is calculated by - default. + The operation that is performed on :math:`A(t)` and :math:`B(t+\\tau)` + to obtain :math:`C(\\tau)` depends on the ``corr_operation`` argument: - obs2 : :class:`espressomd.observables.Observable`, optional - The observable :math:`B` to be correlated with :math:`A` (``obs1``). + * ``"scalar_product"``: Scalar product of :math:`A` and + :math:`B`, i.e., :math:`C=\\sum\\limits_{i} A_i B_i` - corr_operation : :obj:`str` - The operation that is performed on :math:`A(t)` and - :math:`B(t+\\tau)` to obtain :math:`C(\\tau)`. The - following operations are currently available: + * ``"componentwise_product"``: Componentwise product of + :math:`A` and :math:`B`, i.e., :math:`C_i = A_i B_i` - * ``"scalar_product"``: Scalar product of :math:`A` and - :math:`B`, i.e., :math:`C=\\sum\\limits_{i} A_i B_i` + * ``"square_distance_componentwise"``: Each component of + the correlation vector is the square of the difference + between the corresponding components of the observables, i.e., + :math:`C_i = (A_i-B_i)^2`. Example: when :math:`A` is + :class:`espressomd.observables.ParticlePositions`, it produces the + mean square displacement (for each component separately). - * ``"componentwise_product"``: Componentwise product of - :math:`A` and :math:`B`, i.e., :math:`C_i = A_i B_i` + * ``"tensor_product"``: Tensor product of :math:`A` and + :math:`B`, i.e., :math:`C_{i \\cdot l_B + j} = A_i B_j` + with :math:`l_B` the length of :math:`B`. - * ``"square_distance_componentwise"``: Each component of - the correlation vector is the square of the difference - between the corresponding components of the observables, i.e., - :math:`C_i = (A_i-B_i)^2`. Example: when :math:`A` is - :class:`espressomd.observables.ParticlePositions`, it produces the - mean square displacement (for each component separately). + * ``"fcs_acf"``: Fluorescence Correlation Spectroscopy (FCS) + autocorrelation function, i.e., - * ``"tensor_product"``: Tensor product of :math:`A` and - :math:`B`, i.e., :math:`C_{i \\cdot l_B + j} = A_i B_j` - with :math:`l_B` the length of :math:`B`. + .. math:: - * ``"fcs_acf"``: Fluorescence Correlation Spectroscopy (FCS) - autocorrelation function, i.e., + G_i(\\tau) = + \\frac{1}{N} \\left< \\exp \\left( + - \\frac{\\Delta x_i^2(\\tau)}{w_x^2} + - \\frac{\\Delta y_i^2(\\tau)}{w_y^2} + - \\frac{\\Delta z_i^2(\\tau)}{w_z^2} + \\right) \\right> - .. math:: + where :math:`N` is the average number of fluorophores in the + illumination area, - G_i(\\tau) = - \\frac{1}{N} \\left< \\exp \\left( - - \\frac{\\Delta x_i^2(\\tau)}{w_x^2} - - \\frac{\\Delta y_i^2(\\tau)}{w_y^2} - - \\frac{\\Delta z_i^2(\\tau)}{w_z^2} - \\right) \\right> + .. math:: - where :math:`N` is the average number of fluorophores in the - illumination area, + \\Delta x_i^2(\\tau) = \\left( x_i(0) - x_i(\\tau) \\right)^2 - .. math:: + is the square displacement of particle + :math:`i` in the :math:`x` direction, and :math:`w_x` + is the beam waist of the intensity profile of the + exciting laser beam, - \\Delta x_i^2(\\tau) = \\left( x_i(0) - x_i(\\tau) \\right)^2 + .. math:: - is the square displacement of particle - :math:`i` in the :math:`x` direction, and :math:`w_x` - is the beam waist of the intensity profile of the - exciting laser beam, + W(x,y,z) = I_0 \\exp + \\left( - \\frac{2x^2}{w_x^2} - \\frac{2y^2}{w_y^2} - + \\frac{2z^2}{w_z^2} \\right). - .. math:: + The values of :math:`w_x`, :math:`w_y`, and :math:`w_z` + are passed to the correlator as ``args``. The correlator calculates - W(x,y,z) = I_0 \\exp - \\left( - \\frac{2x^2}{w_x^2} - \\frac{2y^2}{w_y^2} - - \\frac{2z^2}{w_z^2} \\right). + .. math:: - The values of :math:`w_x`, :math:`w_y`, and :math:`w_z` - are passed to the correlator as ``args``. The correlator calculates + C_i(\\tau) = + \\exp \\left( + - \\frac{\\Delta x_i^2(\\tau)}{w_x^2} + - \\frac{\\Delta y_i^2(\\tau)}{w_y^2} + - \\frac{\\Delta z_i^2(\\tau)}{w_z^2} + \\right) - .. math:: + Per each 3 dimensions of the observable, one dimension of the correlation + output is produced. If ``"fcs_acf"`` is used with other observables than + :class:`espressomd.observables.ParticlePositions`, the physical meaning + of the result is unclear. - C_i(\\tau) = - \\exp \\left( - - \\frac{\\Delta x_i^2(\\tau)}{w_x^2} - - \\frac{\\Delta y_i^2(\\tau)}{w_y^2} - - \\frac{\\Delta z_i^2(\\tau)}{w_z^2} - \\right) + The above equations are a generalization of the formula presented by + Höfling et al. :cite:`hofling11a`. For more information, see references + therein. - Per each 3 dimensions of the - observable, one dimension of the correlation output - is produced. If ``"fcs_acf"`` is used with other observables than - :class:`espressomd.observables.ParticlePositions`, the physical - meaning of the result is unclear. + Parameters + ---------- + obs1 : :class:`espressomd.observables.Observable` + The observable :math:`A` to be correlated with :math:`B` (``obs2``). + If ``obs2`` is omitted, autocorrelation of ``obs1`` is calculated by + default. - The above equations are a - generalization of the formula presented by Hoefling - et. al. :cite:`hofling11a`. For more information, see - references therein. + obs2 : :class:`espressomd.observables.Observable`, optional + The observable :math:`B` to be correlated with :math:`A` (``obs1``). + corr_operation : :obj:`str` + The operation that is performed on :math:`A(t)` and :math:`B(t+\\tau)`. delta_N : :obj:`int` Number of timesteps between subsequent samples for the auto update mechanism. diff --git a/src/python/espressomd/electrostatics.pyx b/src/python/espressomd/electrostatics.pyx index 45a8b4bdcae..02294d261d8 100644 --- a/src/python/espressomd/electrostatics.pyx +++ b/src/python/espressomd/electrostatics.pyx @@ -324,6 +324,8 @@ IF P3M == 1: Defaults to ``True``. timings : :obj:`int` Number of force calculations during tuning. + verbose : :obj:`bool`, optional + If ``False``, disable log output during tuning. check_neutrality : :obj:`bool`, optional Raise a warning if the system is not electrically neutral when set to ``True`` (default). @@ -370,6 +372,8 @@ IF P3M == 1: Defaults to ``True``. timings : :obj:`int` Number of force calculations during tuning. + verbose : :obj:`bool`, optional + If ``False``, disable log output during tuning. check_neutrality : :obj:`bool`, optional Raise a warning if the system is not electrically neutral when set to ``True`` (default).