Mechanica Library Python API Reference 

Returns

MxParticleHandle*

Overload 2:

Particle constructor.

Automatically updates when running on a CUDA device.

Parameters

str (string) – JSON string
clusterId (int) – id of parent cluster, optional

Return type

Returns

MxParticleHandle*

factory(nr_parts=0, positions=None, velocities=None, cluster_ids=None)

newType(_name: char const *) → MxParticleType *

Particle type constructor.

New type is constructed from the definition of the calling type.

Parameters: _name (string) – name of the new type
Return type: MxParticleType
Returns: MxParticleType*

registerType() → HRESULT

Registers a type with the engine.

Note that this occurs automatically, unless noReg==true in constructor.

Return type: int
Returns: HRESULT

on_register() → void: A callback for when a type is registered

isRegistered() → bool

Tests whether this type is registered

Return type: boolean
Returns: true if registered

get() → MxParticleType *

Get the type engine instance

Return type: MxParticleType
Returns: MxParticleType*

items() → MxParticleList *

Get all particles of this type.

Return type: MxParticleList
Returns: MxParticleList*

isCluster() → bool

to_cluster() → MxClusterParticleType *: Limits casting to cluster by type

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxParticleType *

Create from a JSON string representation.

The returned type is automatically registered with the engine.

Parameters: str (string) –
Return type: MxParticleType
Returns: MxParticleType*

__reduce__(): Helper for pickle.

mechanica.Cluster: alias of MxCluster

mechanica.ClusterHandle: alias of MxClusterParticleHandle

class mechanica.MxCluster

Bases: MxParticle

The cluster analogue to MxParticle.

class mechanica.MxClusterParticleHandle(*args)

Bases: MxParticleHandle

The cluster analogue to MxParticleHandle.

These are special in that they can create particles of their constituent particle types, much like a MxParticleType.

property radius_of_gyration: Radius of gyration

property center_of_mass: Center of mass

property centroid: Centroid

property moment_of_inertia: Moment of inertia

items = <function MxClusterParticleHandle.items>

__call__(particle_type, *args, **kwargs)

Call self as a function.

Alias of _call

_call(*args) → MxParticleHandle *

Overload 1:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters

partType (MxParticleType) – type of particle to create
position (MxVector3f) – position of new particle, optional
velocity (MxVector3f) – velocity of new particle, optional

Return type

Returns

MxParticleHandle*

Overload 2:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters

partType (MxParticleType) – type of particle to create
str (string) – JSON string

Return type

Returns

MxParticleHandle*

cluster() → MxCluster *

Gets the actual cluster of this handle.

Return type: MxCluster
Returns: MxParticle*

split(axis: MxVector3f = None, random: bool * = None, time: float * = None, normal: MxVector3f = None, point: MxVector3f = None) → MxParticleHandle *

Split the cluster.

Parameters

axis (MxVector3f) – axis of split, optional
random (boolean) – divide by randomly and evenly allocating constituent particles, optional
time (float) – time at which to implement the split; currently not supported
normal (MxVector3f) – normal vector of cleavage plane, optional
point (MxVector3f) – point on cleavage plane, optional

Return type

Returns

MxParticleHandle*

class mechanica.ClusterType

Bases: ParticleType

Interface for class-centric design of MxClusterParticleType

types = None: List of constituent types of the cluster, if any

class mechanica.MxClusterParticleType(noReg: bool const & = False)

Bases: MxParticleType

The cluster analogue to MxParticleType.

types: list of particle types that belong to this type.

hasType(type: MxParticleType) → bool

Tests where this cluster has a particle type

Parameters: type (MxParticleType) – type to test
Return type: boolean
Returns: true if this cluster has the type

get() → MxClusterParticleType *

Get the type engine instance

Return type: MxClusterParticleType
Returns: MxClusterParticleType*

ParticleList and ParticleTypeList

mechanica.ParticleList: alias of MxParticleList

class mechanica.MxParticleList(*args)

A special list with convenience methods for working with sets of particles.

property virial: Virial tensor of particles in list

property radius_of_gyration: Radius of gyration of particles in list

property center_of_mass: Center of mass of particles in list

property centroid: Centroid of particles in list

property moment_of_inertia: Moment of inertia of particles in list

property positions: Position of each particle in list

property velocities: Velocity of each particle in list

property forces: Net forces acting on each particle in list

__len__() → int

__getitem__(i: int)

reserve(_nr_parts: size_t) → HRESULT

