espressomd package

Subpackages

• espressomd.MDA_ESP package
  • Module contents
• espressomd.io package
  • Subpackages
    • espressomd.io.writer package
      • Submodules
      • espressomd.io.writer.h5md module
      • espressomd.io.writer.vtf module
      • Module contents
  • Submodules
  • espressomd.io.mpiio module
  • Module contents

Submodules

espressomd.__cinit__ module

espressomd._init module

espressomd.accumulators module

class espressomd.accumulators.AutoUpdateAccumulators

Bases: espressomd.script_interface.ScriptObjectRegistry

Class for handling the auto-update of accumulators used by espressomd.system.System.

add(accumulator)

Adds an accumulator instance to the auto-update list.

clear()

Removes all accumulators from the auto-update list.

remove(accumulator)

Removes an accumulator from the auto-update list.

class espressomd.accumulators.Correlator

Bases: espressomd.script_interface.ScriptInterfaceHelper

Calculates correlations based on results from observables.

Parameters

• obs1 (espressomd.observables.Observable) – The observable \(A\) to be correlated with \(B\) (obs2). If obs2 is omitted, autocorrelation of obs1 is calculated by default.

• obs2 (espressomd.observables.Observable, optional) – The observable \(B\) to be correlated with \(A\) (obs1).

• corr_operation (str) – The operation that is performed on \(A(t)\) and \(B(t+\tau)\) to obtain \(C(\tau)\). The following operations are currently available:

  • "scalar_product": Scalar product of \(A\) and \(B\), i.e., \(C=\sum\limits_{i} A_i B_i\)

  • "componentwise_product": Componentwise product of \(A\) and \(B\), i.e., \(C_i = A_i B_i\)

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

  • "tensor_product": Tensor product of \(A\) and \(B\), i.e., \(C_{i \cdot l_B + j} = A_i B_j\) with \(l_B\) the length of \(B\).

  • "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}\]

  • "fcs_acf": Fluorescence Correlation Spectroscopy (FCS) autocorrelation function, i.e.,

    \[G_i(\tau) = \frac{1}{N} \left< \exp \left( - \frac{\Delta x_i^2(\tau)}{w_x^2} - \frac{\Delta y_i^2(\tau)}{w_y^2} - \frac{\Delta z_i^2(\tau)}{w_z^2} \right) \right>\]

    where

    \[\Delta x_i^2(\tau) = \left( x_i(0) - x_i(\tau) \right)^2\]

    is the square displacement of particle \(i\) in the \(x\) direction, and \(w_x\) is the beam waist of the intensity profile of the exciting laser beam,

    \[W(x,y,z) = I_0 \exp \left( - \frac{2x^2}{w_x^2} - \frac{2y^2}{w_y^2} - \frac{2z^2}{w_z^2} \right).\]

    The values of \(w_x\), \(w_y\), and \(w_z\) are passed to the correlator as args

    The above equations are a generalization of the formula presented by Hoefling et. al. [HoflingBF11]. For more information, see references therein. Per each 3 dimensions of the observable, one dimension of the correlation output is produced. If "fcs_acf" is used with other observables than espressomd.observables.ParticlePositions, the physical meaning of the result is unclear.

• delta_N (int) – Number of timesteps between subsequent samples for the auto update mechanism.

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

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

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

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

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

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

  If only compress1 is specified, then the same compression function is used for both observables. If 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.

• compress2 (str, optional) – See compress1.

• args (float of length 3) – Three floats which are passed as arguments to the correlation function. Currently it is only used by "fcs_acf". Other correlation operations will ignore these values.

result()

Returns

The result of the correlation function as a 2d-array. The first column contains the values of the lag time tau. The second column contains the number of values used to perform the averaging of the correlation. Further columns contain the values of the correlation function. The number of these columns is the dimension of the output of the correlation operation.

Return type

numpy.ndarray

class espressomd.accumulators.MeanVarianceCalculator

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.

class espressomd.accumulators.TimeSeries

Bases: espressomd.script_interface.ScriptInterfaceHelper

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

time_series()

Returns the recorded values of the observable.

clear()

Clear the data

espressomd.actors module

class espressomd.actors.Actor(*args, **kwargs)

Bases: object

Abstract base class for interactions affecting particles in the system, such as electrostatics, magnetostatics or LB fluids. Derived classes must implement the interface to the relevant core objects and global variables.

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

class_lookup(self, cls)

default_params(self)

Virtual method.

get_params(self)

Get interaction parameters

is_active(self)

is_valid(self)

Check if the data stored in this instance still matches the corresponding data in the core.

required_keys(self)

Virtual method.

set_params(self, **p)

Update the given parameters.

system

object

Type

system

valid_keys(self)

Virtual method.

validate_params(self)

Virtual method.

class espressomd.actors.Actors

Bases: object

Container for Actor objects.

active_actors = []

add(self, actor)

Parameters

actor (Actor) – Actor to add to this container.

clear(self)

Remove all actors.

remove(self, actor)

Parameters

actor (Actor) – Actor to remove from this container.

espressomd.analyze module

class espressomd.analyze.Analysis

Bases: object

angular_momentum(self, p_type=None)

Calculates the system’s angular momentum with respect to the origin.

Note that virtual sites are not included, as they do not have a meaningful mass.

Parameters

p_type (int) – Particle type for which to calculate the center of mass.

Returns

The center of mass of the system.

Return type

(3,) ndarray of float

append(self)

Append configuration for averaged analysis.

calc_re(self, chain_start=None, number_of_chains=None, chain_length=None)

Calculates the mean end-to-end distance of chains and its standard deviation, as well as mean square end-to-end 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

Where [0] is the mean end-to-end distance of chains and [1] its standard deviation, [2] the mean square end-to-end distance and [3] its standard deviation.

Return type

(4,) array_like of float

calc_rg(self, chain_start=None, number_of_chains=None, chain_length=None)

Calculates the mean radius of gyration of chains and its standard deviation, as well as the mean square radius of gyration of chains and its standard deviation.

This requires that a set of chains of equal length which start with the particle with particle number chain_start and are consecutively numbered, the last particle in that topology has id number

Parameters

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

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

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

Returns

Where [0] is the mean radius of gyration of the chains and [1] its standard deviation, [2] the mean square radius of gyration and [3] its standard deviation.

Return type

(4,) array_like of float

calc_rh(self, chain_start=None, number_of_chains=None, chain_length=None)

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

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

Parameters

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

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

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

Returns

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

Return type

(2,) array_like of float

center_of_mass(self, p_type=None)

Calculates the system’s center of mass.

Note that virtual sites are not included, as they do not have a meaningful mass.

Parameters

p_type (int) – 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 ((3,) array_like of float) – Coordinates of the centre of the cylinder.

• axis ((3,) array_like of float) – Axis vectory of the cylinder, does not need to be normalized.

• length (float) – Length of the cylinder.

• radius (float) – Radius of the cylinder.

• bins_axial (int) – Number of axial bins.

• bins_radial (int) – Number of radial bins.

• types (lists of int) – Particle type

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

dist_to(self, id=None, pos=None)

Calculates the distance to a point or particle.

Parameters

• id (int, optional) – Calculate distance to particle with id id.

• pos (array of float, optional) – Calculate distance to position pos.

Returns

The calculated distance.

Return type

float

distribution(self, type_list_a=None, type_list_b=None, r_min=0.0, r_max=None, r_bins=100, log_flag=0, int_flag=0)

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

Parameters

• type_list_a (list of int) – List of particle type, only consider distances from these types.

• type_list_b (list of int) – List of particle type, only consider distances to these types.

• r_min (float) – Minimum distance.

• r_max (float) – Maximum distance.

• r_bins (int) – Number of bins.

• log_flag (int) – When set to 0, the bins are linearly equidistant; when set to 1, the bins are logarithmically equidistant.

• int_flag (int) – When set to 1, the result is an integrated distribution.

Returns

Where [0] contains the midpoints of the bins, and [1] contains the values of the rdf.

Return type

ndarray

dpd_stress(self)

energy(self)

Calculate the systems energy.

Returns

A dictionary with keys total, kinetic, bonded, nonbonded, coulomb, external_fields.

Return type

dict

Examples

>>> energy = system.analysis.energy()
>>> print(energy["total"])
>>> print(energy["kinetic"])
>>> print(energy["bonded"])
>>> print(energy["non_bonded"])
>>> print(energy["external_fields"])

gyration_tensor(self, p_type=None)

Analyze the gyration tensor of particles of a given type or of all particles in the system if no type is given.

Parameters

p_type (list of int, optional) – A 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.

Return type

dict

linear_momentum(self, include_particles=True, include_lbfluid=True)

Calculates the system’s linear momentum.

Parameters

• include_particles (bool, optional) – whether to include the particles contribution to the linear momentum.

• include_lbfluid (bool, optional) – whether to include the Lattice Boltzmann fluid contribution to the linear momentum.

Returns

The linear momentum of the system.

Return type

float

min_dist(self, p1=u'default', p2=u'default')

Minimal distance between two sets of particles.

Parameters

p1, p2 (lists of int) – Particle type in both sets. If both are set to 'default', the minimum distance of all pairs is returned.

min_dist2(self, p1, p2)

Minimal distance between two three-dimensional coordinates p1 and p2.

Parameters

p1, p2 (arrays of float)

moment_of_inertia_matrix(self, p_type=None)

Returns the 3x3 moment of inertia matrix for particles of a given type.

Parameters

p_type (int) – A particle type

Returns

3x3 moment of inertia matrix.

Return type

ndarray

nbhood(self, pos=None, r_catch=None, plane=u'3d')

Get all particles in a defined neighborhood.

Parameters

• pos (array of float) – Reference position for the neighborhood.

• r_catch (float) – Radius of the region.

• plane (str, {‘xy’, ‘xz’, ‘yz’}) – If given, r_catch is the distance to the respective plane.

Returns

The neighbouring particle ids.

Return type

array of int

pressure(self, v_comp=False)

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

Returns

A dictionary with the following keys:

• "total": total pressure

• "kinetic": kinetic pressure

• "bonded": total bonded pressure

• "bonded", <bond_type>: bonded pressure which arises from the given bond_type

• "nonbonded": total nonbonded pressure

• "nonbonded", <type_i>, <type_j>: nonbonded pressure which arises from the interactions between type_i and type_j

• "nonbonded_intra", <type_i>, <type_j>: nonbonded pressure between short ranged forces between type i and j and with the same mol_id

• "nonbonded_inter", <type_i>, <type_j>: nonbonded pressure between short ranged forces between type i and j and different mol_ids

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

• "dipolar": TODO

• "virtual_sites": Stress contribution due to virtual sites

Return type

dict

rdf(self, rdf_type=None, type_list_a=None, type_list_b=None, r_min=0.0, r_max=None, r_bins=100, n_conf=None)

Calculate a radial distribution function. The result is normalized by the spherical bin shell, the total number of particle pairs and the system volume.

Parameters

• rdf_type (str) – 'rdf' or '<rdf>'.

• type_list_a (lists of int) – Left type of the rdf.

• type_list_b (lists of int, optional) – Right type 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

ndarray

stress_tensor(self, v_comp=False)

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

Returns

A dictionary with the following keys:

• "total": total stress tensor

• "kinetic": kinetic stress tensor

• "bonded": total bonded stress tensor

• "bonded", <bond_type>: bonded stress tensor which arises from the given bond_type

• "nonbonded": total nonbonded stress tensor

• "nonbonded", <type_i>, <type_j>: nonbonded stress tensor which arises from the interactions between type_i and type_j

• "nonbonded_intra" <type_i>, <type_j>: nonbonded stress tensor between short ranged forces between type i and j and with the same mol_id

• "nonbonded_inter" <type_i>, <type_j>: nonbonded stress tensor between short ranged forces between type i and j and different mol_ids

• "coulomb": Maxwell stress tensor, how it is calculated depends on the method

• "dipolar": TODO

• "virtual_sites": Stress tensor contribution for virtual sites

Return type

dict

structure_factor(self, sf_types=None, sf_order=None)

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

Parameters

• sf_types (list of int) – 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

ndarray

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, {‘read’, ‘set’ or ‘reset’}) – Mode.

• Vk1 (float) – Volume.

• Vk2 (float) – Volume squared.

• avk (float) – Number of averages.

espressomd.cellsystem module

class espressomd.cellsystem.CellSystem

Bases: object

get_pairs_(self, distance)

get_state(self)

max_num_cells

Maximum number for the cells.

min_num_cells

Minimal number of the cells.

node_grid

Node grid.

resort(self, global_flag=True)

Resort the particles in the cellsystem. Returns the particle numbers on the nodes after the resort.

Parameters

global_flag (bool) – If true, a global resorting is done, otherwise particles are only exchanged between neighboring nodes.

set_domain_decomposition(self, use_verlet_lists=True, fully_connected=[False, False, False])

Activates domain decomposition cell system.

Parameters

use_verlet_lists (bool, optional) – Activates or deactivates the usage of Verlet lists in the algorithm.

set_layered(self, n_layers=None, use_verlet_lists=True)

Activates the layered cell system.

Parameters

• n_layers (int, optional, positive) – Sets the number of layers in the z-direction.

• use_verlet_lists (bool, optional) – Activates or deactivates the usage of the Verlet lists for this algorithm.

set_n_square(self, use_verlet_lists=True)

Activates the nsquare force calculation.

Parameters

use_verlet_lists (bool, optional) – Activates or deactivates the usage of the Verlet lists for this algorithm.

skin

Value of the skin layer expects a floating point number.

Note

Mandatory to set.

tune_skin(self, min_skin=None, max_skin=None, tol=None, int_steps=None, adjust_max_skin=False)

Tunes the skin by measuring the integration time and bisecting over the given range of skins. The best skin is set in the simulation core.

Parameters

• min_skin (float) – Minimum skin to test.

• max_skin (float) – Maximum skin.

• tol (float) – Accuracy in skin to tune to.

• int_steps (int) – Integration steps to time.

• adjust_max_skin (bool, optional) – If True, the value of max_skin is reduced to the maximum permissible skin (in case the passed value is too large). Set to False by default.

Returns

The skin

Return type

float

espressomd.checkpointing module

class espressomd.checkpointing.Checkpoint(checkpoint_id=None, checkpoint_path='.')

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

Returns the last index of the given checkpoint id. Will raise exception if no checkpoints are found.

get_registered_objects()

Returns a list of all object names that are registered for checkpointing.

has_checkpoints()

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)

Loads the python objects using (c)Pickle and sets them in the calling module.

Parameters

checkpoint_index (int, optional) – If not given, the last checkpoint_index will be used.

read_signals()

Reads all registered signals from the signal file and returns a list of integers.

register(*args)

Register python objects for checkpointing.

Parameters

args (list of str) – Names of python objects to be registered for checkpointing.

register_signal(signum=None)

Register a signal that will trigger the signal handler.

Parameters

signum (int) – Signal to be registered.

save(checkpoint_index=None)

Saves all registered python objects in the given checkpoint directory using cPickle.

unregister(*args)

Unregister python objects for checkpointing.

Parameters

args (list of str) – Names of python objects to be unregistered for checkpointing.

espressomd.cluster_analysis module

class espressomd.cluster_analysis.Cluster

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 particles in the cluster

size():

Returns the number of particles in the cluster

center_of_mass():

center of mass of the cluster

longest_distance():

Longest distance between any combination of two particles in the cluster

fractal_dimension(dr=None):

estimates the cluster’s fractal dimension by fitting the number of particles \(n\) in spheres of growing radius around the center of mass to \(c*r_g^d\), where \(r_g\) is the radius of gyration of the particles within the sphere, and \(d\) is the fractal dimension.

Parameters

dr – Minimum increment for the radius of the spheres.

