square_distance_componentwise: Each component of
the correlation vector is the square of the difference
between the corresponding components of the
observables, i.E., \(C_i = (A_i-B_i)^2\). Example:
when \(A\) is ParticlePositions, it produces the
mean square displacement (for each component
separately).

Number of timesteps between subsequent samples for the auto update mechanism.

tau_max :float

This is the maximum value of :math:` au` for which the
correlation should be computed. Warning: Unless you are using
the multiple tau correlator, choosing tau_max of more than
100`dt` will result in a huge computational overhead. In a
multiple tau correlator with reasonable parameters, tau_max
can span the entire simulation without too much additional cpu
time.

tau_lin :int

The number of data-points for which the results are linearly spaced
in tau. This is a parameter of the multiple tau correlator. If you
want to use it, make sure that you know how it works. By default, it
is set equal to tau_max which results in the trivial linear
correlator. By setting tau_lin < tau_max the multiple
tau correlator is switched on. In many cases, tau_lin`=16 is a
good choice but this may strongly depend on the observables you are
correlating. For more information, we recommend to read
Ref. :cite:`ramirez10a or to perform your own tests.

compress1 and compress2 :str

These functions are used to compress the data when
going to the next level of the multiple tau
correlator. This is done by producing one value out of two.
The following compression functions are available:

discard2: (default value) discard the second value from the time series, use the first value as the result

discard1: discard the first value from the time series, use the second value as the result

linear: make a linear combination (average) of the two values

If only compress1 is specified, then
the same compression function is used for both
observables. If both compress1 and compress2 are specified,
then compress1 is used for obs1 and compress2 for obs2.

Both discard1 and discard2 are safe for all
observables but produce poor statistics in the
tail. For some observables, linear compression
can be used which makes an average of two
neighboring values but produces systematic
errors. Depending on the observable, the
systematic error using the linear compression
can be anything between harmless and disastrous.
For more information, we recommend to read Ref.
[RSVL10] or to perform your own tests.

args: float[3]

Three floats which are passed as arguments to the
correlation function. Currently it is only used by
fcs_acf. Other correlation operations will ignore these
values.

Calculates the hydrodynamic mean radius of chains and its standard deviation.

