ASE Integration Module

Overview

The kim_convergence.ase module connects kim-convergence to the Atomic Simulation Environment (ASE). It drives an ASE MolecularDynamics object in chunks, collects one or more properties through ASE’s observer mechanism, and feeds them to kim_convergence.run_length_control() to automatically detect equilibration and control the run length.

Note

This module is optional and requires ASE. Install it with:

pip install ase

or, together with kim-convergence:

pip install kim-convergence[ase]

For a narrative, copy-paste-ready walkthrough see the ASE Integration example. A complete runnable script is provided in examples/ase/example_equilibration.py.

Equilibration Driver

Convergence-controlled equilibration for ASE molecular dynamics.

This module provides utilities for running equilibration phases with automatic convergence detection using kim-convergence.

class kim_convergence.ase.equilibration.ASESampler(dynamics: MolecularDynamics, property_names: str | List[str] = 'energy', sample_interval: int = 1, extractors: Dict[str, Callable[[Atoms], float]] | None = None)

Trajectory sampler for ASE molecular dynamics.

This sampler advances the MD simulation and collects property values for convergence analysis using kim-convergence. It uses ASE’s observer mechanism for efficient data collection.

Examples

>>> from ase.md.langevin import Langevin
>>> from kim_convergence.ase import ASESampler, run_ase_equilibration
>>>
>>> dyn = Langevin(atoms, timestep=1.0, temperature_K=300, friction=0.01)
>>> sampler = ASESampler(dyn, property_names="temperature")
>>> result = run_ase_equilibration(sampler, maximum_run_length=10000)

property num_properties: int: Return the number of properties being sampled

property total_steps: int: Return the total number of MD steps run so far.

kim_convergence.ase.equilibration.run_ase_equilibration(sampler: ASESampler, **kwargs: Any) → Dict[str, Any]

Run convergence-controlled equilibration for ASE molecular dynamics.

This function runs an equilibration phase using kim-convergence to automatically detect when the system has reached equilibrium.

Parameters:

sampler – An ASESampler instance that will be used to collect trajectory data during the simulation.
**kwargs –
Keyword arguments passed to kim_convergence.run_length_control(). Common options include: - initial_run_length (int): Initial samples before checking. Default: 10000. - maximum_run_length (int): Maximum samples to collect. Default: 1000000. - maximum_equilibration_step (int): Max samples for equilibration detection. - relative_accuracy (float): Target relative accuracy. Default: 0.1. - absolute_accuracy (float): Target absolute accuracy. Default: 0.1. - confidence_coefficient (float): Confidence level. Default: 0.95. See kim_convergence.run_length_control for all available options.

Note: The get_trajectory, fp, and fp_format parameters are reserved and cannot be overridden.

Returns:

Dictionary containing the kim-convergence run_length_control result. Key fields include: - converged (bool): Whether convergence was achieved. - total_run_length (int): Total number of samples collected. - equilibration_step (int): Sample at which equilibration was detected. - mean (float): Estimated mean of the monitored property. - standard_deviation (float): Standard deviation. See kim_convergence.run_length_control documentation for full details.

Raises:

CRerror – If a reserved parameter is provided in **kwargs

Examples

Basic usage:

>>> from ase.build import bulk
>>> from ase.calculators.emt import EMT
>>> from ase.md.langevin import Langevin
>>> from ase import units
>>> from kim_convergence.ase import ASESampler, run_ase_equilibration
>>>
>>> atoms = bulk('Cu', cubic=True) * (3, 3, 3)
>>> atoms.calc = EMT()
>>> dyn = Langevin(atoms, 5 * units.fs, temperature_K=500, friction=0.01)
>>>
>>> sampler = ASESampler(dyn, property_names="temperature")
>>> result = run_ase_equilibration(
...     sampler,
...     initial_run_length=1000,
...     maximum_run_length=10000,
...     relative_accuracy=0.1,
... )
>>> if result["converged"]:
...     print(f"Equilibrated! Mean T = {result['mean']:.1f} K")

With sample_interval to reduce data collection:

>>> sampler = ASESampler(dyn, property_names="energy", sample_interval=10)
>>> result = run_ase_equilibration(
...     sampler,
...     maximum_run_length=5000,  # 5000 samples = 50000 MD steps
...     relative_accuracy=0.05,
... )

With multiple properties:

>>> sampler = ASESampler(dyn, property_names=["energy", "temperature"])

With custom property extractor:

>>> def get_max_force(atoms):
...     return np.max(np.abs(atoms.get_forces()))
>>>
>>> sampler = ASESampler(
...     dyn,
...     property_names="max_force",
...     extractors={"max_force": get_max_force},
... )
>>> result = run_ase_equilibration(sampler, relative_accuracy=0.1)

Property Extractors

Built-in extractors map a property name to a callable that takes an ASE Atoms object and returns a float. The available names are energy (or potential_energy), kinetic_energy, total_energy, temperature, volume, pressure, and density. Custom extractors can be supplied through the extractors argument of ASESampler.

Property extractors for ASE Atoms objects.

This module provides functions to extract thermodynamic properties from ASE Atoms objects for use in convergence analysis.

kim_convergence.ase.extractors.get_density(atoms: Atoms) → float

Extract density from atoms object.

Parameters:: atoms – ASE Atoms object.
Returns:: Density in g/cm³.

kim_convergence.ase.extractors.get_kinetic_energy(atoms: Atoms) → float

Extract kinetic energy from atoms object.

Parameters:: atoms – ASE Atoms object.
Returns:: Kinetic energy in eV.

kim_convergence.ase.extractors.get_potential_energy(atoms: Atoms) → float

Extract potential energy from atoms object.

Parameters:: atoms – ASE Atoms object with an attached calculator.
Returns:: Potential energy in eV.

kim_convergence.ase.extractors.get_pressure(atoms: Atoms) → float

Extract pressure from atoms object.

The pressure is computed as the negative trace of the stress tensor divided by 3 (hydrostatic pressure).

Parameters:: atoms – ASE Atoms object with an attached calculator that supports stress calculations.
Returns:: Pressure in eV/Å³.

kim_convergence.ase.extractors.get_temperature(atoms: Atoms) → float

Extract kinetic temperature from atoms object.

Parameters:: atoms – ASE Atoms object with velocities.
Returns:: Temperature in Kelvin.

kim_convergence.ase.extractors.get_total_energy(atoms: Atoms) → float

Extract total energy (potential + kinetic) from atoms object.

Parameters:: atoms – ASE Atoms object with an attached calculator.
Returns:: Total energy in eV.

kim_convergence.ase.extractors.get_volume(atoms: Atoms) → float

Extract volume from atoms object.

Parameters:: atoms – ASE Atoms object.
Returns:: Volume in Å³.