espressomd package¶
Subpackages¶
Submodules¶
espressomd.accumulators module¶
- class espressomd.accumulators.AutoUpdateAccumulators(*args, **kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptObjectList
Class for handling the auto-update of accumulators used by
espressomd.system.System
.
- class espressomd.accumulators.Correlator(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Calculates the correlation of two observables \(A\) and \(B\), or of one observable against itself (i.e. \(B = A\)). The correlation can be compressed using the multiple tau correlation algorithm.
The operation that is performed on \(A(t)\) and \(B(t+\tau)\) to obtain \(C(\tau)\) depends on the
corr_operation
argument:"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\) isespressomd.observables.ParticlePositions
, it produces the mean square displacement (for each component separately)."tensor_product"
: Tensor product of \(A\) and \(B\), i.e., \(C_{i \cdot l_B + j} = A_i B_j\) with \(l_B\) the length of \(B\)."fcs_acf"
: Fluorescence Correlation Spectroscopy (FCS) autocorrelation function, i.e.,\[G_i(\tau) = \frac{1}{N} \left< \exp \left( - \frac{\Delta x_i^2(\tau)}{w_x^2} - \frac{\Delta y_i^2(\tau)}{w_y^2} - \frac{\Delta z_i^2(\tau)}{w_z^2} \right) \right>\]where \(N\) is the average number of fluorophores in the illumination area,
\[\Delta x_i^2(\tau) = \left( x_i(0) - x_i(\tau) \right)^2\]is the square displacement of particle \(i\) in the \(x\) direction, and \(w_x\) is the beam waist of the intensity profile of the exciting laser beam,
\[W(x,y,z) = I_0 \exp \left( - \frac{2x^2}{w_x^2} - \frac{2y^2}{w_y^2} - \frac{2z^2}{w_z^2} \right).\]The values of \(w_x\), \(w_y\), and \(w_z\) are passed to the correlator as
args
. The correlator calculates\[C_i(\tau) = \exp \left( - \frac{\Delta x_i^2(\tau)}{w_x^2} - \frac{\Delta y_i^2(\tau)}{w_y^2} - \frac{\Delta z_i^2(\tau)}{w_z^2} \right)\]Per each 3 dimensions of the observable, one dimension of the correlation output is produced. If
"fcs_acf"
is used with other observables thanespressomd.observables.ParticlePositions
, the physical meaning of the result is unclear.The above equations are a generalization of the formula presented by Höfling et al. [Höfling et al., 2011]. For more information, see references therein.
- Parameters
obs1 (
espressomd.observables.Observable
) – The observable \(A\) to be correlated with \(B\) (obs2
). Ifobs2
is omitted, autocorrelation ofobs1
is calculated by default.obs2 (
espressomd.observables.Observable
, optional) – The observable \(B\) to be correlated with \(A\) (obs1
).corr_operation (
str
) – The operation that is performed on \(A(t)\) and \(B(t+\tau)\).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, choosingtau_max
of more than100 * dt
will result in a huge computational overhead. In a multiple tau correlator with reasonable parameters,tau_max
can span the entire simulation without too much additional cpu time.tau_lin (
int
) – The number of data-points for which the results are linearly spaced intau
. This is a parameter of the multiple tau correlator. If you want to use it, make sure that you know how it works.tau_lin
must be divisible by 2. By settingtau_lin
such thattau_max >= dt * delta_N * tau_lin
, the multiple tau correlator is used, otherwise the trivial linear correlator is used. By settingtau_lin = 1
, the value will be overridden bytau_lin = ceil(tau_max / (dt * delta_N))
, which will result in either the multiple or linear tau correlator. In many cases,tau_lin=16
is a good choice but this may strongly depend on the observables you are correlating. For more information, we recommend to read ref. [Ramirez et al., 2010] or to perform your own tests.compress1 (
str
) – These functions are used to compress the data when going to the next level of the multiple tau correlator. This is done by producing one value out of two. The following compression functions are available:"discard2"
: (default value) discard the second value from the time series, use the first value as the result"discard1"
: discard the first value from the time series, use the second value as the result"linear"
: make a linear combination (average) of the two values
If only
compress1
is specified, then the same compression function is used for both observables. If bothcompress1
andcompress2
are specified, thencompress1
is used forobs1
andcompress2
forobs2
.Both
discard1
anddiscard2
are safe for all observables but produce poor statistics in the tail. For some observables,"linear"
compression can be used which makes an average of two neighboring values but produces systematic errors. Depending on the observable, the systematic error using the"linear"
compression can be anything between harmless and disastrous. For more information, we recommend to read ref. [Ramirez et al., 2010] or to perform your own tests.compress2 (
str
, optional) – Seecompress1
.args (
float
of length 3) – Three floats which are passed as arguments to the correlation function. Currently it is only used by"fcs_acf"
, which will square these values in the core; if you later decide to update these weights withobs.args = [...]
, you’ll have to provide already squared values! Other correlation operations will ignore these values.
- class espressomd.accumulators.MeanVarianceCalculator(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Accumulates results from observables.
- Parameters
delta_N (
int
) – Number of timesteps between subsequent samples for the auto update mechanism.
- update()¶
Update the accumulator (get the current values from the observable).
- mean()[source]¶
Returns the samples mean values of the respective observable with which the accumulator was initialized.
- class espressomd.accumulators.TimeSeries(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Records results from observables.
- Parameters
delta_N (
int
) – Number of timesteps between subsequent samples for the auto update mechanism.
- update()¶
Update the accumulator (get the current values from the observable).
- clear()¶
Clear the data
espressomd.actors module¶
espressomd.analyze module¶
- class espressomd.analyze.Analysis(system)¶
Bases:
object
- angular_momentum(self, p_type=None)¶
Calculates the system’s angular momentum with respect to the origin.
Note that virtual sites are not included, as they do not have a meaningful mass.
- Parameters
p_type (
int
) – Particletype
for which to calculate the center of mass.- Returns
The center of mass of the system.
- Return type
(3,)
ndarray
offloat
- calc_re(self, chain_start=None, number_of_chains=None, chain_length=None)¶
Calculate 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 number
chain_start
and are consecutively numbered, the last particle in that topology having id numberchain_start + number_of_chains * chain_length - 1
.- Parameters
chain_start (
int
) – The id of the first monomer of the first chain.number_of_chains (
int
) – Number of chains contained in the range.chain_length (
int
) – The length of every chain.
- Returns
Where [0] is the mean 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)¶
Calculate the mean radius of gyration of chains and its standard deviation, as well as the mean square radius of gyration of chains and its standard deviation.
This requires that a set of chains of equal length which start with the particle number
chain_start
and are consecutively numbered, the last particle in that topology having id numberchain_start + number_of_chains * chain_length - 1
.- Parameters
chain_start (
int
) – The id of the first monomer of the first chain.number_of_chains (
int
) – Number of chains contained in the range.chain_length (
int
) – The length of every chain.
- Returns
Where [0] is the mean radius of gyration of the chains and [1] its standard deviation, [2] the mean square radius of gyration and [3] its standard deviation.
- Return type
(4,) array_like of
float
- calc_rh(self, chain_start=None, number_of_chains=None, chain_length=None)¶
Calculate the hydrodynamic mean radius of chains and its standard deviation.
This requires that a set of chains of equal length which start with the particle number
chain_start
and are consecutively numbered, the last particle in that topology having id numberchain_start + number_of_chains * chain_length - 1
.- Parameters
chain_start (
int
) – The id of the first monomer of the first chainnumber_of_chains (
int
) – Number of chains contained in the range.chain_length (
int
) – The length of every chain.
- Returns
Where [0] is the mean hydrodynamic radius of the chains and [1] its standard deviation.
- Return type
(2,) array_like of
float
- center_of_mass(self, p_type=None)¶
Calculate the system’s center of mass.
Note that virtual sites are not included, as they do not have a meaningful mass.
- Parameters
p_type (
int
) – Particletype
for which to calculate the center of mass.- Returns
The center of mass of the system.
- Return type
array of
float
- check_topology(self, chain_start=None, number_of_chains=None, chain_length=None)¶
- distribution(self, type_list_a=None, type_list_b=None, r_min=0.0, r_max=None, r_bins=100, log_flag=0, int_flag=0)¶
Calculates the distance distribution of particles (probability of finding a particle of type A at a certain distance around a particle of type B, disregarding the fact that a spherical shell of a larger radius covers a larger volume). The distance is defined as the minimal distance between a particle of group
type_list_a
to any of the grouptype_list_b
. Returns two arrays, the bins and the (normalized) distribution.- Parameters
type_list_a (list of
int
) – List of particletype
, only consider distances from these types.type_list_b (list of
int
) – List of particletype
, only consider distances to these types.r_min (
float
) – Minimum distance.r_max (
float
) – Maximum distance.r_bins (
int
) – Number of bins.log_flag (
bool
) – When set toFalse
, the bins are linearly equidistant; when set toTrue
, the bins are logarithmically equidistant.int_flag (
bool
) – When set toTrue
, 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 system energy in parallel.
- Returns
A dictionary with the following keys:
"total"
: total energy"kinetic"
: linear and rotational kinetic energy"bonded"
: total bonded energy"bonded", <bond_id>
: bonded energy from the bond identified bybond_id
"non_bonded"
: total non-bonded energy"non_bonded", <type_i>, <type_j>
: non-bonded energy from short-range interactions betweentype_i
andtype_j
"non_bonded_intra", <type_i>, <type_j>
: non-bonded energy from short-range interactions betweentype_i
andtype_j
with the samemol_id
"non_bonded_inter", <type_i>, <type_j>
: non-bonded energy from short-range interactions betweentype_i
andtype_j
with differentmol_id
"coulomb"
: Coulomb energy, how it is calculated depends on the method"coulomb", <i>
: Coulomb energy from particle pairs (i=0
), electrostatics solvers (i=1
)"dipolar"
: dipolar energy"dipolar", <i>
: dipolar energy from particle pairs and magnetic field constraints (i=0
), magnetostatics solvers (i=1
)"external_fields"
: external fields contribution
- Return type
dict
Examples
>>> energy = system.analysis.energy() >>> print(energy["total"]) >>> print(energy["kinetic"]) >>> print(energy["bonded"]) >>> print(energy["non_bonded"]) >>> print(energy["external_fields"])
- gyration_tensor(self, p_type=None)¶
Analyze the gyration tensor of particles of a given type or of all particles in the system if no type is given.
- Parameters
p_type (list of
int
, optional) – A particletype
, or list of all particle types to be considered.- Returns
A dictionary with the following keys:
"Rg^2"
: squared radius of gyration"shape"
: three shape descriptors (asphericity, acylindricity, and relative shape anisotropy)"eva0"
: eigenvalue 0 of the gyration tensor and its corresponding eigenvector."eva1"
: eigenvalue 1 of the gyration tensor and its corresponding eigenvector."eva2"
: eigenvalue 2 of the gyration tensor and its corresponding eigenvector.
The eigenvalues are sorted in descending order.
- Return type
dict
- linear_momentum(self, include_particles=True, include_lbfluid=True)¶
Calculates the system’s linear momentum.
- Parameters
include_particles (
bool
, optional) – whether to include the particles contribution to the linear momentum.include_lbfluid (
bool
, optional) – whether to include the lattice-Boltzmann fluid contribution to the linear momentum.
- Returns
The linear momentum of the system.
- Return type
float
- min_dist(self, p1='default', p2='default')¶
Minimal distance between two sets of particle types.
- Parameters
p1, p2 (lists of
int
) – Particletype
in both sets. If both are set to'default'
, the minimum distance of all pairs is returned.
- moment_of_inertia_matrix(self, p_type=None)¶
Returns the 3x3 moment of inertia matrix for particles of a given type.
- Parameters
p_type (
int
) – A particletype
- Returns
3x3 moment of inertia matrix.
- Return type
ndarray
- nbhood(self, pos=None, r_catch=None)¶
Get all particles in a defined neighborhood.
- Parameters
pos (array of
float
) – Reference position for the neighborhood.r_catch (
float
) – Radius of the region.
- Returns
The neighbouring particle ids.
- Return type
array of
int
- particle_energy(self, particle)¶
Calculate the non-bonded energy of a single given particle.
- Parameters
particle (
ParticleHandle
)- Returns
non-bonded energy of that particle
- Return type
obj: float
- pressure(self)¶
Calculate the instantaneous scalar 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_id>
: bonded pressure from the bond identified bybond_id
"non_bonded"
: total non-bonded pressure"non_bonded", <type_i>, <type_j>
: non-bonded pressure which arises from the interactions betweentype_i
andtype_j
"non_bonded_intra", <type_i>, <type_j>
: non-bonded pressure from short-range forces betweentype_i
andtype_j
with the samemol_id
"non_bonded_inter", <type_i>, <type_j>
: non-bonded pressure from short-range forces betweentype_i
andtype_j
with differentmol_id
"coulomb"
: Coulomb pressure, how it is calculated depends on the method. It is equivalent to 1/3 of the trace of the Coulomb pressure tensor. For how the pressure tensor is calculated, see Pressure Tensor. The averaged value in an isotropic NVT simulation is equivalent to the average of \(E^{\mathrm{coulomb}}/(3V)\), see [Brown and Neyertz, 1995]."coulomb", <i>
: Coulomb pressure from particle pairs (i=0
), electrostatics solvers (i=1
)"dipolar"
: not implemented"virtual_sites"
: Pressure contribution from virtual sites"external_fields"
: external fields contribution
- Return type
dict
- pressure_tensor(self)¶
Calculate the instantaneous pressure tensor in parallel. This is sensible in an anisotropic system. Still it assumes that the system is homogeneous since the volume-averaged pressure tensor is used. Do not use this pressure tensor in an (on average) inhomogeneous system. If the system is (on average inhomogeneous) then use a local pressure tensor. In order to obtain the pressure tensor, the ensemble average needs to be calculated.
- Returns
A dictionary with the following keys:
"total"
: total pressure tensor"kinetic"
: kinetic pressure tensor"bonded"
: total bonded pressure tensor"bonded", <bond_id>
: bonded pressure tensor from the bond identified bybond_id
"non_bonded"
: total non-bonded pressure tensor"non_bonded", <type_i>, <type_j>
: non-bonded pressure tensor from short-range forces betweentype_i
andtype_j
"non_bonded_intra", <type_i>, <type_j>
: non-bonded pressure tensor from short-range forces betweentype_i
andtype_j
with the samemol_id
"non_bonded_inter", <type_i>, <type_j>
: non-bonded pressure tensor from short-range forces betweentype_i
andtype_j
with differentmol_id
"coulomb"
: Maxwell pressure tensor, how it is calculated depends on the method"coulomb", <i>
: Maxwell pressure tensor from particle pairs (i=0
), electrostatics solvers (i=1
)"dipolar"
: not implemented"virtual_sites"
: pressure tensor contribution from virtual sites"external_fields"
: external fields contribution
- Return type
dict
- structure_factor(self, sf_types=None, sf_order=None)¶
Calculate the structure factor for given types. Returns the spherically averaged structure factor of particles specified in
sf_types
. The structure factor is calculated for all possible wave vectors q up tosf_order
. Do not choose parametersf_order
too large because the number of calculations grows assf_order
to the third power.- Parameters
sf_types (list of
int
) – Specifies which particletype
should be considered.sf_order (
int
) – Specifies the maximum wavevector.
- Returns
Where [0] contains q and [1] contains the structure factor s(q)
- Return type
ndarray
- v_kappa(self, mode=None, Vk1=None, Vk2=None, avk=None)¶
Todo
Looks to be incomplete
Calculate the compressibility through volume fluctuations.
- Parameters
mode (
str
, {‘read’, ‘set’ or ‘reset’}) – Mode.Vk1 (
float
) – Volume.Vk2 (
float
) – Volume squared.avk (
float
) – Number of averages.
- espressomd.analyze.autocorrelation(time_series)¶
Calculate the unnormalized autocorrelation function \(R_{XX}\) of an observable \(X\) measured at time \(t\) with constant time step for lag times \(\tau\) such that:
\(\displaystyle R_{XX}(\tau) = \frac{1}{N - \tau} \sum_{t=0}^{N - \tau} X_{t} \cdot X_{t + \tau}\)
This is a scipy implementation of the algorithm described in [de Buyl, 2018] that uses FFT. This implementation:
doesn’t subtract the mean of the time series before calculating the ACF,
doesn’t normalize the ACF by the variance of the time series,
assumes the time series is aperiodic (i.e. uses zero-padding).
- Parameters
time_series ((N,) or (N, M) array_like of
float
) – Time series to correlate. For multi-dimensional data, M is the number of columns.- Returns
The time series autocorrelation function.
- Return type
(N,) array_like of
float
espressomd.bond_breakage module¶
- class espressomd.bond_breakage.BreakageSpec(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Specifications for bond breakage. See Deleting bonds when particles are pulled apart for more details.
- Parameters
breakage_length (
float
) – Maximal bond extension until the bond breaks.action_type (
str
, {‘delete_bond’, ‘revert_bind_at_point_of_collision’, ‘none’}) – Action triggered when the bond reaches its maximal extension.
espressomd.cell_system module¶
- class espressomd.cell_system.CellSystem(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
This class controls the particle decomposition.
- decomposition_type¶
Name of the currently active particle decomposition.
- Type
str
- use_verlet_lists¶
Whether to use Verlet lists.
- Type
bool
- skin¶
Verlet list skin.
- Type
float
- node_grid¶
MPI repartition for the regular decomposition cell system.
- Type
(3,) array_like of
int
- max_cut_bonded¶
Maximal range from bonded interactions.
- Type
float
- max_cut_nonbonded¶
Maximal range from non-bonded interactions.
- Type
float
- interaction_range¶
Maximal interaction range from all interactions, or -1 when no interactions are active (or their cutoff has no impact when only 1 MPI rank is used).
- Type
float
- resort()¶
Resort the particles in the cell system.
- Parameters
global_flag (
bool
, optional) – If true (default), a global resorting is done, otherwise particles are only exchanged between neighboring nodes.- Returns
The number of particles per node.
- Return type
(N,) array_like of
int
- tune_skin()¶
Tune the skin by measuring the integration time and bisecting over the given range of skins. The best skin is set in the simulation core.
- Parameters
min_skin (
float
) – Minimum skin to test.max_skin (
float
) – Maximum skin.tol (
float
) – Accuracy in skin to tune to.int_steps (
int
) – Integration steps to time.adjust_max_skin (
bool
, optional) – IfTrue
, the value ofmax_skin
is reduced to the maximum permissible skin (in case the passed value is too large). Defaults toFalse
.
- Returns
The
skin
- Return type
float
- get_state()¶
Get the current state of the cell system.
- Returns
The cell system state.
- Return type
dict
- get_neighbors(particle, distance)[source]¶
Get neighbors of a given particle up to a certain distance.
The choice of cell systems has an impact on how far the algorithm can detect particle pairs:
N-square: no restriction on the search distance, no double counting if search distance is larger than the box size
regular decomposition: the search distance is bounded by half the local cell geometry
hybrid decomposition: not supported
- Parameters
particle (
ParticleHandle
)distance (
float
) – Pairs of particles closer thandistance
are found.
- Returns
The list of neighbor particles surrounding the particle
- Return type
(N,) array_like of
int
- get_pairs(distance, types='all')[source]¶
Get pairs of particles closer than threshold value.
- Parameters
distance (
float
) – Pairs of particles closer thandistance
are found.types (list of
int
or'all'
, optional) – Restrict the pair search to the specified types. Defaults to'all'
, in which case all particles are considered.
- Returns
The particle pairs identified by their index
- Return type
list of tuples of
int
- Raises
Exception – If the pair search distance is greater than the cell size
- set_hybrid_decomposition(**kwargs)[source]¶
Activate the hybrid domain decomposition.
- Parameters
cutoff_regular (
float
) – Maximum cutoff to consider in regular decomposition. Should be as low as the system permits.n_square_types (list of
int
, optional) – Particles types that should be handled in the N-square cell system. Defaults to an empty list.use_verlet_lists (
bool
, optional) – Activates or deactivates the usage of Verlet lists. Defaults toTrue
.
espressomd.checkpointing module¶
- class espressomd.checkpointing.Checkpoint(checkpoint_id=None, checkpoint_path='.')[source]¶
Bases:
object
Checkpoint handling (reading and writing).
- Parameters
checkpoint_id (
str
) – A string identifying a specific checkpoint.checkpoint_path (
str
, optional) – Path for reading and writing the checkpoint. If not given, the current working directory is used.
- get_last_checkpoint_index()[source]¶
Returns the last index of the given checkpoint id. Will raise exception if no checkpoints are found.
- get_registered_objects()[source]¶
Returns a list of all object names that are registered for checkpointing.
- has_checkpoints()[source]¶
Check for checkpoints.
- Returns
True
if any checkpoints exist that matchcheckpoint_id
andcheckpoint_path
otherwiseFalse
.- Return type
bool
- load(checkpoint_index=None)[source]¶
Loads the python objects using (c)Pickle and sets them in the calling module.
- Parameters
checkpoint_index (
int
, optional) – If not given, the lastcheckpoint_index
will be used.
- read_signals()[source]¶
Reads all registered signals from the signal file and returns a list of integers.
- register(*args)[source]¶
Register python objects for checkpointing.
- Parameters
args (list of
str
) – Names of python objects to be registered for checkpointing.
- register_signal(signum=None)[source]¶
Register a signal that will trigger the signal handler.
- Parameters
signum (
int
) – Signal to be registered.
espressomd.cluster_analysis module¶
- class espressomd.cluster_analysis.Cluster(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Class representing a cluster of particles.
- particle_ids()¶
Returns list of particle ids in the cluster
- size()¶
Returns the number of particles in the cluster
- center_of_mass()¶
Center of mass of the cluster (folded coordinates)
- longest_distance()¶
Longest distance between any combination of two particles in the cluster
- fractal_dimension(dr=None)¶
Estimates the cluster’s fractal dimension by fitting the number of particles \(n\) in spheres of growing radius around the center of mass to \(c*r_g^d\), where \(r_g\) is the radius of gyration of the particles within the sphere, and \(d\) is the fractal dimension.
Note
Requires
GSL
external feature, enabled with-DWITH_GSL=ON
.- Parameters
dr (
float
) – Minimum increment for the radius of the spheres.- Returns
Fractal dimension and mean square residual.
- Return type
tuple
- class espressomd.cluster_analysis.ClusterStructure(*args, **kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Cluster structure of a simulation system, and access to cluster analysis
- Parameters
pair_criterion (
espressomd.pair_criteria._PairCriterion
) – Criterion to decide whether two particles are neighbors.
- cid_for_particle(p)[source]¶
Returns cluster id for the particle.
- Parameters
p (
espressomd.particle_data.ParticleHandle
orint
containing the particle id) – Particle.
- property clusters¶
Gives access to the clusters in the cluster structure via an instance of
Clusters
.
- class espressomd.cluster_analysis.Clusters(cluster_structure)[source]¶
Bases:
object
Access to the clusters in the cluster structure.
Access is as follows:
number of clusters:
len(clusters)
access a cluster via its id:
clusters[id]
iterate over clusters (yields
(id, cluster)
tuples)
Example:
>>> for cluster_id, cluster in clusters: ... print(f"{cluster_id=} CoM={cluster.center_of_mass()}") cluster_id=1 CoM=[1.71834061 1.54988961 1.54734631]
espressomd.collision_detection module¶
- class espressomd.collision_detection.CollisionDetection(**kwargs)[source]¶
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
collision_detection
attribute of the system class to access the collision detection.Use method
set_params()
to change the parameters of the collision detection.- set_params(**kwargs)[source]¶
Set the parameters for the collision detection
See Creating bonds when particles collide for detailed instructions.
- Parameters
mode (
str
, {“off”, “bind_centers”, “bind_at_point_of_collision”, “bind_three_particles”, “glue_to_surface”}) – Collision detection modedistance (
float
) – Distance below which a pair of particles is considered in the collision detectionbond_centers (
espressomd.interactions.BondedInteraction
) – Bond to add between the colliding particlesbond_vs (
espressomd.interactions.BondedInteraction
) – Bond to add between virtual sites (for modes using virtual sites)part_type_vs (
int
) – Particle type of the virtual sites being created on collision (virtual sites based modes)part_type_to_be_glued (
int
) – particle type for"glue_to_surface"
mode. See user guide.part_type_to_attach_vs_to (
int
) – particle type for"glue_to_surface"
mode. See user guide.part_type_after_glueing (
int
) – particle type for"glue_to_surface"
mode. See user guide.distance_glued_particle_to_vs (
float
) – Distance for"glue_to_surface"
mode. See user guide.bond_three_particles (
espressomd.interactions.BondedInteraction
) – First angular bond for the"bind_three_particles"
mode. See user guidethree_particle_binding_angle_resolution (
int
) – Resolution for the angular bonds (mode"bind_three_particles"
). Resolution+1 bonds are needed to accommodate the case of 180 degrees angles
espressomd.comfixed module¶
- class espressomd.comfixed.ComFixed(**kwargs)[source]¶
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(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Base class for constraints. A constraint provides a force and an energy contribution for a single particle.
- class espressomd.constraints.Constraints(*args, **kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptObjectList
List of active constraints. Add a
espressomd.constraints.Constraint
to make it active in the system, or remove it to make it inactive.- add(*args, **kwargs)[source]¶
Add a constraint to the list.
- Parameters
constraint (
espressomd.constraints.Constraint
) – Either a constraint object…**kwargs (any) – … or parameters to construct an
espressomd.constraints.ShapeBasedConstraint
- Returns
constraint – The added constraint
- Return type
- remove(constraint)[source]¶
Remove a constraint from the list.
- Parameters
constraint (
espressomd.constraints.Constraint
)
- class espressomd.constraints.ElectricPlaneWave(phi=0, **kwargs)[source]¶
Bases:
espressomd.constraints.Constraint
Electric field of the form
\(E = E0 \cdot \sin(k \cdot x + \omega \cdot t + \phi)\)
The resulting force on the particles are then
\(F = q \cdot E\)
where \(q\) is the charge of the particle. This can be used to generate a homogeneous AC field by setting k to zero.
- Parameters
E0 (array_like of
float
) – Amplitude of the electric field.k (array_like of
float
) – Wave vector of the waveomega (
float
) – Frequency of the wavephi (
float
, optional) – Phase shift
- property E0¶
- property k¶
- property omega¶
- property phi¶
- class espressomd.constraints.ElectricPotential(**kwargs)[source]¶
Bases:
espressomd.constraints._Interpolated
Electric potential interpolated from provided data. The electric field E is calculated numerically from the potential, and the resulting force on the particles are
\(F = q \cdot E\)
where \(q\) is the charge of the particle.
- Parameters
field ((M, N, O, 1) array_like of
float
) – Potential on a grid of size (M, N, O)grid_spacing ((3,) array_like of
float
) – Spacing of the grid points.
- class espressomd.constraints.FlowField(**kwargs)[source]¶
Bases:
espressomd.constraints._Interpolated
Viscous coupling to a flow field that is interpolated from tabulated data like
\(F = -\gamma \cdot \left( u(r) - v \right)\)
where \(v\) is the velocity of the particle.
- Parameters
field ((M, N, O, 3) array_like of
float
) – Field velocity on a grid of size (M, N, O)grid_spacing ((3,) array_like of
float
) – Spacing of the grid points.gamma (
float
) – Coupling constant
- class espressomd.constraints.ForceField(**kwargs)[source]¶
Bases:
espressomd.constraints._Interpolated
A generic tabulated force field that applies a 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 (
dict
) – A dictionary mapping particle ids to scaling factors. For these particles, the interaction is scaled with their individual scaling factor. Other particles are scaled with the default scaling factor.
- class espressomd.constraints.Gravity(**kwargs)[source]¶
Bases:
espressomd.constraints.Constraint
Gravity force
\(F = m \cdot g\)
- Parameters
g ((3,) array_like of
float
) – The gravitational acceleration.
- property g¶
- class espressomd.constraints.HomogeneousFlowField(**kwargs)[source]¶
Bases:
espressomd.constraints.Constraint
Viscous coupling to a flow field that is constant in space with the force
\(F = -\gamma \cdot (u - v)\)
where \(v\) is the velocity of the particle.
- gamma¶
Coupling constant
- Type
float
- property u¶
Field velocity ((3,) array_like of
float
).
- class espressomd.constraints.HomogeneousMagneticField(**kwargs)[source]¶
Bases:
espressomd.constraints.Constraint
- H¶
Magnetic field vector. Describes both field direction and strength of the magnetic field (via length of the vector).
- Type
(3,) array_like of
float
- class espressomd.constraints.LinearElectricPotential(phi0=0, **kwargs)[source]¶
Bases:
espressomd.constraints.Constraint
Electric potential of the form
\(\phi = -E \cdot x + \phi_0\),
resulting in the electric field E everywhere. (E.g. in a plate capacitor). The resulting force on the particles are then
\(F = q \cdot E\)
where \(q\) is the charge of the particle.
- Parameters
E (array_like of
float
) – The electric field.phi0 (
float
) – The potential at the origin
- property E¶
- property phi0¶
- class espressomd.constraints.PotentialField(**kwargs)[source]¶
Bases:
espressomd.constraints._Interpolated
A generic tabulated force field that applies a 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 (
dict
) – A dictionary mapping particle ids to scaling factors. For these particles, the interaction is scaled with their individual scaling factor. Other particles are scaled with the default scaling factor.
- class espressomd.constraints.ShapeBasedConstraint(**kwargs)[source]¶
Bases:
espressomd.constraints.Constraint
- only_positive¶
Act only in the direction of positive normal, only useful if penetrable is
True
.- Type
bool
- particle_type¶
Interaction type of the constraint.
- Type
int
- particle_velocity¶
Interaction velocity of the boundary
- Type
array_like of
float
- penetrable¶
Whether particles are allowed to penetrate the constraint.
- Type
bool
- shape¶
One of the shapes from
espressomd.shapes
See also
espressomd.shapes
shape module that defines mathematical surfaces
Examples
>>> import espressomd >>> import espressomd.shapes >>> system = espressomd.System(box_l=3 * [10.]) >>> >>> # create first a shape-object to define the constraint surface >>> spherical_cavity = espressomd.shapes.Sphere(center=system.box_l / 2, radius=2.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(pos=0.51 * system.box_l, type=1)
- min_dist()[source]¶
Calculates the minimum distance to all interacting particles.
- Returns
The minimum distance
- Return type
float
- total_force()[source]¶
Get total force acting on this constraint.
Examples
>>> import espressomd >>> import espressomd.shapes >>> system = espressomd.System(box_l=[50., 50., 50.]) >>> system.time_step = 0.01 >>> 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=espressomd.shapes.Wall(normal=[0, 0, 1], dist=0.0), ... particle_type=0, penetrable=False, only_positive=False) >>> >>> p = system.part.add(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(p.pos, floor.total_force())
espressomd.cuda_init module¶
- class espressomd.cuda_init.CudaInitHandle¶
Bases:
object
- device¶
Get device.
- Returns
Id of current set device.
- Return type
int
- list_devices(self)¶
List devices.
- Returns
List of available CUDA devices.
- Return type
dict
- list_devices_properties(self)¶
List devices with their properties on each host machine.
- Returns
List of available CUDA devices with their properties.
- Return type
dict
- espressomd.cuda_init.gpu_available()¶
espressomd.drude_helpers module¶
- class espressomd.drude_helpers.DrudeHelpers[source]¶
Bases:
object
Provides helper functions to assist in the creation of Drude particles.
- add_all_thole(system, verbose=False)[source]¶
Calls
add_thole_pair_damping()
for all necessary combinations to create the interactions.- Parameters
system (
espressomd.system.System
)verbose (
bool
) – Turns on verbosity.
- add_drude_particle_to_core(system, harmonic_bond, thermalized_bond, p_core, type_drude, alpha, mass_drude, coulomb_prefactor, thole_damping=2.6, verbose=False)[source]¶
Adds a Drude particle with specified type and mass to the system and returns its espressomd.particle_data.ParticleHandle. Checks if different Drude particles have different types. Collects types/charges/polarizations/Thole factors for intramolecular core-Drude short-range exclusion and Thole interaction.
- Parameters
system (
espressomd.system.System
)harmonic_bond (
espressomd.interactions.HarmonicBond
) – Add this harmonic bond to between Drude particle and corethermalized_bond (
espressomd.interactions.ThermalizedBond
) – Add this thermalized_bond to between Drude particle and corep_core (
espressomd.particle_data.ParticleHandle
) – The existing core particletype_drude (
int
) – The type of the newly created Drude particlealpha (
float
) – The polarizability in units of inverse volume. Related to the charge of the Drude particle.mass_drude (
float
) – The mass of the newly created Drude particlecoulomb_prefactor (
float
) – Required to calculate the charge of the Drude particle.thole_damping (
float
) – Thole damping factor of the Drude pair. Comes to effect ifadd_all_thole()
method is used.verbose (
bool
) – Turns on verbosity.
- Returns
The created Drude Particle.
- Return type
- add_intramol_exclusion_bonds(drude_parts, core_parts, verbose=False)[source]¶
Applies electrostatic short-range exclusion bonds for the given ids. Has to be applied for all molecules.
- Parameters
system (
espressomd.system.System
)drude_parts – List of Drude particles within a molecule.
core_parts – List of core particles within a molecule.
verbose (
bool
) – Turns on verbosity.
- add_thole_pair_damping(system, t1, t2, verbose=False)[source]¶
Calculates mixed Thole factors depending on Thole damping and polarization. Adds non-bonded Thole interactions to the system.
- Parameters
system (
espressomd.system.System
)t1 (
int
) – Type 1t2 (
int
) – Type 2verbose (
bool
) – Turns on verbosity.
- setup_and_add_drude_exclusion_bonds(system, verbose=False)[source]¶
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.
- Parameters
system (
espressomd.system.System
)verbose (
bool
) – Turns on verbosity.
- setup_intramol_exclusion_bonds(system, mol_drude_types, mol_core_types, mol_core_partial_charges, verbose=False)[source]¶
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.
- Parameters
system (
espressomd.system.System
)mol_drude_types – List of types of Drude particles within the molecule
mol_core_types – List of types of core particles within the molecule
mol_core_partial_charges – List of partial charges of core particles within the molecule
verbose (
bool
) – Turns on verbosity.
espressomd.ekboundaries module¶
- class espressomd.ekboundaries.EKBoundaries(*args, **kwargs)[source]¶
Bases:
espressomd.lbboundaries.LBBoundaries
Creates a set of electrokinetics boundaries.
- class espressomd.ekboundaries.EKBoundary(**kwargs)[source]¶
Bases:
espressomd.lbboundaries.LBBoundary
Creates a EK boundary.
espressomd.electrokinetics module¶
- class espressomd.electrokinetics.Electrokinetics¶
Bases:
espressomd.lb.HydrodynamicInteraction
Creates the electrokinetic method using the GPU unit.
- add_boundary(self, shape)¶
- add_reaction(self, shape)¶
- add_species(self, species)¶
Initializes a new species for the electrokinetic method.
- Parameters
species (
int
) – Species to be initialized.
- default_params(self)¶
Returns the default parameters.
- ek_init(self)¶
Initializes the electrokinetic system. This automatically initializes the 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.
- 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.
- write_vtk_boundary(self, path)¶
Writes the boundary information into a vtk-file.
- Parameters
path (
str
) – Path of the .vtk file the boundary is written to.
- write_vtk_density(self, path)¶
Writes the LB density information into a vtk-file.
- Parameters
path (
str
) – Path of the .vtk file the LB density is written to.
- write_vtk_lbforce(self, path)¶
Writes the LB force information into a vtk-file.
- Parameters
path (
str
) – Path of the .vtk file the LB force is written to.
- write_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
) – Path of the .vtk file the electrostatic potential is written to.
- write_vtk_potential(self, path)¶
Writes the electrostatic potential into a vtk-file.
- Parameters
path (
str
) – Path of the .vtk file the electrostatic potential is written to.
- write_vtk_velocity(self, path)¶
Writes the lattice-Boltzmann velocity information into a vtk-file.
- Parameters
path (
str
) – Path of the .vtk file the velocity is written to.
- class espressomd.electrokinetics.ElectrokineticsRoutines¶
Bases:
espressomd.lb.LBFluidRoutines
- potential¶
- class espressomd.electrokinetics.Species(**kwargs)¶
Bases:
object
Creates a species object that is passed to the ek instance.
- default_params(self)¶
Returns the default parameters for the species.
- get_params(self)¶
Returns the parameters of the species.
- id = -1¶
- 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.
- write_vtk_density(self, path)¶
Writes the species density into a vtk-file.
- Parameters
path (
str
) – Path of the .vtk file the species density is written to.
- write_vtk_flux(self, path)¶
Writes the species flux into a vtk-file.
- Parameters
path (
str
) – Path of the .vtk file the species flux is written to.
- write_vtk_flux_fluc(self, path)¶
- write_vtk_flux_link(self, path)¶
espressomd.electrostatic_extensions module¶
- class espressomd.electrostatic_extensions.ICC(**kwargs)[source]¶
Bases:
espressomd.electrostatic_extensions.ElectrostaticExtensions
Interface to the induced charge calculation scheme for dielectric interfaces. See Dielectric interfaces with the ICC\star algorithm for more details.
- Parameters
n_icc (
int
) – Total number of ICC Particles.first_id (
int
, optional) – ID of the first ICC Particle.convergence (
float
, optional) – Abort criteria of the iteration. It corresponds to the maximum relative change of any of the interface particle’s charge.relaxation (
float
, optional) – SOR relaxation parameter.ext_field (
float
, optional) – Homogeneous electric field added to the calculation of dielectric boundary forces.max_iterations (
int
, optional) – Maximal number of iterations.eps_out (
float
, optional) – Relative permittivity of the outer region (where the particles are).normals ((
n_icc
, 3) array_likefloat
) – Normal vectors pointing into the outer region.areas ((
n_icc
, ) array_likefloat
) – Areas of the discretized surface.sigmas ((
n_icc
, ) array_likefloat
, optional) – Additional surface charge density in the absence of any charge induction.epsilons ((
n_icc
, ) array_likefloat
) – Dielectric constant associated to the areas.
espressomd.electrostatics module¶
- class espressomd.electrostatics.DH(**kwargs)[source]¶
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
) – Cutoff radius for this interaction.
- class espressomd.electrostatics.ELC(**kwargs)[source]¶
Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver for systems with two periodic dimensions. See Electrostatic Layer Correction (ELC) for more details.
- Parameters
actor (
P3M
, required) – Base P3M actor.gap_size (
float
, required) – The gap size gives the height \(h\) of the empty region between the system box and the neighboring artificial images. ESPResSo checks that the gap is empty and will throw an error if it isn’t. Therefore you should really make sure that the gap region is empty (e.g. with wall constraints).maxPWerror (
float
, required) – The maximal pairwise error sets the least upper bound (LUB) error of the force between any two charges without prefactors (see the papers). The algorithm tries to find parameters to meet this LUB requirements or will throw an error if there are none.delta_mid_top (
float
, optional) – Dielectric contrast \(\Delta_t\) between the upper boundary and the simulation box. Value between -1 and +1 (inclusive).delta_mid_bottom (
float
, optional) – Dielectric contrast \(\Delta_b\) between the lower boundary and the simulation box. Value between -1 and +1 (inclusive).const_pot (
bool
, optional) – Activate a constant electric potential between the top and bottom of the simulation box.pot_diff (
float
, optional) – Ifconst_pot
is enabled, this parameter controls the applied voltage between the boundaries of the simulation box in the z-direction (at \(z = 0\) and \(z = L_z - h\)).neutralize (
bool
, optional) – By default, ELC just as P3M adds a homogeneous neutralizing background to the system in case of a net charge. However, unlike in three dimensions, this background adds a parabolic potential across the slab [Ballenegger et al., 2009]. Therefore, under normal circumstances, you will probably want to disable the neutralization for non-neutral systems. This corresponds then to a formal regularization of the forces and energies [Ballenegger et al., 2009]. Also, if you add neutralizing walls explicitly as constraints, you have to disable the neutralization. When using a dielectric contrast or full metallic walls (delta_mid_top != 0
ordelta_mid_bot != 0
orconst_pot=True
),neutralize
is overwritten and switched off internally. Note that the special case of non-neutral systems with a non-metallic dielectric jump (e.g.delta_mid_top
ordelta_mid_bot
in]-1,1[
) is not covered by the algorithm and will throw an error.far_cut (
float
, optional) – Cutoff radius, use with care, intended for testing purposes. When setting the cutoff directly, the maximal pairwise error is ignored.
- class espressomd.electrostatics.ElectrostaticInteraction(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Common interface for electrostatics solvers.
- Parameters
prefactor (
float
) – Electrostatics prefactor \(\frac{1}{4\pi\varepsilon_0\varepsilon_r}\)
- class espressomd.electrostatics.MMM1D(**kwargs)[source]¶
Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver for systems with one periodic direction. See MMM1D for more details.
- Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).maxWPerror (
float
) – Maximal pairwise error.far_switch_radius (
float
, optional) – Radius where near-field and far-field calculation are switched.bessel_cutoff (
int
, optional)tune (
bool
, optional) – Specify whether to automatically tune or not. Defaults toTrue
.timings (
int
) – Number of force calculations during tuning.
- class espressomd.electrostatics.MMM1DGPU(**kwargs)[source]¶
Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver with GPU support for systems with one periodic direction. See MMM1D on GPU for more details.
- Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).maxWPerror (
float
) – Maximal pairwise error.far_switch_radius (
float
, optional) – Radius where near-field and far-field calculation are switchedbessel_cutoff (
int
, optional)tune (
bool
, optional) – Specify whether to automatically tune or not. Defaults toTrue
.
- class espressomd.electrostatics.P3M(**kwargs)[source]¶
Bases:
espressomd.electrostatics._P3MBase
P3M electrostatics solver.
Particle–Particle–Particle–Mesh (P3M) is a Fourier-based Ewald summation method to calculate potentials in N-body simulation. See Coulomb P3M for more details.
- Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).accuracy (
float
) – P3M tunes its parameters to provide this target accuracy.alpha (
float
, optional) – The Ewald parameter.cao (
float
, optional) – The charge-assignment order, an integer between 1 and 7.epsilon (
float
orstr
, optional) – A positive number for the dielectric constant of the surrounding medium. Use'metallic'
to set the dielectric constant of the surrounding medium to infinity (default).mesh (
int
or (3,) array_like ofint
, optional) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.mesh_off ((3,) array_like of
float
, optional) – Mesh offset.r_cut (
float
, optional) – The real space cutoff.tune (
bool
, optional) – Used to activate/deactivate the tuning method on activation. Defaults toTrue
.timings (
int
) – Number of force calculations during tuning.verbose (
bool
, optional) – IfFalse
, disable log output during tuning.check_neutrality (
bool
, optional) – Raise a warning if the system is not electrically neutral when set toTrue
(default).
- class espressomd.electrostatics.P3MGPU(**kwargs)[source]¶
Bases:
espressomd.electrostatics._P3MBase
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. See Coulomb P3M on GPU for more details.
- Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).accuracy (
float
) – P3M tunes its parameters to provide this target accuracy.alpha (
float
, optional) – The Ewald parameter.cao (
float
, optional) – The charge-assignment order, an integer between 0 and 7.epsilon (
float
orstr
, optional) – A positive number for the dielectric constant of the surrounding medium. Use'metallic'
to set the dielectric constant of the surrounding medium to infinity (default).mesh (
int
or (3,) array_like ofint
, optional) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.mesh_off ((3,) array_like of
float
, optional) – Mesh offset.r_cut (
float
, optional) – The real space cutofftune (
bool
, optional) – Used to activate/deactivate the tuning method on activation. Defaults toTrue
.timings (
int
) – Number of force calculations during tuning.verbose (
bool
, optional) – IfFalse
, disable log output during tuning.check_neutrality (
bool
, optional) – Raise a warning if the system is not electrically neutral when set toTrue
(default).
- class espressomd.electrostatics.ReactionField(**kwargs)[source]¶
Bases:
espressomd.electrostatics.ElectrostaticInteraction
Electrostatics solver based on the Reaction Field framework. See Reaction Field method for more details.
- Parameters
prefactor (
float
) – Electrostatics prefactor (see (1)).kappa (
float
) – Inverse Debye screening length.epsilon1 (
float
) – interior dielectric constantepsilon2 (
float
) – exterior dielectric constantr_cut (
float
) – Cutoff radius for this interaction.
- class espressomd.electrostatics.Scafacos(**kwargs)[source]¶
Bases:
espressomd.electrostatics.ElectrostaticInteraction
Calculate the Coulomb interaction using the ScaFaCoS library. See ScaFaCoS electrostatics for more details.
- Parameters
prefactor (
float
) – Coulomb prefactor as defined in (1).method_name (
str
) – Name of the ScaFaCoS method to use.method_params (
dict
) – Dictionary containing the method-specific parameters.
- get_available_methods()¶
List long-range methods available in the ScaFaCoS library.
- set_near_field_delegation()¶
Choose whether to delegate short-range calculation to ESPResSo (this is the default when the method supports it) or ScaFaCos.
- Parameters
delegate (
bool
) – Delegate to ESPResSo ifTrue
and the method supports it.
- get_near_field_delegation()¶
Find whether the short-range calculation is delegated to ESPResSo (this is the default when the method supports it) or ScaFaCos.
- Returns
delegate – Delegate to ESPResSo if
True
and the method supports it,False
if delegated to ScaFaCoS or the method doesn’t have a short-range kernel.- Return type
bool
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.highlander module¶
espressomd.integrate module¶
- class espressomd.integrate.BrownianDynamics¶
Bases:
espressomd.integrate.Integrator
Brownian Dynamics integrator.
- default_params(self)¶
- required_keys(self)¶
Parameters that have to be set.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.integrate.Integrator(*args, **kwargs)¶
Bases:
object
Integrator class.
- default_params(self)¶
Virtual method.
- get_params(self)¶
Get integrator parameters.
- required_keys(self)¶
Virtual method.
- 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.
- valid_keys(self)¶
Virtual method.
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.integrate.IntegratorHandle¶
Bases:
object
Provide access to all integrators.
- force_cap¶
- get_state(self)¶
Return the integrator.
- run(self, *args, **kwargs)¶
Run the integrator.
- set_brownian_dynamics(self)¶
Set the integration method to BD.
- set_isotropic_npt(self, *args, **kwargs)¶
Set the integration method to a modified velocity Verlet designed for simulations in the NpT ensemble (
VelocityVerletIsotropicNPT
).
- set_nvt(self)¶
Set the integration method to velocity Verlet, which is suitable for simulations in the NVT ensemble (
VelocityVerlet
).
- set_steepest_descent(self, *args, **kwargs)¶
Set the integration method to steepest descent (
SteepestDescent
).
- set_stokesian_dynamics(self, *args, **kwargs)¶
Set the integration method to Stokesian Dynamics (
StokesianDynamics
).
- set_vv(self)¶
Set the integration method to velocity Verlet, which is suitable for simulations in the NVT ensemble (
VelocityVerlet
).
- time¶
- time_step¶
- class espressomd.integrate.SteepestDescent¶
Bases:
espressomd.integrate.Integrator
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_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)¶
- required_keys(self)¶
Parameters that have to be set.
- run(self, steps=1, **kwargs)¶
Run the steepest descent.
- Parameters
steps (
int
) – Maximal number of time steps to integrate.- Returns
Number of integrated steps.
- Return type
int
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
- class espressomd.integrate.StokesianDynamics¶
Bases:
espressomd.integrate.Integrator
Stokesian Dynamics integrator.
- Parameters
viscosity (
float
) – Bulk viscosity.radii (
dict
) – Dictionary that maps particle types to radii.approximation_method (
str
, optional, {‘ft’, ‘fts’}) – Chooses the method of the mobility approximation.'fts'
is more accurate. Default is'fts'
.self_mobility (
bool
, optional) – Switches off or on the mobility terms for single particles. Default isTrue
.pair_mobility (
bool
, optional) – Switches off or on the hydrodynamic interactions between particles. Default isTrue
.
- default_params(self)¶
- required_keys(self)¶
Parameters that have to be set.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.integrate.VelocityVerlet¶
Bases:
espressomd.integrate.Integrator
Velocity Verlet integrator, suitable for simulations in the NVT ensemble.
- default_params(self)¶
- required_keys(self)¶
Parameters that have to be set.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.integrate.VelocityVerletIsotropicNPT¶
Bases:
espressomd.integrate.Integrator
Modified velocity Verlet integrator, suitable for simulations in the NpT ensemble with isotropic rescaling. Requires the NpT thermostat, activated with
espressomd.thermostat.Thermostat.set_npt()
.- Parameters
ext_pressure (
float
) – The external pressure.piston (
float
) – The mass of the applied piston.direction ((3,) array_like of
bool
, optional) – Select which dimensions are allowed to fluctuate by assigning them toTrue
.cubic_box (
bool
, optional) – IfTrue
, a cubic box is assumed and the value ofdirection
will be ignored when rescaling the box. This is required e.g. for electrostatics and magnetostatics.
- default_params(self)¶
- required_keys(self)¶
Parameters that have to be set.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
espressomd.interactions module¶
- class espressomd.interactions.AngleCosine(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Bond-angle-dependent cosine potential.
- Parameters
phi0 (
float
) – Equilibrium bond angle in radians.bend (
float
) – Magnitude of the bond interaction.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.AngleCossquare(*args, **kwargs)¶
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.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.AngleHarmonic(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Bond-angle-dependent harmonic potential.
- Parameters
phi0 (
float
) – Equilibrium bond angle in radians.bend (
float
) – Magnitude of the bond interaction.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.BMHTFInteraction¶
Bases:
espressomd.interactions.NonBondedInteraction
- default_params(self)¶
Python dictionary of default parameters.
- is_active(self)¶
Check if interaction is active.
- required_keys(self)¶
Parameters that have to be set.
- set_params(self, **kwargs)¶
Set parameters for the BMHTF interaction.
- Parameters
a (
float
) – Magnitude of exponential part of the interaction.b (
float
) – Exponential factor of the interaction.c (
float
) – Magnitude of the term decaying with the sixth power of r.d (
float
) – Magnitude of the term decaying with the eighth power of r.sig (
float
) – Shift in the exponent.cutoff (
float
) – Cutoff distance of the interaction.
- type_name(self)¶
Name of interaction type.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.interactions.BondedCoulomb(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Bonded Coulomb bond.
- Parameters
prefactor (
float
) – Coulomb prefactor of the bonded Coulomb interaction.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
- type_number(self)¶
- class espressomd.interactions.BondedCoulombSRBond(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Bonded Coulomb short range bond. Calculates the short range part of Coulomb interactions.
- Parameters
q1q2 (
float
) – Charge factor of the involved particle pair. Note the particle charges are used to allow e.g. only partial subtraction of the involved charges.
- get_default_params(self)¶
- type_name(self)¶
- type_number(self)¶
- class espressomd.interactions.BondedInteraction(*args, **kwargs)¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
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.
- get_default_params(self)¶
Gets default values of optional parameters.
- property params¶
- required_keys(self)¶
Parameters that have to be set.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self, params)¶
Check that parameters are valid.
- class espressomd.interactions.BondedInteractionNotDefined(*args, **kwargs)¶
Bases:
object
- get_default_params(self)¶
Gets default values of optional parameters.
- required_keys(self)¶
Parameters that have to be set.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- valid_keys(self)¶
All parameters that can be set.
- class espressomd.interactions.BondedInteractions(*args, **kwargs)¶
Bases:
espressomd.script_interface.ScriptObjectMap
Represents the bonded interactions list.
Individual interactions can be accessed using
BondedInteractions[i]
, wherei
is the bond id.- remove():
Remove a bond from the list. This is a no-op if the bond does not exist.
- Parameters
bond_id (
int
)
- clear()¶
Remove all bonds.
- add(self, *args, **kwargs)¶
Add a bond to the list.
- Parameters
bond (
espressomd.interactions.BondedInteraction
) – Either a bond object…**kwargs (any) – … or parameters to construct a
BondedInteraction
object
- 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 partk (
float
) – Exponent in the modified weight functionr_cut (
float
) – Cutoff of the parallel parttrans_weight_function (
int
, {0, 1}) – The distance dependence of the orthogonal part, either 0 (constant) or 1 (linear)trans_gamma (
float
) – Friction coefficient of the orthogonal parttrans_r_cut (
float
) – Cutoff of the orthogonal part
- type_name(self)¶
- valid_keys(self)¶
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.interactions.Dihedral(*args, **kwargs)¶
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.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- validate_params(self, params)¶
Check that parameters are valid.
- class espressomd.interactions.FeneBond(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
FENE bond.
- Parameters
k (
float
) – Magnitude of the bond interaction.d_r_max (
float
) – Maximum stretch and compression length of the bond.r_0 (
float
, optional) – Equilibrium bond length.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- 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
orstr
) – 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
orstr
{‘auto’}) – Constant shift of the potential. If'auto'
, a default value is computed from the other parameters. The LJ potential will be shifted by \(\epsilon\cdot\text{shift}\).offset (
float
) – Offset distance of the interaction.e1 (
int
) – Exponent of the repulsion term.e2 (
int
) – Exponent of the attraction term.b1 (
float
) – Prefactor of the repulsion term.b2 (
float
) – Prefactor of the attraction term.delta (
float
, optional) –LJGEN_SOFTCORE
parameter delta. Allows control over how smoothly the potential drops to zero as lambda approaches zero.lam (
float
, optional) –LJGEN_SOFTCORE
parameter lambda. Tune the strength of the interaction.
- type_name(self)¶
Name of interaction type.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- Raises
ValueError – If not true.
- class espressomd.interactions.HarmonicBond(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Harmonic bond.
- Parameters
k (
float
) – Magnitude of the bond interaction.r_0 (
float
) – Equilibrium bond length.r_cut (
float
, optional) – Maximum distance beyond which the bond is considered broken.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.HatInteraction¶
Bases:
espressomd.interactions.NonBondedInteraction
- default_params(self)¶
- is_active(self)¶
- required_keys(self)¶
- set_params(self, **kwargs)¶
Set parameters for the Hat interaction.
- Parameters
F_max (
float
) – Magnitude of the interaction.cutoff (
float
) – Cutoff distance of the interaction.
- type_name(self)¶
- valid_keys(self)¶
- validate_params(self)¶
- class espressomd.interactions.HertzianInteraction¶
Bases:
espressomd.interactions.NonBondedInteraction
- default_params(self)¶
Python dictionary of default parameters.
- is_active(self)¶
Check if interaction is active.
- required_keys(self)¶
Parameters that have to be set.
- set_params(self, **kwargs)¶
Set parameters for the Hertzian interaction.
- Parameters
eps (
float
) – Magnitude of the interaction.sig (
float
) – Parameter sigma. Determines the length over which the potential decays.
- type_name(self)¶
Name of interaction type.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.interactions.IBM_Tribend(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
IBM Tribend bond.
See Figure C.2 in [Krüger, 2012].
- Parameters
ind1, ind2, ind3, ind4 (
int
) – First, second, third and fourth bonding partner. Used for initializing reference statekb (
float
) – Bending modulusrefShape (
str
, optional, {‘Flat’, ‘Initial’}) – Reference shape, default is'Flat'
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
- type_number(self)¶
- valid_keys(self)¶
- validate_params(self, params)¶
Check that parameters are valid.
- class espressomd.interactions.IBM_Triel(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
IBM Triel bond.
See Figure C.1 in [Krüger, 2012].
- Parameters
ind1, ind2, ind3 (
int
) – First, second and third bonding partner. Used for initializing reference statek1 (
float
) – Shear elasticity for Skalak and Neo-Hookeank2 (
float
, optional) – Area resistance for SkalakmaxDist (
float
) – Gives an error if an edge becomes longer than maxDistelasticLaw (
str
, {‘NeoHookean’, ‘Skalak’}) – Type of elastic bond
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
- type_number(self)¶
- valid_keys(self)¶
- validate_params(self, params)¶
Check that parameters are valid.
- class espressomd.interactions.IBM_VolCons(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
IBM volume conservation bond.
See Figure C.3 in [Krüger, 2012].
- Parameters
softID (
int
) – Used to identify the object to which this bond belongs. Each object (cell) needs its own ID. For performance reasons, it is best to start fromsoftID=0
and increment by 1 for each subsequent bond.kappaV (
float
) – Modulus for volume force
- current_volume(self)¶
Query the current volume of the soft object associated to this bond. The volume is initialized once all
IBM_Triel
bonds have been added and the forces have been recalculated.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
- type_number(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
orstr
{‘auto’}) – Constant shift of the potential. If'auto'
, a default value is computed fromsigma
andcutoff
. The LJ potential will be shifted by \(4\epsilon\cdot\text{shift}\).offset (
float
, optional) – Offset distance of the interaction.min (
float
, optional) – Restricts the interaction to a minimal distance.
- type_name(self)¶
Name of interaction type.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- Raises
ValueError – If not true.
- class espressomd.interactions.MorseInteraction¶
Bases:
espressomd.interactions.NonBondedInteraction
- default_params(self)¶
Python dictionary of default parameters.
- is_active(self)¶
Check if interaction is active.
- required_keys(self)¶
Parameters that have to be set.
- set_params(self, **kwargs)¶
Set parameters for the Morse interaction.
- Parameters
eps (
float
) – The magnitude of the interaction.alpha (
float
) – Stiffness of the Morse interaction.rmin (
float
) – Distance of potential minimumcutoff (
float
, optional) – Cutoff distance of the interaction.
- type_name(self)¶
Name of interaction type.
- valid_keys(self)¶
All parameters that can be set.
- validate_params(self)¶
Check that parameters are valid.
- class espressomd.interactions.NonBondedInteraction(*args, **kwargs)¶
Bases:
object
Represents an instance of a 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(_type1, _type2)¶
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¶
- 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]
, wherei, j
are particle types. Returns aNonBondedInteractionHandle
object. Also: access to force capping.- reset(self)¶
Reset all interaction parameters to their default values.
- class espressomd.interactions.OifGlobalForces(*args, **kwargs)¶
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 meshka_g (
float
) – Area coefficientV0 (
float
) – Relaxed volume of the meshkv (
float
) – Volume coefficient
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.OifLocalForces(*args, **kwargs)¶
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 edgesks (
float
) – Non-linear stretching coefficient of triangle edgeskslin (
float
) – Linear stretching coefficient of triangle edgesphi0 (
float
) – Equilibrium angle between the two triangleskb (
float
) – Bending coefficient for the angle between the two trianglesA01 (
float
) – Equilibrium surface of the first triangleA02 (
float
) – Equilibrium surface of the second trianglekal (
float
) – Stretching coefficient of a triangle surfacekvisc (
float
) – Viscous coefficient of the triangle vertices
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.QuarticBond(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Quartic bond.
- Parameters
k0 (
float
) – Magnitude of the square term.k1 (
float
) – Magnitude of the fourth order term.r (
float
) – Equilibrium bond length.r_cut (
float
) – Maximum interaction length.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.RigidBond(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Rigid bond.
- Parameters
r (
float
) – Bond length.ptol (
float
, optional) – Tolerance for positional deviations.vtop (
float
, optional) – Tolerance for velocity deviations.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- 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.TabulatedAngle(*args, **kwargs)¶
Bases:
espressomd.interactions._TabulatedBase
Tabulated bond angle.
- Parameters
energy (array_like of
float
) – The energy table for the range \(0-\pi\).force (array_like of
float
) – The force table for the range \(0-\pi\).
- pi = 3.14159265358979¶
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- validate_params(self, params)¶
Check that parameters are valid.
- class espressomd.interactions.TabulatedDihedral(*args, **kwargs)¶
Bases:
espressomd.interactions._TabulatedBase
Tabulated bond dihedral.
- Parameters
energy (array_like of
float
) – The energy table for the range \(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, params)¶
Check that parameters are valid.
- class espressomd.interactions.TabulatedDistance(*args, **kwargs)¶
Bases:
espressomd.interactions._TabulatedBase
Tabulated bond length.
- Parameters
min (
float
) – The minimal interaction distance.max (
float
) – The maximal interaction distance.energy (array_like of
float
) – The energy table.force (array_like of
float
) – The force table.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- class espressomd.interactions.TabulatedNonBonded(*args, **kwargs)¶
Bases:
espressomd.interactions.NonBondedInteraction
- is_active(self)¶
Check if interaction is active.
- required_keys(self)¶
Parameters that have to be set.
- set_default_params(self)¶
Set parameters that are not required to their default value.
- set_params(self, **kwargs)¶
Set parameters for the TabulatedNonBonded interaction.
- Parameters
min (
float
,) – The minimal interaction distance.max (
float
,) – The maximal interaction distance.energy (array_like of
float
) – The energy table.force (array_like of
float
) – The force table.
- type_name(self)¶
Name of the potential.
- type_number(self)¶
- valid_keys(self)¶
All parameters that can be set.
- class espressomd.interactions.ThermalizedBond(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Thermalized bond.
- Parameters
temp_com (
float
) – Temperature of the Langevin thermostat for the center of mass of the particle pair.gamma_com (
float
) – Friction coefficient of the Langevin thermostat for the center of mass of the particle pair.temp_distance (
float
) – Temperature of the Langevin thermostat for the distance vector of the particle pair.gamma_distance (
float
) – Friction coefficient of the Langevin thermostat for the distance vector of the particle pair.r_cut (
float
, optional) – Maximum distance beyond which the bond is considered broken.seed (
int
) – Initial counter value (or seed) of the philox RNG. Required on the first thermalized bond in the system. Must be positive. If prompted, it does not return the initially set counter value (the seed) but the current state of the RNG.
- get_default_params(self)¶
- type_name(self)¶
- type_number(self)¶
- validate_params(self, params)¶
- class espressomd.interactions.TholeInteraction¶
Bases:
espressomd.interactions.NonBondedInteraction
- default_params(self)¶
- is_active(self)¶
- required_keys(self)¶
- set_params(self, **kwargs)¶
Set parameters for the Thole interaction.
- Parameters
scaling_coeff (
float
) – The factor used in the Thole damping function between polarizable particles i and j. Usually calculated by the polarizabilities \(\alpha_i\), \(\alpha_j\) and damping parameters \(a_i\), \(a_j\) via \(s_{ij} = \frac{(a_i+a_j)/2}{((\alpha_i\cdot\alpha_j)^{1/2})^{1/3}}\)q1q2 (
float
) – Charge factor of the involved charges. Has to be set because it acts only on the portion of the Drude core charge that is associated to the dipole of the atom. For charged, polarizable atoms that charge is not equal to the particle charge property.
- type_name(self)¶
- valid_keys(self)¶
- validate_params(self)¶
- class espressomd.interactions.Virtual(*args, **kwargs)¶
Bases:
espressomd.interactions.BondedInteraction
Virtual bond.
- get_default_params(self)¶
Gets default values of optional parameters.
- type_name(self)¶
Name of interaction type.
- type_number(self)¶
- 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.interactions.get_bonded_interaction_type_from_es_core(bond_id)¶
espressomd.lb module¶
- class espressomd.lb.FluidActor(*args, **kwargs)¶
Bases:
object
Abstract base class for interactions affecting particles in the system, such as LB fluids. Derived classes must implement the interface to the relevant core objects and global variables.
- active_list = {'HydrodynamicInteraction': 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.lb.HydrodynamicInteraction¶
Bases:
espressomd.lb.FluidActor
Base class for LB implementations.
- Parameters
agrid (
float
) – Lattice constant. The box size in every direction must be an integer multiple ofagrid
.tau (
float
) – LB time step, must be an integer multiple of the MD time step.dens (
float
) – Fluid density.visc (
float
) – Fluid kinematic viscosity.bulk_visc (
float
, optional) – Fluid bulk viscosity.gamma_odd (
int
, optional) – Relaxation parameter \(\gamma_{\textrm{odd}}\) for kinetic modes.gamma_even (
int
, optional) – Relaxation parameter \(\gamma_{\textrm{even}}\) for kinetic modes.ext_force_density ((3,) array_like of
float
, optional) – Force density applied on the fluid.kT (
float
, optional) – Thermal energy of the simulated heat bath (for thermalized fluids). Set it to 0 for an unthermalized fluid.seed (
int
, optional) – Initial counter value (or seed) of the philox RNG. Required for a thermalized fluid. Must be positive.
- 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)¶
Load LB node populations from a file.
LBBoundaries
information is not available in the file. The boundary information of the grid will be set to zero, even ifLBBoundaries
containsLBBoundary
objects (they are ignored).
- nodes(self)¶
Provides a generator for iterating over all lb nodes
- pressure_tensor¶
- required_keys(self)¶
- save_checkpoint(self, path, binary)¶
Write LB node populations to a file.
LBBoundaries
information is not written to the file.
- seed¶
- set_interpolation_order(self, interpolation_order)¶
Set the order for the fluid interpolation scheme.
- Parameters
interpolation_order (
str
, {“linear”, “quadratic”}) –"linear"
for trilinear interpolation,"quadratic"
for quadratic interpolation. For the CPU implementation of LB, only"linear"
is available.
- shape¶
- tau¶
- valid_keys(self)¶
- validate_params(self)¶
- viscosity¶
- write_boundary(self, path)¶
Write the LB boundaries to a data file that can be loaded by numpy, with format “x y z u”.
- Parameters
path (
str
) – Path to the output data file.
- write_velocity(self, path)¶
Write the LB fluid velocity to a data file that can be loaded by numpy, with format “x y z vx vy vz”.
- Parameters
path (
str
) – Path to the output data file.
- write_vtk_boundary(self, path)¶
Write the LB boundaries to a VTK file.
- Parameters
path (
str
) – Path to the output ASCII file.
- write_vtk_velocity(self, path, bb1=None, bb2=None)¶
Write the LB fluid velocity to a VTK file. If both
bb1
andbb2
are specified, return a subset of the grid.- Parameters
path (
str
) – Path to the output ASCII file.bb1 ((3,) array_like of
int
, optional) – Node indices of the lower corner of the bounding box.bb2 ((3,) array_like of
int
, optional) – Node indices of the upper corner of the bounding box.
- class espressomd.lb.LBFluid¶
Bases:
espressomd.lb.HydrodynamicInteraction
Initialize the lattice-Boltzmann method for hydrodynamic flow using the CPU. See
HydrodynamicInteraction
for the list of parameters.
- class espressomd.lb.LBFluidGPU¶
Bases:
espressomd.lb.HydrodynamicInteraction
Initialize the lattice-Boltzmann method for hydrodynamic flow using the GPU. See
HydrodynamicInteraction
for the list of parameters.- 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¶
- pressure_tensor¶
- pressure_tensor_neq¶
- velocity¶
- class espressomd.lb.LBSlice(key, shape)¶
Bases:
object
- property boundary¶
boundary for a slice
- property density¶
density for a slice
- get_indices(self, key, shape_x, shape_y, shape_z)¶
- get_values(self, x_indices, y_indices, z_indices, prop_name)¶
- property index¶
index for a slice
- property population¶
population for a slice
- property pressure_tensor¶
pressure_tensor for a slice
- property pressure_tensor_neq¶
pressure_tensor_neq for a slice
- set_values(self, x_indices, y_indices, z_indices, prop_name, value)¶
- property velocity¶
velocity for a slice
espressomd.lbboundaries module¶
- class espressomd.lbboundaries.LBBoundaries(*args, **kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptObjectList
Creates a set of lattice-Boltzmann boundaries.
- size()¶
Get the number of active boundaries.
- empty()¶
Return
True
if there are not active boundaries.
- clear()¶
Clear the list of boundaries.
- add(*args, **kwargs)[source]¶
Adds a boundary to the set of boundaries. Either pass a valid boundary as argument, or a valid set of parameters to create a boundary.
- remove(lbboundary)[source]¶
Removes a boundary from the set.
- Parameters
lbboundary (
LBBoundary
) – The boundary to be removed from the set.
- class espressomd.lbboundaries.LBBoundary(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Creates a LB boundary from a shape.
The fluid velocity is limited to \(v_{\mathrm{max}} = 0.20\) (see quasi-incompressible limit in [Krüger et al., 2017], chapter 7, page 272), which corresponds to Mach 0.35.
The relative error in the fluid density between a compressible fluid and an incompressible fluid at Mach 0.30 is less than 5% (see constant density assumption in [Kundu et al., 2001] chapter 16, page 663). Since the speed of sound is \(c_s = 1 / \sqrt{3}\) in LB velocity units in a D3Q19 lattice, the velocity limit at Mach 0.30 is \(v_{\mathrm{max}} = 0.30 / \sqrt{3} \approx 0.17\). At Mach 0.35 the relative error is around 6% and \(v_{\mathrm{max}} = 0.35 / \sqrt{3} \approx 0.20\).
- Parameters
shape (
espressomd.shapes.Shape
) – The shape from which to build the boundary.velocity ((3,) array_like of
float
, optional) – The boundary slip velocity. By default, a velocity of zero is used (no-slip boundary condition).
espressomd.lees_edwards module¶
- class espressomd.lees_edwards.LeesEdwards(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Interface to the Lees–Edwards boundary conditions. When writing H5MD files, the shear direction and shear plane normals are written as integers instead of characters, with 0 = x-axis, 1 = y-axis, 2 = z-axis.
- protocol¶
Lees–Edwards protocol.
- Type
object
- shear_velocity¶
Current shear velocity.
- Type
float
- pos_offset¶
Current position offset
- Type
float
- shear_direction¶
Shear direction.
- Type
str
, {‘x’, ‘y’, ‘z’}
- shear_plane_normal¶
Shear plane normal.
- Type
str
, {‘x’, ‘y’, ‘z’}
- set_boundary_conditions()¶
Set a protocol, the shear direction and shear normal.
- Parameters
protocol (
object
)shear_direction (
str
, {‘x’, ‘y’, ‘z’})shear_plane_normal (
str
, {‘x’, ‘y’, ‘z’})
- class espressomd.lees_edwards.LinearShear(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Lees–Edwards protocol for linear shear.
- Parameters
initial_pos_offset (
float
) – Positional offset at the Lees–Edwards boundary at t=0.shear_velocity (
float
) – Shear velocity (velocity jump) across the Lees–Edwards boundary.
- class espressomd.lees_edwards.Off(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Lees–Edwards protocol resulting in un-shifted boundaries.
- class espressomd.lees_edwards.OscillatoryShear(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Lees–Edwards protocol for oscillatory shear.
- Parameters
initial_pos_offset (
float
) – Positional offset at the Lees–Edwards boundary at t=0.amplitude (
float
) – Maximum amplitude of the positional offset at the Lees–Edwards boundary.omega (
float
) – Radian frequency of the oscillation.time_0 (
float
) – Time offset of the oscillation.
espressomd.magnetostatics module¶
- class espressomd.magnetostatics.DLC(**kwargs)[source]¶
Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Electrostatics solver for systems with two periodic dimensions. See Dipolar Layer Correction (DLC) for more details.
Notes
At present, the empty gap (volume without any particles), is assumed to be along the z-axis. As a reference for the DLC method, see [Bródka, 2004].
- Parameters
gap_size (
float
) – The gap size gives the height \(h\) of the empty region between the system box and the neighboring artificial images. ESPResSo checks that the gap is empty and will throw an error if it isn’t. Therefore you should really make sure that the gap region is empty (e.g. with wall constraints).maxPWerror (
float
) – Maximal pairwise error of the potential and force.far_cut (
float
, optional) – Cutoff of the exponential sum.
- class espressomd.magnetostatics.DipolarBarnesHutGpu(**kwargs)[source]¶
Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculates magnetostatic interactions by direct summation over all pairs. See Barnes-Hut octree sum on GPU for more details.
TODO: If the system has periodic boundaries, the minimum image convention is applied.
Requires feature
DIPOLAR_BARNES_HUT
, which depends onDIPOLES
andCUDA
.
- class espressomd.magnetostatics.DipolarDirectSumCpu(**kwargs)[source]¶
Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions by direct summation over all pairs. See Dipolar direct sum for more details.
If the system has periodic boundaries, the minimum image convention is applied in the respective directions.
- Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))
- class espressomd.magnetostatics.DipolarDirectSumGpu(**kwargs)[source]¶
Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions by direct summation over all pairs. See Dipolar direct sum for more details.
If the system has periodic boundaries, the minimum image convention is applied in the respective directions.
This is the GPU version of
espressomd.magnetostatics.DipolarDirectSumCpu
but uses floating point precision.Requires feature
DIPOLAR_DIRECT_SUM
, which depends onDIPOLES
andCUDA
.- Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))
- class espressomd.magnetostatics.DipolarDirectSumWithReplicaCpu(**kwargs)[source]¶
Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions by direct summation over all pairs. See Dipolar direct sum for more details.
If the system has periodic boundaries,
n_replica
copies of the system are taken into account in the respective directions. Spherical cutoff is applied.- Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))n_replica (
int
) – Number of replicas to be taken into account at periodic boundaries.
- class espressomd.magnetostatics.DipolarP3M(**kwargs)[source]¶
Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate magnetostatic interactions using the dipolar P3M method. See Dipolar P3M for more details.
- Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\))accuracy (
float
) – P3M tunes its parameters to provide this target accuracy.alpha (
float
) – Ewald parameter.cao (
int
) – Charge-assignment order, an integer between 1 and 7.mesh (
int
or (3,) array_like ofint
) – The number of mesh points in x, y and z direction. Use a single value for cubic boxes.mesh_off ((3,) array_like of
float
, optional) – Mesh offset.r_cut (
float
) – Real space cutoff.tune (
bool
, optional) – Activate/deactivate the tuning method on activation (default isTrue
, i.e., activated).timings (
int
) – Number of force calculations during tuning.
- class espressomd.magnetostatics.MagnetostaticInteraction(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Common interface for magnetostatics solvers.
- Parameters
prefactor (
float
) – Magnetostatics prefactor \(\frac{\mu_0\mu}{4\pi}\)
- class espressomd.magnetostatics.Scafacos(**kwargs)[source]¶
Bases:
espressomd.magnetostatics.MagnetostaticInteraction
Calculate the dipolar interaction using dipoles-capable methods from the ScaFaCoS library. See ScaFaCoS magnetostatics for more details.
- Parameters
prefactor (
float
) – Magnetostatics prefactor (\(\mu_0/(4\pi)\)).method_name (
str
) – Name of the ScaFaCoS method to use.method_params (
dict
) – Dictionary with the key-value pairs of the method parameters as defined in ScaFaCoS. Note that the values are cast to strings to match ScaFaCoS’ interface.
- get_available_methods()¶
List long-range methods available in the ScaFaCoS library.
espressomd.math module¶
- class espressomd.math.CylindricalTransformationParameters(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Class to hold and validate the parameters needed for a cylindrical transformation. The three parameters are available as attributes but are read-only.
- Parameters
center ((3,) array_like of
float
, default = [0, 0, 0]) – Position of the origin of the cylindrical coordinate system.axis ((3,) array_like of
float
, default = [0, 0, 1]) – Orientation vector of thez
-axis of the cylindrical coordinate system.orientation ((3,) array_like of
float
, default = [1, 0, 0]) – The axis on whichphi = 0
.
Notes
If you provide no arguments, the defaults above are set. If you provide only a
center
and anaxis
, anorientation
will be automatically generated that is orthogonal toaxis
.
espressomd.observables module¶
- class espressomd.observables.BondAngles(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the angles between bonds of particles with given ids along a polymer chain.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(N - 2,)
ndarray
offloat
- class espressomd.observables.BondDihedrals(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the dihedrals between particles with given ids along a polymer chain.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(N - 3,)
ndarray
offloat
- class espressomd.observables.ComPosition(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the center of mass for particles with given ids.
Note that virtual sites are not included since they do not have a meaningful mass.
Output format: \(\frac{1}{\sum_i m_i} \left( \sum_i m_i r^x_i, \sum_i m_i r^y_i, \sum_i m_i r^z_i\right)\)
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(3,)
ndarray
offloat
- class espressomd.observables.ComVelocity(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the center of mass velocity for particles with given ids.
Note that virtual sites are not included since they do not have a meaningful mass.
Output format: \(\frac{1}{\sum_i m_i} \left( \sum_i m_i v^x_i, \sum_i m_i v^y_i, \sum_i m_i v^z_i\right)\)
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(3,)
ndarray
offloat
- class espressomd.observables.CosPersistenceAngles(**kwargs)[source]¶
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.- Returns
- Return type
(N - 2,)
ndarray
offloat
- class espressomd.observables.CylindricalDensityProfile(transform_params=<espressomd.math.CylindricalTransformationParameters object>, **kwargs)[source]¶
Bases:
espressomd.observables.CylindricalProfileObservable
Calculates the particle density in cylindrical coordinates.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.transform_params (
espressomd.math.CylindricalTransformationParameters
, optional) – Parameters of the cylinder transformation. Defaults to the default ofespressomd.math.CylindricalTransformationParameters
n_r_bins (
int
, default = 1) – Number of bins in radial direction.n_phi_bins (
int
, default = 1) – Number of bins for the azimuthal direction.n_z_bins (
int
, default = 1) – Number of bins inz
direction.min_r (
float
, default = 0) – Minimumr
to consider.min_phi (
float
, default = -pi) – Minimumphi
to consider. Must be in [-pi,pi).min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
, default = pi) – Maximumphi
to consider. Must be in (-pi,pi].max_z (
float
) – Maximumz
to consider.
- Returns
- Return type
(
n_r_bins
,n_phi_bins
,n_z_bins
)ndarray
offloat
- class espressomd.observables.CylindricalFluxDensityProfile(transform_params=<espressomd.math.CylindricalTransformationParameters object>, **kwargs)[source]¶
Bases:
espressomd.observables.CylindricalProfileObservable
Calculates the particle flux density in cylindrical coordinates.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.transform_params (
espressomd.math.CylindricalTransformationParameters
, optional) – Parameters of the cylinder transformation. Defaults to the default ofespressomd.math.CylindricalTransformationParameters
n_r_bins (
int
, default = 1) – Number of bins in radial direction.n_phi_bins (
int
, default = 1) – Number of bins for the azimuthal direction.n_z_bins (
int
, default = 1) – Number of bins inz
direction.min_r (
float
, default = 0) – Minimumr
to consider.min_phi (
float
, default = -pi) – Minimumphi
to consider. Must be in [-pi,pi).min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
, default = pi) – Maximumphi
to consider. Must be in (-pi,pi].max_z (
float
) – Maximumz
to consider.
- Returns
The fourth component contains the histogram for the radial distance, azimuth and axial coordinate of the particle flux density field.
- Return type
(
n_r_bins
,n_phi_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.CylindricalLBFluxDensityProfileAtParticlePositions(transform_params=<espressomd.math.CylindricalTransformationParameters object>, **kwargs)[source]¶
Bases:
espressomd.observables.CylindricalProfileObservable
Calculates the LB fluid flux density at the particle positions in cylindrical coordinates.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.transform_params (
espressomd.math.CylindricalTransformationParameters
, optional) – Parameters of the cylinder transformation. Defaults to the default ofespressomd.math.CylindricalTransformationParameters
n_r_bins (
int
, default = 1) – Number of bins in radial direction.n_phi_bins (
int
, default = 1) – Number of bins for the azimuthal direction.n_z_bins (
int
, default = 1) – Number of bins inz
direction.min_r (
float
, default = 0) – Minimumr
to consider.min_phi (
float
, default = -pi) – Minimumphi
to consider. Must be in [-pi,pi).min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
, default = pi) – Maximumphi
to consider. Must be in (-pi,pi].max_z (
float
) – Maximumz
to consider.
- Returns
The fourth component contains the histogram for the radial distance, azimuth and axial coordinate of the LB flux density field.
- Return type
(
n_r_bins
,n_phi_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.CylindricalLBVelocityProfile(transform_params=<espressomd.math.CylindricalTransformationParameters object>, **kwargs)[source]¶
Bases:
espressomd.observables.CylindricalProfileObservable
Calculates the LB fluid velocity profile in cylindrical coordinates.
This observable samples the fluid in on a regular grid defined by variable
sampling_density
. Note that a small delta leads to a large number of sample points and carries a performance cost.- Parameters
transform_params (
espressomd.math.CylindricalTransformationParameters
, optional) – Parameters of the cylinder transformation. Defaults to the default ofespressomd.math.CylindricalTransformationParameters
n_r_bins (
int
, default = 1) – Number of bins in radial direction.n_phi_bins (
int
, default = 1) – Number of bins for the azimuthal direction.n_z_bins (
int
, default = 1) – Number of bins inz
direction.min_r (
float
, default = 0) – Minimumr
to consider.min_phi (
float
, default = -pi) – Minimumphi
to consider. Must be in [-pi,pi).min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
, default = pi) – Maximumphi
to consider. Must be in (-pi,pi].max_z (
float
) – Maximumz
to consider.sampling_density (
float
) – Samples per unit volume for the LB velocity interpolation.
- Returns
The fourth component contains the histogram for the radial distance, azimuth and axial coordinate of the LB velocity field.
- Return type
(
n_r_bins
,n_phi_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.CylindricalLBVelocityProfileAtParticlePositions(transform_params=<espressomd.math.CylindricalTransformationParameters object>, **kwargs)[source]¶
Bases:
espressomd.observables.CylindricalProfileObservable
Calculates the LB fluid velocity at the particle positions in cylindrical coordinates.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.transform_params (
espressomd.math.CylindricalTransformationParameters
, optional) – Parameters of the cylinder transformation. Defaults to the default ofespressomd.math.CylindricalTransformationParameters
n_r_bins (
int
, default = 1) – Number of bins in radial direction.n_phi_bins (
int
, default = 1) – Number of bins for the azimuthal direction.n_z_bins (
int
, default = 1) – Number of bins inz
direction.min_r (
float
, default = 0) – Minimumr
to consider.min_phi (
float
, default = -pi) – Minimumphi
to consider. Must be in [-pi,pi).min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
, default = pi) – Maximumphi
to consider. Must be in (-pi,pi].max_z (
float
) – Maximumz
to consider.
- Returns
The fourth component contains the histogram for the radial distance, azimuth and axial coordinate of the LB velocity field.
- Return type
(
n_r_bins
,n_phi_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.CylindricalProfileObservable(transform_params=<espressomd.math.CylindricalTransformationParameters object>, **kwargs)[source]¶
Bases:
espressomd.observables.ProfileObservable
Base class for observables that work with cylinder coordinates
- class espressomd.observables.CylindricalVelocityProfile(transform_params=<espressomd.math.CylindricalTransformationParameters object>, **kwargs)[source]¶
Bases:
espressomd.observables.CylindricalProfileObservable
Calculates the particle velocity profile in cylindrical coordinates.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.transform_params (
espressomd.math.CylindricalTransformationParameters
, optional) – Parameters of the cylinder transformation. Defaults to the default ofespressomd.math.CylindricalTransformationParameters
n_r_bins (
int
, default = 1) – Number of bins in radial direction.n_phi_bins (
int
, default = 1) – Number of bins for the azimuthal direction.n_z_bins (
int
, default = 1) – Number of bins inz
direction.min_r (
float
, default = 0) – Minimumr
to consider.min_phi (
float
, default = -pi) – Minimumphi
to consider. Must be in [-pi,pi).min_z (
float
) – Minimumz
to consider.max_r (
float
) – Maximumr
to consider.max_phi (
float
, default = pi) – Maximumphi
to consider. Must be in (-pi,pi].max_z (
float
) – Maximumz
to consider.
- Returns
The fourth component contains the histogram for the radial distance, azimuth and axial coordinate of the particle velocity field.
- Return type
(
n_r_bins
,n_phi_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.DPDStress(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the non-equilibrium contribution of the DPD interaction to the stress tensor.
- Parameters
None
- Returns
- Return type
(3, 3)
ndarray
offloat
- class espressomd.observables.DensityProfile(**kwargs)[source]¶
Bases:
espressomd.observables.ProfileObservable
Calculates the particle density profile for particles with given ids.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.
- Returns
- Return type
(3,)
ndarray
offloat
- class espressomd.observables.DipoleMoment(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the dipole moment for particles with given ids.
Output format: \(\left(\sum_i q_i r^x_i, \sum_i q_i r^y_i, \sum_i q_i r^z_i\right)\)
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(3,)
ndarray
offloat
- class espressomd.observables.Energy(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the total energy.
- Returns
- Return type
float
- class espressomd.observables.FluxDensityProfile(**kwargs)[source]¶
Bases:
espressomd.observables.ProfileObservable
Calculates the particle flux density for particles with given ids.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.
- Returns
The fourth component contains the histogram for the x, y and z components of the flux density.
- Return type
(
n_x_bins
,n_y_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.ForceDensityProfile(**kwargs)[source]¶
Bases:
espressomd.observables.ProfileObservable
Calculates the force density profile for particles with given ids.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.
- Returns
The fourth component contains the histogram for the x, y and z components of the force.
- Return type
(
n_x_bins
,n_y_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.LBFluidPressureTensor(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the average pressure tensor of the LB fluid for all nodes.
- Parameters
None
- Returns
- Return type
(3, 3)
ndarray
offloat
- class espressomd.observables.LBVelocityProfile(**kwargs)[source]¶
Bases:
espressomd.observables.ProfileObservable
Calculates the LB fluid velocity profile.
This observable samples the fluid in on a regular grid defined by the variables
sampling_*
. Note that a small delta leads to a large number of sample points and carries a performance cost.Warning
In case of the CPU version of the LB fluid implementation, this observable currently only works for a single core.
- Parameters
n_x_bins (
int
) – Number of bins inx
direction.n_y_bins (
int
) – Number of bins iny
direction.n_z_bins (
int
) – Number of bins inz
direction.min_x (
float
) – Minimumx
to consider.min_y (
float
) – Minimumy
to consider.min_z (
float
) – Minimumz
to consider.max_x (
float
) – Maximumx
to consider.max_y (
float
) – Maximumy
to consider.max_z (
float
) – Maximumz
to consider.sampling_delta_x (
float
, default=1.0) – Spacing for the sampling grid inx
-direction.sampling_delta_y (
float
, default=1.0) – Spacing for the sampling grid iny
-direction.sampling_delta_z (
float
, default=1.0) – Spacing for the sampling grid inz
-direction.sampling_offset_x (
float
, default=0.0) – Offset for the sampling grid inx
-direction.sampling_offset_y (
float
, default=0.0) – Offset for the sampling grid iny
-direction.sampling_offset_z (
float
, default=0.0) – Offset for the sampling grid inz
-direction.allow_empty_bins (
bool
, default=False) – Whether or not to allow bins that will not be sampled at all.
- Returns
The fourth component contains the histogram for the x, y and z components of the LB velocity.
- Return type
(
n_x_bins
,n_y_bins
,n_z_bins
, 3)ndarray
offloat
- class espressomd.observables.MagneticDipoleMoment(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the magnetic dipole moment for particles with given ids.
Output format: \(\left(\sum_i \mu^x_i, \sum_i \mu^y_i, \sum_i \mu^z_i\right)\)
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(3,)
ndarray
offloat
- class espressomd.observables.Observable(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Base class for all observables.
- shape()¶
Return the shape of the observable.
- class espressomd.observables.ParticleAngularVelocities(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the angular velocity (omega) in the spaced-fixed frame of reference
Output format: \((\omega^x_1,\ \omega^y_1,\ \omega^z_1),\ (\omega^x_2,\ \omega^y_2,\ \omega^z_2), \dots,\ (\omega^x_n,\ \omega^y_n,\ \omega^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.- Returns
- Return type
(N, 3)
ndarray
offloat
- class espressomd.observables.ParticleBodyAngularVelocities(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the angular velocity (omega) 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: \((\omega^x_1,\ \omega^y_1,\ \omega^z_1),\ (\omega^x_2,\ \omega^y_2,\ \omega^z_2), \dots,\ (\omega^x_n,\ \omega^y_n,\ \omega^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.- Returns
- Return type
(N, 3)
ndarray
offloat
- class espressomd.observables.ParticleBodyVelocities(**kwargs)[source]¶
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^x_1,\ v^y_1,\ v^z_1),\ (v^x_2,\ v^y_2,\ v^z_2),\ \dots,\ (v^x_n,\ v^y_n,\ v^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.- Returns
- Return type
(N, 3)
ndarray
offloat
- class espressomd.observables.ParticleDistances(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the distances between particles with given ids along a polymer chain.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(N - 1,)
ndarray
offloat
- class espressomd.observables.ParticleForces(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the particle forces for particles with given ids.
Output format: \((f^x_1,\ f^y_1,\ f^z_1),\ (f^x_2,\ f^y_2,\ f^z_2),\ \dots,\ (f^x_n,\ f^y_n,\ f^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.- Returns
- Return type
(N, 3)
ndarray
offloat
- class espressomd.observables.ParticlePositions(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the particle positions for particles with given ids.
Output format: \((x_1,\ y_1,\ z_1),\ (x_2,\ y_2,\ z_2),\ \dots,\ (x_n,\ y_n,\ z_n)\).
The particles are ordered according to the list of ids passed to the observable.
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(N, 3)
ndarray
offloat
- class espressomd.observables.ParticleVelocities(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the particle velocities for particles with given ids.
Output format: \((v^x_1,\ v^y_1,\ v^z_1),\ (v^x_2,\ v^y_2,\ v^z_2),\ \dots,\ (v^x_n,\ v^y_n,\ v^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.- Returns
- Return type
(N, 3)
ndarray
offloat
- class espressomd.observables.Pressure(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the total scalar pressure.
- Returns
- Return type
float
- class espressomd.observables.PressureTensor(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the total pressure tensor.
- Returns
- Return type
(3, 3)
ndarray
offloat
- class espressomd.observables.ProfileObservable(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Base class for histogram-based observables.
- class espressomd.observables.RDF(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates a radial distribution function. The result is normalized by the bulk concentration.
- Parameters
ids1 (array_like of
int
) – The ids of (existing) particles to calculate the distance from.ids2 (array_like of
int
, optional) – The ids of (existing) particles to calculate the distance to. If not provided, useids1
.n_r_bins (
int
) – Number of bins in radial direction.min_r (
float
) – Minimumr
to consider.max_r (
float
) – Maximumr
to consider.
- Returns
The RDF.
- Return type
(
n_r_bins
,)ndarray
offloat
- class espressomd.observables.TotalForce(**kwargs)[source]¶
Bases:
espressomd.observables.Observable
Calculates the total force on particles with given ids.
Note that virtual sites are not included since forces on them do not enter the equation of motion directly.
Output format: \(\left(\sum_i f^x_i, \sum_i f^y_i, \sum_i f^z_i\right)\)
- Parameters
ids (array_like of
int
) – The ids of (existing) particles to take into account.- Returns
- Return type
(3,)
ndarray
offloat
espressomd.pair_criteria module¶
- class espressomd.pair_criteria.BondCriterion(**kwargs)[source]¶
Bases:
espressomd.pair_criteria._PairCriterion
Pair criterion returning true, if a pair bond of given type exists between them
The following parameters can be passed to the constructor, changed via
set_params()
and retrieved viaget_params()
.- Parameters
bond_type (
int
) – numeric type of the bond
- class espressomd.pair_criteria.DistanceCriterion(**kwargs)[source]¶
Bases:
espressomd.pair_criteria._PairCriterion
Pair criterion returning true, if particles are closer than a cutoff. Periodic boundaries are treated via minimum image convention.
The following parameters can be passed to the constructor, changed via
set_params()
and retrieved viaget_params()
.- Parameters
cut_off (
float
) – distance cutoff for the criterion
- class espressomd.pair_criteria.EnergyCriterion(**kwargs)[source]¶
Bases:
espressomd.pair_criteria._PairCriterion
Pair criterion returning true, if the short range energy between the particles is superior or equal to the cutoff.
Be aware that the short range energy contains the short range part of dipolar and electrostatic interactions, but not the long range part.
The following parameters can be passed to the constructor, changed via
set_params()
and retrieved viaget_params()
.- Parameters
cut_off (
float
) – energy cutoff for the criterion
espressomd.particle_data module¶
- class espressomd.particle_data.ParticleHandle¶
Bases:
object
- add_bond(self, bond)¶
Add a single bond to the particle.
- Parameters
bond (
tuple
) – tuple where the first element is either a bond ID or a bond object, and the next elements are particle ids or particle objects to be bonded to.
See also
bonds
Particle
property containing a list of all current bonds held byParticle
.
Examples
>>> import espressomd.interactions >>> >>> system = espressomd.System(box_l=3 * [10]) >>> >>> # define a harmonic potential and add it to the system >>> harm_bond = espressomd.interactions.HarmonicBond(r_0=1, k=5) >>> system.bonded_inter.add(harm_bond) >>> >>> # add two particles >>> p1 = system.part.add(pos=(1, 0, 0)) >>> p2 = system.part.add(pos=(2, 0, 0)) >>> >>> # bond them via the bond type >>> p1.add_bond((harm_bond, p2)) >>> # or via the bond index (zero in this case since it is the first one added) >>> p1.add_bond((0, p2))
- add_exclusion(self, partner)¶
Exclude non-bonded interactions with the given partner.
Note
This needs the feature
EXCLUSIONS
.- Parameters
partner (
ParticleHandle
orint
) – Particle to exclude.
- add_verified_bond(self, bond)¶
Add a bond, the validity of which has already been verified.
- bonds¶
The bonds stored by this particle. Note that bonds are only stored by one partner. You need to define a bonded interaction.
bonds : list/tuple of tuples/lists
A bond tuple is specified as a bond identifier associated with a particle
(bond_ID, part_ID)
. A single particle may contain multiple such tuples.See also
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.
- 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 held byParticle
.
- delete_bond(self, bond)¶
Delete a single bond from the particle.
- Parameters
bond (
tuple
) – tuple where the first element is either a bond ID or a bond object, and the next elements are particle ids or particle objects that are bonded to.
See also
bonds
Particle
property containing a list of all bonds currently held byParticle
.
Examples
>>> import espressomd.interactions >>> >>> system = espressomd.System(box_l=3 * [10]) >>> >>> # define a harmonic potential and add it to the system >>> harm_bond = espressomd.interactions.HarmonicBond(r_0=1, k=5) >>> system.bonded_inter.add(harm_bond) >>> >>> # bond two particles to the first one >>> p0 = system.part.add(pos=(1, 0, 0)) >>> p1 = system.part.add(pos=(2, 0, 0)) >>> p2 = system.part.add(pos=(1, 1, 0)) >>> p0.add_bond((harm_bond, p1)) >>> p0.add_bond((harm_bond, p2)) >>> >>> print(p0.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 first bond >>> p0.delete_bond(p0.bonds[0]) >>> print(p0.bonds) ((HarmonicBond(0): {'r_0': 1.0, 'k': 5.0, 'r_cut': 0.0}, 2),)
- delete_exclusion(self, partner)¶
Remove exclusion of non-bonded interactions with the given partner.
Note
This needs the feature
EXCLUSIONS
.- Parameters
partner (
ParticleHandle
orint
) – Particle to remove from exclusions.
- delete_verified_bond(self, bond)¶
Delete a single bond from the particle. The validity of which has already been verified.
- Parameters
bond (
tuple
) – tuple where the first element is either a bond ID of a bond type, and the last element is the ID of the partner particle to be bonded to.
See also
delete_bond
Delete an unverified bond held by the
Particle
.bonds
Particle
property containing a list of all current bonds held byParticle
.
- dip¶
The orientation of the dipole axis.
dip : (3,) array_like of
float
Note
This needs the feature
DIPOLES
.
- dipm¶
The magnitude of the dipole moment.
dipm :
float
Note
This needs the feature
DIPOLES
.
- director¶
The particle director.
The
director
defines the the z-axis in the body-fixed frame. If particle rotations happen, the director, i.e., the body-fixed coordinate system co-rotates. Properties such as the angular velocityespressomd.particle_data.ParticleHandle.omega_body
are evaluated in this body-fixed coordinate system. When using particle dipoles, the dipole moment is co-aligned with the particle director. Setting the director thus modifies the dipole moment orientation (espressomd.particle_data.ParticleHandle.dip
) and vice versa. See also Rotational degrees of freedom and particle anisotropy.director : (3,) array_like of
float
Note
This needs the feature
ROTATION
.
- exclusions¶
The exclusion list of particles where non-bonded interactions are ignored.
Note
This needs the feature
EXCLUSIONS
.exclusions : (N,) array_like of
int
- ext_force¶
An additional external force applied to the particle.
ext_force : (3,) array_like of
float
Note
This needs the feature
EXTERNAL_FORCES
.
- ext_torque¶
An additional external torque is applied to the particle.
ext_torque : (3,) array_like of
float
Note
This torque is specified in the laboratory frame!
This needs features
EXTERNAL_FORCES
andROTATION
.
- f¶
The instantaneous force acting on this particle.
f : (3,) array_like of
float
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
bool
Fixes the particle in space. By supplying a set of 3 bools as arguments it is possible to fix motion in x, y, or z coordinates independently. For example:
part[<INDEX>].fix = [False, False, True]
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 and Brownian thermostats.
gamma :
float
or (3,) array_like offloat
Note
This needs features
PARTICLE_ANISOTROPY
andTHERMOSTAT_PER_PARTICLE
.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 and Brownian thermostats.
gamma_rot :
float
or (3,) array_like offloat
Note
This needs features
ROTATION
,PARTICLE_ANISOTROPY
andTHERMOSTAT_PER_PARTICLE
.
- 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.
- lees_edwards_flag¶
The Lees-Edwards flag that indicate if the particle crossed the upper or lower boundary.
- lees_edwards_offset¶
The accumulated Lees-Edwards offset. Can be used to reconstruct continuous trajectories.
offset : (3,) array_like of
float
- mass¶
Particle mass.
mass :
float
See also
espressomd.thermostat.Thermostat.set_langevin()
Setting the parameters of the Langevin thermostat
- mol_id¶
The molecule id of the Particle.
mol_id :
int
The particle
mol_id
is used to differentiate between particles belonging to different molecules, e.g. when virtual sites are used, or object-in-fluid cells. The defaultmol_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.
- normalize_and_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.
Normalize the bond, i.e. replace bond ids by bond objects and particle objects by particle ids.
- 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
Note
This needs the feature
ROTATION
.If you set the angular velocity of the particle in the lab frame, the orientation of the particle (
quat
) must be set before settingomega_lab
, otherwise the conversion from lab to body frame will not be handled properly.See also
- pos¶
The unwrapped (not folded into central box) particle position.
pos : (3,) array_like of
float
- pos_folded¶
The wrapped (folded into central box) position vector of a particle.
pos : (3,) array_like of
float
Note
Setting the folded position is ambiguous and is thus not possible, please use
pos
.Examples
>>> import espressomd >>> system = espressomd.System(box_l=[10, 10, 10]) >>> system.part.add(pos=(5, 0, 0)) >>> system.part.add(pos=(10, 0, 0)) >>> system.part.add(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¶
Quaternion representation of the particle rotational position.
quat : (4,) array_like of
float
Note
This needs the feature
ROTATION
.
- remove(self)¶
Delete the particle.
- rinertia¶
The particle rotational inertia.
rinertia : (3,) array_like of
float
Sets the diagonal elements of this particles rotational inertia tensor. These correspond with the inertial moments along the coordinate axes in the particle’s 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, angle)¶
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
bool
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 byv_swim
. Alternatively it is possible to achieve a constant velocity by imposing a constant force termf_swim
that is balanced by friction of a (Langevin) thermostat. The way the velocity of the particle decays to the constant terminal velocity in either of these methods is completely determined by the friction coefficient. You may only set one of the possibilitiesv_swim
orf_swim
as you cannot relax to constant force and constant velocity at the same time. Setting bothv_swim
andf_swim
to 0.0 disables swimming. This option applies to all non-lattice-Boltzmann thermostats. Note that there is no real difference betweenv_swim
andf_swim
since the latter may always be chosen such that the same terminal velocity is achieved for a given friction coefficient.- Parameters
f_swim (
float
) – Achieve a constant velocity by imposing a constant force termf_swim
that is balanced by friction of a (Langevin) thermostat. This excludes the optionv_swim
.v_swim (
float
) – Achieve a constant velocity by imposing a constant terminal velocityv_swim
. This excludes the optionf_swim
.mode (
str
, {‘pusher’, ‘puller’, ‘N/A’}) – The LB flow field can be generated by a pushing or a pulling mechanism, leading to change in the sign of the dipolar flow field with respect to the direction of motion.dipole_length (
float
) – This determines the distance of the source of propulsion from the particle’s center.
Notes
This needs the feature
ENGINE
. The keys'mode'
, and'dipole_length'
are only available ifENGINE
is used with LB orCUDA
.Examples
>>> import espressomd >>> system = espressomd.System(box_l=[10, 10, 10]) >>> # Langevin swimmer >>> system.part.add(pos=[1, 0, 0], swimming={'f_swim': 0.03}) >>> # LB swimmer >>> system.part.add(pos=[2, 0, 0], swimming={'f_swim': 0.01, ... 'mode': 'pusher', 'dipole_length': 2.0})
- to_dict(self)¶
Returns the particle’s attributes as a dictionary.
It includes the content of
particle_attributes
, minus a few exceptions:
- torque_lab¶
The particle torque in the lab frame.
torque_lab : (3,) array_like of
float
This property defines the torque of this particle in the fixed frame (or laboratory frame).
Note
The orientation of the particle (
quat
) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.
- type¶
The particle type for nonbonded interactions.
type :
int
Note
The value of
type
has to be an integer >= 0.
- update(self, new_properties)¶
Update properties of a particle.
- Parameters
new_properties (
dict
) – Map particle property names to values. All properties except for the particle id can be changed.
Examples
>>> import espressomd >>> system = espressomd.System(box_l=[10, 10, 10]) >>> p = system.part.add(pos=[1, 2, 3], q=1, virtual=True) >>> print(p.pos, p.q, p.virtual) [1. 2. 3.] 1.0 True >>> p.update({'pos': [4, 5, 6], 'virtual': False, 'q': 0}) >>> print(p.pos, p.q, p.virtual) [4. 5. 6.] 0.0 False
- v¶
The particle velocity in the lab frame.
v : (3,) array_like of
float
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, rel_to)¶
Setup this particle as virtual site relative to the particle in argument
rel_to
. A particle cannot relate to itself.- Parameters
rel_to (
int
orParticleHandle
) – Particle to relate to (either particle id or particle object).
- 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, quaternion)
Note
This needs the feature
VIRTUAL_SITES_RELATIVE
- class espressomd.particle_data.ParticleList¶
Bases:
object
Provides access to the particles.
- add(self, *args, **kwargs)¶
Adds one or several particles to the system
- Parameters
Either a dictionary or a bunch of keyword args.
- Returns
- Return type
Returns an instance of
espressomd.particle_data.ParticleHandle
for each added particle.
Examples
>>> import espressomd >>> system = espressomd.System(box_l=[10, 10, 10]) >>> # 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))
- all(self)¶
Get a slice containing all particles.
- by_id(self, id)¶
Access a particle by its integer id.
- by_ids(self, ids)¶
Get a slice of particles by their integer ids.
- clear(self)¶
Removes all particles.
- exists(self, idx)¶
- highest_particle_id¶
Largest particle id.
- n_part_types¶
Number of particle types.
- n_rigidbonds¶
Number of rigid bonds.
- pairs(self)¶
Generator returns all pairs of particles.
- select(self, *args, **kwargs)¶
Generates a particle slice by filtering particles via a 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
- writevtk(self, fname, types='all')¶
Write the positions and velocities of particles with specified types to a VTK file.
- Parameters
fname (
str
) – Filename of the target output filetypes (list of
int
or the string ‘all’, optional (default: ‘all’)) – A list of particle types which should be output to ‘fname’
Examples
>>> import espressomd >>> system = espressomd.System(box_l=[10, 10, 10]) >>> # add several particles >>> system.part.add(pos=0.5 * system.box_l, v=[1, 0, 0], type=0) >>> system.part.add(pos=0.4 * system.box_l, v=[0, 2, 0], type=1) >>> system.part.add(pos=0.7 * system.box_l, v=[2, 0, 1], type=1) >>> system.part.add(pos=0.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 bonds¶
The bonds stored by this particle. Note that bonds are only stored by one partner. You need to define a bonded interaction.
bonds : list/tuple of tuples/lists
A bond tuple is specified as a bond identifier associated with a particle
(bond_ID, part_ID)
. A single particle may contain multiple such tuples.See also
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¶
The particle director.
The
director
defines the the z-axis in the body-fixed frame. If particle rotations happen, the director, i.e., the body-fixed coordinate system co-rotates. Properties such as the angular velocityespressomd.particle_data.ParticleHandle.omega_body
are evaluated in this body-fixed coordinate system. When using particle dipoles, the dipole moment is co-aligned with the particle director. Setting the director thus modifies the dipole moment orientation (espressomd.particle_data.ParticleHandle.dip
) and vice versa. See also Rotational degrees of freedom and particle anisotropy.director : (3,) array_like of
float
Note
This needs the feature
ROTATION
.
- property exclusions¶
The exclusion list of particles where non-bonded interactions are ignored.
Note
This needs the feature
EXCLUSIONS
.exclusions : (N,) array_like of
int
- property ext_force¶
An additional external force applied to the particle.
ext_force : (3,) array_like of
float
Note
This needs the feature
EXTERNAL_FORCES
.
- property ext_torque¶
An additional external torque is applied to the particle.
ext_torque : (3,) array_like of
float
Note
This torque is specified in the laboratory frame!
This needs features
EXTERNAL_FORCES
andROTATION
.
- property f¶
The instantaneous force acting on this particle.
f : (3,) array_like of
float
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
bool
Fixes the particle in space. By supplying a set of 3 bools as arguments it is possible to fix motion in x, y, or z coordinates independently. For example:
part[<INDEX>].fix = [False, False, True]
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 and Brownian thermostats.
gamma :
float
or (3,) array_like offloat
Note
This needs features
PARTICLE_ANISOTROPY
andTHERMOSTAT_PER_PARTICLE
.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 and Brownian thermostats.
gamma_rot :
float
or (3,) array_like offloat
Note
This needs features
ROTATION
,PARTICLE_ANISOTROPY
andTHERMOSTAT_PER_PARTICLE
.
- 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 lees_edwards_flag¶
The Lees-Edwards flag that indicate if the particle crossed the upper or lower boundary.
- property lees_edwards_offset¶
The accumulated Lees-Edwards offset. Can be used to reconstruct continuous trajectories.
offset : (3,) array_like of
float
- property mass¶
Particle mass.
mass :
float
See also
espressomd.thermostat.Thermostat.set_langevin()
Setting the parameters of the Langevin thermostat
- property mol_id¶
The molecule id of the Particle.
mol_id :
int
The particle
mol_id
is used to differentiate between particles belonging to different molecules, e.g. when virtual sites are used, or object-in-fluid cells. The defaultmol_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
Note
This needs the feature
ROTATION
.If you set the angular velocity of the particle in the lab frame, the orientation of the particle (
quat
) must be set before settingomega_lab
, otherwise the conversion from lab to body frame will not be handled properly.See also
- property pos¶
The unwrapped (not folded into central box) particle position.
pos : (3,) array_like of
float
- property q¶
Particle charge.
q :
float
Note
This needs the feature
ELECTROSTATICS
.
- property quat¶
Quaternion representation of the particle rotational position.
quat : (4,) array_like of
float
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
bool
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 byv_swim
. Alternatively it is possible to achieve a constant velocity by imposing a constant force termf_swim
that is balanced by friction of a (Langevin) thermostat. The way the velocity of the particle decays to the constant terminal velocity in either of these methods is completely determined by the friction coefficient. You may only set one of the possibilitiesv_swim
orf_swim
as you cannot relax to constant force and constant velocity at the same time. Setting bothv_swim
andf_swim
to 0.0 disables swimming. This option applies to all non-lattice-Boltzmann thermostats. Note that there is no real difference betweenv_swim
andf_swim
since the latter may always be chosen such that the same terminal velocity is achieved for a given friction coefficient.- Parameters
f_swim (
float
) – Achieve a constant velocity by imposing a constant force termf_swim
that is balanced by friction of a (Langevin) thermostat. This excludes the optionv_swim
.v_swim (
float
) – Achieve a constant velocity by imposing a constant terminal velocityv_swim
. This excludes the optionf_swim
.mode (
str
, {‘pusher’, ‘puller’, ‘N/A’}) – The LB flow field can be generated by a pushing or a pulling mechanism, leading to change in the sign of the dipolar flow field with respect to the direction of motion.dipole_length (
float
) – This determines the distance of the source of propulsion from the particle’s center.
Notes
This needs the feature
ENGINE
. The keys'mode'
, and'dipole_length'
are only available ifENGINE
is used with LB orCUDA
.Examples
>>> import espressomd >>> system = espressomd.System(box_l=[10, 10, 10]) >>> # Langevin swimmer >>> system.part.add(pos=[1, 0, 0], swimming={'f_swim': 0.03}) >>> # LB swimmer >>> system.part.add(pos=[2, 0, 0], swimming={'f_swim': 0.01, ... 'mode': 'pusher', 'dipole_length': 2.0})
- to_dict(self)¶
Returns the particles attributes as a dictionary.
It can be used to save the particle data and recover it by using
>>> p = system.part.add(...) >>> particle_dict = p.to_dict() >>> system.part.add(particle_dict)
It includes the content of
particle_attributes
, minus a few exceptions:
- property torque_lab¶
The particle torque in the lab frame.
torque_lab : (3,) array_like of
float
This property defines the torque of this particle in the fixed frame (or laboratory frame).
Note
The orientation of the particle (
quat
) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly.
- property type¶
The particle type for nonbonded interactions.
type :
int
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
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, quaternion)
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.linear_polymer_positions(**kwargs)¶
Generates particle positions for polymer creation.
- Parameters
n_polymers (
int
, required) – Number of polymer chainsbeads_per_chain (
int
, required) – Number of monomers per chainbond_length (
float
, required) – distance between adjacent monomers in a chainseed (
int
, required) – Seed for the RNG used to generate the particle positions.bond_angle (
float
, optional) – If set, this parameter defines the angle between adjacent bonds within a polymer.start_positions (array_like
float
.) – If set, this vector defines the start positions for the polymers, i.e., the position of each polymer’s first monomer bead. Here, a numpy array of shape (n_polymers, 3) is expected.min_distance (
float
, optional) – Minimum distance between all generated positions. Defaults to 0respect_constraints (
bool
, optional) – If True, the particle setup tries to obey previously defined constraints. Default value is False.max_tries (
int
, optional) – Maximal number of attempts to generate every monomer position, as well as maximal number of retries per polymer, if choosing suitable monomer positions fails. Default value is 1000. Depending on the total number of beads and constraints, this value needs to be adapted.
- Returns
Three-dimensional numpy array, namely a list of polymers containing the coordinates of the respective monomers.
- Return type
ndarray
- espressomd.polymer.setup_diamond_polymer(system=None, bond=None, MPC=0, dist_cM=1, val_cM=0.0, val_nodes=0.0, start_id='auto', no_bonds=False, type_nodes=0, type_nM=1, type_cM=2)¶
Places particles to form a diamond lattice shaped polymer. Can also assign charges and bonds at the appropriate places.
- Parameters
system (
espressomd.system.System
, required) – System to which the particles will be added.bond (
espressomd.interactions.BondedInteraction
, required ifno_bonds == False
) – The bond to be created between monomers. Should be compatible with the spacingsystem.box_l[0]*(0.25 * sqrt(3))/(MPC + 1)
between monomers.no_bonds (
bool
, optional) – If True, the particles will only be placed in the system but not connected by bonds. In that case, thebond
argument can be omitted. Defaults toFalse
.MPC (
int
, optional) – Monomers per chain, where chain refers to the connection between the 8 lattice nodes of the diamond lattice. Defaults to 0.dist_cM (
int
, optional) – Distance between charged monomers in the chains. Defaults to 1.val_cM (
float
, optional) – Valence of the charged monomers in the chains. Defaults to 0.val_nodes (
float
, optional) – Valence of the node particles. Defaults to 0.start_id (
int
or'auto'
, optional) – Start id for particle creation. Subsequent ids will be contiguous integers. If'auto'
, particle ids will start after the highest id of particles already in the system.type_nodes (
int
, optional) – Type assigned to the node particles. Defaults to 0.type_nM (
int
, optional) – Type assigned to the neutral monomers in the chains. Defaults to 1.type_cM (
int
, optional) – Type assigned to the charged monomers in the chains. Defaults to 2.
- 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_methods module¶
- class espressomd.reaction_methods.ConstantpHEnsemble(**kwargs)[source]¶
Bases:
espressomd.reaction_methods.ReactionAlgorithm
This class implements the constant pH Ensemble.
When adding an acid-base reaction, the acid and base particle types are always assumed to be at index 0 of the lists passed to arguments
reactant_types
andproduct_types
.- constant_pH¶
Constant pH value.
- Type
float
- add_reaction(*args, **kwargs)[source]¶
Sets up a reaction in the forward and backward direction.
- Parameters
gamma (
float
) – Equilibrium constant \(\Gamma\) of the reaction in simulation units (see section Reaction ensemble for its definition).reactant_types (list of
int
) – List of particle types of reactants in the reaction.reactant_coefficients (list of
int
) – List of stoichiometric coefficients of the reactants in the same order as the list of their types.product_types (list of
int
) – List of particle types of products in the reaction.product_coefficients (list of
int
) – List of stoichiometric coefficients of products of the reaction in the same order as the list of their typesdefault_charges (
dict
) – A dictionary of default charges for types that occur in the provided reaction.check_for_electroneutrality (
bool
) – Check for electroneutrality of the given reaction. Default isTrue
.
- class espressomd.reaction_methods.ReactionAlgorithm(**kwargs)[source]¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
This class provides the base class for Reaction Algorithms like the Reaction Ensemble algorithm and the constant pH method. Initialize the reaction algorithm by setting the standard pressure, temperature, and the exclusion range.
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
kT (
float
) – Thermal energy of the system in simulation unitsexclusion_range (
float
) – Minimal distance from any particle, within which new particles will not be inserted.seed (
int
) – Initial counter value (or seed) of the Mersenne Twister RNG.exclusion_radius_per_type (
dict
, optional) – Mapping of particle types to exclusion radii.search_algorithm (
str
) – Pair search algorithm. Default is"order_n"
, which evaluates the distance between the inserted particle and all other particles in the system, which scales with O(N). For MPI-parallel simulations, the"parallel"
method is faster. The"parallel"
method is not recommended for simulations on 1 MPI rank, since it comes with the overhead of a ghost particle update.
- remove_constraint()¶
Remove any previously defined constraint. Requires setting the volume using
set_volume()
.
- set_cylindrical_constraint_in_z_direction()¶
Constrain the reaction moves within a cylinder aligned on the z-axis. 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_wall_constraints_in_z_direction()¶
Restrict the sampling area to a slab in z-direction. Requires setting the volume using
set_volume()
. This constraint is necessary when working with Electrostatic Layer Correction (ELC).- Parameters
slab_start_z (
float
) – z coordinate of the bottom wall.slab_end_z (
float
) – z coordinate of the top wall.
Examples
>>> import espressomd >>> import espressomd.shapes >>> import espressomd.electrostatics >>> import espressomd.reaction_methods >>> import numpy as np >>> # setup a charged system >>> box_l = 20 >>> elc_gap = 10 >>> system = espressomd.System(box_l=[box_l, box_l, box_l + elc_gap]) >>> system.time_step = 0.001 >>> system.cell_system.skin = 0.4 >>> types = {"HA": 0, "A-": 1, "H+": 2, "wall": 3} >>> charges = {types["HA"]: 0, types["A-"]: -1, types["H+"]: +1} >>> for i in range(10): ... system.part.add(pos=np.random.random(3) * box_l, type=types["A-"], q=charges[types["A-"]]) ... system.part.add(pos=np.random.random(3) * box_l, type=types["H+"], q=charges[types["H+"]]) >>> for particle_type in charges.keys(): ... system.non_bonded_inter[particle_type, types["wall"]].wca.set_params(epsilon=1.0, sigma=1.0) >>> # add ELC actor >>> p3m = espressomd.electrostatics.P3M(prefactor=1.0, accuracy=1e-2) >>> elc = espressomd.electrostatics.ELC(actor=p3m, maxPWerror=1.0, gap_size=elc_gap) >>> system.actors.add(elc) >>> # add constant pH method >>> RE = espressomd.reaction_methods.ConstantpHEnsemble(kT=1, exclusion_range=1, seed=77) >>> RE.constant_pH = 2 >>> RE.add_reaction(gamma=0.0088, reactant_types=[types["HA"]], ... product_types=[types["A-"], types["H+"]], ... default_charges=charges) >>> # add walls for the ELC gap >>> RE.set_wall_constraints_in_z_direction(0, box_l) >>> RE.set_volume(box_l**3) >>> system.constraints.add(shape=espressomd.shapes.Wall(dist=0, normal=[0, 0, 1]), ... particle_type=types["wall"]) >>> system.constraints.add(shape=espressomd.shapes.Wall(dist=-box_l, normal=[0, 0, -1]), ... particle_type=types["wall"])
- get_wall_constraints_in_z_direction()¶
Returns the restrictions of the sampling area in z-direction.
- set_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.
- Parameters
volume (
float
) – Volume of the system in simulation units
- get_volume()¶
Get the volume to be used in the acceptance probability of the reaction ensemble.
- get_acceptance_rate_configurational_moves():
Returns the acceptance rate for the configuration moves.
- get_acceptance_rate_reaction()¶
Returns the acceptance rate for the given reaction.
- Parameters
reaction_id (
int
) – Reaction id
- set_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, or if you need improved performance, as the default value of 100 causes some overhead. 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.
- Parameters
type (
int
) – Particle type for the hidden particles
- get_non_interacting_type()¶
Returns the type which is used for hiding particle
- reaction()¶
Performs randomly selected reactions.
- Parameters
reaction_steps (
int
, optional) – The number of reactions to be performed at once, defaults to 1.
- displacement_mc_move_for_particles_of_type()¶
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 movedparticle_number_to_be_changed (
int
) – Number of particles to move, defaults to 1.
- Returns
Whether the move was accepted.
- Return type
bool
- delete_particle()¶
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.
- Parameters
p_id (
int
) – Id of the particle to be deleted.
- change_reaction_constant()¶
Changes the reaction constant of a given reaction (for both the forward and backward reactions). The
reaction_id
which is assigned to a reaction depends on the order in whichadd_reaction()
was called. The 0th reaction hasreaction_id=0
, the next added reaction needs to be addressed withreaction_id=1
, etc.- Parameters
reaction_id (
int
) – Reaction idgamma (
float
) – New reaction constant
- delete_reaction()¶
Delete a reaction from the set of used reactions (the forward and backward reaction). The
reaction_id
which is assigned to a reaction depends on the order in whichadd_reaction()
was called. The 0th reaction hasreaction_id=0
, the next added reaction needs to be addressed withreaction_id=1
, etc. After the deletion of a reaction subsequent reactions take thereaction_id
of the deleted reaction.- Parameters
reaction_id (
int
) – Reaction id
- add_reaction(**kwargs)[source]¶
Sets up a reaction in the forward and backward direction.
- Parameters
gamma (
float
) – Equilibrium constant \(\Gamma\) of the reaction in simulation units (see section Reaction ensemble for its definition).reactant_types (list of
int
) – List of particle types of reactants in the reaction.reactant_coefficients (list of
int
) – List of stoichiometric coefficients of the reactants in the same order as the list of their types.product_types (list of
int
) – List of particle types of products in the reaction.product_coefficients (list of
int
) – List of stoichiometric coefficients of products of the reaction in the same order as the list of their typesdefault_charges (
dict
) – A dictionary of default charges for types that occur in the provided reaction.check_for_electroneutrality (
bool
) – Check for electroneutrality of the given reaction. Default isTrue
.
- class espressomd.reaction_methods.ReactionEnsemble(**kwargs)[source]¶
Bases:
espressomd.reaction_methods.ReactionAlgorithm
This class implements the Reaction Ensemble.
- class espressomd.reaction_methods.WidomInsertion(**kwargs)[source]¶
Bases:
espressomd.reaction_methods.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.
- add_reaction(**kwargs)[source]¶
Sets up a reaction in the forward and backward direction.
- Parameters
gamma (
float
) – Equilibrium constant \(\Gamma\) of the reaction in simulation units (see section Reaction ensemble for its definition).reactant_types (list of
int
) – List of particle types of reactants in the reaction.reactant_coefficients (list of
int
) – List of stoichiometric coefficients of the reactants in the same order as the list of their types.product_types (list of
int
) – List of particle types of products in the reaction.product_coefficients (list of
int
) – List of stoichiometric coefficients of products of the reaction in the same order as the list of their typesdefault_charges (
dict
) – A dictionary of default charges for types that occur in the provided reaction.check_for_electroneutrality (
bool
) – Check for electroneutrality of the given reaction. Default isTrue
.
- calculate_excess_chemical_potential(**kwargs)[source]¶
Given a set of samples of the particle insertion potential energy, calculates the excess chemical potential and its statistical error.
- Parameters
particle_insertion_potential_energy_samples (array_like of
float
) – Samples of the particle insertion potential energy.N_blocks (
int
, optional) – Number of bins for binning analysis.
- Returns
mean (
float
) – Mean excess chemical potential.error (
float
) – Standard error of the mean.
- calculate_particle_insertion_potential_energy(**kwargs)[source]¶
Measures the potential energy when particles are inserted in the system following the reaction provided in
reaction_id
. Please define the insertion moves first by calling the methodadd_reaction()
(with only product types specified).Note that although this function does not provide directly the chemical potential, it can be used to calculate it. For an example of such an application please check
/samples/widom_insertion.py
.- Parameters
reaction_id (
int
) – Reaction identifier.
espressomd.rotation module¶
- espressomd.rotation.diagonalized_inertia_tensor(positions, masses)[source]¶
Calculate the diagonalized inertia tensor with respect to the center of mass for given point masses at given positions.
- Parameters
positions ((N,3) array_like of
float
) – Positions of the masses.masses ((N,) array_like of
float
)
- Returns
(3,) array_like of
float
– Principal moments of inertia.(3,3) array_like of
float
– Principal axes of inertia. Note that the second axis is the coordinate axis (same as input).
- espressomd.rotation.inertia_tensor(positions, masses)[source]¶
Calculate the inertia tensor for given point masses at given positions.
- Parameters
positions ((N,3) array_like of
float
) – Point masses’ positions.masses ((N,) array_like of
float
)
- Returns
Moment of inertia tensor.
- Return type
(3,3) array_like of
float
Notes
See wikipedia.
- espressomd.rotation.matrix_to_quat(m)[source]¶
Convert the (proper) rotation matrix to the corresponding quaternion representation based on pyquaternion.
- Parameters
m ((3,3) array_like of
float
) – Rotation matrix.- Returns
Quaternion representation of the rotation.
- Return type
array_like of
float
- Raises
ValueError – If the matrix does not a correspond to a proper rotation (det(m) != 1).
espressomd.script_interface module¶
- class espressomd.script_interface.PScriptInterface(name=None, policy='GLOBAL', sip=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
sip (
PObjectRef
) – Object id of an existing core object (method 1).name (
str
) – Name of the core class to instantiate (method 2).**kwargs – Parameters for the core class constructor (method 2).
policy (
str
, {‘GLOBAL’, ‘LOCAL’}) – Creation policy. The managed object exists either on all MPI nodes with ‘GLOBAL’ (default), or only on the head node with ‘LOCAL’.
- sip¶
Pointer to a ScriptInterface object in the core.
- Type
- 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)¶
- get_sip(self)¶
Get pointer to the core object.
- name(self)¶
Return name of the core class.
- set_params(self, **kwargs)¶
- class espressomd.script_interface.ScriptInterfaceHelper(**kwargs)¶
Bases:
espressomd.script_interface.PScriptInterface
- define_bound_methods(self)¶
- generate_caller(self, method_name)¶
- class espressomd.script_interface.ScriptObjectList(*args, **kwargs)¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Base class for container-like classes such as
Constraints
andLBBoundaries
. Derived classes must implement anadd()
method which adds a single item to the container.The core objects must be managed by a container derived from
ScriptInterface::ObjectList
.
- class espressomd.script_interface.ScriptObjectMap(*args, **kwargs)¶
Bases:
espressomd.script_interface.ScriptInterfaceHelper
Base class for container-like classes such as
BondedInteractions
. Derived classes must implement anadd()
method which adds a single item to the container.The core objects must be managed by a container derived from
ScriptInterface::ObjectMap
.- clear(self)¶
Remove all elements.
- items(self)¶
- keys(self)¶
- remove(self, key)¶
Remove the element with the given key. This is a no-op if the key does not exist.
- espressomd.script_interface.script_interface_register(c)¶
Decorator used to register script interface classes. This will store a name<->class relationship in a registry, so that parameters of type object can be instantiated as the correct python class.
espressomd.shapes module¶
- class espressomd.shapes.Cylinder(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A cylinder shape.
- center¶
Coordinates of the center of the cylinder.
- Type
(3,) array_like of
float
- axis¶
Axis of the cylinder.
- Type
(3,) array_like of
float
- radius¶
Radius of the cylinder.
- Type
float
- length¶
Length of the cylinder.
- Type
float
- direction¶
Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.
- Type
int
- open¶
cylinder is open or has caps.
- Type
bool
- class espressomd.shapes.Ellipsoid(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
An ellipsoid.
For now only ellipsoids of revolution are supported. The symmetry axis is aligned parallel to the 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.HollowConicalFrustum(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
Hollow conical frustum shape.
- cyl_transform_params¶
Parameters of the spacial orientation of the frustum. Contained must be parameters for
center
andaxis
.orientation
has no effect, unlesscentral_angle != 0
- r1¶
Radius r1.
- Type
float
- r2¶
Radius r2.
- Type
float
- length¶
Length of the conical frustum along
axis
.- Type
float
- thickness¶
The thickness of the frustum. Also determines the rounding radius of the edges
- Type
float
- direction¶
Surface orientation, for +1 the normal points out of the mantel, for -1 it points inside of the shape. Defaults to 1
- Type
int
, optional
- central_angle¶
A
central_angle
creates an opening in the frustum along the side, centered symmetrically around thedirection
ofcyl_transform_params
. Must be between0
and2 pi
. Defaults to 0.- Type
float
, optional
- class espressomd.shapes.Rhomboid(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A parallelepiped.
- a¶
First base vector.
- Type
(3,) array_like of
float
- b¶
Second base vector.
- Type
(3,) array_like of
float
- c¶
Third base vector.
- Type
(3,) array_like of
float
- corner¶
Lower left corner of the rhomboid.
- Type
(3,) array_like of
float
- direction¶
Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.
- Type
int
- class espressomd.shapes.SimplePore(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
Two parallel infinite planes, and a cylindrical channel connecting them. The cylinder and the planes are connected by torus segments with an adjustable radius.
- radius¶
The radius of the pore.
- Type
float
- length¶
The distance between the planes.
- Type
float
- smoothing_radius¶
Radius of the torus segments
- Type
float
- axis¶
Axis of the cylinder and normal of the planes
- Type
(3,) array_like of
float
- center¶
Position of the center of the cylinder.
- Type
(3,) array_like of
float
- class espressomd.shapes.Slitpore(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
- channel_width¶
- Type
float
- lower_smoothing_radius¶
- Type
float
- pore_length¶
- Type
float
- pore_mouth¶
- Type
float
- pore_width¶
- Type
float
- upper_smoothing_radius¶
- Type
float
- dividing_plane¶
- Type
float
- class espressomd.shapes.Sphere(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A sphere.
- center¶
Center of the sphere
- Type
(3,) array_like of
float
- radius¶
Radius of the sphere.
- Type
float
- direction¶
Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.
- Type
int
- class espressomd.shapes.SpheroCylinder(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A cylinder with hemispheres as caps.
- center¶
Coordinates of the center of the cylinder.
- Type
(3,) array_like of
float
- axis¶
Axis of the cylinder.
- Type
(3,) array_like of
float
- radius¶
Radius of the cylinder.
- Type
float
- direction¶
Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.
- Type
int
- length¶
Length of the cylinder (not including the caps).
- Type
float
- class espressomd.shapes.Torus(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
A torus shape.
- center¶
Coordinates of the center of the torus.
- Type
(3,) array_like of
float
- normal¶
Normal axis of the torus.
- Type
(3,) array_like of
float
- radius¶
Radius of the torus.
- Type
float
- tube_radius¶
Radius of the tube.
- Type
float
- direction¶
Surface orientation, for +1 the normal points out of the mantel, for -1 it points inward.
- Type
int
- class espressomd.shapes.Union(*args, **kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptObjectList
A union of shapes.
This shape represents a union of shapes where the distance to the union is defined by the smallest distance to any shape contained in the union.
- size()¶
Number of shapes contained in the union.
- clear()¶
Remove all shapes from the union.
- add(shape)[source]¶
Add a shape to the union.
- Parameters
shape (array_like / instance of
espressomd.shapes.Shape
) – Shape instance(s) to be added to the union.
- remove(shape)[source]¶
Remove a shape from the union.
- Parameters
shape (array_like / instance of
espressomd.shapes.Shape
) – Shape instance(s) to be removed from the union.
- class espressomd.shapes.Wall(**kwargs)[source]¶
Bases:
espressomd.shapes.Shape
,espressomd.script_interface.ScriptInterfaceHelper
An infinite plane.
- dist¶
Distance from the origin.
- Type
float
- normal¶
Normal vector of the plane (needs not to be length 1).
- Type
(3,) array_like of
int
espressomd.system module¶
- class espressomd.system.System(**kwargs)¶
Bases:
object
The ESPResSo system class.
Note
every attribute has to be declared at the class level. This means that methods cannot define an attribute by using
self.new_attr = somevalue
without declaring it inside this indentation level, either as method, property or reference.- actors¶
object
espressomd.actors.Actors
- Type
actors
- analysis¶
object
espressomd.analyze.Analysis
- Type
analysis
- auto_exclusions(self, distance)¶
Automatically adds exclusions between particles that are bonded.
This only considers pair bonds.
Requires feature
EXCLUSIONS
.- Parameters
distance (
int
) – Bond distance upto which the exclusions should be added.
- auto_update_accumulators¶
object
espressomd.accumulators.AutoUpdateAccumulators
- Type
auto_update_accumulators
- bond_breakage¶
object
espressomd.bond_breakage.BreakageSpecs
- Type
bond_breakage
- bonded_inter¶
object
espressomd.interactions.BondedInteractions
- Type
bonded_inter
- box_l¶
(3,) array_like of
float
: Dimensions of the simulation box
- cell_system¶
object
espressomd.cell_system.CellSystem
- Type
cell_system
- change_volume_and_rescale_particles(self, d_new, dir='xyz')¶
Change box size and rescale particle coordinates.
- Parameters
d_new (
float
) – New box lengthdir (
str
, optional) – Coordinate to work on,"x"
,"y"
,"z"
or"xyz"
for isotropic. Isotropic assumes a cubic box.
- collision_detection¶
object
espressomd.collision_detection.CollisionDetection
- Type
collision_detection
- comfixed¶
object
espressomd.comfixed.ComFixed
- Type
comfixed
- constraints¶
object
espressomd.constraints.Constraints
- Type
constraints
- cuda_init_handle¶
object
espressomd.cuda_init.CudaInitHandle
- Type
cuda_init_handle
- distance(self, p1, p2)¶
Return the scalar distance between particles, between a particle and a point or between two points, respecting periodic boundaries.
- Parameters
p1 (
ParticleHandle
or (3,) array offloat
) – First particle or position.p2 (
ParticleHandle
or (3,) array offloat
) – Second particle or position.
- distance_vec(self, p1, p2)¶
Return the distance vector between particles, between a particle and a point or between two points, respecting periodic boundaries.
- Parameters
p1 (
ParticleHandle
or (3,) array offloat
) – First particle or position.p2 (
ParticleHandle
or (3,) array offloat
) – Second particle or position.
- ekboundaries¶
object
espressomd.ekboundaries.EKBoundaries
- Type
ekboundaries
- force_cap¶
float
: If > 0, the magnitude of the force on the particles are capped to this value.
- galilei¶
object
espressomd.galilei.GalileiTransform
- Type
galilei
- integrator¶
object
espressomd.integrate.IntegratorHandle
- Type
integrator
- lbboundaries¶
object
espressomd.lbboundaries.LBBoundaries
- Type
lbboundaries
- lees_edwards¶
object
espressomd.lees_edwards.LeesEdwards
- Type
lees_edwards
- max_cut_bonded¶
- max_cut_nonbonded¶
- max_oif_objects¶
Maximum number of objects as per the object_in_fluid method.
- min_global_cut¶
- non_bonded_inter¶
object
espressomd.interactions.NonBondedInteractions
- Type
non_bonded_inter
- number_of_particles(self, type=None)¶
- Parameters
type (
int
(type
)) – Particle type to count the number for.- Returns
The number of particles which have the given type.
- Return type
int
- Raises
RuntimeError – If the particle
type
is not currently tracked by the system. To select which particle types are tracked, callsetup_type_map()
.
- part¶
object
espressomd.particle_data.ParticleList
- Type
part
- periodicity¶
(3,) array_like of
bool
: System periodicity in[x, y, z]
,False
for no periodicity in this direction,True
for periodicity
- 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
- setup_type_map(self, type_list=None)¶
For using ESPResSo conveniently for simulations in the grand canonical ensemble, or other purposes, when particles of certain types are created and deleted frequently. Particle ids can be stored in lists for each individual type and so random ids of particles of a certain type can be drawn. If you want ESPResSo to keep track of particle ids of a certain type you have to initialize the method by calling the setup function. After that ESPResSo will keep track of particle ids of that type.
- thermostat¶
object
espressomd.thermostat.Thermostat
- Type
thermostat
- time¶
Set the time in the simulation.
- time_step¶
Set the time step for the integrator.
- velocity_difference(self, p1, p2)¶
Return the velocity difference between two particles, considering Lees-Edwards boundary conditions, if active.
- Parameters
p1 (
ParticleHandle
)p2 (
ParticleHandle
)
- virtual_sites¶
Set the virtual site implementation.
Requires feature
VIRTUAL_SITES
.
- volume(self)¶
Return box volume of the cuboid box.
espressomd.thermostat module¶
- espressomd.thermostat.AssertThermostatType(*allowedthermostats)¶
Assert that only a certain group of thermostats is active at a time.
Decorator class to ensure that only specific combinations of thermostats can be activated together by the user. Usage:
cdef class Thermostat: @AssertThermostatType(THERMO_LANGEVIN, THERMO_DPD) def set_langevin(self, kT=None, gamma=None, gamma_rotation=None, act_on_virtual=False, seed=None): ...
This will prefix an assertion that prevents setting up the Langevin thermostat if the list of active thermostats contains anything other than the DPD and Langevin thermostats.
- Parameters
allowedthermostats (
str
) – Allowed list of thermostats which are known to be compatible with one another.
- class espressomd.thermostat.Thermostat¶
Bases:
object
- get_state(self)¶
Returns the thermostat status.
- get_ts(self)¶
- recover(self)¶
Recover a suspended thermostat
If the thermostat had been suspended using
suspend()
, it can be recovered with this method.
- set_brownian(self, kT, gamma, gamma_rotation=None, act_on_virtual=False, seed=None)¶
Sets the Brownian thermostat.
- Parameters
kT (
float
) – Thermal energy of the simulated heat bath.gamma (
float
) – Contains the friction coefficient of the bath. If the featurePART