Returns

Fractal_dimension, mean_square_residual.

Return type

tuple

particles()

class espressomd.cluster_analysis.ClusterStructure(*args, **kwargs)

Bases: espressomd.script_interface.ScriptInterfaceHelper

Cluster structure of a simulation system, and access to cluster analysis

pair_criterion

Criterion to decide whether two particles are neighbors.

Type

classes derived from _PairCriterion

clusters

Access to individual clusters in the cluster structure either via cluster[i], where i is a (non-consecutive) integer cluster id or via iteration:

for pair in clusters:

where pair contains the numeric id and the corresponding cluster object.

Type

behaves like a read-only dictionary

cid_for_particle(p)

Returns cluster id for the particle (passed as ParticleHandle or particle id)

clear()

Clears the cluster structure.

cluster_ids()

Returns a list of all cluster ids of the clusters in the structure.

property clusters

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

run_for_all_pairs()

Runs the cluster analysis, considering all pairs of particles in the system

run_for_bonded_particles()

Runs the cluster analysis, considering only pairs of particles connected by a pair-bond.

class espressomd.cluster_analysis.Clusters(cluster_structure)

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

Bases: espressomd.script_interface.ScriptInterfaceHelper

Interface to the collision detection / dynamic binding.

See Creating bonds when particles collide for detailed instructions.

This class should not be instantiated by the user. Instead, use the espressomd.system.System.collision_detection attribute of the system class to access the collision detection.

Use espressomd.collision_detection.CollisionDetection.set_params() to change the parameters of the collision detection.

get_parameter(self, name)

Gets a single parameter from the collision detection.

get_params(self)

Returns the parameters of the collision detection as dict.

set_params(self, **kwargs)

Set the parameters for the collision detection

See Creating bonds when particles collide for detailed instructions.

Parameters

• mode (str, {“off”, “bind_centers”, “bind_at_point_of_collision”, “bind_three_particles”, “glue_to_surface”}) – Collision detection mode

• distance (float) – Distance below which a pair of particles is considered in the collision detection

• bond_centers (espressomd.interactions.BondedInteraction) – Bond to add between the colliding particles

• bond_vs (espressomd.interactions.BondedInteraction) – Bond to add between virtual sites (for modes using virtual sites)

• part_type_vs (int) – Particle type of the virtual sites being created on collision (virtual sites based modes)

• part_type_to_be_glued (int) – particle type for "glue_to_surface" mode. See user guide.

• part_type_to_attach_vs_to (int) – particle type for "glue_to_surface" mode. See user guide.

• part_type_after_glueing (int) – particle type for "glue_to_surface" mode. See user guide.

• distance_glued_particle_to_vs (float) – Distance for "glue_to_surface" mode. See user guide.

• bond_three_particles (espressomd.interactions.BondedInteraction) – First angular bond for the "bind_three_particles" mode. See user 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 180 degrees angles

validate(self)

Validates the parameters of the collision detection.

This is called automatically on parameter change

espressomd.comfixed module

class espressomd.comfixed.ComFixed

Bases: espressomd.script_interface.ScriptInterfaceHelper

Fix the center of mass of specific types.

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

Parameters

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

espressomd.constraints module

class espressomd.constraints.Constraint

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

Bases: espressomd.script_interface.ScriptObjectRegistry

List of active constraints. Add a espressomd.constraints.Constraint to make it active in the system, or remove it to make it inactive.

add(*args, **kwargs)

Add a constraint to the list.

Parameters

• constraint (espressomd.constraints.Constraint) – Either a constraint object…

• **kwargs (any) – … or parameters to construct an espressomd.constraints.ShapeBasedConstraint

Returns

constraint – The added constraint

Return type

espressomd.constraints.Constraint

clear()

Remove all constraints.

remove(constraint)

Remove a constraint from the list.

Parameters

constraint (espressomd.constraints.Constraint)

class espressomd.constraints.ElectricPlaneWave(phi=0, **kwargs)

Bases: espressomd.constraints.Constraint

Electric field of the form

\(E = E0 \cdot \sin(k \cdot x + \omega \cdot t + \phi)\)

The resulting force on the particles are then

\(F = q \cdot E\)

where \(q\) is the charge of the particle. This can be used to generate a homogeneous AC field by setting k to zero.

Parameters

• E0 (array_like of float) – Amplitude of the electric field.

• k (array_like of float) – Wave vector of the wave

• omega (float) – Frequency of the wave

• phi (float, optional) – Phase shift

property E0

property k

property omega

property phi

class espressomd.constraints.ElectricPotential(**kwargs)

Bases: espressomd.constraints._Interpolated

Electric potential interpolated from provided data. The electric field E is calculated numerically from the potential, and the resulting force on the particles are

\(F = q \cdot E\)

where \(q\) is the charge of the particle.

Parameters

• field ((M, N, O, 1) array_like of float) – Potential on a grid of size (M, N, O)

• grid_spacing ((3,) array_like of float) – Spacing of the grid points.

class espressomd.constraints.FlowField(**kwargs)

Bases: espressomd.constraints._Interpolated

Viscous coupling to a flow field that is interpolated from tabulated data like

\(F = -\gamma \cdot \left( u(r) - v \right)\)

where \(v\) is the velocity of the particle.

Parameters

• field ((M, N, O, 3) array_like of float) – Field velocity on a grid of size (M, N, O)

• grid_spacing ((3,) array_like of float) – Spacing of the grid points.

• gamma (float) – Coupling constant

class espressomd.constraints.ForceField(**kwargs)

Bases: espressomd.constraints._Interpolated

A generic tabulated force field that applies a per-particle scaling factor.

Parameters

• field ((M, N, O, 3) array_like of float) – Forcefield amplitude on a grid of size (M, N, O).

• grid_spacing ((3,) array_like of float) – Spacing of the grid points.

• default_scale (float) – Scaling factor for particles that have no individual scaling factor.

• particle_scales (array_like of (int, float)) – A list of tuples of ids and scaling factors. For particles in the list the interaction is scaled with their individual scaling factor before it is applied.

class espressomd.constraints.Gravity(**kwargs)

Bases: espressomd.constraints.Constraint

Gravity force

\(F = m \cdot g\)

Parameters

g ((3,) array_like of float) – The gravitational acceleration.

property g

class espressomd.constraints.HomogeneousFlowField(**kwargs)

Bases: espressomd.constraints.Constraint

Viscous coupling to a flow field that is constant in space with the force

\(F = -\gamma \cdot (u - v)\)

where \(v\) is the velocity of the particle.

u

Field velocity.

Type

(3,) array_like of float

gamma

Coupling constant

Type

float

property u

class espressomd.constraints.HomogeneousMagneticField

Bases: espressomd.constraints.Constraint

H

Magnetic field vector. Describes both field direction and strength of the magnetic field (via length of the vector).

Type

(3,) array_like of float

class espressomd.constraints.LinearElectricPotential(phi0=0, **kwargs)

Bases: espressomd.constraints.Constraint

Electric potential of the form

\(\phi = -E \cdot x + \phi_0\),

resulting in the electric field E everywhere. (E.g. in a plate capacitor). The resulting force on the particles are then

\(F = q \cdot E\)

where \(q\) is the charge of the particle.

Parameters

• E (array_like of float) – The electric field.

• phi0 (float) – The potential at the origin

property E

property phi0

class espressomd.constraints.PotentialField(**kwargs)

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.

Parameters

• field ((M, N, O, 1) array_like of float) – Potential on a grid of size (M, N, O).

• grid_spacing ((3,) array_like of float) – Spacing of the grid points.

• default_scale (float) – Scaling factor for particles that have no individual scaling factor.

• particle_scales (array_like (int, float)) – A list of tuples of ids and scaling factors. For particles in the list the interaction is scaled with their individual scaling factor before it is applied.

class espressomd.constraints.ShapeBasedConstraint

Bases: espressomd.constraints.Constraint

only_positive

Act only in the direction of positive normal, only useful if penetrable is True.

Type

bool

particle_type

Interaction type of the constraint.

Type

int

particle_velocity

Interaction velocity of the boundary

Type

array_like of float

penetrable

Whether particles are allowed to penetrate the constraint.

Type

bool

shape

One of the shapes from espressomd.shapes

Type

espressomd.shapes.Shape

See also

espressomd.shapes

shape module that define mathematical surfaces

Examples

>>> import espressomd
>>> from espressomd import shapes
>>> system = espressomd.System()
>>>
>>> # create first a shape-object to define the constraint surface
>>> spherical_cavity = shapes.Sphere(center=[5,5,5], radius=5.0, direction=-1.0)
>>>
>>> # now create an un-penetrable shape-based constraint of type 0
>>> spherical_constraint = system.constraints.add(particle_type=0, penetrable=False, shape=spherical_cavity)
>>>
>>> # place a trapped particle inside this sphere
>>> system.part.add(id=0, pos=[5, 5, 5], type=1)

min_dist()

Calculates the minimum distance to all interacting particles.

Returns

The minimum distance

Return type

float

total_force()

Get total force acting on this constraint.

Examples

>>> import espressomd
>>> from espressomd import shapes
>>> system = espressomd.System()
>>>
>>> system.time_step = 0.01
>>> system.box_l = [50, 50, 50]
>>> system.thermostat.set_langevin(kT=0.0, gamma=1.0)
>>> system.cell_system.set_n_square(use_verlet_lists=False)
>>> system.non_bonded_inter[0, 0].lennard_jones.set_params(
...     epsilon=1, sigma=1,
...     cutoff=2**(1. / 6), shift="auto")
>>>
>>> floor = system.constraints.add(shape=shapes.Wall(normal=[0, 0, 1], dist=0.0),
...    particle_type=0, penetrable=False, only_positive=False)
>>>
>>> system.part.add(id=0, pos=[0,0,1.5], type=0, ext_force=[0, 0, -.1])
>>> # print the particle position as it falls
>>> # and print the force it applies on the floor
>>> for t in range(10):
...     system.integrator.run(100)
...     print(system.part[0].pos, floor.total_force())

total_normal_force()

Get the total summed normal force acting on this constraint.

espressomd.cuda_init module

class espressomd.cuda_init.CudaInitHandle

Bases: object

device

Get device.

Returns

Id of current set device.

Return type

int

device_list

List devices.

Returns

List of available CUDA devices.

Return type

list

espressomd.cuda_init.gpu_available()

espressomd.diamond module

class espressomd.diamond.Diamond(*args, **kwargs)

Bases: object

Class to create a diamond-like polymer network.

Parameters

• a (float) – Size of the unit cell.

• bond_length (float) – Distance between adjacent monomers in the chains.

• MPC (int) – Monomers per chain.

• cM_dist (int, optional) – Distance between charged monomers.

• N_CI (int, optional) – Number of counter ions.

• val_nodes (float, optional) – Charge valency of the 8 node particles (crosslinker).

• val_cM (float, optional) – Valency of the charge bearing monomers.

• val_CI (float, optional) – Valency of the counterions.

• nonet (bool, optional) – False creates network, True does not crosslink the individual polymers.

default_params(self)

required_keys(self)

valid_keys(self)

validate_params(self)

espressomd.drude_helpers module

espressomd.drude_helpers.add_all_thole(system, verbose=False)

Calls add_thole_pair_damping() for all necessary combinations to create the interactions.

espressomd.drude_helpers.system

Type

Instance of espressomd.system.System

espressomd.drude_helpers.verbose

Turns on verbosity.

Type

bool

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)

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

espressomd.drude_helpers.system

Type

Instance of espressomd.system.System

espressomd.drude_helpers.harmonic_bond

Type

This method adds this harmonic bond to between Drude particle and core

espressomd.drude_helpers.thermalized_bond

Type

This method adds this thermalized_bond to between Drude particle and core

espressomd.drude_helpers.p_core

Type

The existing core particle

espressomd.drude_helpers.id_drude

This method creates the Drude particle and assigns this id.

Type

int

espressomd.drude_helpers.type_drude

The type of the newly created Drude particle

Type

int

espressomd.drude_helpers.alpha

The polarizability in units of inverse volume. Related to the charge of the Drude particle.

Type

float

espressomd.drude_helpers.mass_drude

The mass of the newly created Drude particle

Type

float

espressomd.drude_helpers.coulomb_prefactor

Required to calculate the charge of the Drude particle.

Type

float

espressomd.drude_helpers.thole_damping

Thole damping factor of the Drude pair. Comes to effect if add_all_thole() method is used.

Type

float

espressomd.drude_helpers.verbose

Turns on verbosity.

Type

bool

espressomd.drude_helpers.add_intramol_exclusion_bonds(system, drude_ids, core_ids, verbose=False)

Applies electrostatic short-range exclusion bonds for the given ids. Has to be applied for all molecules.

espressomd.drude_helpers.system

Type

Instance of espressomd.system.System

espressomd.drude_helpers.drude_ids

Type

IDs of Drude particles within a molecule.

espressomd.drude_helpers.core_ids

Type

IDs of core particles within a molecule.

espressomd.drude_helpers.verbose

Turns on verbosity.

Type

bool

espressomd.drude_helpers.add_thole_pair_damping(system, t1, t2, verbose=False)

Calculates mixed Thole factors depending on Thole damping and polarization. Adds non-bonded Thole interactions to the system.

espressomd.drude_helpers.system

Type

Instance of espressomd.system.System

espressomd.drude_helpers.t1

Type 1

Type

int

espressomd.drude_helpers.t2

Type 2

Type

int

espressomd.drude_helpers.verbose

Turns on verbosity.

Type

bool

espressomd.drude_helpers.setup_and_add_drude_exclusion_bonds(system, verbose=False)

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

espressomd.drude_helpers.system

Type

Instance of espressomd.system.System

espressomd.drude_helpers.verbose

Turns on verbosity.

Type

bool

espressomd.drude_helpers.setup_intramol_exclusion_bonds(system, mol_drude_types, mol_core_types, mol_core_partial_charges, verbose=False)

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

espressomd.drude_helpers.system

Type

Instance of espressomd.system.System

espressomd.drude_helpers.mol_drude_types

Type

List of types of Drude particles within the molecule

espressomd.drude_helpers.mol_core_types

Type

List of types of core particles within the molecule

espressomd.drude_helpers.mol_core_partial_charges

Type

List of partial charges of core particles within the molecule

espressomd.drude_helpers.verbose

Turns on verbosity.

Type

bool

espressomd.ekboundaries module

class espressomd.ekboundaries.EKBoundaries

Bases: espressomd.lbboundaries.LBBoundaries

Creates a set of electrokinetics boundaries.

class espressomd.ekboundaries.EKBoundary

Bases: espressomd.lbboundaries.LBBoundary

Creates a EK boundary.

espressomd.electrokinetics module

class espressomd.electrokinetics.Electrokinetics

Bases: espressomd.lb.HydrodynamicInteraction

Creates the electrokinetic method using the GPU unit.

add_boundary(self, shape)

add_reaction(self, shape)

add_species(self, species)

Initializes a new species for the electrokinetic method.

Parameters

species (int) – Species to be initialized.

default_params(self)

Returns the default parameters.

ek_init(self)

Initializes the electrokinetic system. This automatically initializes the lattice Boltzmann method on the GPU.

get_params(self)

Prints out the parameters of the electrokinetic system.

load_checkpoint(self, path)

neutralize_system(self, species)

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

Note

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

Parameters

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

print_vtk_boundary(self, path)

Writes the boundary information into a vtk-file.

Parameters

path (str) – The path and vtk-file name the boundary is written to.

print_vtk_density(self, path)

Writes the LB density information into a vtk-file.

Parameters

path (str) – The path and vtk-file name the LB density is written to.

print_vtk_lbforce(self, path)

Writes the LB force information into a vtk-file.

