Potential¶

Numerical potential energy functions for bonds, angles, dihedrals, and pairs.

Quick reference¶

Symbol	Summary	Preferred for
`BondHarmonic`	Harmonic bond: E = k(r - r₀)²	Standard bonded interactions
`AngleHarmonic`	Harmonic angle: E = k(θ - θ₀)²	Standard angle terms
`LJ126`	Lennard-Jones 12-6 pair	Standard nonbonded interactions
`TypeIndexedArray`	Array indexed by type name strings	Vectorized parameter lookup

Canonical example¶

ff = mp.AtomisticForcefield(name="demo", units="real")
bond_style = ff.def_bondstyle("harmonic")
bond_style.def_type(ct, hc, k0=340.0, r0=1.09)

pot = bond_style.to_potential()
print(pot.k["CT-HC"])   # [340.]
print(pot.r0["CT-HC"])  # [1.09]

Concepts: Force Field

Full API¶

Base¶

base ¶

Base classes for potential functions.

Potential ¶

Base class for all potential functions in MolPy.

This class provides a template for defining potential functions that can be used in molecular simulations. Each potential class should implement calc_energy and calc_forces methods with specific parameters.

calc_energy ¶

calc_energy(*args, **kwargs)

Calculate the potential energy.

Parameters¶

args: Arguments specific to the potential type *kwargs: Keyword arguments specific to the potential type

Returns¶

float The potential energy.

calc_forces ¶

calc_forces(*args, **kwargs)

Calculate the forces.

Parameters¶

args: Arguments specific to the potential type *kwargs: Keyword arguments specific to the potential type

Returns¶

np.ndarray An array of forces.

Potentials ¶

Bases: UserList[Potential]

Collection of potential functions.

This class provides a way to combine multiple potentials and calculate total energy and forces. However, since different potentials require different parameters, you need to call calc_energy and calc_forces for each potential separately and sum the results.

For a simpler interface, use the helper functions in potential.utils to extract data from Frame objects.

calc_energy ¶

calc_energy(*args, **kwargs)

Calculate the total energy by summing energies from all potentials.

If a Frame object is passed as the first argument, automatically extracts the necessary data for each potential type.

Parameters¶

args: Arguments passed to each potential's calc_energy method. If first arg is a Frame, data is automatically extracted. *kwargs: Keyword arguments passed to each potential's calc_energy method

Returns¶

float The total energy.

calc_forces ¶

calc_forces(*args, **kwargs)

Calculate the total forces by summing forces from all potentials.

If a Frame object is passed as the first argument, automatically extracts the necessary data for each potential type.

Parameters¶

args: Arguments passed to each potential's calc_forces method. If first arg is a Frame, data is automatically extracted. *kwargs: Keyword arguments passed to each potential's calc_forces method

Returns¶

np.ndarray An array of total forces.

Bond¶

bond ¶

BondClass2Style ¶

BondClass2Style()

Bases: BondStyle

Class2 quartic bond: E = k2*(r-r0)^2 + k3*(r-r0)^3 + k4*(r-r0)^4.

BondHarmonic ¶

BondHarmonic(k, r0)

Bases: BondPotential

Initialize harmonic bond potential.

Parameters:

Name	Type	Description	Default
`k`	`NDArray[floating] \| float \| dict[str, float]`	Force constant (array for multiple types, scalar, or dict mapping type names to values)	required
`r0`	`NDArray[floating] \| float \| dict[str, float]`	Equilibrium bond length (array for multiple types, scalar, or dict mapping type names to values)	required

calc_energy ¶

calc_energy(r, bond_idx, bond_types)

Calculate bond energy.

Parameters:

Name	Type	Description	Default
`r`	`NDArray[floating]`	Atom coordinates (shape: (n_atoms, 3))	required
`bond_idx`	`NDArray[integer]`	Bond indices (shape: (n_bonds, 2))	required
`bond_types`	`NDArray[integer] \| NDArray[str_]`	Bond types (shape: (n_bonds,)) - can be integer indices or string type names	required

Returns:

Type	Description
`float`	Total bond energy

calc_forces ¶

calc_forces(r, bond_idx, bond_types)

Calculate bond forces.

Parameters:

