espressomd package¶
Subpackages¶
Submodules¶
espressomd.accumulators module¶

class
espressomd.accumulators.
AutoUpdateAccumulators
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptObjectRegistry
Class for handling the autoupdate of accumulators used by
espressomd.system.System
.

class
espressomd.accumulators.
Correlator
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Calculates correlations based on results from observables.
 Parameters
obs1 (
espressomd.observables.Observable
) – The observable \(A\) to be correlated with \(B\) (obs2
). Ifobs2
is omitted, autocorrelation ofobs1
is calculated by default.obs2 (
espressomd.observables.Observable
, optional) – The observable \(B\) to be correlated with \(A\) (obs1
).corr_operation (
str
) – The operation that is performed on \(A(t)\) and \(B(t+\tau)\) to obtain \(C(\tau)\). The following operations are currently available:"scalar_product"
: Scalar product of \(A\) and \(B\), i.e., \(C=\sum\limits_{i} A_i B_i\)"componentwise_product"
: Componentwise product of \(A\) and \(B\), i.e., \(C_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., \(C_i = (A_iB_i)^2\). Example: when \(A\) isespressomd.observables.ParticlePositions
, it produces the mean square displacement (for each component separately)."tensor_product"
: Tensor product of \(A\) and \(B\), i.e., \(C_{i \cdot l_B + j} = A_i B_j\) with \(l_B\) the length of \(B\)."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>\]where \(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\]is the square displacement of particle \(i\) in the \(x\) direction, and \(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).\]The values of \(w_x\), \(w_y\), and \(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)\]Per each 3 dimensions of the observable, one dimension of the correlation output is produced. If
"fcs_acf"
is used with other observables thanespressomd.observables.ParticlePositions
, the physical meaning of the result is unclear.The above equations are a generalization of the formula presented by Hoefling et. al. [HoflingBF11]. For more information, see references therein.
 delta_N
int
Number of timesteps between subsequent samples for the auto update mechanism.
 tau_max
float
This is the maximum value of \(\tau\) for which the correlation should be computed. Warning: Unless you are using the multiple tau correlator, choosing
tau_max
of more than100 * 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 datapoints 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.tau_lin
must be divisible by 2. By settingtau_lin
such thattau_max >= dt * delta_N * tau_lin
, the multiple tau correlator is used, otherwise the trivial linear correlator is used. By settingtau_lin = 1
, the value will be overridden bytau_lin = ceil(tau_max / (dt * delta_N))
, which will result in either the multiple or linear tau correlator. 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. [RSVL10] or to perform your own tests. compress1
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 bothcompress1
andcompress2
are specified, thencompress1
is used forobs1
andcompress2
forobs2
.Both
discard1
anddiscard2
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. compress2
str
, optional See
compress1
. args:
float
of length 3 Three floats which are passed as arguments to the correlation function. Currently it is only used by
"fcs_acf"
, which will square these values in the core; if you later decide to update these weights withobs.args = [...]
, you’ll have to provide already squared values! Other correlation operations will ignore these values.

result
()[source]¶  Returns
The result of the correlation function as a 2darray. The first column contains the values of the lag time tau. The second column contains the number of values used to perform the averaging of the correlation. Further columns contain the values of the correlation function. The number of these columns is the dimension of the output of the correlation operation.
 Return type
numpy.ndarray

class
espressomd.accumulators.
MeanVarianceCalculator
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Accumulates results from observables.
 Parameters
delta_N (
int
) – Number of timesteps between subsequent samples for the auto update mechanism.

update
()¶ Update the accumulator (get the current values from the observable).

class
espressomd.accumulators.
TimeSeries
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Records results from observables.
 Parameters
delta_N (
int
) – Number of timesteps between subsequent samples for the auto update mechanism.

update
()¶ Update the accumulator (get the current values from the observable).

clear
()¶ Clear the data
espressomd.actors module¶

class
espressomd.actors.
Actor
(*args, **kwargs)¶ Bases:
object
Abstract base class for interactions affecting particles in the system, such as electrostatics, magnetostatics or LB fluids. Derived classes must implement the interface to the relevant core objects and global variables.

active_list
= {'ElectrostaticInteraction': False, 'HydrodynamicInteraction': False, 'MagnetostaticExtension': False, 'MagnetostaticInteraction': False, 'Scafacos': False}¶

class_lookup
(self, cls)¶

default_params
(self)¶ Virtual method.

get_params
(self)¶ Get interaction parameters

is_active
(self)¶

is_valid
(self)¶ Check if the data stored in this instance still matches the corresponding data in the core.

required_keys
(self)¶ Virtual method.

set_params
(self, **p)¶ Update the given parameters.

system
¶ object
 Type
system

valid_keys
(self)¶ Virtual method.

validate_params
(self)¶ Virtual method.

espressomd.analyze module¶

class
espressomd.analyze.
Analysis
(system)¶ Bases:
object

angular_momentum
(self, p_type=None)¶ Calculates the system’s angular momentum with respect to the origin.
Note that virtual sites are not included, as they do not have a meaningful mass.
 Parameters
p_type (
int
) – Particletype
for which to calculate the center of mass. Returns
The center of mass of the system.
 Return type
(3,)
ndarray
offloat

append
(self)¶ Append configuration for averaged analysis.

calc_re
(self, chain_start=None, number_of_chains=None, chain_length=None)¶ Calculates the mean endtoend distance of chains and its standard deviation, as well as mean square endtoend distance of chains and its standard deviation.
This requires that a set of chains of equal length which start with the particle number
chain_start
and are consecutively numbered, the last particle in that topology having id numberchain_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 endtoend distance of chains and [1] its standard deviation, [2] the mean square endtoend distance and [3] its standard deviation.
 Return type
(4,) array_like of
float

calc_rg
(self, chain_start=None, number_of_chains=None, chain_length=None)¶ Calculates the mean radius of gyration of chains and its standard deviation, as well as the mean square radius of gyration of chains and its standard deviation.
This requires that a set of chains of equal length which start with the particle number
chain_start
and are consecutively numbered, the last particle in that topology having id numberchain_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 radius of gyration of the chains and [1] its standard deviation, [2] the mean square radius of gyration and [3] its standard deviation.
 Return type
(4,) array_like of
float

calc_rh
(self, chain_start=None, number_of_chains=None, chain_length=None)¶ 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 number
chain_start
and are consecutively numbered, the last particle in that topology having id numberchain_start + number_of_chains * chain_length  1
. Parameters
chain_start (
int
) – The id of the first monomer of the first chainnumber_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.
 Return type
(2,) array_like of
float

center_of_mass
(self, p_type=None)¶ Calculates the system’s center of mass.
Note that virtual sites are not included, as they do not have a meaningful mass.
 Parameters
p_type (
int
) – Particletype
for which to calculate the center of mass. Returns
The center of mass of the system.
 Return type
array of
float

check_topology
(self, chain_start=None, number_of_chains=None, chain_length=None)¶

cylindrical_average
(self, center=None, axis=None, length=None, radius=None, bins_axial=None, bins_radial=None, types=[ 1])¶ Calculates the particle distribution using cylindrical binning.
 Parameters
center ((3,) array_like of
float
) – Coordinates of the centre of the cylinder.axis ((3,) array_like of
float
) – Axis vectory of the cylinder, does not need to be normalized.length (
float
) – Length of the cylinder.radius (
float
) – Radius of the cylinder.bins_axial (
int
) – Number of axial bins.bins_radial (
int
) – Number of radial bins.types (lists of
int
) – Particletype
 Returns
columns indicate
index_radial
,index_axial
,pos_radial
,pos_axial
,binvolume
,density
,v_radial
,v_axial
,density
,v_radial
andv_axial
. Note that the columnsdensity
,v_radial
andv_axial
appear for each type indicated intypes
, in the same order. Return type
list of lists

dist_to
(self, id=None, pos=None)¶ Calculates the distance to a point or particle.
 Parameters
id (
int
, optional) – Calculate distance to particle withid
id
.pos (array of
float
, optional) – Calculate distance to positionpos
.
 Returns
The calculated distance.
 Return type
float

distribution
(self, type_list_a=None, type_list_b=None, r_min=0.0, r_max=None, r_bins=100, log_flag=0, int_flag=0)¶ Calculates the distance distribution of particles (probability of finding a particle of type A at a certain distance around a particle of type B, 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 grouptype_list_b
. Returns two arrays, the bins and the (normalized) distribution. Parameters
type_list_a (list of
int
) – List of particletype
, only consider distances from these types.type_list_b (list of
int
) – List of particletype
, only consider distances to these types.r_min (
float
) – Minimum distance.r_max (
float
) – Maximum distance.r_bins (
int
) – Number of bins.log_flag (
int
) – When set to 0, the bins are linearly equidistant; when set to 1, the bins are logarithmically equidistant.int_flag (
int
) – When set to 1, the result is an integrated distribution.
 Returns
Where [0] contains the midpoints of the bins, and [1] contains the values of the rdf.
 Return type
ndarray

dpd_stress
(self)¶

energy
(self)¶ Calculate the systems energy.
 Returns
A dictionary with keys
total
,kinetic
,bonded
,nonbonded
,coulomb
,external_fields
. Return type
dict
Examples
>>> energy = system.analysis.energy() >>> print(energy["total"]) >>> print(energy["kinetic"]) >>> print(energy["bonded"]) >>> print(energy["non_bonded"]) >>> print(energy["external_fields"])

gyration_tensor
(self, p_type=None)¶ Analyze the gyration tensor of particles of a given type or of all particles in the system if no type is given.
 Parameters
p_type (list of
int
, optional) – A particletype
, or list of all particle types to be considered. Returns
A dictionary with the following keys:
"Rg^2"
: squared radius of gyration"shape"
: three shape descriptors (asphericity, acylindricity, and relative shape anisotropy)"eva0"
: eigenvalue 0 of the gyration tensor and its corresponding eigenvector."eva1"
: eigenvalue 1 of the gyration tensor and its corresponding eigenvector."eva2"
: eigenvalue 2 of the gyration tensor and its corresponding eigenvector.
The eigenvalues are sorted in descending order.
 Return type
dict

linear_momentum
(self, include_particles=True, include_lbfluid=True)¶ Calculates the system’s linear momentum.
 Parameters
include_particles (
bool
, optional) – whether to include the particles contribution to the linear momentum.include_lbfluid (
bool
, optional) – whether to include the latticeBoltzmann fluid contribution to the linear momentum.
 Returns
The linear momentum of the system.
 Return type
float

min_dist
(self, p1='default', p2='default')¶ Minimal distance between two sets of particles.
 Parameters
p1, p2 (lists of
int
) – Particletype
in both sets. If both are set to'default'
, the minimum distance of all pairs is returned.

min_dist2
(self, p1, p2)¶ Minimal distance between two threedimensional coordinates p1 and p2.
 Parameters
p1, p2 (arrays of
float
)

moment_of_inertia_matrix
(self, p_type=None)¶ Returns the 3x3 moment of inertia matrix for particles of a given type.
 Parameters
p_type (
int
) – A particletype
 Returns
3x3 moment of inertia matrix.
 Return type
ndarray

nbhood
(self, pos=None, r_catch=None, plane='3d')¶ Get all particles in a defined neighborhood.
 Parameters
pos (array of
float
) – Reference position for the neighborhood.r_catch (
float
) – Radius of the region.plane (
str
, {‘xy’, ‘xz’, ‘yz’}) – If given,r_catch
is the distance to the respective plane.
 Returns
The neighbouring particle ids.
 Return type
array of
int

pressure
(self, v_comp=False)¶ 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]."dipolar"
: TODO"virtual_sites"
: Stress contribution due to virtual sites
 Return type
dict

rdf
(self, rdf_type=None, type_list_a=None, type_list_b=None, r_min=0.0, r_max=None, r_bins=100, n_conf=None)¶ Calculate a radial distribution function. The result is normalized by the spherical bin shell, the total number of particle pairs and the system volume.
 Parameters
rdf_type (
str
, {‘rdf’, ‘<rdf>’}) – Type of analysis.type_list_a (lists of
int
) – Lefttype
of the rdf.type_list_b (lists of
int
, optional) – Righttype
of the rdf.r_min (
float
) – Minimal distance to consider.r_max (
float
) – Maximal distance to consider.r_bins (
int
) – Number of bins.n_conf (
int
, optional) – Ifrdf_type
is'<rdf>'
this determines the number of stored configs that are used (ifNone
, all configurations are used).
 Returns
Where [0] contains the midpoints of the bins, and [1] contains the values of the rdf.
 Return type
ndarray

stress_tensor
(self, v_comp=False)¶ 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"dipolar"
: TODO"virtual_sites"
: Stress tensor contribution for virtual sites
 Return type
dict

structure_factor
(self, sf_types=None, sf_order=None)¶ Calculate the structure factor for given types. Returns the spherically averaged structure factor of particles specified in
sf_types
. The structure factor is calculated for all possible wave vectors q up tosf_order
. Do not choose parametersf_order
too large because the number of calculations grows assf_order
to the third power. Parameters
sf_types (list of
int
) – Specifies which particletype
should be considered.sf_order (
int
) – Specifies the maximum wavevector.
 Returns
Where [0] contains q and [1] contains the structure factor s(q)
 Return type
ndarray

v_kappa
(self, mode=None, Vk1=None, Vk2=None, avk=None)¶ Todo
Looks to be incomplete
Calculates the compressibility through volume fluctuations.
 Parameters
mode (
str
, {‘read’, ‘set’ or ‘reset’}) – Mode.Vk1 (
float
) – Volume.Vk2 (
float
) – Volume squared.avk (
float
) – Number of averages.

espressomd.cellsystem module¶

class
espressomd.cellsystem.
CellSystem
¶ Bases:
object

get_pairs_
(self, distance)¶

get_state
(self)¶

max_num_cells
¶ Maximum number for the cells.

min_num_cells
¶ Minimal number of the cells.

node_grid
¶ Node grid.

resort
(self, global_flag=True)¶ Resort the particles in the cellsystem. Returns the particle numbers on the nodes after the resort.
 Parameters
global_flag (
bool
) – If true, a global resorting is done, otherwise particles are only exchanged between neighboring nodes.

set_domain_decomposition
(self, use_verlet_lists=True, fully_connected=[False, False, False])¶ Activates domain decomposition cell system.
 Parameters
use_verlet_lists (
bool
, optional) – Activates or deactivates the usage of Verlet lists in the algorithm.

set_layered
(self, n_layers=None, use_verlet_lists=True)¶ Activates the layered cell system.
 Parameters
n_layers (
int
, optional, positive) – Sets the number of layers in the zdirection.use_verlet_lists (
bool
, optional) – Activates or deactivates the usage of the Verlet lists for this algorithm.

set_n_square
(self, use_verlet_lists=True)¶ Activates the nsquare force calculation.
 Parameters
use_verlet_lists (
bool
, optional) – Activates or deactivates the usage of the Verlet lists for this algorithm.

skin
¶ Value of the skin layer expects a floating point number.
Note
Mandatory to set.

tune_skin
(self, min_skin=None, max_skin=None, tol=None, int_steps=None, adjust_max_skin=False)¶ Tunes the skin by measuring the integration time and bisecting over the given range of skins. The best skin is set in the simulation core.
 Parameters
min_skin (
float
) – Minimum skin to test.max_skin (
float
) – Maximum skin.tol (
float
) – Accuracy in skin to tune to.int_steps (
int
) – Integration steps to time.adjust_max_skin (
bool
, optional) – IfTrue
, the value ofmax_skin
is reduced to the maximum permissible skin (in case the passed value is too large). Set toFalse
by default.
 Returns
The
skin
 Return type
float

espressomd.checkpointing module¶

class
espressomd.checkpointing.
Checkpoint
(checkpoint_id=None, checkpoint_path='.')[source]¶ Bases:
object
Checkpoint handling (reading and writing).
 Parameters
checkpoint_id (
str
) – A string identifying a specific checkpoint.checkpoint_path (
str
, optional) – Path for reading and writing the checkpoint. If not given, the CWD is used.

get_last_checkpoint_index
()[source]¶ Returns the last index of the given checkpoint id. Will raise exception if no checkpoints are found.

get_registered_objects
()[source]¶ Returns a list of all object names that are registered for checkpointing.

has_checkpoints
()[source]¶ Check for checkpoints.
 Returns
True
if any checkpoints exist that matchcheckpoint_id
andcheckpoint_path
otherwiseFalse
. Return type
bool

load
(checkpoint_index=None)[source]¶ Loads the python objects using (c)Pickle and sets them in the calling module.
 Parameters
checkpoint_index (
int
, optional) – If not given, the lastcheckpoint_index
will be used.

read_signals
()[source]¶ Reads all registered signals from the signal file and returns a list of integers.

register
(*args)[source]¶ Register python objects for checkpointing.
 Parameters
args (list of
str
) – Names of python objects to be registered for checkpointing.

register_signal
(signum=None)[source]¶ Register a signal that will trigger the signal handler.
 Parameters
signum (
int
) – Signal to be registered.
espressomd.cluster_analysis module¶

class
espressomd.cluster_analysis.
Cluster
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Class representing a cluster of particles.

particle_ids
()¶ Returns list of particle ids 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 center of mass to \(c*r_g^d\), where \(r_g\) is the radius of gyration of the particles within the sphere, and \(d\) is the fractal dimension.
Note
Requires
GSL
external feature, enabled withDWITH_GSL=ON
. Parameters
dr (
float
) – Minimum increment for the radius of the spheres. Returns
Fractal dimension and mean square residual.
 Return type
tuple


class
espressomd.cluster_analysis.
ClusterStructure
(*args, **kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Cluster structure of a simulation system, and access to cluster analysis
 Parameters
pair_criterion (
espressomd.pair_criteria._PairCriterion
) – Criterion to decide whether two particles are neighbors.

cid_for_particle
(p)[source]¶ Returns cluster id for the particle.
 Parameters
p (
espressomd.particle_data.ParticleHandle
orint
containing the particle id) – Particle.

property
clusters
¶ Gives access to the clusters in the cluster structure via an instance of
Clusters
.

class
espressomd.cluster_analysis.
Clusters
(cluster_structure)[source]¶ Bases:
object
Access to the clusters in the cluster structure.
Access is as follows:
number of clusters:
len(clusters)
access a cluster via its id:
clusters[id]
iterate over clusters:
for c in clusters:
where
c
will be a tuple containing the cluster id and the cluster object.
espressomd.collision_detection module¶

class
espressomd.collision_detection.
CollisionDetection
(*args, **kwargs)¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Interface to the collision detection / dynamic binding.
See Creating bonds when particles collide for detailed instructions.
This class should not be instantiated by the user. Instead, use the
espressomd.system.System.collision_detection
attribute of the system class to access the collision detection.Use
espressomd.collision_detection.CollisionDetection.set_params()
to change the parameters of the collision detection.
get_parameter
(self, name)¶ Gets a single parameter from the collision detection.

get_params
(self)¶ Returns the parameters of the collision detection as dict.

set_params
(self, **kwargs)¶ Set the parameters for the collision detection
See Creating bonds when particles collide for detailed instructions.
 Parameters
mode (
str
, {“off”, “bind_centers”, “bind_at_point_of_collision”, “bind_three_particles”, “glue_to_surface”}) – Collision detection modedistance (
float
) – Distance below which a pair of particles is considered in the collision detectionbond_centers (
espressomd.interactions.BondedInteraction
) – Bond to add between the colliding particlesbond_vs (
espressomd.interactions.BondedInteraction
) – Bond to add between virtual sites (for modes using virtual sites)part_type_vs (
int
) – Particle type of the virtual sites being created on collision (virtual sites based modes)part_type_to_be_glued (
int
) – particle type for"glue_to_surface"
mode. See user guide.part_type_to_attach_vs_to (
int
) – particle type for"glue_to_surface"
mode. See user guide.part_type_after_glueing (
int
) – particle type for"glue_to_surface"
mode. See user guide.distance_glued_particle_to_vs (
float
) – Distance for"glue_to_surface"
mode. See user guide.bond_three_particles (
espressomd.interactions.BondedInteraction
) – First angular bond for the"bind_three_particles"
mode. See user guidethree_particle_binding_angle_resolution (
int
) – Resolution for the angular bonds (mode"bind_three_particles"
). Resolution+1 bonds are needed to accommodate the case of 180 degrees angles

validate
(self)¶ Validates the parameters of the collision detection.
This is called automatically on parameter change

espressomd.comfixed module¶

class
espressomd.comfixed.
ComFixed
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Fix the center of mass of specific types.
Subtracts massweighted 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 for which the center of mass should be fixed.
espressomd.constraints module¶

class
espressomd.constraints.
Constraint
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Base class for constraints. A constraint provides a force and an energy contribution for a single particle.

class
espressomd.constraints.
Constraints
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptObjectRegistry
List of active constraints. Add a
espressomd.constraints.Constraint
to make it active in the system, or remove it to make it inactive.
add
(*args, **kwargs)[source]¶ Add a constraint to the list.
 Parameters
constraint (
espressomd.constraints.Constraint
) – Either a constraint object…**kwargs (any) – … or parameters to construct an
espressomd.constraints.ShapeBasedConstraint
 Returns
constraint – The added constraint
 Return type

remove
(constraint)[source]¶ Remove a constraint from the list.
 Parameters
constraint (
espressomd.constraints.Constraint
)


class
espressomd.constraints.
ElectricPlaneWave
(phi=0, **kwargs)[source]¶ Bases:
espressomd.constraints.Constraint
Electric field of the form
\(E = E0 \cdot \sin(k \cdot x + \omega \cdot t + \phi)\)
The resulting force on the particles are then
\(F = q \cdot E\)
where \(q\) is the charge of the particle. This can be used to generate a homogeneous AC field by setting k to zero.
 Parameters
E0 (array_like of
float
) – Amplitude of the electric field.k (array_like of
float
) – Wave vector of the waveomega (
float
) – Frequency of the wavephi (
float
, optional) – Phase shift

property
E0
¶

property
k
¶

property
omega
¶

property
phi
¶

class
espressomd.constraints.
ElectricPotential
(**kwargs)[source]¶ Bases:
espressomd.constraints._Interpolated
Electric potential interpolated from provided data. The electric field E is calculated numerically from the potential, and the resulting force on the particles are
\(F = q \cdot E\)
where \(q\) is the charge of the particle.
 Parameters
field ((M, N, O, 1) array_like of
float
) – Potential on a grid of size (M, N, O)grid_spacing ((3,) array_like of
float
) – Spacing of the grid points.

class
espressomd.constraints.
FlowField
(**kwargs)[source]¶ Bases:
espressomd.constraints._Interpolated
Viscous coupling to a flow field that is interpolated from tabulated data like
\(F = \gamma \cdot \left( u(r)  v \right)\)
where \(v\) is the velocity of the particle.
 Parameters
field ((M, N, O, 3) array_like of
float
) – Field velocity on a grid of size (M, N, O)grid_spacing ((3,) array_like of
float
) – Spacing of the grid points.gamma (
float
) – Coupling constant

class
espressomd.constraints.
ForceField
(**kwargs)[source]¶ Bases:
espressomd.constraints._Interpolated
A generic tabulated force field that applies a perparticle scaling factor.
 Parameters
field ((M, N, O, 3) array_like of
float
) – Forcefield amplitude on a grid of size (M, N, O).grid_spacing ((3,) array_like of
float
) – Spacing of the grid points.default_scale (
float
) – Scaling factor for particles that have no individual scaling factor.particle_scales (array_like of (
int
,float
)) – A list of tuples of ids and scaling factors. For particles in the list the interaction is scaled with their individual scaling factor before it is applied.

class
espressomd.constraints.
Gravity
(**kwargs)[source]¶ Bases:
espressomd.constraints.Constraint
Gravity force
\(F = m \cdot g\)
 Parameters
g ((3,) array_like of
float
) – The gravitational acceleration.

property
g
¶

class
espressomd.constraints.
HomogeneousFlowField
(**kwargs)[source]¶ Bases:
espressomd.constraints.Constraint
Viscous coupling to a flow field that is constant in space with the force
\(F = \gamma \cdot (u  v)\)
where \(v\) is the velocity of the particle.

gamma
¶ Coupling constant
 Type
float

property
u
¶ returns: Field velocity. :rtype: (3,) array_like of
float


class
espressomd.constraints.
HomogeneousMagneticField
(**kwargs)[source]¶ Bases:
espressomd.constraints.Constraint

H
¶ Magnetic field vector. Describes both field direction and strength of the magnetic field (via length of the vector).
 Type
(3,) array_like of
float


class
espressomd.constraints.
LinearElectricPotential
(phi0=0, **kwargs)[source]¶ Bases:
espressomd.constraints.Constraint
Electric potential of the form
\(\phi = E \cdot x + \phi_0\),
resulting in the electric field E everywhere. (E.g. in a plate capacitor). The resulting force on the particles are then
\(F = q \cdot E\)
where \(q\) is the charge of the particle.
 Parameters
E (array_like of
float
) – The electric field.phi0 (
float
) – The potential at the origin

property
E
¶

property
phi0
¶

class
espressomd.constraints.
PotentialField
(**kwargs)[source]¶ Bases:
espressomd.constraints._Interpolated
A generic tabulated force field that applies a perparticle scaling factor. The forces are calculated numerically from the data by finite differences. The potential is interpolated from the provided data.
 Parameters
field ((M, N, O, 1) array_like of
float
) – Potential on a grid of size (M, N, O).grid_spacing ((3,) array_like of
float
) – Spacing of the grid points.default_scale (
float
) – Scaling factor for particles that have no individual scaling factor.particle_scales (array_like (
int
,float
)) – A list of tuples of ids and scaling factors. For particles in the list the interaction is scaled with their individual scaling factor before it is applied.

class
espressomd.constraints.
ShapeBasedConstraint
(**kwargs)[source]¶ Bases:
espressomd.constraints.Constraint

only_positive
¶ Act only in the direction of positive normal, only useful if penetrable is
True
. Type
bool

particle_type
¶ Interaction type of the constraint.
 Type
int

particle_velocity
¶ Interaction velocity of the boundary
 Type
array_like of
float

penetrable
¶ Whether particles are allowed to penetrate the constraint.
 Type
bool

shape
¶ One of the shapes from
espressomd.shapes
See also
espressomd.shapes
shape module that define mathematical surfaces
Examples
>>> import espressomd >>> from espressomd import shapes >>> system = espressomd.System() >>> >>> # create first a shapeobject to define the constraint surface >>> spherical_cavity = shapes.Sphere(center=[5,5,5], radius=5.0, direction=1.0) >>> >>> # now create an unpenetrable shapebased constraint of type 0 >>> spherical_constraint = system.constraints.add(particle_type=0, penetrable=False, shape=spherical_cavity) >>> >>> # place a trapped particle inside this sphere >>> system.part.add(id=0, pos=[5, 5, 5], type=1)

min_dist
()[source]¶ Calculates the minimum distance to all interacting particles.
 Returns
The minimum distance
 Return type
float

total_force
()[source]¶ Get total force acting on this constraint.
Examples
>>> import espressomd >>> from espressomd import shapes >>> system = espressomd.System() >>> >>> system.time_step = 0.01 >>> system.box_l = [50, 50, 50] >>> system.thermostat.set_langevin(kT=0.0, gamma=1.0) >>> system.cell_system.set_n_square(use_verlet_lists=False) >>> system.non_bonded_inter[0, 0].lennard_jones.set_params( ... epsilon=1, sigma=1, ... cutoff=2**(1. / 6), shift="auto") >>> >>> floor = system.constraints.add(shape=shapes.Wall(normal=[0, 0, 1], dist=0.0), ... particle_type=0, penetrable=False, only_positive=False) >>> >>> 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 >>> for t in range(10): ... system.integrator.run(100) ... print(system.part[0].pos, floor.total_force())

espressomd.cuda_init module¶

class
espressomd.cuda_init.
CudaInitHandle
¶ Bases:
object

device
¶ Get device.
 Returns
Id of current set device.
 Return type
int

device_list
¶ List devices.
 Returns
List of available CUDA devices.
 Return type
list


espressomd.cuda_init.
gpu_available
()¶
espressomd.diamond module¶

class
espressomd.diamond.
Diamond
(*args, **kwargs)¶ Bases:
object
Class to create a diamondlike polymer network.
 Parameters
a (
float
) – Size of the unit cell.bond_length (
float
) – Distance between adjacent monomers in the chains.MPC (
int
) – Monomers per chain.cM_dist (
int
, optional) – Distance between charged monomers.N_CI (
int
, optional) – Number of counter ions.val_nodes (
float
, optional) – Charge valency of the 8 node particles (crosslinker).val_cM (
float
, optional) – Valency of the charge bearing monomers.val_CI (
float
, optional) – Valency of the counterions.nonet (
bool
, optional) – False creates network, True does not crosslink the individual polymers.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶
espressomd.drude_helpers module¶

espressomd.drude_helpers.
add_all_thole
(system, verbose=False)[source]¶ Calls
add_thole_pair_damping()
for all necessary combinations to create the interactions. Parameters
system (
espressomd.system.System
)verbose (
bool
) – Turns on verbosity.

espressomd.drude_helpers.
add_drude_particle_to_core
(system, harmonic_bond, thermalized_bond, p_core, id_drude, type_drude, alpha, mass_drude, coulomb_prefactor, thole_damping=2.6, verbose=False)[source]¶ 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 intramolecular coreDrude shortrange exclusion and Thole interaction.
 Parameters
system (
espressomd.system.System
)harmonic_bond (
espressomd.interactions.HarmonicBond
) – Add this harmonic bond to between Drude particle and corethermalized_bond (
espressomd.interactions.ThermalizedBond
) – Add this thermalized_bond to between Drude particle and corep_core (
espressomd.particle_data.ParticleHandle
) – The existing core particleid_drude (
int
) – This method creates the Drude particle and assigns this id.type_drude (
int
) – The type of the newly created Drude particlealpha (
float
) – The polarizability in units of inverse volume. Related to the charge of the Drude particle.mass_drude (
float
) – The mass of the newly created Drude particlecoulomb_prefactor (
float
) – Required to calculate the charge of the Drude particle.thole_damping (
float
) – Thole damping factor of the Drude pair. Comes to effect ifadd_all_thole()
method is used.verbose (
bool
) – Turns on verbosity.

espressomd.drude_helpers.
add_intramol_exclusion_bonds
(system, drude_ids, core_ids, verbose=False)[source]¶ Applies electrostatic shortrange exclusion bonds for the given ids. Has to be applied for all molecules.
 Parameters
system (
espressomd.system.System
)drude_ids – IDs of Drude particles within a molecule.
core_ids – IDs of core particles within a molecule.
verbose (
bool
) – Turns on verbosity.

espressomd.drude_helpers.
add_thole_pair_damping
(system, t1, t2, verbose=False)[source]¶ Calculates mixed Thole factors depending on Thole damping and polarization. Adds nonbonded Thole interactions to the system.
 Parameters
system (
espressomd.system.System
)t1 (
int
) – Type 1t2 (
int
) – Type 2verbose (
bool
) – Turns on verbosity.

espressomd.drude_helpers.
setup_and_add_drude_exclusion_bonds
(system, verbose=False)[source]¶ Creates electrostatic shortrange 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.
 Parameters
system (
espressomd.system.System
)verbose (
bool
) – Turns on verbosity.

espressomd.drude_helpers.
setup_intramol_exclusion_bonds
(system, mol_drude_types, mol_core_types, mol_core_partial_charges, verbose=False)[source]¶ Creates electrostatic shortrange 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.
 Parameters
system (
espressomd.system.System
)mol_drude_types – List of types of Drude particles within the molecule
mol_core_types – List of types of core particles within the molecule
mol_core_partial_charges – List of partial charges of core particles within the molecule
verbose (
bool
) – Turns on verbosity.
espressomd.ekboundaries module¶

class
espressomd.ekboundaries.
EKBoundaries
(**kwargs)[source]¶ Bases:
espressomd.lbboundaries.LBBoundaries
Creates a set of electrokinetics boundaries.

class
espressomd.ekboundaries.
EKBoundary
(**kwargs)[source]¶ Bases:
espressomd.lbboundaries.LBBoundary
Creates a EK boundary.
espressomd.electrokinetics module¶

class
espressomd.electrokinetics.
Electrokinetics
¶ Bases:
espressomd.lb.HydrodynamicInteraction
Creates the electrokinetic method using the GPU unit.

add_boundary
(self, shape)¶

add_reaction
(self, shape)¶

add_species
(self, species)¶ Initializes a new species for the electrokinetic method.
 Parameters
species (
int
) – Species to be initialized.

default_params
(self)¶ Returns the default parameters.

ek_init
(self)¶ Initializes the electrokinetic system. This automatically initializes the latticeBoltzmann method on the GPU.

get_params
(self)¶ Prints out the parameters of the electrokinetic system.

load_checkpoint
(self, path)¶

neutralize_system
(self, species)¶ Sets the global density of a species to a specific value for which the whole system will have no net charge.
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.
 Parameters
species (
int
) – The species which will be changed to neutralize the system.

print_vtk_boundary
(self, path)¶ Writes the boundary information into a vtkfile.
 Parameters
path (
str
) – Path of the .vtk file the boundary is written to.

print_vtk_density
(self, path)¶ Writes the LB density information into a vtkfile.
 Parameters
path (
str
) – Path of the .vtk file the LB density is written to.

print_vtk_lbforce
(self, path)¶ Writes the LB force information into a vtkfile.
 Parameters
path (
str
) – Path of the .vtk file the LB force is written to.

print_vtk_particle_potential
(self, path)¶ Writes the electrostatic particle potential into a vtkfile.
Note
This only works if ‘es_coupling’ is active.
 Parameters
path (
str
) – Path of the .vtk file the electrostatic potential is written to.

print_vtk_potential
(self, path)¶ Writes the electrostatic potential into a vtkfile.
 Parameters
path (
str
) – Path of the .vtk file the electrostatic potential is written to.

print_vtk_velocity
(self, path)¶ Writes the latticeBoltzmann velocity information into a vtkfile.
 Parameters
path (
str
) – Path of the .vtk file the velocity is written to.

required_keys
(self)¶ Returns the necessary options to initialize the electrokinetic method.

save_checkpoint
(self, path)¶

set_density
(self, species=None, density=None, node=None)¶ Sets the density of a species at a specific node. If no node is given the density will be set global for the species.
 Parameters
species (
int
) – species for which the density will apply.density (
float
) – The value to which the density will be set to.node (numpyarray of type
int
of length (3)) – If set the density will be only applied on this specific node.

valid_keys
(self)¶ Returns the valid options used for the electrokinetic method.

validate_params
(self)¶ Checks if the parameters for “stencil” and “fluid_coupling” are valid.


class
espressomd.electrokinetics.
ElectrokineticsRoutines
(key)¶ Bases:
object

potential
¶

pressure
¶

velocity
¶


class
espressomd.electrokinetics.
Species
(**kwargs)¶ Bases:
object
Creates a species object that is passed to the ek instance.

default_params
(self)¶ Returns the default parameters for the species.

get_params
(self)¶ Returns the parameters of the species.

id
= 1¶

print_vtk_density
(self, path)¶ Writes the species density into a vtkfile.
 Parameters
path (
str
) – Path of the .vtk file the species density is written to.

print_vtk_flux
(self, path)¶ Writes the species flux into a vtkfile.
 Parameters
path (
str
) – Path of the .vtk file the species flux is written to.

print_vtk_flux_fluc
(self, path)¶

print_vtk_flux_link
(self, path)¶

py_number_of_species
= 0¶

required_keys
(self)¶ Returns the required keys for the species.

valid_keys
(self)¶ Returns the valid keys for the species.

espressomd.electrostatic_extensions module¶

class
espressomd.electrostatic_extensions.
ELC
¶ Bases:
espressomd.electrostatic_extensions.ElectrostaticExtensions
Electrostatics solver for systems with two periodic dimensions. See Electrostatic Layer Correction (ELC) for more details.
 Parameters
gap_size (
float
, required) – The gap size gives the height \(h\) 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 user’s responsibility. The method will run even 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) – Dielectric contrast \(\Delta_t\) between the upper boundary and the simulation box.delta_mid_bottom (
float
, optional) – Dielectric contrast \(\Delta_b\) between the lower boundary and the simulation box.const_pot (
bool
, optional) – Activate a constant electric potential between the top and bottom of the simulation box.pot_diff (
float
, optional) – Ifconst_pot
is enabled, this parameter controls the applied voltage between the boundaries of the simulation box in the zdirection (at \(z = 0\) and \(z = L_z  h\)).neutralize (
bool
, 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 circumstances, you will probably want to disable the neutralization for nonneutral 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
ordelta_mid_bot != 0
orconst_pot=True
),neutralize
is overwritten and switched off internally. Note that the special case of nonneutral systems with a nonmetallic dielectric jump (e.g.delta_mid_top
ordelta_mid_bot
in]1,1[
) is not covered by the algorithm and will throw an error.far_cut (
float
, optional) – Cutoff radius, use with care, intended for testing purposes. When setting the cutoff directly, the maximal pairwise error is ignored.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatic_extensions.
ElectrostaticExtensions
¶ Bases:
espressomd.actors.Actor

class
espressomd.electrostatic_extensions.
ICC
¶ Bases:
espressomd.electrostatic_extensions.ElectrostaticExtensions
Interface to the induced charge calculation scheme for dielectric interfaces. See Dielectric interfaces with the ICC\star algorithm for more details.
 Parameters
n_icc (
int
) – Total number of ICC Particles.first_id (
int
, optional) – ID of the first ICC Particle.convergence (
float
, optional) – Abort criteria of the iteration. It corresponds to the maximum relative change of any of the interface particle’s charge.relaxation (
float
, optional) – SOR relaxation parameter.ext_field (
float
, optional) – Homogeneous electric field added to the calculation of dielectric boundary forces.max_iterations (
int
, optional) – Maximal number of iterations.eps_out (
float
, optional) – Relative permittivity of the outer region (where the particles are).normals ((
n_icc
, 3) array_likefloat
) – Normal vectors pointing into the outer region.areas ((
n_icc
, ) array_likefloat
) – Areas of the discretized surface.sigmas ((
n_icc
, ) array_likefloat
, optional) – Additional surface charge density in the absence of any charge induction.epsilons ((
n_icc
, ) array_likefloat
, optional) – Dielectric constant associated to the areas.

default_params
(self)¶

last_iterations
(self)¶ Number of iterations needed in last relaxation to reach the convergence criterion.
 Returns
iterations – Number of iterations
 Return type
int

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶
espressomd.electrostatics module¶

class
espressomd.electrostatics.
DH
¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver based on the DebyeHueckel framework. See DebyeHückel potential for more details.
 Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).kappa (
float
) – Inverse Debye screening length.r_cut (
float
) – Cut off radius for this interaction.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatics.
ElectrostaticInteraction
¶ Bases:
espressomd.actors.Actor