Parameters

path (str) – The path and vtk-file name the LB force is written to.

print_vtk_particle_potential(self, path)

Writes the electrostatic particle potential into a vtk-file.

Note

This only works if ‘es_coupling’ is active.

Parameters

path (str) – The path and vtk-file name the electrostatic potential is written to.

print_vtk_potential(self, path)

Writes the electrostatic potential into a vtk-file.

Parameters

path (str) – The path and vtk-file name the electrostatic potential is written to.

print_vtk_velocity(self, path)

Writes the lattice Boltzmann velocity information into a vtk-file.

Parameters

path (str) – The path and vtk-file name the velocity is written to.

required_keys(self)

Returns the necessary options to initialize the electrokinetic method.

save_checkpoint(self, path)

set_density(self, species=None, density=None, node=None)

Sets the density of a species at a specific node. If no node is given the density will be set global for the species.

Parameters

• species (int) – species for which the density will apply.

• density (float) – The value to which the density will be set to.

• node (numpy-array of type int of length (3)) – If set the density will be only applied on this specific node.

valid_keys(self)

Returns the valid options used for the electrokinetic method.

validate_params(self)

Checks if the parameters for “stencil” and “fluid_coupling” are valid.

class espressomd.electrokinetics.ElectrokineticsRoutines(key)

Bases: object

potential

pressure

velocity

class espressomd.electrokinetics.SpecieRoutines(key, id)

Bases: object

density

flux

class espressomd.electrokinetics.Species

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

Parameters

path (str) – The path and vtk-file name the species density is written to.

print_vtk_flux(self, path)

Writes the species flux into a vtk-file.

Parameters

path (str) – The path and vtk-file name the species flux is written to.

print_vtk_flux_fluc(self, path)

print_vtk_flux_link(self, path)

py_number_of_species = 0

required_keys(self)

Returns the required keys for the species.

valid_keys(self)

Returns the valid keys for the species.

espressomd.electrostatic_extensions module

class espressomd.electrostatic_extensions.ELC

Bases: espressomd.electrostatic_extensions.ElectrostaticExtensions

Electrostatics solver for systems with two periodic dimensions.

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 (bool, optional) – Selector parameter for setting a constant electric potential between the top and bottom of the simulation box.

• pot_diff (float, optional) – If const_pot mode is enabled 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 non-neutral systems. This corresponds then to a formal regularization of the forces and energies [BAC09]. Also, if you add neutralizing walls explicitly as constraints, you have to disable the neutralization. When using a dielectric contrast or full metallic walls (delta_mid_top != 0 or delta_mid_bot != 0 or const_pot=True), neutralize is overwritten and switched off internally. Note that the special case of non-neutral systems with a non-metallic dielectric jump (eg. delta_mid_top or delta_mid_bot in ]-1,1[) is not covered by the algorithm and will throw an error.

• 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\star algorithm

default_params(self)

last_iterations(self)

Number of iterations needed in last relaxation to reach the convergence criterion.

Returns

iterations – Number of iterations

Return type

int

required_keys(self)

valid_keys(self)

validate_params(self)

espressomd.electrostatics module

class espressomd.electrostatics.DH

Bases: espressomd.electrostatics.ElectrostaticInteraction

Electrostatics solver based on the Debye-Hueckel framework. See Debye-Hückel potential for more details.

Parameters

• prefactor (float) – Electrostatics prefactor (see (1)).

• kappa (float) – Inverse Debye screening length.

• r_cut (float) – Cut off radius for this interaction.

default_params(self)

required_keys(self)

valid_keys(self)

validate_params(self)

class espressomd.electrostatics.ElectrostaticInteraction

Bases: espressomd.actors.Actor

tune(self, **tune_params_subset)

class espressomd.electrostatics.MMM1D

Bases: espressomd.electrostatics.ElectrostaticInteraction

Electrostatics solver for systems with one periodic direction. See MMM1D theory for more details.

Parameters

• prefactor (float) – Electrostatics prefactor (see (1)).

• maxWPerror (float) – Maximal pairwise error.

• far_switch_radius (float, optional) – Radius where near-field and far-field 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)

class espressomd.electrostatics.MMM1DGPU

Bases: espressomd.electrostatics.ElectrostaticInteraction

Electrostatics solver with GPU support 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 near-field and far-field 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)

class espressomd.electrostatics.MMM2D

Bases: espressomd.electrostatics.ElectrostaticInteraction

Electrostatics solver for systems with two periodic dimensions. More detail are in the user guide MMM2D theory

Parameters

• prefactor (float) – Electrostatics prefactor (see (1)).

• maxWPerror (float) – Maximal pairwise error.

• dielectric (bool, optional) – Selector parameter for setting the dielectric constants manually (top, mid, bottom), mutually exclusive with dielectric-contrast

• 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 (bool, optional) – Selector parameter for setting a dielectric contrast between the upper simulation boundary and the simulation box, and between the lower simulation boundary and the simulation box, respectively.

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

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

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

• pot_diff (float, optional) – If const_pot mode is selected this parameter controls the applied voltage.

• far_cut (float, optional) – Cut off radius, use with care, intended for testing purposes.

default_params(self)

required_keys(self)

valid_keys(self)

validate_params(self)

class espressomd.electrostatics.P3M(*args, **kwargs)

Bases: espressomd.electrostatics.ElectrostaticInteraction

P3M electrostatics solver.

Particle–Particle–Particle–Mesh (P3M) is a Fourier-based Ewald summation method to calculate potentials in N-body simulation.

Parameters

• prefactor (float) – Electrostatics prefactor (see (1)).

• accuracy (float) – P3M tunes its parameters to provide this target accuracy.

• alpha (float, optional) – The Ewald parameter.

• cao (float, optional) – The charge-assignment order, an integer between 0 and 7.

• epsilon (float or str, optional) – A positive number for the dielectric constant of the surrounding medium. Use 'metallic' to set the dielectric constant of the surrounding medium to infinity (default).

• mesh (int or (3,) array_like of int, optional) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.

• r_cut (float, optional) – The real space cutoff.

• tune (bool, optional) – Used to activate/deactivate the tuning method on activation. Defaults to True.

• check_neutrality (bool, optional) – Raise a warning if the system is not electrically neutral when set to True (default).

default_params(self)

required_keys(self)

valid_keys(self)

validate_params(self)

class espressomd.electrostatics.P3MGPU(*args, **kwargs)

Bases: espressomd.electrostatics.ElectrostaticInteraction

P3M electrostatics solver with GPU support.

Particle–Particle–Particle–Mesh (P3M) is a Fourier-based Ewald summation method to calculate potentials in N-body simulation.

Parameters

• prefactor (float) – Electrostatics prefactor (see (1)).

• accuracy (float) – P3M tunes its parameters to provide this target accuracy.

• alpha (float, optional) – The Ewald parameter.

• cao (float, optional) – The charge-assignment order, an integer between 0 and 7.

• epsilon (float or str, optional) – A positive number for the dielectric constant of the surrounding medium. Use 'metallic' to set the dielectric constant of the surrounding medium to infinity (default).

• mesh (int or (3,) array_like of int, optional) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.

• r_cut (float, optional) – The real space cutoff

• tune (bool, optional) – Used to activate/deactivate the tuning method on activation. Defaults to True.

• check_neutrality (bool, optional) – Raise a warning if the system is not electrically neutral when set to True (default).

default_params(self)

required_keys(self)

valid_keys(self)

validate_params(self)

class espressomd.electrostatics.ReactionField

Bases: espressomd.electrostatics.ElectrostaticInteraction

Electrostatics solver based on the Reaction-Field framework.

Parameters

• prefactor (float) – Electrostatics prefactor (see (1)).

• kappa (float) – Inverse Debye screening length.

• epsilon1 (float) – interior dielectric constant

• epsilon2 (float) – exterior dielectric constant

• r_cut (float) – Cut off radius for this interaction.

default_params(self)

required_keys(self)

valid_keys(self)

validate_params(self)

class espressomd.electrostatics.Scafacos

Bases: espressomd.scafacos.ScafacosConnector, espressomd.electrostatics.ElectrostaticInteraction

Calculate the Coulomb interaction using the ScaFaCoS library.

default_params(self)

dipolar = False

espressomd.electrostatics.check_neutrality(_params)

espressomd.galilei module

class espressomd.galilei.GalileiTransform

Bases: object

galilei_transform(self)

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

kill_particle_forces(self, torque=False)

Set the forces on the particles to zero.

Parameters

torque (bool, optional) – Whether or not to kill the torques on all particles too.

kill_particle_motion(self, rotation=False)

Stop the motion of the particles.

Parameters

rotation (bool, optional) – Whether or not to kill the rotations too.

system_CMS(self)

Calculate the center of mass of the system. Assumes equal unit mass if the mass feature is not used.

Returns

cms – The of the center of mass position vector.

Return type

(3,) array_like of float

system_CMS_velocity(self)

Calculate the center of mass velocity of the system. Assumes equal unit mass if the mass feature is not used.

Returns

cms_vel – The of the center of mass velocity vector.

Return type

(3,) array_like of float

espressomd.globals module

class espressomd.globals.Globals

Bases: object

box_l

force_cap

min_global_cut

periodicity

time

time_step

timings

espressomd.highlander module

exception espressomd.highlander.ThereCanOnlyBeOne(cls)

Bases: BaseException

espressomd.highlander.highlander(klass)

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.

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 ((3,) array_like of int, optional) – Set the box geometry for non-cubic boxes.

• cubic_box (bool, optional) – If this optional parameter is true, a cubic box is assumed.

set_nvt(self)

Set the integration method to NVT.

set_steepest_descent(self, *args, **kwargs)

Set parameters for steepest descent.

See also

espressomd.minimize_energy.MinimizeEnergy

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

Parameters

• phi0 (float) – Equilibrium bond angle in radians.

• bend (float) – Magnitude of the bond interaction.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.AngleCossquare

Bases: espressomd.interactions.BondedInteraction

Bond-angle-dependent cosine squared potential.

Parameters

• phi0 (float) – Equilibrium bond angle in radians.

• bend (float) – Magnitude of the bond interaction.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.AngleHarmonic

Bases: espressomd.interactions.BondedInteraction

Bond-angle-dependent harmonic potential.

Parameters

• phi0 (float) – Equilibrium bond angle in radians.

• bend (float) – Magnitude of the bond interaction.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.BMHTFInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the BMHTF interaction.

Parameters

• a (float) – Magnitude of exponential part of the interaction.

• b (float) – Exponential factor of the interaction.

• c (float) – Magnitude of the term decaying with the sixth power of r.

• d (float) – Magnitude of the term decaying with the eighth power of r.

• sig (float) – Shift in the exponent.

• cutoff (float) – Cutoff distance of the interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.BondedCoulomb

Bases: espressomd.interactions.BondedInteraction

Bonded Coulomb bond.

Parameters

prefactor (float) – Coulomb prefactor of the bonded Coulomb interaction.

required_keys(self)

set_default_params(self)

type_name(self)

type_number(self)

valid_keys(self)

class espressomd.interactions.BondedCoulombSRBond

Bases: espressomd.interactions.BondedInteraction

Bonded Coulomb short range bond. Calculates the short range part of Coulomb interactions.

Parameters

q1q2 (float) – Charge factor of the involved particle pair. Note the particle charges are used to allow e.g. only partial subtraction of the involved charges.

required_keys(self)

set_default_params(self)

type_name(self)

type_number(self)

valid_keys(self)

class espressomd.interactions.BondedInteraction(*args, **kwargs)

Bases: object

Base class for bonded interactions.

Either called with an interaction id, in which case the interaction will represent the bonded interaction as it is defined in Espresso core, or called with keyword arguments describing a new interaction.

is_valid(self)

Check, if the data stored in the instance still matches what is in Espresso.

params

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.BondedInteractionNotDefined

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 (float, optional) – Exponent of the exponential part of the interaction.

• c (float) – Prefactor of term decaying with the sixth power of distance.

• d (float) – Prefactor of term decaying with the fourth power of distance.

• discont (float) – Distance below which the potential is linearly continued.

• cutoff (float) – Cutoff distance of the interaction.

• shift (float, optional) – Constant potential shift.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.DPDInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

is_active(self)

required_keys(self)

set_params(self, **kwargs)

Set parameters for the DPD interaction.

Parameters

• weight_function (int, {0, 1}) – The distance dependence of the parallel part, either 0 (constant) or 1 (linear)

• gamma (float) – Friction coefficient of the parallel part

• r_cut (float) – Cutoff of the parallel part

• trans_weight_function (int, {0, 1}) – The distance dependence of the orthogonal part, either 0 (constant) or 1 (linear)

• trans_gamma (float) – Friction coefficient of the orthogonal part

• trans_r_cut (float) – Cutoff of the orthogonal part

type_name(self)

valid_keys(self)

validate_params(self)

class espressomd.interactions.Dihedral

Bases: espressomd.interactions.BondedInteraction

Dihedral potential with phase shift.

Parameters

• mult (int) – Multiplicity of the potential (number of minima).

• bend (float) – Bending constant.

• phase (float) – Angle of the first local minimum in radians.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.FeneBond

Bases: espressomd.interactions.BondedInteraction

FENE bond.

Parameters

• k (float) – Magnitude of the bond interaction.

• d_r_max (float) – Maximum stretch and compression length of the bond.

• r_0 (float, optional) – Equilibrium bond length.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.GaussianInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Gaussian interaction.

Parameters

• eps (float) – Overlap energy epsilon.

• sig (float) – Variance sigma of the Gaussian interaction.

• cutoff (float) – Cutoff distance of the interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.GayBerneInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Gay-Berne interaction.

Parameters

• eps (float) – Potential well depth.

• sig (float) – Interaction range.

• cut (float) – Cutoff distance of the interaction.

• k1 (float or str) – Molecular elongation.

• k2 (float, optional) – Ratio of the potential well depths for the side-by-side and end-to-end configurations.

• mu (float, optional) – Adjustable exponent.

• nu (float, optional) – Adjustable exponent.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.GenericLennardJonesInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the generic Lennard-Jones interaction.

Parameters

• epsilon (float) – Magnitude of the interaction.

• sigma (float) – Interaction length scale.

• cutoff (float) – Cutoff distance of the interaction.

• shift (float or str {‘auto’}) – Constant shift of the potential. If 'auto', a default value is computed from the other parameters. The LJ potential will be shifted by \(\epsilon\cdot\text{shift}\).

• offset (float) – Offset distance of the interaction.

• e1 (int) – Exponent of the repulsion term.

• e2 (int) – Exponent of the attraction term.

• b1 (float) – Prefactor of the repulsion term.

• b2 (float) – Prefactor of the attraction term.

• delta (float, optional) – LJGEN_SOFTCORE parameter delta. Allows control over how smoothly the potential drops to zero as lambda approaches zero.

• lam (float, optional) – LJGEN_SOFTCORE parameter lambda. Tune the strength of the interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

Raises

ValueError – If not true.

class espressomd.interactions.HarmonicBond

Bases: espressomd.interactions.BondedInteraction

Harmonic bond.

Parameters

• k (float) – Magnitude of the bond interaction.

• r_0 (float) – Equilibrium bond length.

• r_cut (float, optional) – Maximum distance beyond which the bond is considered broken.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.HarmonicDumbbellBond

Bases: espressomd.interactions.BondedInteraction

Harmonic Dumbbell bond.

Parameters

• k1 (float) – Magnitude of the bond interaction.

• k2 (float) – Magnitude of the angular interaction.

• r_0 (float) – Equilibrium bond length.

• r_cut (float, optional) – Maximum distance beyond which the bond is considered broken.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.HatInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

is_active(self)

required_keys(self)

