matcalc package

Calculators for materials properties from the potential energy surface.

class AdsorptionCalc(calculator: Calculator | str, *, relax_adsorbate: bool = True, relax_slab: bool = True, relax_bulk: bool = True, fmax: float = 0.1, optimizer: str | Optimizer = 'BFGS', max_steps: int = 500, adsorbate_vacuum_size: float = 15.0, relax_calc_kwargs: dict[str, Any] | None = None)[source]

Bases: PropCalc

Adsorption energies on surfaces via bulk, slab, adsorbate, and adslab relaxations.

Uses RelaxCalc for geometry optimizations. Attributes mirror constructor arguments plus optional cached bulk state after calc_bulk / calc_adslabs.

Parameters:

• calculator – ASE calculator or universal model name string.

• relax_adsorbate – Relax isolated adsorbate in a box when True.

• relax_slab – Relax clean slab (fixed cell) when True.

• relax_bulk – Relax bulk with cell when True.

• fmax – Force tolerance (eV/Å).

• optimizer – ASE optimizer name or class.

• max_steps – Max relaxation steps.

• adsorbate_vacuum_size – Padding (Å) added on each side of the adsorbate’s bounding box when building the isolated-adsorbate relaxation cell. Increase for large or charged adsorbates to avoid spurious image-image interactions. Default 15.

• relax_calc_kwargs – Optional kwargs for RelaxCalc.

_abc_impl = <_abc._abc_data object>[source]

calc(structure: dict[str, Any]) → dict[str, Any][source]

Parameters:

structure – Dict with adslab, slab, adsorbate; optional slab_energy / adsorbate_energy.

Returns:

Dict including adsorption_energy and merged slab/adsorbate fields.

calc_adslabs(adsorbate: Molecule | Atoms, bulk: Structure | Atoms, miller_index: tuple[int, int, int], *, adsorbate_energy: float | None = None, slab_energy: float | None = None, min_slab_size: float = 10.0, min_vacuum_size: float = 20.0, min_area_extent: tuple[float, float] | None = None, inplane_supercell: tuple[int, int] = (1, 1), slab_gen_kwargs: dict[str, Any] | None = None, get_slabs_kwargs: dict[str, Any] | None = None, adsorption_sites: dict[str, Sequence[tuple[float, float]]] | str = 'all', height: float = 0.9, mi_vec: tuple[float, float] | None = None, fixed_height: float = 5, find_adsorption_sites_args: dict[str, Any] | None = None, dry_run: bool = False, **kwargs: dict[str, Any]) → list[dict[str, Any]] | dict[Any, Any][source]

Parameters:

• adsorbate – Adsorbate species.

• bulk – Bulk structure (use conventional cell if needed for Miller indices).

• miller_index – Surface orientation.

• adsorbate_energy – Optional fixed adsorbate energy.

• slab_energy – Optional fixed clean-slab energy for all slabs.

• min_slab_size – Minimum slab thickness (Å).

• min_vacuum_size – Vacuum thickness (Å).

• min_area_extent – Minimum in-plane extent (Å); may expand inplane_supercell.

• inplane_supercell – In-plane supercell factors.

• slab_gen_kwargs – Kwargs for SlabGenerator.

• get_slabs_kwargs – Kwargs for SlabGenerator.get_slabs.

• adsorption_sites – "all", site name string, or custom fractional-coordinate dict.

• height – Adsorbate height above surface (Å).

• mi_vec – Optional in-plane vector for AdsorbateSiteFinder.

• fixed_height – Fix slab atoms below this height (Å) during relaxation.

• find_adsorption_sites_args – Kwargs for find_adsorption_sites.

• dry_run – If True, return adslab dicts without calc_many.

• **kwargs – Forwarded to calc_many.

Returns:

List of per-configuration results, or raw adslab dicts if dry_run.

calc_adsorbate(adsorbate: Molecule | Atoms, adsorbate_energy: float | None = None) → dict[str, Any][source]

Parameters:

• adsorbate – Adsorbate as molecule or atoms.

• adsorbate_energy – Optional fixed energy; otherwise from calculator on final geometry.

Returns:

Dict with adsorbate_energy, adsorbate, final_adsorbate.

calc_bulk(bulk: Structure | Atoms, bulk_energy: float | None = None) → dict[str, Any][source]

Parameters:

• bulk – Bulk pymatgen structure or ASE atoms.

• bulk_energy – If relax_bulk is False and this is set, used as energy; else relaxed.

Returns:

Dict with final_structure and energy (when available).

calc_slab(slab: Structure | Atoms, slab_energy: float | None = None) → dict[str, Any][source]

Parameters:

• slab – Slab structure or atoms.

• slab_energy – Optional total slab energy; if None, taken from calculator.

Returns:

Dict with slab, slab_energy, slab_energy_per_atom, final_slab.

class ChainedCalc(prop_calcs: Sequence[PropCalc])[source]

Bases: PropCalc

A chained calculator that runs a series of PropCalcs on a structure or set of structures.

Often, you may want to obtain multiple properties at once, e.g., perform a relaxation followed by a formation energy computation and an elasticity calculation. This can be done by supplying a list of calculators. Each calculator receives the full result dict from the previous step, so downstream calculators can skip redundant relaxations by setting relax_structure=False.

Initialize a chained calculator.

Parameters:

prop_calcs – Sequence of prop calcs.

_abc_impl = <_abc._abc_data object>[source]

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

Runs the series of PropCalcs on a structure.

Parameters:

structure – Pymatgen structure or a dict containing a pymatgen Structure under a “final_structure” or “structure” key. Allowing dicts provide the means to chain calculators, e.g., do a relaxation followed by an elasticity calculation.