Reserve enough storage for a given number of items.

Parameters: _nr_parts (int) – number of items
Return type: int
Returns: HRESULT

insert(*args) → uint16_t

Inserts the given particle into the list, returns the index of the item.

Parameters: particle (MxParticleHandle) – particle to insert
Return type: int
Returns: uint16_t

remove(id: int32_t) → uint16_t

looks for the item with the given id and deletes it form the list

Parameters: id (int) – id to remove
Return type: int
Returns: uint16_t

extend(other: MxParticleList) → void

inserts the contents of another list

Parameters: other (MxParticleList) – another list

item(i: int32_t const &) → MxParticleHandle *

looks for the item at the given index and returns it if found, otherwise returns NULL

Parameters: i (int) – index of lookup
Return type: MxParticleHandle
Returns: MxParticleHandle*

static all() → MxParticleList *

returns an instance populated with all current particles

Return type: MxParticleList
Returns: MxParticleList*

sphericalPositions(origin: MxVector3f = None) → std::vector< MxVector3f,std::allocator< MxVector3f > >

Get the spherical coordinates of each particle

Parameters: origin (MxVector3f) – optional origin of coordinates; default is center of universe
Return type: std::vector< MxVector3f,std::allocator< MxVector3f > >
Returns: std::vector<MxVector3f>

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxParticleList *

Create from a JSON string representation

Parameters: str (string) –
Return type: MxParticleList
Returns: MxParticleList*

__reduce__(): Helper for pickle.

mechanica.ParticleTypeList: alias of MxParticleTypeList

class mechanica.MxParticleTypeList(*args)

A special list with convenience methods for working with sets of particle types.

property virial: Virial tensor of particles corresponding to all types in list

property radius_of_gyration: Radius of gyration of particles corresponding to all types in list

property center_of_mass: Center of mass of particles corresponding to all types in list

property centroid: Centroid of particles corresponding to all types in list

property moment_of_inertia: Moment of inertia of particles corresponding to all types in list

property positions: Position of each particle corresponding to all types in list

property velocities: Velocity of each particle corresponding to all types in list

property forces: Total net force acting on each particle corresponding to all types in list

__len__() → int

__getitem__(i: int)

reserve(_nr_parts: size_t) → HRESULT

Reserve enough storage for a given number of items.

Parameters: _nr_parts (int) – number of items
Return type: int
Returns: HRESULT

insert(*args) → uint16_t

Inserts the given particle type into the list, returns the index of the item.

Parameters: ptype (MxParticleType) –
Return type: int
Returns: uint16_t

remove(id: int32_t) → uint16_t

looks for the item with the given id and deletes it form the list

Parameters: id (int) – id to remove
Return type: int
Returns: uint16_t

extend(other: MxParticleTypeList) → void

inserts the contents of another list

Parameters: other (MxParticleTypeList) – another list

item(i: int32_t const &) → MxParticleType *

looks for the item at the given index and returns it if found, otherwise returns NULL

Parameters: i (int) – index of lookup
Return type: MxParticleType
Returns: MxParticleType*

static all() → MxParticleTypeList *

returns an instance populated with all current particle types

Return type: MxParticleTypeList
Returns: MxParticleTypeList*

sphericalPositions(origin: MxVector3f = None) → std::vector< MxVector3f,std::allocator< MxVector3f > >

Get the spherical coordinates of each particle

Parameters: origin (MxVector3f) – optional origin of coordinates; default is center of universe
Return type: std::vector< MxVector3f,std::allocator< MxVector3f > >
Returns: std::vector<MxVector3f>

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxParticleTypeList *

Create from a JSON string representation

Parameters: str (string) –
Return type: MxParticleTypeList
Returns: MxParticleTypeList*

__reduce__(): Helper for pickle.

Potentials

mechanica.Potential: alias of MxPotentialPy

class mechanica.MxPotential

A Potential object is a compiled interpolation of a given function. The Universe applies potentials to particles to calculate the net force on them.

For performance reasons, Mechanica implements potentials as interpolations, which can be much faster than evaluating the function directly.

A potential can be treated just like any callable object.

property min: float: Minimum distance of evaluation

property max: float: Maximum distance of evaluation

property cutoff: float: Cutoff distance

property domain: (<class 'float'>, <class 'float'>): Evaluation domain

property intervals: int: Evaluation intervals

property bound: bool: Bound flag

property r0: float: Potential r0 value

property shifted: bool: Shifted flag

