charmm_terms

CHARMM-specific molecular mechanics force-term primitives.

import mlx_atomistic.charmm_terms

Classes

CHARMMCMAPPotential

class CHARMMCMAPPotential
    def __init__(charmm_cmap_terms: object, cmap_grids: object, cmap_indices: object | None = None, name: str = 'charmm_cmap_terms', supports_virial: bool = True)

CHARMM CMAP two-dihedral correction term with periodic bicubic interpolation.

Parameters

Name	Type	Default	Description
charmm_cmap_terms	object
cmap_grids	object
cmap_indices	object | None	None
name	str	'charmm_cmap_terms'
supports_virial	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 CMAP energy and per-atom forces (forces via autodiff).

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 CHARMM CMAP two-dihedral correction 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.

Returns

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

CHARMMForceSwitchNonbondedPotential

class CHARMMForceSwitchNonbondedPotential
    def __init__(sigma: object, epsilon: object, charges: object, cutoff: float, switch_distance: float, coulomb_constant: float = 1.0, lj_shift: bool = False, coulomb_shift: bool = False, topology: object | 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, backend: str = 'auto', tile_size: int = 512, memory_budget_bytes: int | None = None, name: str = 'charmm_force_switch_nonbonded', supports_virial: bool = True)

CHARMM LJ force-switch nonbonded primitive.

Parameters

Name	Type	Default	Description
sigma	object
epsilon	object
charges	object
cutoff	float
switch_distance	float
coulomb_constant	float	1.0
lj_shift	bool	False
coulomb_shift	bool	False
topology	object | 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
backend	str	'auto'
tile_size	int	512
memory_budget_bytes	int | None	None
name	str	'charmm_force_switch_nonbonded'
supports_virial	bool	True

Methods

component_energies

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

Return separate LJ and Coulomb force-switched energy components.

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] — 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 the force-switched LJ and 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).

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 in one pass.

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, components) tuple.

potential_energy

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

Return the force-switched LJ and 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 force-switched nonbonded energy as a scalar array.

CHARMMNBFIXPairOverridePotential

class CHARMMNBFIXPairOverridePotential
    def __init__(sigma: object, epsilon: object, charges: object, nbfix_pairs: object, nbfix_sigma: object, nbfix_epsilon: object, coulomb_constant: float = 1.0, cutoff: float | None = 2.5, switch_distance: float | None = None, lj_shift: bool = False, coulomb_shift: bool = False, backend: str = 'auto', name: str = 'nbfix_pair_overrides', supports_virial: bool = True)

CHARMM NBFIX-style explicit-pair LJ override layered over regular nonbonded terms.

Parameters

Name	Type	Default	Description
sigma	object
epsilon	object
charges	object
nbfix_pairs	object
nbfix_sigma	object
nbfix_epsilon	object
coulomb_constant	float	1.0
cutoff	float | None	2.5
switch_distance	float | None	None
lj_shift	bool	False
coulomb_shift	bool	False
backend	str	'auto'
name	str	'nbfix_pair_overrides'
supports_virial	bool	True

Methods

component_energies

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

Return nonbonded components with the NBFIX LJ correction folded into the LJ term.

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	Must be None — NBFIX overrides require full-system evaluation. Defaults to None.

Returns

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

Raises

• ValueError — If pairs is not None.

energy_forces

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

Return the NBFIX-corrected nonbonded 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	Must be None — NBFIX overrides require full-system evaluation. 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 pairs is not None.

potential_energy

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

Return the base nonbonded energy plus the NBFIX explicit-pair LJ correction.

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 NBFIX-corrected nonbonded energy as a scalar array.

CHARMMUreyBradleyPotential

class CHARMMUreyBradleyPotential
    def __init__(urey_bradley_terms: object, k: object, distance: object, name: str = 'urey_bradley', supports_virial: bool = True)

CHARMM Urey-Bradley 1-3 distance term for angle triplets.

Parameters

Name	Type	Default	Description
urey_bradley_terms	object
k	object
distance	object
name	str	'urey_bradley'
supports_virial	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 Urey-Bradley 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 CHARMM Urey-Bradley 1-3 energy 0.5 * sum(k * (r13 - 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 Urey-Bradley energy as a scalar array.