Returns:

Merged dict from all steps (final keys depend on the chain).

calc_many(structures: Sequence[Structure | Atoms | dict[str, Any]], n_jobs: None | int = None, allow_errors: bool = False, **kwargs: Any) → Generator[dict | None, None, None][source]

Runs the sequence of PropCalc on many structures.

Parameters:

• structures – List or generator of Structures.

• n_jobs – The maximum number of concurrently running jobs. If -1 all CPUs are used. For n_jobs below -1, (n_cpus + 1 + n_jobs) are used. None is a marker for unset that will be interpreted as n_jobs=1 unless the call is performed under a parallel_config() context manager that sets another value for n_jobs.

• allow_errors – Whether to skip failed calculations. For these calculations, None will be returned. For large scale calculations, you may want this to be True to avoid the entire calculation failing. Defaults to False.

• **kwargs – Passthrough to calc_many method of all PropCalcs.

Returns:

Generator of dicts.

class EOSCalc(calculator: Calculator | str, *, optimizer: Optimizer | str = 'FIRE', max_steps: int = 500, max_abs_strain: float = 0.1, n_points: int = 11, fmax: float = 0.1, allow_shape_change: bool = True, relax_structure: bool = True, relax_calc_kwargs: dict | None = None, r2_min: float = 0.95)[source]

Bases: PropCalc

Performs equation of state (EOS) calculations using a specified ASE calculator.

This class is intended to fit the Birch-Murnaghan equation of state, determine the bulk modulus, and provide other relevant physical properties of a given structure. The EOS calculation includes applying volumetric strain to the structure, optional initial relaxation of the structure, and evaluation of energies and volumes corresponding to the applied strain.

calculator[source]

ASE calculator or universal model name.

optimizer[source]

Optimizer for optional relaxations.

relax_structure[source]

Relax initial structure before the EOS scan.

n_points[source]

Number of volume/strain samples.

max_abs_strain[source]

Half-range of applied volumetric strain (symmetric scan).

fmax[source]

Force tolerance for relaxations.

max_steps[source]

Max optimizer steps per relaxation.

allow_shape_change[source]

Allow cell shape to change at fixed volume during EOS points.

relax_calc_kwargs[source]

Optional kwargs for RelaxCalc.

Parameters:

• calculator – ASE calculator or universal model name string.

• optimizer – ASE optimizer name or class for relaxations.

• max_steps – Maximum relaxation steps per structure.

• max_abs_strain – Maximum absolute volumetric strain in the scan.

• n_points – Number of strain points (including halves of the scan).

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

• allow_shape_change – Relax cell shape at fixed volume for EOS points when True.

• relax_structure – Relax input structure before the strain scan.

• relax_calc_kwargs – Optional kwargs for RelaxCalc.

• r2_min – Minimum acceptable R² for the Birch-Murnaghan fit. A RuntimeWarning is emitted (and the value is still returned) if the fit’s R² falls below this threshold. Set to a negative number to disable the check.

_abc_impl = <_abc._abc_data object>[source]

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

Parameters:

structure – Pymatgen structure, ASE atoms, or dict with structure keys.

Returns:

Dict with eos (volumes in A^3, energies in eV), bulk_modulus_bm (GPa), r2_score_bm (dimensionless), and fields from the final relaxation merged in. _units maps each numeric output to its unit string. See pymatgen BirchMurnaghan / EOSBase for fit details.

class ElasticityCalc(calculator: Calculator | str, *, norm_strains: Sequence[float] | float = (-0.01, -0.005, 0.005, 0.01), shear_strains: Sequence[float] | float = (-0.06, -0.03, 0.03, 0.06), fmax: float = 0.1, symmetry: bool = False, relax_structure: bool = True, relax_deformed_structures: bool = False, use_equilibrium: bool = True, units_GPa: bool = False, relax_calc_kwargs: dict | None = None, r2_min: float = 0.95)[source]

Bases: PropCalc

Elastic tensor and related moduli via strain-stress fitting with pymatgen.

calculator[source]

ASE calculator (or universal model name).

norm_strains[source]

Normal strains applied in DeformedStructureSet.

shear_strains[source]

Shear strains applied in DeformedStructureSet.

fmax[source]

Force tolerance for optional relaxations.

symmetry[source]

Whether to reduce deformations by symmetry.

relax_structure[source]

Relax initial structure before deforming.

relax_deformed_structures[source]

Relax each deformed structure before stress.

use_equilibrium[source]

Include equilibrium stress in the fit when applicable.

units_GPa[source]

If True, report moduli in GPa instead of pymatgen’s native eV/A^3.

relax_calc_kwargs[source]

Optional kwargs for RelaxCalc.

Parameters:

• calculator – ASE calculator or universal model name string.

• norm_strains – Normal strains (non-empty, no zeros); scalar broadcast to one value.

• shear_strains – Shear strains (non-empty, no zeros); scalar allowed.

• fmax – Force tolerance for relaxations.

• symmetry – Pass-through to pymatgen DeformedStructureSet.

• relax_structure – Relax parent structure before generating deformations.

• relax_deformed_structures – Relax each deformed structure before stress eval.

• use_equilibrium – Use equilibrium stress in fit; forced True if only one strain type.

• units_GPa – If True, return moduli (and elastic tensor / residuals) in GPa. Defaults to False, in which case values are returned in pymatgen’s native units of eV/A^3.

• relax_calc_kwargs – Optional kwargs for RelaxCalc.