property periodic: bool: Periodic flag

property r_square: bool: Potential r2 value

__call__(): Alias of _call

_call(*args) → float

plot(s=None, force=True, potential=False, show=True, ymin=None, ymax=None, *args, **kwargs): Potential plot function

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxPotential *

Create from a JSON string representation

Parameters: str (string) –
Return type: MxPotential
Returns: MxPotential*

__reduce__(): Helper for pickle.

static lennard_jones_12_6(min: double, max: double, A: double, B: double, tol: double * = None) → MxPotential *

Creates a 12-6 Lennard-Jones potential.

The Lennard Jones potential has the form:

\[\left( \frac{A}{r^{12}} - \frac{B}{r^6} \right)\]

Parameters

min (float) – The smallest radius for which the potential will be constructed.
max (float) – The largest radius for which the potential will be constructed.
A (float) – The first parameter of the Lennard-Jones potential.
B (float) – The second parameter of the Lennard-Jones potential.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).

Return type

Returns

MxPotential*

static lennard_jones_12_6_coulomb(min: double, max: double, A: double, B: double, q: double, tol: double * = None) → MxPotential *

Creates a potential of the sum of a 12-6 Lennard-Jones potential and a shifted Coulomb potential.

The 12-6 Lennard Jones - Coulomb potential has the form:

\[\left( \frac{A}{r^{12}} - \frac{B}{r^6} \right) + q \left( \frac{1}{r} - \frac{1}{max} \right)\]

Parameters

min (float) – The smallest radius for which the potential will be constructed.
max (float) – The largest radius for which the potential will be constructed.
A (float) – The first parameter of the Lennard-Jones potential.
B (float) – The second parameter of the Lennard-Jones potential.
q (float) – The charge scaling of the potential.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).

Return type

Returns

MxPotential*

static ewald(min: double, max: double, q: double, kappa: double, tol: double * = None, periodicOrder: unsigned int * = None) → MxPotential *

Creates a real-space Ewald potential.

The Ewald potential has the form:

\[q \frac{\mathrm{erfc}\, ( \kappa r)}{r}\]

Parameters

min (float) – The smallest radius for which the potential will be constructed.
max (float) – The largest radius for which the potential will be constructed.
q (float) – The charge scaling of the potential.
kappa (float) – The screening distance of the Ewald potential.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).
periodicOrder (int) – Order of lattice periodicity along all periodic dimensions. Defaults to 0.

Return type

Returns

MxPotential*

static coulomb(q: double, min: double * = None, max: double * = None, tol: double * = None, periodicOrder: unsigned int * = None) → MxPotential *

Creates a Coulomb potential.

The Coulomb potential has the form:

\[\frac{q}{r}\]

Parameters

q (float) – The charge scaling of the potential.
min (float) – The smallest radius for which the potential will be constructed. Default is 0.01.
max (float) – The largest radius for which the potential will be constructed. Default is 2.0.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).
periodicOrder (int) – Order of lattice periodicity along all periodic dimensions. Defaults to 0.

Return type

Returns

MxPotential*

static coulombR(q: double, kappa: double, min: double, max: double, modes: unsigned int * = None) → MxPotential *

Creates a Coulomb reciprocal potential.

The Coulomb reciprocal potential has the form:

\[\frac{\pi q}{V} \sum_{||\mathbf{m}|| \neq 0} \frac{1}{||\mathbf{m}||^2} \exp \left( \left( i \mathbf{r}_{jk} - \left( \frac{\pi}{\kappa} \right)^{2} \mathbf{m} \right) \cdot \mathbf{m} \right)\]

Here \(V\) is the volume of the domain and \(\mathbf{m}\) is a reciprocal vector of the domain.

Parameters

q (float) – Charge scaling of the potential.
kappa (float) – Screening distance.
min (float) – Smallest radius for which the potential will be constructed.
max (float) – Largest radius for which the potential will be constructed.
modes (int) – Number of Fourier modes along each periodic dimension. Default is 1.

Return type

Returns

MxPotential*

static harmonic(k: double, r0: double, min: double * = None, max: double * = None, tol: double * = None) → MxPotential *

Creates a harmonic bond potential.

The harmonic potential has the form:

\[k \left( r-r_0 \right)^2\]

Parameters

k (float) – The energy of the bond.
r0 (float) – The bond rest length.
min (float) – The smallest radius for which the potential will be constructed. Defaults to \(r_0 - r_0 / 2\).
max (float) – The largest radius for which the potential will be constructed. Defaults to \(r_0 + r_0 /2\).
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to \(0.01 \abs(max-min)\).