tune
(self, **tune_params_subset)¶


class
espressomd.electrostatics.
MMM1D
¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver for systems with one periodic direction. See MMM1D for more details.
 Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).maxWPerror (
float
) – Maximal pairwise error.far_switch_radius (
float
, optional) – Radius where nearfield and farfield calculation are switched.bessel_cutoff (
int
, optional)tune (
bool
, optional) – Specify whether to automatically tune or not. Defaults toTrue
.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatics.
MMM1DGPU
¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver with GPU support for systems with one periodic direction. See MMM1D on GPU for more details.
 Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).maxWPerror (
float
) – Maximal pairwise error.far_switch_radius (
float
, optional) – Radius where nearfield and farfield calculation are switchedbessel_cutoff (
int
, optional)tune (
bool
, optional) – Specify whether to automatically tune or not. Defaults toTrue
.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatics.
MMM2D
¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver for systems with two periodic dimensions. More detail are in the user guide MMM2D theory
 Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).maxWPerror (
float
) – Maximal pairwise error.dielectric (
bool
, optional) – Selector parameter for setting the dielectric constants manually (top, mid, bottom), mutually exclusive with dielectriccontrasttop (
float
, optional) – If dielectric is specified this parameter sets the dielectric constant above the simulation box \(\varepsilon_\mathrm{top}\)mid (
float
, optional) – If dielectric is specified this parameter sets the dielectric constant in the simulation box \(\varepsilon_\mathrm{mid}\).bottom (
float
, optional) – If dielectric is specified this parameter sets the dielectric constant below the simulation box \(\varepsilon_\mathrm{bot}\).dielectric_contrast_on (
bool
, 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 dielectriccontrast 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 dielectriccontrast mode is selected, then this parameter sets the dielectric contrast between the lower boundary and the simulation box \(\Delta_b\).const_pot (
bool
, optional) – Selector parameter for setting a constant electric potential between the top and bottom of the simulation box.pot_diff (
float
, optional) – If const_pot mode is selected this parameter controls the applied voltage.far_cut (
float
, optional) – Cut off radius, use with care, intended for testing purposes.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatics.
P3M
(*args, **kwargs)¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
P3M electrostatics solver.
Particle–Particle–Particle–Mesh (P3M) is a Fourierbased Ewald summation method to calculate potentials in Nbody simulation. See Coulomb P3M for more details.
 Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).accuracy (
float
) – P3M tunes its parameters to provide this target accuracy.alpha (
float
, optional) – The Ewald parameter.cao (
float
, optional) – The chargeassignment order, an integer between 0 and 7.epsilon (
float
orstr
, optional) – A positive number for the dielectric constant of the surrounding medium. Use'metallic'
to set the dielectric constant of the surrounding medium to infinity (default).mesh (
int
or (3,) array_like ofint
, optional) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.r_cut (
float
, optional) – The real space cutoff.tune (
bool
, optional) – Used to activate/deactivate the tuning method on activation. Defaults toTrue
.check_neutrality (
bool
, optional) – Raise a warning if the system is not electrically neutral when set toTrue
(default).

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatics.
P3MGPU
(*args, **kwargs)¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
P3M electrostatics solver with GPU support.
Particle–Particle–Particle–Mesh (P3M) is a Fourierbased Ewald summation method to calculate potentials in Nbody simulation. See Coulomb P3M on GPU for more details.
 Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).accuracy (
float
) – P3M tunes its parameters to provide this target accuracy.alpha (
float
, optional) – The Ewald parameter.cao (
float
, optional) – The chargeassignment order, an integer between 0 and 7.epsilon (
float
orstr
, optional) – A positive number for the dielectric constant of the surrounding medium. Use'metallic'
to set the dielectric constant of the surrounding medium to infinity (default).mesh (
int
or (3,) array_like ofint
, optional) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.r_cut (
float
, optional) – The real space cutofftune (
bool
, optional) – Used to activate/deactivate the tuning method on activation. Defaults toTrue
.check_neutrality (
bool
, optional) – Raise a warning if the system is not electrically neutral when set toTrue
(default).

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatics.
ReactionField
¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver based on the ReactionField framework.
 Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).kappa (
float
) – Inverse Debye screening length.epsilon1 (
float
) – interior dielectric constantepsilon2 (
float
) – exterior dielectric constantr_cut (
float
) – Cut off radius for this interaction.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