• r2_min – Minimum acceptable mean R² across the per-component linear strain-stress fits. A RuntimeWarning is emitted (and values are still returned) when the mean R² drops below this. Set negative to disable. Default 0.95.

_abc_impl = <_abc._abc_data object>[source]

_elastic_tensor_from_strains(strains: ArrayLike, stresses: ArrayLike, eq_stress: ArrayLike = None, tol: float = 1e-07) → tuple[ElasticTensor, float, float][source]

Fit elastic constants from strain-stress pairs (Voigt), optionally subtracting equilibrium stress.

Parameters:

• strains – Strain states (array-like) for each deformation.

• stresses – Matching stress tensors (array-like).

• eq_stress – Equilibrium stress to subtract; None to omit.

• tol – Small components below this are zeroed on the fitted tensor.

Returns:

(ElasticTensor, residuals_sum, mean_r2). mean_r2 is the average coefficient of determination across the 36 per-component linear fits; stress components with zero variance (zeroed by symmetry) are skipped.

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

Parameters:

structure – Pymatgen structure, ASE atoms, or dict with structure keys.

Returns:

Dict including elastic_tensor, shear_modulus_vrh, bulk_modulus_vrh, youngs_modulus, residuals_sum, structure, _units, and merged relaxation fields. elastic_tensor, shear_modulus_vrh, bulk_modulus_vrh, youngs_modulus and residuals_sum are returned in GPa if units_GPa=True, otherwise in eV/A^3 (pymatgen’s native units). _units is a dict mapping each numeric output to its unit string.

class EnergeticsCalc(calculator: Calculator | str, *, elemental_refs: Literal['MP-PBE', 'MatPES-PBE', 'MatPES-r2SCAN'] | dict = 'MatPES-PBE', fmax: float = 0.1, optimizer: str = 'FIRE', perturb_distance: float | None = None, use_gs_reference: bool = False, relax_structure: bool = True, relax_calc_kwargs: dict | None = None)[source]

Bases: PropCalc

Handles formation energy per atom, cohesive energy per atom, and relaxed structures using reference elemental data and optional relaxation.

calculator[source]

ASE calculator (or universal model name) for energies and forces.

elemental_refs[source]

Builtin ref key or custom dict mapping elements to reference data.

use_gs_reference[source]

If True, use tabulated DFT ground-state energies from refs.

relax_structure[source]

Whether to relax the input structure before energetics.

relax_calc_kwargs[source]

Optional kwargs forwarded to RelaxCalc.

Parameters:

• calculator – ASE calculator or universal model name string.

• elemental_refs – "MP-PBE", "MatPES-PBE", "MatPES-r2SCAN", or a custom dict.

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

• optimizer – ASE optimizer name for relaxation.

• perturb_distance – Random displacement (Å) before relaxation, or None.

• use_gs_reference – Use tabulated ground-state energies from references when True.

• relax_structure – Relax input structure before computing energetics.

• relax_calc_kwargs – Optional kwargs for RelaxCalc.

_abc_impl = <_abc._abc_data object>[source]

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

Parameters:

structure – Pymatgen structure, ASE atoms, or chained-result dict.

Returns:

Dict with formation_energy_per_atom (eV/atom), cohesive_energy_per_atom (eV/atom, or None if reference data missing), final_structure, _units, and other keys from relaxation / PES when applicable.

class GBCalc(calculator: Calculator | str, *, relax_bulk: bool = True, relax_gb: bool = True, fmax: float = 0.1, optimizer: str | Optimizer = 'FIRE', max_steps: int = 500, relax_calc_kwargs: dict | None = None)[source]

Bases: PropCalc

A class for performing grain boundary energy calculations by generating grain boundary structures from a bulk structure using pymatgen’s GrainBoundaryGenerator, optionally relaxing bulk and GB, and computing gamma_GB via (E_GB - N_GB * E_bulk_per_atom) / (2 * A).

calculator[source]

ASE Calculator used for energy and force evaluations.

relax_bulk[source]

Whether to relax the bulk structure (cell and atoms) before GB generation.

relax_gb[source]

Whether to relax the grain boundary structures (atoms only) after generation.

fmax[source]

Force convergence criterion (eV/Å) for relaxations.

optimizer[source]

Optimizer for structure relaxations.

max_steps[source]

Maximum optimization steps for relaxations.

relax_calc_kwargs[source]

Additional keyword arguments for relaxation calculations.

Parameters:

• calculator – ASE Calculator or string identifier for a universal calculator.

• relax_bulk – Whether to relax the bulk structure before GB generation. Default True.

• relax_gb – Whether to relax the GB structures after generation. Default True.

• fmax – Force tolerance (eV/Å) for relaxations. Default 0.1.

• optimizer – ASE optimizer or name for relaxations. Default “FIRE”.

• max_steps – Max optimization steps. Default 500.

• relax_calc_kwargs – Additional keyword arguments for relaxation calculations. Defaults to None.

_abc_impl = <_abc._abc_data object>[source]

calc(structure: dict[str, Any]) → dict[str, Any][source]

Compute grain boundary energy for a single grain boundary structure dict produced by calc_gb or direct input. The function handles relaxation of both bulk and grain boundary structures when necessary.

Parameters:

structure – Dictionary containing information about the bulk and grain boundary structures. It must have the format: {'grain_boundary': gb_structure, 'bulk': bulk_structure} or {'grain_boundary': gb_structure, 'bulk_energy_per_atom': energy}.

Returns:

A dictionary containing the updated structure data, including fields like ‘grain_boundary’, ‘final_grain_boundary’, ‘gb_relax_energy’, ‘grain_boundary_energy’, and possibly updated ‘bulk_energy_per_atom’ and ‘final_bulk’.