Return type

Returns

MxPotential*

static linear(k: double, min: double * = None, max: double * = None, tol: double * = None) → MxPotential *

Creates a linear potential.

The linear potential has the form:

\[k r\]

Parameters

k (float) – interaction strength; represents the potential energy peak value.
min (float) – The smallest radius for which the potential will be constructed. Defaults to 0.0.
max (float) – The largest radius for which the potential will be constructed. Defaults to 10.0.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001.

Return type

Returns

MxPotential*

static harmonic_angle(k: double, theta0: double, min: double * = None, max: double * = None, tol: double * = None) → MxPotential *

Creates a harmonic angle potential.

The harmonic angle potential has the form:

\[k \left(\theta-\theta_{0} \right)^2\]

Parameters

k (float) – The energy of the angle.
theta0 (float) – The minimum energy angle.
min (float) – The smallest angle for which the potential will be constructed. Defaults to zero.
max (float) – The largest angle for which the potential will be constructed. Defaults to PI.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.005 * (max - min).

Return type

Returns

MxPotential*

static harmonic_dihedral(k: double, delta: double, min: double * = None, max: double * = None, tol: double * = None) → MxPotential *

Creates a harmonic dihedral potential.

The harmonic dihedral potential has the form:

\[k \left( \theta - \delta \right) ^2\]

Parameters

k (float) – energy of the dihedral.
delta (float) – minimum energy dihedral.
min (float) – The smallest angle for which the potential will be constructed. Defaults to zero.
max (float) – The largest angle for which the potential will be constructed. Defaults to PI.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.005 * (max - min).

Return type

Returns

MxPotential*

static cosine_dihedral(k: double, n: int, delta: double, tol: double * = None) → MxPotential *

Creates a cosine dihedral potential.

The cosine dihedral potential has the form:

\[k \left( 1 + \cos( n \theta-\delta ) \right)\]

Parameters

k (float) – energy of the dihedral.
n (int) – multiplicity of the dihedral.
delta (float) – minimum energy dihedral.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.01.

Return type

Returns

MxPotential*

static well(k: double, n: double, r0: double, min: double * = None, max: double * = None, tol: double * = None) → MxPotential *

Creates a well potential.

Useful for binding a particle to a region.

The well potential has the form:

\[\frac{k}{\left(r_0 - r\right)^{n}}\]

Parameters

k (float) – potential prefactor constant, should be decreased for larger n.
n (float) – exponent of the potential, larger n makes a sharper potential.
r0 (float) – The extents of the potential, length units. Represents the maximum extents that a two objects connected with this potential should come apart.
min (float) – The smallest radius for which the potential will be constructed. Defaults to zero.
max (float) – The largest radius for which the potential will be constructed. Defaults to r0.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.01 * abs(min-max).

Return type

Returns

MxPotential*

static glj(e: double, m: double * = None, n: double * = None, k: double * = None, r0: double * = None, min: double * = None, max: double * = None, tol: double * = None, shifted: bool * = None) → MxPotential *

Creates a generalized Lennard-Jones potential.

The generalized Lennard-Jones potential has the form:

\[\frac{\epsilon}{n-m} \left[ m \left( \frac{r_0}{r} \right)^n - n \left( \frac{r_0}{r} \right)^m \right]\]

Parameters

e (float) – effective energy of the potential.
m (float) – order of potential. Defaults to 3
n (float) – order of potential. Defaults to 2*m.
k (float) – mimumum of the potential. Defaults to 1.
r0 (float) – mimumum of the potential. Defaults to 1.
min (float) – The smallest radius for which the potential will be constructed. Defaults to 0.05 * r0.
max (float) – The largest radius for which the potential will be constructed. Defaults to 5 * r0.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.01.
shifted (boolean) – Flag for whether using a shifted potential. Defaults to true.

Return type

Returns

MxPotential*

static morse(d: double * = None, a: double * = None, r0: double * = None, min: double * = None, max: double * = None, tol: double * = None, shifted: bool * = None) → MxPotential *

Creates a Morse potential.

The Morse potential has the form:

\[d \left(1 - e^{ -a \left(r - r_0 \right) } \right)^2\]

Parameters