class
espressomd.electrostatics.
Scafacos
(*args, **kwargs)¶ Bases:
espressomd.scafacos.ScafacosConnector
,espressomd.electrostatics.ElectrostaticInteraction
Calculate the Coulomb interaction using the ScaFaCoS library. See ScaFaCoS electrostatics for more details.
 Parameters
prefactor (
float
) – Coulomb prefactor as defined in (1).method_name (
str
) – Name of the ScaFaCoS method to use.method_params (
dict
) – Dictionary containing the methodspecific parameters.

default_params
(self)¶

dipolar
= False¶

espressomd.electrostatics.
check_neutrality
(_params)¶
espressomd.galilei module¶

class
espressomd.galilei.
GalileiTransform
¶ Bases:
object

galilei_transform
(self)¶ 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 latticeBoltzmann. This is due to the random nature of LD that yield a nonzero net system momentum at any given time.

kill_particle_forces
(self, torque=False)¶ Set the forces on the particles to zero.
 Parameters
torque (
bool
, optional) – Whether or not to kill the torques on all particles too.

kill_particle_motion
(self, rotation=False)¶ Stop the motion of the particles.
 Parameters
rotation (
bool
, optional) – Whether or not to kill the rotations too.

system_CMS
(self)¶ Calculate the center of mass of the system. Assumes equal unit mass if the mass feature is not used.
 Returns
cms – The of the center of mass position vector.
 Return type
(3,) array_like of
float

system_CMS_velocity
(self)¶ Calculate the center of mass velocity of the system. Assumes equal unit mass if the mass feature is not used.
 Returns
cms_vel – The of the center of mass velocity vector.
 Return type
(3,) array_like of
float

espressomd.globals module¶
espressomd.highlander module¶
espressomd.integrate module¶

class
espressomd.integrate.
Integrator
¶ Bases:
object
Integrator class.
This class interfaces the Velocity Verlet integrator.

get_state
(self)¶ Returns the integrator status.

run
(self, steps=1, recalc_forces=False, reuse_forces=False)¶ Run the integrator.
 Parameters
steps (
int
) – Number of time steps to integrate.recalc_forces (
bool
, optional) – Recalculate the forces regardless of whether they are reusable.reuse_forces (
bool
, optional) – Reuse the forces from previous time step.

set_isotropic_npt
(self, ext_pressure, piston, direction=True, True, True, cubic_box=False)¶ Set the integration method to NPT.
 Parameters
ext_pressure (
float
) – The external pressure.piston (
float
) – The mass of the applied piston.direction ((3,) array_like of
bool
, optional) – Select which dimensions are allowed to fluctuate by assigning them toTrue
.cubic_box (
bool
, optional) – IfTrue
, a cubic box is assumed and the value ofdirection
will be ignored when rescaling the box. This is required e.g. for electrostatics and magnetostatics.

set_nvt
(self)¶ Set the integration method to NVT.

set_steepest_descent
(self, *args, **kwargs)¶ Set parameters for steepest descent.

set_vv
(self)¶ Set the integration method to Velocity Verlet.

espressomd.interactions module¶

class
espressomd.interactions.
AffinityInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶

is_active
(self)¶

required_keys
(self)¶

type_name
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


class
espressomd.interactions.
AngleCosine
¶ Bases:
espressomd.interactions.BondedInteraction
Bondangledependent cosine potential.
 Parameters
phi0 (
float
) – Equilibrium bond angle in radians.bend (
float
) – Magnitude of the bond interaction.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
AngleCossquare
¶ Bases:
espressomd.interactions.BondedInteraction
Bondangledependent cosine squared potential.
 Parameters
phi0 (
float
) – Equilibrium bond angle in radians.bend (
float
) – Magnitude of the bond interaction.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
AngleHarmonic
¶ Bases:
espressomd.interactions.BondedInteraction
Bondangledependent harmonic potential.
 Parameters
phi0 (
float
) – Equilibrium bond angle in radians.bend (
float
) – Magnitude of the bond interaction.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
BMHTFInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the BMHTF interaction.
 Parameters
a (
float
) – Magnitude of exponential part of the interaction.b (
float
) – Exponential factor of the interaction.c (
float
) – Magnitude of the term decaying with the sixth power of r.d (
float
) – Magnitude of the term decaying with the eighth power of r.sig (
float
) – Shift in the exponent.cutoff (
float
) – Cutoff distance of the interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
BondedCoulomb
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Bonded Coulomb bond.
 Parameters
prefactor (
float
) – Coulomb prefactor of the bonded Coulomb interaction.

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶

class
espressomd.interactions.
BondedCoulombSRBond
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Bonded Coulomb short range bond. Calculates the short range part of Coulomb interactions.
 Parameters
q1q2 (
float
) – Charge factor of the involved particle pair. Note the particle charges are used to allow e.g. only partial subtraction of the involved charges.

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶

class
espressomd.interactions.
BondedInteraction
(*args, **kwargs)¶ Bases:
object
Base class for bonded interactions.
Either called with an interaction 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.

is_valid
(self)¶ Check, if the data stored in the instance still matches what is in Espresso.

params
¶

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
BondedInteractionNotDefined
(*args, **kwargs)¶ Bases:
object

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.


class
espressomd.interactions.
BondedInteractions
¶ Bases:
object
Represents the bonded interactions.
Individual interactions can be accessed using
BondedInteractions[i]
, wherei
is the bond id. Will return a bonded interaction frombonded_interaction_classes

add
(self, bonded_ia)¶ Add a bonded IA to the simulation


class
espressomd.interactions.
BuckinghamInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the Buckingham interaction.
 Parameters
a (
float
) – Magnitude of the exponential part of the interaction.b (
float
, optional) – Exponent of the exponential part of the interaction.c (
float
) – Prefactor of term decaying with the sixth power of distance.d (
float
) – Prefactor of term decaying with the fourth power of distance.discont (
float
) – Distance below which the potential is linearly continued.cutoff (
float
) – Cutoff distance of the interaction.shift (
float
, optional) – Constant potential shift.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
DPDInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶

is_active
(self)¶

required_keys
(self)¶

set_params
(self, **kwargs)¶ Set parameters for the DPD interaction.
 Parameters
weight_function (
int
, {0, 1}) – The distance dependence of the parallel part, either 0 (constant) or 1 (linear)gamma (
float
) – Friction coefficient of the parallel partr_cut (
float
) – Cutoff of the parallel parttrans_weight_function (
int
, {0, 1}) – The distance dependence of the orthogonal part, either 0 (constant) or 1 (linear)trans_gamma (
float
) – Friction coefficient of the orthogonal parttrans_r_cut (
float
) – Cutoff of the orthogonal part

type_name
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


class
espressomd.interactions.
Dihedral
¶ Bases:
espressomd.interactions.BondedInteraction
Dihedral potential with phase shift.
 Parameters
mult (
int
) – Multiplicity of the potential (number of minima).bend (
float
) – Bending constant.phase (
float
) – Angle of the first local minimum in radians.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
FeneBond
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
FENE bond.
 Parameters
k (
float
) – Magnitude of the bond interaction.d_r_max (
float
) – Maximum stretch and compression length of the bond.r_0 (
float
, optional) – Equilibrium bond length.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
GaussianInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the Gaussian interaction.
 Parameters
eps (
float
) – Overlap energy epsilon.sig (
float
) – Variance sigma of the Gaussian interaction.cutoff (
float
) – Cutoff distance of the interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
GayBerneInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the GayBerne interaction.
 Parameters
eps (
float
) – Potential well depth.sig (
float
) – Interaction range.cut (
float
) – Cutoff distance of the interaction.k1 (
float
orstr
) – Molecular elongation.k2 (
float
, optional) – Ratio of the potential well depths for the sidebyside and endtoend configurations.mu (
float
, optional) – Adjustable exponent.nu (
float
, optional) – Adjustable exponent.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
GenericLennardJonesInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the generic LennardJones interaction.
 Parameters
epsilon (
float
) – Magnitude of the interaction.sigma (
float
) – Interaction length scale.cutoff (
float
) – Cutoff distance of the interaction.shift (
float
orstr
{‘auto’}) – Constant shift of the potential. If'auto'
, a default value is computed from the other parameters. The LJ potential will be shifted by \(\epsilon\cdot\text{shift}\).offset (
float
) – Offset distance of the interaction.e1 (
int
) – Exponent of the repulsion term.e2 (
int
) – Exponent of the attraction term.b1 (
float
) – Prefactor of the repulsion term.b2 (
float
) – Prefactor of the attraction term.delta (
float
, optional) –LJGEN_SOFTCORE
parameter delta. Allows control over how smoothly the potential drops to zero as lambda approaches zero.lam (
float
, optional) –LJGEN_SOFTCORE
parameter lambda. Tune the strength of the interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.
 Raises
ValueError – If not true.


class
espressomd.interactions.
HarmonicBond
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Harmonic bond.
 Parameters
k (
float
) – Magnitude of the bond interaction.r_0 (
float
) – Equilibrium bond length.r_cut (
float
, optional) – Maximum distance beyond which the bond is considered broken.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
HarmonicDumbbellBond
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Harmonic Dumbbell bond.
 Parameters
k1 (
float
) – Magnitude of the bond interaction.k2 (
float
) – Magnitude of the angular interaction.r_0 (
float
) – Equilibrium bond length.r_cut (
float
, optional) – Maximum distance beyond which the bond is considered broken.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
HatInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶

is_active
(self)¶

required_keys
(self)¶

set_params
(self, **kwargs)¶ Set parameters for the Hat interaction.
 Parameters
F_max (
float
) – Magnitude of the interaction.cutoff (
float
) – Cutoff distance of the interaction.

type_name
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


class
espressomd.interactions.
HertzianInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the Hertzian interaction.
 Parameters
eps (
float
) – Magnitude of the interaction.sig (
float
) – Parameter sigma. Determines the length over which the potential decays.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
IBM_Tribend
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
IBM Tribend bond.
 Parameters
ind1, ind2, ind3, ind4 (
int
) – First, second, third and fourth bonding partner. Used for initializing reference statekb (
float
) – Bending modulusrefShape (
str
, optional, {‘Flat’, ‘Initial’}) – Reference shape, default is'Flat'

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶

class
espressomd.interactions.
IBM_Triel
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
IBM Triel bond.
 Parameters
ind1, ind2, ind3 (
int
) – First, second and third bonding partner. Used for initializing reference statek1 (
float
) – Shear elasticity for Skalak and NeoHookeank2 (
float
) – Area resistance for SkalakmaxDist (
float
) – Gives an error if an edge becomes longer than maxDistelasticLaw (
str
) – Specify NeoHookean or Skalak

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶

class
espressomd.interactions.
IBM_VolCons
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
IBM volume conservation bond.
 Parameters
softID (
int
) – Used to identify the object to which this bond belongs. Each object (cell) needs its own IDkappaV (
float
) – Modulus for volume force

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶

class
espressomd.interactions.
LennardJonesCos2Interaction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶

is_active
(self)¶

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the LennardJones cosine squared interaction.
 Parameters
epsilon (
float
) – Magnitude of the interaction.sigma (
float
) – Interaction length scale.offset (
float
, optional) – Offset distance of the interaction.width (
float
) – Width of interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶


class
espressomd.interactions.
LennardJonesCosInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶

is_active
(self)¶

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the LennardJones cosine interaction.
 Parameters
epsilon (
float
) – Magnitude of the interaction.sigma (
float
) – Interaction length scale.cutoff (
float
) – Cutoff distance of the interaction.offset (
float
, optional) – Offset distance of the interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶


class
espressomd.interactions.
LennardJonesInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the LennardJones interaction.
 Parameters
epsilon (
float
) – Magnitude of the interaction.sigma (
float
) – Interaction length scale.cutoff (
float
) – Cutoff distance of the interaction.shift (
float
orstr
{‘auto’}) – Constant shift of the potential. If'auto'
, a default value is computed fromsigma
andcutoff
. The LJ potential will be shifted by \(4\epsilon\cdot\text{shift}\).offset (
float
, optional) – Offset distance of the interaction.min (
float
, optional) – Restricts the interaction to a minimal distance.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.
 Raises
ValueError – If not true.


class
espressomd.interactions.
MembraneCollisionInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶

is_active
(self)¶

required_keys
(self)¶

type_name
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


class
espressomd.interactions.
MorseInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the Morse interaction.
 Parameters
eps (
float
) – The magnitude of the interaction.alpha (
float
) – Stiffness of the Morse interaction.rmin (
float
) – Distance of potential minimumcutoff (
float
, optional) – Cutoff distance of the interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
NonBondedInteraction
(*args, **kwargs)¶ Bases:
object
Represents an instance of a nonbonded interaction, such as LennardJones. 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.

default_params
(self)¶ Virtual method.

get_params
(self)¶ Get interaction parameters.

is_active
(self)¶ Virtual method.

is_valid
(self)¶ Check, if the data stored in the instance still matches what is in Espresso.

required_keys
(self)¶ Virtual method.

set_params
(self, **p)¶ Update the given parameters.

type_name
(self)¶ Virtual method.

user_interactions
¶ object
 Type
user_interactions

valid_keys
(self)¶ Virtual method.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
NonBondedInteractionHandle
(_type1, _type2)¶ Bases:
object
Provides access to all nonbonded interactions between two particle types.

bmhtf
= None¶

buckingham
= None¶

dpd
= None¶

gaussian
= None¶

gay_berne
= None¶

generic_lennard_jones
= None¶

hat
= None¶

hertzian
= None¶

lennard_jones
= None¶

lennard_jones_cos
= None¶

lennard_jones_cos2
= None¶

membrane_collision
= None¶

morse
= None¶

smooth_step
= None¶

soft_sphere
= None¶

tabulated
= None¶

thole
= None¶

type1
= 1¶

type2
= 1¶


class
espressomd.interactions.
NonBondedInteractions
¶ Bases:
object
Access to nonbonded interaction parameters via
[i,j]
, wherei, j
are particle types. Returns aNonBondedInteractionHandle
object. Also: access to force capping.
reset
(self)¶ Reset all interaction parameters to their default values.


class
espressomd.interactions.
OifGlobalForces
¶ Bases:
espressomd.interactions.BondedInteraction
Characterize the distribution of the force of the global mesh deformation onto individual vertices of the mesh.
Part of the Objectinfluid method.
 Parameters