set_params(self, **kwargs)

Set parameters for the Hat interaction.

Parameters

• F_max (float) – Magnitude of the interaction.

• cutoff (float) – Cutoff distance of the interaction.

type_name(self)

valid_keys(self)

validate_params(self)

class espressomd.interactions.HertzianInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Hertzian interaction.

Parameters

• eps (float) – Magnitude of the interaction.

• sig (float) – Parameter sigma. Determines the length over which the potential decays.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.IBM_Tribend

Bases: espressomd.interactions.BondedInteraction

IBM Tribend bond.

Parameters

• ind1, ind2, ind3, ind4 (int) – First, second, third and fourth bonding partner. Used for initializing reference state

• kb (float) – Bending modulus

• refShape (str, optional, {‘Flat’, ‘Initial’}) – Reference shape, default is 'Flat'

required_keys(self)

set_default_params(self)

type_name(self)

type_number(self)

valid_keys(self)

class espressomd.interactions.IBM_Triel

Bases: espressomd.interactions.BondedInteraction

IBM Triel bond.

Parameters

• ind1, ind2, ind3 (int) – First, second and third bonding partner. Used for initializing reference state

• k1 (float) – Shear elasticity for Skalak and Neo-Hookean

• k2 (float) – Area resistance for Skalak

• maxDist (float) – Gives an error if an edge becomes longer than maxDist

• elasticLaw (str) – Specify NeoHookean or Skalak

required_keys(self)

set_default_params(self)

type_name(self)

type_number(self)

valid_keys(self)

class espressomd.interactions.IBM_VolCons

Bases: espressomd.interactions.BondedInteraction

IBM volume conservation bond.

Parameters

• softID (int) – Used to identify the object to which this bond belongs. Each object (cell) needs its own ID

• kappaV (float) – Modulus for volume force

required_keys(self)

set_default_params(self)

type_name(self)

type_number(self)

valid_keys(self)

class espressomd.interactions.LennardJonesCos2Interaction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

is_active(self)

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Lennard-Jones cosine squared interaction.

Parameters

• epsilon (float) – Magnitude of the interaction.

• sigma (float) – Interaction length scale.

• offset (float, optional) – Offset distance of the interaction.

• width (float) – Width of interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

class espressomd.interactions.LennardJonesCosInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

is_active(self)

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Lennard-Jones cosine interaction.

Parameters

• epsilon (float) – Magnitude of the interaction.

• sigma (float) – Interaction length scale.

• cutoff (float) – Cutoff distance of the interaction.

• offset (float, optional) – Offset distance of the interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

class espressomd.interactions.LennardJonesInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Lennard-Jones interaction.

Parameters

• epsilon (float) – Magnitude of the interaction.

• sigma (float) – Interaction length scale.

• cutoff (float) – Cutoff distance of the interaction.

• shift (float or str {‘auto’}) – Constant shift of the potential. If 'auto', a default value is computed from sigma and cutoff. The LJ potential will be shifted by \(4\epsilon\cdot\text{shift}\).

• offset (float, optional) – Offset distance of the interaction.

• min (float, optional) – Restricts the interaction to a minimal distance.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

Raises

ValueError – If not true.

class espressomd.interactions.MembraneCollisionInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

is_active(self)

required_keys(self)

type_name(self)

valid_keys(self)

validate_params(self)

class espressomd.interactions.MorseInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Morse interaction.

Parameters

• eps (float) – The magnitude of the interaction.

• alpha (float) – Stiffness of the Morse interaction.

• rmin (float) – Distance of potential minimum

• cutoff (float, optional) – Cutoff distance of the interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.NonBondedInteraction(*args, **kwargs)

Bases: object

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

default_params(self)

Virtual method.

get_params(self)

Get interaction parameters.

is_active(self)

Virtual method.

is_valid(self)

Check, if the data stored in the instance still matches what is in Espresso.

required_keys(self)

Virtual method.

set_params(self, **p)

Update the given parameters.

type_name(self)

Virtual method.

user_interactions

object

Type

user_interactions

valid_keys(self)

Virtual method.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.NonBondedInteractionHandle

Bases: object

Provides access to all non-bonded 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 non-bonded interaction parameters via [i,j], where i, j are particle types. Returns a NonBondedInteractionHandle object. Also: access to force capping.

reset(self)

Reset all interaction parameters to their default values.

class espressomd.interactions.OifGlobalForces

Bases: espressomd.interactions.BondedInteraction

Characterize the distribution of the force of the global mesh deformation onto individual vertices of the mesh.

Part of the Object-in-fluid method.

Parameters

• A0_g (float) – Relaxed area of the mesh

• ka_g (float) – Area coefficient

• V0 (float) – Relaxed volume of the mesh

• kv (float) – Volume coefficient

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.OifLocalForces

Bases: espressomd.interactions.BondedInteraction

Characterize the deformation of two triangles sharing an edge.

Part of the Object-in-fluid method.

Parameters

• r0 (float) – Equilibrium bond length of triangle edges

• ks (float) – Non-linear stretching coefficient of triangle edges

• kslin (float) – Linear stretching coefficient of triangle edges

• phi0 (float) – Equilibrium angle between the two triangles

• kb (float) – Bending coefficient for the angle between the two triangles

• A01 (float) – Equilibrium surface of the first triangle

• A02 (float) – Equilibrium surface of the second triangle

• kal (float) – Stretching coefficient of a triangle surface

• kvisc (float) – Viscous coefficient of the triangle vertices

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.OifOutDirection

Bases: espressomd.interactions.BondedInteraction

Determine the surface normals of triangles on a mesh. Takes no parameter.

required_keys(self)

set_default_params(self)

type_name(self)

type_number(self)

valid_keys(self)

class espressomd.interactions.QuarticBond

Bases: espressomd.interactions.BondedInteraction

Quartic bond.

Parameters

• k0 (float) – Magnitude of the square term.

• k1 (float) – Magnitude of the fourth order term.

• r (float) – Equilibrium bond length.

• r_cut (float) – Maximum interaction length.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.RigidBond

Bases: espressomd.interactions.BondedInteraction

Rigid bond.

Parameters

• r (float) – Bond length.

• ptol (float, optional) – Tolerance for positional deviations.

• vtop (float, optional) – Tolerance for velocity deviations.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.SmoothStepInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the smooth-step interaction.

Parameters

• d (float) – Short range repulsion parameter.

• n (int, optional) – Exponent of short range repulsion.

• eps (float) – Magnitude of the second (soft) repulsion.

• k0 (float, optional) – Exponential factor in second (soft) repulsion.

• sig (float, optional) – Length scale of second (soft) repulsion.

• cutoff (float) – Cutoff distance of the interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.SoftSphereInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the Soft-sphere interaction.

Parameters

• a (float) – Magnitude of the interaction.

• n (float) – Exponent of the power law.

• cutoff (float) – Cutoff distance of the interaction.

• offset (float, optional) – Offset distance of the interaction.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.SubtLJ

Bases: espressomd.interactions.BondedInteraction

Subtracted LJ potential. Takes no parameter.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.TabulatedAngle

Bases: espressomd.interactions._TabulatedBase

Tabulated bond angle.

Parameters

• energy (array_like of float) – The energy table for the range \(0-\pi\).

• force (array_like of float) – The force table for the range \(0-\pi\).

pi = 3.14159265358979

type_name(self)

Name of interaction type.

type_number(self)

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.TabulatedDihedral

Bases: espressomd.interactions._TabulatedBase

Tabulated bond dihedral.

Parameters

• energy (array_like of float) – The energy table for the range \(0-2\pi\).

• force (array_like of float) – The force table for the range \(0-2\pi\).

pi = 3.14159265358979

type_name(self)

Name of interaction type.

type_number(self)

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.TabulatedDistance

Bases: espressomd.interactions._TabulatedBase

Tabulated bond length.

Parameters

• min (float) – The minimal interaction distance.

• max (float) – The maximal interaction distance.

• energy (array_like of float) – The energy table.

• force (array_like of float) – The force table.

type_name(self)

Name of interaction type.

type_number(self)

validate_params(self)

Check that parameters are valid.

class espressomd.interactions.TabulatedNonBonded(*args, **kwargs)

Bases: espressomd.interactions.NonBondedInteraction

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Set parameters that are not required to their default value.

set_params(self, **kwargs)

Set parameters for the TabulatedNonBonded interaction.

Parameters

• min (float,) – The minimal interaction distance.

• max (float,) – The maximal interaction distance.

• energy (array_like of float) – The energy table.

• force (array_like of float) – The force table.

type_name(self)

Name of the potential.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.ThermalizedBond

Bases: espressomd.interactions.BondedInteraction

Thermalized bond.

Parameters

• temp_com (float) – Temperature of the Langevin thermostat for the center of mass of the particle pair.

• gamma_com (float) – Friction coefficient of the Langevin thermostat for the center of mass of the particle pair.

• temp_distance (float) – Temperature of the Langevin thermostat for the distance vector of the particle pair.

• gamma_distance (float) – Friction coefficient of the Langevin thermostat for the distance vector of the particle pair.

• r_cut (float, optional) – Maximum distance beyond which the bond is considered broken.

• seed (int) – Initial counter value (or seed) of the philox RNG. Required on the first thermalized bond in the system. Must be positive. If prompted, it does not return the initially set counter value (the seed) but the current state of the RNG.

required_keys(self)

set_default_params(self)

type_name(self)

type_number(self)

valid_keys(self)

class espressomd.interactions.TholeInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

is_active(self)

required_keys(self)

set_params(self, **kwargs)

Set parameters for the Thole interaction.

Parameters

• scaling_coeff (float) – The factor used in the Thole damping function between polarizable particles i and j. Usually calculated by the polarizabilities \(\alpha_i\), \(\alpha_j\) and damping parameters \(a_i\), \(a_j\) via \(s_{ij} = \frac{(a_i+a_j)/2}{((\alpha_i\cdot\alpha_j)^{1/2})^{1/3}}\)

• q1q2 (float) – Charge factor of the involved charges. Has to be set because it acts only on the portion of the Drude core charge that is associated to the dipole of the atom. For charged, polarizable atoms that charge is not equal to the particle charge property.

type_name(self)

valid_keys(self)

validate_params(self)

class espressomd.interactions.Virtual

Bases: espressomd.interactions.BondedInteraction

Virtual bond.

required_keys(self)

Parameters that have to be set.

set_default_params(self)

Sets parameters that are not required to their default value.

type_name(self)

Name of interaction type.

type_number(self)

valid_keys(self)

All parameters that can be set.

class espressomd.interactions.WCAInteraction

Bases: espressomd.interactions.NonBondedInteraction

default_params(self)

Python dictionary of default parameters.

is_active(self)

Check if interaction is active.

required_keys(self)

Parameters that have to be set.

set_params(self, **kwargs)

Set parameters for the WCA interaction.

Parameters

• epsilon (float) – Magnitude of the interaction.

• sigma (float) – Interaction length scale.

type_name(self)

Name of interaction type.

valid_keys(self)

All parameters that can be set.

validate_params(self)

Check that parameters are valid.

Raises

ValueError – If not true.

espressomd.lb module

class espressomd.lb.HydrodynamicInteraction

Bases: espressomd.actors.Actor

agrid

bulk_viscosity

default_params(self)

density

ext_force_density

get_interpolated_velocity(self, pos)

Get LB fluid velocity at specified position.

Parameters

pos ((3,) array_like of float) – The position at which velocity is requested.

Returns

v – The LB fluid velocity at pos.

Return type

(3,) array_like float

kT

load_checkpoint(self, path, binary)

nodes(self)

Provides a generator for iterating over all lb nodes

print_boundary(self, path)

print_velocity(self, path)

print_vtk_boundary(self, path)

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

required_keys(self)

save_checkpoint(self, path, binary)

seed

set_interpolation_order(self, interpolation_order)

Set the order for the fluid interpolation scheme.

Parameters

interpolation_order (str) – "linear" for linear interpolation, "quadratic" for quadratic interpolation.

shape

stress

tau

valid_keys(self)

validate_params(self)

viscosity

class espressomd.lb.LBFluid

Bases: espressomd.lb.HydrodynamicInteraction

Initialize the lattice-Boltzmann method for hydrodynamic flow using the CPU.

class espressomd.lb.LBFluidGPU

Bases: espressomd.lb.HydrodynamicInteraction

Initialize the lattice-Boltzmann method for hydrodynamic flow using the GPU.

get_interpolated_fluid_velocity_at_positions(self, ndarray positions, three_point=False)

Calculate the fluid velocity at given positions.

Parameters

positions ((N,3) numpy-array of type float) – The 3-dimensional positions.

Returns

velocities – The 3-dimensional LB fluid velocities.

Return type

(N,3) numpy-array of type float

Raises

AssertionError – If shape of positions not (N,3).

class espressomd.lb.LBFluidRoutines(key)

Bases: object

boundary

density

index

population

stress

stress_neq

velocity

espressomd.lb.assert_agrid_tau_set(obj)

espressomd.lbboundaries module

class espressomd.lbboundaries.LBBoundaries

Bases: espressomd.script_interface.ScriptObjectRegistry

Creates a set of lattice Boltzmann boundaries.

add(*args, **kwargs)

Adds a boundary to the set. Either a valid boundary is an argument, or a valid set of parameters to create a boundary.

clear()

Removes all boundaries.

empty()

remove(lbboundary)

Removes a boundary from the set.

Parameters

lbboundary (LBBoundary) – The boundary to be removed from the set.

size()

class espressomd.lbboundaries.LBBoundary

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 z-axis. As a reference for the DLC method, see [Brodka04].

far_cut

Cutoff of the exponential sum.

Type

float

gap_size

Size of the empty gap. Note that DLC relies on the user to make sure that this condition is fulfilled.

Type

float

maxPWerror

Maximal pairwise error of the potential and force.

Type

float

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

Magnetostatics prefactor (\(\mu_0/(4\pi)\))

Type

float

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

Magnetostatics prefactor (\(\mu_0/(4\pi)\))

Type

float

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

Magnetostatics prefactor (\(\mu_0/(4\pi)\))

Type

float

n_replica

Number of replicas to be taken into account at periodic boundaries.

Type

int

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

Magnetostatics prefactor (\(\mu_0/(4\pi)\))

Type

float

accuracy

P3M tunes its parameters to provide this target accuracy.

Type

float

alpha

Ewald parameter.

Type

float

cao

Charge-assignment order, an integer between -1 and 7.

Type

int

mesh

The number of mesh points in x, y and z direction. Use a single value for cubic boxes.

Type

int or (3,) array_like of int

mesh_off

Mesh offset.

Type

(3,) array_like of float

r_cut

Real space cutoff.

Type

float

tune

Activate/deactivate the tuning method on activation (default is True, i.e., activated).

Type

bool, optional

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

Magnetostatics prefactor (\(\mu_0/(4\pi)\))

Type

float

set_magnetostatics_prefactor(self)

Set the magnetostatics prefactor

validate_params(self)

Check validity of given parameters.

class espressomd.magnetostatics.Scafacos

Bases: espressomd.scafacos.ScafacosConnector, espressomd.magnetostatics.MagnetostaticInteraction

Calculates dipolar interactions using dipoles-capable method from the SCAFACOs library.

prefactor

Magnetostatics prefactor (\(\mu_0/(4\pi)\))

Type

float

method_name

Name of the method as defined in Scafacos

Type

str

method_params

Dictionary with the key-value pairs of the method parameters as defined in Scafacos. Note that the values are cast to strings to match Scafacos’ interface

Type

dict

default_params(self)

dipolar = True

espressomd.minimize_energy module

class espressomd.minimize_energy.MinimizeEnergy(*args, **kwargs)