d (float) – well depth. Defaults to 1.0.
a (float) – potential width. Defaults to 6.0.
r0 (float) – equilibrium distance. Defaults to 0.0.
min (float) – The smallest radius for which the potential will be constructed. Defaults to 0.0001.
max (float) – The largest radius for which the potential will be constructed. Defaults to 3.0.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001.
shifted (boolean) – Flag for whether using a shifted potential. Defaults to true.

Return type

Returns

MxPotential*

static overlapping_sphere(mu: double * = None, kc: double * = None, kh: double * = None, r0: double * = None, min: double * = None, max: double * = None, tol: double * = None) → MxPotential *

Creates an overlapping-sphere potential from [OFPF+17].

The overlapping-sphere potential has the form:

\[\mu_{ij} s_{ij}(t) \hat{\mathbf{r}}_{ij} \log \left( 1 + \frac{||\mathbf{r}_{ij}|| - s_{ij}(t)}{s_{ij}(t)} \right) \text{ if } ||\mathbf{r}_{ij}|| < s_{ij}(t) ,\]

\[\mu_{ij}\left(||\mathbf{r}_{ij}|| - s_{ij}(t)\right) \hat{\mathbf{r}}_{ij} \exp \left( -k_c \frac{||\mathbf{r}_{ij}|| - s_{ij}(t)}{s_{ij}(t)} \right) \text{ if } s_{ij}(t) \leq ||\mathbf{r}_{ij}|| \leq r_{max} ,\]

\[0 \text{ otherwise} .\]

Osborne refers to \(\mu_{ij}\) as a “spring constant”, this controls the size of the force, and is the potential energy peak value. \(\hat{\mathbf{r}}_{ij}\) is the unit vector from particle \(i\) center to particle \(j\) center, \(k_C\) is a parameter that defines decay of the attractive force. Larger values of \(k_C\) result in a shaper peaked attraction, and thus a shorter ranged force. \(s_{ij}(t)\) is the is the sum of the radii of the two particles.

Parameters

mu (float) – interaction strength, represents the potential energy peak value. Defaults to 1.0.
kc (float) – decay strength of long range attraction. Larger values make a shorter ranged function. Defaults to 1.0.
kh (float) – Optionally add a harmonic long-range attraction, same as glj function. Defaults to 0.0.
r0 (float) – Optional harmonic rest length, only used if kh is non-zero. Defaults to 0.0.
min (float) – The smallest radius for which the potential will be constructed. Defaults to 0.001.
max (float) – The largest radius for which the potential will be constructed. Defaults to 10.0.
tol (float) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001.

Return type

Returns

MxPotential*

static power(k: double * = None, r0: double * = None, alpha: double * = None, min: double * = None, max: double * = None, tol: double * = None) → MxPotential *

Creates a power potential.

The power potential the general form of many of the potential functions, such as linear, etc. power has the form:

\[k (r-r_0)^{\alpha}\]

Parameters

k (float) – interaction strength, represents the potential energy peak value. Defaults to 1
r0 (float) – potential rest length, zero of the potential, defaults to 0.
alpha (float) – Exponent, defaults to 1.
min (float) – minimal value potential is computed for, defaults to r0 / 2.
max (float) – cutoff distance, defaults to 3 * r0.
tol (float) – Tolerance, defaults to 0.01.

Return type

Returns

MxPotential*

static dpd(alpha: double * = None, gamma: double * = None, sigma: double * = None, cutoff: double * = None, shifted: bool * = None) → MxPotential *

Creates a Dissipative Particle Dynamics potential.

The Dissipative Particle Dynamics force has the form:

\[\mathbf{F}_{ij} = \mathbf{F}^C_{ij} + \mathbf{F}^D_{ij} + \mathbf{F}^R_{ij}\]

The conservative force is:

\[\mathbf{F}^C_{ij} = \alpha \left(1 - \frac{r_{ij}}{r_c}\right) \mathbf{e}_{ij}\]

The dissapative force is:

\[\mathbf{F}^D_{ij} = -\gamma \left(1 - \frac{r_{ij}}{r_c}\right)^{2}(\mathbf{e}_{ij} \cdot \mathbf{v}_{ij}) \mathbf{e}_{ij}\]

The random force is:

\[\mathbf{F}^R_{ij} = \sigma \left(1 - \frac{r_{ij}}{r_c}\right) \xi_{ij}\Delta t^{-1/2}\mathbf{e}_{ij}\]

Parameters