A0_g (
float
) – Relaxed area of the meshka_g (
float
) – Area coefficientV0 (
float
) – Relaxed volume of the meshkv (
float
) – Volume coefficient

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
OifLocalForces
¶ Bases:
espressomd.interactions.BondedInteraction
Characterize the deformation of two triangles sharing an edge.
Part of the Objectinfluid method.
 Parameters
r0 (
float
) – Equilibrium bond length of triangle edgesks (
float
) – Nonlinear stretching coefficient of triangle edgeskslin (
float
) – Linear stretching coefficient of triangle edgesphi0 (
float
) – Equilibrium angle between the two triangleskb (
float
) – Bending coefficient for the angle between the two trianglesA01 (
float
) – Equilibrium surface of the first triangleA02 (
float
) – Equilibrium surface of the second trianglekal (
float
) – Stretching coefficient of a triangle surfacekvisc (
float
) – Viscous coefficient of the triangle vertices

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
OifOutDirection
¶ Bases:
espressomd.interactions.BondedInteraction
Determine the surface normals of triangles on a mesh. Takes no parameter.

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶


class
espressomd.interactions.
QuarticBond
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Quartic bond.
 Parameters
k0 (
float
) – Magnitude of the square term.k1 (
float
) – Magnitude of the fourth order term.r (
float
) – Equilibrium bond length.r_cut (
float
) – Maximum interaction length.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
RigidBond
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Rigid bond.
 Parameters
r (
float
) – Bond length.ptol (
float
, optional) – Tolerance for positional deviations.vtop (
float
, optional) – Tolerance for velocity deviations.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.

class
espressomd.interactions.
SmoothStepInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the smoothstep interaction.
 Parameters
d (
float
) – Short range repulsion parameter.n (
int
, optional) – Exponent of short range repulsion.eps (
float
) – Magnitude of the second (soft) repulsion.k0 (
float
, optional) – Exponential factor in second (soft) repulsion.sig (
float
, optional) – Length scale of second (soft) repulsion.cutoff (
float
) – Cutoff distance of the interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
SoftSphereInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the Softsphere interaction.
 Parameters
a (
float
) – Magnitude of the interaction.n (
float
) – Exponent of the power law.cutoff (
float
) – Cutoff distance of the interaction.offset (
float
, optional) – Offset distance of the interaction.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.


class
espressomd.interactions.
SubtLJ
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Subtracted LJ potential. Takes no parameter.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.


class
espressomd.interactions.
TabulatedAngle
(*args, **kwargs)¶ Bases:
espressomd.interactions._TabulatedBase
Tabulated bond angle.
 Parameters
energy (array_like of
float
) – The energy table for the range \(0\pi\).force (array_like of
float
) – The force table for the range \(0\pi\).

pi
= 3.14159265358979¶

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

validate_params
(self)¶ Check that parameters are valid.

class
espressomd.interactions.
TabulatedDihedral
(*args, **kwargs)¶ Bases:
espressomd.interactions._TabulatedBase
Tabulated bond dihedral.
 Parameters
energy (array_like of
float
) – The energy table for the range \(02\pi\).force (array_like of
float
) – The force table for the range \(02\pi\).

pi
= 3.14159265358979¶

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

validate_params
(self)¶ Check that parameters are valid.

class
espressomd.interactions.
TabulatedDistance
(*args, **kwargs)¶ Bases:
espressomd.interactions._TabulatedBase
Tabulated bond length.
 Parameters
min (
float
) – The minimal interaction distance.max (
float
) – The maximal interaction distance.energy (array_like of
float
) – The energy table.force (array_like of
float
) – The force table.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

validate_params
(self)¶ Check that parameters are valid.

class
espressomd.interactions.
TabulatedNonBonded
(*args, **kwargs)¶ Bases:
espressomd.interactions.NonBondedInteraction

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Set parameters that are not required to their default value.

set_params
(self, **kwargs)¶ Set parameters for the TabulatedNonBonded interaction.
 Parameters
min (
float
,) – The minimal interaction distance.max (
float
,) – The maximal interaction distance.energy (array_like of
float
) – The energy table.force (array_like of
float
) – The force table.

type_name
(self)¶ Name of the potential.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.


class
espressomd.interactions.
ThermalizedBond
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Thermalized bond.
 Parameters
temp_com (
float
) – Temperature of the Langevin thermostat for the center of mass of the particle pair.gamma_com (
float
) – Friction coefficient of the Langevin thermostat for the center of mass of the particle pair.temp_distance (
float
) – Temperature of the Langevin thermostat for the distance vector of the particle pair.gamma_distance (
float
) – Friction coefficient of the Langevin thermostat for the distance vector of the particle pair.r_cut (
float
, optional) – Maximum distance beyond which the bond is considered broken.seed (
int
) – Initial counter value (or seed) of the philox RNG. Required on the first thermalized bond in the system. Must be positive. If prompted, it does not return the initially set counter value (the seed) but the current state of the RNG.

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶

class
espressomd.interactions.
TholeInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶

is_active
(self)¶

required_keys
(self)¶

set_params
(self, **kwargs)¶ Set parameters for the Thole interaction.
 Parameters
scaling_coeff (
float
) – The factor used in the Thole damping function between polarizable particles i and j. Usually calculated by the polarizabilities \(\alpha_i\), \(\alpha_j\) and damping parameters \(a_i\), \(a_j\) via \(s_{ij} = \frac{(a_i+a_j)/2}{((\alpha_i\cdot\alpha_j)^{1/2})^{1/3}}\)q1q2 (
float
) – Charge factor of the involved charges. Has to be set because it acts only on the portion of the Drude core charge that is associated to the dipole of the atom. For charged, polarizable atoms that charge is not equal to the particle charge property.

type_name
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


class
espressomd.interactions.
Virtual
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction
Virtual bond.

required_keys
(self)¶ Parameters that have to be set.

set_default_params
(self)¶ Sets parameters that are not required to their default value.

type_name
(self)¶ Name of interaction type.

type_number
(self)¶

valid_keys
(self)¶ All parameters that can be set.


class
espressomd.interactions.
WCAInteraction
¶ Bases:
espressomd.interactions.NonBondedInteraction

default_params
(self)¶ Python dictionary of default parameters.

is_active
(self)¶ Check if interaction is active.

required_keys
(self)¶ Parameters that have to be set.

set_params
(self, **kwargs)¶ Set parameters for the WCA interaction.
 Parameters
epsilon (
float
) – Magnitude of the interaction.sigma (
float
) – Interaction length scale.

type_name
(self)¶ Name of interaction type.

valid_keys
(self)¶ All parameters that can be set.

validate_params
(self)¶ Check that parameters are valid.
 Raises
ValueError – If not true.

espressomd.lb module¶

class
espressomd.lb.
HydrodynamicInteraction
¶ Bases:
espressomd.actors.Actor

agrid
¶

bulk_viscosity
¶

default_params
(self)¶

density
¶

ext_force_density
¶

get_interpolated_velocity
(self, pos)¶ Get LB fluid velocity at specified position.
 Parameters
pos ((3,) array_like of
float
) – The position at which velocity is requested. Returns
v – The LB fluid velocity at
pos
. Return type
(3,) array_like
float

kT
¶

load_checkpoint
(self, path, binary)¶

nodes
(self)¶ Provides a generator for iterating over all lb nodes

print_boundary
(self, path)¶

print_velocity
(self, path)¶

print_vtk_boundary
(self, path)¶

print_vtk_velocity
(self, path, bb1=None, bb2=None)¶

required_keys
(self)¶

save_checkpoint
(self, path, binary)¶

seed
¶

set_interpolation_order
(self, interpolation_order)¶ Set the order for the fluid interpolation scheme.
 Parameters
interpolation_order (
str
) –"linear"
for linear interpolation,"quadratic"
for quadratic interpolation.

shape
¶

stress
¶

tau
¶

valid_keys
(self)¶

validate_params
(self)¶

viscosity
¶


class
espressomd.lb.
LBFluid
¶ Bases:
espressomd.lb.HydrodynamicInteraction
Initialize the latticeBoltzmann method for hydrodynamic flow using the CPU.

class
espressomd.lb.
LBFluidGPU
¶ Bases:
espressomd.lb.HydrodynamicInteraction
Initialize the latticeBoltzmann method for hydrodynamic flow using the GPU.

get_interpolated_fluid_velocity_at_positions
(self, ndarray positions, three_point=False)¶ Calculate the fluid velocity at given positions.
 Parameters
positions ((N,3) numpyarray of type
float
) – The 3dimensional positions. Returns
velocities – The 3dimensional LB fluid velocities.
 Return type
(N,3) numpyarray of type
float
 Raises
AssertionError – If shape of
positions
not (N,3).


class
espressomd.lb.
LBFluidRoutines
(key)¶ Bases:
object

boundary
¶

density
¶

index
¶

population
¶

stress
¶

stress_neq
¶

velocity
¶


espressomd.lb.
assert_agrid_tau_set
(obj)¶
espressomd.lbboundaries module¶

class
espressomd.lbboundaries.
LBBoundaries
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptObjectRegistry
Creates a set of latticeBoltzmann boundaries.

add
(*args, **kwargs)[source]¶ Adds a boundary to the set. Either a valid boundary is an argument, or a valid set of parameters to create a boundary.

remove
(lbboundary)[source]¶ Removes a boundary from the set.
 Parameters
lbboundary (
LBBoundary
) – The boundary to be removed from the set.


class
espressomd.lbboundaries.
LBBoundary
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Creates a LB boundary.
espressomd.magnetostatic_extensions module¶

class
espressomd.magnetostatic_extensions.
DLC
¶ Bases:
espressomd.magnetostatic_extensions.MagnetostaticExtension
Electrostatics solver for systems with two periodic dimensions. See Dipolar Layer Correction (DLC) for more details.
Notes
At present, the empty gap (volume without any particles), is assumed to be along the zaxis. As a reference for the DLC method, see [Brodka04].
 Parameters
gap_size (
float
) – Size of the empty gap. Note that DLC relies on the user to make sure that this condition is fulfilled.maxPWerror (
float
) – Maximal pairwise error of the potential and force.far_cut (
float
, optional) – Cutoff of the exponential sum.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶ Check validity of class attributes.

class
espressomd.magnetostatic_extensions.
MagnetostaticExtension
¶ Bases:
espressomd.actors.Actor
espressomd.magnetostatics module¶

class
espressomd.magnetostatics.
DipolarBarnesHutGpu
¶ Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculates magnetostatic interactions by direct summation over all pairs. See BarnesHut octree sum on GPU for more details.
TODO: If the system has periodic boundaries, the minimum image convention is applied.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶


class
espressomd.magnetostatics.
DipolarDirectSumCpu
¶ Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions by direct summation over all pairs. See Dipolar direct sum for more details.
If the system has periodic boundaries, the minimum image convention is applied in the respective directions.
 Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

class
espressomd.magnetostatics.
DipolarDirectSumGpu
¶ Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions by direct summation over all pairs. See Dipolar direct sum for more details.
If the system has periodic boundaries, the minimum image convention is applied in the respective directions.
This is the GPU version of
espressomd.magnetostatics.DipolarDirectSumCpu
but uses floating point precision. Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

class
espressomd.magnetostatics.
DipolarDirectSumWithReplicaCpu
¶ Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions by direct summation over all pairs. See Dipolar direct sum for more details.
If the system has periodic boundaries,
n_replica
copies of the system are taken into account in the respective directions. Spherical cutoff is applied. Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))n_replica (
int
) – Number of replicas to be taken into account at periodic boundaries.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

class
espressomd.magnetostatics.
DipolarP3M
¶ Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions using the dipolar P3M method. See Dipolar P3M for more details.
 Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))accuracy (
float
) – P3M tunes its parameters to provide this target accuracy.alpha (
float
) – Ewald parameter.cao (
int
) – Chargeassignment order, an integer between 1 and 7.mesh (
int
or (3,) array_like ofint
) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.mesh_off ((3,) array_like of
float
) – Mesh offset.r_cut (
float
) – Real space cutoff.tune (
bool
, optional) – Activate/deactivate the tuning method on activation (default isTrue
, i.e., activated).

default_params
(self)¶

python_dp3m_adaptive_tune
(self)¶

python_dp3m_set_mesh_offset
(self, mesh_off)¶

python_dp3m_set_params
(self, p_r_cut, p_mesh, p_cao, p_alpha, p_accuracy)¶

python_dp3m_set_tune_params
(self, p_r_cut, p_mesh, p_cao, p_alpha, p_accuracy, p_n_interpol)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶ Check validity of parameters.

class
espressomd.magnetostatics.
MagnetostaticInteraction
¶ Bases:
espressomd.actors.Actor
Provide magnetostatic interactions.
 Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))

set_magnetostatics_prefactor
(self)¶ Set the magnetostatics prefactor

validate_params
(self)¶ Check validity of given parameters.

class
espressomd.magnetostatics.
Scafacos
(*args, **kwargs)¶ Bases:
espressomd.scafacos.ScafacosConnector
,espressomd.magnetostatics.MagnetostaticInteraction
Calculate the dipolar interaction using dipolescapable methods from the ScaFaCoS library. See ScaFaCoS magnetostatics for more details.
 Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\)).method_name (
str
) – Name of the ScaFaCoS method to use.method_params (
dict
) – Dictionary with the keyvalue pairs of the method parameters as defined in ScaFaCoS. Note that the values are cast to strings to match ScaFaCoS’ interface.

default_params
(self)¶

dipolar
= True¶
espressomd.minimize_energy module¶

class
espressomd.minimize_energy.
MinimizeEnergy
(*args, **kwargs)¶ Bases:
object
Steepest descent algorithm for energy minimization.
Particles located at \(\vec{r}_i\) at integration step \(i\) and experiencing a potential \(\mathcal{H}(\vec{r}_i)\) are displaced according to the equation:
\(\vec{r}_{i+1} = \vec{r}_i  \gamma\nabla\mathcal{H}(\vec{r}_i)\)
 Parameters
f_max (
float
) – Convergence criterion. Minimization stops when the maximal force on particles in the system is lower than this threshold. Set this to 0 when running minimization in a loop that stops when a custom convergence criterion is met.gamma (
float
) – Dampening constant.max_steps (
int
) – Maximal number of iterations.max_displacement (
float
) – Maximal allowed displacement per step. Typical values for a LJ liquid are in the range of 0.1% to 10% of the particle sigma.

default_params
(self)¶

init
(self, *args, **kwargs)¶

minimize
(self)¶ Perform energy minimization sweep.

required_keys
(self)¶

validate_params
(self)¶
espressomd.observables module¶

class
espressomd.observables.
BondAngles
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the angles between bonds of particles with given ids along a polymer chain.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
BondDihedrals
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the dihedrals between particles with given ids along a polymer chain.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ComForce
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the total force on particles with given ids.
Note that virtual sites are not included since forces on them do not enter the equation of motion directly.
Output format: \(\left(\sum_i f^x_i, \sum_i f^y_i, \sum_i f^z_i\right)\)
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ComPosition
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the center of mass for particles with given ids.
Note that virtual sites are not included since they do not have a meaningful mass.
Output format: \(\frac{1}{\sum_i m_i} \left( \sum_i m_i r^x_i, \sum_i m_i r^y_i, \sum_i m_i r^z_i\right)\)
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ComVelocity
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the center of mass velocity for particles with given ids.
Note that virtual sites are not included since they do not have a meaningful mass.
Output format: \(\frac{1}{\sum_i m_i} \left( \sum_i m_i v^x_i, \sum_i m_i v^y_i, \sum_i m_i v^z_i\right)\)
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
CosPersistenceAngles
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the cosine of mutual bond angles for chained particles with given ids.
The ith value of the result contains the cosine of the angle between bonds that are separated by i bonds. The values are averaged over the chain.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
Current
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the electric current for particles with given ids.
Output format: \(\left(\sum_i q_i v^x_i, \sum_i q_i v^y_i, \sum_i q_i v^z_i, \right)\)
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
CylindricalDensityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle density in cylindrical coordinates.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.center ((3,) array_like of
float
) – Position of the center of the cylindrical coordinate system for the histogram.axis ((3,) array_like of
float
) – Orientation vector of thez
axis of the cylindrical coordinate system for the histogram.n_r_bins (
int
) – Number of bins in radial direction.n_phi_bins (
int
) – Number of bins for the azimuthal direction.n_z_bins (
int
) – Number of bins inz
direction.min_r (
float
) – Minimumr
to consider.min_phi (
float
) – Minimumphi
to consider.min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
) – Maximumphi
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
CylindricalFluxDensityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle flux density in cylindrical coordinates.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.center ((3,) array_like of
float
) – Position of the center of the cylindrical coordinate system for the histogram.axis ((3,) array_like of
float
) – Orientation vector of thez
axis of the cylindrical coordinate system for the histogram.n_r_bins (
int
) – Number of bins in radial direction.n_phi_bins (
int
) – Number of bins for the azimuthal direction.n_z_bins (
int
) – Number of bins inz
direction.min_r (
float
) – Minimumr
to consider.min_phi (
float
) – Minimumphi
to consider.min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
) – Maximumphi
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
CylindricalLBFluxDensityProfileAtParticlePositions
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the LB fluid flux density at the particle positions in cylindrical coordinates.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.center ((3,) array_like of
float
) – Position of the center of the cylindrical coordinate system for the histogram.axis ((3,) array_like of
float
) – Orientation vector of thez
axis of the cylindrical coordinate system for the histogram.n_r_bins (
int
) – Number of bins in radial direction.n_phi_bins (
int
) – Number of bins for the azimuthal direction.n_z_bins (
int
) – Number of bins inz
direction.min_r (
float
) – Minimumr
to consider.min_phi (
float
) – Minimumphi
to consider.min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
) – Maximumphi
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
CylindricalLBVelocityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the LB fluid velocity profile in cylindrical coordinates.
This observable samples the fluid in on a regular grid defined by variable
sampling_density
. Note that a small delta leads to a large number of sample points and carries a performance cost. Parameters
center ((3,) array_like of
float
) – Position of the center of the cylindrical coordinate system for the histogram.axis ((3,) array_like of
float
) – Orientation vector of thez
axis of the cylindrical coordinate system for the histogram.n_r_bins (
int
) – Number of bins in radial direction.n_phi_bins (
int
) – Number of bins for the azimuthal direction.n_z_bins (
int
) – Number of bins inz
direction.min_r (
float
) – Minimumr
to consider.min_phi (
float
) – Minimumphi
to consider.min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
) – Maximumphi
to consider.max_z (
float
) – Maximumz
to consider.sampling_density (
float
) – Samples per unit volume for the LB velocity interpolation.