Name	Type	Description	Default
`r`	`NDArray[floating]`	Atom coordinates (shape: (n_atoms, 3))	required
`bond_idx`	`NDArray[integer]`	Bond indices (shape: (n_bonds, 2))	required
`bond_types`	`NDArray[integer] \| NDArray[str_]`	Bond types (shape: (n_bonds,)) - can be integer indices or string type names	required

Returns:

Type	Description
`NDArray[floating]`	Array of forces on each atom (shape: (n_atoms, 3))

BondHarmonicStyle ¶

BondHarmonicStyle()

Bases: BondStyle

Harmonic bond style with fixed name='harmonic'.

def_type ¶

def_type(itom, jtom, k, r0, name='')

Define harmonic bond type.

Parameters:

Name	Type	Description	Default
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType`	Second atom type	required
`k`	`float`	Force constant	required
`r0`	`float`	Equilibrium bond length	required
`name`	`str`	Optional name (defaults to itom-jtom)	`''`

Returns:

Type	Description
`BondHarmonicType`	BondHarmonicType instance

BondHarmonicType ¶

BondHarmonicType(name, itom, jtom, k, r0)

Bases: BondType

Harmonic bond type with k and r0 parameters.

Parameters:

Name	Type	Description	Default
`name`	`str`	Type name	required
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType`	Second atom type	required
`k`	`float`	Force constant	required
`r0`	`float`	Equilibrium bond length	required

BondMorseStyle ¶

BondMorseStyle()

Bases: BondStyle

Morse bond style. Parameters per type: D (well depth), alpha (steepness), r0 (equilibrium length).

BondPotential ¶

Bases: Potential

Base class for bond potentials.

Angle¶

angle ¶

AngleClass2BondAngleStyle ¶

AngleClass2BondAngleStyle()

Bases: AngleStyle

Bond-Angle cross-term for class2 angle.

AngleClass2BondBondStyle ¶

AngleClass2BondBondStyle()

Bases: AngleStyle

Bond-Bond cross-term for class2 angle.

AngleClass2Style ¶

AngleClass2Style()

Bases: AngleStyle

Class2 angle core term: E = k2*(th-th0)^2 + k3*(th-th0)^3 + k4*(th-th0)^4.

AngleHarmonic ¶

AngleHarmonic(k, theta0)

Bases: AnglePotential

Initialize harmonic angle potential.

Parameters:

Name	Type	Description	Default
`k`	`NDArray[floating] \| float \| dict[str, float]`	Force constant in kcal/mol/rad² (array, scalar, or dict mapping type names to values)	required
`theta0`	`NDArray[floating] \| float \| dict[str, float]`	Equilibrium angle in degrees (array, scalar, or dict mapping type names to values)	required

calc_energy ¶

calc_energy(r, angle_idx, angle_types)

Calculate angle energy.

Parameters:

Name	Type	Description	Default
`r`	`NDArray[floating]`	Atom coordinates (shape: (n_atoms, 3))	required
`angle_idx`	`NDArray[integer]`	Angle indices (shape: (n_angles, 3))	required
`angle_types`	`NDArray[integer] \| NDArray[str_]`	Angle types (shape: (n_angles,))	required

Returns:

Type	Description
`float`	Total angle energy

calc_forces ¶

calc_forces(r, angle_idx, angle_types)

Calculate angle forces.

Parameters:

Name	Type	Description	Default
`r`	`NDArray[floating]`	Atom coordinates (shape: (n_atoms, 3))	required
`angle_idx`	`NDArray[integer]`	Angle indices (shape: (n_angles, 3))	required
`angle_types`	`NDArray[integer] \| NDArray[str_]`	Angle types (shape: (n_angles,))	required

Returns:

Type	Description
`NDArray[floating]`	Array of forces on each atom (shape: (n_atoms, 3))

AngleHarmonicStyle ¶

AngleHarmonicStyle()

Bases: AngleStyle

Harmonic angle style with fixed name='harmonic'.

def_type ¶

def_type(itom, jtom, ktom, k, theta0, name='')

Define harmonic angle type.

Parameters:

Name	Type	Description	Default
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType`	Central atom type	required
`ktom`	`AtomType`	Third atom type	required
`k`	`float`	Force constant	required
`theta0`	`float`	Equilibrium angle in degrees	required
`name`	`str`	Optional name (defaults to itom-jtom-ktom)	`''`

Returns:

Type	Description
`AngleHarmonicType`	AngleHarmonicType instance

AngleHarmonicType ¶

AngleHarmonicType(name, itom, jtom, ktom, k, theta0)

Bases: AngleType

Harmonic angle type with k and theta0 parameters.

Parameters:

Name	Type	Description	Default
`name`	`str`	Type name	required
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType`	Central atom type	required
`ktom`	`AtomType`	Third atom type	required
`k`	`float`	Force constant	required
`theta0`	`float`	Equilibrium angle in degrees	required

AnglePotential ¶

Bases: Potential

Base class for angle potentials.

Dihedral¶

dihedral ¶

Dihedral potentials.

DihedralCharmmStyle ¶

DihedralCharmmStyle()

Bases: DihedralStyle

CHARMM proper: E = K*(1 + cos(n*phi - d)), 1-4 weight w.

DihedralClass2Style ¶

DihedralClass2Style()

Bases: DihedralStyle

Class2 dihedral core term (three-term cosine expansion).

DihedralFourierStyle ¶

DihedralFourierStyle()

Bases: DihedralStyle

LAMMPS fourier dihedral style for AMBER/GAFF force fields.

Parameters stored per type: k1=K, k2=n (int), k3=phase (degrees), k4=weight. Written as: dihedral_coeff ID m K n phase (m=1 for single-term AMBER dihedrals).

def_type ¶

def_type(itom, jtom, ktom, ltom, name='', **kwargs)

Define periodic dihedral type.

Parameters:

Name	Type	Description	Default
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType`	Second atom type	required
`ktom`	`AtomType`	Third atom type	required
`ltom`	`AtomType`	Fourth atom type	required
`name`	`str`	Optional name (defaults to itom-jtom-ktom-ltom)	`''`
`**kwargs`	`Any`	Periodic parameters (periodicity1, k1, phase1, ...).	`{}`

Returns:

Type	Description
`DihedralPeriodicType`	DihedralPeriodicType instance

DihedralMultiHarmonicStyle ¶

DihedralMultiHarmonicStyle()

Bases: DihedralStyle

Multi-harmonic: E = sum_{n=1..5} A_n * cos^(n-1)(phi).

DihedralOPLSStyle ¶

DihedralOPLSStyle()

Bases: DihedralStyle

OPLS dihedral style with fixed name='opls'.

OPLS dihedral uses Ryckaert-Bellemans (RB) coefficients c0-c5. LAMMPS opls style expects k1-k4, which are computed from c0-c5 using analytical conversion according to GROMACS manual Eqs. 200-201.

def_type ¶

def_type(itom, jtom, ktom, ltom, c0=0.0, c1=0.0, c2=0.0, c3=0.0, c4=0.0, c5=0.0, name='')

Define OPLS dihedral type.

Parameters:

Name	Type	Description	Default
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType`	Second atom type	required
`ktom`	`AtomType`	Third atom type	required
`ltom`	`AtomType`	Fourth atom type	required
`c0`	`float`	OPLS Ryckaert-Bellemans coefficient c0.	`0.0`
`c1`	`float`	OPLS Ryckaert-Bellemans coefficient c1.	`0.0`
`c2`	`float`	OPLS Ryckaert-Bellemans coefficient c2.	`0.0`
`c3`	`float`	OPLS Ryckaert-Bellemans coefficient c3.	`0.0`
`c4`	`float`	OPLS Ryckaert-Bellemans coefficient c4.	`0.0`
`c5`	`float`	OPLS Ryckaert-Bellemans coefficient c5.	`0.0`
`name`	`str`	Optional name (defaults to itom-jtom-ktom-ltom)	`''`

Returns:

Type	Description
`DihedralOPLSType`	DihedralOPLSType instance

to_lammps_params ¶

to_lammps_params(dihedral_type)

Convert OPLS c0-c5 coefficients to LAMMPS k1-k4 format.

Note: In OPLS XML files, c1-c4 typically contain OPLS coefficients F1-F4 directly (not RB format). So we use c1-c4 directly as k1-k4.

For true RB format coefficients, use rb_to_opls() function instead.

Parameters:

Name	Type	Description	Default
`dihedral_type`	`DihedralOPLSType`	DihedralOPLSType with c0-c5 parameters	required

Returns:

Type	Description
`list[float]`	List of [k1, k2, k3, k4] for LAMMPS in kcal/mol

DihedralOPLSType ¶

