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

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

class
espressomd.accumulators.
Correlator
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Calculates correlations based on results from observables.
Parameters:  obs2 (obs1,) – The observables A and B that are to be correlated. If obs2 is omitted, autocorrelation of obs1 is calculated by default.
 corr_operation –
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\) is 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\).
 complex_conjugate_product: assuming that the observables
consist of a complex and real part
\(A=(A_x+iA_y)\), and \(B=(B_x+iB_y)\), this
operation computes the result \(C=(C_x+iC_y)\),
as:\[\begin{split}C_x = A_xB_x + A_yB_y\\ C_y = A_yB_x  A_xB_y\end{split}\]
 delta_N :
int
 Number of timesteps between subsequent samples for the auto update mechanism.
 tau_max :
float
 This is the maximum value of :math:` au` for which the correlation should be computed. Warning: Unless you are using the multiple tau correlator, choosing tau_max of more than 100`dt` will result in a huge computational overhead. In a multiple tau correlator with reasonable parameters, tau_max can span the entire simulation without too much additional cpu time.
 tau_lin :
int
 The number of 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. By default, it is set equal to tau_max which results in the trivial linear correlator. By setting tau_lin < tau_max the multiple tau correlator is switched on. In many cases, tau_lin`=16 is a good choice but this may strongly depend on the observables you are correlating. For more information, we recommend to read Ref. :cite:`ramirez10a or to perform your own tests.
 compress1 and compress2 :
str
These functions are used to compress the data when going to the next level of the multiple tau correlator. This is done by producing one value out of two. The following compression functions are available:
 discard2: (default value) discard the second value from the time series, use the first value as the result
 discard1: discard the first value from the time series, use the second value as the result
 linear: make a linear combination (average) of the two values
If only compress1 is specified, then the same compression function is used for both observables. If both compress1 and compress2 are specified, then compress1 is used for obs1 and compress2 for obs2.
Both discard1 and discard2 are safe for all observables but produce poor statistics in the tail. For some observables, linear compression can be used which makes an average of two neighboring values but produces systematic errors. Depending on the observable, the systematic error using the linear compression can be anything between harmless and disastrous. For more information, we recommend to read Ref. [RSVL10] or to perform your own tests.
 args:
float[3]
 Three floats which are passed as arguments to the correlation function. Currently it is only used by fcs_acf. Other correlation operations will ignore these values.

class
espressomd.accumulators.
MeanVarianceCalculator
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Accumulates results from observables.
Parameters:  obs (Instance of
espressomd.observables.Observable
.) –  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).

get_mean
()¶ Returns the samples mean values of the respective observable with which the accumulator was initialized.