This requires that a set of chains of equal length which start with the
particle with particle number chain_start and are consecutively
numbered (the last particle in that topology has id number :
chain_start`+ `number_of_chains`*`chain_length-1.

Parameters:

chain_start (int.) – The id of the first monomer of the first chain

number_of_chains (int.) – Number of chains contained in the range.

chain_length (int.) – The length of every chain.

Returns:

Where [0] is the mean hydrodynamic radius of the chains
and [1] its standard deviation,

Calculates the distance distribution of particles (probability of
finding a particle of type at a certain distance around a particle of
type , disregarding the fact that a spherical shell of a larger radius
covers a larger volume) The distance is defined as the minimal distance
between a particle of group type_list_a to any of the group
type_list_b. Returns two arrays, the bins and the (normalized)
distribution.

Calculates the instantaneous pressure (in parallel). This is only sensible in an isotropic system which is homogeneous (on average)! Do not use this in an anisotropic or inhomogeneous system. In order to obtain the pressure the ensemble average needs to be calculated.

Returns:

A dictionary with the following keys

* “total”, total pressure

* “kinetic”, kinetic pressure

* “bonded” , total bonded pressure

* “bonded”, bond_type , bonded pressure which arises from the given bond_type

* “nonbonded”, total nonbonded pressure

* “nonbonded”, type_i, type_j, nonbonded pressure which arises from the interactions between type_i and type_j

* “nonbonded_intra”, type_i, type_j, nonbonded pressure between short ranged forces between type i and j and with the same mol_id

* “nonbonded_inter” type_i, type_j”, nonbonded pressure between short ranged forces between type i and j and different mol_ids

* “coulomb”, Coulomb pressure, how it is calculated depends on the method. It is equivalent to 1/3 of the trace of the coulomb stress tensor. For how the stress tensor is calculated see below. The averaged value in an isotropic NVT simulation is equivalent to the average of \(E^{coulomb}/(3V)\), see [BN95].

Calculates the instantaneous stress tensor (in parallel). This is sensible in an anisotropic system. Still it assumes that the system is homogeneous since the volume averaged stress tensor is used. Do not use this stress tensor in an (on average) inhomogeneous system. If the system is (on average inhomogeneous) then use a local stress tensor. In order to obtain the stress tensor the ensemble average needs to be calculated.

Returns:

a dictionary with the following keys

* “total”, total stress tensor

* “kinetic”, kinetic stress tensor

* “bonded” , total bonded stress tensor

* “{bonded, bond_type}” , bonded stress tensor which arises from the given bond_type

* “nonbonded”, total nonbonded stress tensor

* “nonbonded type_i”, type_j, nonbonded stress tensor which arises from the interactions between type_i and type_j

* “nonbonded_intra type_i” type_j, nonbonded stress tensor between short ranged forces between type i and j and with the same mol_id

* “nonbonded_inter type_i”, type_j, nonbonded stress tensor between short ranged forces between type i and j and different mol_ids

* “coulomb”, Maxwell stress tensor, how it is calculated depends on the method

Calculate the structure factor for given types. Returns the
spherically averaged structure factor of particles specified in
types. The structure factor is calculated for all possible wave
vectors q up to order Do not choose parameter order too large
because the number of calculations grows as order to the third power.

Returns an instance of ParticleSlice containing the paritlces in the cluster

size():

Returns the number of particles in the cluster

center_of_mass():

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 particles
\(n\) in spheres of growing radius around the cetner of mass
to \(c*r_g^d\), where \(r_g\) is the radius of gyration of the particles
witin the sphere, and \(d\) is the fractal dimensoin.
dr: Minimum increment for the radius of the spheres.
Return value: (fractal_dimension, mean_square_residual)

Access to individual clusters in the cluster structure either via
cluster[i], wher 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.

Subtracts mass-weighted fraction of the total
force action on all particles of the type from
the particles after each force calculation. This
keeps the center of mass of the type fixed iff
the total momentum of the type is zero.

Parameters:

types (array_like) – List of types of which the center of mass
should be fixed.

A generic tabulated force field that applies a per particle
scaling factor. The forces are calculated numerically from
the data by finite differences. The potential is interpolated
from the provided data.

>>> system.part.add(id=0,pos=[0,0,1.5],type=0,ext_force=[0,0,-.1])>>> # print the particle position as it falls>>> # and print the force it applies on the floor>>> fortinrange(10):>>> system.integrator.run(100)>>> print(system.part[0].pos,floor.total_force())

Adds a Drude particle with specified id, type, and mass to the system.
Checks if different Drude particles have different types.
Collects types/charges/polarizations/Thole factors for intramol. core-Drude short-range exclusion and Thole interaction.

Creates electrostatic short-range exclusion bonds for global exclusion
between Drude particles and core charges and adds the bonds to the cores.
Has to be called once after all Drude particles have been created.

Creates electrostatic short-range exclusion bonds for intramolecular exclusion
between Drude particles and partial charges of the cores. Has to be called once
after all Drude particles have been created.

Sets the global density of a species to a specific value
for which the whole system will have no net charge.

Parameters:

species (integer) – The species which will be changed to neutralize the system.

note (The previous density of the species will be ignored and) – it will be homogeneous distributed over the whole system
The species must be charged to begin with.
If the neutralization would lead to a negative species density
an exception will be raised.

gap_size (float, required) – The gap size gives the height of the empty region between the system box
and the neighboring artificial images. ESPResSo does not
make sure that the gap is actually empty, this is the users
responsibility. The method will compute fine if the condition is not
fulfilled, however, the error bound will not be reached. Therefore you
should really make sure that the gap region is empty (e.g. with wall
constraints).

maxPWerror (float, required) – The maximal pairwise error sets the least upper bound (LUB) error of
the force between any two charges without prefactors (see the papers).
The algorithm tries to find parameters to meet this LUB requirements or
will throw an error if there are none.

delta_mid_top (float, optional) – This parameter sets the dielectric contrast
between the upper boundary and the simulation
box \(\Delta_t\).

delta_mid_bottom (float, optional) – This parameter sets the dielectric contrast
between the lower boundary and the simulation
box \(\Delta_b\).

const_pot (int, optional) – Selector parameter for setting a constant
electric potential between the top and bottom
of the simulation box.

neutralize (int, optional) – By default, ELC just as P3M adds a homogeneous neutralizing background
to the system in case of a net charge. However, unlike in three dimensions,
this background adds a parabolic potential across the
slab [BAC09]. Therefore, under normal circumstance, you will
probably want to disable the neutralization for non-neutral systems.
This corresponds then to a formal regularization of the forces and
energies [BAC09]. Also, if you add neutralizing walls
explicitly as constraints, you have to disable the neutralization.
When using a dielectric contrast or full metallic walls (delta_mid_top
!= 0 or delta_mid_bot != 0 or const_pot_on=1), neutralize is
overwritten and switched off internally. Note that the special case of
non-neutral systems with a non-metallic dielectric jump (eg.
delta_mid_top or delta_mid_bot in ]-1,1[) is not covered by the
algorithm and will throw an error.

dielectric_contrast_on (int, optional) – Selector parameter for setting a dielectric contrast between the
upper simulation boundary and the simulation box, and between the
lower simulation boundary and the simulation box, respectively.

delta_mid_top (float, optional) – If dielectric-contrast mode is selected, then this parameter sets
the dielectric contrast between the upper boundary and the
simulation box \(\Delta_t\).

delta_mid_bottom (float, optional) – If dielectric-contrast mode is selected, then this parameter sets
the dielectric contrast between the lower boundary and the
simulation box \(\Delta_b\).

const_pot (int, optional) – Selector parameter for setting a constant electric potential
between the top and bottom of the simulation box.

Remove the center of mass velocity of the system. Assumes equal unit
mass if the mass feature is not used. This is often used when switching
from Langevin Dynamics to Lattice Boltzmann. This is due to the random
nature of LD that yield a non-zero net system momentum at any given
time.

Represents an instance of a non-bonded interaction, such as Lennard-Jones
Either called with two particle type id, in which case, the interaction
will represent the bonded interaction as it is defined in Espresso core
Or called with keyword arguments describing a new interaction.

Particle property containing a list of all current bonds help by Particle.

Examples

>>> importespressomd>>> fromespressomd.interactionsimport*>>>>>> system=espressomd.System()>>>>>> # define a harmonic potential and add it to the system>>> harm_bond=HarmonicBond(r_0=1,k=5)>>> system.bonded_inter.add(harm_bond)>>>>>> # add two particles>>> system.part.add(id=0,pos=(1,0,0))>>> system.part.add(id=1,pos=(2,0,0))>>>>>> # bond them via the bond type>>> system.part[0].add_bond((harm_bond,1))>>> # or via the bond index (zero in this case since it is the first one added)>>> system.part[0].add_bond((0,1))

A list of three floats representing the current forces on the Particle

Note

Whereas the velocity is modified with respect to the velocity you set
upon integration, the force it recomputed during the integration step and any
force set in this way is immediatly lost at the next integration step.

List of three floats giving the particle angular
velocity as measured from the lab frame.

Note

This needs the feature ROTATION.

If you set the angular velocity of the particle in the lab
frame, the orientation of the particle
(espressomd.particle_data.ParticleHandle.quat) must be
set before setting omega_lab, otherwise the conversion from
lab to body frame will not be handled properly.

Sets the diagonal elements of this particles rotational inertia
tensor. These correspond with the inertial moments along the
coordinate axes in the particle’s co-rotating coordinate system.
When the particle’s quaternions are set to 1 0 0 0, the co-rotating
and the fixed (lab) frame are co-aligned.

Switches the particle’s rotational degrees of freedom in the Cartesian axes in the body-fixed frame
The content of the torque and omega variables are meaningless, for the co-ordinates for which
rotation is disabled.

This property takes a dictionary with a different number of
entries depending whether there is an implicit fluid (i.e. with the
Langevin thermostat) of an explicit fluid (with LB).

Swimming enables the particle to be self-propelled in the direction determined by its
quaternion. For setting the quaternion of the particle see . The
self-propulsion speed will relax to a constant velocity, that is specified by
v_swim . Alternatively it is possible to achieve a constant velocity by
imposing a constant force term f_swim that is balanced by friction of a
(Langevin) thermostat. The way the velocity of the particle decays to the
constant terminal velocity in either of these methods is completely
determined by the friction coefficient. You may only set one of the
possibilities v_swimorf_swim as you cannot relax to constant force
and constant velocity at the same time. The setting both v_swim and
f_swim to 0.0 thus disables swimming. This option applies to all
non-lattice-Boltzmann thermostats. Note that there is no real difference
between v_swim and f_swim since the latter may aways be chosen such that
the same terminal velocity is achieved for a given friction coefficient.

Parameters:

'f_swim' (float) – Achieve a constant velocity by imposing a constant
force term ‘f_swim’ that is balanced by friction of a
(Langevin) thermostat. This exludes the option
‘v_swim’.

'mode' (string, 'pusher' or 'puller' (initially 'N/A')) – The LB flow field can be generated by a pushing or a
pulling mechanism, leading to change in the sign of the
dipolar flow field with respect to the direction of
motion.

'dipole_length' (float) – This determines the distance of the source of
propulsion from the particle’s center.

'rotational_friction' (float) – This key can be used to set the friction that causes
the orientation of the particle to change in shear
flow. The torque on the particle is determined by
taking the cross product of the difference between the
fluid velocity at the center of the particle and at
the source point and the vector connecting the center
and source.

Notes

This needs the feature ENGINE. The keys ‘mode’,
‘dipole_length’, and ‘rotational_friction’ are only
available if ENGINE is used with LB or LB_GPU.

Allows for manual access to the attributes of virtual sites in the “relative”
implementation. PID denotes the id of the particle to which this virtual site
is related and distance the distance between non-virtual and virtual particle.
The relative orientation is specified as a quaternion of 4 floats.

A list of three floats representing the current forces on the Particle

Note

Whereas the velocity is modified with respect to the velocity you set
upon integration, the force it recomputed during the integration step and any
force set in this way is immediatly lost at the next integration step.

List of three floats giving the particle angular
velocity as measured from the lab frame.

Note

This needs the feature ROTATION.

If you set the angular velocity of the particle in the lab
frame, the orientation of the particle
(espressomd.particle_data.ParticleHandle.quat) must be
set before setting omega_lab, otherwise the conversion from
lab to body frame will not be handled properly.

Sets the diagonal elements of this particles rotational inertia
tensor. These correspond with the inertial moments along the
coordinate axes in the particle’s co-rotating coordinate system.
When the particle’s quaternions are set to 1 0 0 0, the co-rotating
and the fixed (lab) frame are co-aligned.

Switches the particle’s rotational degrees of freedom in the Cartesian axes in the body-fixed frame
The content of the torque and omega variables are meaningless, for the co-ordinates for which
rotation is disabled.

This property takes a dictionary with a different number of
entries depending whether there is an implicit fluid (i.e. with the
Langevin thermostat) of an explicit fluid (with LB).

Swimming enables the particle to be self-propelled in the direction determined by its
quaternion. For setting the quaternion of the particle see . The
self-propulsion speed will relax to a constant velocity, that is specified by
v_swim . Alternatively it is possible to achieve a constant velocity by
imposing a constant force term f_swim that is balanced by friction of a
(Langevin) thermostat. The way the velocity of the particle decays to the
constant terminal velocity in either of these methods is completely
determined by the friction coefficient. You may only set one of the
possibilities v_swimorf_swim as you cannot relax to constant force
and constant velocity at the same time. The setting both v_swim and
f_swim to 0.0 thus disables swimming. This option applies to all
non-lattice-Boltzmann thermostats. Note that there is no real difference
between v_swim and f_swim since the latter may aways be chosen such that
the same terminal velocity is achieved for a given friction coefficient.

Parameters:

'f_swim' (float) – Achieve a constant velocity by imposing a constant
force term ‘f_swim’ that is balanced by friction of a
(Langevin) thermostat. This exludes the option
‘v_swim’.

'mode' (string, 'pusher' or 'puller' (initially 'N/A')) – The LB flow field can be generated by a pushing or a
pulling mechanism, leading to change in the sign of the
dipolar flow field with respect to the direction of
motion.

'dipole_length' (float) – This determines the distance of the source of
propulsion from the particle’s center.

'rotational_friction' (float) – This key can be used to set the friction that causes
the orientation of the particle to change in shear
flow. The torque on the particle is determined by
taking the cross product of the difference between the
fluid velocity at the center of the particle and at
the source point and the vector connecting the center
and source.

Notes

This needs the feature ENGINE. The keys ‘mode’,
‘dipole_length’, and ‘rotational_friction’ are only
available if ENGINE is used with LB or LB_GPU.

Allows for manual access to the attributes of virtual sites in the “relative”
implementation. PID denotes the id of the particle to which this virtual site
is related and distance the distance between non-virtual and virtual particle.
The relative orientation is specified as a quaternion of 4 floats.

Note that a the first monomer of a polymer is always assigned the type type_poly_charge.
The next charge_distance monomers have type type_poly_neutral.
This process repeats until all monomers are placed.
Afterwards, all monomers of type type_poly_charge are assigned the charge val_poly.
Thus the following example creates a single uncharged polymer where all monomers are of type=0:

This class provides the base class for Reaction Algorithms like the Reaction Ensemble algorithm, the Wang-Landau
Reaction Ensemble algorithm and the constant pH method. Initialize the
reaction algorithm by setting the standard pressure, temperature, and the
exclusion radius.

Note: When creating particles the velocities of the new particles are set
according the Maxwell-Boltzmann distribution. In this step the mass of the
new particle is assumed to equal 1.

Parameters:

temperature (float) – The temperature at which the reaction is performed.

exclusion_radius (float) – Minimal distance from any particle, within which new
particle will not be inserted. This is useful to avoid
integrator failures if particles are too close and there
is a diverging repulsive interaction, or to prevent two
oppositely charged particles from being placed on top of
each other. The Boltzmann factor \(\exp(-\beta
E)\) gives these configurations a small contribution to
the partition function, therefore they can be neglected.

Deletes the particle of the given p_id and makes sure that the particle
range has no holes. This function has some restrictions, as e.g. bonds
are not deleted. Therefore only apply this function to simple ions.

Performs a displacement Monte Carlo move for particles of given type. New positions
of the displaced particles are chosen from the whole box with a uniform probability distribution.
If there are multiple types, that are being moved in a simulation, they should be moved in a
random order to avoid artefacts.

Sets the particle type for non-interacting particles.
Default value: 100.
This is used to temporarily hide
particles during a reaction trial move, if they are to be deleted after
the move is accepted.
Please change this value if you intend to use the type 100 for some other
particle types with interactions. Please also note that particles in the current
implementation of the Reaction Ensemble are only hidden with respect to
Lennard-Jones and Coulomb interactions. Hiding of other interactions,
for example a magnetic, needs to be implemented in the code.

Set the volume to be used in the acceptance probability of the reaction
ensemble. This can be useful when using constraints, if the relevant
volume is different from the box volume. If not used the default volume
which is used, is the box volume.

Adds the potential energy as a collective variable (reaction coordinate) for the Wang-Landau Reaction Ensemble.
Several collective variables can be set simultaneously.

Parameters:

filename (str) – Filename of the energy boundary file which provides the
potential energy boundaries (min E_pot, max E_pot) tabulated
for all degrees of association. Make sure to only list the
degrees of association which are used by the degree of
association collective variable within this file. The energy
boundary file can be created in a preliminary energy run. By
the help of the functions
update_maximum_and_minimum_energies_at_current_state()
and write_out_preliminary_energy_run_results(). This
file has to be obtained before being able to run a
simulation with the energy as collective variable.

delta (float) – Provides the discretization of the potential energy range. Only
for small enough delta the results of the energy reweighted
averages are correct. If delta is chosen too big there are
discretization errors in the numerical integration which occurs
during the energy reweighting process.

Performs an MC (Monte Carlo) move for particle_number_to_be_changed particle of type type_mc. Positions for the particles are drawn uniformly random within the box. The command takes into account the Wang-Landau terms in the acceptance probability.
If there are multiple types, that
need to be moved, make sure to move them in a random order to avoid
artefacts. For the Wang-Landau algorithm in the case of energy reweighting you would also need to move the monomers of the polymer with special moves for the MC part. Those polymer configuration changing moves need to be implemented in the case of using Wang-Landau with energy reweighting and a polymer in the system. Polymer configuration changing moves had been implemented before but were removed from espresso.

Performs reaction_steps reactions. Sets the number of reaction steps which are
performed at once. Do not use too many reaction steps
steps consecutively without having conformation
changing steps in between (especially important for the Wang-Landau reaction ensemble). Providing a number for the parameter reaction steps reduces the need for the interpreter to be
called between consecutive reactions.

final_wang_landau_parameter (float) – Sets the final Wang-Landau parameter, which is the Wang-Landau parameter after which the simulation should stop.).