alpha (float) – interaction strength of the conservative force. Defaults to 1.0.
gamma (float) – interaction strength of dissapative force. Defaults to 1.0.
sigma (float) – strength of random force. Defaults to 1.0.
cutoff (float) – cutoff distance. Defaults to 1.0.
shifted (boolean) – Flag for whether using a shifted potential. Defaults to false.

Return type

Returns

MxPotential*

class mechanica.DPDPotential(alpha: float, gamma: float, sigma: float, cutoff: float, shifted: bool)

Bases: MxPotential

alpha: strength of conserative interaction

gamma: strength of dissapative interaction

sigma: strength of random interaction

static fromPot(pot: MxPotential) → DPDPotential *

Convert basic potential to DPD.

If the basic potential is not DPD, then NULL is returned.

Parameters: pot (MxPotential) –
Return type: DPDPotential
Returns: DPDPotential*

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → DPDPotential *

Create from a JSON string representation

Parameters: str (string) –
Return type: DPDPotential
Returns: MxPotential*

__reduce__(): Helper for pickle.

class mechanica.MxPotentialPy

Bases: MxPotential

custom = <function MxPotentialPy.custom>

Forces

mechanica.Force: alias of MxForce

class mechanica.MxForce

MxForce is a metatype, in that Mechanica has lots of different instances of force functions, that have different attributes, but only have one base type.

Forces are one of the fundamental processes in Mechanica that cause objects to move.

bind_species(a_type: MxParticleType, coupling_symbol: std::string const &) → HRESULT

Bind a force to a species.

When a force is bound to a species, the magnitude of the force is scaled by the concentration of the species.

Parameters

a_type (MxParticleType) – particle type containing the species
coupling_symbol (string) – symbol of the species

Return type

int

Returns

HRESULT

static berendsen_tstat(tau: float const &) → Berendsen *

Creates a Berendsen thermostat.

The thermostat uses the target temperature \(T_0\) from the object to which it is bound. The Berendsen thermostat effectively re-scales the velocities of an object in order to make the temperature of that family of objects match a specified temperature.

The Berendsen thermostat force has the function form:

\[\frac{\mathbf{p}}{\tau_T} \left(\frac{T_0}{T} - 1 \right),\]

where \(\mathbf{p}\) is the momentum, \(T\) is the measured temperature of a family of particles, \(T_0\) is the control temperature, and \(\tau_T\) is the coupling constant. The coupling constant is a measure of the time scale on which the thermostat operates, and has units of time. Smaller values of \(\tau_T\) result in a faster acting thermostat, and larger values result in a slower acting thermostat.

Parameters: tau (float) – time constant that determines how rapidly the thermostat effects the system.
Return type: Berendsen
Returns: Berendsen*

static random(std: float const &, mean: float const &, duration: float const & = 0.01) → Gaussian *

Creates a random force.

A random force has a randomly selected orientation and magnitude.

Orientation is selected according to a uniform distribution on the unit sphere.

Magnitude is selected according to a prescribed mean and standard deviation.

Parameters

std (float) – standard deviation of magnitude
mean (float) – mean of magnitude
duration (float) – duration of force. Defaults to 0.01.

Return type

Gaussian

Returns

Gaussian*

static friction(coef: float const &) → Friction *

Creates a friction force.

A friction force has the form:

\[- \frac{|| \mathbf{v} ||}{\tau} \mathbf{v} ,\]

where \(\mathbf{v}\) is the velocity of a particle and \(\tau\) is a time constant.

Parameters: coef (float) – time constant
Return type: Friction
Returns: Friction*

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxForce *

Create from a JSON string representation

Parameters: str (string) –
Return type: MxForce
Returns: MxForce*

__reduce__(): Helper for pickle.

mechanica.ConstantForce: alias of MxConstantForcePy

class mechanica.MxConstantForce(*args)

Bases: MxForce

A custom force function.

The force is updated according to an update frequency.

This object acts like a constant force, but also acts like a time event, in that it periodically calls a custom function to update the applied force.

static fromForce(f: MxForce) → MxConstantForce *

Convert basic force to MxConstantForce.

If the basic force is not a MxConstantForce, then NULL is returned.

Parameters: f (MxForce) –
Return type: MxConstantForce
Returns: MxConstantForce*

class mechanica.MxConstantForcePy(*args)

Bases: MxConstantForce

Creates an instance from an underlying custom python function

Parameters

f (PyObject) – python function. Takes no arguments and returns a three-component vector.
period (float) – period at which the force is updated.

static fromForce(f: MxForce) → MxConstantForcePy *