DihedralOPLSType(name, itom, jtom, ktom, ltom, c0=0.0, c1=0.0, c2=0.0, c3=0.0, c4=0.0, c5=0.0)

Bases: DihedralType

OPLS dihedral type with c0-c5 coefficients.

Parameters:

Name	Type	Description	Default
`name`	`str`	Type name	required
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType`	Second atom type	required
`ktom`	`AtomType`	Third atom type	required
`ltom`	`AtomType`	Fourth atom type	required
`c0`	`float`	OPLS Ryckaert-Bellemans coefficient c0.	`0.0`
`c1`	`float`	OPLS Ryckaert-Bellemans coefficient c1.	`0.0`
`c2`	`float`	OPLS Ryckaert-Bellemans coefficient c2.	`0.0`
`c3`	`float`	OPLS Ryckaert-Bellemans coefficient c3.	`0.0`
`c4`	`float`	OPLS Ryckaert-Bellemans coefficient c4.	`0.0`
`c5`	`float`	OPLS Ryckaert-Bellemans coefficient c5.	`0.0`

DihedralPeriodicStyle ¶

DihedralPeriodicStyle()

Bases: DihedralStyle

Periodic torsion dihedral style (AMBER/GAFF).

Uses periodic cosine terms: V(phi) = sum_i k_i * (1 + cos(n_i * phi - phi0_i))

DihedralPeriodicType ¶

DihedralPeriodicType(name, itom, jtom, ktom, ltom, **kwargs)

Bases: DihedralType

Periodic torsion dihedral type with multiple terms.

Each term has: periodicity (n), force constant (k), phase angle (phi0). V(phi) = sum_i k_i * (1 + cos(n_i * phi - phi0_i))

Pair¶

pair ¶

CoulCut ¶

Bases: PairPotential

Coulomb pair potential with cutoff.

The potential is defined as: V(r) = q_i * q_j / r

The force is: F(r) = q_i * q_j / r^3 * dr

calc_energy ¶

calc_energy(r, pair_idx, charges)

Calculate Coulomb energy.

Parameters:

Name	Type	Description	Default
`r`	`NDArray[floating]`	Atom coordinates (shape: (n_atoms, 3))	required
`pair_idx`	`NDArray[integer]`	Pair indices (shape: (n_pairs, 2))	required
`charges`	`NDArray[floating]`	Atom charges (shape: (n_atoms,))	required

Returns:

Type	Description
`float`	Total Coulomb energy

calc_forces ¶

calc_forces(r, pair_idx, charges)

Calculate Coulomb forces.

Parameters:

Name	Type	Description	Default
`r`	`NDArray[floating]`	Atom coordinates (shape: (n_atoms, 3))	required
`pair_idx`	`NDArray[integer]`	Pair indices (shape: (n_pairs, 2))	required
`charges`	`NDArray[floating]`	Atom charges (shape: (n_atoms,))	required

Returns:

Type	Description
`NDArray[floating]`	Array of forces on each atom (shape: (n_atoms, 3))

LJ126 ¶

LJ126(epsilon, sigma)

Bases: PairPotential

Lennard-Jones 12-6 pair potential with cutoff.

The potential is defined as: V(r) = 4 * ε * ((σ/r)^12 - (σ/r)^6)

The force is: F(r) = 24 * ε * (2 * (σ/r)^12 - (σ/r)^6) * dr / r^2

Attributes:

Name	Type	Description
`epsilon`		Depth of potential well for each atom type [energy]
`sigma`		Finite distance at which potential is zero [length]

Initialize LJ126 potential.

Parameters:

Name	Type	Description	Default
`epsilon`	`float \| NDArray[float64]`	Depth of potential well, can be scalar or array for multiple types	required
`sigma`	`float \| NDArray[float64]`	Finite distance at which potential is zero, can be scalar or array for multiple types	required

calc_energy ¶

calc_energy(dr, dr_norm, pair_types)

Calculate pair energy.

Parameters:

Name	Type	Description	Default
`dr`	`NDArray[floating]`	Pair displacement vectors (shape: (n_pairs, 3))	required
`dr_norm`	`NDArray[floating]`	Pair distances (shape: (n_pairs, 1) or (n_pairs,))	required
`pair_types`	`NDArray[integer]`	Pair types (shape: (n_pairs,))	required

Returns:

Type	Description
`float`	Total pair energy

calc_forces ¶

calc_forces(dr, dr_norm, pair_types, pair_idx, n_atoms)

Calculate pair forces.

Parameters:

Name	Type	Description	Default
`dr`	`NDArray[floating]`	Pair displacement vectors (shape: (n_pairs, 3))	required
`dr_norm`	`NDArray[floating]`	Pair distances (shape: (n_pairs, 1) or (n_pairs,))	required
`pair_types`	`NDArray[integer]`	Pair types (shape: (n_pairs,))	required
`pair_idx`	`NDArray[integer]`	Pair indices (shape: (n_pairs, 2))	required
`n_atoms`	`int`	Number of atoms	required

Returns:

Type	Description
`NDArray[floating]`	Array of forces on each atom (shape: (n_atoms, 3))

LJ126CoulLong ¶

LJ126CoulLong(epsilon, sigma, charges, type_names)

Bases: PairPotential

Combined Lennard-Jones 12-6 and Coulomb long-range pair potential.

This is a composite potential that combines LJ and Coulomb interactions. Uses PairTypeIndexedArray internally for automatic combining rules.

V(r) = V_LJ(r) + V_Coul(r)

Initialize LJ126CoulLong potential.

Parameters:

Name	Type	Description	Default
`epsilon`	`NDArray[float64]`	Per-atom-type epsilon values (numpy array)	required
`sigma`	`NDArray[float64]`	Per-atom-type sigma values (numpy array)	required
`charges`	`NDArray[float64]`	Per-atom-type charges (numpy array)	required
`type_names`	`list[str]`	List of atom type names corresponding to array indices	required

calc_energy ¶

calc_energy(dr, dr_norm, pair_types_i, pair_types_j)

Calculate combined LJ + Coulomb energy.

Uses PairTypeIndexedArray to automatically apply combining rules.

calc_forces ¶

calc_forces(dr, dr_norm, pair_types_i, pair_types_j, pair_idx, n_atoms)

Calculate combined LJ + Coulomb forces.

Uses PairTypeIndexedArray to automatically apply combining rules.

PairBuckStyle ¶

PairBuckStyle(**style_kwargs)

Bases: PairStyle

Buckingham: E = A*exp(-r/rho) - C/r^6.

PairCoulLongStyle ¶

PairCoulLongStyle(cutoff=10.0)

Bases: PairStyle

Coulomb long-range pair style with fixed name='coul/long'.

Parameters:

Name	Type	Description	Default
`cutoff`	`float`	Cutoff distance in Angstroms (default: 10.0)	`10.0`

PairLJ126CoulCutStyle ¶

PairLJ126CoulCutStyle(lj_cutoff=10.0, coul_cutoff=10.0, coulomb14scale=0.5, lj14scale=0.5)

Bases: PairStyle

Combined LJ 12-6 and Coulomb cut pair style.

This is a composite style that combines PairLJ126Style and Coulomb cut. The name is 'lj/cut/coul/cut' for LAMMPS compatibility.

Parameters:

Name	Type	Description	Default
`lj_cutoff`	`float`	LJ cutoff distance in Angstroms (default: 10.0)	`10.0`
`coul_cutoff`	`float`	Coulomb cutoff distance in Angstroms (default: 10.0)	`10.0`
`coulomb14scale`	`float`	1-4 Coulomb scaling factor (default: 0.5)	`0.5`
`lj14scale`	`float`	1-4 LJ scaling factor (default: 0.5)	`0.5`

def_type ¶

def_type(itom, jtom=None, epsilon=0.0, sigma=0.0, charge=0.0, name='')

Define LJ 12-6 pair type (same as PairLJ126Style).

Parameters:

Name	Type	Description	Default
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType \| None`	Second atom type (None for self-interaction)	`None`
`epsilon`	`float`	LJ epsilon parameter	`0.0`
`sigma`	`float`	LJ sigma parameter	`0.0`
`charge`	`float`	Atomic charge (optional)	`0.0`
`name`	`str`	Optional name	`''`