class
espressomd.observables.
CylindricalLBVelocityProfileAtParticlePositions
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the LB fluid velocity at the particle positions in cylindrical coordinates.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.center ((3,) array_like of
float
) – Position of the center of the cylindrical coordinate system for the histogram.axis ((3,) array_like of
float
) – Orientation vector of thez
axis of the cylindrical coordinate system for the histogram.n_r_bins (
int
) – Number of bins in radial direction.n_phi_bins (
int
) – Number of bins for the azimuthal direction.n_z_bins (
int
) – Number of bins inz
direction.min_r (
float
) – Minimumr
to consider.min_phi (
float
) – Minimumphi
to consider.min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
) – Maximumphi
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
CylindricalVelocityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle velocity profile in cylindrical coordinates.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.center ((3,) array_like of
float
) – Position of the center of the cylindrical coordinate system for the histogram.axis ((3,) array_like of
float
) – Orientation vector of thez
axis of the cylindrical coordinate system for the histogram.n_r_bins (
int
) – Number of bins in radial direction.n_phi_bins (
int
) – Number of bins for the azimuthal direction.n_z_bins (
int
) – Number of bins inz
direction.min_r (
float
) – Minimumr
to consider.min_phi (
float
) – Minimumphi
to consider.min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
) – Maximumphi
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
DPDStress
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the nonequilibrium contribution of the DPD interaction to the stress tensor.
 Parameters
None

class
espressomd.observables.
DensityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle density profile for particles with given ids.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
DipoleMoment
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the dipole moment for particles with given ids.
Output format: \(\left(\sum_i q_i r^x_i, \sum_i q_i r^y_i, \sum_i q_i r^z_i\right)\)
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
FluxDensityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle flux density for particles with given ids.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
ForceDensityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the force density profile for particles with given ids.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.

class
espressomd.observables.
LBFluidStress
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the average stress of the LB fluid for all nodes.
 Parameters
None

class
espressomd.observables.
LBVelocityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the LB fluid velocity profile.
This observable samples the fluid in on a regular grid defined by the variables
sampling_*
. Note that a small delta leads to a large number of sample points and carries a performance cost.Warning
In case of the CPU version of the LB fluid implementation, this observable currently only works for a single core.
 Parameters
n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.sampling_delta_x (
float
, default=1.0) – Spacing for the sampling grid inx
direction.sampling_delta_y (
float
, default=1.0) – Spacing for the sampling grid iny
direction.sampling_delta_z (
float
, default=1.0) – Spacing for the sampling grid inz
direction.sampling_offset_x (
float
, default=0.0) – Offset for the sampling grid inx
direction.sampling_offset_y (
float
, default=0.0) – Offset for the sampling grid iny
direction.sampling_offset_z (
float
, default=0.0) – Offset for the sampling grid inz
direction.allow_empty_bins (
bool
, default=False) – Whether or not to allow bins that will not be sampled at all.

class
espressomd.observables.
MagneticDipoleMoment
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the magnetic dipole moment for particles with given ids.
Output format: \(\left(\sum_i \mu^x_i, \sum_i \mu^y_i, \sum_i \mu^z_i\right)\)
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ParticleBodyVelocities
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle velocity in the particles’ bodyfixed frame of reference.
For each particle, the bodyfixed frame of reference is obtained from the particle’s orientation stored in the quaternions.
Output format: \(v_{x1},\ v_{y1},\ v_{z1},\ v_{x2},\ v_{y2},\ v_{z2},\ \dots\ v_{xn},\ v_{yn},\ v_{zn}\).
The particles are ordered according to the list of ids passed to the observable.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ParticleDistances
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the distances between particles with given ids along a polymer chain.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ParticleForces
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle forces for particles with given ids.
Output format: \(f_{x1},\ f_{y1},\ f_{z1},\ f_{x2},\ f_{y2},\ f_{z2},\ \dots\ f_{xn},\ f_{yn},\ f_{zn}\).
The particles are ordered according to the list of ids passed to the observable.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ParticlePositions
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle positions for particles with given ids.
Output format: \(x_1,\ y_1,\ z_1,\ x_2,\ y_2,\ z_2,\ \dots\ x_n,\ y_n,\ z_n\).
The particles are ordered according to the list of ids passed to the observable.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
ParticleVelocities
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle velocities for particles with given ids.
Output format: \(v_{x1},\ v_{y1},\ v_{z1},\ v_{x2},\ v_{y2},\ v_{z2},\ \dots\ v_{xn},\ v_{yn},\ v_{zn}\).
The particles are ordered according to the list of ids passed to the observable.
 Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.

class
espressomd.observables.
StressTensor
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the total stress tensor. See Stress Tensor.
espressomd.pair_criteria module¶

class
espressomd.pair_criteria.
BondCriterion
(**kwargs)[source]¶ Bases:
espressomd.pair_criteria._PairCriterion
Pair criterion returning true, if a pair bond of given type exists between them
The following parameters can be passed to the constructor, changed via
set_params()
and retrieved viaget_params()
. Parameters
bond_type (
int
) – numeric type of the bond

class
espressomd.pair_criteria.
DistanceCriterion
(**kwargs)[source]¶ Bases:
espressomd.pair_criteria._PairCriterion
Pair criterion returning true, if particles are closer than a cutoff. Periodic boundaries are treated via minimum image convention.
The following parameters can be passed to the constructor, changed via
set_params()
and retrieved viaget_params()
. Parameters
cut_off (
float
) – distance cutoff for the criterion

class
espressomd.pair_criteria.
EnergyCriterion
(**kwargs)[source]¶ Bases:
espressomd.pair_criteria._PairCriterion
Pair criterion returning true, if the short range energy between the particles is superior or equal to the cutoff.
Be aware that the short range energy contains the short range part of dipolar and electrostatic interactions, but not the long range part.
The following parameters can be passed to the constructor, changed via
set_params()
and retrieved viaget_params()
. Parameters
cut_off (
float
) – energy cutoff for the criterion
espressomd.particle_data module¶

class
espressomd.particle_data.
ParticleHandle
¶ Bases:
object

add_bond
(self, _bond)¶ Add a single bond to the particle.
 Parameters
_bond (
tuple
) – tuple where the first element is either a bond ID of a bond type, and the last element is the ID of the partner particle to be bonded to.
See also
bonds()
Particle
property containing a list of all current bonds help byParticle
.
Examples
>>> import espressomd >>> from espressomd.interactions import HarmonicBond >>> >>> 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))

add_exclusion
(self, _partner)¶ Excluding interaction with the given partner.
 Parameters
_partner (
int
) – partner

add_verified_bond
(self, bond)¶ Add a bond, the validity of which has already been verified.
See also
add_bond()
Delete an unverified bond held by the
Particle
.bonds()
Particle
property containing a list of all current bonds help byParticle
.

bond_site
¶ OIF bond_site

bonds
¶ The bonds stored by this particle. Note that bonds are only stored by one partner. You need to define a bonded interaction.
 bondslist/tuple of tuples/lists
a bond tuple is specified as a bond identifier associated with a particle
(bond_ID, part_ID)
. A single particle may contain multiple such tuples.
See also
espressomd.particle_data.ParticleHandle.add_bond
Method to add bonds to a
Particle
espressomd.particle_data.ParticleHandle.delete_bond
Method to remove bonds from a
Particle
Bond ids have to be an integer >= 0.

check_bond_or_throw_exception
(self, bond)¶ Checks the validity of the given bond:
If the bondtype is given as an object or a numerical id
If all partners are of type
int
If the number of partners satisfies the bond
If the bond type used exists (is lower than
n_bonded_ia
)If the number of bond partners fits the bond type
Throws an exception if any of these are not met.

convert_vector_body_to_space
(self, vec)¶ Converts the given vector from the particle’s body frame to the space frame

convert_vector_space_to_body
(self, vec)¶ Converts the given vector from the space frame to the particle’s body frame

delete_all_bonds
(self)¶ Delete all bonds from the particle.
See also
delete_bond()
Delete an unverified bond held by the particle.
bonds()
Particle property containing a list of all current bonds help by particle.

delete_bond
(self, _bond)¶ Delete a single bond from the particle.
 Parameters
_bond – bond to be deleted
See also
bonds()
Particle property, a list of all current bonds.
Examples
>>> import espressomd >>> from espressomd.interactions import HarmonicBond >>> >>> 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 bonded particles to particle 0
>>> system.part.add(id=0, pos=(1, 0, 0)) >>> system.part.add(id=1, pos=(2, 0, 0)) >>> system.part.add(id=2, pos=(1, 1, 0)) >>> system.part[0].add_bond((harm_bond,1)) >>> system.part[0].add_bond((harm_bond,2)) >>> >>> bonds = system.part[0].bonds >>> print(bonds) ((HarmonicBond(0): {'r_0': 1.0, 'k': 5.0, 'r_cut': 0.0}, 1), (HarmonicBond(0): {'r_0': 1.0, 'k': 5.0, 'r_cut': 0.0}, 2))
delete the bond between particle 0 and particle 1
>>> system.part[0].delete_bond(bonds[0]) >>> print(system.part[0].bonds) ((HarmonicBond(0): {'r_0': 1.0, 'k': 5.0, 'r_cut': 0.0}, 2),)

delete_exclusion
(self, _partner)¶

delete_verified_bond
(self, bond)¶ Delete a single bond from the particle. The validity of which has already been verified.
 Parameters
bond (
tuple
) – tuple where the first element is either a bond ID of a bond type, and the last element is the ID of the partner particle to be bonded to.
See also
delete_bond()
Delete an unverified bond held by the
Particle
.bonds()
Particle
property containing a list of all current bonds help byParticle
.

dip
¶ The orientation of the dipole axis.
dip : (3,) array_like of
float
Note
This needs the feature
DIPOLES
.

dipm
¶ The magnitude of the dipole moment.
dipm :
float
Note
This needs the feature
DIPOLES
.

director
¶ Director.
Note
Setting the director is not implemented. This needs the feature
ROTATION
.

exclusions
¶ The exclusion list of particles where nonbonded interactions are ignored.
Note
This needs the feature
EXCLUSIONS
.

ext_force
¶ An additional external force applied to the particle.
ext_force : (3,) array_like of
float
Note
This needs the feature
EXTERNAL_FORCES
.

ext_torque
¶ An additional external torque is applied to the particle.
ext_torque : (3,) array_like of
float
Note
This torque is specified in the laboratory frame!
This needs features
EXTERNAL_FORCES
andROTATION
.

f
¶ The instantaneous force acting on this particle.
 f(3,) array_like of
float
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 immediately lost at the next integration step.
 f(3,) array_like of

fix
¶ Fixes the particle motion in the specified cartesian directions.
fix : (3,) array_like of
int
Fixes the particle in space. By supplying a set of 3 integers as arguments it is possible to fix motion in x, y, or z coordinates independently. For example:
part[<INDEX>].fix = [0, 0, 1]
will fix motion for particle with index
INDEX
only in z.Note
This needs the feature
EXTERNAL_FORCES
.

gamma
¶ The bodyfixed frictional coefficient used in the Langevin thermostat.
gamma :
float
or (3,) array_like offloat
Note
This needs features
LANGEVIN_PER_PARTICLE
andPARTICLE_ANISOTROPY
.See also
espressomd.thermostat.Thermostat.set_langevin()
Setting the parameters of the Langevin thermostat

gamma_rot
¶ The particle translational frictional coefficient used in the Langevin thermostat.
gamma_rot :
float
or (3,) array_like offloat
Note
This needs features
LANGEVIN_PER_PARTICLE
,ROTATION
andPARTICLE_ANISOTROPY
.

id
¶ Integer particle id

image_box
¶ The image box the particles is in.
This is the number of times the particle position has been folded by the box length in each direction.

mass
¶ Particle mass.
 mass
float
The particle mass.
See also
espressomd.thermostat.Thermostat.set_langevin()
Setting the parameters of the Langevin thermostat
 mass

mol_id
¶ The molecule id of the Particle.
 mol_id
int
The particle
mol_id
is used to differentiate between particles belonging to different molecules, e.g. when virtual sites are used, or objectinfluid cells. The defaultmol_id
for all particles is 0.
Note
The value of
mol_id
has to be an integer >= 0. mol_id

mu_E
¶ Particle electrophoretic velocity.
mu_E :
float
This effectively acts as a velocity offset between a latticeBoltzmann fluid and the particle. Has only an effect if LB is turned on.
Note
This needs the feature
LB_ELECTROHYDRODYNAMICS
.

node
¶ The node the particle is on, identified by its MPI rank.

omega_body
¶ The particle angular velocity in body frame.
omega_body : (3,) array_like of
float
This property sets the angular momentum of this particle in the particles corotating frame (or body frame).
Note
This needs the feature
ROTATION
.

omega_lab
¶ The particle angular velocity the lab frame.
 omega_lab(3,) array_like of
float
The particle’s angular velocity 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 (
quat
) must be set before settingomega_lab
, otherwise the conversion from lab to body frame will not be handled properly.See also
 omega_lab(3,) array_like of

out_direction
¶ OIF Outward direction

pos
¶ The unwrapped (not folded into central box) particle position.
 pos(3,) array_like of
float
The particles’ absolute position.
 pos(3,) array_like of

pos_folded
¶ The wrapped (folded into central box) position vector of a particle.
 pos(3,) array_like of
float
The particles’ position.
Note
Setting the folded position is ambiguous and is thus not possible, please use
pos
.Examples
>>> import espressomd >>> >>> system = espressomd.System() >>> >>> system.box_l=[10,10,10] >>> # add two bonded particles to particle 0 >>> system.part.add(id=0, pos=(5, 0, 0)) >>> system.part.add(id=1, pos=(10, 0, 0)) >>> system.part.add(id=2, pos=(25, 0, 0)) >>> for p in system.part: >>> print(p.pos) [ 5. 0. 0.] [ 10. 0. 0.] [ 25. 0. 0.] >>> >>> for p in system.part: >>> print(p.pos_folded) [5.0, 0.0, 0.0] [0.0, 0.0, 0.0] [5.0, 0.0, 0.0]
 pos(3,) array_like of

q
¶ Particle charge.
q :
float
Note
This needs the feature
ELECTROSTATICS
.

quat
¶ Particle quaternion representation.
 quat(4,) array_like of
float
Sets the quaternion representation of the rotational position of this particle.
Note
This needs the feature
ROTATION
. quat(4,) array_like of

remove
(self)¶ Delete the particle.

rinertia
¶ The particle rotational inertia.
rinertia : (3,) array_like of
float
Sets the diagonal elements of this particles rotational inertia tensor. These correspond with the inertial moments along the coordinate axes in the particle’s corotating coordinate system. When the particle’s quaternions are set to
[1, 0, 0, 0,]
, the corotating and the fixed (lab) frames are coaligned.Note
This needs the feature
ROTATIONAL_INERTIA
.

rotate
(self, axis=None, angle=None)¶ Rotates the particle around the given axis
 Parameters
axis ((3,) array_like of
float
)angle (
float
)

rotation
¶ Switches the particle’s rotational degrees of freedom in the Cartesian axes in the bodyfixed frame. The content of the torque and omega variables are meaningless for the coordinates for which rotation is disabled.
The default is not to integrate any rotational degrees of freedom.
rotation : (3,) array_like of
int
Note
This needs the feature
ROTATION
.

swimming
¶ Set swimming parameters.
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 selfpropelled in the direction determined by its quaternion. For setting the quaternion of the particle see
quat
. The selfpropulsion speed will relax to a constant velocity, that is specified byv_swim
. Alternatively it is possible to achieve a constant velocity by imposing a constant force termf_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 possibilitiesv_swim
orf_swim
as you cannot relax to constant force and constant velocity at the same time. The setting bothv_swim
andf_swim
to 0.0 thus disables swimming. This option applies to all nonlatticeBoltzmann thermostats. Note that there is no real difference betweenv_swim
andf_swim
since the latter may always 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 termf_swim
that is balanced by friction of a (Langevin) thermostat. This excludes the optionv_swim
.v_swim (
float
) – Achieve a constant velocity by imposing a constant terminal velocityv_swim
. This excludes the optionf_swim
.mode (
str
, {‘pusher’, ‘puller’}) – 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.
Notes
This needs the feature
ENGINE
. The keys'mode'
, and'dipole_length'
are only available ifENGINE
is used with LB orCUDA
.Examples
>>> import espressomd >>> >>> system = espressomd.System() >>> >>> # Usage with Langevin >>> system.part.add(id=0, pos=[1,0,0],swimming={'f_swim':0.03}) >>> >>> # Usage with LB >>> system.part.add(id=1, pos=[2,0,0], swimming={'f_swim': 0.01, ... 'mode': 'pusher', 'dipole_length': 2.0})

temp
¶ Particle’s temperature in the Langevin thermostat.
temp:
float
Note
This needs the feature
LANGEVIN_PER_PARTICLE
.

torque_lab
¶ The particle torque in the lab frame.
torque_lab : (3,) array_like of
float
This property defines the torque of this particle in the fixed frame (or laboratory frame).
Note
The orientation of the particle (
quat
) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.

type
¶ The particle type for nonbonded interactions.
 type
int
Nonbonded interactions act between different types of particles.
Note
The value of
type
has to be an integer >= 0. type

update
(self, P)¶

v
¶ The particle velocity in the lab frame.
 v(3,) array_like of
float
The particles’ velocity
Note
The velocity remains variable and will be changed during integration.
 v(3,) array_like of

virtual
¶ Virtual flag.
Declares the particles as virtual (
True
) or nonvirtual (False
, default).virtual :
bool
Note
This needs the feature
VIRTUAL_SITES

vs_auto_relate_to
(self, _relto)¶ Setup this particle as virtual site relative to the particle with the given id.

vs_quat
¶ Virtual site quaternion.
This quaternion describes the virtual particles orientation in the body fixed frame of the related real particle.
vs_quat : (4,) array_like of
float
Note
This needs the feature
VIRTUAL_SITES_RELATIVE
.

vs_relative
¶ Virtual sites relative parameters.
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 nonvirtual and virtual particle. The relative orientation is specified as a quaternion of 4 floats.
vs_relative : tuple: (PID, distance, (q1,q2,q3,q4))
Note
This needs the feature
VIRTUAL_SITES_RELATIVE


class
espressomd.particle_data.
ParticleList
¶ Bases:
object
Provides access to the particles via
[i]
, wherei
is the particle id. Returns aespressomd.particle_data.ParticleHandle
object.
add
(self, *args, **kwargs)¶ Adds one or several particles to the system
 Parameters
Either a dictionary or a bunch of keyword args.
 Returns
 Return type
Returns an instance of
espressomd.particle_data.ParticleHandle
for each added particle.
Examples
>>> import espressomd >>> >>> system = espressomd.System() >>> >>> # add two particles >>> system.part.add(id=0, pos=(1, 0, 0)) >>> system.part.add(id=1, pos=(2, 0, 0))
Pos is mandatory, id can be omitted, in which case it is assigned automatically. Several particles can be added by passing one value per particle to each property:
system.part.add(pos=((1,2,3),(4,5,6)),q=(1,1))

clear
(self)¶ Removes all particles.

exists
(self, idx)¶

highest_particle_id
¶ Largest particle id.

n_part_types
¶ Number of particle types.

n_rigidbonds
¶ Number of rigid bonds.

pairs
(self)¶ Generator returns all pairs of particles.

select
(self, *args, **kwargs)¶ Generates a particle slice by filtering particles via a userdefined criterion
Parameters:
Either: a keyword arguments in which the keys are names of particle properties and the values are the values to filter for. E.g.,:
system.part.select(type=0, q=1)
Or: a function taking a ParticleHandle as argument and returning True if the particle is to be filtered for. E.g.,:
system.part.select(lambda p: p.pos[0] < 0.5)
 Returns