Bases: object

Steepest descent algorithm for energy minimization.

Particles located at \(\vec{r}_i\) at integration step \(i\) and experiencing a potential \(\mathcal{H}(\vec{r}_i)\) are displaced according to the equation:

\(\vec{r}_{i+1} = \vec{r}_i - \gamma\nabla\mathcal{H}(\vec{r}_i)\)

Parameters

• f_max (float) – Convergence criterion. Minimization stops when the maximal force on particles in the system is lower than this threshold. Set this to 0 when running minimization in a loop that stops when a custom convergence criterion is met.

• gamma (float) – Dampening constant.

• max_steps (int) – Maximal number of iterations.

• max_displacement (float) – Maximal allowed displacement per step. Typical values for a LJ liquid are in the range of 0.1% to 10% of the particle sigma.

default_params(self)

init(self, *args, **kwargs)

minimize(self)

Perform energy minimization sweep.

required_keys(self)

validate_params(self)

espressomd.observables module

class espressomd.observables.BondAngles

Bases: espressomd.observables.Observable

Calculates the angles between bonds of particles with given ids along a polymer chain.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.BondDihedrals

Bases: espressomd.observables.Observable

Calculates the dihedrals between particles with given ids along a polymer chain.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.ComForce

Bases: espressomd.observables.Observable

Calculates the total force on particles with given ids.

Note that virtual sites are not included since they do not have a meaningful mass.

Output format: \(\left(\sum_i f^x_i, \sum_i f^y_i, \sum_i f^z_i\right)\)

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.ComPosition

Bases: espressomd.observables.Observable

Calculates the center of mass for particles with given ids.

Note that virtual sites are not included since they do not have a meaningful mass.

Output format: \(\frac{1}{\sum_i m_i} \left( \sum_i m_i r^x_i, \sum_i m_i r^y_i, \sum_i m_i r^z_i\right)\)

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.ComVelocity

Bases: espressomd.observables.Observable

Calculates the center of mass velocity for particles with given ids.

Note that virtual sites are not included since they do not have a meaningful mass.

Output format: \(\frac{1}{\sum_i m_i} \left( \sum_i m_i v^x_i, \sum_i m_i v^y_i, \sum_i m_i v^z_i\right)\)

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.CosPersistenceAngles

Bases: espressomd.observables.Observable

Calculates the cosine of mutual bond angles for chained particles with given ids.

The i-th value of the result contains the cosine of the angle between bonds that are separated by i bonds. The values are averaged over the chain.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.Current

Bases: espressomd.observables.Observable

Calculates the electric current for particles with given ids.

Output format: \(\left(\sum_i q_i v^x_i, \sum_i q_i v^y_i, \sum_i q_i v^z_i, \right)\)

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.CylindricalDensityProfile

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 ((3,) array_like of float) – Position of the center of the polar coordinate system for the histogram.

• axis ((3,) array_like of float) – Orientation vector of the z-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 in z direction.

• min_r (float) – Minimum r to consider.

• min_phi (float) – Minimum phi to consider.

• min_z (float) – Minimum z to consider.

• max_r (float) – Maximum r to consider.

• max_phi (float) – Maximum phi to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.CylindricalFluxDensityProfile

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 ((3,) array_like of float) – Position of the center of the polar coordinate system for the histogram.

• axis ((3,) array_like of float) – Orientation vector of the z-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 in z direction.

• min_r (float) – Minimum r to consider.

• min_phi (float) – Minimum phi to consider.

• min_z (float) – Minimum z to consider.

• max_r (float) – Maximum r to consider.

• max_phi (float) – Maximum phi to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.CylindricalLBFluxDensityProfileAtParticlePositions

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 ((3,) array_like of float) – Position of the center of the polar coordinate system for the histogram.

• axis ((3,) array_like of float) – Orientation vector of the z-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 in z direction.

• min_r (float) – Minimum r to consider.

• min_phi (float) – Minimum phi to consider.

• min_z (float) – Minimum z to consider.

• max_r (float) – Maximum r to consider.

• max_phi (float) – Maximum phi to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.CylindricalLBVelocityProfile

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 ((3,) array_like of float) – Position of the center of the polar coordinate system for the histogram.

• axis ((3,) array_like of float) – Orientation vector of the z-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 in z direction.

• min_r (float) – Minimum r to consider.

• min_phi (float) – Minimum phi to consider.

• min_z (float) – Minimum z to consider.

• max_r (float) – Maximum r to consider.

• max_phi (float) – Maximum phi to consider.

• max_z (float) – Maximum z to consider.

• sampling_density (float) – Samples per unit volume for the LB velocity interpolation.

class espressomd.observables.CylindricalLBVelocityProfileAtParticlePositions

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 ((3,) array_like of float) – Position of the center of the polar coordinate system for the histogram.

• axis ((3,) array_like of float) – Orientation vector of the z-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 in z direction.

• min_r (float) – Minimum r to consider.

• min_phi (float) – Minimum phi to consider.

• min_z (float) – Minimum z to consider.

• max_r (float) – Maximum r to consider.

• max_phi (float) – Maximum phi to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.CylindricalVelocityProfile

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 ((3,) array_like of float) – Position of the center of the polar coordinate system for the histogram.

• axis ((3,) array_like of float) – Orientation vector of the z-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 in z direction.

• min_r (float) – Minimum r to consider.

• min_phi (float) – Minimum phi to consider.

• min_z (float) – Minimum z to consider.

• max_r (float) – Maximum r to consider.

• max_phi (float) – Maximum phi to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.DPDStress

Bases: espressomd.observables.Observable

Calculates the non-equilibrium contribution of the DPD interaction to the stress tensor.

Parameters

None

class espressomd.observables.DensityProfile

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 in x direction.

• n_y_bins (int) – Number of bins in y direction.

• n_z_bins (int) – Number of bins in z direction.

• min_x (float) – Minimum x to consider.

• min_y (float) – Minimum y to consider.

• min_z (float) – Minimum z to consider.

• max_x (float) – Maximum x to consider.

• max_y (float) – Maximum y to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.DipoleMoment

Bases: espressomd.observables.Observable

Calculates the dipole moment for particles with given ids.

Output format: \(\left(\sum_i q_i r^x_i, \sum_i q_i r^y_i, \sum_i q_i r^z_i\right)\)

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.FluxDensityProfile

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 in x direction.

• n_y_bins (int) – Number of bins in y direction.

• n_z_bins (int) – Number of bins in z direction.

• min_x (float) – Minimum x to consider.

• min_y (float) – Minimum y to consider.

• min_z (float) – Minimum z to consider.

• max_x (float) – Maximum x to consider.

• max_y (float) – Maximum y to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.ForceDensityProfile

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 in x direction.

• n_y_bins (int) – Number of bins in y direction.

• n_z_bins (int) – Number of bins in z direction.

• min_x (float) – Minimum x to consider.

• min_y (float) – Minimum y to consider.

• min_z (float) – Minimum z to consider.

• max_x (float) – Maximum x to consider.

• max_y (float) – Maximum y to consider.

• max_z (float) – Maximum z to consider.

class espressomd.observables.LBFluidStress

Bases: espressomd.observables.Observable

Calculates the average stress of the LB fluid for all nodes.

Parameters

None

class espressomd.observables.LBVelocityProfile

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 in x direction.

• n_y_bins (int) – Number of bins in y direction.

• n_z_bins (int) – Number of bins in z direction.

• min_x (float) – Minimum x to consider.

• min_y (float) – Minimum y to consider.

• min_z (float) – Minimum z to consider.

• max_x (float) – Maximum x to consider.

• max_y (float) – Maximum y to consider.

• max_z (float) – Maximum z to consider.

• sampling_delta_x (float, default=1.0) – Spacing for the sampling grid in x-direction.

• sampling_delta_y (float, default=1.0) – Spacing for the sampling grid in y-direction.

• sampling_delta_z (float, default=1.0) – Spacing for the sampling grid in z-direction.

• sampling_offset_x (float, default=0.0) – Offset for the sampling grid in x-direction.

• sampling_offset_y (float, default=0.0) – Offset for the sampling grid in y-direction.

• sampling_offset_z (float, default=0.0) – Offset for the sampling grid in z-direction.

• allow_empty_bins (bool, default=False) – Whether or not to allow bins that will not be sampled at all.

class espressomd.observables.MagneticDipoleMoment

Bases: espressomd.observables.Observable

Calculates the magnetic dipole moment for particles with given ids.

Output format: \(\left(\sum_i \mu^x_i, \sum_i \mu^y_i, \sum_i \mu^z_i\right)\)

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.Observable

Bases: espressomd.script_interface.ScriptInterfaceHelper

class espressomd.observables.ParticleAngularVelocities

Bases: espressomd.observables.Observable

class espressomd.observables.ParticleBodyAngularVelocities

Bases: espressomd.observables.Observable

class espressomd.observables.ParticleBodyVelocities

Bases: espressomd.observables.Observable

Calculates the particle velocity in the particles’ body-fixed frame of reference.

For each particle, the body-fixed frame of reference is obtained from the particle’s orientation stored in the quaternions.

Output format: \(v_{x1},\ v_{y1},\ v_{z1},\ v_{x2},\ v_{y2},\ v_{z2},\ \dots\ v_{xn},\ v_{yn},\ v_{zn}\).

The particles are ordered according to the list of ids passed to the observable.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.ParticleDistances

Bases: espressomd.observables.Observable

Calculates the distances between particles with given ids along a polymer chain.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.ParticleForces

Bases: espressomd.observables.Observable

Calculates the particle forces for particles with given ids.

Output format: \(f_{x1},\ f_{y1},\ f_{z1},\ f_{x2},\ f_{y2},\ f_{z2},\ \dots\ f_{xn},\ f_{yn},\ f_{zn}\).

The particles are ordered according to the list of ids passed to the observable.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.ParticlePositions

Bases: espressomd.observables.Observable

Calculates the particle positions for particles with given ids.

Output format: \(x_1,\ y_1,\ z_1,\ x_2,\ y_2,\ z_2,\ \dots\ x_n,\ y_n,\ z_n\).

The particles are ordered according to the list of ids passed to the observable.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.ParticleVelocities

Bases: espressomd.observables.Observable

Calculates the particle velocities for particles with given ids.

Output format: \(v_{x1},\ v_{y1},\ v_{z1},\ v_{x2},\ v_{y2},\ v_{z2},\ \dots\ v_{xn},\ v_{yn},\ v_{zn}\).

The particles are ordered according to the list of ids passed to the observable.

Parameters

ids (array_like of int) – The ids of (existing) particles to take into account.

class espressomd.observables.StressTensor

Bases: espressomd.observables.Observable

Calculates the total stress tensor. See Stress Tensor)

espressomd.pair_criteria module

class espressomd.pair_criteria.BondCriterion

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_typeint

numeric type of the bond

class espressomd.pair_criteria.DistanceCriterion

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_offfloat

distance cut off for the criterion

class espressomd.pair_criteria.EnergyCriterion

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_offfloat

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

add_exclusion(self, _partner)

Excluding interaction with the given partner.

Parameters

_partner (int) – partner

add_verified_bond(self, bond)

Add a bond, the validity of which has already been verified.

See also

add_bond()

Delete an unverified bond held by the Particle.

bonds()

Particle property containing a list of all current bonds help 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.

bondslist/tuple of tuples/lists

a bond tuple is specified as a bond identifier associated with a particle (bond_ID, part_ID). A single particle may contain multiple such tuples.

See also

espressomd.particle_data.ParticleHandle.add_bond

Method to add bonds to a Particle

espressomd.particle_data.ParticleHandle.delete_bond

Method to remove bonds from a Particle

Bond ids have to be an integer >= 0.

check_bond_or_throw_exception(self, bond)

Checks the validity of the given bond:

• If the bondtype is given as an object or a numerical id

• If all partners are of type int

• If the number of partners satisfies the bond

• If the bond type used exists (is lower than n_bonded_ia)

• If the number of bond partners fits the bond type

Throws an exception if any of these are not met.

convert_vector_body_to_space(self, vec)

Converts the given vector from the particle’s body frame to the space frame

convert_vector_space_to_body(self, vec)

Converts the given vector from the space frame to the particle’s body frame

delete_all_bonds(self)

Delete all bonds from the particle.

See also

delete_bond()

Delete an unverified bond held by the particle.

bonds()

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

delete_bond(self, _bond)

Delete a single bond from the particle.

Parameters

_bond (bond to be deleted)

See also

bonds()

Particle property, a list of all current bonds.

Examples

>>> import espressomd
>>> from espressomd.interactions import HarmonicBond
>>>
>>> system = espressomd.System()

define a harmonic potential and add it to the system

>>> harm_bond = HarmonicBond(r_0=1, k=5)
>>> system.bonded_inter.add(harm_bond)

add two bonded particles to particle 0

>>> system.part.add(id=0, pos=(1, 0, 0))
>>> system.part.add(id=1, pos=(2, 0, 0))
>>> system.part.add(id=2, pos=(1, 1, 0))
>>> system.part[0].add_bond((harm_bond,1))
>>> system.part[0].add_bond((harm_bond,2))
>>>
>>> bonds = system.part[0].bonds
>>> print(bonds)
((HarmonicBond(0): {'r_0': 1.0, 'k': 5.0, 'r_cut': 0.0}, 1), (HarmonicBond(0): {'r_0': 1.0, 'k': 5.0, 'r_cut': 0.0}, 2))

delete the bond between particle 0 and particle 1

>>> system.part[0].delete_bond(bonds[0])
>>> print(system.part[0].bonds)
((HarmonicBond(0): {'r_0': 1.0, 'k': 5.0, 'r_cut': 0.0}, 2),)

delete_exclusion(self, _partner)

delete_verified_bond(self, bond)

Delete a single bond from the particle. The validity of which has already been verified.

Parameters

bond (tuple) – tuple where the first element is either a bond ID of a bond type, and the last element is the ID of the 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 : (3,) array_like of float

Note

This needs the feature DIPOLES.

dipm

The magnitude of the dipole moment.

dipm : float

Note

This needs the feature DIPOLES.

director

Director.

Note

Setting the director is not implemented. This needs the feature ROTATION.

exclusions

The exclusion list of particles where nonbonded interactions are ignored.

Note

This needs the feature EXCLUSIONS.

ext_force

An additional external force applied to the particle.

ext_force : (3,) array_like of float

Note

This needs the feature EXTERNAL_FORCES.

ext_torque

An additional external torque is applied to the particle.

ext_torque : (3,) array_like of float

Note

• This torque is specified in the laboratory frame!

• This needs features EXTERNAL_FORCES and ROTATION.

f

The instantaneous force acting on this particle.

f(3,) array_like of float

The current forces on the particle

Note

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

fix

Fixes the particle motion in the specified cartesian directions.

fix : (3,) array_like of int

Fixes the particle in space. By supplying a set of 3 integers as arguments it is possible to fix motion in x, y, or z coordinates independently. For example:

part[<INDEX>].fix = [0, 0, 1]

will fix motion for particle with index INDEX only in z.

Note

This needs the feature EXTERNAL_FORCES.

gamma

The body-fixed frictional coefficient used in the Langevin thermostat.

gamma : float or (3,) array_like of float

Note

This needs features 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 : float or (3,) array_like of float

Note

This needs features 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.

massfloat

The particle mass.

See also

espressomd.thermostat.Thermostat.set_langevin()

Setting the parameters of the Langevin thermostat

mol_id

The molecule id of the Particle.

mol_idint

The particle mol_id is used to differentiate between particles belonging to different molecules, e.g. when virtual sites are used, or object-in-fluid cells. The default mol_id for all particles is 0.

Note

The value of mol_id has to be an integer >= 0.

mu_E