full_path_to_output_filename (str) – Sets the path to the output file of the
Wang-Landau algorithm which contains the
Wang-Landau potential

do_not_sample_reaction_partition_function (bool) – Avoids sampling the
Reaction ensemble partition
function in the Wang-Landau
algorithm. Therefore this
option makes all degrees of
association equally
probable. This option may
be used in the sweeping
mode of the reaction
ensemble, since the
reaction ensemble partition
function can be later added
analytically.

Records the minimum and maximum potential energy as a function of the
degree of association in a preliminary Wang-Landau reaction ensemble
simulation where the acceptance probability includes the factor
\(\exp(-\beta \Delta E_{pot})\). The minimal and maximal
potential energies which occur in the system are needed for the energy
reweighting simulations where the factor \(\exp(-\beta \Delta E_{pot})\)
is not included in the acceptance probability in
order to avoid choosing the wrong potential energy boundaries.

Measures the excess chemical potential in a homogeneous system. Returns the excess chemical potential and the standard error for the excess chemical potential. It assumes that your samples are uncorrelated in estimating the standard error.

every attribute has to be declared at the class level.
This means that methods cannot define an attribute by using
self.new_attr=somevalue without declaring it inside this
indentation level, either as method, property or reference.

For using Espresso conveniently for simulations in the grand canonical
ensemble, or other purposes, when particles of certain types are created
and deleted frequently. Particle ids can be stored in lists for each
individual type and so random ids of particles of a certain type can be
drawn. If you want Espresso to keep track of particle ids of a certain type
you have to initialize the method by calling the setup function. After that
Espresso will keep track of particle ids of that type.

