Base Classes¶

BaseCalculator ¶

BaseCalculator(
    fmax: float = 0.1,
    steps: int = 1000,
    optimizer: type[Optimizer] | str = "FIRE",
    relax_cell: bool = True,
    fix_symmetry: bool = False,
    fix_atoms: bool = False,
    hydrostatic_strain: bool = False,
    symprec: float = 0.01,
    traj_file: str | None = None,
    interval: int = 1,
    verbose: bool = False,
    params_asecellfilter: dict | None = None,
    include_magmoms: bool = False,
    include_dipoles: bool = False,
    **kwargs: Any,
)

Abstract base class for structure relaxers and calculators built on the Atomic Simulation Environment (ASE).

Subclasses must implement the AVAILABLE_PROPERTIES class attribute and the calculator property.

Attributes:

Name	Type	Description
`fmax`	`float`	Maximum force convergence criterion for relaxation.
`steps`	`int`	Maximum number of optimization steps.
`optimizer`	`Optimizer`	The optimization algorithm used for relaxation.
`relax_cell`	`bool`	Whether to relax the cell during optimization.
`fix_symmetry`	`bool`	Whether to enforce symmetry constraints during relaxation.
`fix_atoms`	`bool`	Whether to fix the positions of atoms during relaxation.
`hydrostatic_strain`	`bool`	Whether to apply hydrostatic strain during relaxation.
`sym_prec`	`float`	Symmetry precision used when applying symmetry constraints.
`traj_file`	`str or None`	Path to the trajectory file where the relaxation path will be saved.
`interval`	`int`	Frequency of recording trajectory steps.
`verbose`	`bool`	If True, prints detailed output during relaxation.
`params_asecellfilter`	`dict or None`	Additional parameters for ASE cell filter.
`include_magmoms`	`bool`	Whether to include magnetic moments in the trajectory.
`include_dipoles`	`bool`	Whether to include dipoles in the trajectory.

Initializes the BaseCalculator with parameters for structure relaxation.

Parameters:

Name	Type	Description	Default
`fmax`	`float`	Maximum force convergence criterion. Defaults to 0.1.	`0.1`
`steps`	`int`	Maximum number of optimization steps. Defaults to 1000.	`1000`
`optimizer`	`type[Optimizer] \| str`	The optimization algorithm to use. Can be either an Optimizer subclass or a string referring to one of the OPTIMIZERS enum members. Defaults to "FIRE".	`'FIRE'`
`relax_cell`	`bool`	If True, relaxes the unit cell dimensions. Defaults to True.	`True`
`fix_symmetry`	`bool`	If True, enforces symmetry constraints during relaxation. Defaults to False.	`False`
`fix_atoms`	`bool`	If True, fixes the positions of all atoms during relaxation. Defaults to False.	`False`
`hydrostatic_strain`	`bool`	If True, applies hydrostatic strain during cell relaxation. Defaults to False.	`False`
`symprec`	`float`	Symmetry precision for enforcing symmetry constraints. Defaults to 1e-2.	`0.01`
`traj_file`	`str or None`	Path to save the trajectory file. If None, trajectory is not saved. Defaults to None.	`None`
`interval`	`int`	Interval at which trajectory is recorded. Defaults to 1.	`1`
`verbose`	`bool`	If True, prints detailed output during relaxation. Defaults to False.	`False`
`params_asecellfilter`	`dict or None`	Additional parameters for the ASE cell filter. Defaults to None.	`None`
`include_magmoms`	`bool`	If True, includes magnetic moments in the trajectory. Defaults to False.	`False`
`include_dipoles`	`bool`	If True, includes dipoles in the trajectory. Defaults to False.	`False`
`**kwargs`	`Any`	Forwarded to the next class in the MRO (e.g. `BaseMDCalculator`), so cooperative subclasses can chain a single `super().__init__(**kwargs)` call instead of splitting kwargs by hand.	`{}`

AVAILABLE_PROPERTIES `abstractmethod` `classmethod` `property` ¶

AVAILABLE_PROPERTIES: list[str]

Abstract class-level property that must be defined in all subclasses.

Returns:

Type	Description
`list[str]`	list[str]: Names of the properties the calculator can compute, such as
`list[str]`	"potential_energy", "forces", or "stress".

calculator `abstractmethod` `property` ¶

calculator: Calculator

Returns the ASE Calculator object associated with this relaxer.

