matcalc.backend._ase module

This module implements convenience functions to perform various atomic simulation types, specifically relaxation and static, using either ASE or LAMMPS. This enables the code to use either for the computation of various properties.

get_ase_optimizer(optimizer: str | Optimizer) → Optimizer[source]

Retrieve an ASE optimizer instance based on the provided input. This function accepts either a string representing the name of a valid ASE optimizer or an instance/subclass of the Optimizer class. If a string is provided, it checks the validity of the optimizer name, and if valid, retrieves the corresponding optimizer from ASE. An error is raised if the optimizer name is invalid.

If an Optimizer subclass or instance is provided as input, it is returned directly.

Parameters:

optimizer – ASE optimizer name (str) or Optimizer subclass.

Returns:

The ASE optimizer class or the given Optimizer subclass.

Raises:

ValueError – If optimizer is a string not in VALID_OPTIMIZERS.

is_ase_optimizer(key: str | Optimizer) → bool[source]

Determines whether the given key is an ASE optimizer. A key can either be a string representing the name of an optimizer class within ase.optimize or directly be an optimizer class that subclasses Optimizer.

If the key is a string, the function checks whether it corresponds to a class in ase.optimize that is a subclass of Optimizer.

Parameters:

key – String name of an ASE optimizer in ase.optimize, or an Optimizer subclass.

Returns:

True if key names a valid ASE optimizer class or is an Optimizer subclass.

run_ase(structure: Structure | Atoms, calculator: Calculator, *, relax_atoms: bool = False, relax_cell: bool = False, optimizer: Optimizer | str = 'FIRE', max_steps: int = 500, traj_file: str | None = None, interval: int = 1, fmax: float = 0.1, cell_filter: Filter = <class 'ase.filters.FrechetCellFilter'>, cell_filter_kwargs: dict | None = None) → SimulationResult[source]

Run ASE static calculation using the given structure and calculator.

Parameters:

  • structure – Input structure for energy, forces, and stress.

  • calculator – ASE calculator attached to the structure.

  • relax_atoms – Whether to relax atomic positions.

  • relax_cell – Whether to relax the cell (with cell_filter).

  • optimizer – Optimizer name or class.

  • max_steps – Maximum optimization steps.

  • traj_file – Optional trajectory path during relaxation.

  • interval – Trajectory write interval.

  • fmax – Force convergence criterion (eV/Å).

  • cell_filter – Cell filter class when relax_cell is True.

  • cell_filter_kwargs – Extra arguments for the cell filter.

Returns:

SimulationResult with structure, energies, forces, and stress.