relentless.model.potential.PairSpline#

class relentless.model.potential.PairSpline(types, num_knots, mode='diff', name=None)#

Spline pair potential.

The pair potential is defined by interpolation through a set of knot points. The interpolation scheme uses Akima splines.

Parameters:

  • types (tuple[str]) – Types.

  • num_knots (int) – Number of knots.

  • mode (str) – Mode for storing the values of the knots in Variable that can be optimized. If mode='value', the knot amplitudes are manipulated directly. If mode='diff', the amplitude of the last knot is fixed, and differences between neighboring knots are manipulated for all other knots. Defaults to 'diff'.

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

Examples

The spline potential is setup from a tabulated potential instead of specifying knot parameters directly:

spline = relentless.potential.pair.Spline(types=('A',), num_knots=3)
spline.from_array(('A','A'),[0,1,2],[4,2,0])

However, the knot variables can be iterated over and manipulated directly:

for r,k in spline.knots(('A','A')):
    k.value = 1.0

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_array(pair, r, u)

Set up the potential from knot points.

from_file(filename[, name])

Create potential from a JSON file.

from_json(data[, name])

Create potential from JSON data.

knot_params(i)

Get the parameter names for a given knot.

knots(pair)

Generator for knot points.

save(filename)

Save the potential to file as JSON data.

to_json()

Export potential to a JSON-compatible dictionary.

Attributes

count

design_variables

Designable variables of the spline.

mode

Spline construction mode.

names

num_knots

Number of knots.

valid_modes

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.

property design_variables#

Designable variables of the spline.

Type:

tuple

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.

from_array(pair, r, u)#

Set up the potential from knot points.

Each knot will be converted into two Variable objects consistent with the storage mode.

Parameters:

  • pair (tuple[str]) – The type pair (i,j) for which to set up the potential.

  • r (list) – Position of each knot.

  • u (list) – Potential energy of each knot.

Raises:

  • ValueError – If the number of r values is not the same as the number of knots.

  • ValueError – If the number of u values is not the same as the number of knots.

classmethod from_file(filename, name=None)#

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.

  • name (str or bool or None) – Name of the potential. If a str, name overrides the value in the file. If True, the name in the file is always preserved. If False, the name in the file is always ignored, and a default name is created. If None, the value in the file is used if it is not taken and does not match the default name pattern; otherwise, a new default name is generated.

classmethod from_json(data, name=None)#

Create potential from JSON data.

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

Parameters:

  • data (dict) – JSON data for potential.

  • name (str or bool or None) – Name of the potential. If a str, name overrides the value in the JSON data. If True, the name in the JSON data is always preserved. If False, the name in the JSON data is always ignored, and a default name is created. If None, the value in the JSON data is used if it is not taken and does not match the default name pattern; otherwise, a new default name is generated.

knot_params(i)#

Get the parameter names for a given knot.

Parameters:

i (int) – Key for the knot variable.

Returns:

  • str – The parameter name of the \(r\) value.

  • str – The parameter name of the knot value.

Raises:

TypeError – If the knot key is not an integer.

knots(pair)#

Generator for knot points.

Parameters:

pair (tuple[str]) – The type pair (i,j) for which to retrieve the knot points.

Yields:

  • Variable – The next \(dr\) variable in the parameters.

  • Variable – The next knot variable in the parameters.

property mode#

Spline construction mode.

Type:

str

property num_knots#

Number of knots.

Type:

int

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