Returns:

Type	Description
`PairLJ126Type`	PairLJ126Type instance

PairLJ126CoulLongStyle ¶

PairLJ126CoulLongStyle(lj_cutoff=10.0, coul_cutoff=10.0, coulomb14scale=0.5, lj14scale=0.5)

Bases: PairStyle

Combined LJ 12-6 and Coulomb long pair style.

This is a composite style that combines PairLJ126Style and PairCoulLongStyle. The name is 'lj/cut/coul/long' for LAMMPS compatibility.

Parameters:

Name	Type	Description	Default
`lj_cutoff`	`float`	LJ cutoff distance in Angstroms (default: 10.0)	`10.0`
`coul_cutoff`	`float`	Coulomb cutoff distance in Angstroms (default: 10.0)	`10.0`
`coulomb14scale`	`float`	1-4 Coulomb scaling factor (default: 0.5)	`0.5`
`lj14scale`	`float`	1-4 LJ scaling factor (default: 0.5)	`0.5`

def_type ¶

def_type(itom, jtom=None, epsilon=0.0, sigma=0.0, charge=0.0, name='')

Define LJ 12-6 pair type (same as PairLJ126Style).

Parameters:

Name	Type	Description	Default
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType \| None`	Second atom type (None for self-interaction)	`None`
`epsilon`	`float`	LJ epsilon parameter	`0.0`
`sigma`	`float`	LJ sigma parameter	`0.0`
`charge`	`float`	Atomic charge (optional)	`0.0`
`name`	`str`	Optional name	`''`

Returns:

Type	Description
`PairLJ126Type`	PairLJ126Type instance

to_potential ¶

to_potential()

Convert this style to a Potential object.

PairLJ126Style ¶

PairLJ126Style(cutoff=10.0)

Bases: PairStyle

Lennard-Jones 12-6 pair style with fixed name='lj126'.

Parameters:

Name	Type	Description	Default
`cutoff`	`float`	Cutoff distance in Angstroms (default: 10.0)	`10.0`

def_type ¶

def_type(itom, jtom=None, epsilon=0.0, sigma=0.0, charge=0.0, name='')

Define LJ 12-6 pair type.

Parameters:

Name	Type	Description	Default
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType \| None`	Second atom type (None for self-interaction)	`None`
`epsilon`	`float`	LJ epsilon parameter	`0.0`
`sigma`	`float`	LJ sigma parameter	`0.0`
`charge`	`float`	Atomic charge (optional)	`0.0`
`name`	`str`	Optional name	`''`