Raises:

ValueError – If structure is not a dict with the required keys.

calc_gb(structure: Structure | Atoms, sigma: int, rotation_axis: tuple[int, int, int], gb_plane: tuple[int, int, int], rotation_angle: float, expand_times: int = 4, vacuum_thickness: float = 0.0, ab_shift: tuple[float, float] = (0.0, 0.0), rotation_angle_tolerance: float = 0.1, normal: bool = True, rm_ratio: float = 0.7, gb_generator_kwargs: dict | None = None, gb_from_parameters_kwargs: dict | None = None) → dict[str, Any][source]

Generate grain boundary structures from bulk, relax them, and compute GB energies.

Parameters:

• structure – Bulk Structure for GB generation.

• sigma – Sigma value of the coincident site lattice (CSL) grain boundary.

• rotation_axis – Rotation axis vector for GB (u, v, w).

• gb_plane – Miller indices of GB plane.

• rotation_angle – Rotation angle in degrees.

• expand_times – Multiplier for cell expansion to avoid interactions. Default 4.

• vacuum_thickness – Vacuum layer thickness (Å) between grains. Default 0.0.

• ab_shift – In-plane shift along a, b vectors. Default (0.0, 0.0).

• rotation_angle_tolerance – Tolerance (degrees) for matching rotation angle. Default 0.1.

• normal – Whether the c axis of top grain should be perpendicular to the surface. Default True.

• rm_ratio – Criteria to remove atoms which are too close with each other. Default 0.7.

• gb_generator_kwargs – Additional args for GrainBoundaryGenerator(). Default None.

• gb_from_parameters_kwargs – Additional args for gb_from_parameters(). Default None.

Returns:

A dictionary containing the updated structure data, including fields like ‘grain_boundary’, ‘final_grain_boundary’, ‘gb_relax_energy’, ‘grain_boundary_energy’, and possibly updated ‘bulk_energy_per_atom’ and ‘final_bulk’.

Raises:

ValueError – If no rotation angle within rotation_angle_tolerance of rotation_angle exists for the given sigma.

class InterfaceCalc(calculator: Calculator | str, *, relax_bulk: bool = True, relax_interface: bool = True, fmax: float = 0.1, optimizer: str | Optimizer = 'BFGS', max_steps: int = 500, relax_calc_kwargs: dict | None = None)[source]

Bases: PropCalc

This class generates all possible coherent interfaces between two bulk structures given their miller indices, relaxes them, and computes their interfacial energies.

Initialize the instance of the class.

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.

• relax_bulk (bool, optional) – Whether to relax the bulk structures before interface calculations. Defaults to True.

• relax_interface (bool, optional) – Whether to relax the interface structures. Defaults to True.

• fmax (float, optional) – The maximum force tolerance for convergence. Defaults to 0.1.

• optimizer (str | Optimizer, optional) – The optimization algorithm to use. Defaults to “BFGS”.

• max_steps (int, optional) – The maximum number of optimization steps. Defaults to 500.

• relax_calc_kwargs – Additional keyword arguments passed to the RelaxCalc constructor for both bulk and interface. Default is None.

Returns:

None

_abc_impl = <_abc._abc_data object>[source]

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

Calculate the interfacial energy of the given interface structures and sort by the energy.

Parameters:

structure – A dictionary containing the film, substrate, interface structures

Returns:

• “interface” (Structure): The initial interface structure.

• ”final_interface” (Structure): The relaxed interface structure.

• ”interface_energy_per_atom” (float): The final energy of the relaxed interface structure.

• ”num_atoms” (int): The number of atoms in the interface structure.

• ”interfacial_energy” (float): The calculated interfacial energy

Return type:

dict

calc_interfaces(film_bulk: Structure, substrate_bulk: Structure, film_miller: tuple[int, int, int], substrate_miller: tuple[int, int, int], zslgen: ZSLGenerator | None = None, cib_kwargs: dict | None = None, **kwargs: Any) → list[dict[str, Any]][source]

Calculate all possible coherent interfaces between two bulk structures.

Parameters:

• film_bulk (Structure) – The bulk structure of the film material.

• substrate_bulk (Structure) – The bulk structure of the substrate material.

• film_miller (tuple[int, int, int]) – The Miller index for the film surface.

• substrate_miller (tuple[int, int, int]) – The Miller index for the substrate surface.

• zslgen (ZSLGenerator | None, optional) – An instance of ZSLGenerator to use for generating supercells.

• zsl_kwargs (dict | None, optional) – Additional keyword arguments to pass to the ZSLGenerator.

• cib_kwargs (dict | None, optional) – Additional keyword arguments to pass to the CoherentInterfaceBuilder.

• **kwargs (Any) – Additional keyword arguments passed to calc_many.

Returns:

A list of dictionaries containing the calculated film, substrate, interface.

Return type:

dict

class LAMMPSMDCalc(calculator: str, *, temperature: int = 300, ensemble: Literal['nve', 'nvt', 'npt', 'nvt_nose_hoover', 'npt_nose_hoover'] = 'nvt', timestep: float = 0.001, steps: int = 100, pressure: float = 1, taut: float | None = None, taup: float | None = None, infile: str = 'in.md', trajfile: str = 'md.lammpstrj', logfile: str = 'log.lammps', loginterval: int = 1, relax_structure: bool = True, fmax: float = 0.1, optimizer: str = 'FIRE', frames: int = 10, settings: dict | None = None, relax_calc_kwargs: dict | None = None)[source]

Bases: PropCalc

Class to manage molecular dynamics simulations using LAMMPS.