Convert basic force to MxConstantForcePy.

If the basic force is not a MxConstantForcePy, then NULL is returned.

Parameters: f (MxForce) –
Return type: MxConstantForcePy
Returns: MxConstantForcePy*

mechanica.ForceSum: alias of MxForceSum

class mechanica.MxForceSum

Bases: MxForce

f1

f2

static fromForce(f: MxForce) → MxForceSum *

Convert basic force to force sum.

If the basic force is not a force sum, then NULL is returned.

Parameters: f (MxForce) –
Return type: MxForceSum
Returns: MxForceSum*

class mechanica.Berendsen

Bases: MxForce

Berendsen force.

Create one with MxForce.berendsen_tstat.

itau: time constant

static fromForce(f: MxForce) → Berendsen *

Convert basic force to Berendsen.

If the basic force is not a Berendsen, then NULL is returned.

Parameters: f (MxForce) –
Return type: Berendsen
Returns: Berendsen*

class mechanica.Gaussian

Bases: MxForce

Random force.

Create one with MxForce.random.

std: standard deviation of magnitude

mean: mean of magnitude

durration_steps: duration of force.

static fromForce(f: MxForce) → Gaussian *

Convert basic force to Gaussian.

If the basic force is not a Gaussian, then NULL is returned.

Parameters: f (MxForce) –
Return type: Gaussian
Returns: Gaussian*

class mechanica.Friction

Bases: MxForce

Friction force.

Create one with MxForce.friction.

coef: time constant

static fromForce(f: MxForce) → Friction *

Convert basic force to Friction.

If the basic force is not a Friction, then NULL is returned.

Parameters: f (MxForce) –
Return type: Friction
Returns: Friction*

Reactions and Species

mechanica.Species: alias of MxSpecies

class mechanica.MxSpecies(*args)

The Mechanica species object.

Mostly, this is a wrap of libSBML Species.

__str__() → str: Return str(self).

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxSpecies *

Create from a JSON string representation.

Parameters: str (string) –
Return type: MxSpecies
Returns: MxSpecies*

__reduce__(): Helper for pickle.

property id: str

property name: str

property species_type: str

property compartment: str

property initial_amount: float

property initial_concentration: float

property substance_units: str

property spatial_size_units: str

property units: str

property has_only_substance_units: bool

property boundary_condition: bool

property charge: int

property constant: bool

property conversion_factor: str

mechanica.SpeciesValue: alias of MxSpeciesValue

class mechanica.MxSpeciesValue(*args)

A working valued-object of an underlying MxSpecies attached to an object.

property boundary_condition: bool

property initial_amount: float

property initial_concentration: float

property constant: bool

secrete(amount, to=None, distance=None)

Secrete this species into a neighborhood.

Requires either a list of neighboring particles or neighborhood distance.

Parameters

amount (float) – Amount to secrete.
to (MxParticleList) – Optional list of particles to secrete to.
distance (float) – Neighborhood distance.

Returns

Amount actually secreted, accounting for availability and other subtleties.

Return type

float

mechanica.SpeciesList: alias of MxSpeciesList

class mechanica.MxSpeciesList

__str__() → str: Return str(self).

__len__() → int

__getattr__(item: str)

__setattr__(item: str, value) → None: Implement setattr(self, name, value).

__getitem__(item) → MxSpecies

__setitem__(item, value) → None

item(*args) → MxSpecies *

Overload 1:

Get a species by index

Parameters: index (int) – index of the species
Return type: MxSpecies
Returns: MxSpecies*

Overload 2:

Get a species by name

Parameters: s (string) – name of species
Return type: MxSpecies
Returns: MxSpecies*

insert(*args) → HRESULT

Overload 1:

Insert a species

Return type: int
Returns: HRESULT

Overload 2:

Insert a species by name

Parameters: s (string) – name of the species
Return type: int
Returns: HRESULT

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxSpeciesList *

Create from a JSON string representation.

Parameters: str (string) –
Return type: MxSpeciesList
Returns: MxSpeciesList*

__reduce__(): Helper for pickle.

mechanica.StateVector: alias of MxStateVector

class mechanica.MxStateVector(*args)

A state vector of an object.

__str__() → str: Return str(self).

__len__() → int

__getattr__(item: str)

__setattr__(item: str, value: float) → None: Implement setattr(self, name, value).

__getitem__(item: int)

__setitem__(item: int, value: float) → None

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxStateVector *

Create from a JSON string representation.