Returns:

Type	Description
`PairLJ126Type`	PairLJ126Type instance

PairLJ126Type ¶

PairLJ126Type(name, itom, jtom=None, epsilon=0.0, sigma=0.0, charge=0.0)

Bases: PairType

Lennard-Jones 12-6 pair type with epsilon and sigma parameters.

Parameters:

Name	Type	Description	Default
`name`	`str`	Type name	required
`itom`	`AtomType`	First atom type	required
`jtom`	`AtomType \| None`	Second atom type (None for self-interaction)	`None`
`epsilon`	`float`	LJ epsilon parameter	`0.0`
`sigma`	`float`	LJ sigma parameter	`0.0`
`charge`	`float`	Atomic charge (optional)	`0.0`

PairLJClass2Style ¶

PairLJClass2Style(**style_kwargs)

Bases: PairStyle

Class2 LJ (12-9): E = epsilon * (2*(sigma/r)^9 - 3*(sigma/r)^6).

PairMorseStyle ¶

PairMorseStyle(**style_kwargs)

Bases: PairStyle

Morse: E = D0 * ((1 - exp(-alpha*(r-r0)))^2 - 1).

PairPotential ¶

Bases: Potential

Base class for pair potentials.

Pair Params¶

pair_params ¶

Specialized TypeIndexedArray for pair potentials with combining rules.

PairTypeIndexedArray ¶

PairTypeIndexedArray(data, combining_rule='geometric')

Bases: TypeIndexedArray

Specialized TypeIndexedArray for pair potential parameters.

Handles combining rules (Lorentz-Berthelot, geometric, etc.) for computing pair parameters from individual atom type parameters.

For pair potentials, we store per-atom-type parameters (epsilon, sigma) and apply combining rules when indexing with two atom types.

Examples:

>>> # Create with per-atom-type parameters
>>> epsilon = PairTypeIndexedArray(
...     {'opls_135': 0.066, 'opls_140': 0.030},
...     combining_rule='geometric'
... )
>>>
>>> # Index with single type (self-interaction)
>>> epsilon['opls_135']  # 0.066
>>>
>>> # Index with two types (cross-interaction, uses combining rule)
>>> epsilon[('opls_135', 'opls_140')]  # sqrt(0.066 * 0.030) = 0.0445
>>>
>>> # Array indexing with pairs
>>> pairs = np.array([['opls_135', 'opls_140'], ['opls_140', 'opls_140']])
>>> epsilon[pairs]  # [0.0445, 0.030]

Initialize PairTypeIndexedArray.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, float] \| NDArray[floating] \| float`	Dictionary mapping atom type names to parameters, or array	required
`combining_rule`	`Literal['geometric', 'arithmetic', 'harmonic']`	Rule for combining parameters: - 'geometric': sqrt(a * b) - for epsilon - 'arithmetic': (a + b) / 2 - for sigma - 'harmonic': 2 * a * b / (a + b) - alternative	`'geometric'`

get_pair_array ¶

get_pair_array(type_pairs)

Get combined parameters for an array of type pairs.

Parameters:

Name	Type	Description	Default
`type_pairs`	`NDArray`	Array of shape (n_pairs, 2) with type labels or indices	required

Returns:

Type	Description
`NDArray[floating]`	Array of combined parameters for each pair

get_pair_matrix ¶

get_pair_matrix()

Get full pair parameter matrix for all type combinations.

Returns:

Type	Description
`NDArray[floating]`	Matrix of shape (n_types, n_types) with combined parameters
`NDArray[floating]`	for all pairs of atom types

create_lj_parameters ¶

create_lj_parameters(epsilon_dict, sigma_dict)

Create LJ parameter arrays with standard Lorentz-Berthelot combining rules.

Parameters:

Name	Type	Description	Default
`epsilon_dict`	`dict[str, float]`	Per-atom-type epsilon values	required
`sigma_dict`	`dict[str, float]`	Per-atom-type sigma values	required

Returns:

Type	Description
`tuple[PairTypeIndexedArray, PairTypeIndexedArray]`	Tuple of (epsilon_array, sigma_array) with combining rules applied

Example

epsilon_dict = {'opls_135': 0.066, 'opls_140': 0.030} sigma_dict = {'opls_135': 3.5, 'opls_140': 2.5} epsilon, sigma = create_lj_parameters(epsilon_dict, sigma_dict)

Get cross-interaction parameters¶

eps_ij = epsilon[('opls_135', 'opls_140')] # sqrt(0.066 * 0.030) sig_ij = sigma[('opls_135', 'opls_140')] # (3.5 + 2.5) / 2

Utils¶

utils ¶

Utility functions and classes for potentials.

TypeIndexedArray ¶

TypeIndexedArray(data)

Array-like container that supports both integer and string type name indexing.

This class allows potentials to accept either integer indices or string type labels for indexing parameters. It maintains an internal mapping between type names and indices.

Examples:

>>> # Create from dictionary (type name -> value)
>>> k = TypeIndexedArray({"CT-CT": 100.0, "CT-OH": 80.0})
>>> k[0]  # Access by integer index
100.0
>>> k["CT-CT"]  # Access by type name
100.0
>>> k[np.array([0, 1])]  # Array indexing with integers
array([100.,  80.])
>>> k[np.array(["CT-CT", "CT-OH"])]  # Array indexing with strings
array([100.,  80.])

>>> # Create from array (for backward compatibility)
>>> k = TypeIndexedArray(np.array([100.0, 80.0]))
>>> k[0]
100.0

Initialize TypeIndexedArray.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, float] \| NDArray[floating] \| float`	Either a dictionary mapping type names to values, or an array/float for backward compatibility	required

type_names `property` ¶

type_names

Get the list of type names (if available).

values `property` ¶

values

Get the underlying values array.

reshape ¶

reshape(*args, **kwargs)

Reshape the values array (for backward compatibility).

calc_energy_from_frame ¶

calc_energy_from_frame(potential, frame)

Calculate energy from Frame for a potential.

This is a convenience function that extracts the necessary data from Frame and calls the potential's calc_energy method.

Parameters:

Name	Type	Description	Default
`potential`	`Potential`	Potential instance	required
`frame`	`Frame`	Frame containing the necessary data	required

Returns:

Type	Description
`float`	Potential energy

Raises:

Type	Description
`TypeError`	If potential type is not recognized
`ValueError`	If required data is missing from frame

