matcalc._relaxation module

Relaxation properties.

class RelaxCalc(calculator: Calculator | str, *, optimizer: Optimizer | str = 'FIRE', max_steps: int = 500, traj_file: str | None = None, interval: int = 1, fmax: float = 0.1, relax_atoms: bool = True, relax_cell: bool = True, cell_filter: Filter = <class 'ase.filters.FrechetCellFilter'>, perturb_distance: float | None = None)[source]

Bases: PropCalc

A class to perform structural relaxation calculations using ASE (Atomic Simulation Environment).

This class facilitates structural relaxation by integrating with ASE tools for optimized geometry and/or cell parameters. It enables convergence on forces, stress, and total energy, offering customization for relaxation parameters and further enabling properties to be extracted from the relaxed structure.

Variables:

  • calculator – ASE Calculator used for force and energy evaluations.

  • optimizer – Algorithm for performing the optimization.

  • max_steps – Maximum number of optimization steps allowed.

  • traj_file – Path to save relaxation trajectory (optional).

  • interval – Interval for saving trajectory frames during relaxation.

  • fmax – Force tolerance for convergence (eV/Å).

  • relax_atoms – Whether atomic positions are relaxed.

  • relax_cell – Whether the cell parameters are relaxed.

  • cell_filter – ASE filter used for modifying the cell during relaxation.

  • perturb_distance – Distance (Å) for random perturbation to break symmetry.

Initializes the relaxation procedure for an atomic configuration system.

This constructor sets up the relaxation pipeline, configuring the required calculator, optimizer, relaxation parameters, and logging options. The relaxation process aims to find the minimum energy configuration, optionally relaxing atoms and/or the simulation cell within the specified constraints.

Parameters:

  • calculator (Calculator | str) – An ASE calculator object used to perform energy and force calculations. If string is provided, the corresponding universal calculator is loaded.

  • optimizer – The optimization algorithm to use for relaxation. It can either be an instance of an Optimizer class or a string identifier for a recognized ASE optimizer. Defaults to “FIRE”.

  • max_steps – The maximum number of optimization steps to perform during the relaxation process. Defaults to 500.

  • traj_file – Path to a file for periodic trajectory output (if specified). This file logs the atomic positions and cell configurations after a given interval. Defaults to None.

  • interval – The interval (in steps) at which the trajectory file is updated. Defaults to 1.

  • fmax – The force convergence threshold. Relaxation continues until the maximum force on any atom falls below this value. Defaults to 0.1.

  • relax_atoms – A flag indicating whether the atomic positions are to be relaxed. Defaults to True.

  • relax_cell – A flag indicating whether the simulation cell is to be relaxed. Defaults to True.

  • cell_filter – The filter to apply when relaxing the simulation cell. This determines constraints or allowed degrees of freedom during cell relaxation. Defaults to FrechetCellFilter.

  • perturb_distance – A perturbation distance used for initializing the system configuration before relaxation. If None, no perturbation is applied. Defaults to None.

_abc_impl = <_abc._abc_data object>[source]
calc(structure: Structure | dict) → dict[source]

Calculate the final relaxed structure, energy, forces, and stress for a given structure and update the result dictionary with additional geometric properties.

This method takes an input structure and performs a relaxation process depending on the specified parameters. If the perturb_distance attribute is provided, the structure is perturbed before relaxation. The relaxation process can involve optimization of both atomic positions and the unit cell if specified. Results of the calculation including final structure geometry, energy, forces, stresses, and lattice parameters are returned in a dictionary.

Parameters:

structure – Input structure for calculation. Can be provided as a Structure object or a dictionary convertible to Structure.

Returns:

Dictionary containing the final relaxed structure, calculated energy, forces, stress, and lattice parameters.

Return type:

dict

class TrajectoryObserver(atoms: Atoms, energies: list[float] = <factory>, forces: list[np.ndarray] = <factory>, stresses: list[np.ndarray] = <factory>, atom_positions: list[np.ndarray] = <factory>, cells: list[np.ndarray] = <factory>)[source]

Bases: object

Class for observing and recording the properties of an atomic structure during relaxation.

The TrajectoryObserver class is designed to track and store the atomic properties like energies, forces, stresses, atom positions, and cell structure of an atomic system represented by an Atoms object. It provides functionality to save recorded data to a file for further analysis or usage.

Variables:

  • atoms – The atomic structure being observed.

  • energies – List of potential energy values of the atoms during relaxation.

  • forces – List of force arrays recorded for the atoms during relaxation.

  • stresses – List of stress tensors recorded for the atoms during relaxation.

  • atom_positions – List of atomic positions recorded during relaxation.

  • cells – List of unit cell arrays recorded during relaxation.

atom_positions: list[np.ndarray][source]
atoms: Atoms[source]
cells: list[np.ndarray][source]
energies: list[float][source]
forces: list[np.ndarray][source]
save(filename: str) → None[source]

Save the trajectory to file.

Parameters:

filename (str) – filename to save the trajectory.

stresses: list[np.ndarray][source]