Potentials

class tissue_forge.tissue_forge._Potential

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, Tissue Forge 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) → FPTYPE

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

Potential plot function

Parameters:

s – sum of theoretical radii of two interacting particles
force – flag to plot evaluations of the force magnitude
potential – flag to plot evaluations of the potential
show – flag to show the plot
ymin – minimum vertical plot value
ymax – maximum vertical plot value

Returns:

plot lines

toString() → std::string

Get a JSON string representation

Return type:: string
Returns:: std::string

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

Create from a JSON string representation

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

__reduce__(): Helper for pickle.

static lennard_jones_12_6(min: FPTYPE, max: FPTYPE, A: FPTYPE, B: FPTYPE, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static lennard_jones_12_6_coulomb(min: FPTYPE, max: FPTYPE, A: FPTYPE, B: FPTYPE, q: FPTYPE, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static ewald(min: FPTYPE, max: FPTYPE, q: FPTYPE, kappa: FPTYPE, tol: FPTYPE * = None, periodicOrder: unsigned int * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static coulomb(q: FPTYPE, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None, periodicOrder: unsigned int * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static coulombR(q: FPTYPE, kappa: FPTYPE, min: FPTYPE, max: FPTYPE, modes: unsigned int * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static harmonic(k: FPTYPE, r0: FPTYPE, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static linear(k: FPTYPE, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static harmonic_angle(k: FPTYPE, theta0: FPTYPE, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static harmonic_dihedral(k: FPTYPE, delta: FPTYPE, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static cosine_dihedral(k: FPTYPE, n: int, delta: FPTYPE, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static well(k: FPTYPE, n: FPTYPE, r0: FPTYPE, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

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

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:

Potential

Returns:

Potential*

static morse(d: FPTYPE * = None, a: FPTYPE * = None, r0: FPTYPE * = None, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None, shifted: bool * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static overlapping_sphere(mu: FPTYPE * = None, kc: FPTYPE * = None, kh: FPTYPE * = None, r0: FPTYPE * = None, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

static power(k: FPTYPE * = None, r0: FPTYPE * = None, alpha: FPTYPE * = None, min: FPTYPE * = None, max: FPTYPE * = None, tol: FPTYPE * = None) → TissueForge::Potential *

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 \lvert r-r_0 \rvert ^{\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:

Potential

Returns:

Potential*

static dpd(alpha: FPTYPE * = None, gamma: FPTYPE * = None, sigma: FPTYPE * = None, cutoff: FPTYPE * = None, shifted: bool * = None) → TissueForge::Potential *

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:

Potential

Returns:

Potential*

class tissue_forge.tissue_forge.Potential

Bases: _Potential

custom = <function Potential.custom>

class tissue_forge.tissue_forge.DPDPotential(alpha: FPTYPE, gamma: FPTYPE, sigma: FPTYPE, cutoff: FPTYPE, shifted: bool)

Bases: _Potential

alpha: strength of conserative interaction

gamma: strength of dissapative interaction

sigma: strength of random interaction

static fromPot(pot: _Potential) → TissueForge::DPDPotential *

Convert basic potential to DPD.

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

Parameters:: pot (Potential) –
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 &) → TissueForge::DPDPotential *

Create from a JSON string representation

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

__reduce__(): Helper for pickle.