Subclasses of BaseCalculator must implement this property; the returned Calculator object performs the relaxation and calculation of structures within relax().

Raises:

Type	Description
`NotImplementedError`	If the subclass does not implement this property.

Returns:

Name	Type	Description
`Calculator`	`Calculator`	An ASE Calculator instance configured for the specific
	`Calculator`	relaxation and calculation task.

relax ¶

relax(
    structure: Atoms | Structure | Molecule, **kwargs: Any
) -> dict[str, Any]

Relaxes a given atomic structure using the specified optimizer and calculator.

Parameters:

Name	Type	Description	Default
`structure`	`Atoms \| Structure \| Molecule`	The atomic structure to relax. This can be an ASE `Atoms` object, a Pymatgen `Structure` object, or a Pymatgen `Molecule` object.	required
`**kwargs`	`Any`	Additional keyword arguments to pass to the optimizer during relaxation.	`{}`

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: Dictionary with keys: - `final_structure`: Final relaxed structure as a pymatgen `Structure`. - `trajectory`: `TrajectoryObserver` containing intermediate relaxation states. - Property keys from `AVAILABLE_PROPERTIES` (for example `energy`, `forces`, `stress`) populated from the calculator results.

Raises:

Type	Description
`ValueError`	If the structure cannot be relaxed.

calculate ¶

calculate(
    structure: Atoms | Structure | Molecule,
) -> dict[str, Any]

Performs a single-point calculation on the given atomic structure using the specified calculator.

No relaxation is performed. The properties to compute are defined in the AVAILABLE_PROPERTIES class attribute.

Parameters:

Name	Type	Description	Default
`structure`	`Atoms \| Structure \| Molecule`	The atomic structure to calculate. This can be an ASE `Atoms` object, a Pymatgen `Structure` object, or a Pymatgen `Molecule` object.	required

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: Dictionary with keys: - `final_structure`: Input structure as a pymatgen `Structure`. - Property keys from `AVAILABLE_PROPERTIES` (for example `energy`, `forces`, `stress`) populated from the calculator results.

BaseMDCalculator ¶

BaseMDCalculator(
    ensemble: Literal[
        "nve",
        "nvt_nose_hoover",
        "langevin",
        "andersen",
        "bussi",
        "nvt_berendsen",
        "nose_hoover_chain_nvt",
        "npt_nose_hoover",
        "isotropic_mtk_npt",
        "mtk_npt",
        "masked_mtk_npt",
        "npt_berendsen",
        "inhomogeneous_npt_berendsen",
    ] = "nve",
    timestep: float = 1.0,
    temperature: int = 300,
    pressure: float = 1,
    ttime: float = 10.0,
    pfactor: float = 75.0**2.0,
    friction: float = 0.01,
    andersen_prob: float = 0.01,
    taut: float = 500.0,
    taup: float = 1000.0,
    compressibility: float = 5e-07,
    mask: tuple[int, int, int] = (1, 1, 1),
    stationary: bool = True,
    zero_rotation: bool = True,
    logfile: str | None = None,
    loginterval: int = 1,
    interval: int = 1,
    **kwargs: Any,
)

A calculator class for performing Molecular Dynamics (MD) simulations using universal potentials.

Supports NVE, several NVT thermostats (Nose-Hoover, Langevin, Andersen, Bussi, Berendsen, and a Nose-Hoover chain), and several NPT barostats (Nose-Hoover, MTK and its isotropic/masked variants, and Berendsen and its inhomogeneous variant), with customizable parameters for temperature, pressure, and timestep. Also applies constraints such as fixing symmetry and initializing velocities before a simulation starts.

Initializes the BaseMDCalculator with the specified parameters for running MD simulations.

Parameters:

Name	Type	Description	Default
`ensemble`	`str`	The MD ensemble to run, one of "nve", "nvt_nose_hoover", "langevin", "andersen", "bussi", "nvt_berendsen", "nose_hoover_chain_nvt", "npt_nose_hoover", "isotropic_mtk_npt", "mtk_npt", "masked_mtk_npt", "npt_berendsen", or "inhomogeneous_npt_berendsen". Defaults to "nve".	`'nve'`
`timestep`	`float`	The timestep for the MD simulation in femtoseconds (fs). Defaults to 1.0 fs.	`1.0`
`temperature`	`int`	The temperature in Kelvin (K) for the MD simulation. Defaults to 300 K.	`300`
`pressure`	`float`	The pressure in atmospheres (atm) for the NPT ensemble. Defaults to 1 atm.	`1`
`ttime`	`float`	The time constant for temperature control in femtoseconds (fs). Defaults to 10.0 fs.	`10.0`
`pfactor`	`float`	Pressure factor for the NPT ensemble in fs^2. Defaults to 75.0^2 fs^2.	`75.0 ** 2.0`
`friction`	`float`	Friction coefficient for the Langevin thermostat, in fs^-1. Defaults to 0.01 fs^-1.	`0.01`
`andersen_prob`	`float`	Collision probability per step for the Andersen thermostat, typically between 1e-4 and 1e-1. Defaults to 1e-2.	`0.01`
`taut`	`float`	Time constant for Berendsen or Bussi temperature coupling in fs. Defaults to 0.5e3 fs.	`500.0`
`taup`	`float`	Time constant for Berendsen pressure coupling in fs. Defaults to 1e3 fs.	`1000.0`
`compressibility`	`float`	Compressibility for the NPT ensemble in 1/bar. Defaults to 5e-7 1/bar.	`5e-07`
`mask`	`tuple[int, int, int]`	Specifies which axes participate in the barostat for the Inhomogeneous NPT Berendsen and masked MTK NPT ensembles. Defaults to (1, 1, 1).	`(1, 1, 1)`
`stationary`	`bool`	Whether to set the center-of-mass motion to zero. Defaults to True.	`True`
`zero_rotation`	`bool`	Whether to set the total angular momentum to zero. Defaults to True.	`True`
`logfile`	`str \| None`	The file to log simulation output. If None, no logging occurs. Defaults to None.	`None`
`loginterval`	`int`	The interval at which to log the simulation results. Defaults to 1 (every step).	`1`
`interval`	`int`	The interval at which to record the simulation trajectory. Defaults to 1 (every step).	`1`
`**kwargs`	`Any`	Forwarded to the next class in the MRO, so cooperative subclasses can chain a single `super().__init__(**kwargs)` call instead of splitting kwargs by hand.	`{}`

Raises:

Type	Description
`ValueError`	If an unsupported ensemble type is provided.

calculator `abstractmethod` `property` ¶

calculator: Calculator

Returns the ASE Calculator object associated with this instance.

Subclasses of BaseMDCalculator must implement this property; the returned Calculator object performs the molecular dynamics calculation of structures within run().

Raises:

Type	Description
`NotImplementedError`	If the subclass does not implement this property.

Returns:

Name	Type	Description
`Calculator`	`Calculator`	An ASE Calculator instance configured for the specific
	`Calculator`	molecular dynamics task.

run ¶

run(
    structure: Atoms | Structure | Molecule, steps: int
) -> dict[str, Any]

Executes the Molecular Dynamics (MD) simulation using the specified calculator.

If structure has no velocities set, initial momenta are drawn from a Maxwell-Boltzmann distribution at temperature. If it already has velocities set (only possible by passing an ase.Atoms with set_velocities()/set_momenta() already called; pymatgen Structure/ Molecule carry no velocity information, and neither does this method's own final_structure output), those are kept as-is instead of being overwritten.

Parameters:

Name	Type	Description	Default
`structure`	`Atoms \| Structure \| Molecule`	The input atomic structure for the MD simulation.	required
`steps`	`int`	The number of MD steps to perform.	required

Returns:

Type Description

dict[str, Any]

dict[str, Any]: Dictionary with keys: - total_energy: Total energies at each recorded MD step (eV). - potential_energy: Potential energies at each recorded MD step (eV). - kinetic_energy: Kinetic energies at each recorded MD step (eV). - forces: Force arrays at each recorded MD step (eV/A). - stresses: Stress tensors at each recorded MD step. - temperature: Temperatures at each recorded MD step (K). - velocities: Velocity arrays at each recorded MD step. - final_structure: Final structure as a pymatgen Structure.

Base Classes¶

BaseCalculator ¶

AVAILABLE_PROPERTIES abstractmethod classmethod property ¶

calculator abstractmethod property ¶

relax ¶

calculate ¶

BaseMDCalculator ¶

calculator abstractmethod property ¶

run ¶

AVAILABLE_PROPERTIES `abstractmethod` `classmethod` `property` ¶

calculator `abstractmethod` `property` ¶

calculator `abstractmethod` `property` ¶