Particle electrophoretic velocity.

mu_E : float

This effectively acts as a velocity offset between a lattice-Boltzmann fluid and the particle. Has only an effect if LB is turned on.

Note

This needs the feature LB_ELECTROHYDRODYNAMICS.

node

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

omega_body

The particle angular velocity in body frame.

omega_body : (3,) array_like of float

This property sets the angular momentum of this particle in the particles co-rotating frame (or body frame).

Note

This needs the feature ROTATION.

omega_lab

The particle angular velocity the lab frame.

omega_lab(3,) array_like of float

The particle’s angular velocity measured from the lab frame.

Note

This needs the feature ROTATION.

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

See also

omega_body

out_direction

OIF Outward direction

pos

The unwrapped (not folded into central box) particle position.

pos(3,) array_like of float

The particles’ absolute position.

pos_folded

The wrapped (folded into central box) position vector of a particle.

pos(3,) array_like of float

The particles’ position.

Note

Setting the folded position is ambiguous and is thus not possible, please use pos.

Examples

>>> import espressomd
>>>
>>> system = espressomd.System()
>>>
>>> system.box_l=[10,10,10]
>>> # add two bonded particles to particle 0
>>> system.part.add(id=0, pos=(5, 0, 0))
>>> system.part.add(id=1, pos=(10, 0, 0))
>>> system.part.add(id=2, pos=(25, 0, 0))
>>> for p in system.part:
>>>     print(p.pos)
[ 5.  0.  0.]
[ 10.   0.   0.]
[ 25.   0.   0.]
>>>
>>> for p in system.part:
>>>     print(p.pos_folded)
[5.0, 0.0, 0.0]
[0.0, 0.0, 0.0]
[5.0, 0.0, 0.0]

q

Particle charge.

q : float

Note

This needs the feature ELECTROSTATICS.

quat

Particle quaternion representation.

quat(4,) array_like of float

Sets the quaternion representation of the rotational position of this particle.

Note

This needs the feature ROTATION.

remove(self)

Delete the particle.

See also

espressomd.particle_data.ParticleList.add(), espressomd.particle_data.ParticleList.clear()

rinertia

The particle rotational inertia.

rinertia : (3,) array_like of float

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

Note

This needs the feature ROTATIONAL_INERTIA.

rotate(self, axis=None, angle=None)

Rotates the particle around the given axis

Parameters

• axis ((3,) array_like of float)

• angle (float)

rotation

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

The default is not to integrate any rotational degrees of freedom.

rotation : (3,) array_like of int

Note

This needs the feature ROTATION.

swimming

Set swimming parameters.

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

Swimming enables the particle to be self-propelled in the direction determined by its quaternion. For setting the quaternion of the particle see quat. The self-propulsion speed will relax to a constant velocity, that is specified by v_swim. Alternatively it is possible to achieve a constant velocity by imposing a constant force term f_swim that is balanced by friction of a (Langevin) thermostat. The way the velocity of the particle decays to the constant terminal velocity in either of these methods is completely determined by the friction coefficient. You may only set one of the possibilities v_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 non-lattice-Boltzmann thermostats. Note that there is no real difference between v_swim and f_swim since the latter may aways be chosen such that the same terminal velocity is achieved for a given friction coefficient.

Parameters

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

• v_swim (float) – Achieve a constant velocity by imposing a constant terminal velocity v_swim. This excludes the option f_swim.

• mode (str, {‘pusher’, ‘puller’}) – The LB flow field can be generated by a pushing or a pulling mechanism, leading to change in the sign of the dipolar flow field with respect to the direction of motion.

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

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

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

temp

Particle’s temperature in the Langevin thermostat.

temp: float

Note

This needs the feature LANGEVIN_PER_PARTICLE.

torque_lab

The particle torque in the lab frame.

torque_lab : (3,) array_like of float

This property defines the torque of this particle in the fixed frame (or laboratory frame).

Note

The orientation of the particle (quat) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.

type

The particle type for nonbonded interactions.

typeint

Nonbonded interactions act between different types of particles.

Note

The value of type has to be an integer >= 0.

update(self, P)

v

The particle velocity in the lab frame.

v(3,) array_like of float

The particles’ velocity

Note

The velocity remains variable and will be changed during integration.

virtual

Virtual flag.

Declares the particles as virtual (True) or non-virtual (False, default).

virtual : bool

Note

This needs the feature VIRTUAL_SITES

vs_auto_relate_to(self, _relto)

Setup this particle as virtual site relative to the particle with the given id.

vs_quat

Virtual site quaternion.

This quaternion describes the virtual particles orientation in the body fixed frame of the related real particle.

vs_quat : (4,) array_like of float

Note

This needs the feature VIRTUAL_SITES_RELATIVE.

vs_relative

Virtual sites relative parameters.

Allows for manual access to the attributes of virtual sites in the “relative” implementation. PID denotes the id of the particle to which this virtual site is related and distance the distance between non-virtual 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

Either a dictionary or a bunch of keyword args.

Returns

Return type

Returns an instance of espressomd.particle_data.ParticleHandle for each added particle.

See also

espressomd.particle_data.ParticleHandle.remove()

Examples

>>> import espressomd
>>>
>>> system = espressomd.System()
>>>
>>> # add two particles
>>> system.part.add(id=0, pos=(1, 0, 0))
>>> system.part.add(id=1, pos=(2, 0, 0))

Pos is mandatory, id can be omitted, in which case it is assigned automatically. Several particles can be added by passing one value per particle to each property:

system.part.add(pos=((1,2,3),(4,5,6)),q=(1,-1))

clear(self)

Removes all particles.

See also

add(), espressomd.particle_data.ParticleHandle.remove()

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 user-defined criterion

Parameters:

Either: a keyword arguments in which the keys are names of particle properties and the values are the values to filter for. E.g.,:

system.part.select(type=0, q=1)

Or: a function taking a ParticleHandle as argument and returning True if the particle is to be filtered for. E.g.,:

system.part.select(lambda p: p.pos[0] < 0.5)

Returns

An instance of ParticleSlice containing the selected particles

Return type

ParticleSlice