An instance of
ParticleSlice
containing the selected particles Return type

writevtk
(self, fname, types='all')¶ Write the positions and velocities of particles with specified types to a VTK file.
 Parameters
fname (
str
) – Filename of the target output filetypes (list of
int
or the string ‘all’, optional (default: ‘all’)) – A list of particle types which should be output to ‘fname’
Examples
>>> import espressomd >>> >>> system = espressomd.System() >>> >>> # add several particles >>> system.part.add(pos=.5*system.box_l,v=[1,0,0],type=0) >>> system.part.add(pos=.4*system.box_l,v=[0,2,0],type=1) >>> system.part.add(pos=.7*system.box_l,v=[2,0,1],type=1) >>> system.part.add(pos=.1*system.box_l,v=[0,0,1],type=2) >>> >>> # write to VTK >>> system.part.writevtk("part_type_0_1.vtk", types=[0,1]) >>> system.part.writevtk("part_type_2.vtk", types=[2]) >>> system.part.writevtk("part_all.vtk")
Todo
move to
./io/writer/


class
espressomd.particle_data.
ParticleSlice
¶ Bases:
espressomd.particle_data._ParticleSliceImpl
Handles slice inputs e.g.
part[0:2]
. Sets values for selected slices or returns values as a single list.
property
bond_site
¶ OIF bond_site

property
bonds
¶ The bonds stored by this particle. Note that bonds are only stored by one partner. You need to define a bonded interaction.
 bondslist/tuple of tuples/lists
a bond tuple is specified as a bond identifier associated with a particle
(bond_ID, part_ID)
. A single particle may contain multiple such tuples.
See also
espressomd.particle_data.ParticleHandle.add_bond
Method to add bonds to a
Particle
espressomd.particle_data.ParticleHandle.delete_bond
Method to remove bonds from a
Particle
Bond ids have to be an integer >= 0.

property
dip
¶ The orientation of the dipole axis.
dip : (3,) array_like of
float
Note
This needs the feature
DIPOLES
.

property
dipm
¶ The magnitude of the dipole moment.
dipm :
float
Note
This needs the feature
DIPOLES
.

property
director
¶ Director.
Note
Setting the director is not implemented. This needs the feature
ROTATION
.

property
exclusions
¶ The exclusion list of particles where nonbonded interactions are ignored.
Note
This needs the feature
EXCLUSIONS
.

property
ext_force
¶ An additional external force applied to the particle.
ext_force : (3,) array_like of
float
Note
This needs the feature
EXTERNAL_FORCES
.

property
ext_torque
¶ An additional external torque is applied to the particle.
ext_torque : (3,) array_like of
float
Note
This torque is specified in the laboratory frame!
This needs features
EXTERNAL_FORCES
andROTATION
.

property
f
¶ The instantaneous force acting on this particle.
 f(3,) array_like of
float
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 immediately lost at the next integration step.
 f(3,) array_like of

property
fix
¶ Fixes the particle motion in the specified cartesian directions.
fix : (3,) array_like of
int
Fixes the particle in space. By supplying a set of 3 integers as arguments it is possible to fix motion in x, y, or z coordinates independently. For example:
part[<INDEX>].fix = [0, 0, 1]
will fix motion for particle with index
INDEX
only in z.Note
This needs the feature
EXTERNAL_FORCES
.

property
gamma
¶ The bodyfixed frictional coefficient used in the Langevin thermostat.
gamma :
float
or (3,) array_like offloat
Note
This needs features
LANGEVIN_PER_PARTICLE
andPARTICLE_ANISOTROPY
.See also
espressomd.thermostat.Thermostat.set_langevin()
Setting the parameters of the Langevin thermostat

property
gamma_rot
¶ The particle translational frictional coefficient used in the Langevin thermostat.
gamma_rot :
float
or (3,) array_like offloat
Note
This needs features
LANGEVIN_PER_PARTICLE
,ROTATION
andPARTICLE_ANISOTROPY
.

property
id
¶ Integer particle id

property
image_box
¶ The image box the particles is in.
This is the number of times the particle position has been folded by the box length in each direction.

property
mass
¶ Particle mass.
 mass
float
The particle mass.
See also
espressomd.thermostat.Thermostat.set_langevin()
Setting the parameters of the Langevin thermostat
 mass

property
mol_id
¶ The molecule id of the Particle.
 mol_id
int
The particle
mol_id
is used to differentiate between particles belonging to different molecules, e.g. when virtual sites are used, or objectinfluid cells. The defaultmol_id
for all particles is 0.
Note
The value of
mol_id
has to be an integer >= 0. mol_id

property
mu_E
¶ Particle electrophoretic velocity.
mu_E :
float
This effectively acts as a velocity offset between a latticeBoltzmann fluid and the particle. Has only an effect if LB is turned on.
Note
This needs the feature
LB_ELECTROHYDRODYNAMICS
.

property
node
¶ The node the particle is on, identified by its MPI rank.

property
omega_body
¶ The particle angular velocity in body frame.
omega_body : (3,) array_like of
float
This property sets the angular momentum of this particle in the particles corotating frame (or body frame).
Note
This needs the feature
ROTATION
.

property
omega_lab
¶ The particle angular velocity the lab frame.
 omega_lab(3,) array_like of
float
The particle’s angular velocity 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 (
quat
) must be set before settingomega_lab
, otherwise the conversion from lab to body frame will not be handled properly.See also
 omega_lab(3,) array_like of

property
out_direction
¶ OIF Outward direction

property
pos
¶ The unwrapped (not folded into central box) particle position.
 pos(3,) array_like of
float
The particles’ absolute position.
 pos(3,) array_like of

property
q
¶ Particle charge.
q :
float
Note
This needs the feature
ELECTROSTATICS
.

property
quat
¶ Particle quaternion representation.
 quat(4,) array_like of
float
Sets the quaternion representation of the rotational position of this particle.
Note
This needs the feature
ROTATION
. quat(4,) array_like of

property
rinertia
¶ The particle rotational inertia.
rinertia : (3,) array_like of
float
Sets the diagonal elements of this particles rotational inertia tensor. These correspond with the inertial moments along the coordinate axes in the particle’s corotating coordinate system. When the particle’s quaternions are set to
[1, 0, 0, 0,]
, the corotating and the fixed (lab) frames are coaligned.Note
This needs the feature
ROTATIONAL_INERTIA
.

property
rotation
¶ Switches the particle’s rotational degrees of freedom in the Cartesian axes in the bodyfixed frame. The content of the torque and omega variables are meaningless for the coordinates for which rotation is disabled.
The default is not to integrate any rotational degrees of freedom.
rotation : (3,) array_like of
int
Note
This needs the feature
ROTATION
.

property
swimming
¶ Set swimming parameters.
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 selfpropelled in the direction determined by its quaternion. For setting the quaternion of the particle see
quat
. The selfpropulsion speed will relax to a constant velocity, that is specified byv_swim
. Alternatively it is possible to achieve a constant velocity by imposing a constant force termf_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 possibilitiesv_swim
orf_swim
as you cannot relax to constant force and constant velocity at the same time. The setting bothv_swim
andf_swim
to 0.0 thus disables swimming. This option applies to all nonlatticeBoltzmann thermostats. Note that there is no real difference betweenv_swim
andf_swim
since the latter may always 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 termf_swim
that is balanced by friction of a (Langevin) thermostat. This excludes the optionv_swim
.v_swim (
float
) – Achieve a constant velocity by imposing a constant terminal velocityv_swim
. This excludes the optionf_swim
.mode (
str
, {‘pusher’, ‘puller’}) – 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.
Notes
This needs the feature
ENGINE
. The keys'mode'
, and'dipole_length'
are only available ifENGINE
is used with LB orCUDA
.Examples
>>> import espressomd >>> >>> system = espressomd.System() >>> >>> # Usage with Langevin >>> system.part.add(id=0, pos=[1,0,0],swimming={'f_swim':0.03}) >>> >>> # Usage with LB >>> system.part.add(id=1, pos=[2,0,0], swimming={'f_swim': 0.01, ... 'mode': 'pusher', 'dipole_length': 2.0})

property
temp
¶ Particle’s temperature in the Langevin thermostat.
temp:
float
Note
This needs the feature
LANGEVIN_PER_PARTICLE
.

property
torque_lab
¶ The particle torque in the lab frame.
torque_lab : (3,) array_like of
float
This property defines the torque of this particle in the fixed frame (or laboratory frame).
Note
The orientation of the particle (
quat
) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.

property
type
¶ The particle type for nonbonded interactions.
 type
int
Nonbonded interactions act between different types of particles.
Note
The value of
type
has to be an integer >= 0. type

property
v
¶ The particle velocity in the lab frame.
 v(3,) array_like of
float
The particles’ velocity
Note
The velocity remains variable and will be changed during integration.
 v(3,) array_like of

property
virtual
¶ Virtual flag.
Declares the particles as virtual (
True
) or nonvirtual (False
, default).virtual :
bool
Note
This needs the feature
VIRTUAL_SITES

property
vs_quat
¶ Virtual site quaternion.
This quaternion describes the virtual particles orientation in the body fixed frame of the related real particle.
vs_quat : (4,) array_like of
float
Note
This needs the feature
VIRTUAL_SITES_RELATIVE
.

property
vs_relative
¶ Virtual sites relative parameters.
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 nonvirtual and virtual particle. The relative orientation is specified as a quaternion of 4 floats.
vs_relative : tuple: (PID, distance, (q1,q2,q3,q4))
Note
This needs the feature
VIRTUAL_SITES_RELATIVE

property

espressomd.particle_data.
set_slice_one_for_all
(particle_slice, attribute, values)¶

espressomd.particle_data.
set_slice_one_for_each
(particle_slice, attribute, values)¶
espressomd.polymer module¶

espressomd.polymer.
positions
(**kwargs)¶ Generates particle positions for polymer creation.
 Parameters
n_polymers (
int
, required) – Number of polymer chainsbeads_per_chain (
int
, required) – Number of monomers per chainbond_length (
float
, required) – distance between adjacent monomers in a chainseed (
int
, required) – Seed for the RNG used to generate the particle positions.bond_angle (
float
, optional) – If set, this parameter defines the angle between adjacent bonds within a polymer.start_positions (array_like
float
.) – If set, this vector defines the start positions for the polymers, i.e., the position of each polymer’s first monomer bead. Here, a numpy array of shape (n_polymers, 3) is expected.min_distance (
float
, optional) – Minimum distance between all generated positions. Defaults to 0respect_constraints (
bool
, optional) – If True, the particle setup tries to obey previously defined constraints. Default value is False.max_tries (
int
, optional) – Maximal number of attempts to generate every monomer position, as well as maximal number of retries per polymer, if choosing suitable monomer positions fails. Default value is 1000. Depending on the total number of beads and constraints, this value needs to be adapted.
 Returns
Threedimensional numpy array, namely a list of polymers containing the coordinates of the respective monomers.
 Return type
ndarray

espressomd.polymer.
validate_params
(_params, default)¶
espressomd.profiler module¶

espressomd.profiler.
begin_section
(name)¶ Start named section in profiler.
 Parameters
name (
str
) – Name of the section

espressomd.profiler.
end_section
(name)¶ End named section in profiler.
 Parameters
name (
str
) – Name of the section
espressomd.reaction_ensemble module¶

class
espressomd.reaction_ensemble.
ConstantpHEnsemble
(*args, **kwargs)¶ Bases:
espressomd.reaction_ensemble.ReactionAlgorithm

add_reaction
(self, *args, **kwargs)¶

constant_pH
¶ Sets the input pH for the constant pH ensemble method.


class
espressomd.reaction_ensemble.
ReactionAlgorithm
¶ Bases:
object
This class provides the base class for Reaction Algorithms like the Reaction Ensemble algorithm, the WangLandau 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 MaxwellBoltzmann 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.seed (
int
) – Initial counter value (or seed) of the Mersenne Twister RNG.

add_reaction
(self, *args, **kwargs)¶ Sets up a reaction in the forward and backward direction.
 Parameters
gamma (
float
) – Equilibrium constant of the reaction, \(\gamma\) (see the User guide, section 6.6 for the definition and further details).reactant_types (list of
int
) – List of particle types of reactants in the reaction.reactant_coefficients (list of
int
) – List of stoichiometric coefficients of the reactants in the same order as the list of their types.product_types (list of
int
) – List of particle types of products in the reaction.product_coefficients (list of
int
) – List of stoichiometric coefficients of products of the reaction in the same order as the list of their typesdefault_charges (
dict
) – A dictionary of default charges for types that occur in the provided reaction.check_for_electroneutrality (
bool
) – Check for electroneutrality of the given reaction ifTrue
.

change_reaction_constant
(self, reaction_id, gamma)¶ Changes the reaction constant of a given reaction (for the forward and backward reaction). The
reaction_id
which is assigned to a reaction depends on the order in whichadd_reaction()
was called. The 0th reaction hasreaction_id=0
, the next added reaction needs to be addressed withreaction_id=1
, etc. Parameters
reaction_id (
int
) – reaction_idgamma (
float
) – new reaction constant

delete_particle
(self, p_id)¶ 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.

delete_reaction
(self, reaction_id)¶ Delete a reaction from the set of used reactions (the forward and backward reaction). The
reaction_id
which is assigned to a reaction depends on the order in whichadd_reaction()
was called. The 0th reaction hasreaction_id=0
, the next added reaction needs to be addressed withreaction_id=1
, etc. After the deletion of a reaction subsequent reactions take thereaction_id
of the deleted reaction. Parameters
reaction_id (
int
) – reaction_id

displacement_mc_move_for_particles_of_type
(self, type_mc, particle_number_to_be_changed=1)¶ 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.
 Parameters
type_mc (
int
) – particle type which should be moved

get_acceptance_rate_configurational_moves
(self)¶ Returns the acceptance rate for the configuration moves.

get_acceptance_rate_reaction
(self, reaction_id)¶ Returns the acceptance rate for the given reaction.

get_non_interacting_type
(self)¶ Returns the type which is used for hiding particles.

get_status
(self)¶ Returns the status of the reaction ensemble in a dictionary containing the used reactions, the used temperature and the used exclusion radius.

get_volume
(self)¶ Get the volume to be used in the acceptance probability of the reaction ensemble.

get_wall_constraints_in_z_direction
(self)¶ Returns the restrictions of the sampling area in zdirection.

reaction
(self, reaction_steps=1)¶ Performs randomly selected reactions.
 Parameters
reaction_steps (
int
, optional) – The number of reactions to be performed at once, defaults to 1.

set_cylindrical_constraint_in_z_direction
(self, center_x, center_y, radius_of_cylinder)¶ Constrain the reaction moves within a cylinder defined by its axis passing through centres (\(x\) and \(y\)) and the radius. Requires setting the volume using
set_volume()
. Parameters
center_x (
float
) – x coordinate of center of the cylinder.center_y (
float
) – y coordinate of center of the cylinder.radius_of_cylinder (
float
) – radius of the cylinder

set_non_interacting_type
(self, non_interacting_type)¶ Sets the particle type for noninteracting 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 LennardJones and Coulomb interactions. Hiding of other interactions, for example a magnetic, needs to be implemented in the code.

set_volume
(self, volume)¶ 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.

set_wall_constraints_in_z_direction
(self, slab_start_z, slab_end_z)¶ Restrict the sampling area to a slab in zdirection. Requires setting the volume using
set_volume()
.

class
espressomd.reaction_ensemble.
ReactionEnsemble
(*args, **kwargs)¶ Bases:
espressomd.reaction_ensemble.ReactionAlgorithm
This class implements the Reaction Ensemble.

exception
espressomd.reaction_ensemble.
WangLandauHasConverged
¶ Bases:
Exception

class
espressomd.reaction_ensemble.
WangLandauReactionEnsemble
(*args, **kwargs)¶ Bases:
espressomd.reaction_ensemble.ReactionAlgorithm
This Class implements the WangLandau Reaction Ensemble.

add_collective_variable_degree_of_association
(self, *args, **kwargs)¶ Adds the degree of association as a collective variable (reaction coordinate) for the WangLandau Reaction Ensemble. Several collective variables can be set simultaneously.
 Parameters
associated_type (
int
) – Particle type of the associated state of the reacting species.min (
float
) – Minimum value of the collective variable.max (
float
) – Maximum value of the collective variable.corresponding_acid_types (list of
int
) – List of the types of the version of the species.

add_collective_variable_potential_energy
(self, *args, **kwargs)¶ Adds the potential energy as a collective variable (reaction coordinate) for the WangLandau 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 functionsupdate_maximum_and_minimum_energies_at_current_state()
andwrite_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.

displacement_mc_move_for_particles_of_type
(self, type_mc, particle_number_to_be_changed=1)¶ Performs an MC (Monte Carlo) move for
particle_number_to_be_changed
particle of typetype_mc
. Positions for the particles are drawn uniformly and randomly within the box. The command takes into account the WangLandau 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 WangLandau 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 configurationchanging moves need to be implemented in the case of using WangLandau with energy reweighting and a polymer in the system. Polymer configurationchanging moves had been implemented before but were removed from espresso.

load_wang_landau_checkpoint
(self)¶ Loads the dumped WangLandau potential file.

reaction
(self, reaction_steps=1)¶ Performs reaction_steps reactions. Sets the number of reaction steps which are performed at once. Do not use too many reaction steps consecutively without having conformationchanging steps inbetween (especially important for the WangLandau reaction ensemble). Providing a number for the parameter reaction steps reduces the need for the interpreter to be called between consecutive reactions.

set_wang_landau_parameters
(self, *args, **kwargs)¶ Sets the final WangLandau parameter.
 Parameters
final_wang_landau_parameter (
float
) – Sets the final WangLandau parameter, which is the WangLandau parameter after which the simulation should stop.full_path_to_output_filename (
str
) – Sets the path to the output file of the WangLandau algorithm which contains the WangLandau potentialdo_not_sample_reaction_partition_function (
bool
) – Avoids sampling the Reaction ensemble partition function in the WangLandau 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.

update_maximum_and_minimum_energies_at_current_state
(self)¶ Records the minimum and maximum potential energy as a function of the degree of association in a preliminary WangLandau 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.

write_out_preliminary_energy_run_results
(self)¶ This writes out the minimum and maximum potential energy as a function of the degree of association to a file. It requires that previously
update_maximum_and_minimum_energies_at_current_state()
was used.

write_wang_landau_checkpoint
(self)¶ Dumps the WangLandau potential to a checkpoint file. Can be used to checkpoint the WangLandau histogram, potential, parameter and the number of executed trial moves.

write_wang_landau_results_to_file
(self, filename)¶ This writes out the WangLandau potential as a function of the used collective variables.


class
espressomd.reaction_ensemble.
WidomInsertion
(*args, **kwargs)¶ Bases:
espressomd.reaction_ensemble.ReactionAlgorithm
This class implements the Widom insertion method in the canonical ensemble for homogeneous systems, where the excess chemical potential is not depending on the location.

measure_excess_chemical_potential
(self, reaction_id=0)¶ Measures the excess chemical potential in a homogeneous system for the provided
reaction_id
. Please define the insertion moves first by calling the methodadd_reaction()
(with only product types specified). Returns the excess chemical potential and the standard error for the excess chemical potential. The error estimate assumes that your samples are uncorrelated.

