relentless.model.potential.Depletion#

class relentless.model.potential.Depletion(types, name=None)#

Depletion pair potential.

The Asakura–Oosawa pairwise attraction between spherical particles due to implicit depletion from an idealized polymer solution:

\[u(r) = -\frac{\pi P}{12 r} \left[\frac{1}{2}(\sigma_i+\sigma_j)+\sigma_d-r\right]^2 \left[r^2+r(\sigma_i+\sigma_j+2\sigma_d) \right. \left.-\frac{3}{4}(\sigma_i-\sigma_j)^2\right]\]

where \(r\) is the distance between two particles. The parameters for each \((i,j)\) pair are:

Parameter	Description	Initial
`P`	Osmotic pressure \(P\) of depletant.
`sigma_i`	Diameter \(\sigma_i\) of type \(i\).
`sigma_j`	Diameter \(\sigma_j\) of type \(j\).
`sigma_d`	Diameter \(\sigma_d\) of depletant.
`rmin`	Minimum distance cutoff \(r_{\rm min}\). Force is zero and energy is constant for \(r < r_{\rm min}\). Ignored if `False`.	`False`
`rmax`	Maximum distance cutoff \(r_{\rm max}\). Force is zero and energy is constant for \(r > r_{\rm max}\). If `False`, the cutoff is automatically set to \((\sigma_i+\sigma_j)/2+\sigma_d\).	`False`
`shift`	If `True`, shift potential to zero at `rmax`.	`False`

For most physical systems, it is advisable to set P and sigma_d to the same value for all pairs. It is also recommended to leave rmax=False so that the potential is cutoff at the distance set by the diameters in the model.

Parameters:

types (tuple[str]) – Types.
name (str) – Unique name of the potential. Defaults to __u[id], where id is the unique integer ID of the potential.

coeff#

Parameters of the potential for each pair.

Type:: PairParameters

Examples

Depletion attraction:

>>> u = relentless.potential.pair.Depletion(('A',))
>>> u.coeff['A','A'].update({
    'P': 2.0, 'sigma_i': 1.0, 'sigma_j': 1.0, 'sigma_d': 0.1})

Methods

`derivative`(pair, var, r)	Evaluate pair derivative with respect to a variable.
`energy`(pair, r)	Evaluate pair energy.
`force`(pair, r)	Evaluate pair force.
`from_file`(filename)	Create potential from a JSON file.
`from_json`(data)	Create potential from JSON data.
`save`(filename)	Save the potential to file as JSON data.
`to_json`()	Export potential to a JSON-compatible dictionary.

Attributes

`count`
`names`

class Cutoff(sigma_i, sigma_j, sigma_d)#

Physical cutoff for depletion potential.

The depletion potential is usually cutoff based on the diameters of the particles and depletant:

\[r_{\rm max} = \frac{1}{2}(\sigma_i+\sigma_j)+\sigma_d\]

Parameters:

sigma_i (int, float, or Variable) – Diameter \(\sigma_i\) of particle of type i.
sigma_j (int/float or Variable) – Diameter \(\sigma_j\) of particle of type j.
sigma_d (int/float or Variable) – Diameter \(\sigma_d\) of depletant.

compute(sigma_i, sigma_j, sigma_d)#

Implementation of the value.

This method should implement calculation of the variable from the parameter keywords. The parameters will be passed as keyword arguments.

compute_derivative(param, sigma_i, sigma_j, sigma_d)#

Implementation of the derivative.

This method should implement the partial derivative with respect to the named dependency param given the current value of this variable. The parameters will be passed as keyword arguments.

Parameters:: param (str) – Name of the dependency.

derivative(var)#

Calculate derivative with respect to a Variable.

The derivative is evaluated using the VariableGraph. Any values of the graph that are needed will be updated.

Parameters:: var (Variable) – Variable with respect to which to take the derivative.
Returns:: The calculated derivative.
Return type:: float

property params#

Names of parameters

Type:: tuple

property value#

Value of the variable.

The variable will be evaluated using the VariableGraph if it needs to be recomputed.

Type:: float

derivative(pair, var, r)#

Evaluate pair derivative with respect to a variable.

The derivative is evaluated using the _derivative() function for all \(u_{0,\lambda}(r)\). The truncation and shifting scheme is applied.

The derivative will be carried out with respect to var for all Variable parameters. The appropriate chain rules are handled automatically. If the potential does not depend on var, the derivative will be zero by definition.

Parameters:

pair (tuple[str]) – The pair for which to calculate the derivative.
var (Variable) – The variable with respect to which the derivative is calculated.
r (float or list) – The pair distance(s) at which to evaluate the derivative.

Returns:

The pair derivative evaluated at r. The return type is consistent with r.

Return type:

float or numpy.ndarray

Raises:

ValueError – If any value in r is negative.
TypeError – If the parameter with respect to which to take the derivative is not a Variable.
ValueError – If the potential is shifted without setting rmax.

energy(pair, r)#

Evaluate pair energy.

The energy is evaluated using the _energy() function for \(u_0(r)\). The truncation and shifting scheme is applied.

Parameters:

pair (tuple[str]) – The pair for which to calculate the energy.
r (float or list) – The pair distance(s) at which to evaluate the energy.

Returns:

The pair energy evaluated at r. The return type is consistent with r.

Return type:

float or numpy.ndarray

Raises:

ValueError – If any value in r is negative.
ValueError – If the potential is shifted without setting rmax.

force(pair, r)#

Evaluate pair force.

The force is evaluated using the _force() function for \(f_0(r)\). The truncation and shifting scheme is applied.

Parameters:

pair (tuple[str]) – The pair for which to calculate the force.
r (float or list) – The pair distance(s) at which to evaluate the force.

Returns:

The pair force evaluated at r. The return type is consistent with r.

Return type:

float or numpy.ndarray

Raises:

ValueError – If any value in r is negative.

classmethod from_file(filename)#

Create potential from a JSON file.

It is assumed that the JSON file is compatible with the potential type.

Parameters:: filename (str) – JSON file to load.

classmethod from_json(data)#

Create potential from JSON data.

It is assumed that the data is compatible with the pair potential.

Parameters:: data (dict) – JSON data for potential.

save(filename)#

Save the potential to file as JSON data.

Parameters:: filename (str) – The name of the file to which to save the data.

to_json()#

Export potential to a JSON-compatible dictionary.

The JSON dictionary will contain the id and name of the potential, along with the JSON representation of its coefficients.

Returns:: Potential.
Return type:: dict