matcalc._md module

Calculator for MD properties.

class MDCalc(calculator: Calculator, *, ensemble: Literal['nve', 'nvt', 'nvt_nose_hoover', 'nvt_berendsen', 'nvt_langevin', 'nvt_andersen', 'nvt_bussi', 'npt', 'npt_nose_hoover', 'npt_berendsen', 'npt_inhomogeneous', 'npt_isotropic_mtk'] = 'nvt', temperature: int = 300, timestep: float = 1.0, steps: int = 100, pressure: float = 6.324209121801212e-07, taut: float | None = None, taup: float | None = None, friction: float = 0.001, andersen_prob: float = 0.01, ttime: float = 25.0, pfactor: float = 5625.0, external_stress: float | np.ndarray | None = None, compressibility_au: float | None = None, tchain: int = 3, pchain: int = 3, tloop: int = 1, ploop: int = 1, trajfile: Any = None, logfile: str | None = None, loginterval: int = 1, append_trajectory: bool = False, mask: tuple | np.ndarray | None = None, relax_structure: bool = True, fmax: float = 0.1, optimizer: str = 'FIRE', frames: int | None = None, relax_calc_kwargs: dict | None = None)[source]

Bases: PropCalc

Performs molecular dynamics (MD) simulations on the input structure to calculate the final energy and obtain the final structure. Optionally, the structure is relaxed prior to the MD simulation. The simulation setup is flexible, supporting various ensembles (e.g., “nvt”, “nve”, “npt”, etc.) and user-defined parameters such as temperature, time step, and number of steps.

Initializes an MDCalc instance with the specified simulation parameters and relaxation settings.

Parameters:

  • calculator (Calculator) – The calculator used for energy, force, and stress evaluations. Default to the provided calculator.

  • ensemble (str) – Ensemble for MD simulation. Options include “nve”, “nvt_langevin”, “nvt_andersen”, “nvt_bussi”, “npt”, “npt_berendsen”, “npt_nose_hoover”, “npt_mtk”. Default to “nvt”.

  • temperature (int) – Simulation temperature in Kelvin. Default to 300.

  • timestep (float) – Time step in femtoseconds. Default to 1.0.

  • steps (int) – Number of MD simulation steps. Default to 100.

  • pressure (float) – External pressure for NPT simulations (in eV/ų). Default to 1.01325 * units.bar.

  • taut (float | None) – Time constant for temperature coupling. If None, defaults to 100 * timestep * fs. For npt_isotropic_mtk, this is the time constant for temperature damping.

  • taup (float | None) – Time constant for pressure coupling. If None, defaults to 1000 * timestep * fs. For npt_isotropic_mtk, this is the time constant for pressure damping.

  • friction (float) – Friction coefficient for Langevin dynamics. Default to 1.0e-3.

  • andersen_prob (float) – Collision probability for Andersen thermostat. Default to 1.0e-2.

  • ttime (float) – Characteristic time scale for the thermostat in ASE units (fs). Default to 25.0.

  • pfactor (float) – Barostat differential equation constant. Default to 75.0**2.0.

  • external_stress (float | np.ndarray | None) – External stress applied to the system. If not provided, defaults to 0.0.

  • compressibility_au (float | None) – Material compressibility in ų/eV. Default to None.

  • tchain (int) – The number of thermostat variables in the Nose-Hoover thermostat. Default to 3. Only used by IsotropicMTKNPT.

  • pchain (int) – The number of barostat variables in the Nose-Hoover barostat. Default to 3. Only used by IsotropicMTKNPT.

  • tloop (int) – The number of sub-steps in thermostat integration. Default to 1. Only used by IsotropicMTKNPT.

  • ploop (int) – T The number of sub-steps in barostat integration. Default to 1. Only used by IsotropicMTKNPT.

  • trajfile (Any) – Trajectory object or file for storing simulation data. Default to None.

  • logfile (str | None) – Filename for simulation logs. Default to None.

  • loginterval (int) – Interval (in steps) for logging simulation data. Default to 1.

  • append_trajectory (bool) – Whether to append to an existing trajectory file. Default to False.

  • mask (tuple | np.ndarray | None) – Constraint mask for NPT simulation cell deformations. If not provided, defaults to np.array([(1, 0, 0), (0, 1, 0), (0, 0, 1)]).

  • relax_structure (bool) – Whether to relax the input structure before MD simulation. Default to True.

  • fmax (float) – Maximum force tolerance for structure relaxation (in eV/Å). Default to 0.1.

  • optimizer (str) – Optimizer used for structure relaxation. Default to “FIRE”.

  • frames (int) – Number of MD frames for analysis. Default to None, which means all frames will be

  • returned

  • i.e.

  • steps. (frames =)

  • relax_calc_kwargs (dict | None) – Additional keyword arguments for the relaxation calculation. Default to None.

_abc_impl = <_abc._abc_data object>[source]
_initialize_md(atoms: Atoms) → Any[source]

Initializes the MD simulation object based on the provided ASE atoms object and simulation parameters.

Parameters:

atoms (Atoms) – ASE atoms object representing the structure.

Returns:

An MD simulation object (e.g., an instance of NVTBerendsen, VelocityVerlet, etc.)

_upper_triangular_cell(atoms: Atoms) → None[source]

Transforms the cell of the given atoms object to an upper triangular form if it is not already, as required by the Nose-Hoover NPT implementation.

Parameters:

atoms (Atoms) – ASE atoms object.

calc(structure: Structure | Atoms | dict[str, Any]) → dict[str, Any][source]

Performs the MD simulation calculation for the input structure. Prior to generating initial velocities, this method calls the superclass’s calc method for preprocessing and optionally relaxes the structure. It then initializes the atomic velocities using the Maxwell-Boltzmann distribution, runs the MD simulation, and returns the final energy along with the final atomic configuration.

Parameters:

structure (Structure | Atoms | dict[str, Any]) – Input structure as a Structure instance or a dictionary.

Returns:

A dictionary containing the final energy and the final atomic configuration.

It includes the keys “final_structure” and “energy”.

Return type:

dict