# espressomd/espresso

Update Sphinx documentation

Fix broken internal and external links, remove documentation of
recently deleted Python samples, cleanup Sphinx syntax, fix typos.
1 parent d25a4c9 commit ea658e1794803a8aba284865baf621661e30010b

Large diffs are not rendered by default.

 @@ -10,7 +10,7 @@ Analysis calculation and data accumulation performed in the core. - :ref:Observables and correlators: This provides a more flexible concept of in-core analysis, where a certain observable (:ref:Available observables), a rule for data accumulation (ref Accumulators) and/or correlation (:ref:Correlations) can be defined. a rule for data accumulation (:ref:Accumulators) and/or correlation (:ref:Correlations) can be defined. .. _Direct analysis routines:
 @@ -462,7 +462,7 @@ Errors Common to all algorithms of the MMM family is that accuracy is cheap with respect to computation time. More precisely, the maximal pairwise error, i.e. the maximal error of the :math:\psi expression, decreases error, i.e. the maximal error of the :math:\psi expression decreases exponentially with the cutoffs. In turn, the computation time grows logarithmically with the accuracy. This is quite in contrast to the Ewald methods, for which decreasing the error bound can lead to @@ -481,10 +481,12 @@ additional error source. .. figure:: figures/elc-errordist.pdf :alt: Error distribution of the ELC method. :align: center :height: 6.00000cm Error distribution of the ELC method. Figure [fig:ELC-error] shows the error distribution of the ELC method The figure shows the error distribution of the ELC method for a gap size of :math:10\% of the total system height. For MMM2D and MMM1D the error distribution is less homogeneous, however, also here it is always better to have some extra precision, especially since it is
 @@ -150,7 +150,7 @@ Getting the minimal distance to a constraint Calculates the smallest distance to all interacting constraints that can be repulsive (wall, cylinder, sphere, rhomboid, maze, pore, slitpore). Negative distances mean that the position is pore, slitpore). Negative distances mean that the position is within the area that particles should not access. Helpful to find initial configurations. @@ -455,7 +455,7 @@ Pictured is an example constraint with a Hollowcone shape created with :: system.constraints.add(shape=hollowcone, particle_type=0, penetrable=True) For the shapes wall, sphere, cylinder, rhomboid, maze, For the shapes wall, sphere, cylinder, rhomboid, pore and stomatocyte, constraints are able to be penetrated if penetrable is set to True. Otherwise, when the penetrable option is ignored or is set to False, the constraint cannot be violated, i.e. no @@ -568,17 +568,17 @@ Constant fields ~~~~~~~~~~~~~~~ These are fields that are constant in space or simple linear functions of the position. The available fields are of the position. The available fields are: :class:espressomd.constraints.HomogeneousMagneticField :class:espressomd.constraints.ElectricPlaneWave :class:espressomd.constraints.LinearElectricPotential :class:espressomd.constraints.HomogeneousFlowField :class:espressomd.constraints.Gravity * :class:espressomd.constraints.HomogeneousMagneticField * :class:espressomd.constraints.ElectricPlaneWave * :class:espressomd.constraints.LinearElectricPotential * :class:espressomd.constraints.HomogeneousFlowField * :class:espressomd.constraints.Gravity a detailed description can be found in the class documentation. A detailed description can be found in the class documentation. please be aware of the fact that a constant per particle force can be Please be aware of the fact that a constant per-particle force can be set via the ext_force property of the particles and is not provided here. @@ -591,8 +591,8 @@ which has to be provided by the user. The fields differ by how they couple to particles, for a detailed description see their respective class documentation. :class:espressomd.constraints.ForceField :class:espressomd.constraints.PotentialField :class:espressomd.constraints.ElectricPotential :class:espressomd.constraints.FlowField * :class:espressomd.constraints.ForceField * :class:espressomd.constraints.PotentialField * :class:espressomd.constraints.ElectricPotential * :class:espressomd.constraints.FlowField
 @@ -66,7 +66,7 @@ installed on your system. In |es|, you can check if it is compiled in by checking for the feature FFTW with espressomd.features. P3M requires full periodicity (1 1 1). Make sure that you know the relevance of the P3M parameters before using P3M! If you are not sure, read the following references references: :cite:ewald21,hockney88,kolafa92,deserno98a,deserno98b,deserno00,deserno00a,cerda08d. .. _Tuning Coulomb P3M: @@ -81,11 +81,12 @@ This can be useful to speed up the tuning during testing or if the parameters are already known. To prevent the automatic tuning, set the tune parameter to False. To manually tune or retune P3M, call :meth:espresso.electrostatics.P3M.Tune. To manually tune or retune P3M, call :meth:espressomd.electrostatics.P3M.tune . Note, however, that this is a method the P3M object inherited from :attr:espressomd.electrostatics.ElectrostaticInteraction. All parameters passed to the method are fixed in the tuning routine. If not specified in the Tune() method, the parameters prefactor and specified in the tune() method, the parameters prefactor and accuracy are reused. It is not easy to calculate the various parameters of the P3M method @@ -127,7 +128,8 @@ It uses the same parameters and interface functionality as the CPU version of the solver. It should be noted that this does not always provide significant increase in performance. Furthermore it computes the far field interactions with only single precision which limits the maximum precision. The algorithm does not work in combination with the electrostatic extensions :ref:Dielectric interfaces with the ICC algorithm does not work in combination with the electrostatic extensions :ref:Dielectric interfaces with the ICC* algorithm  and :ref:Electrostatic Layer Correction (ELC). .. _Debye-Hückel potential: @@ -265,7 +267,7 @@ MMM2D MMM2D is an electrostatics solver for explicit 2D periodic systems. It can account for different dielectric jumps on both sides of the non-periodic direction. MMM2D Coulomb method needs periodicity 1 1 0 and the non-periodic direction. MMM2D Coulomb method needs periodicity (1 1 0) and the layered cell system. The performance of the method depends on the number of slices of the cell system, which has to be tuned manually. It is automatically ensured that the maximal pairwise error is smaller than @@ -332,7 +334,7 @@ method in computational order N. Currently, it only supports P3M. This means, that you will first have to set up the P3M algorithm before using ELC. The algorithm is definitely faster than MMM2D for larger numbers of particles (:math:>400 at reasonable accuracy requirements). The periodicity has to be set to 1 1 1 still, *ELC* cancels the electrostatic contribution of the set to (1 1 1) still, *ELC* cancels the electrostatic contribution of the periodic replica in **z-direction**. Make sure that you read the papers on ELC (:cite:arnold02c,arnold02d,tyagi08a) before using it. ELC is an |es| actor and is used with:: @@ -366,15 +368,15 @@ Parameters are: forces/energies in *ELC* and is therefore only possible with the const_pot option. * const_pot: As described, setting this to 1 leads to fully metallic boundaries and As described, setting this to True leads to fully metallic boundaries and behaves just like the mmm2d parameter of the same name: It maintains a constant potential pot_diff by countering the total dipole moment of the system and adding a homogeneous electric field according to pot_diff. * pot_diff: Used in conjunction with const_pot set to 1, this sets the potential difference between the boundaries in the z-direction between z=0 and z = box_l[2] - gap_size. Used in conjunction with const_pot set to True, this sets the potential difference between the boundaries in the z-direction between z=0 and z = box_l[2] - gap_size. * far_cut: The setting of the far cutoff is only intended for testing and allows to directly set the cutoff. In this case, the maximal pairwise error is @@ -423,7 +425,7 @@ parameters. mmm1d = MMM1D(prefactor=C, maxPWerror=err) where the prefactor :math:C is defined in Eqn. :eq:coulomb_prefactor. MMM1D Coulomb method for systems with periodicity 0 0 1. Needs the MMM1D Coulomb method for systems with periodicity (0 0 1). Needs the nsquared cell system (see section :ref:Cellsystems). The first form sets parameters manually. The switch radius determines at which xy-distance the force calculation switches from the near to the far formula. The Bessel cutoff
 @@ -150,7 +150,7 @@ A pairwise Coulomb interaction can be instantiated via This creates a bond with a Coulomb pair potential between particles 0 and 1. It is given by .. math:: V(r) = \frac{\alpha q_1 q_2}{r}, .. math:: V(r) = \alpha \frac{q_1 q_2}{r}, where :math:q_1 and :math:q_2 are the charges of the bound particles and :math:\alpha is the Coulomb prefactor. This interaction has no cutoff and acts independently of other @@ -451,8 +451,11 @@ For details of the interpolation, see :ref:Tabulated interaction. Object-in-fluid interactions ---------------------------- Please cite :cite:Cimrak2014 when using the interactions in this section in order to simulate extended objects embedded in a LB fluid. For more details we encourage the dedicated OIF documentation available at http://cell-in-fluid.fri.uniza.sk/en/content/oif-espresso. Please cite :cite:Cimrak2014 when using the interactions in this section in order to simulate extended objects embedded in a LB fluid. For more details please consult the dedicated OIF documentation available at http://cell-in-fluid.fri.uniza.sk/en/content/oif-espresso _. The following interactions are implemented in order to mimic the mechanics of elastic or rigid objects immersed in the LB fluid flow.
 @@ -581,7 +581,7 @@ only has an effect if the DPD thermostat is activated. The interaction consists of a friction force :math:\vec{F}_{ij}^{D} and a random force :math:\vec{F}_{ij}^R added to the other interactions between particles :math:i and :math:j. It is decomposed into a component parallel and perpendicular to the distance vector :math:\vec{r}_{ij} of the particle pair . parallel and perpendicular to the distance vector :math:\vec{r}_{ij} of the particle pair. The friction force contributions of the parallel part are .. math:: \vec{F}_{ij}^{D} = -\gamma_\parallel w_\parallel (r_{ij}) (\hat{r}_{ij} \cdot \vec{v}_{ij}) \hat{r}_{ij}
 @@ -312,30 +312,12 @@ or in the git repository
 @@ -125,7 +125,7 @@ details). Currently |es| supports some basic functions for writing simulation data to H5MD files. The implementation is MPI-parallelized and is capable of dealing with varying numbers of particles. To write data in a hdf5-file according to the H5MD proposal (http://nongnu.org/h5md/), first an object of the class To write data in a hdf5-file according to the H5MD proposal (https://nongnu.org/h5md/), first an object of the class :class:espressomd.io.writer.h5md.H5md has to be created and linked to the respective hdf5-file. This may, for example, look like: @@ -178,7 +178,7 @@ call the H5md objects :meth:espressomd.io.writer.h5md.H5md.write method withou After the last write call, you have to call the close() method to remove the backup file and to close the datasets etc. H5MD files can be read and modified with the python module h5py (for documentation see h5py _). For example all positions stored in the file called "h5mdfile.h5" can be read using H5MD files can be read and modified with the python module h5py (for documentation see h5py _). For example all positions stored in the file called "h5mdfile.h5" can be read using .. code:: python @@ -226,7 +226,7 @@ There exists a legacy python script in the :file:tools directory which can con MPI-IO data to the now unsupported blockfile format. Check it out if you want to post-process the data without ESPResSo. *WARNING* Do not attempt to read these binary files on a machine with a different *WARNING*: Do not attempt to read these binary files on a machine with a different architecture! .. _Writing VTF files: @@ -366,7 +366,7 @@ Note that the |es| particles are ordered in increasing order, thus id=3 corr Writing various formats using MDAnalysis ---------------------------------------- If the MDAnalysis package (http://mdanalysis.org) is installed, it If the MDAnalysis package (https://mdanalysis.org) is installed, it is possible to use it to convert frames to any of the supported configuration/trajectory formats, including PDB, GROMACS, GROMOS, CHARMM/NAMD, AMBER, LAMMPS, ...) @@ -396,7 +396,7 @@ using MDAnalysis. A simple example is the following: u.load_new(eos.trajectory) # load the frame to the MDA universe W.write_next_timestep(u.trajectory.ts) # append it to the trajectory For other examples see samples/python/MDAnalysisIntegration.py For other examples, see :file:/samples/MDAnalysisIntegration.py .. _Parsing PDB Files:
 @@ -148,8 +148,7 @@ one of:: lb.set_interpolation_order('quadratic') A note on boundaries: Both interpolation schemes don't take into account the physical location of the boundaries both interpolation schemes don't take into account the physical location of the boundaries (e.g. in the middle between two nodes for a planar wall) but will use the boundary node slip velocity at the node position. This means that every interpolation involving at least one boundary node will introduce an error. @@ -392,7 +391,7 @@ Intersecting boundaries are in principle possible but must be treated with care. In the current implementation, all nodes that are within at least one boundary are treated as boundary nodes. Currently, only the so called "link-bounce-back" algorithm for wall Currently, only the so-called "link-bounce-back" algorithm for wall nodes is available. This creates a boundary that is located approximately midway between the lattice nodes, so in the above example wall[0] corresponds to a boundary at :math:x=1.5. Note that the
 @@ -75,7 +75,7 @@ It is based on :cite:brodka04a and the dipolar version of Usage notes: * The non-periodic direction is always the z-direction. * The non-periodic direction is always the **z-direction**. * The method relies on a slab of the simulation box perpendicular to the z-direction not to contain particles. The size in z-direction of this slab is controlled by the gap_size parameter. The user has to ensure that no particles enter this region by means of constraints or by fixing the particles' z-coordinate. When there is no empty slab of the specified size, the method will silently produce wrong results.
 @@ -382,9 +382,9 @@ To set up a virtual site, #. Repeat the previous step with more virtual sites, if desired. #. To update the positions of all virtual sites, call #. To update the positions of all virtual sites, call:: system.integrator.run(0,recalc_forces=True) system.integrator.run(0, recalc_forces=True) Please note: @@ -400,8 +400,9 @@ Please note: guaranteed. Always relate a virtual site to a non-virtual particle placed in the center of mass of the rigid arrangement of particles. - In case you know the correct quaternions, you can also setup a virtual site using its :attr:espressomd.particle_data.ParticleHandle.vs_relative and :attr:espressomd.particle_data.ParticleHandle.virtual attributes. - In case you know the correct quaternions, you can also setup a virtual site using its :attr:espressomd.particle_data.ParticleHandle.vs_relative and :attr:espressomd.particle_data.ParticleHandle.virtual attributes. - In a simulation on more than one CPU, the effective cell size needs to be larger than the largest distance between a non-virtual particle