forcefields

Molecular mechanics force terms.

import mlx_atomistic.forcefields

Classes

CoulombPotential

class CoulombPotential
    def __init__(charges: object | None = None, coulomb_constant: float = 1.0, cutoff: float | None = None, shift: bool = False, topology: Topology | None = None, one_four_scale: float = 1.0, name: str = 'coulomb', supports_virial: bool = True, analytic_virial_supported: bool = False)

Direct pair Coulomb potential in reduced units.

Parameters

Name	Type	Default	Description
charges	object | None	None
coulomb_constant	float	1.0
cutoff	float | None	None
shift	bool	False
topology	Topology | None	None
one_four_scale	float	1.0
name	str	'coulomb'
supports_virial	bool	True
analytic_virial_supported	bool	False

Methods

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return the direct pair Coulomb energy and per-atom forces.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Optional explicit atom-pair list, shape (n_pairs, 2); None evaluates all unique pairs. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

potential_energy

def potential_energy(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> mx.array

Return the direct pair Coulomb energy.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Optional explicit atom-pair list, shape (n_pairs, 2); None evaluates all unique pairs. Defaults to None.

Returns

• mx.array — Total Coulomb energy as a scalar array.

HarmonicAnglePotential

class HarmonicAnglePotential
    def __init__(angles: object, k: object, angle: object, name: str = 'angle', supports_virial: bool = True, analytic_virial_supported: bool = True)

Harmonic angle bend potential.

Parameters

Name	Type	Default	Description
angles	object
k	object
angle	object
name	str	'angle'
supports_virial	bool	True
analytic_virial_supported	bool	True

Methods

analytic_virial_tensor

def analytic_virial_tensor(positions: mx.array, *, cell: Cell, pairs: object | None, masses: mx.array | None, molecule_ids: object | None) -> mx.array

Return the analytic molecular diagonal cell-strain virial.

Parameters

Name	Type	Default	Description
positions	mx.array
cell	Cell
pairs	object | None
masses	mx.array | None
molecule_ids	object | None

Returns

• mx.array

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return the harmonic angle-bend energy and per-atom forces.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Accepted for interface uniformity and ignored; the term uses its stored index list. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

potential_energy

def potential_energy(positions: mx.array, cell: Cell | None = None) -> mx.array

Return the harmonic angle-bend energy 0.5 * sum(k * (theta - theta0)**2).

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.

Returns

• mx.array — Total angle-bend energy as a scalar array.

HarmonicBondPotential

class HarmonicBondPotential
    def __init__(bonds: object, k: object, length: object, name: str = 'bond', supports_virial: bool = True, analytic_virial_supported: bool = True)

Harmonic bond stretch potential.

Parameters

Name	Type	Default	Description
bonds	object
k	object
length	object
name	str	'bond'
supports_virial	bool	True
analytic_virial_supported	bool	True

Methods

analytic_virial_tensor

def analytic_virial_tensor(positions: mx.array, *, cell: Cell, pairs: object | None, masses: mx.array | None, molecule_ids: object | None) -> mx.array

Return the analytic molecular diagonal cell-strain virial.

Parameters

Name	Type	Default	Description
positions	mx.array
cell	Cell
pairs	object | None
masses	mx.array | None
molecule_ids	object | None

Returns

• mx.array

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return the harmonic bond-stretch energy and per-atom forces.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Accepted for interface uniformity and ignored; the term uses its stored index list. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

potential_energy

def potential_energy(positions: mx.array, cell: Cell | None = None) -> mx.array

Return the harmonic bond-stretch energy 0.5 * sum(k * (r - r0)**2).

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.

Returns

• mx.array — Total bond-stretch energy as a scalar array.

ImproperDihedralPotential

class ImproperDihedralPotential(PeriodicDihedralPotential)
    def __init__(dihedrals: object, k: object, periodicity: object, phase: object = 0.0, name: str = 'improper', supports_virial: bool = True, analytic_virial_supported: bool = True)

Periodic or CHARMM-harmonic improper torsion potential.

A positive periodicity uses the periodic torsion form inherited from PeriodicDihedralPotential. A zero periodicity is the artifact sentinel for the CHARMM harmonic form k * wrap(phi + phase)**2. The plus sign maps the stored CHARMM/OpenMM equilibrium angle onto this runtime’s opposite signed dihedral convention.

Parameters

Name	Type	Default	Description
dihedrals	object
k	object
periodicity	object
phase	object	0.0
name	str	'improper'
supports_virial	bool	True
analytic_virial_supported	bool	True

Methods

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return the mixed improper energy and per-atom forces.

Parameters

Name	Type	Default	Description
positions	mx.array
cell	Cell | None	None
pairs	mx.array | None	None

Returns

• tuple[mx.array, mx.array]

potential_energy

def potential_energy(positions: mx.array, cell: Cell | None = None) -> mx.array

Return the mixed periodic and CHARMM-harmonic improper energy.

Parameters

Name	Type	Default	Description
positions	mx.array
cell	Cell | None	None

Returns

• mx.array

NonbondedPotential

class NonbondedPotential
    def __init__(sigma: object, epsilon: object, charges: object, coulomb_constant: float = 1.0, cutoff: float | None = 2.5, lj_shift: bool = True, coulomb_shift: bool = False, electrostatics: NonbondedElectrostatics = 'cutoff', switch_distance: float | None = None, topology: Topology | None = None, lj_one_four_scale: float = 1.0, coulomb_one_four_scale: float = 1.0, exception_pairs: object = (), exception_charge_products: object | None = None, exception_sigma: object | None = None, exception_epsilon: object | None = None, atom_types: object | None = None, nbfix_pairs: object = (), nbfix_sigma: object | None = None, nbfix_epsilon: object | None = None, nbfix_type_pairs: object = (), nbfix_type_sigma: object | None = None, nbfix_type_epsilon: object | None = None, backend: NonbondedBackend = 'auto', ewald_config: EwaldReferenceConfig | None = None, pme_config: PMEConfig | None = None, pme_plan: PMEExecutionPlan | None = None, tile_size: int = 512, memory_budget_bytes: int | None = DEFAULT_DENSE_MEMORY_BUDGET_BYTES, lambda_lj: float = 1.0, lambda_electrostatics: float = 1.0, use_dispersion_correction: bool = False, name: str = 'nonbonded', supports_virial: bool = True)

Combined Lennard-Jones and Coulomb pair potential.

Parameters

Name	Type	Default	Description
sigma	object
epsilon	object
charges	object
coulomb_constant	float	1.0
cutoff	float | None	2.5
lj_shift	bool	True
coulomb_shift	bool	False
electrostatics	NonbondedElectrostatics	'cutoff'
switch_distance	float | None	None
topology	Topology | None	None
lj_one_four_scale	float	1.0
coulomb_one_four_scale	float	1.0
exception_pairs	object	()
exception_charge_products	object | None	None
exception_sigma	object | None	None
exception_epsilon	object | None	None
atom_types	object | None	None
nbfix_pairs	object	()
nbfix_sigma	object | None	None
nbfix_epsilon	object | None	None
nbfix_type_pairs	object	()
nbfix_type_sigma	object | None	None
nbfix_type_epsilon	object | None	None
backend	NonbondedBackend	'auto'
ewald_config	EwaldReferenceConfig | None	None
pme_config	PMEConfig | None	None
pme_plan	PMEExecutionPlan | None	None
tile_size	int	512
memory_budget_bytes	int | None	DEFAULT_DENSE_MEMORY_BUDGET_BYTES
lambda_lj	float	1.0
lambda_electrostatics	float	1.0
use_dispersion_correction	bool	False
name	str	'nonbonded'
supports_virial	bool	True

Properties

• has_exceptions bool — Whether explicit nonbonded pair overrides are active.
• has_nbfix bool — Whether NBFIX LJ overrides are active.
• has_soft_core bool — Whether lambda-scaled soft-core pair evaluation is active.
• pme_plan_diagnostics dict[str, object] | None — Diagnostics for the bound PME plan, or None when unbound.

Methods

analytic_virial_tensor

def analytic_virial_tensor(positions: mx.array, *, cell: Cell, pairs: object | None, masses: mx.array | None, molecule_ids: object | None) -> mx.array

Return the analytic molecular diagonal cell-strain virial.

Parameters

Name	Type	Default	Description
positions	mx.array		Particle coordinates, shape (n_atoms, 3).
cell	Cell		Source orthorhombic periodic cell.
pairs	object | None		Neighbor blocks or compact pairs held fixed during the local cell derivative.
masses	mx.array | None		Optional per-particle masses for molecular centers.
molecule_ids	object | None		Optional contiguous per-particle molecule identifiers.

Returns

• mx.array — The diagonal (3, 3) configurational virial tensor.

Raises

• ValueError — If this configuration is outside the admitted analytic virial envelope.

bind_pme_plan

def bind_pme_plan(plan: PMEExecutionPlan | Cell) -> NonbondedPotential

Return a copy explicitly bound to a compatible fixed-cell PME plan.

Parameters

Name	Type	Default	Description
plan	PMEExecutionPlan | Cell		Existing compatible plan, or an orthorhombic cell from which to build one.

Returns

• NonbondedPotential — A new potential that reuses the bound plan for every PME scope.

Raises

• ValueError — If this potential is not configured for PME or the plan does not match its configuration.

build_pme_plan

def build_pme_plan(cell: Cell) -> PMEExecutionPlan

Build a compatible fixed-cell PME execution plan for this potential.

Parameters

Name	Type	Default	Description
cell	Cell		Orthorhombic periodic cell to bind.

Returns

• PMEExecutionPlan — A materialized plan matching this potential’s PME configuration and
• PMEExecutionPlan — Coulomb constant.

Raises

• ValueError — If this potential does not use PME electrostatics.

component_energies

def component_energies(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> dict[str, mx.array | object]

Return LJ and Coulomb energy components.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell for minimum-image distances. Defaults to None.
pairs	mx.array | None	None	Optional precomputed neighbor/pair structure. Defaults to None.

Returns

• dict[str, mx.array | object] — A dict of named energy components (e.g. "lj", "coulomb").

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return total nonbonded energy and forces.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell for minimum-image distances. Defaults to None.
pairs	mx.array | None	None	Optional precomputed neighbor/pair structure. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar total nonbonded energy and (n_atoms, 3) forces.

Raises

• ValueError — If positions is not (n_atoms, 3).

energy_forces_dlambda

def energy_forces_dlambda(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array, dict[str, mx.array]]

Return energy, forces, and analytic lambda derivatives.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell for minimum-image distances. Defaults to None.
pairs	mx.array | None	None	Optional precomputed neighbor/pair structure. Defaults to None.

Returns

• tuple[mx.array, mx.array, dict[str, mx.array]] — An (energy, forces, derivatives) tuple: scalar energy, (n_atoms, 3) forces, and a dict with "lambda_lj" and "lambda_electrostatics" dU/dλ terms.

Raises

• ValueError — If the electrostatics mode is not "cutoff" (the only mode with analytic dU/dλ).

energy_forces_for_scope

def energy_forces_for_scope(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None, *, scope: str = 'total') -> tuple[mx.array, mx.array]

Evaluate energy and forces through an explicit force scope.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell for minimum-image distances. Defaults to None.
pairs	mx.array | None	None	Optional precomputed neighbor/pair structure. Defaults to None.
scope	str	'total'	Force-evaluation scope to evaluate. Defaults to "total".

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple for the scope: scalar energy and (n_atoms, 3) forces.

Raises

• ValueError — If the scope is unsupported for this potential’s electrostatics or positions is not (n_atoms, 3).

energy_forces_with_components

def energy_forces_with_components(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array, dict[str, mx.array | object]]

Return total energy, forces, and LJ/Coulomb components in one pass.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell for minimum-image distances. Defaults to None.
pairs	mx.array | None	None	Optional precomputed neighbor/pair structure. Defaults to None.

Returns

• tuple[mx.array, mx.array, dict[str, mx.array | object]] — An (energy, forces, components) tuple: scalar total energy, (n_atoms, 3) forces, and a dict of "lj"/"coulomb" energies.

Raises

• ValueError — If positions is not (n_atoms, 3).

finite_difference_virial_tensor

def finite_difference_virial_tensor(positions: mx.array, *, cell: Cell, pairs: object | None, masses: mx.array | None, molecule_ids: object | None, strain_epsilon: float) -> mx.array

Return a component-wise finite-strain virial without total-energy cancellation.

Parameters

Name	Type	Default	Description
positions	mx.array
cell	Cell
pairs	object | None
masses	mx.array | None
molecule_ids	object | None
strain_epsilon	float

Returns

• mx.array

force_scope_report

def force_scope_report(scope: str = 'total') -> dict[str, object]

Return support metadata for a force-evaluation scope.

Parameters

Name	Type	Default	Description
scope	str	'total'	Force-evaluation scope to query. Defaults to "total".

Returns

• dict[str, object] — A ForceScopeReport dict describing whether the scope is supported and how it is evaluated for this potential’s electrostatics.

mixed_pair_parameters

def mixed_pair_parameters(pairs) -> tuple[mx.array, mx.array]

Return mixed sigma and epsilon, with NBFIX LJ overrides substituted.

Parameters

Name	Type	Default	Description
pairs			Atom-index pairs, shape (n_pairs, 2).

Returns

• tuple[mx.array, mx.array] — A (sigma_ij, epsilon_ij) tuple of per-pair mixed LJ parameters, each shape (n_pairs,) (NBFIX overrides applied where defined).

PairRestrictedNonbondedPotential

class PairRestrictedNonbondedPotential
    def __init__(potential: NonbondedPotential, pairs: object, name: str = 'pair_restricted_nonbonded', supports_virial: bool = True, analytic_virial_supported: bool = False)

Nonbonded potential evaluated only on an explicit atom-pair list.

Parameters

Name	Type	Default	Description
potential	NonbondedPotential
pairs	object
name	str	'pair_restricted_nonbonded'
supports_virial	bool	True
analytic_virial_supported	bool	False

Methods

component_energies

def component_energies(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> dict[str, mx.array]

Return LJ and Coulomb components, evaluated on the fixed pair list.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Ignored; the fixed pair list supplied at construction is used. Defaults to None.

Returns

• dict[str, mx.array] — A dict of named energy components (e.g. "lj", "coulomb").

Raises

• ValueError — If the wrapped electrostatics needs full-system evaluation (ewald_reference / pme).

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return total nonbonded energy and forces on the fixed pair list.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Ignored; the fixed pair list supplied at construction is used. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

Raises

• ValueError — If the wrapped electrostatics needs full-system evaluation (ewald_reference / pme).

energy_forces_for_scope

def energy_forces_for_scope(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None, *, scope: str = 'total') -> tuple[mx.array, mx.array]

Evaluate energy and forces through an explicit force scope on the fixed pair list.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Ignored; the fixed pair list supplied at construction is used. Defaults to None.
scope	str	'total'	Force-evaluation scope, e.g. "total" or a direct/reciprocal-space component. Defaults to "total".

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

Raises

• ValueError — If scope is unsupported for pair-restricted evaluation.

energy_forces_with_components

def energy_forces_with_components(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array, dict[str, mx.array]]

Return energy, forces, and LJ/Coulomb components on the fixed pair list.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Ignored; the fixed pair list supplied at construction is used. Defaults to None.

Returns

• tuple[mx.array, mx.array, dict[str, mx.array]] — An (energy, forces, components) tuple.

Raises

• ValueError — If the wrapped electrostatics needs full-system evaluation (ewald_reference / pme).

force_scope_report

def force_scope_report(scope: str = 'total') -> dict[str, object]

Return force-scope support metadata for pair-restricted evaluation.

Parameters

Name	Type	Default	Description
scope	str	'total'	Force-evaluation scope, e.g. "total" or a direct/reciprocal-space component. Defaults to "total".

Returns

• dict[str, object] — A metadata dict describing whether the scope is supported and how it is evaluated; full-system scopes are marked unsupported.

PeriodicDihedralPotential

class PeriodicDihedralPotential
    def __init__(dihedrals: object, k: object, periodicity: object, phase: object = 0.0, name: str = 'dihedral', supports_virial: bool = True, analytic_virial_supported: bool = True)

Periodic torsion potential with the package dihedral-angle convention.

Parameters

Name	Type	Default	Description
dihedrals	object
k	object
periodicity	object
phase	object	0.0
name	str	'dihedral'
supports_virial	bool	True
analytic_virial_supported	bool	True

Methods

analytic_virial_tensor

def analytic_virial_tensor(positions: mx.array, *, cell: Cell, pairs: object | None, masses: mx.array | None, molecule_ids: object | None) -> mx.array

Return the analytic molecular diagonal cell-strain virial.

Parameters

Name	Type	Default	Description
positions	mx.array
cell	Cell
pairs	object | None
masses	mx.array | None
molecule_ids	object | None

Returns

• mx.array

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return the periodic torsion energy and per-atom forces.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Accepted for interface uniformity and ignored; the term uses its stored index list. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

potential_energy

def potential_energy(positions: mx.array, cell: Cell | None = None) -> mx.array

Return the periodic torsion energy sum(k * (1 + cos(n * phi + phase))).

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.

Returns

• mx.array — Total periodic torsion energy as a scalar array.

PositionalRestraintPotential

class PositionalRestraintPotential
    def __init__(reference_positions: object, mask: object, k: float, name: str = 'positional_restraint', supports_virial: bool = True, analytic_virial_supported: bool = False)

Harmonic positional restraint for selected atoms.

Parameters

Name	Type	Default	Description
reference_positions	object
mask	object
k	float
name	str	'positional_restraint'
supports_virial	bool	True
analytic_virial_supported	bool	False

Methods

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return the positional-restraint energy and per-atom forces.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Accepted for interface uniformity but unused; restraints act on absolute positions. Defaults to None.
pairs	mx.array | None	None	Accepted for interface uniformity and ignored; the term uses its stored index list. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

potential_energy

def potential_energy(positions: mx.array, cell: Cell | None = None) -> mx.array

Return the positional-restraint energy 0.5 * k * sum(mask * |x - x_ref|**2).

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Accepted for interface uniformity but unused; restraints act on absolute positions. Defaults to None.

Returns

• mx.array — Total restraint energy as a scalar array.

RBDihedralPotential

class RBDihedralPotential
    def __init__(dihedrals: object, c0: object, c1: object, c2: object, c3: object, c4: object, c5: object, name: str = 'rb_dihedral', supports_virial: bool = True, analytic_virial_supported: bool = False)

Ryckaert-Bellemans torsion potential.

Uses the OpenMM RB convention: E = sum(Cn * cos(phi - pi)^n), where phi is the package/OpenMM-style periodic dihedral angle.

Parameters

Name	Type	Default	Description
dihedrals	object
c0	object
c1	object
c2	object
c3	object
c4	object
c5	object
name	str	'rb_dihedral'
supports_virial	bool	True
analytic_virial_supported	bool	False

Methods

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return the Ryckaert-Bellemans torsion energy and per-atom forces.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Accepted for interface uniformity and ignored; the term uses its stored index list. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

potential_energy

def potential_energy(positions: mx.array, cell: Cell | None = None) -> mx.array

Return the Ryckaert-Bellemans torsion energy sum(Cn * cos(phi - pi)**n).

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.

Returns

• mx.array — Total Ryckaert-Bellemans torsion energy as a scalar array.

SoftCoreNonbondedPotential

class SoftCoreNonbondedPotential
    def __init__(potential: NonbondedPotential, lambda_lj: float = 1.0, lambda_electrostatics: float = 1.0, name: str = 'soft_core_nonbonded', supports_virial: bool = True, analytic_virial_supported: bool = False)

Lambda-scaled wrapper around a combined nonbonded potential.

Parameters

Name	Type	Default	Description
potential	NonbondedPotential
lambda_lj	float	1.0
lambda_electrostatics	float	1.0
name	str	'soft_core_nonbonded'
supports_virial	bool	True
analytic_virial_supported	bool	False

Properties

• electrostatics NonbondedElectrostatics — Electrostatics mode of the wrapped potential.
• sigma mx.array — Per-atom Lennard-Jones sigma of the wrapped potential.

Methods

component_energies

def component_energies(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> dict[str, mx.array | object]

Return LJ and Coulomb components from the lambda-scaled potential.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Optional explicit atom-pair list, shape (n_pairs, 2); None evaluates all unique pairs. Defaults to None.

Returns

• dict[str, mx.array | object] — A dict of named energy components (e.g. "lj", "coulomb").

energy_forces

def energy_forces(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array]

Return total energy and forces from the lambda-scaled potential.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Optional explicit atom-pair list, shape (n_pairs, 2); None evaluates all unique pairs. Defaults to None.

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

energy_forces_dlambda

def energy_forces_dlambda(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array, dict[str, mx.array]]

Return energy, forces, and analytic derivatives w.r.t. the coupling parameters.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Optional explicit atom-pair list, shape (n_pairs, 2); None evaluates all unique pairs. Defaults to None.

Returns

• tuple[mx.array, mx.array, dict[str, mx.array]] — An (energy, forces, derivatives) tuple; derivatives maps each coupling parameter to dE/dlambda.

energy_forces_for_scope

def energy_forces_for_scope(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None, *, scope: str = 'total') -> tuple[mx.array, mx.array]

Evaluate energy and forces through an explicit force scope (lambda-scaled).

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Optional explicit atom-pair list, shape (n_pairs, 2); None evaluates all unique pairs. Defaults to None.
scope	str	'total'	Force-evaluation scope, e.g. "total" or a direct/reciprocal-space component. Defaults to "total".

Returns

• tuple[mx.array, mx.array] — An (energy, forces) tuple: scalar energy and per-atom forces of shape (n_atoms, 3).

energy_forces_with_components

def energy_forces_with_components(positions: mx.array, cell: Cell | None = None, pairs: mx.array | None = None) -> tuple[mx.array, mx.array, dict[str, mx.array | object]]

Return energy, forces, and LJ/Coulomb components from the lambda-scaled potential.

Parameters

Name	Type	Default	Description
positions	mx.array		Atomic coordinates, shape (n_atoms, 3).
cell	Cell | None	None	Optional periodic cell; when given, distances use the minimum-image convention. Defaults to None.
pairs	mx.array | None	None	Optional explicit atom-pair list, shape (n_pairs, 2); None evaluates all unique pairs. Defaults to None.

Returns

• tuple[mx.array, mx.array, dict[str, mx.array | object]] — An (energy, forces, components) tuple.

force_scope_report

def force_scope_report(scope: str = 'total') -> dict[str, object]

Return force-scope support metadata from the wrapped potential.

Parameters

Name	Type	Default	Description
scope	str	'total'	Force-evaluation scope, e.g. "total" or a direct/reciprocal-space component. Defaults to "total".

Returns

• dict[str, object] — A metadata dict describing whether the scope is supported and how it is evaluated.