calculator[source]

Universal model name string (resolved for MatGL potentials).

temperature[source]

Target temperature (K).

ensemble[source]

Thermostat/barostat choice.

timestep[source]

MD timestep (ps).

steps[source]

Total MD steps.

pressure[source]

Target pressure for NPT (bar).

taut, taup

Thermo/barostat time constants (ps).

infile, trajfile, logfile

LAMMPS IO paths.

loginterval[source]

Thermo output stride.

relax_structure[source]

Pre-MD RelaxCalc when True.

fmax, optimizer

Relaxation settings.

frames[source]

Number of trailing trajectory frames to return.

settings[source]

Extra template placeholders for LammpsRun.

relax_calc_kwargs[source]

Kwargs for pre-MD RelaxCalc.

Initialize LAMMPSMDCalc with simulation parameters.

_abc_impl = <_abc._abc_data object>[source]

_generate_fix_command() → str[source]

Generate LAMMPS fix command based on the selected ensemble.

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

Run the MD calculation using LAMMPS.

write_inputs(structure: Structure | Atoms | dict[str, Any], script_template: str | Path = PosixPath('/home/runner/work/matcalc/matcalc/src/matcalc/lammps_templates/md.template')) → LammpsRun[source]

Write LAMMPS input files based on a given structure.

Parameters:

• structure – Structure, atoms, or dict accepted by PropCalc.calc.

• script_template – Path or string content of the LAMMPS script template.

Returns:

LammpsRun with inputs written to the current working directory.

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_mtk', '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, equilibration_frames: int = 0, relax_calc_kwargs: dict | None = None, set_com_stationary: bool = False, set_zero_rotation: bool = False)[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”, “npt_isotropic_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_mtk and 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_mtk and 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 and MTKNPT.

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

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

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

• 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 trailing MD frames to average energies over. Default to None, which means all frames (i.e. frames = steps).

• equilibration_frames (int) – Skip this many leading frames before the trailing frames window. Use this to discard non-equilibrated state at the start of an MD run. Default 0.

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

• set_com_stationary (bool) – Whether to set the center-of-mass momentum to zero after setting up the Maxwell-Boltzmann distribution. Default to False.

• set_zero_rotation (bool) – Whether to set the total angular momentum to zero after setting up the Maxwell-Boltzmann distribution. Default to False.

_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 with final_structure, trajectory (list of ASE Atoms),

potential_energy (eV), kinetic_energy (eV), total_energy (eV) averaged over the last frames frames, _units mapping each numeric output to its unit string, plus any relaxation fields merged in.

Return type:

dict

class MEP(structures: list[Structure], energies: list[float])[source]

Bases: object

Minimum Energy Path dataclass for NEB calculations.

Stores MEP results in a data-efficient format where labels are stored once, and only fractional coordinates and lattices vary between images.

Initialize MEP from structures and energies.

Parameters:

• structures – List of pymatgen Structures.

• energies – List of energies for each image.

as_dict() → dict[str, Any][source]

Convert MEP to a data-efficient dictionary representation.

Returns:

• “labels”: List of species strings (stored once)

• ”lattice”: Lattice matrix as a 3x3 array (only if same for all images)

• ”images”: List of dictionaries, each containing:

  • ”lattice”: Lattice matrix as a 3x3 array (only if different per image)

  • ”frac_coords”: Fractional coordinates for the image

  • ”energy”: Energy for the image

Return type:

Dictionary with

energies: list[float][source]

Energy for each image.

frac_coords: list[ndarray][source]

Fractional coordinates for each image.

classmethod from_dict(d: dict[str, Any]) → MEP[source]

Reconstruct MEP from a dictionary representation.

Parameters:

d – Dictionary with keys “labels” and “images” as returned by as_dict(). May also contain “lattice” at top level if same for all images.

Returns:

MEP instance reconstructed from the dictionary.

get_lattices_list() → list[ndarray][source]

Get lattices as a list, expanding a single lattice if needed.

get_structures() → list[Structure][source]

Get all images as a list of pymatgen Structures.

Returns:

List of Structure objects, one for each image in the MEP.

labels: list[Species][source]

Species labels for all atoms (same for all images).

lattices: ndarray | list[ndarray][source]

Lattice matrix(ces). If a single array, applies to all images. If a list, one per image.

class NEBCalc(calculator: Calculator | str, *, optimizer: str | Optimizer = 'BFGS', traj_folder: str | None = None, interval: int = 1, climb: bool = True, fmax: float = 0.1, method: str = 'improvedtangent', max_steps: int = 1000, **kwargs: Any)[source]

Bases: PropCalc

NEB calculator.

Initialize the instance of the class.

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 (str | Optimizer, optional) – The optimization algorithm to use. Defaults to “BFGS”.

• traj_folder (str | None, optional) – The folder to save trajectory information. Defaults to None.

• interval (int, optional) – The interval for recording trajectory information. Defaults to 1.

• climb (bool, optional) – Whether to perform climbing image nudged elastic band (CI-NEB). Defaults to True.

• fmax (float, optional) – The maximum force tolerance for convergence. Defaults to 0.1.

• max_steps (int, optional) – The maximum number of optimization steps. Defaults to 1000.

• **kwargs (Any) – Additional keyword arguments.

Returns:

None

_abc_impl = <_abc._abc_data object>[source]

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

Calculate the energy barrier using the nudged elastic band method.

Parameters:

structure (-) – A dictionary containing the images with keys ‘image0’, ‘image1’, etc. Must be of type dict.

Returns:

• “barrier” (float): The energy barrier of the reaction pathway.

• ”force” (float): The force exerted on the atoms during the NEB calculation.

• ”mep” (MEP): An MEP dataclass containing the images and their respective energies.

Return type:

dict

calc_images(start_struct: Structure, end_struct: Structure, *, n_images: int = 7, interpolate_lattices: bool = False, autosort_tol: float = 0.5) → dict[str, Any][source]

Calculate NEB images between given start and end structures.

Parameters:

• start_struct (Structure) – Initial structure.

• end_struct (Structure) – Final structure.

• n_images (int) – Number of images to calculate (default is 7).

• interpolate_lattices (bool) – Whether to interpolate lattices between start and end structures (default is False).

• autosort_tol (float) – Tolerance for autosorting the images (default is 0.5).

Returns:

NEB calculation object containing the interpolated images.

Return type:

NEBCalc

class PESCalculator(potential: LMPStaticCalculator, stress_unit: Literal['eV/A3', 'GPa'] = 'GPa', stress_weight: float = 1.0, **kwargs: Any)[source]

Bases: Calculator

Class for simulating and calculating potential energy surfaces (PES) using various machine learning and classical potentials. It extends the ASE Calculator API, allowing integration with the ASE framework for molecular dynamics and structure optimization.

PESCalculator provides methods to perform energy, force, and stress calculations using potentials such as MTP, GAP, NNP, SNAP, ACE, NequIP, DeePMD and MatGL (M3GNet, TensorNet, CHGNet). The class includes utilities to load compatible models for each potential type, making it a versatile tool for materials modeling and molecular simulations.

potential[source]

MAML LAMMPS static potential backend.

stress_weight[source]

Factor applied to stress (includes unit conversion).

Initialize PESCalculator with a potential from maml.

Parameters:

• potential – MAML LMPStaticCalculator instance.

• stress_unit – "GPa" or "eV/A3" for returned stress units.

• stress_weight – Multiplier on stress after unit conversion (default 1.0).

• **kwargs – Forwarded to ase.calculators.calculator.Calculator.

_abc_impl = <_abc._abc_data object>[source]

calculate(atoms: Atoms | None = None, properties: list | None = None, system_changes: list | None = None) → None[source]

Perform calculation for an input Atoms.

Parameters:

• atoms – Structure to evaluate.

• properties – ASE property list to compute (defaults to all).

• system_changes – ASE change list; if unchanged, cached results may be reused.

implemented_properties: list[str] = ['energy', 'forces', 'stress'][source]

Properties calculator can handle (energy, forces, …)

static load_ace(basis_set: str | Path | ACEBBasisSet | ACECTildeBasisSet | BBasisConfiguration, **kwargs: Any) → Calculator[source]

Load an ACE (Atomic Cluster Expansion) calculator using the specified basis set.

This method utilizes the PyACE library to create and initialize a PyACECalculator instance with a given basis set. The provided basis set can take various forms including file paths, basis set objects, or configurations. Additional customization options can be passed through keyword arguments.

Parameters:

• basis_set – ACE basis (path, or PyACE basis / configuration object).

• **kwargs – Forwarded to PyACECalculator.

Returns:

Initialized PyACE ASE calculator.

static load_deepmd(model_path: str | Path, **kwargs: Any) → Calculator[source]

Loads a Deep Potential Molecular Dynamics (DeePMD) model and returns a Calculator object for molecular dynamics simulations.

This method imports the deepmd.calculator.DP class and initializes it with the given model path and optional keyword arguments. The resulting Calculator object is used to perform molecular simulations based on the specified DeePMD model.

The function requires the DeePMD-kit library to be installed to properly import and utilize the DP class.

Parameters:

• model_path – Trained DeePMD model path.

• **kwargs – Forwarded to DeePMD DP.

Returns:

DeePMD ASE calculator instance.

static load_gap(filename: str | Path, **kwargs: Any) → Calculator[source]

Loads a Gaussian Approximation Potential (GAP) model from the given file and returns a corresponding Calculator instance. GAP is a machine learning-based potential used for atomistic simulations and requires a specific config file as input. Any additional arguments for the calculator can be passed via kwargs, allowing customization.

Parameters:

• filename – GAP configuration file path.

• **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the GAP model.

static load_matgl(path: str | Path, **kwargs: Any) → Calculator[source]

Loads a MATGL model from the specified path and initializes a PESCalculator with the loaded model and additional optional parameters.

This method uses the MATGL library to load a model from the given file path or directory. It then configures a calculator using the loaded model and the provided keyword arguments.

Parameters:

• path – Path to the MatGL model file or pretrained model name.

• **kwargs – Forwarded to the MatGL ASE calculator.

Returns:

Configured ASE calculator for the MatGL model.

static load_mtp(filename: str | Path, elements: list, **kwargs: Any) → Calculator[source]

Load a machine-learned potential (MTPotential) from a configuration file and create a calculator object to interface with it.

This method initializes an instance of MTPotential using a provided configuration file and elements. It returns a PESCalculator instance, which wraps the initialized potential model.

Parameters:

• filename – MTP configuration file path.

• elements – Element symbols for the potential (e.g. ["Cu"]).

• **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the MTP model.

static load_nequip(model_path: str | Path, **kwargs: Any) → Calculator[source]

Loads and returns a NequIP Calculator instance from the specified model path. This method facilitates the integration of machine learning models into ASE by loading a model for atomic-scale simulations.

Parameters:

• model_path – Path to the deployed NequIP model.

• **kwargs – Forwarded to NequIPCalculator.from_deployed_model.

Returns:

NequIP ASE calculator instance.

static load_nnp(input_filename: str | Path, scaling_filename: str | Path, weights_filenames: list, **kwargs: Any) → Calculator[source]

Loads a neural network potential (NNP) from specified configuration files and creates a Calculator object configured with the potential. This function allows for customizable keyword arguments to modify the behavior of the resulting Calculator.

Parameters:

• input_filename – NNP input configuration path.

• scaling_filename – NNP scaling parameters path.

• weights_filenames – Paths to NNP weight files.

• **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the NNP model.

static load_snap(param_file: str | Path, coeff_file: str | Path, **kwargs: Any) → Calculator[source]

Load a SNAP (Spectral Neighbor Analysis Potential) configuration and create a corresponding Calculator instance.

This static method initializes a SNAPotential instance using the provided configuration files and subsequently generates a PESCalculator based on the created potential model and additional keyword arguments.

Parameters:

• param_file – SNAP parameter file path.

• coeff_file – SNAP coefficient file path.

• **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the SNAP model.

static load_universal(name: str | Calculator, **kwargs: Any) → Calculator[source]

Load a foundation potential calculator by its canonical name.

Names follow the unified convention <Architecture>-<Dataset>-<Optional Version> (e.g. TensorNet-MatPES-PBE-2025.2, MACE-MPA-0-medium). The full list of canonical names is the keys of MODEL_REGISTRY; short / legacy spellings in MODEL_ALIASES resolve to a canonical name. Lookups are case-insensitive.

If name is already a Calculator, it is returned unchanged.

Parameters:

• name – Canonical model name, alias, or an existing ASE calculator instance.

• **kwargs – Provider-specific options. These override the defaults stored in the registry entry (e.g. device="cuda" for ORB / FAIRChem).

Returns:

An ASE Calculator instance.

Raises:

• ValueError – If name is not a recognized model.

• ImportError – If the model is recognized but the provider’s optional dependency is not installed.

class Phonon3Calc(calculator: Calculator | str, *, fc2_supercell: ArrayLike = ((2, 0, 0), (0, 2, 0), (0, 0, 2)), fc3_supercell: ArrayLike = ((2, 0, 0), (0, 2, 0), (0, 0, 2)), mesh_numbers: ArrayLike = (20, 20, 20), disp_kwargs: dict[str, Any] | None = None, thermal_conductivity_kwargs: dict | None = None, relax_structure: bool = True, relax_calc_kwargs: dict | None = None, fmax: float = 0.1, optimizer: str = 'FIRE', t_min: float = 0, t_max: float = 1000, t_step: float = 10, write_phonon3: bool | str | Path = False, write_kappa: bool = False)[source]

Bases: PropCalc

Class for calculating thermal conductivity using third-order force constants.

This class integrates with the Phono3py library to compute thermal conductivity based on third-order force constants (FC3). It includes capabilities for optional structure relaxation, displacement generation, and force calculations on supercells. Results include the thermal conductivity as a function of temperature and other intermediate configurations used in the calculation.

calculator[source]

ASE calculator or universal model name.

fc2_supercell[source]

Supercell matrix for FC2 (phonon supercell).

fc3_supercell[source]

Supercell matrix for FC3.

mesh_numbers[source]

q-mesh dimensions for phono3py.

disp_kwargs[source]

Passed to generate_displacements.

thermal_conductivity_kwargs[source]

Passed to run_thermal_conductivity.

relax_structure[source]

Relax primitive structure before phono3py.

relax_calc_kwargs[source]

Kwargs for RelaxCalc.

fmax[source]

Relaxation force tolerance (eV/Å).

optimizer[source]

Relaxation optimizer name.

t_min, t_max, t_step

Temperature grid for κ(T) (K).

write_phonon3[source]

Path to save phono3py state, True for default, or False.

write_kappa[source]

Whether phono3py writes κ output files.

Initializes the class for thermal conductivity calculation and structure relaxation utilizing third-order force constants (fc3). The class provides configurable parameters for the relaxation process, supercell settings, thermal conductivity calculation, and file output management.

Parameters:

• calculator – ASE calculator or universal model name string.

• fc2_supercell – Phonon (FC2) supercell matrix.

• fc3_supercell – FC3 supercell matrix.

• mesh_numbers – q-point mesh shape.

• disp_kwargs – Kwargs for Phono3py.generate_displacements.

• thermal_conductivity_kwargs – Kwargs for run_thermal_conductivity.

• relax_structure – Relax input before building phono3py.

• relax_calc_kwargs – Kwargs for RelaxCalc.

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

• optimizer – ASE optimizer for relaxation.

• t_min – Minimum temperature for κ (K).

• t_max – Maximum temperature for κ (K).

• t_step – Temperature step (K).

• write_phonon3 – Save path, True for default YAML, or False.

• write_kappa – Pass write_kappa to phono3py RTA.

_abc_impl = <_abc._abc_data object>[source]

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

Performs thermal conductivity calculations using the Phono3py library.

This method processes a given atomic structure and calculates its thermal conductivity through third-order force constants (FC3) computations. The process involves optional relaxation of the input structure, generation of displacements, and force calculations corresponding to the supercell structures. The results include computed thermal conductivity over specified temperatures, along with intermediate Phono3py configurations.

Parameters:

structure – Pymatgen structure, ASE atoms, or dict with structure keys.

Returns:

Dict with phonon3 (Phono3py), temperatures (K), and thermal_conductivity (spatially averaged kappa in W/(m*K) where defined; NaN if unavailable). _units maps each numeric output to its unit string. See phono3py RTA documentation for details.

class PhononCalc(calculator: Calculator | str, *, atom_disp: float = 0.015, min_length: float | None = 20.0, supercell_matrix: ArrayLike | None = None, t_step: float = 10, t_max: float = 1000, t_min: float = 0, fmax: float = 1e-05, max_steps: int = 5000, optimizer: str = 'FIRE', relax_structure: bool = True, relax_calc_kwargs: dict | None = None, imaginary_freq_tol: float = -0.01, on_imaginary_modes: Literal['error', 'warn'] = 'warn', fix_imaginary_attempts: int = 0, symprec: float = 1e-05, write_force_constants: bool | str | Path = False, write_band_structure: bool | str | Path = False, write_total_dos: bool | str | Path = False, write_phonon: bool | str | Path = True)[source]

Bases: PropCalc

A class for phonon and thermal property calculations using phonopy.

The PhononCalc class extends the PropCalc class to provide functionalities for calculating phonon properties and thermal properties of a given structure using the phonopy library. It includes options for structural relaxation before phonon property determination, as well as methods to export calculated properties to various output files for further analysis or visualization.

calculator[source]

ASE calculator or universal model name.

atom_disp[source]

Finite-difference displacement for force constants (Å).

min_length[source]

Minimum supercell dimension (Å); used if supercell_matrix is None.

supercell_matrix[source]

Explicit supercell; overrides min_length when set.

t_step, t_max, t_min

Thermal property temperature grid (K).

fmax[source]

Relaxation force tolerance when relax_structure is used.

max_steps[source]

Max relaxation steps.

optimizer[source]

ASE optimizer name for pre-phonon relaxation.

relax_structure[source]

Relax structure before phonopy.

relax_calc_kwargs[source]

Optional kwargs for RelaxCalc.

imaginary_freq_tol[source]

Frequencies below this (THz) count as imaginary.

on_imaginary_modes[source]

"warn" or "error" on imaginary modes.

fix_imaginary_attempts[source]

Rattle/retry cycles to fix imaginary modes.

symprec[source]

symmetry precision used for spglib symmetry finding.

write_force_constants[source]

Output path for force constants (or False).

write_band_structure[source]

Band structure YAML path (or False).

write_total_dos[source]

Total DOS path (or False).

write_phonon[source]

Phonopy save path (e.g. phonon.yaml) or False.

Parameters:

• calculator – ASE calculator or universal model name string.

• atom_disp – Displacement for phonopy finite differences.

• min_length – Minimum supercell size along each lattice direction (Å).

• supercell_matrix – Integer supercell matrix; if None, derived from min_length.

• t_step – Temperature step for thermal properties (K).

• t_max – Maximum temperature (K).

• t_min – Minimum temperature (K).

• fmax – Relaxation force tolerance (eV/Å).

• max_steps – Maximum relaxation steps before phonopy.

• optimizer – Optimizer for pre-phonon relaxation.

• relax_structure – Whether to relax before building phonopy.

• relax_calc_kwargs – Optional kwargs for RelaxCalc.

• imaginary_freq_tol – Threshold (THz) for classifying imaginary modes.

• on_imaginary_modes – "warn" or "error" when imaginary modes exist.

• fix_imaginary_attempts – Rattle/relax/phonon retries; 0 disables.

• symprec – symmetry precision used for spglib symmetry finding.

• write_force_constants – Path to write FCs, True for default name, or False.

• write_band_structure – Path, True for default YAML, or False.

• write_total_dos – Path, True for default DOS file, or False.

• write_phonon – Path, True for default phonon.yaml, or False.

_abc_impl = <_abc._abc_data object>[source]

_check_imaginary_modes(frequencies: ndarray) → None[source]

Warn or raise if imaginary modes are present, based on on_imaginary_modes setting.

Parameters:

frequencies – Frequencies array from the mesh run.

_rattle_structure(structure_in: Structure, stdev: float = 0.01) → Structure[source]

Rattle the atoms to bump out of stationary point (stdev=0.01 Å).

Parameters:

• structure_in – Pymatgen structure.

• stdev – standard deviation in angstrom for the rattle.

Returns:

Pymatgen structure with rattled atomic positions.

_relax_structure(structure_in: Structure) → dict[source]

Relax a structure.

Parameters:

structure_in – Pymatgen structure.

Returns:

Full result dict from RelaxCalc.

_resolve_imaginary_modes(structure_in: Structure, phonon: phonopy.Phonopy, frequencies: np.ndarray, disp_supercells: list) → tuple[dict, phonopy.Phonopy, np.ndarray, list[Structure]][source]

Attempt to resolve imaginary modes by rattling and re-relaxing.

Parameters:

• structure_in – Current primitive-cell structure.

• phonon – Phonopy object from the most recent build.

• frequencies – Frequencies from the most recent mesh run.

• disp_supercells – Displaced supercells from the most recent build.

Returns:

Updated (RelaxCalc dictionary, phonon, frequencies, disp_supercells).

_run_phonopy(structure: Structure) → tuple[phonopy.Phonopy, np.ndarray, list[Structure]][source]

Build a Phonopy object, run force calculations, and return (phonon, frequencies, disp_supercells).

Parameters:

structure – Pymatgen structure.

Returns:

Tuple of (phonon, frequencies, disp_supercells).

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

Compute phonons and thermal properties with phonopy.

Parameters:

structure – Pymatgen structure, ASE atoms, or dict with structure keys.

Returns:

Dict with phonon (phonopy.Phonopy), thermal_properties (phonopy thermal dict: temperatures in K, free_energy in kJ/mol, entropy in J/(K*mol), heat_capacity in J/(K*mol)), frequencies in THz, disp_supercells, plus any relaxation fields merged in. _units maps each numeric output to its unit string.