espressomd.scafacos module¶
Code shared by charge and dipole methods based on the SCAFACOS library.

class
espressomd.scafacos.
ScafacosConnector
¶ Bases:
espressomd.actors.Actor
Scafacos interface class shared by charge and dipole methods. Do not use directly.

default_params
(self)¶

get_params
(self)¶

required_keys
(self)¶

set_params
(self, params)¶

valid_keys
(self)¶

validate_params
(self)¶


espressomd.scafacos.
available_methods
()¶ Lists long range methods available in the Scafacos library.
espressomd.script_interface module¶

class
espressomd.script_interface.
PObjectId
¶ Bases:
object
Python interface to a core ObjectId object.

class
espressomd.script_interface.
PScriptInterface
(name=None, policy='GLOBAL', oid=None, **kwargs)¶ Bases:
object
Python interface to a core ScriptInterface object. The core ScriptInterface class is itself an interface for other core classes, such as constraints, shapes, observables, etc.
This class can be instantiated in two ways: (1) with the object id of an existing core ScriptInterface object, or (2) with parameters to construct a new ScriptInterface object in the core.
 Parameters
name (
str
) – Name of the core class to instantiate (method 1).**kwargs – Parameters for the core class constructor (method 1).
oid (
PObjectId
) – Object id of an existing core object (method 2).policy (
str
, {‘GLOBAL’, ‘LOCAL’}) – Creation policy.

sip
¶ Pointer to a ScriptInterface object in the core.
 Type
shared_ptr

policy_
¶ Creation policy.
 Type
str

call_method
(self, method, **kwargs)¶ Call a method of the core class.
 Parameters
method (Creation policy.) – Name of the core method.
**kwargs – Arguments for the method.

get_parameter
(self, name)¶

get_params
(self)¶

name
(self)¶ Return name of the core class.

set_params
(self, **kwargs)¶

set_sip_via_oid
(self, PObjectId id)¶ Set the shared_ptr to an existing core ScriptInterface object via its object id.

class
espressomd.script_interface.
ScriptInterfaceHelper
(**kwargs)¶ Bases:
espressomd.script_interface.PScriptInterface
Base class from which to derive most interfaces to core ScriptInterface classes.

define_bound_methods
(self)¶

generate_caller
(self, method_name)¶


class
espressomd.script_interface.
ScriptObjectRegistry
(**kwargs)¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Base class for containerlike classes such as
Constraints
andLBBoundaries
. Derived classes must implement anadd()
method which adds a single item to the container.The core class should derive from ScriptObjectRegistry or provide
"get_elements"
and"size"
as callable methods.

espressomd.script_interface.
init
()¶

espressomd.script_interface.
script_interface_register
(c)¶ Decorator used to register script interface classes. This will store a nametoclass relationship in a registry, so that parameters of type object can be instantiated as the correct python class
espressomd.shapes module¶

class
espressomd.shapes.
Cylinder
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A cylinder shape.

center
¶ Coordinates of the center of the cylinder.
 Type
(3,) array_like of
float

axis
¶ Axis of the cylinder.
 Type
(3,) array_like of
float

radius
¶ Radius of the cylinder.
 Type
float

length
¶ Length of the cylinder.
 Type
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int

open
¶ cylinder is open or has caps.
 Type
bool


class
espressomd.shapes.
Ellipsoid
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
An ellipsoid.
For now only ellipsoids of revolution are supported. The symmetry axis is aligned parallel to the xdirection.

center
¶ Coordinates of the center of the ellipsoid.
 Type
(3,) array_like of
float

a
¶ Semiaxis along the axis of rotational symmetry.
 Type
float

b
¶ Equatorial semiaxes.
 Type
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int


class
espressomd.shapes.
HollowCone
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A hollow cone shape.

inner_radius
¶ Inner radius of the cone.
 Type
float

outer_radius
¶ Outer radius of the cone.
 Type
float

opening_angle
¶ Opening angle of the cone (in rad).
 Type
float

axis
¶ Axis of symmetry, prescribes orientation of the cone.
 Type
(3,) array_like of
float

center
¶ Position of the cone.
 Type
(3,) array_like of
float

width
¶ Wall thickness of the cone.
 Type
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int


class
espressomd.shapes.
Rhomboid
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
An parallelepiped.

a
¶ First base vector.
 Type
(3,) array_like of
float

b
¶ Second base vector.
 Type
(3,) array_like of
float

c
¶ Third base vector.
 Type
(3,) array_like of
float

corner
¶ Lower left corner of the rhomboid.
 Type
(3,) array_like of
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int


class
espressomd.shapes.
SimplePore
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
Two parallel infinite planes, and a cylindrical channel connecting them. The cylinder and the planes are connected by torus segments with an adjustable radius.

radius
¶ The radius of the pore.
 Type
float

length
¶ The distance between the planes.
 Type
float

smoothing_radius
¶ Radius of the torus segments
 Type
float

axis
¶ Axis of the cylinder and normal of the planes
 Type
(3,) array_like of
float

center
¶ Position of the center of the cylinder.
 Type
(3,) array_like of
float


class
espressomd.shapes.
Slitpore
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper

channel_width
¶  Type
float

lower_smoothing_radius
¶  Type
float

pore_length
¶  Type
float

pore_mouth
¶  Type
float

pore_width
¶  Type
float

upper_smoothing_radius
¶  Type
float

dividing_plane
¶  Type
float


class
espressomd.shapes.
Sphere
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A sphere.

center
¶ Center of the sphere
 Type
(3,) array_like of
float

radius
¶ Radius of the sphere.
 Type
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int


class
espressomd.shapes.
SpheroCylinder
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A cylinder with hemispheres as caps.

center
¶ Coordinates of the center of the cylinder.
 Type
(3,) array_like of
float

axis
¶ Axis of the cylinder.
 Type
(3,) array_like of
float

radius
¶ Radius of the cylinder.
 Type
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int

length
¶ Length of the cylinder (not including the caps).
 Type
float


class
espressomd.shapes.
Stomatocyte
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper

inner_radius
¶ Inner radius of the stomatocyte.
 Type
float

outer_radius
¶ Outer radius of the stomatocyte.
 Type
float

axis
¶ Symmetry axis, prescribing the orientation of the stomatocyte.
 Type
(3,) array_like of
float

center
¶ Position of the stomatocyte.
 Type
(3,) array_like of
float

layer_width
¶ Scaling parameter.
 Type
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int


class
espressomd.shapes.
Torus
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A torus shape.

center
¶ Coordinates of the center of the torus.
 Type
(3,) array_like of
float

normal
¶ Normal axis of the torus.
 Type
(3,) array_like of
float

radius
¶ Radius of the torus.
 Type
float

tube_radius
¶ Radius of the tube.
 Type
float

direction
¶ Surface orientation, for +1 the normal points out of the mantel, for 1 it points inward.
 Type
int


class
espressomd.shapes.
Wall
(**kwargs)[source]¶ Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
An infinite plane.

dist
¶ Distance from the origin.
 Type
float

normal
¶ Normal vector of the plane (needs not to be length 1).
 Type
(3,) array_like of
int

espressomd.system module¶

class
espressomd.system.
System
(**kwargs)¶ Bases:
object
The espresso system class.
Note
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.
actors
¶ object
espressomd.actors.Actors
 Type
actors

analysis
¶ object
espressomd.analyze.Analysis
 Type
analysis

auto_exclusions
(self, distance)¶ Automatically adds exclusions between particles that are bonded.
This only considers pair bonds.
 Parameters
distance (
int
) – Bond distance upto which the exclusions should be added.

auto_update_accumulators
¶ object
espressomd.accumulators.AutoUpdateAccumulators
 Type
auto_update_accumulators

bonded_inter
¶ object
espressomd.interactions.BondedInteractions
 Type
bonded_inter

box_l
¶ (3,) array_like of
float
: Dimensions of the simulation box

cell_system
¶ object
espressomd.cellsystem.CellSystem
 Type
cell_system

change_volume_and_rescale_particles
(self, d_new, dir='xyz')¶ Change box size and rescale particle coordinates.
 Parameters
d_new (
float
) – New box lengthdir (
str
, optional) – Coordinate to work on,"x"
,"y"
,"z"
or"xyz"
for isotropic. Isotropic assumes a cubic box.

collision_detection
¶ object
espressomd.collision_detection.CollisionDetection
 Type
collision_detection

comfixed
¶ object
espressomd.comfixed.ComFixed
 Type
comfixed

constraints
¶ object
espressomd.constraints.Constraints
 Type
constraints

cuda_init_handle
¶ object
espressomd.cuda_init.CudaInitHandle
 Type
cuda_init_handle

distance
(self, p1, p2)¶ Return the scalar distance between the particles, respecting periodic boundaries.

distance_vec
(self, p1, p2)¶ Return the distance vector between the particles, respecting periodic boundaries.

ekboundaries
¶ object
espressomd.ekboundaries.EKBoundaries
 Type
ekboundaries

force_cap
¶ float
: If > 0, the magnitude of the force on the particles are capped to this value.

galilei
¶ object
espressomd.galilei.GalileiTransform
 Type
galilei

globals
¶ object
espressomd.globals.Globals
 Type
globals

integ_switch
¶

integrator
¶ object
espressomd.integrate.Integrator
 Type
integrator

lbboundaries
¶ object
espressomd.lbboundaries.LBBoundaries
 Type
lbboundaries

max_cut_bonded
¶

max_cut_nonbonded
¶

max_oif_objects
¶ Maximum number of objects as per the object_in_fluid method.

min_global_cut
¶

minimize_energy
¶ object
espressomd.minimize_energy.MinimizeEnergy
 Type
minimize_energy

non_bonded_inter
¶ object
espressomd.interactions.NonBondedInteractions
 Type
non_bonded_inter

number_of_particles
(self, type=None)¶  Parameters
type (
int
(type
)) – Particle type to count the number for. Returns
The number of particles which have the given type.
 Return type
int

part
¶ object
espressomd.particle_data.ParticleList
 Type
part

periodicity
¶ (3,) array_like of
bool
: System periodicity in[x, y, z]
,False
for no periodicity in this direction,True
for periodicity

random_number_generator_state
¶ Sets the random number generator state in the core. This is of interest for deterministic checkpointing.

rotate_system
(self, **kwargs)¶ Rotate the particles in the system about the center of mass.
If
ROTATION
is activated, the internal rotation degrees of freedom are rotated accordingly. Parameters
phi (
float
) – Angle between the zaxis and the rotation axis.theta (
float
) – Rotation of the axis around the yaxis.alpha (
float
) – How much to rotate

seed
¶ Sets the seed of the pseudo random number with a list of seeds which is as long as the number of used nodes.

set_random_state_PRNG
(self)¶ Sets the state of the pseudo random number generator using real random numbers.

setup_type_map
(self, type_list=None)¶ 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.

thermostat
¶ object
espressomd.thermostat.Thermostat
 Type
thermostat

time
¶ Set the time in the simulation

time_step
¶ Sets the time step for the integrator.

timings
¶

virtual_sites
¶

volume
(self)¶ Return box volume of the cuboid box.

espressomd.thermostat module¶

espressomd.thermostat.
AssertThermostatType
(*allowedthermostats)¶ Assert that only a certain group of thermostats is active at a time.
Decorator class to ensure that only specific combinations of thermostats can be activated together by the user. Usage:
cdef class Thermostat: @AssertThermostatType(THERMO_LANGEVIN, THERMO_DPD) def set_langevin(self, kT=None, gamma=None, gamma_rotation=None, act_on_virtual=False, seed=None): ...
This will prefix an assertion that prevents setting up the Langevin thermostat if the list of active thermostats contains anything other than the DPD and Langevin thermostats.
 Parameters
allowedthermostats (
str
) – Allowed list of thermostats which are known to be compatible with one another.

class
espressomd.thermostat.
Thermostat
¶ Bases:
object

get_state
(self)¶ Returns the thermostat status.

get_ts
(self)¶

recover
(self)¶ Recover a suspended thermostat
If the thermostat had been suspended using
suspend()
, it can be recovered with this method.

set_dpd
(self, kT=None, seed=None)¶ Sets the DPD thermostat with required parameters ‘kT’. This also activates the DPD interactions.
 Parameters
kT (
float
) – Thermal energy of the heat bath.seed (
int
) – Initial counter value (or seed) of the philox RNG. Required on first activation of the DPD thermostat. Must be positive.

set_langevin
(self, kT=None, gamma=None, gamma_rotation=None, act_on_virtual=False, seed=None)¶ Sets the Langevin thermostat.
 Parameters
kT (
float
) – Thermal energy of the simulated heat bath.gamma (
float
) – Contains the friction coefficient of the bath. If the featurePARTICLE_ANISOTROPY
is compiled in, thengamma
can be a list of three positive floats, for the friction coefficient in each cardinal direction.gamma_rotation (
float
, optional) – The same applies togamma_rotation
, which requires the featureROTATION
to work properly. But also accepts three floats ifPARTICLE_ANISOTROPY
is also compiled in.act_on_virtual (
bool
, optional) – IfTrue
the thermostat will act on virtual sites, default isFalse
.seed (
int
) – Initial counter value (or seed) of the philox RNG. Required on first activation of the Langevin thermostat. Must be positive.

set_lb
(self, seed=None, act_on_virtual=True, LB_fluid=None, gamma=0.0)¶ Sets the LB thermostat.
This thermostat requires the feature
LBFluid
orLBFluidGPU
. Parameters
LB_fluid (
LBFluid
orLBFluidGPU
)seed (
int
) – Seed for the random number generator, required if kT > 0. Must be positive.act_on_virtual (
bool
, optional) – IfTrue
the thermostat will act on virtual sites (default).gamma (
float
) – Frictional coupling constant for the MD particle coupling.

set_npt
(self, kT=None, gamma0=None, gammav=None)¶ Sets the NPT thermostat.
 Parameters
kT (
float
) – Thermal energy of the heat bathgamma0 (
float
) – Friction coefficient of the bathgammav (
float
) – Artificial friction coefficient for the volume fluctuations.

suspend
(self)¶ Suspend the thermostat
The thermostat can be suspended, e.g. to perform an energy minimization.

turn_off
(self)¶ Turns off all the thermostat and sets all the thermostat variables to zero.

espressomd.utils module¶

class
espressomd.utils.
array_locked
(input_array)¶ Bases:
numpy.ndarray
Returns a nonwritable numpy.ndarray with a special error message upon usage of __setitem__ or inplace operators. Cast return in __get__ of array properties to array_locked to prevent these operations.

ERR_MSG
= 'ESPResSo array properties return nonwritable arrays and can only be modified as a whole, not inplace or componentwise. Use numpy.copy(<ESPResSo array property>) to get a writable copy.'¶


espressomd.utils.
check_type_or_throw_except
(x, n, t, msg)¶ 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.

espressomd.utils.
handle_errors
(msg)¶ Gathers runtime errors.
 Parameters
msg (
str
) – Error message that is to be raised.

espressomd.utils.
is_valid_type
(value, t)¶ Extended checks for numpy int and float types.

espressomd.utils.
nesting_level
(obj)¶ Returns the maximal nesting level of an object.

espressomd.utils.
requires_experimental_features
(reason)¶ Class decorator which makes instantiation conditional on
EXPERIMENTAL_FEATURES
being defined in myconfig.hpp.

espressomd.utils.
to_char_pointer
(s)¶ Returns a char pointer which contains the information of the provided python string.
 Parameters
s (
str
)

espressomd.utils.
to_str
(s)¶ Returns a python string.
 Parameters
s (char*)
espressomd.version module¶

espressomd.version.
friendly
()¶ Dot version of the version.

espressomd.version.
git_branch
()¶ Git branch of the build if known, otherwise empty.

espressomd.version.
git_commit
()¶ Git commit of the build if known, otherwise empty.

espressomd.version.
git_state
()¶ Git state of the build if known, otherwise empty. State is “CLEAN” if the repository was not changed from git_commit(), “DIRTY” otherwise.

espressomd.version.
major
()¶ Prints the major version of Espresso.

espressomd.version.
minor
()¶ Prints the minor version of Espresso.
espressomd.virtual_sites module¶

class
espressomd.virtual_sites.
ActiveVirtualSitesHandle
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Handle for the virtual sites implementation active in the core
This should not be used directly.

implementation
¶ instance of a virtual sites implementation


class
espressomd.virtual_sites.
VirtualSitesInertialessTracers
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Virtual sites which are advected with an lb fluid without inertia. Forces are on them are transferred to the fluid instantly.

class
espressomd.virtual_sites.
VirtualSitesOff
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Virtual sites implementation which does nothing (default)

class
espressomd.virtual_sites.
VirtualSitesRelative
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Virtual sites implementation placing virtual sites relative to other particles. See Rigid arrangements of particles for details.
Attributes can be set on the instance or passed to the constructor as keyword arguments.

have_velocity
¶ Determines whether the velocity of the virtual sites is calculated. This carries a performance cost.
 Type
bool

espressomd.visualization module¶

class
espressomd.visualization.
mayaviLive
(system, particle_sizes='auto')¶ Bases:
object
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
start()
in your main thread to be able to interact with the GUI. Parameters
system (
espressomd.system.System
)particle_sizes (function, list, or dict (optional)) – object which maps particle types to radii

processGuiEvents
(self)¶ Process GUI events, e.g. mouse clicks, in the Mayavi window.
Call this function as often as you can to get a smooth GUI experience.

register_callback
(self, cb, interval=1000)¶

run
(self, integ_steps=1)¶ Convenience method with a simple integration thread.

start
(self)¶ Start the GUI event loop.
This function blocks until the Mayavi window is closed. So you should only use it if your Espresso simulation’s integrate loop is running in a secondary thread.

update
(self)¶ Pull the latest particle information from Espresso.
This is the only function that should be called from the computation thread. It does not call any Mayavi functions unless it is being called from the main (GUI) thread.