writevtk(self, fname, types=u'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/

class espressomd.particle_data.ParticleSlice

Bases: espressomd.particle_data._ParticleSliceImpl

Handles slice inputs e.g. part[0:2]. Sets values for selected slices or returns values as a single list.

property bond_site

OIF bond_site

property bonds

The bonds stored by this particle. Note that bonds are only stored by one partner. You need to define a bonded interaction.

bondslist/tuple of tuples/lists

a bond tuple is specified as a bond identifier associated with a particle (bond_ID, part_ID). A single particle may contain multiple such tuples.

See also

espressomd.particle_data.ParticleHandle.add_bond

Method to add bonds to a Particle

espressomd.particle_data.ParticleHandle.delete_bond

Method to remove bonds from a Particle

Bond ids have to be an integer >= 0.

property dip

The orientation of the dipole axis.

dip : (3,) array_like of float

Note

This needs the feature DIPOLES.

property dipm

The magnitude of the dipole moment.

dipm : float

Note

This needs the feature DIPOLES.

property director

Director.

Note

Setting the director is not implemented. This needs the feature ROTATION.

property exclusions

The exclusion list of particles where nonbonded interactions are ignored.

Note

This needs the feature EXCLUSIONS.

property ext_force

An additional external force applied to the particle.

ext_force : (3,) array_like of float

Note

This needs the feature EXTERNAL_FORCES.

property ext_torque

An additional external torque is applied to the particle.

ext_torque : (3,) array_like of float

Note

• This torque is specified in the laboratory frame!

• This needs features EXTERNAL_FORCES and ROTATION.

property f

The instantaneous force acting on this particle.

f(3,) array_like of float

The current forces on the particle

Note

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

property fix

Fixes the particle motion in the specified cartesian directions.

fix : (3,) array_like of int

Fixes the particle in space. By supplying a set of 3 integers as arguments it is possible to fix motion in x, y, or z coordinates independently. For example:

part[<INDEX>].fix = [0, 0, 1]

will fix motion for particle with index INDEX only in z.

Note

This needs the feature EXTERNAL_FORCES.

property gamma

The body-fixed frictional coefficient used in the Langevin thermostat.

gamma : float or (3,) array_like of float

Note

This needs features LANGEVIN_PER_PARTICLE and PARTICLE_ANISOTROPY.

See also

espressomd.thermostat.Thermostat.set_langevin()

Setting the parameters of the Langevin thermostat

property gamma_rot

The particle translational frictional coefficient used in the Langevin thermostat.

gamma_rot : float or (3,) array_like of float

Note

This needs features LANGEVIN_PER_PARTICLE, ROTATION and PARTICLE_ANISOTROPY.

property id

Integer particle id

property image_box

The image box the particles is in.

This is the number of times the particle position has been folded by the box length in each direction.

property mass

Particle mass.

massfloat

The particle mass.

See also

espressomd.thermostat.Thermostat.set_langevin()

Setting the parameters of the Langevin thermostat

property mol_id

The molecule id of the Particle.

mol_idint

The particle mol_id is used to differentiate between particles belonging to different molecules, e.g. when virtual sites are used, or object-in-fluid cells. The default mol_id for all particles is 0.

Note

The value of mol_id has to be an integer >= 0.

property mu_E

Particle electrophoretic velocity.

mu_E : float

This effectively acts as a velocity offset between a lattice-Boltzmann fluid and the particle. Has only an effect if LB is turned on.

Note

This needs the feature LB_ELECTROHYDRODYNAMICS.

property node

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

property omega_body

The particle angular velocity in body frame.

omega_body : (3,) array_like of float

This property sets the angular momentum of this particle in the particles co-rotating frame (or body frame).

Note

This needs the feature ROTATION.

property omega_lab

The particle angular velocity the lab frame.

omega_lab(3,) array_like of float

The particle’s angular velocity measured from the lab frame.

Note

This needs the feature ROTATION.

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

See also

omega_body

property out_direction

OIF Outward direction

property pos

The unwrapped (not folded into central box) particle position.

pos(3,) array_like of float

The particles’ absolute position.

property q

Particle charge.

q : float

Note

This needs the feature ELECTROSTATICS.

property quat

Particle quaternion representation.

quat(4,) array_like of float

Sets the quaternion representation of the rotational position of this particle.

Note

This needs the feature ROTATION.

property rinertia

The particle rotational inertia.

rinertia : (3,) array_like of float

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

Note

This needs the feature ROTATIONAL_INERTIA.

property rotation

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

The default is not to integrate any rotational degrees of freedom.

rotation : (3,) array_like of int

Note

This needs the feature ROTATION.

property swimming

Set swimming parameters.

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

Swimming enables the particle to be self-propelled in the direction determined by its quaternion. For setting the quaternion of the particle see quat. The self-propulsion speed will relax to a constant velocity, that is specified by v_swim. Alternatively it is possible to achieve a constant velocity by imposing a constant force term f_swim that is balanced by friction of a (Langevin) thermostat. The way the velocity of the particle decays to the constant terminal velocity in either of these methods is completely determined by the friction coefficient. You may only set one of the possibilities v_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 non-lattice-Boltzmann thermostats. Note that there is no real difference between v_swim and f_swim since the latter may aways be chosen such that the same terminal velocity is achieved for a given friction coefficient.

Parameters

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

• v_swim (float) – Achieve a constant velocity by imposing a constant terminal velocity v_swim. This excludes the option f_swim.

• mode (str, {‘pusher’, ‘puller’}) – The LB flow field can be generated by a pushing or a pulling mechanism, leading to change in the sign of the dipolar flow field with respect to the direction of motion.

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

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

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

property temp

Particle’s temperature in the Langevin thermostat.

temp: float

Note

This needs the feature LANGEVIN_PER_PARTICLE.

property torque_lab

The particle torque in the lab frame.

torque_lab : (3,) array_like of float

This property defines the torque of this particle in the fixed frame (or laboratory frame).

Note

The orientation of the particle (quat) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.

property type

The particle type for nonbonded interactions.

typeint

Nonbonded interactions act between different types of particles.

Note

The value of type has to be an integer >= 0.

property v

The particle velocity in the lab frame.

v(3,) array_like of float

The particles’ velocity

Note

The velocity remains variable and will be changed during integration.

property virtual

Virtual flag.

Declares the particles as virtual (True) or non-virtual (False, default).

virtual : bool

Note

This needs the feature VIRTUAL_SITES

property vs_quat

Virtual site quaternion.

This quaternion describes the virtual particles orientation in the body fixed frame of the related real particle.

vs_quat : (4,) array_like of float

Note

This needs the feature VIRTUAL_SITES_RELATIVE.

property vs_relative

Virtual sites relative parameters.

Allows for manual access to the attributes of virtual sites in the “relative” implementation. PID denotes the id of the particle to which this virtual site is related and distance the distance between non-virtual 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.positions(**kwargs)

Generates particle positions for polymer creation.

Parameters

• n_polymers (int, required) – Number of polymer chains

• beads_per_chain (int, required) – Number of monomers per chain

• bond_length (float, required) – distance between adjacent monomers in a chain

• seed (int, required) – Seed for the RNG used to generate the particle positions.

• bond_angle (float, optional) – If set, this parameter defines the angle between adjacent bonds withing a polymer.

• start_positions (array_like float.) – If set, this vector defines the start positions for the polymers, i.e., the position of each polymer’s first monomer bead. Here, a numpy array of shape (n_polymers, 3) is expected.

• min_distance (float, optional) – Minimum distance between all generated positions. Defaults to 0

• respect_constraints (bool, optional) – If True, the particle setup tries to obey previously defined constraints. Default value is False.

• max_tries (int, optional) – Maximal number of attempts to generate every monomer position, as well as maximal number of retries per polymer, if choosing suitable monomer positions fails. Default value is 1000. Depending on the total number of beads and constraints, this value needs to be adapted.

Returns

Three-dimensional numpy array, namely a list of polymers containing the coordinates of the respective monomers.

Return type

ndarray

espressomd.polymer.validate_params(_params, default)

espressomd.profiler module

espressomd.profiler.begin_section(name)

Start named section in profiler.

Parameters

name (str) – Name of the section

espressomd.profiler.end_section(name)

End named section in profiler.

Parameters

name (str) – Name of the section

espressomd.reaction_ensemble module

class espressomd.reaction_ensemble.ConstantpHEnsemble(*args, **kwargs)

Bases: espressomd.reaction_ensemble.ReactionAlgorithm

add_reaction(self, *args, **kwargs)

constant_pH

Sets the input pH for the constant pH ensemble method.

class espressomd.reaction_ensemble.ReactionAlgorithm

Bases: object

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

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

Parameters

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

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

• seed (int) – Initial counter value (or seed) of the Mersenne Twister RNG.

add_reaction(self, *args, **kwargs)

Sets up a reaction in the forward and backward direction.

Parameters

• gamma (float) – Equilibrium constant of the reaction, \(\gamma\) (see the User guide, section 6.6 for the definition and further details).

• reactant_types (list of int) – List of particle types of reactants in the reaction.

• reactant_coefficients (list of int) – List of stoichiometric coefficients of the reactants in the same order as the list of their types.

• product_types (list of int) – List of particle types of products in the reaction.

• product_coefficients (list of int) – List of stoichiometric coefficients of products of the reaction in the same order as the list of their types

• default_charges (dict) – A dictionary of default charges for types that occur in the provided reaction.

• check_for_electroneutrality (bool) – Check for electroneutrality of the given reaction if True.

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_acceptance_rate_reaction(self, reaction_id)

Returns the acceptance rate for the given reaction.

get_non_interacting_type(self)

Returns the type which is used for hiding particles.

get_status(self)

Returns the status of the reaction ensemble in a dictionary containing the used reactions, the used temperature and the used exclusion radius.

get_volume(self)

Get the volume to be used in the acceptance probability of the reaction ensemble.

get_wall_constraints_in_z_direction(self)

Returns the restrictions of the sampling area in z-direction.

reaction(self, reaction_steps=1)

Performs randomly selected reactions.

Parameters

reaction_steps (int, optional) – The number of reactions to be performed at once, defaults to 1.

set_cylindrical_constraint_in_z_direction(self, center_x, center_y, radius_of_cylinder)

Constrain the reaction moves within a cylinder defined by its axis passing through centres (\(x\) and \(y\)) and the radius. Requires setting the volume using set_volume().

Parameters

• center_x (float) – x coordinate of center of the cylinder.

• center_y (float) – y coordinate of center of the cylinder.

• radius_of_cylinder (float) – radius of the cylinder

set_non_interacting_type(self, non_interacting_type)

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

set_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 z-direction. Requires setting the volume using set_volume().

class espressomd.reaction_ensemble.ReactionEnsemble(*args, **kwargs)

Bases: espressomd.reaction_ensemble.ReactionAlgorithm

This class implements the Reaction Ensemble.

exception espressomd.reaction_ensemble.WangLandauHasConverged

Bases: Exception

class espressomd.reaction_ensemble.WangLandauReactionEnsemble(*args, **kwargs)

Bases: espressomd.reaction_ensemble.ReactionAlgorithm

This Class implements the Wang-Landau Reaction Ensemble.

add_collective_variable_degree_of_association(self, *args, **kwargs)

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

Parameters

• associated_type (int) – Particle type of the associated state of the reacting species.

• min (float) – Minimum value of the collective variable.

• max (float) – Maximum value of the collective variable.

• corresponding_acid_types (list of int) – List of the types of the version of the species.

add_collective_variable_potential_energy(self, *args, **kwargs)

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

Parameters

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

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

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 Wang-Landau terms in the acceptance probability. If there are multiple types, that need to be moved, make sure to move them in a random order to avoid artefacts. For the Wang-Landau algorithm in the case of energy reweighting you would also need to move the monomers of the polymer with special moves for the MC part. Those polymer configuration changing moves need to be implemented in the case of using Wang-Landau with energy reweighting and a polymer in the system. Polymer configuration changing moves had been implemented before but were removed from espresso.

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 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 Wang-Landau parameter.

Parameters

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

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

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

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 Wang-Landau reaction ensemble simulation where the acceptance probability includes the factor \(\exp(-\beta \Delta E_{pot})\). The minimal and maximal potential energies which occur in the system are needed for the energy reweighting simulations where the factor \(\exp(-\beta \Delta E_{pot})\) is not included in the acceptance probability in order to avoid choosing the wrong potential energy boundaries.

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 Wang-Landau 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 in the canonical ensemble for homogeneous systems, where the excess chemical potential is not depending on the location.

measure_excess_chemical_potential(self, reaction_id=0)

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

espressomd.scafacos module

Code shared by charge and dipole methods based on the SCAFACOS library.

class espressomd.scafacos.ScafacosConnector

Bases: espressomd.actors.Actor

Scafacos interface class shared by charge and dipole methods. Do not use directly.

default_params(self)

get_params(self)

required_keys(self)

set_params(self, params)

valid_keys(self)

validate_params(self)

espressomd.scafacos.available_methods()

Lists long range methods available in the Scafacos library.

espressomd.script_interface module

class espressomd.script_interface.PObjectId

Bases: object

Python interface to a core ObjectId object.

class espressomd.script_interface.PScriptInterface(name=None, policy=u'GLOBAL', oid=None, **kwargs)

Bases: object

Python interface to a core ScriptInterface object. The core ScriptInterface class is itself an interface for other core classes, such as constraints, shapes, observables, etc.

This class can be instantiated in two ways: (1) with the object id of an existing core ScriptInterface object, or (2) with parameters to construct a new ScriptInterface object in the core.

Parameters

• name (str) – Name of the core class to instantiate (method 1).

• **kwargs – Parameters for the core class constructor (method 1).

• oid (PObjectId) – Object id of an existing core object (method 2).

• policy (str, {‘GLOBAL’, ‘LOCAL’}) – Creation policy.

sip

Pointer to a ScriptInterface object in the core.

Type

shared_ptr

policy_

Creation policy.

Type

str

call_method(self, method, **kwargs)

Call a method of the core class.

Parameters

• method (Creation policy.) – Name of the core method.

• **kwargs – Arguments for the method.

get_parameter(self, name)

get_params(self)

id(self)

Return the core class object id (PObjectId).

name(self)

Return name of the core class.

set_params(self, **kwargs)

set_sip_via_oid(self, PObjectId id)

Set the shared_ptr to an existing core ScriptInterface object via its object id.

class espressomd.script_interface.ScriptInterfaceHelper

Bases: espressomd.script_interface.PScriptInterface

Base class from which to derive most interfaces to core ScriptInterface classes.

define_bound_methods(self)

generate_caller(self, method_name)

class espressomd.script_interface.ScriptObjectRegistry

Bases: espressomd.script_interface.ScriptInterfaceHelper

Base class for container-like classes such as Constraints and LBBoundaries. Derived classes must implement an add() method which adds a single item to the container.

The core class should derive from ScriptObjectRegistry or provide "get_elements" and "size" as callable methods.

espressomd.script_interface.init()

espressomd.script_interface.script_interface_register(c)

Decorator used to register script interface classes. This will store a name-to-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

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

A cylinder shape.

center

Coordinates of the center of the cylinder.

Type

(3,) array_like of float

axis

Axis of the cylinder.

Type

(3,) array_like of float

radius

Radius of the cylinder.

Type

float

length

Length of the cylinder.

Type

float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

open

cylinder is open or has caps.

Type

bool

class espressomd.shapes.Ellipsoid

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

An ellipsoid.

For now only ellipsoids of revolution are supported. The symmetry axis is aligned parallel to the x-direction.

center

Coordinates of the center of the ellipsoid.

Type

(3,) array_like of float

a

Semiaxis along the axis of rotational symmetry.

Type

float

b

Equatorial semiaxes.

Type

float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

class espressomd.shapes.HollowCone

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

A hollow cone shape.

inner_radius

Inner radius of the cone.

Type

float

outer_radius

Outer radius of the cone.

Type

float

opening_angle

Opening angle of the cone (in rad).

Type

float

axis

Axis of symmetry, prescribes orientation of the cone.

Type

(3,) array_like of float

center

Position of the cone.

Type

(3,) array_like of float

width

Wall thickness of the cone.

Type

float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

class espressomd.shapes.Rhomboid

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

An parallelepiped.

a

First base vector.

Type

(3,) array_like of float

b

Second base vector.

Type

(3,) array_like of float

c

Third base vector.

Type

(3,) array_like of float

corner

Lower left corner of the rhomboid.

Type

(3,) array_like of float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

class espressomd.shapes.Shape

Bases: object

class espressomd.shapes.SimplePore

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

Two parallel infinite planes, and a cylindrical channel connecting them. The cylinder and the planes are connected by torus segments with an adjustable radius.

radius

The radius of the pore.

Type

float

length

The distance between the planes.

Type

float

smoothing_radius

Radius of the torus segments

Type

float

axis

Axis of the cylinder and normal of the planes

Type

(3,) array_like of float

center

Position of the center of the cylinder.

Type

(3,) array_like of float

class espressomd.shapes.Slitpore

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

channel_width

Type

float

lower_smoothing_radius

Type

float

pore_length

Type

float

pore_mouth

Type

float

pore_width

Type

float

upper_smoothing_radius

Type

float

dividing_plane

Type

float

class espressomd.shapes.Sphere

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

A sphere.

center

Center of the sphere

Type

(3,) array_like of float

radius

Radius of the sphere.

Type

float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

class espressomd.shapes.SpheroCylinder

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

A cylinder with hemispheres as caps.

center

Coordinates of the center of the cylinder.

Type

(3,) array_like of float

axis

Axis of the cylinder.

Type

(3,) array_like of float

radius

Radius of the cylinder.

Type

float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

length

Length of the cylinder (not including the caps).

Type

float

class espressomd.shapes.Stomatocyte

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

inner_radius

Inner radius of the stomatocyte.

Type

float

outer_radius

Outer radius of the stomatocyte.

Type

float

axis

Symmetry axis, prescribing the orientation of the stomatocyte.

Type

(3,) array_like of float

center

Position of the stomatocyte.

Type

(3,) array_like of float

layer_width

Scaling parameter.

Type

float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

class espressomd.shapes.Torus

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

A torus shape.

center

Coordinates of the center of the torus.

Type

(3,) array_like of float

normal

Normal axis of the torus.

Type

(3,) array_like of float

radius

Radius of the torus.

Type

float

tube_radius

Radius of the tube.

Type

float

direction

Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.

Type

int

class espressomd.shapes.Wall

Bases: espressomd.shapes.Shape, espressomd.script_interface.ScriptInterfaceHelper

An infinite plane.

dist

Distance from the origin.

Type

float

normal

Normal vector of the plane (needs not to be length 1).

Type

(3,) array_like of int

espressomd.system module

class espressomd.system.System(**kwargs)

Bases: object

The espresso system class.

Note

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

globals

Type

espressomd.globals.Globals

actors

Type

espressomd.actors.Actors

analysis

Type

espressomd.analyze.Analysis

auto_update_accumulators

Type

espressomd.accumulators.AutoUpdateAccumulators

bonded_inter

Type

espressomd.interactions.BondedInteractions

cell_system

Type

espressomd.cellsystem.CellSystem

collision_detection

Type

espressomd.collision_detection.CollisionDetection

comfixed

Type

espressomd.comfixed.ComFixed

constraints

Type

espressomd.constraints.Constraints

cuda_init_handle

Type

espressomd.cuda_init.CudaInitHandle

galilei

Type

espressomd.galilei.GalileiTransform

integrator

Type

espressomd.integrate.Integrator

lbboundaries

Type

espressomd.lbboundaries.LBBoundaries

ekboundaries

Type

espressomd.ekboundaries.EKBoundaries

minimize_energy

Type

espressomd.minimize_energy.MinimizeEnergy

non_bonded_inter

Type

espressomd.interactions.NonBondedInteractions

part

Type

espressomd.particle_data.ParticleList

thermostat

Type

espressomd.thermostat.Thermostat

actors

object

Type

actors

analysis

object

Type

analysis

auto_exclusions(self, distance)

Automatically adds exclusions between particles that are bonded.

This only considers pair bonds.

Parameters

distance (int) – Bond distance upto which the exclusions should be added.

auto_update_accumulators

object

Type

auto_update_accumulators

bonded_inter

object

Type

bonded_inter

box_l

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

cell_system

object

Type

cell_system

change_volume_and_rescale_particles(self, d_new, dir=u'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.

check_valid_type(self, current_type)

collision_detection

object

Type

collision_detection

comfixed

object

Type

comfixed

constraints

object

Type

constraints

cuda_init_handle

object

Type

cuda_init_handle

distance(self, p1, p2)

Return the scalar distance between the particles, respecting periodic boundaries.

distance_vec(self, p1, p2)

Return the distance vector between the particles, respecting periodic boundaries.

ekboundaries

object

Type

ekboundaries

force_cap

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

galilei

object

Type

galilei

globals

object

Type

globals

integ_switch

integrator

object

Type

integrator

lbboundaries

object

Type

lbboundaries

max_cut_bonded

max_cut_nonbonded

max_oif_objects

Maximum number of objects as per the object_in_fluid method.

min_global_cut

minimize_energy

object

Type

minimize_energy

non_bonded_inter

object

Type

non_bonded_inter

number_of_particles(self, type=None)

Parameters

current_type (int (type)) – Particle type to count the number for.

Returns

The number of particles which have the given type.

Return type

int

part

object

Type

part

periodicity

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

random_number_generator_state

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

rotate_system(self, **kwargs)

Rotate the particles in the system about the center of mass.

If ROTATION is activated, the internal rotation degrees of freedom are rotated accordingly.

Parameters

• phi (float) – Angle between the z-axis and the rotation axis.

• theta (float) – Rotation of the axis around the y-axis.

• alpha (float) – How much to rotate

seed

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

set_random_state_PRNG(self)

Sets the state of the pseudo random number generator using real random numbers.

setup_type_map(self, type_list=None)

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

thermostat

object

Type

thermostat

time

Set the time in the simulation

time_step

Sets the time step for the integrator.

timings

virtual_sites

volume(self)

Return box volume of the cuboid box.

espressomd.thermostat module

espressomd.thermostat.AssertThermostatType(*allowedthermostats)

Assert that only a certain 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, seed=None)

Sets the DPD thermostat with required parameters ‘kT’. This also activates the DPD interactions.

Parameters

• kT (float) – Thermal energy of the heat bath.

• seed (int) – Initial counter value (or seed) of the philox RNG. Required on first activation of the DPD thermostat. Must be positive.

set_langevin(self, kT=None, gamma=None, gamma_rotation=None, act_on_virtual=False, seed=None)

Sets the Langevin thermostat.

Parameters

• kT (float) – Thermal energy of the simulated heat bath.

• gamma (float) – Contains the friction coefficient of the bath. If the 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 floats if PARTICLE_ANISOTROPY is also compiled in.

• act_on_virtual (bool, optional) – If True the thermostat will act on virtual sites, default is False.

• seed (int) – Initial counter value (or seed) of the philox RNG. Required on first activation of the Langevin thermostat. Must be positive.

set_lb(self, seed=None, act_on_virtual=True, LB_fluid=None, gamma=0.0)

Sets the LB thermostat.

This thermostat requires the feature LBFluid or LBFluidGPU.

Parameters

• LB_fluid (LBFluid or LBFluidGPU)

• seed (int) – Seed for the random number generator, required if kT > 0. Must be positive.

• act_on_virtual (bool, optional) – If True the thermostat will act on virtual sites (default).

• gamma (float) – Frictional coupling constant for the MD particle coupling.

set_npt(self, kT=None, gamma0=None, gammav=None)

Sets the NPT thermostat.

Parameters

• kT (float) – Thermal energy of the heat bath

• gamma0 (float) – Friction coefficient of the bath

• gammav (float) – Artificial friction coefficient for the volume fluctuations. Mass of the artificial piston.

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 non-writable numpy.ndarray with a special error message upon usage of __setitem__ or in-place operators. Cast return in __get__ of array properties to array_locked to prevent these operations.

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

espressomd.utils.check_type_or_throw_except(x, n, t, msg)

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

espressomd.utils.handle_errors(msg)

Gathers runtime errors.

Parameters

msg (str) – Error message that is to be raised.

espressomd.utils.is_valid_type(value, t)

Extended checks for numpy int and float types.

espressomd.utils.nesting_level(obj)

Returns the maximal nesting level of an object.

espressomd.utils.requires_experimental_features(reason)

Class decorator which makes instantiation conditional on EXPERIMENTAL_FEATURES being defined in myconfig.hpp.

espressomd.utils.to_char_pointer(s)

Returns a char pointer which contains the information of the provided python string.

Parameters

s (str)

espressomd.utils.to_str(s)

Returns a python string.

Parameters

s (char*)

espressomd.version module

espressomd.version.friendly()

Dot version of the version.

espressomd.version.git_branch()

Git branch of the build if known, otherwise empty.

espressomd.version.git_commit()

Git commit of the build if known, otherwise empty.

espressomd.version.git_state()

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

espressomd.version.major()

Prints the major version of Espresso.

espressomd.version.minor()

Prints the minor version of Espresso.

espressomd.virtual_sites module

class espressomd.virtual_sites.ActiveVirtualSitesHandle

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

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

Bases: espressomd.script_interface.ScriptInterfaceHelper

Virtual sites implementation which does nothing (default)

class espressomd.virtual_sites.VirtualSitesRelative

Bases: espressomd.script_interface.ScriptInterfaceHelper

Virtual sites implementation placing virtual sites relative to other particles. See Rigid arrangements of particles for details.

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

have_velocity

Determines whether the velocity of the virtual sites is calculated. This carries a performance cost.

Type

bool

espressomd.visualization module

class espressomd.visualization.mayaviLive(system, particle_sizes=u'auto')

Bases: object

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

Parameters

• system (espressomd.system.System)

• particle_sizes (function, list, or dict (optional)) – object which maps particle types to radii

processGuiEvents(self)

Process GUI events, e.g. mouse clicks, in the Mayavi window.

Call this function as often as you can to get a smooth GUI experience.

register_callback(self, cb, interval=1000)

run(self, integ_steps=1)

Convenience method with a simple integration thread.

start(self)

Start the GUI event loop.

This function blocks until the Mayavi window is closed. So you should only use it if your Espresso simulation’s integrate loop is running in a secondary thread.

update(self)

Pull the latest particle information from Espresso.

This is the only function that should be called from the computation thread. It does not call any Mayavi functions unless it is being called from the main (GUI) thread.

class espressomd.visualization.openGLLive

Bases: object

This class provides live visualization using pyOpenGL. Use the update method to push your current simulation state after integrating. Modify the appearance with a list of keywords. Timed callbacks can be registered via the register_callback() method and keyboard callbacks via keyboardManager.register_button().

Parameters

• system (espressomd.system.System)

• window_size ((2,) array_like of int, optional) – Size of the visualizer window in pixels.

• name (str, optional) – The name of the visualizer window.

• background_color ((3,) array_like of int, optional) – RGB of the background.

• periodic_images ((3,) array_like of int, optional) – Periodic repetitions on both sides of the box in xyz-direction.

• draw_box (bool, optional) – Draw wireframe boundaries.

• draw_axis (bool, optional) – Draw xyz system axes.

• draw_nodes (bool, optional) – Draw node boxes.

• draw_cells (bool, optional) – Draw cell boxes.

• quality_particles (int, optional) – The number of subdivisions for particle spheres.

• quality_bonds (int, optional) – The number of subdivisions for cylindrical bonds.

• quality_arrows (int, optional) – The number of subdivisions for external force arrows.

• quality_constraints (int, optional) – The number of subdivisions for primitive constraints.

• close_cut_distance (float, optional) – The distance from the viewer to the near clipping plane.

• far_cut_distance (float, optional) – The distance from the viewer to the far clipping plane.

• camera_position (str or (3,) array_like of float, optional) – Initial camera position. Use 'auto' (default) for shifted position in z-direction.

• camera_target (str or (3,) array_like of float, optional) – Initial camera target. Use 'auto' (default) to look towards the system center.

• camera_right ((3,) array_like of float, optional) – Camera right vector in system coordinates. Default is [1, 0, 0]

• particle_sizes (str or array_like float or callable, optional) –

  • 'auto' (default): The Lennard-Jones sigma value of the self-interaction is used for the particle diameter.

  • callable: A lambda function with one argument. Internally, the numerical particle type is passed to the lambda function to determine the particle radius.

  • list: A list of particle radii, indexed by the particle type.

• particle_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 ((2,) array_like of float, optional) – Two colors for min/max charged particles.

• draw_constraints (bool, optional) – Enables constraint visualization. For simple constraints (planes, spheres and cylinders), OpenGL primitives are used. Otherwise, visualization by rasterization is used.

• rasterize_pointsize (float, optional) – Point size for the rasterization dots.

• rasterize_resolution (float, optional) – Accuracy of the rasterization.

• quality_constraints (int, optional) – The number of subdivisions for primitive constraints.

• constraint_type_colors (array_like float, optional) – Colors of the constraints by type.

• constraint_type_materials (array_like str, optional) – Materials of the constraints by type.

• draw_bonds (bool, optional) – Enables bond visualization.

• bond_type_radius (array_like float, optional) – Radii of bonds by type.

• bond_type_colors (array_like float, optional) – Color of bonds by type.

• bond_type_materials (array_like float, optional) – Materials of bonds by type.

• ext_force_arrows (bool, optional) – Enables external force visualization.

• ext_force_arrows_type_scale (array_like float, optional) – List of scale factors of external force arrows for different particle types.

• ext_force_arrows_type_colors (array_like float, optional) – Colors of ext_force arrows for different particle types.

• ext_force_arrows_type_materials (array_like float, optional) – Materials of ext_force arrows for different particle types.

• ext_force_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• force_arrows (bool, optional) – Enables particle force visualization.

• force_arrows_type_scale (array_like float, optional) – List of scale factors of particle force arrows for different particle types.

• force_arrows_type_colors (array_like float, optional) – Colors of particle force arrows for different particle types.

• force_arrows_type_materials (array_like float, optional) – Materials of particle force arrows for different particle types.

• force_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• velocity_arrows (bool, optional) – Enables particle velocity visualization.

• velocity_arrows_type_scale (array_like float, optional) – List of scale factors of particle velocity arrows for different particle types.

• velocity_arrows_type_colors (array_like float, optional) – Colors of particle velocity arrows for different particle types.

• velocity_arrows_type_materials (array_like float, optional) – Materials of particle velocity arrows for different particle types.

• velocity_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• director_arrows (bool, optional) – Enables particle director visualization.

• director_arrows_type_scale (float, optional) – Scale factor of particle director arrows for different particle types.

• director_arrows_type_colors (array_like float, optional) – Colors of particle director arrows for different particle types.

• director_arrows_type_materials (array_like float, optional) – Materials of particle director arrows for different particle types.

• director_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• drag_enabled (bool, optional) – Enables mouse-controlled 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 ((3,) array_like of float, optional) – If auto (default) is used, the light is placed dynamically in the particle barycenter of the system. Otherwise, a fixed coordinate can be set.

• light_colors (array_like float, optional) – Three lists to specify ambient, diffuse and specular light colors.

• light_brightness (float, optional) – Brightness (inverse constant attenuation) of the light.

• light_size (float, optional) – Size (inverse linear attenuation) of the light. If auto (default) is used, the light size will be set to a reasonable value according to the box size at start.

• spotlight_enabled (bool, optional) – If set to True (default), it enables a spotlight on the camera position pointing in look direction.

• spotlight_colors (array_like float, optional) – Three lists to specify ambient, diffuse and specular spotlight colors.

• spotlight_angle (float, optional) – The spread angle of the spotlight in degrees (from 0 to 90).

• spotlight_brightness (float, optional) – Brightness (inverse constant attenuation) of the spotlight.

• spotlight_focus (float, optional) – Focus (spot exponent) for the spotlight from 0 (uniform) to 128.

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

register_callback(self, cb, interval=1000)

Register timed callbacks.

run(self, integ_steps=1)

Convenience method with a simple integration thread.

screenshot(self, path)

Renders the current state into an image file at path with dimensions of specs['window_size'] in PNG format.

start(self)

The blocking start method.

update(self)

Update method to be called after integration. Changes of espresso system can only happen here.

update_system_info(self)

espressomd.visualization_mayavi module

class espressomd.visualization_mayavi.mayaviLive(system, particle_sizes=u'auto')

Bases: object

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

Parameters

• system (espressomd.system.System)

• particle_sizes (function, list, or dict (optional)) – object which maps particle types to radii

processGuiEvents(self)

Process GUI events, e.g. mouse clicks, in the Mayavi window.

Call this function as often as you can to get a smooth GUI experience.

register_callback(self, cb, interval=1000)

run(self, integ_steps=1)

Convenience method with a simple integration thread.

start(self)

Start the GUI event loop.

This function blocks until the Mayavi window is closed. So you should only use it if your Espresso simulation’s integrate loop is running in a secondary thread.

update(self)

Pull the latest particle information from Espresso.

This is the only function that should be called from the computation thread. It does not call any Mayavi functions unless it is being called from the main (GUI) thread.

espressomd.visualization_opengl module

class espressomd.visualization_opengl.Camera

Bases: object

get_camera_rotation_matrix(self, target_vec, up_vec)

move_backward(self)

move_down(self)

move_forward(self)

move_left(self)

move_right(self)

move_up(self)

normalize(self, vec)

normalized(self, vec)

rotate_camera(self, mousePos, mousePosOld, mouseButtonState)

rotate_system_XL(self)

rotate_system_XR(self)

rotate_system_YL(self)

rotate_system_YR(self)

rotate_system_ZL(self)

rotate_system_ZR(self)

rotate_system_x(self, da)

rotate_system_y(self, da)

rotate_system_z(self, da)

rotate_vector(self, vec, ang, axe)

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

update_modelview(self)

class espressomd.visualization_opengl.KeyboardButtonEvent

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.

callback_on_button(self, be, b)

handle_input(self)

keyboard_down(self, button)

keyboard_up(self, button)

register_button(self, buttonEvent)

Register keyboard input callbacks.

class espressomd.visualization_opengl.MouseButtonEvent

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_button(self, mouseEvent)

Register mouse input callbacks.

class espressomd.visualization_opengl.Quaternion

Bases: object

conjugated(self)

mult_q(self, q)

mult_v(self, v)

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

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

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

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

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

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

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

espressomd.visualization_opengl.draw_slitpore(channel_width, lower_smoothing_radius, upper_smoothing_radius, pore_length, pore_mouth, pore_width, 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

Bases: object

This class provides live visualization using pyOpenGL. Use the update method to push your current simulation state after integrating. Modify the appearance with a list of keywords. Timed callbacks can be registered via the register_callback() method and keyboard callbacks via keyboardManager.register_button().

Parameters

• system (espressomd.system.System)

• window_size ((2,) array_like of int, optional) – Size of the visualizer window in pixels.

• name (str, optional) – The name of the visualizer window.

• background_color ((3,) array_like of int, optional) – RGB of the background.

• periodic_images ((3,) array_like of int, optional) – Periodic repetitions on both sides of the box in xyz-direction.

• draw_box (bool, optional) – Draw wireframe boundaries.

• draw_axis (bool, optional) – Draw xyz system axes.

• draw_nodes (bool, optional) – Draw node boxes.

• draw_cells (bool, optional) – Draw cell boxes.

• quality_particles (int, optional) – The number of subdivisions for particle spheres.

• quality_bonds (int, optional) – The number of subdivisions for cylindrical bonds.

• quality_arrows (int, optional) – The number of subdivisions for external force arrows.

• quality_constraints (int, optional) – The number of subdivisions for primitive constraints.

• close_cut_distance (float, optional) – The distance from the viewer to the near clipping plane.

• far_cut_distance (float, optional) – The distance from the viewer to the far clipping plane.

• camera_position (str or (3,) array_like of float, optional) – Initial camera position. Use 'auto' (default) for shifted position in z-direction.

• camera_target (str or (3,) array_like of float, optional) – Initial camera target. Use 'auto' (default) to look towards the system center.

• camera_right ((3,) array_like of float, optional) – Camera right vector in system coordinates. Default is [1, 0, 0]

• particle_sizes (str or array_like float or callable, optional) –

  • 'auto' (default): The Lennard-Jones sigma value of the self-interaction is used for the particle diameter.

  • callable: A lambda function with one argument. Internally, the numerical particle type is passed to the lambda function to determine the particle radius.

  • list: A list of particle radii, indexed by the particle type.

• particle_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 ((2,) array_like of float, optional) – Two colors for min/max charged particles.

• draw_constraints (bool, optional) – Enables constraint visualization. For simple constraints (planes, spheres and cylinders), OpenGL primitives are used. Otherwise, visualization by rasterization is used.

• rasterize_pointsize (float, optional) – Point size for the rasterization dots.

• rasterize_resolution (float, optional) – Accuracy of the rasterization.

• quality_constraints (int, optional) – The number of subdivisions for primitive constraints.

• constraint_type_colors (array_like float, optional) – Colors of the constraints by type.

• constraint_type_materials (array_like str, optional) – Materials of the constraints by type.

• draw_bonds (bool, optional) – Enables bond visualization.

• bond_type_radius (array_like float, optional) – Radii of bonds by type.

• bond_type_colors (array_like float, optional) – Color of bonds by type.

• bond_type_materials (array_like float, optional) – Materials of bonds by type.

• ext_force_arrows (bool, optional) – Enables external force visualization.

• ext_force_arrows_type_scale (array_like float, optional) – List of scale factors of external force arrows for different particle types.

• ext_force_arrows_type_colors (array_like float, optional) – Colors of ext_force arrows for different particle types.

• ext_force_arrows_type_materials (array_like float, optional) – Materials of ext_force arrows for different particle types.

• ext_force_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• force_arrows (bool, optional) – Enables particle force visualization.

• force_arrows_type_scale (array_like float, optional) – List of scale factors of particle force arrows for different particle types.

• force_arrows_type_colors (array_like float, optional) – Colors of particle force arrows for different particle types.

• force_arrows_type_materials (array_like float, optional) – Materials of particle force arrows for different particle types.

• force_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• velocity_arrows (bool, optional) – Enables particle velocity visualization.

• velocity_arrows_type_scale (array_like float, optional) – List of scale factors of particle velocity arrows for different particle types.

• velocity_arrows_type_colors (array_like float, optional) – Colors of particle velocity arrows for different particle types.

• velocity_arrows_type_materials (array_like float, optional) – Materials of particle velocity arrows for different particle types.

• velocity_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• director_arrows (bool, optional) – Enables particle director visualization.

• director_arrows_type_scale (float, optional) – Scale factor of particle director arrows for different particle types.

• director_arrows_type_colors (array_like float, optional) – Colors of particle director arrows for different particle types.

• director_arrows_type_materials (array_like float, optional) – Materials of particle director arrows for different particle types.

• director_arrows_type_radii (array_like float, optional) – List of arrow radii for different particle types.

• drag_enabled (bool, optional) – Enables mouse-controlled 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 ((3,) array_like of float, optional) – If auto (default) is used, the light is placed dynamically in the particle barycenter of the system. Otherwise, a fixed coordinate can be set.

• light_colors (array_like float, optional) – Three lists to specify ambient, diffuse and specular light colors.

• light_brightness (float, optional) – Brightness (inverse constant attenuation) of the light.

• light_size (float, optional) – Size (inverse linear attenuation) of the light. If auto (default) is used, the light size will be set to a reasonable value according to the box size at start.

• spotlight_enabled (bool, optional) – If set to True (default), it enables a spotlight on the camera position pointing in look direction.

• spotlight_colors (array_like float, optional) – Three lists to specify ambient, diffuse and specular spotlight colors.

• spotlight_angle (float, optional) – The spread angle of the spotlight in degrees (from 0 to 90).

• spotlight_brightness (float, optional) – Brightness (inverse constant attenuation) of the spotlight.

• spotlight_focus (float, optional) – Focus (spot exponent) for the spotlight from 0 (uniform) to 128.

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

register_callback(self, cb, interval=1000)

Register timed callbacks.

run(self, integ_steps=1)

Convenience method with a simple integration thread.

screenshot(self, path)

Renders the current state into an image file at path with dimensions of specs['window_size'] in PNG format.

start(self)

The blocking start method.

update(self)

Update method to be called after integration. Changes of espresso system can only happen here.

update_system_info(self)

espressomd.visualization_opengl.rotation_helper(d)

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

Module contents

exception espressomd.FeaturesError(missing_features_list)

Bases: Exception

espressomd.assert_features(*args)

Raises an exception when a list of features is not a subset of the compiled-in features

espressomd.has_features(*args)

Tests whether a list of features is a subset of the compiled-in features

espressomd.missing_features(*args)

Returns a list of the missing features in the argument