calc_energy_from_frame_multi ¶

calc_energy_from_frame_multi(potentials, frame)

Calculate total energy from multiple potentials.

calc_forces_from_frame ¶

calc_forces_from_frame(potential, frame)

Calculate forces from Frame for a potential.

This is a convenience function that extracts the necessary data from Frame and calls the potential's calc_forces method.

Parameters:

Name	Type	Description	Default
`potential`	`Potential`	Potential instance	required
`frame`	`Frame`	Frame containing the necessary data	required

Returns:

Type	Description
`NDArray`	Array of forces on each atom (shape: (n_atoms, 3))

Raises:

Type	Description
`TypeError`	If potential type is not recognized
`ValueError`	If required data is missing from frame

extract_angle_data ¶

extract_angle_data(frame)

Extract angle data from Frame.

Returns:

Type	Description
`NDArray`	(r, angle_idx, angle_types) where:
`NDArray`	r: atom coordinates (n_atoms, 3)
`NDArray`	angle_idx: angle indices (n_angles, 3)
`tuple[NDArray, NDArray, NDArray]`	angle_types: angle types (n_angles,) - can be integers or strings

extract_bond_data ¶

extract_bond_data(frame)

Extract bond data from Frame.

Returns:

Type	Description
`NDArray`	(r, bond_idx, bond_types) where:
`NDArray`	r: atom coordinates (n_atoms, 3)
`NDArray`	bond_idx: bond indices (n_bonds, 2)
`tuple[NDArray, NDArray, NDArray]`	bond_types: bond types (n_bonds,) - can be integers or strings

extract_coul_data ¶

extract_coul_data(frame)

Extract Coulomb interaction data from Frame.

extract_pair_data ¶

extract_pair_data(frame)

Extract pair interaction data from Frame.

Generates all pairwise interactions between atoms and calculates displacement vectors and distances.

Returns:

Name	Type	Description
`tuple`	`tuple`	A tuple `(dr, dr_norm, pair_types_i, pair_types_j, pair_idx, n_atoms)` where dr is displacement vectors (n_pairs, 3), dr_norm is pair distances (n_pairs,), pair_types_i is atom types for first atom in each pair (n_pairs,), pair_types_j is atom types for second atom in each pair (n_pairs,), pair_idx is pair indices (n_pairs, 2), and n_atoms is the number of atoms.

Potential¶

Quick reference¶

Canonical example¶

Related¶

Full API¶

Base¶

base ¶

Potential ¶

calc_energy ¶

Parameters¶

Returns¶

calc_forces ¶

Parameters¶

Returns¶

Potentials ¶

calc_energy ¶

Parameters¶

Returns¶

calc_forces ¶

Parameters¶

Returns¶

Bond¶

bond ¶

BondClass2Style ¶

BondHarmonic ¶

calc_energy ¶

calc_forces ¶

BondHarmonicStyle ¶

def_type ¶

BondHarmonicType ¶

BondMorseStyle ¶

BondPotential ¶

Angle¶

angle ¶

AngleClass2BondAngleStyle ¶

AngleClass2BondBondStyle ¶

AngleClass2Style ¶

AngleHarmonic ¶

calc_energy ¶

calc_forces ¶

AngleHarmonicStyle ¶

def_type ¶

AngleHarmonicType ¶

AnglePotential ¶

Dihedral¶

dihedral ¶

DihedralCharmmStyle ¶

DihedralClass2Style ¶

DihedralFourierStyle ¶

def_type ¶

DihedralMultiHarmonicStyle ¶

DihedralOPLSStyle ¶

def_type ¶

to_lammps_params ¶

DihedralOPLSType ¶

DihedralPeriodicStyle ¶

DihedralPeriodicType ¶

Pair¶

pair ¶

CoulCut ¶

calc_energy ¶

calc_forces ¶

LJ126 ¶

calc_energy ¶

calc_forces ¶

LJ126CoulLong ¶

calc_energy ¶

calc_forces ¶

PairBuckStyle ¶

PairCoulLongStyle ¶

PairLJ126CoulCutStyle ¶

def_type ¶

PairLJ126CoulLongStyle ¶

def_type ¶

to_potential ¶

PairLJ126Style ¶

def_type ¶

PairLJ126Type ¶

PairLJClass2Style ¶

PairMorseStyle ¶

type_names `property` ¶

values `property` ¶