class
espressomd.visualization.
openGLLive
(system, **kwargs)¶ Bases:
object
This class provides live visualization using pyOpenGL. Use the update method to push your current simulation state after integrating. Modify the appearance with a list of keywords. Timed callbacks can be registered via the
register_callback()
method and keyboard callbacks viakeyboardManager.register_button()
. Parameters
system (
espressomd.system.System
)window_size ((2,) array_like of
int
, optional) – Size of the visualizer window in pixels.name (
str
, optional) – The name of the visualizer window.background_color ((3,) array_like of
int
, optional) – RGB of the background.periodic_images ((3,) array_like of
int
, optional) – Periodic repetitions on both sides of the box in xyzdirection.draw_box (
bool
, optional) – Draw wireframe boundaries.draw_axis (
bool
, optional) – Draw xyz system axes.draw_nodes (
bool
, optional) – Draw node boxes.draw_cells (
bool
, optional) – Draw cell boxes.quality_particles (
int
, optional) – The number of subdivisions for particle spheres.quality_bonds (
int
, optional) – The number of subdivisions for cylindrical bonds.quality_arrows (
int
, optional) – The number of subdivisions for external force arrows.quality_constraints (
int
, optional) – The number of subdivisions for primitive constraints.close_cut_distance (
float
, optional) – The distance from the viewer to the near clipping plane.far_cut_distance (
float
, optional) – The distance from the viewer to the far clipping plane.camera_position (
str
or (3,) array_like offloat
, optional) – Initial camera position. Use'auto'
(default) for shifted position in zdirection.camera_target (
str
or (3,) array_like offloat
, optional) – Initial camera target. Use'auto'
(default) to look towards the system center.camera_right ((3,) array_like of
float
, optional) – Camera right vector in system coordinates. Default is[1, 0, 0]
particle_sizes (
str
or array_likefloat
or callable, optional) –'auto'
(default): The LennardJones sigma value of the selfinteraction 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_coloring (
str
, optional) –'auto'
(default): Colors of charged particles are specified byparticle_charge_colors
, neutral particles byparticle_type_colors
.'charge'
: Minimum and maximum charge of all particles is determined by the visualizer. All particles are colored by a linear interpolation of the two colors given byparticle_charge_colors
according to their charge.'type'
: Particle colors are specified byparticle_type_colors
, indexed by their numerical particle type.'node'
: Color according to the node the particle is on.
particle_type_colors (array_like
float
, optional) – Colors for particle types.particle_type_materials (
str
, optional) – Materials of the particle types.particle_charge_colors ((2,) array_like of
float
, optional) – Two colors for min/max charged particles.draw_constraints (
bool
, optional) – Enables constraint visualization. For simple constraints (planes, spheres and cylinders), OpenGL primitives are used. Otherwise, visualization by rasterization is used.rasterize_pointsize (
float
, optional) – Point size for the rasterization dots.rasterize_resolution (
float
, optional) – Accuracy of the rasterization.quality_constraints (
int
, optional) – The number of subdivisions for primitive constraints.constraint_type_colors (array_like
float
, optional) – Colors of the constraints by type.constraint_type_materials (array_like
str
, optional) – Materials of the constraints by type.draw_bonds (
bool
, optional) – Enables bond visualization.bond_type_radius (array_like
float
, optional) – Radii of bonds by type.bond_type_colors (array_like
float
, optional) – Color of bonds by type.bond_type_materials (array_like
float
, optional) – Materials of bonds by type.ext_force_arrows (
bool
, optional) – Enables external force visualization.ext_force_arrows_type_scale (array_like
float
, optional) – List of scale factors of external force arrows for different particle types.ext_force_arrows_type_colors (array_like
float
, optional) – Colors of ext_force arrows for different particle types.ext_force_arrows_type_materials (array_like
float
, optional) – Materials of ext_force arrows for different particle types.ext_force_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.force_arrows (
bool
, optional) – Enables particle force visualization.force_arrows_type_scale (array_like
float
, optional) – List of scale factors of particle force arrows for different particle types.force_arrows_type_colors (array_like
float
, optional) – Colors of particle force arrows for different particle types.force_arrows_type_materials (array_like
float
, optional) – Materials of particle force arrows for different particle types.force_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.velocity_arrows (
bool
, optional) – Enables particle velocity visualization.velocity_arrows_type_scale (array_like
float
, optional) – List of scale factors of particle velocity arrows for different particle types.velocity_arrows_type_colors (array_like
float
, optional) – Colors of particle velocity arrows for different particle types.velocity_arrows_type_materials (array_like
float
, optional) – Materials of particle velocity arrows for different particle types.velocity_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.director_arrows (
bool
, optional) – Enables particle director visualization.director_arrows_type_scale (
float
, optional) – Scale factor of particle director arrows for different particle types.director_arrows_type_colors (array_like
float
, optional) – Colors of particle director arrows for different particle types.director_arrows_type_materials (array_like
float
, optional) – Materials of particle director arrows for different particle types.director_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.drag_enabled (
bool
, optional) – Enables mousecontrolled particles dragging (Default: False)drag_force (
bool
, optional) – Factor for particle draggingLB_draw_nodes (
bool
, optional) – Draws a lattice representation of the LB nodes that are no boundaries.LB_draw_node_boundaries (
bool
, optional) – Draws a lattice representation of the LB nodes that are boundaries.LB_draw_boundaries (
bool
, optional) – Draws the LB shapes.LB_draw_velocity_plane (
bool
, optional) – Draws LB node velocity arrows specified by LB_plane_axis, LB_plane_dist, LB_plane_ngrid.light_pos ((3,) array_like of
float
, optional) – If auto (default) is used, the light is placed dynamically in the particle barycenter of the system. Otherwise, a fixed coordinate can be set.light_colors (array_like
float
, optional) – Three lists to specify ambient, diffuse and specular light colors.light_brightness (
float
, optional) – Brightness (inverse constant attenuation) of the light.light_size (
float
, optional) – Size (inverse linear attenuation) of the light. If auto (default) is used, the light size will be set to a reasonable value according to the box size at start.spotlight_enabled (
bool
, optional) – If set to True (default), it enables a spotlight on the camera position pointing in look direction.spotlight_colors (array_like
float
, optional) – Three lists to specify ambient, diffuse and specular spotlight colors.spotlight_angle (
float
, optional) – The spread angle of the spotlight in degrees (from 0 to 90).spotlight_brightness (
float
, optional) – Brightness (inverse constant attenuation) of the spotlight.spotlight_focus (
float
, optional) – Focus (spot exponent) for the spotlight from 0 (uniform) to 128.

materials
= {'bright': [0.9, 1.0, 0.8, 0.4, 1.0], 'chrome': [0.25, 0.4, 0.774597, 0.6, 1.0], 'dark': [0.4, 0.5, 0.1, 0.4, 1.0], 'medium': [0.6, 0.8, 0.2, 0.4, 1.0], 'plastic': [0, 0.55, 0.7, 0.25, 1.0], 'rubber': [0, 0.4, 0.7, 0.078125, 1.0], 'steel': [0.25, 0.38, 0, 0.32, 1.0], 'transparent1': [0.6, 0.8, 0.2, 0.5, 0.8], 'transparent2': [0.6, 0.8, 0.2, 0.5, 0.4], 'transparent3': [0.6, 0.8, 0.2, 0.5, 0.2]}¶

register_callback
(self, cb, interval=1000)¶ Register timed callbacks.

run
(self, integ_steps=1)¶ Convenience method with a simple integration thread.

screenshot
(self, path)¶ Renders the current state into an image file at
path
with dimensions ofspecs['window_size']
in PNG format.

start
(self)¶ The blocking start method.

update
(self)¶ Update method to be called after integration. Changes of espresso system can only happen here.

update_system_info
(self)¶
espressomd.visualization_mayavi module¶

class
espressomd.visualization_mayavi.
mayaviLive
(system, particle_sizes='auto')¶ Bases:
object
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
start()
in your main thread to be able to interact with the GUI. Parameters
system (
espressomd.system.System
)particle_sizes (function, list, or dict (optional)) – object which maps particle types to radii

processGuiEvents
(self)¶ Process GUI events, e.g. mouse clicks, in the Mayavi window.
Call this function as often as you can to get a smooth GUI experience.

register_callback
(self, cb, interval=1000)¶

run
(self, integ_steps=1)¶ Convenience method with a simple integration thread.

start
(self)¶ Start the GUI event loop.
This function blocks until the Mayavi window is closed. So you should only use it if your Espresso simulation’s integrate loop is running in a secondary thread.

update
(self)¶ Pull the latest particle information from Espresso.
This is the only function that should be called from the computation thread. It does not call any Mayavi functions unless it is being called from the main (GUI) thread.
espressomd.visualization_opengl module¶

class
espressomd.visualization_opengl.
Camera
¶ Bases:
object

get_camera_rotation_matrix
(self, target_vec, up_vec)¶

move_backward
(self)¶

move_down
(self)¶

move_forward
(self)¶

move_left
(self)¶

move_right
(self)¶

move_up
(self)¶

normalize
(self, vec)¶

normalized
(self, vec)¶

rotate_camera
(self, mousePos, mousePosOld, mouseButtonState)¶

rotate_system_XL
(self)¶

rotate_system_XR
(self)¶

rotate_system_YL
(self)¶

rotate_system_YR
(self)¶

rotate_system_ZL
(self)¶

rotate_system_ZR
(self)¶

rotate_system_x
(self, da)¶

rotate_system_y
(self, da)¶

rotate_system_z
(self, da)¶

rotate_vector
(self, vec, ang, axe)¶

set_camera
(self, camPos=<???>, camTarget=<???>, camRight=<???>, moveSpeed=0.5, rotSpeed=0.001, globalRotSpeed=3.0, center=<???>)¶

update_modelview
(self)¶


class
espressomd.visualization_opengl.
KeyboardButtonEvent
(button, fireEvent, callback, internal=False)¶ Bases:
object
Keyboard event used for keyboard callbacks. Stores button, event type and callback.

class
espressomd.visualization_opengl.
KeyboardFireEvent
¶ Bases:
object
Event type of button used for keyboard callbacks.

Hold
= 1¶

Pressed
= 0¶

Released
= 2¶


class
espressomd.visualization_opengl.
KeyboardManager
¶ Bases:
object
Handles keyboard callbacks.

handle_input
(self)¶

keyboard_down
(self, button)¶

keyboard_up
(self, button)¶
Register keyboard input callbacks.


class
espressomd.visualization_opengl.
MouseButtonEvent
(button, fireEvent, callback, positional=False)¶ Bases:
object
Mouse event used for mouse callbacks. Stores button and callback.

class
espressomd.visualization_opengl.
MouseFireEvent
¶ Bases:
object
Event type of mouse button used for mouse callbacks.

ButtonMotion
= 2¶

ButtonPressed
= 0¶

ButtonReleased
= 3¶

DoubleClick
= 4¶

FreeMotion
= 1¶


class
espressomd.visualization_opengl.
MouseManager
¶ Bases:
object
Handles mouse callbacks.

mouse_click
(self, button, state, x, y)¶

mouse_move
(self, x, y)¶
Register mouse input callbacks.


class
espressomd.visualization_opengl.
Quaternion
(x, y, z, w)¶ Bases:
object

conjugated
(self)¶

mult_q
(self, q)¶

mult_v
(self, v)¶


espressomd.visualization_opengl.
draw_arrow
(pos, d, radius, color, material, quality)¶

espressomd.visualization_opengl.
draw_box
(p0, s, color, material, width)¶

espressomd.visualization_opengl.
draw_cylinder
(posA, posB, radius, color, material, quality, draw_caps=False)¶

espressomd.visualization_opengl.
draw_ellipsoid
(pos, semiaxis_a, semiaxis_b, semiaxis_c, color, material, quality)¶

espressomd.visualization_opengl.
draw_plane
(corners, color, material)¶

espressomd.visualization_opengl.
draw_points
(points, pointsize, color, material)¶

espressomd.visualization_opengl.
draw_simple_pore
(center, axis, length, radius, smoothing_radius, max_box_l, color, material, quality)¶

espressomd.visualization_opengl.
draw_slitpore
(channel_width, lower_smoothing_radius, upper_smoothing_radius, pore_length, pore_mouth, pore_width, dividing_plane, max_box_l, color, material, quality)¶

espressomd.visualization_opengl.
draw_sphere
(pos, radius, color, material, quality)¶

espressomd.visualization_opengl.
draw_sphero_cylinder
(posA, posB, radius, color, material, quality)¶

espressomd.visualization_opengl.
get_extra_clip_plane
()¶

class
espressomd.visualization_opengl.
openGLLive
(system, **kwargs)¶ Bases:
object
This class provides live visualization using pyOpenGL. Use the update method to push your current simulation state after integrating. Modify the appearance with a list of keywords. Timed callbacks can be registered via the
register_callback()
method and keyboard callbacks viakeyboardManager.register_button()
. Parameters
system (
espressomd.system.System
)window_size ((2,) array_like of
int
, optional) – Size of the visualizer window in pixels.name (
str
, optional) – The name of the visualizer window.background_color ((3,) array_like of
int
, optional) – RGB of the background.periodic_images ((3,) array_like of
int
, optional) – Periodic repetitions on both sides of the box in xyzdirection.draw_box (
bool
, optional) – Draw wireframe boundaries.draw_axis (
bool
, optional) – Draw xyz system axes.draw_nodes (
bool
, optional) – Draw node boxes.draw_cells (
bool
, optional) – Draw cell boxes.quality_particles (
int
, optional) – The number of subdivisions for particle spheres.quality_bonds (
int
, optional) – The number of subdivisions for cylindrical bonds.quality_arrows (
int
, optional) – The number of subdivisions for external force arrows.quality_constraints (
int
, optional) – The number of subdivisions for primitive constraints.close_cut_distance (
float
, optional) – The distance from the viewer to the near clipping plane.far_cut_distance (
float
, optional) – The distance from the viewer to the far clipping plane.camera_position (
str
or (3,) array_like offloat
, optional) – Initial camera position. Use'auto'
(default) for shifted position in zdirection.camera_target (
str
or (3,) array_like offloat
, optional) – Initial camera target. Use'auto'
(default) to look towards the system center.camera_right ((3,) array_like of
float
, optional) – Camera right vector in system coordinates. Default is[1, 0, 0]
particle_sizes (
str
or array_likefloat
or callable, optional) –'auto'
(default): The LennardJones sigma value of the selfinteraction 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_coloring (
str
, optional) –'auto'
(default): Colors of charged particles are specified byparticle_charge_colors
, neutral particles byparticle_type_colors
.'charge'
: Minimum and maximum charge of all particles is determined by the visualizer. All particles are colored by a linear interpolation of the two colors given byparticle_charge_colors
according to their charge.'type'
: Particle colors are specified byparticle_type_colors
, indexed by their numerical particle type.'node'
: Color according to the node the particle is on.
particle_type_colors (array_like
float
, optional) – Colors for particle types.particle_type_materials (
str
, optional) – Materials of the particle types.particle_charge_colors ((2,) array_like of
float
, optional) – Two colors for min/max charged particles.draw_constraints (
bool
, optional) – Enables constraint visualization. For simple constraints (planes, spheres and cylinders), OpenGL primitives are used. Otherwise, visualization by rasterization is used.rasterize_pointsize (
float
, optional) – Point size for the rasterization dots.rasterize_resolution (
float
, optional) – Accuracy of the rasterization.quality_constraints (
int
, optional) – The number of subdivisions for primitive constraints.constraint_type_colors (array_like
float
, optional) – Colors of the constraints by type.constraint_type_materials (array_like
str
, optional) – Materials of the constraints by type.draw_bonds (
bool
, optional) – Enables bond visualization.bond_type_radius (array_like
float
, optional) – Radii of bonds by type.bond_type_colors (array_like
float
, optional) – Color of bonds by type.bond_type_materials (array_like
float
, optional) – Materials of bonds by type.ext_force_arrows (
bool
, optional) – Enables external force visualization.ext_force_arrows_type_scale (array_like
float
, optional) – List of scale factors of external force arrows for different particle types.ext_force_arrows_type_colors (array_like
float
, optional) – Colors of ext_force arrows for different particle types.ext_force_arrows_type_materials (array_like
float
, optional) – Materials of ext_force arrows for different particle types.ext_force_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.force_arrows (
bool
, optional) – Enables particle force visualization.force_arrows_type_scale (array_like
float
, optional) – List of scale factors of particle force arrows for different particle types.force_arrows_type_colors (array_like
float
, optional) – Colors of particle force arrows for different particle types.force_arrows_type_materials (array_like
float
, optional) – Materials of particle force arrows for different particle types.force_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.velocity_arrows (
bool
, optional) – Enables particle velocity visualization.velocity_arrows_type_scale (array_like
float
, optional) – List of scale factors of particle velocity arrows for different particle types.velocity_arrows_type_colors (array_like
float
, optional) – Colors of particle velocity arrows for different particle types.velocity_arrows_type_materials (array_like
float
, optional) – Materials of particle velocity arrows for different particle types.velocity_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.director_arrows (
bool
, optional) – Enables particle director visualization.director_arrows_type_scale (
float
, optional) – Scale factor of particle director arrows for different particle types.director_arrows_type_colors (array_like
float
, optional) – Colors of particle director arrows for different particle types.director_arrows_type_materials (array_like
float
, optional) – Materials of particle director arrows for different particle types.director_arrows_type_radii (array_like
float
, optional) – List of arrow radii for different particle types.drag_enabled (
bool
, optional) – Enables mousecontrolled particles dragging (Default: False)drag_force (
bool
, optional) – Factor for particle draggingLB_draw_nodes (
bool
, optional) – Draws a lattice representation of the LB nodes that are no boundaries.LB_draw_node_boundaries (
bool
, optional) – Draws a lattice representation of the LB nodes that are boundaries.LB_draw_boundaries (
bool
, optional) – Draws the LB shapes.LB_draw_velocity_plane (
bool
, optional) – Draws LB node velocity arrows specified by LB_plane_axis, LB_plane_dist, LB_plane_ngrid.light_pos ((3,) array_like of
float
, optional) – If auto (default) is used, the light is placed dynamically in the particle barycenter of the system. Otherwise, a fixed coordinate can be set.light_colors (array_like
float
, optional) – Three lists to specify ambient, diffuse and specular light colors.light_brightness (
float
, optional) – Brightness (inverse constant attenuation) of the light.light_size (
float
, optional) – Size (inverse linear attenuation) of the light. If auto (default) is used, the light size will be set to a reasonable value according to the box size at start.spotlight_enabled (
bool
, optional) – If set to True (default), it enables a spotlight on the camera position pointing in look direction.spotlight_colors (array_like
float
, optional) – Three lists to specify ambient, diffuse and specular spotlight colors.spotlight_angle (
float
, optional) – The spread angle of the spotlight in degrees (from 0 to 90).spotlight_brightness (
float
, optional) – Brightness (inverse constant attenuation) of the spotlight.spotlight_focus (
float
, optional) – Focus (spot exponent) for the spotlight from 0 (uniform) to 128.

materials
= {'bright': [0.9, 1.0, 0.8, 0.4, 1.0], 'chrome': [0.25, 0.4, 0.774597, 0.6, 1.0], 'dark': [0.4, 0.5, 0.1, 0.4, 1.0], 'medium': [0.6, 0.8, 0.2, 0.4, 1.0], 'plastic': [0, 0.55, 0.7, 0.25, 1.0], 'rubber': [0, 0.4, 0.7, 0.078125, 1.0], 'steel': [0.25, 0.38, 0, 0.32, 1.0], 'transparent1': [0.6, 0.8, 0.2, 0.5, 0.8], 'transparent2': [0.6, 0.8, 0.2, 0.5, 0.4], 'transparent3': [0.6, 0.8, 0.2, 0.5, 0.2]}¶

register_callback
(self, cb, interval=1000)¶ Register timed callbacks.

run
(self, integ_steps=1)¶ Convenience method with a simple integration thread.

screenshot
(self, path)¶ Renders the current state into an image file at
path
with dimensions ofspecs['window_size']
in PNG format.

start
(self)¶ The blocking start method.

update
(self)¶ Update method to be called after integration. Changes of espresso system can only happen here.

update_system_info
(self)¶

espressomd.visualization_opengl.
rotation_helper
(d)¶

espressomd.visualization_opengl.
set_solid_material
(color, material=[0.6, 1.0, 0.1, 0.4, 1.0])¶