Parameters: str (string) –
Return type: MxStateVector
Returns: MxStateVector*

__reduce__(): Helper for pickle.

species: Species of the state vector

Fluxes

mechanica.Fluxes: alias of MxFluxes

class mechanica.MxFluxes

A flux is defined between a pair of types, and acts on the state vector between a pair of instances.

The indices of the species in each state vector are most likely different, so Mechanica tracks the indices in each type, and the transport constatants.

A flux between a pair of types, and pair of respective species needs:

(1) type A, (2) type B, (3) species id in A, (4) species id in B, (5) transport constant.

Allocates Flux as a single block, member pointers point to offsets in these blocks.

Allocated size is: sizeof(MxFluxes) + 2 * alloc_size * sizeof(int32) + alloc_size * sizeof(float)

static flux(A: MxParticleType, B: MxParticleType, name: std::string const &, k: float const &, decay: float const & = 0.0) → MxFluxes *

Alias of fluxFick.

Parameters

A (MxParticleType) – first type
B (MxParticleType) – second type
name (string) – name of species
k (float) – transport coefficient
decay (float) – optional decay. Defaults to 0.0.

Return type

Returns

MxFluxes*

static fluxFick(A: MxParticleType, B: MxParticleType, name: std::string const &, k: float const &, decay: float const & = 0.0) → MxFluxes *

Creates and binds a Fickian diffusion flux.

Fickian diffusion flux implements the analogous reaction:

\[a.S \leftrightarrow b.S ; k \left(1 - \frac{r}{r_{cutoff}} \right)\left(a.S - b.S\right) ,\]

\[a.S \rightarrow 0 ; \frac{d}{2} a.S ,\]

\[b.S \rightarrow 0 ; \frac{d}{2} b.S ,\]

where \(a.S\) is a chemical species located at object \(a\), and likewise for \(b\), \(k\) is the flux constant, \(r\) is the distance between the two objects, \(r_{cutoff}\) is the global cutoff distance, and \(d\) is an optional decay term.

Automatically updates when running on a CUDA device.

Parameters

A (MxParticleType) – first type
B (MxParticleType) – second type
name (string) – name of species
k (float) – transport coefficient
decay (float) – optional decay. Defaults to 0.0.

Return type

Returns

MxFluxes*

static secrete(A: MxParticleType, B: MxParticleType, name: std::string const &, k: float const &, target: float const &, decay: float const & = 0.0) → MxFluxes *

Creates a secretion flux by active pumping.

Secretion flux implements the analogous reaction:

\[a.S \rightarrow b.S ; k \left(1 - \frac{r}{r_{cutoff}} \right)\left(a.S - a.S_{target} \right) ,\]

\[a.S \rightarrow 0 ; \frac{d}{2} a.S ,\]

\[b.S \rightarrow 0 ; \frac{d}{2} b.S ,\]

where \(a.S\) is a chemical species located at object \(a\), and likewise for \(b\), \(k\) is the flux constant, \(r\) is the distance between the two objects, \(r_{cutoff}\) is the global cutoff distance, and \(d\) is an optional decay term.

Automatically updates when running on a CUDA device.

Parameters

A (MxParticleType) – first type
B (MxParticleType) – second type
name (string) – name of species
k (float) – transport coefficient
target (float) – target concentration
decay (float) – optional decay. Defaults to 0.0

Return type

Returns

MxFluxes*

static uptake(A: MxParticleType, B: MxParticleType, name: std::string const &, k: float const &, target: float const &, decay: float const & = 0.0) → MxFluxes *

Creates an uptake flux by active pumping.

Uptake flux implements the analogous reaction:

\[a.S \rightarrow b.S ; k \left(1 - \frac{r}{r_{cutoff}}\right)\left(b.S - b.S_{target} \right)\left(a.S\right) ,\]

\[a.S \rightarrow 0 ; \frac{d}{2} a.S ,\]

\[b.S \rightarrow 0 ; \frac{d}{2} b.S ,\]

where \(a.S\) is a chemical species located at object \(a\), and likewise for \(b\), \(k\) is the flux constant, \(r\) is the distance between the two objects, \(r_{cutoff}\) is the global cutoff distance, and \(d\) is an optional decay term.

Automatically updates when running on a CUDA device.

Parameters

A (MxParticleType) – first type
B (MxParticleType) – second type
name (string) – name of species
k (float) – transport coefficient
target (float) – target concentration
decay (float) – optional decay. Defaults to 0.0

Return type