gamma (float) – Contains the friction coefficient of the bath. If the feature ‘PARTICLE_ANISOTROPY’
is compiled in then ‘gamma’ can be a list of three positive floats, for the friction
coefficient in each cardinal direction.

gamma_rotation (float, optional) – The same applies to ‘gamma_rotation’, which requires the feature
‘ROTATION’ to work properly. But also accepts three floating point numbers
if ‘PARTICLE_ANISOTROPY’ is also compiled in.

act_on_virtual (bool, optional) – If true the thermostat will act on virtual sites, default is off.

Returns a non-writable numpy.ndarray with a special error message upon usage
of __setitem__ or in-place operators. Cast return in __get__ of array
properties to array_locked to prevent these operations.

ERR_MSG = 'ESPResSo array properties return non-writable arrays and can only be modified as a whole, not in-place or component-wise. Use numpy.copy(<ESPResSo array property>) to get a writable copy.'¶

Checks that x is of type t and that n values are given, otherwise throws
ValueError with the message msg. If x is an array/list/tuple, the type
checking is done on the elements, and all elements are checked. Integers
are accepted when a float was asked for.

This class provides live visualization using Enthought Mayavi. Use the
update method to push your current simulation state after integrating. If
you run your integrate loop in a separate thread, you can call
run_gui_event_loop in your main thread to be able to interact with the GUI.