get_variance
()¶ Returns the samples variance for the observable.
 obs (Instance of
espressomd.actors module¶

class
espressomd.actors.
Actor
(*args, **kwargs)¶ Bases:
object

active_list
= {'ElectrostaticExtensions': False, '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 the instance still matches what is in Espresso

required_keys
(self)¶ Virtual method.

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

system
¶ system – object

valid_keys
(self)¶ Virtual method.

validate_params
(self)¶ Virtual method.


class
espressomd.actors.
Actors
¶ Bases:
object

active_actors
= []¶

add
(self, actor)¶ Parameters: actor (instance of espressomd.actors.Actor
) –

clear
(self)¶ Remove all actors.

remove
(self, actor)¶ Parameters: actor (instance of espressomd.actors.Actor
) –

espressomd.analyze module¶

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

analyze_linear_momentum
(self, include_particles=True, include_lbfluid=True)¶ Calculates the systems 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 Lattice Boltzmann fluid contribution to the linear momentum.
Returns: The linear momentum of the system.
Return type: float
 include_particles (

angular_momentum
(self, p_type=None)¶

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 with particle number
chain_start
and are consecutively numbered, the last particle in that topology has id number\[``chain_start`` + ``number_of_chains`` * ``chain_length`` 1.\]Parameters:  chain_start (
int
) – The id of the first monomer of the first chain.  number_of_chains (
int
) – Number of chains contained in the range.  chain_length (
int
) – The length of every chain.
Returns: array_like – 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: float
 chain_start (

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 with particle number
chain_start
and are consecutively numbered, the last particle in that topology has id numberParameters:  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: array_like – 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: float
 chain_start (

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 with particle number chain_start and are consecutively numbered (the last particle in that topology has id number : chain_start`+ `number_of_chains`*`chain_length1.
Parameters:  chain_start (
int
.) – The id of the first monomer of the first chain  number_of_chains (
int
.) – Number of chains contained in the range.  chain_length (
int
.) – The length of every chain.
Returns: Where [0] is the mean hydrodynamic radius of the chains and [1] its standard deviation,
Return type: array_like
 chain_start (

center_of_mass
(self, p_type=None)¶ Calculates the systems center of mass.
Parameters: p_type ( int
(espressomd.particle_data.ParticleHandle.type
)) – Particle type 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 (array_like
float
) – Coordinates of the centre of the cylinder.  axis (array_like
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
(espressomd.particle_data.ParticleHandle.type
)) – A list of type IDs.
Returns: columns indicate index_radial, index_axial, pos_radial, pos_axial, binvolume, density, v_radial, v_axial, density, v_radial and v_axial. Note that the columns density, v_radial and v_axial appear for each type indicated in types in the same order.
Return type: list of lists
 center (array_like

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

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 at a certain distance around a particle of type , disregarding the fact that a spherical shell of a larger radius covers a larger volume) The distance is defined as the minimal distance between a particle of group type_list_a to any of the group type_list_b. Returns two arrays, the bins and the (normalized) distribution.
Parameters:  type_list_a (list of
int
(espressomd.particle_data.ParticleHandle.type
)) – List of particle types, only consider distances from these types.  type_list_b (list of
int
(espressomd.particle_data.ParticleHandle.type
)) – List of particle types, 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: array_like
 type_list_a (list of

energy
(self)¶ Calculate the systems energy.
Returns: Return type: dict
{‘total’, ‘kinetic’, ‘bonded’, ‘nonbonded’, [‘coulomb’], ‘external_fields’}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
(espressomd.particle_data.ParticleHandle.type
), optional) – A particle type, 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.

local_stress_tensor
(self, periodicity=(1, 1, 1), range_start=(0.0, 0.0, 0.0), stress_range=(1.0, 1.0, 1.0), bins=(1, 1, 1))¶ local_stress_tensor(periodicity=(1, 1, 1), range_start=(0.0, 0.0, 0.0), stress_range=(1.0, 1.0, 1.0), bins=(1, 1, 1))

min_dist
(self, p1='default', p2='default')¶ Minimal distance between two sets of particles.
Parameters: p2 (p1,) –

min_dist2
(self, p1, p2)¶ Minimal distance between two three dimensional coordinates p1 and p2.
Parameters: p2 (p1,) –

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
(espressomd.particle_data.ParticleHandle.type
)) – A particle typeReturns: 3x3 moment of inertia matrix. Return type: array_like

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
 pos (array of

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

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’ or ‘<rdf>’.  type_list_a (lists of
int
(espressomd.particle_data.ParticleHandle.type
)) – Left types of the rdf.  type_list_b (lists of
int
(espressomd.particle_data.ParticleHandle.type
), optional) – Right types 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) – If rdf_type is ‘<rdf>’ this determines the number of stored configs that are used.
Returns: Where [0] contains the midpoints of the bins, and [1] contains the values of the rdf.
Return type: array_like
 rdf_type (

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

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 types. The structure factor is calculated for all possible wave vectors q up to order Do not choose parameter order too large because the number of calculations grows as order to the third power.
Parameters:  sf_types (list of
int
(espressomd.particle_data.ParticleHandle.type
)) – Specifies which particle type 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: array_like
 sf_types (list of

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

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=1)¶ Resort the particles in the cellsystem. Returns the particle numbers on the nodes after the resort.
Parameters: global_flag ( int
) – If true, a global resorting is done, otherwise particles are only exchanged between neighboring nodes.

set_domain_decomposition
(self, use_verlet_lists=True)¶ 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.
 'n_layers' (

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)¶ 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.
Returns: Return type: espressomd.cell_system.skin
 'min_skin' (

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 match checkpoint_id and checkpoint_path otherwise False. 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 latest checkpoint_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.
 checkpoint_id (
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

particles():
Returns an instance of ParticleSlice containing the paritlces in the cluster

size():
Returns the number of particles in the cluster

center_of_mass():
center of mass of the cluster

longest_distance():
Longest distance between any combination of two particles in the cluster

fractal_dimension(dr=None):
estimates the cluster’s fractal dimension by fitting the number of particles \(n\) in spheres of growing radius around the cetner of mass to \(c*r_g^d\), where \(r_g\) is the radius of gyration of the particles witin the sphere, and \(d\) is the fractal dimensoin. dr: Minimum increment for the radius of the spheres. Return value: (fractal_dimension, mean_square_residual)


class
espressomd.cluster_analysis.
ClusterStructure
(*args, **kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Cluster structure of a simulation system, and access to cluster anaylsis

pair_criterion
¶ Instance of PairCriterion or derived classes – Criterion to decide whether two particles are neighbors.

clusters
¶ behaves like a readonly dictionary – Access to individual clusters in the cluster structure either via cluster[i], wher i is a (nonconsecutive) integer cluster id or via iteration: for pair in clusters: where pair contains the numeric id and the corresponding cluster object.

cid_for_particle
(p)[source]¶ Returns cluster id for the particle (passed as ParticleHandle or particle id)

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
Inteface to the collision detection / dynamic binding.
See Creating bonds when particles collide for detailed instructions.

get_parameter
(self, name)¶

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 (One of "off", "bind_centers", "bind_at_point_of_collision", "bind_three_particles", "glue_to_surface") – Collision detection mode
 distance (
float
) – Distance below which a pair of particles is considered in the collision detection  bond_centers (Instance of
espressomd.interactions.BondedInteraction
) – Bond to add between the colliding particles  bond_vs (Instance of
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 (Instance of
espressomd.interactions.BondedInteraction
) – First angular bond for the “bind_three_particles” mode. See user guide  three_particle_binding_angle_resolution (
int
) – Resolution for the angular bonds (mode “bind_three_particles”). Resolution+1 bonds are needed to accommodate the case of a 180 degrees

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 of 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.ScriptInterfaceHelper
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.
:param Either an instance of
espressomd.constraints.Constraint
, or: :param the parameters to construct anespressomd.constraints.ShapeBasedConstraint
.:Returns: constraint – The added constraint Return type: Instance of espressomd.constraints.Constraint

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


class
espressomd.constraints.
ElectricPotential
(field, **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 * Ewhere q is the charge of the particle.

class
espressomd.constraints.
FlowField
(field, **kwargs)[source]¶ Bases:
espressomd.constraints._Interpolated
Viscous coupling to a flow field that is interpolated from tabulated data like
F = gamma * (u(r)  v)wher v is the velocity of the particle.

class
espressomd.constraints.
ForceField
(field, **kwargs)[source]¶ Bases:
espressomd.constraints._Interpolated
A generic tabulated force field that applies a per particle scaling factor.

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.
Gravity
(g)[source]¶ Bases:
espressomd.constraints.Constraint
 Gravity force
 F = m * g

g
¶ array of
float
– The gravitational acceleration.

g

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

gamma
¶ float
– The coupling constant

u
¶ array_like
float
– The velocity of the field.

u


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

H
¶ array of
float
– Magnetic field vector. Describes both field direction and strength of the magnetic field (via length of the vector).


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

E
¶ array of
float
– The electric field.

phi0
¶ float
– The potential at the origin

E

phi0


class
espressomd.constraints.
PotentialField
(field, **kwargs)[source]¶ Bases:
espressomd.constraints._Interpolated
A generic tabulated force field that applies a per particle scaling factor. The forces are calculated numerically from the data by finite differences. The potential is interpolated from the provided data.

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
¶ bool – Act only in the direction of positive normal, only useful if penetrable is True.

particle_type
¶ int – Interaction type of the constraint.

particle_velocity
¶ array of
float
– Interaction velocity of the boundary

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

shape
¶ object – 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=0, 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: Return type: obj:float: The minimum distance

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=0, only_positive=0)
>>> 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¶
espressomd.diamond module¶
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.

espressomd.drude_helpers.
system
¶ Instance of
espressomd.System

espressomd.drude_helpers.
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 intramol. coreDrude shortrange exclusion and Thole interaction.

espressomd.drude_helpers.
system
Instance of
espressomd.System

espressomd.drude_helpers.
harmonic_bond
¶ This method adds this harmonic bond to between drude particle and core

espressomd.drude_helpers.
thermalized_bond
¶ This method adds this thermalizerd_bond to between drude particle and core

espressomd.drude_helpers.
p_core
¶ The existing core particle

espressomd.drude_helpers.
id_drude
¶ int
– This method creates the drude particle and assigns this id.

espressomd.drude_helpers.
type_drude
¶ int
– The type of the newly created drude particle

espressomd.drude_helpers.
alpha
¶ float
– The polarizability in units of inverse volume. Related to the charge of the drude particle.

espressomd.drude_helpers.
mass_drude
¶ float
– The mass of the newly created drude particle

espressomd.drude_helpers.
coulomb_prefactor
¶ float
– Required to calculate the charge of the drude particle.

espressomd.drude_helpers.
thole_damping
¶ float
– Thole damping factor of the drude pair. Comes to effect if add_all_thole() method is used.

espressomd.drude_helpers.
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.

espressomd.drude_helpers.
system
Instance of
espressomd.System

espressomd.drude_helpers.
drude_ids
¶ IDs of Drude particles within a molecule.

espressomd.drude_helpers.
core_ids
¶ IDs of core particles within a molecule.

espressomd.drude_helpers.
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.

espressomd.drude_helpers.
system
Instance of
espressomd.System

espressomd.drude_helpers.
t1
¶ int
– Type 1

espressomd.drude_helpers.
t2
¶ int
– Type 2

espressomd.drude_helpers.
verbose
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.

espressomd.drude_helpers.
system
Instance of
espressomd.System

espressomd.drude_helpers.
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.

espressomd.drude_helpers.
system
Instance of
espressomd.System

espressomd.drude_helpers.
mol_drude_types
¶ List of types of drude particles within the molecule

espressomd.drude_helpers.
mol_core_types
¶ List of types of core particles within the molecule

espressomd.drude_helpers.
mol_core_partial_charges
¶ List of partial charges of core particles within the molecule

espressomd.drude_helpers.
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 ( integer
) – Species to be initialized.

checkpoint
(self)¶

default_params
(self)¶ Returns the default parameters.

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

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

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.
Parameters:  species (
integer
) – The species which will be changed to neutralize the system.  note (The previous density of the species will be ignored and) – it will be homogeneous distributed over the whole system The species must be charged to begin with. If the neutralization would lead to a negative species density an exception will be raised.
 species (

print_vtk_boundary
(self, path)¶ Writes the boundary information into a vtkfile.
Parameters: path ( string
) – The path and vtkfile name the boundary is written to.

print_vtk_density
(self, path)¶ Writes the LB density information into a vtkfile.
Parameters: path ( string
) – The path and vtkfile name the LB density is written to.

print_vtk_lbforce_density
(self, path)¶ Writes the LB force information into a vtkfile.
Parameters: path ( string
) – The path and vtkfile name the LB force is written to.

print_vtk_particle_potential
(self, path)¶ Writes the electrostatic particle potential into a vtkfile.
Parameters:  path (
string
) – The path and vtkfile name the electrostatic potential is written to.  note (This only works if 'EK_ELECTROSTATIC_COUPLING' is active.) –
 path (

print_vtk_potential
(self, path)¶ Writes the electrostatic potential into a vtkfile.
Parameters: path ( string
) – The path and vtkfile name the electrostatic potential is written to.

print_vtk_velocity
(self, path)¶ Writes the lattice Boltzmann velocity information into a vtkfile.
Parameters: path ( string
) – The path and vtkfile name the velocity is written to.

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

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 (
integer
) – species for which the density will apply.  density (
float
) – The value to which the density will be set to.  node (numpyarray of type
integer
of length (3)) – If set the density will be only applied on this specific node.
 species (

species_list
= []¶

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 ( string
) – The path and vtkfile name the species density is written to.

print_vtk_flux
(self, path)¶ Writes the species flux into a vtkfile.
Parameters: path ( string
) – The path and vtkfile name the species flux is written to.

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.
Parameters:  gap_size (float, required) – The gap size gives the height of the empty region between the system box and the neighboring artificial images. ESPResSo does not make sure that the gap is actually empty, this is the users responsibility. The method will compute fine if the condition is not fulfilled, however, the error bound will not be reached. Therefore you should really make sure that the gap region is empty (e.g. with wall constraints).
 maxPWerror (float, required) – The maximal pairwise error sets the least upper bound (LUB) error of the force between any two charges without prefactors (see the papers). The algorithm tries to find parameters to meet this LUB requirements or will throw an error if there are none.
 delta_mid_top (float, optional) – This parameter sets the dielectric contrast between the upper boundary and the simulation box \(\Delta_t\).
 delta_mid_bottom (float, optional) – This parameter sets the dielectric contrast between the lower boundary and the simulation box \(\Delta_b\).
 const_pot (int, optional) – Selector parameter for setting a constant electric potential between the top and bottom of the simulation box.
 pot_diff (float, optional) – If const_pot mode is selected this parameter controls the applied voltage.
 neutralize (int, optional) – By default, ELC just as P3M adds a homogeneous neutralizing background to the system in case of a net charge. However, unlike in three dimensions, this background adds a parabolic potential across the slab [BAC09]. Therefore, under normal circumstance, you will probably want to disable the neutralization for 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 or delta_mid_bot != 0 or const_pot_on=1), neutralize is overwritten and switched off internally. Note that the special case of nonneutral systems with a nonmetallic dielectric jump (eg. delta_mid_top or delta_mid_bot in ]1,1[) is not covered by the algorithm and will throw an error.
 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.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 algorithm

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶

espressomd.electrostatics module¶

class
espressomd.electrostatics.
DH
¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
Solve electrostatics in 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)¶
 prefactor (

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 theory 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 ore not. The default is True.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶
 prefactor (

class
espressomd.electrostatics.
MMM1DGPU
¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver for Systems with one periodic direction. See MMM1D theory 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 ore not. The default is True.

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶
 prefactor (

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 (
int
, optional) – Selector parameter for setting the dielectric constants manually (top, mid, bottom), mutually exclusive with dielectriccontrast  top (
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 (
int
, optional) – Selector parameter for setting a dielectric contrast between the upper simulation boundary and the simulation box, and between the lower simulation boundary and the simulation box, respectively.  delta_mid_top (
float
, optional) – If 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 (
int
, 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)¶
 prefactor (

class
espressomd.electrostatics.
P3M
(*args, **kwargs)¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


class
espressomd.electrostatics.
P3MGPU
(*args, **kwargs)¶ Bases:
espressomd.electrostatics.ElectrostaticInteraction

default_params
(self)¶

required_keys
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


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 Lattice Boltzmann. 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=0)¶ Set the forces on the particles to zero.
Parameters: torque ( int
, optional) – Whether or not to kill the torques on all particles too.

kill_particle_motion
(self, rotation=0)¶ Stop the motion of the particles.
Parameters: rotation ( int
, 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 as a list of floats. Return type: list

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 as a list of floats Return type: list
offloat

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

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

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.
 steps (

set_isotropic_npt
(self, ext_pressure, piston, direction=[0, 0, 0], 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 (
list
, optional) – Three integers to set the box geometry for noncubic boxes  cubic_box (
bool
, optional) – If this optional parameter is true, a cubic box is assumed.
 ext_pressure (

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
Bond angle dependent ine potential.

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
Bond angle dependent cos^2 potential.

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
Bond angle dependent harmonic potential.

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
) – The magnitude of exponential part of the interaction.  b (
float
) – Exponential factor of the interaction.  c (
float
) – The magnitude of the term decaying with the sixth power of r.  d (
float
) – The magnitude of the term decaying with the eighth power of r.  sig (
float
) – Shift in the exponent.  cutoff (
float
) – Cutoff distance of the interaction.
 a (

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

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶


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

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.

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], where i is the bond id. Will return a bonded interaction from bonded_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 (:obj`float`) – 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.
 a (

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 (
float
) – The distance dependence of the parallel part, either 0 (constant) or 1 (linear)  gamma (
float
) – Friction coefficient of the parallel part  r_cut (
float
) – Cutoff of the parallel part  trans_weight_function (
float
) – The distance dependence of the orthogonal part, either 0 (constant) or 1 (linear)  trans_gamma (
float
) – Friction coefficient of the orthogonal part  trans_r_cut (
float
) – Cutoff of the orthogonal part
 weight_function (

type_name
(self)¶

valid_keys
(self)¶

validate_params
(self)¶


class
espressomd.interactions.
Dihedral
¶ Bases:
espressomd.interactions.BondedInteraction

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

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.
 eps (

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
orstring
) – 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.
 eps (

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
) – The magnitude of the interaction.  sigma (
float
) – Determines the interaction length scale.  cutoff (
float
) – Cutoff distance of the interaction.  shift (
float
, string) – Constant shift of the potential.  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. 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.
 epsilon (

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

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

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
) – The magnitude of the interaction.  cutoff (
float
) – Cutoff distance of the interaction.
 F_max (

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
) – The magnitude of the interaction.  sig (
float
) – Parameter sigma which determines the length over which the potential decays.
 eps (

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

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

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

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 Cosine2 interaction.
Parameters:  epsilon (
float
) – The magnitude of the interaction.  sigma (
float
) – Determines the interaction length scale.  offset (
float
) – Offset distance of the interaction.  width (
float
) – Width of interaction.
 epsilon (

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 Cosine2 interaction.
Parameters:  epsilon (
float
) – The magnitude of the interaction.  sigma (
float
) – Determines the interaction length scale.  cutoff (
float
) – Cutoff distance of the interaction.  offset (
float
) – Offset distance of the interaction.
 epsilon (

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
) – The magnitude of the interaction.  sigma (
float
) – Determines the interaction length scale.  cutoff (
float
) – Cutoff distance of the interaction.  shift (
float
orstr
) – Constant shift of the potential. (4*epsilon*shift).  offset (
float
, optional) – Offset distance of the interaction.  min (
float
, optional) – Restricts the interaction to a minimal distance.
 epsilon (

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 minimum  cutoff (
float
) – Cutoff distance of the interaction.
 eps (

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 lennard jones Either called with two particle type id, in which case, the interaction will represent the bonded interaction as it is defined in Espresso core Or called with keyword arguments describing a new interaction.

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
¶ user_interactions – object

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], where i,j are particle types. Returns NonBondedInteractionHandle. Also: access to force capping.

reset
(self)¶ Reset all interaction parameters to their default values.


class
espressomd.interactions.
OifGlobalForces
¶ Bases:
espressomd.interactions.BondedInteraction
Part of the Objectinfluid method.

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
Part of the Objectinfluid method.

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

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶


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

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
) – Exponent of short range repulsion.  eps (
float
) – The magnitude of the second (soft) repulsion.  k0 (
float
) – Exponential factor in second (soft) repulsion.  sig (
float
) – Length scale of second (soft) repulsion.  cutoff (
float
) – Cutoff distance of the interaction.
 d (

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
) – The 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.
 a (

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

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.
Tabulated
(*args, **kwargs)¶ Bases:
espressomd.interactions.BondedInteraction

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.
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)¶ Sets 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
float
) – The energy table.  force (array_like
float
) – The force table.
 min (

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

required_keys
(self)¶

set_default_params
(self)¶

type_name
(self)¶

type_number
(self)¶

valid_keys
(self)¶


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

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.

espressomd.lb module¶

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

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

default_params
(self)¶

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

load_checkpoint
(self, path, binary)¶

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)¶

valid_keys
(self)¶

validate_params
(self)¶


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

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

remove_total_momentum
(self)¶

espressomd.lbboundaries module¶

class
espressomd.lbboundaries.
LBBoundaries
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Creates a set of lattice Boltzmann 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
Provide the Dipolar Layer Correction (DLC) method.
DLC works like ELC for electrostatics (
espressomd.electrostatic_extensions.ELC
), but applied to magnetic dipoles.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 [Bro04].

far_cut
¶ float
– Cutoff of the exponential sum.

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.

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. 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.
If the system has periodic boundaries, the minimum image convention is applied in the respective directions.

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.
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.
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.
If the system has periodic boundaries, n_replica copies of the system are taken into account in the respective directions. Spherical cutoff is applied.

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.

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 array_like – Number of mesh points.

mesh_off
¶ array_like – Mesh offset.

r_cut
¶ float
– Real space cutoff.

tune
¶ bool
, optional – Activate/deactivate the tuning method on activation (default is True, 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.

prefactor
¶ float
– Magnetostatics prefactor (\(\mu_0/(4\pi)\))

get_params
(self)¶

set_magnetostatics_prefactor
(self)¶ Set the magnetostatics prefactor

validate_params
(self)¶ Check validity of given parameters.

espressomd.minimize_energy module¶

class
espressomd.minimize_energy.
MinimizeEnergy
(*args, **kwargs)¶ Bases:
object
Initialize steepest descent energy minimization.
Parameters:  f_max (
float
) – Maximal allowed force.  gamma (
float
) – Dampening constant.  max_steps (
int
) – Maximal number of iterations.  max_displacement (
float
) – Maximal allowed displacement per step.

default_params
(self)¶

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

minimize
(self)¶ Perform energy minimization sweep.

required_keys
(self)¶

validate_params
(self)¶
 f_max (
espressomd.observables module¶

class
espressomd.observables.
ComForce
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the total force on particles with given ids.
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.
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.
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.
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 polar coordinates.
Parameters:  ids (array_like of
int
) – The ids of (existing) particles to take into account.  center (array_like of
float
) – Position of the center of the polar coordinate system for the histogram.  axis (
str
(x
,y
, orz
)) – Orientation of thez
axis of the polar 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.
 ids (array_like of

class
espressomd.observables.
CylindricalFluxDensityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle flux density in polar coordinates.
Parameters:  ids (array_like of
int
) – The ids of (existing) particles to take into account.  center (array_like of
float
) – Position of the center of the polar coordinate system for the histogram.  axis (
str
(x
,y
, orz
)) – Orientation of thez
axis of the polar 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.
 ids (array_like of

class
espressomd.observables.
CylindricalLBFluxDensityProfileAtParticlePositions
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the LB fluid flux density at the particle positions in polar coordinates.
Parameters:  ids (array_like of
int
) – The ids of (existing) particles to take into account.  center (array_like of
float
) – Position of the center of the polar coordinate system for the histogram.  axis (
str
(x
,y
, orz
)) – Orientation of thez
axis of the polar 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.
 ids (array_like of

class
espressomd.observables.
CylindricalLBVelocityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the LB fluid velocity profile in polar coordinates.
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.Parameters:  center (array_like of
float
) – Position of the center of the polar coordinate system for the histogram.  axis (
str
(x
,y
, orz
)) – Orientation of thez
axis of the polar 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_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) – Wether or not to allow bins that will not be sampled at all.
 center (array_like of

class
espressomd.observables.
CylindricalLBVelocityProfileAtParticlePositions
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the LB fluid velocity at the particle positions in polar coordinates.
Parameters:  ids (array_like of
int
) – The ids of (existing) particles to take into account.  center (array_like of
float
) – Position of the center of the polar coordinate system for the histogram.  axis (
str
(x
,y
, orz
)) – Orientation of thez
axis of the polar 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.
 ids (array_like of

class
espressomd.observables.
CylindricalVelocityProfile
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the particle velocity profile in polar coordinates.
Parameters:  ids (array_like of
int
) – The ids of (existing) particles to take into account.  center (array_like of
float
) – Position of the center of the polar coordinate system for the histogram.  axis (
str
(x
,y
, orz
)) – Orientation of thez
axis of the polar 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.
 ids (array_like of

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.
 ids (array_like of

class
espressomd.observables.
DipoleMoment
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the dipole moment for particles with given ids.
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.
 ids (array_like of

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.
 ids (array_like of

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) – Wether or not to allow bins that will not be sampled at all.
 n_x_bins (

class
espressomd.observables.
MagneticDipoleMoment
(**kwargs)[source]¶ Bases:
espressomd.observables.Observable
Calculates the magnetic dipole moment for particles with given ids.
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.
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.
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.
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.
Parameters: ids (array_like of int
) – The ids of (existing) particles to take into account.
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 via get_params()
 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 cut off. Periodic boundaries are treated via minimum image convention.
The following parameters can be passed to the constructor, changed via set_params() and retrieved via get_params()
 cut_off : float
 distance cut off 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 >= 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 via get_params()
 cut_off : float
 energy cut off 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 where the first element is either a bond ID of a bond) – type, and the last element is the ID of the parter particle to be bonded to. See also
bonds()
 Particle property containing a list of all current bonds help by Particle.
Examples
>>> import espressomd >>> from espressomd.interactions import * >>> >>> 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 (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 by Particle.

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.
 bonds : list/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.

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 * >>> >>> 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 where the first element is either a bond ID of a bond) – type, and the last element is the ID of the parter 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 by Particle.

dip
¶ The orientation of the dipole axis.
dip : list 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 : list of
float
Note
This needs the feature EXTERNAL_FORCES.

ext_torque
¶ An additional external torque is applied to the particle.
ext_torque : list of
float
Note
 This torque is specified in the laboratory frame!
 This needs the feature EXTERNAL_FORCES and ROTATION.

f
¶ The instantaneous force acting on this particle.
 f : list of
float
 A list of three floats representing the current forces on the Particle
Note
Whereas the velocity is modified with respect to the velocity you set upon integration, the force it recomputed during the integration step and any force set in this way is immediatly lost at the next integration step.
 f : list of

fix
¶ Fixes the particle motion in the specified cartesian directions.
fix : list of integers
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 the Langevin thermostat.
gamma : list of
float
Note
This needs the feature LANGEVIN_PER_PARTICLE and PARTICLE_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 : list of
float
Note
This needs the feature LANGEVIN_PER_PARTICLE, ROTATION and PARTICLE_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 objectinfuid cells. The default mol_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 effectivly acts as a velocity offset between an 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 : list 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 : list of
float
 List of three floats giving the particle angular velocity as measured from the lab frame.
Note
This needs the feature ROTATION.
If you set the angular velocity of the particle in the lab frame, the orientation of the particle (
espressomd.particle_data.ParticleHandle.quat
) must be set before setting omega_lab, otherwise the conversion from lab to body frame will not be handled properly. omega_lab : list of

out_direction
¶ OIF Outward direction

pos
¶ The unwrapped (not folded into central box) particle position.
 pos : list of
float
 A list of three floats representing the particles’s absolute position.
 pos : list of

pos_folded
¶ The wrapped (folded into central box) position vector of a particle.
 pos : list of
float
 A list of three floats representing the particles’s 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 : list of

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

quat
¶ Particle quaternion representation.
 quat : list fo
float
(of length four)  This list of four floats sets the quaternion representation of the rotational position of this particle.
Note
This needs the feature ROTATION.
 quat : list fo

remove
(self)¶ Delete the particle.
See also
add()
,clear()

rinertia
¶ The particle rotational inertia.
rintertia : list 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) frame are coaligned.
Note
This needs the feature ROTATIONAL_INERTIA.

rotate
(self, axis=None, angle=None)¶ Rotates the particle around the given axis
Parameters:  axis (arraylike) –
 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 : (int,int,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 . The selfpropulsion speed will relax to a constant velocity, that is specified by v_swim . Alternatively it is possible to achieve a constant velocity by imposing a constant force term f_swim that is balanced by friction of a (Langevin) thermostat. The way the velocity of the particle decays to the constant terminal velocity in either of these methods is completely determined by the friction coefficient. You may only set one of the possibilities v_swim or f_swim as you cannot relax to constant force and constant velocity at the same time. The setting both v_swim and f_swim to 0.0 thus disables swimming. This option applies to all nonlatticeBoltzmann thermostats. Note that there is no real difference between v_swim and f_swim since the latter may aways be chosen such that the same terminal velocity is achieved for a given friction coefficient.
Parameters:  'f_swim' (
float
) – Achieve a constant velocity by imposing a constant force term ‘f_swim’ that is balanced by friction of a (Langevin) thermostat. This exludes the option ‘v_swim’.  'v_swim' (
float
) – Achieve a constant velocity by imposing a constant terminal velocity ‘v_swim’. This exludes the option ‘f_swim’.  'mode' (string, 'pusher' or 'puller' (initially 'N/A')) – The LB flow field can be generated by a pushing or a pulling mechanism, leading to change in the sign of the dipolar flow field with respect to the direction of motion.
 'dipole_length' (
float
) – This determines the distance of the source of propulsion from the particle’s center.  'rotational_friction' (
float
) – This key can be used to set the friction that causes the orientation of the particle to change in shear flow. The torque on the particle is determined by taking the cross product of the difference between the fluid velocity at the center of the particle and at the source point and the vector connecting the center and source.
Notes
This needs the feature ENGINE. The keys ‘mode’, ‘dipole_length’, and ‘rotational_friction’ are only available if ENGINE is used with LB or LB_GPU.
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, 'rotational_friction':20})
 'f_swim' (

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 : list of
float
This property defines the torque of this particle in the fixed frame (or laboratory frame).
Note
The orientation of the particle (
espressomd.particle_data.ParticleHandle.quat
) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.See also
espressomd.particle_data.ParticleHandle.torque_body

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 : list of
float
 A list of three floats representing the Particles’s velocity
Note
The velocity remains variable and will be changed during integration.
 v : list of

virtual
¶ Virtual flag.
Declares the particles as virtual (1) or nonvirtual (0, default).
virtual : integer
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 : 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], where i is the particle id. Returns a ParticleHandle object.

add
(self, *args, **kwargs)¶ Adds one or several particles to the system
Parameters: a dictionary or a bunch of keyword args. (Either) – Returns: Return type: Returns an instance of espressomd.particle_data.ParticleHandle
for each added particle.Examples
>>> import espressomd >>> from espressomd.interactions import * >>> >>> 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.,:
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.,:
lambda p: p.pos[0]<0.5
Returns: Return type: An instance of ParticleSlice containing the selected particles
 Either –

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 file  types (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/
 fname (


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.

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.
 bonds : list/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
add_bond
,delete_bond
 Bond ids have to be an integer >= 0.

dip
¶ The orientation of the dipole axis.
dip : list 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 : list of
float
Note
This needs the feature EXTERNAL_FORCES.

ext_torque
¶ An additional external torque is applied to the particle.
ext_torque : list of
float
Note
 This torque is specified in the laboratory frame!
 This needs the feature EXTERNAL_FORCES and ROTATION.

f
¶ The instantaneous force acting on this particle.
 f : list of
float
 A list of three floats representing the current forces on the Particle
Note
Whereas the velocity is modified with respect to the velocity you set upon integration, the force it recomputed during the integration step and any force set in this way is immediatly lost at the next integration step.
 f : list of

fix
¶ Fixes the particle motion in the specified cartesian directions.
fix : list of integers
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 the Langevin thermostat.
gamma : list of
float
Note
This needs the feature LANGEVIN_PER_PARTICLE and PARTICLE_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 : list of
float
Note
This needs the feature LANGEVIN_PER_PARTICLE, ROTATION and PARTICLE_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 objectinfuid cells. The default mol_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 effectivly acts as a velocity offset between an 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 : list 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 : list of
float
 List of three floats giving the particle angular velocity as measured from the lab frame.
Note
This needs the feature ROTATION.
If you set the angular velocity of the particle in the lab frame, the orientation of the particle (
espressomd.particle_data.ParticleHandle.quat
) must be set before setting omega_lab, otherwise the conversion from lab to body frame will not be handled properly. omega_lab : list of

out_direction
¶ OIF Outward direction

pos
¶ The unwrapped (not folded into central box) particle position.
 pos : list of
float
 A list of three floats representing the particles’s absolute position.
 pos : list of

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

quat
¶ Particle quaternion representation.
 quat : list fo
float
(of length four)  This list of four floats sets the quaternion representation of the rotational position of this particle.
Note
This needs the feature ROTATION.
 quat : list fo

rinertia
¶ The particle rotational inertia.
rintertia : list 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) frame are coaligned.
Note
This needs the feature ROTATIONAL_INERTIA.

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 : (int,int,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 . The selfpropulsion speed will relax to a constant velocity, that is specified by v_swim . Alternatively it is possible to achieve a constant velocity by imposing a constant force term f_swim that is balanced by friction of a (Langevin) thermostat. The way the velocity of the particle decays to the constant terminal velocity in either of these methods is completely determined by the friction coefficient. You may only set one of the possibilities v_swim or f_swim as you cannot relax to constant force and constant velocity at the same time. The setting both v_swim and f_swim to 0.0 thus disables swimming. This option applies to all nonlatticeBoltzmann thermostats. Note that there is no real difference between v_swim and f_swim since the latter may aways be chosen such that the same terminal velocity is achieved for a given friction coefficient.
Parameters:  'f_swim' (
float
) – Achieve a constant velocity by imposing a constant force term ‘f_swim’ that is balanced by friction of a (Langevin) thermostat. This exludes the option ‘v_swim’.  'v_swim' (
float
) – Achieve a constant velocity by imposing a constant terminal velocity ‘v_swim’. This exludes the option ‘f_swim’.  'mode' (string, 'pusher' or 'puller' (initially 'N/A')) – The LB flow field can be generated by a pushing or a pulling mechanism, leading to change in the sign of the dipolar flow field with respect to the direction of motion.
 'dipole_length' (
float
) – This determines the distance of the source of propulsion from the particle’s center.  'rotational_friction' (
float
) – This key can be used to set the friction that causes the orientation of the particle to change in shear flow. The torque on the particle is determined by taking the cross product of the difference between the fluid velocity at the center of the particle and at the source point and the vector connecting the center and source.
Notes
This needs the feature ENGINE. The keys ‘mode’, ‘dipole_length’, and ‘rotational_friction’ are only available if ENGINE is used with LB or LB_GPU.
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, 'rotational_friction':20})
 'f_swim' (

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 : list of
float
This property defines the torque of this particle in the fixed frame (or laboratory frame).
Note
The orientation of the particle (
espressomd.particle_data.ParticleHandle.quat
) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.See also
espressomd.particle_data.ParticleHandle.torque_body

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 :

v
¶ The particle velocity in the lab frame.
 v : list of
float
 A list of three floats representing the Particles’s velocity
Note
The velocity remains variable and will be changed during integration.
 v : list of

virtual
¶ Virtual flag.
Declares the particles as virtual (1) or nonvirtual (0, default).
virtual : integer
Note
This needs the feature VIRTUAL_SITES

vs_quat
¶ Virtual site quaternion.
This quaternion describes the virtual particles orientation in the body fixed frame of the related real particle.
vs_quat : 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


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.
create_polymer
(**kwargs)¶ Generators have a
Yields
section instead of aReturns
section.Parameters:  n (
intd
) – The upper limit of the range to generate, from 0 to n  1.  N_P (
int
) – Number of polymer chains  MPC (
int
) – Number of monomers per chain  bond_length (
float
) – distance between adjacent monomers in a chain  bond (
espressomd.interactions.BondedInteraction
) – The bonded interaction to be set up between the monomers.  start_id (
int
, optional) – Particle ID of the first monomer, all other particles will have larger IDs. Defaults to 0  start_pos (array_like
float
.) – Position of the first monomer  mode (
int
, optional) – Selects a specific random walk procedure for the polymer setup mode = 1 uses a common random walk, mode = 2 produces a pruned selfavoiding random walk, and mode = 0 a selfavoiding random walk. Note that mode = 2 does not produce a true selfavoiding random walk distribution but is much faster than mode = 0. Defaults to 1  shield (
float
, optional) – Shielding radius for the pruned selfavoiding walk mode. Defaults to 0  max_tries (
int
, optional) – Maximal number of attempts to set up a polymer, default value is 1,000. Depending on the random walk mode and the polymer length this value needs to be adapted.  val_poly (
float
, optional) – Valency of the monomers, default is 0.0  charge_distance (
int
, optional) – Distance between charged monomers along the chain. Default is 1  type_poly_neutral (
int
, optional) – Particle type of neutral monomers, default is 0.  type_poly_charged (
int
, optional) – Particle type for charged monomers, default is 1  angle (
float
, optional) –  angle2 (
float
, optional) – The both angles angle and angle2 allow to set up planar or helical polymers, they fix the angles between adjacent bonds.  pos2 (array_like, optional) – Sets the position of the second monomer.
 constraints (
int
, optional) – Either 0 or 1, default is 0. If 1, the particle setupup tries to obey previously defined constraints.
Examples
This example sets 2 polyelectrolyte chains of the length 10. Beads are connected by FENE potential.
>>> fene = interactions.FeneBond(k=10, d_r_max=2) >>> polymer.create_polymer( N_P = 2, MPC = 10, bond_length = 1, bond = fene, val_poly = 1.0)
Note that a the first monomer of a polymer is always assigned the type type_poly_charge. The next charge_distance monomers have type type_poly_neutral. This process repeats until all monomers are placed. Afterwards, all monomers of type type_poly_charge are assigned the charge val_poly. Thus the following example creates a single uncharged polymer where all monomers are of type=0:
>>> fene = interactions.FeneBond(k=10, d_r_max=2) >>> polymer.create_polymer( N_P = 1, MPC = 10, bond_length = 1, bond = fene, val_poly = 0.0, charge_distance = 1, type_poly_charge = 0)
 n (

espressomd.polymer.
validate_params
(_params, default)¶
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.

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) – List of stoichiometric coefficients of the reactants in the same order as the list of their types.
 product_types (list) – List of particle types of products in the reaction.
 product_coefficients (list) – List of stoichiometric coefficients of products of the reaction in the same order as the list of their types
 default_charges (dictionary) – A dictionary of default charges for types that occur in the provided reaction.
 gamma (

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.

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_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
 center_x (

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()
.
 temperature (

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

exception
espressomd.reaction_ensemble.
WangLandauHasConverged
¶ Bases:
exceptions.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) – List of the types of the version of the species.
 associated_type (

add_collective_variable_potential_energy
(self, *args, **kwargs)¶ Adds the potential energy as a collective variable (reaction coordinate) for the Wang Landau Reaction Ensemble. Several collective variables can be set simultaneously.
Parameters:  filename (
str
) – Filename of the energy boundary file which provides the potential energy boundaries (min E_pot, max E_pot) tabulated for all degrees of association. Make sure to only list the degrees of association which are used by the degree of association collective variable within this file. The energy boundary file can be created in a preliminary energy run. By the help of the 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.
 filename (

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 type type_mc. Positions for the particles are drawn uniformly random 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 configuration changing moves need to be implemented in the case of using WangLandau with energy reweighting and a polymer in the system. Polymer configuration changing moves had been implemented before but were removed from espresso.

load_wang_landau_checkpoint
(self)¶ Loads the dumped wang landau 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 steps consecutively without having conformation changing steps in between (especially important for the Wang Landau reaction ensemble). Providing a number for the parameter reaction steps reduces the need for the interpreter to be called between consecutive reactions.

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 potential  do_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.
 final_wang_landau_parameter (

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 wang landau 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 wang landau 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 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. Returns the excess chemical potential and the standard error for the excess chemical potential. It assumes that your samples are uncorrelated.

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

class
espressomd.script_interface.
PObjectId
¶ Bases:
object

class
espressomd.script_interface.
PScriptInterface
(name=None, policy='GLOBAL', oid=None, **kwargs)¶ Bases:
object

call_method
(self, method, **kwargs)¶

get_parameter
(self, name)¶

get_params
(self)¶

id
(self)¶

name
(self)¶

set_params
(self, **kwargs)¶

set_sip_via_oid
(self, PObjectId id)¶ Set the shared_ptr to the script object in the core via the object id


class
espressomd.script_interface.
ScriptInterfaceHelper
(**kwargs)¶ Bases:
espressomd.script_interface.PScriptInterface

define_bound_methods
(self)¶

generate_caller
(self, method_name)¶


espressomd.script_interface.
init
()¶

espressomd.script_interface.
script_interface_register
(c)¶ Decorator used to register script interface classes This will store a name<>class 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.script_interface.ScriptInterfaceHelper
A cylinder shape.

center
¶ array_like
float
– Coordinates of the center of the cylinder.

axis
¶ array_like
float
– Axis of the cylinder.

radius
¶ float
– Radius of the cylinder.

length
¶ float
– Length of the cylinder.

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

open
¶ bool
– cylinder is open or has caps.


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

center
¶ array_like
– Coordinates of the center of the ellipsoid.

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

b
¶ float
– Equatorial semiaxes.

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


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

inner_radius
¶ float
– Inner radius of the cone.

outer_radius
¶ float
– Outer radius of the cone.

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

axis
¶ array_like
float
– Axis of symmetry, prescribes orientation of the cone.

center
¶ array_like
float
– Position of the cone.

width
¶ float
– Wall thickness of the cone.

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


class
espressomd.shapes.
Maze
(**kwargs)[source]¶ Bases:
espressomd.script_interface.ScriptInterfaceHelper
Spherical cavities on a regular grid that are connected by tubes.

cylrad
¶ float
– Radius of the tubes.

dim
¶ float
– Dimension of the maze.

nsphere
¶ int
– Number of spherical cavities.

sphrad
¶ float
– Radius of the spherical cavities.


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

a
¶ array_like
float
– First base vector.

b
¶ array_like
float
– Second base vector.

c
¶ array_like
float
– Third base vector.

corner
¶ array_like
float
– Lower left corner of the rhomboid.

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


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

radius
¶ float – The radius of the pore.

length
¶ float – The distance between the planes.

smoothing_radius
¶ float – Radius of the torus segments

axis
¶ array_like – Axis of the cylinder and normal of the planes

center
¶ array_like – Position of the center of the cylinder.


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

channel_width
¶ float

lower_smoothing_radius
¶ float

pore_length
¶ float

pore_mouth
¶ float

pore_width
¶ float

upper_smoothing_radius
¶ float


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

center
¶ array_like
float
– Center of the sphere

radius
¶ float
– Radius of the sphere.

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


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

center
¶ array_like
float
– Coordinates of the center of the cylinder.

axis
¶ array_like
float
– Axis of the cylinder.

radius
¶ float
– Radius of the cylinder.

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

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


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

inner_radius
¶ float
– Inner radius of the stomatocyte.

outer_radius
¶ float
– Outer radius of the stomatocyte.

axis
¶ array_like
float
– Symmetry axis, prescribing the orientation of the stomatocyte.

center
¶ array_like
float
– Position of the stomatocyte.

layer_width
¶ float
– Scaling parameter.

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


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

dist
¶ float
– Distance from the origin.

normal
¶ array_like
int
– Normal vector of the plan (needs not to be length 1).

espressomd.swimmer_reaction module¶

class
espressomd.swimmer_reaction.
Reaction
(*args, **kwargs)¶ Bases:
object
Class that tries to mimic catalytic reactions for self propelled particles.
Note
Requires the features SWIMMER_REACTIONS.
Keep in mind, that there may be only one reaction enabled. There can be only one.
Parameters:  'product_type' (integer) – Particle type of the reactions product
 'reactant_type' (integer) – Particle type of the reactant
 'catalyzer_type' (integer) – Particle type of the catalyst
 'ct_range' (float) – Distance up to which the catalyst affects the reactants
 'ct_rate' (float) – Reaction rate for particle in the vicinity of catalysts
 'eq_rate' (float, optional) – Equilibrium reaction rate
 'react_once' (bool, optional, defaults to False) – Only perform the reaction move on a particle pair once per timestep
Notes
Requires the features ‘SWIMMER_REACTIONS’.

default_params
(self)¶

get_params
(self)¶ Get parameters set for the catalytic reactions.

required_keys
(self)¶

setup
(self, *args, **kwargs)¶ Collect the parameters and set them in the core.

start
(self)¶ Restart the reaction after it was stopped.

stop
(self)¶ Stop the reaction, i.e. set the reaction rate to 0.0.

valid_keys
(self)¶

validate_params
(self)¶
espressomd.system module¶

class
espressomd.system.
System
(**kwargs)¶ Bases:
object
The base class for espressomd.system.System().
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
¶ actors – object

analysis
¶ analysis – object

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
¶ auto_update_accumulators – object

bonded_inter
¶ bonded_inter – object

box_l
¶ Array like, list of three floats

cell_system
¶ cell_system – object

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

check_valid_type
(self, current_type)¶

collision_detection
¶ collision_detection – object

comfixed
¶ comfixed – object

constraints
¶ constraints – object

cuda_init_handle
¶ cuda_init_handle – object

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
¶ ekboundaries – object

find_particle
(self, type=None)¶ The command will return a randomly chosen particle id, for a particle of the given type.

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

galilei
¶ galilei – object

globals
¶ globals – object

integ_switch
¶

integrator
¶ integrator – object

lattice_switch
¶

lbboundaries
¶ lbboundaries – object

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
¶ minimize_energy – object

non_bonded_inter
¶ non_bonded_inter – object

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

part
¶ part – object

periodicity
¶ list of three integers [x, y, z] zero for no periodicity in this direction one 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
 phi (

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
¶ thermostat – object

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 thermostat is active
Decorator class to assure that only a given thermostat is active at a time. Usage:
@AssertThermostatType(THERMO_LANGEVIN) def set_langevin(self, kT=None, gamma=None, gamma_rotation=None):This will prefix an assertion for THERMO_LANGEVIN to the call.

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)¶ Sets the DPD thermostat with required parameters ‘kT’. This also activates the DPD interactions.
Parameters: 'kT' (float) – Thermal energy of the heat bath, floating point number

set_langevin
(self, kT=None, gamma=None, gamma_rotation=None, act_on_virtual=False)¶ Sets the Langevin thermostat with required parameters ‘kT’ ‘gamma’ and optional parameter ‘gamma_rotation’.
Parameters:  kT (
float
) – Thermal energy of the simulated heat bath.  gamma (
float
) – Contains the friction coefficient of the bath. If the feature ‘PARTICLE_ANISOTROPY’ is compiled in then ‘gamma’ can be a list of three positive floats, for the friction coefficient in each cardinal direction.  gamma_rotation (
float
, optional) – The same applies to ‘gamma_rotation’, which requires the feature ‘ROTATION’ to work properly. But also accepts three floating point numbers if ‘PARTICLE_ANISOTROPY’ is also compiled in.  act_on_virtual (
bool
, optional) – If true the thermostat will act on virtual sites, default is off.
 kT (

set_lb
(self, kT=None, act_on_virtual=True)¶ Sets the LB thermostat with required parameter ‘kT’.
This thermostat requires the feature LB or LB_GPU.
Parameters:  kT (
float
) – Specifies the thermal energy of the heat bath.  act_on_virtual (
bool
, optional) – If true the thermostat will act on virtual sites, default is on.
 kT (

set_npt
(self, kT=None, gamma0=None, gammav=None)¶ Sets the NPT thermostat with required parameters ‘temperature’, ‘gamma0’, ‘gammav’.
Parameters:  kT (
float
) – Thermal energy of the heat bath  gamma0 (
float
) – Friction coefficient of the bath  gammav (
float
) – Artificial friction coefficient for the volume fluctuations. Mass of the artificial piston.
 kT (

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
¶ 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.
get_unravelled_index
(len_dims, n_dims, flattened_index)¶ Getting the unraveled index for a given flattened index in
n_dims
dimensions.Parameters:  len_dims (array_like
int
) – The length of each of then_dims
dimensions.  n_dims (
int
) – The number of dimensions.  flattened_index (
int
) – The flat index that should be converted back to ann_dims
dimensional index.
Returns: unravelled_index – An array containing the index for each dimension.
Return type: array_like
int
 len_dims (array_like

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.
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.

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

Attributes can be set on the instance or passed to the constructor as

keyword arguments.

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 run_gui_event_loop in your main thread to be able to interact with the GUI.
Parameters:  system (instance of espressomd.System) –
 particle_sizes ((optional) function, list, or dict, 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. Keyboad callbacks via keyboardManager.register_button().
Parameters:  system (instance of
espressomd.System
) –  window_size (array_like
int
, optional) – Size of the visualizer window in pixels.  name (
str
, optional) – The name of the visualizer window.  background_color (array_like
int
, optional) – RGB of the background.  periodic_images (array_like
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 array_likefloat
, optional) – Initial camera position.auto
(default) for shiftet position in zdirection.  camera_target (
str
or array_likefloat
, optional) – Initial camera target.auto
(default) to look towards the system center.  camera_right (array_like
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 by particle_charge_colors, neutral particles by particle_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 by particle_charge_colors according to their charge. type: Particle colors are specified by particle_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 (array_like
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 – The number of subdivisions for primitive constraints.
 constraint_type_colors (array_like
float
, optional) – Colors of the constaints 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) – Materils 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 dragging  LB_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 (array_like
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.

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 and into an image file at path with dimensions of specs[‘window_size’].

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)¶
 system (instance of
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 run_gui_event_loop in your main thread to be able to interact with the GUI.
Parameters:  system (instance of espressomd.System) –
 particle_sizes ((optional) function, list, or dict, 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)¶ 
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
(edges, 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_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. Keyboad callbacks via keyboardManager.register_button().
Parameters:  system (instance of
espressomd.System
) –  window_size (array_like
int
, optional) – Size of the visualizer window in pixels.  name (
str
, optional) – The name of the visualizer window.  background_color (array_like
int
, optional) – RGB of the background.  periodic_images (array_like
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 array_likefloat
, optional) – Initial camera position.auto
(default) for shiftet position in zdirection.  camera_target (
str
or array_likefloat
, optional) – Initial camera target.auto
(default) to look towards the system center.  camera_right (array_like
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 by particle_charge_colors, neutral particles by particle_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 by particle_charge_colors according to their charge. type: Particle colors are specified by particle_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 (array_like
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 – The number of subdivisions for primitive constraints.
 constraint_type_colors (array_like
float
, optional) – Colors of the constaints 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) – Materils 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 dragging  LB_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 (array_like
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.

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 and into an image file at path with dimensions of specs[‘window_size’].

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)¶
 system (instance of

espressomd.visualization_opengl.
rotation_helper
(d)¶

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