matcalc._qha module
Calculator for phonon properties under quasi-harmonic approximation.
- class QHACalc(calculator: Calculator | str, *, t_step: float = 10, t_max: float = 1000, t_min: float = 0, pressure: None | float | Sequence[float] = None, fmax: float = 1e-05, max_steps: int = 5000, optimizer: str = 'FIRE', eos: Literal['vinet', 'birch_murnaghan', 'murnaghan'] = 'vinet', allow_shape_change: bool = True, relax_structure: bool = True, relax_calc_kwargs: dict | None = None, phonon_calc_kwargs: dict | None = None, scale_factors: Sequence[float] = (0.95, 0.96, 0.97, 0.98, 0.99, 1.0, 1.01, 1.02, 1.03, 1.04, 1.05), imaginary_freq_tol: float = -0.01, on_imaginary_modes: Literal['error', 'warn'] = 'warn', fix_imaginary_attempts: int = 0, write_helmholtz_volume: bool | str | os.PathLike = False, write_volume_temperature: bool | str | os.PathLike = False, write_thermal_expansion: bool | str | os.PathLike = False, write_gibbs_temperature: bool | str | os.PathLike = False, write_bulk_modulus_temperature: bool | str | os.PathLike = False, write_heat_capacity_p_numerical: bool | str | os.PathLike = False, write_heat_capacity_p_polyfit: bool | str | os.PathLike = False, write_gruneisen_temperature: bool | str | os.PathLike = False)[source]
Bases:
PropCalcClass for performing quasi-harmonic approximation calculations.
This class utilizes phonopy and Pymatgen-based structure manipulation to calculate thermal properties such as Gibbs free energy, thermal expansion, heat capacity, and bulk modulus as a function of temperature under the quasi-harmonic approximation. It allows for structural relaxation, handling customized scale factors for lattice constants, and fine-tuning various calculation parameters. Calculation results can be selectively saved to output files.
- t_step, t_max, t_min
Temperature grid (K) for QHA output.
- pressure[source]
Target pressure(s) in GPa. Accepts a single float, a list of floats, or None. When multiple pressures are given the expensive phonon calculations are run once and the cheap QHA fitting is repeated per pressure.
- imaginary_freq_tol, on_imaginary_modes, fix_imaginary_attempts
Passed to
PhononCalc.
- write_*
Output paths (or True for defaults) for phonopy QHA text files. When multiple pressures are requested a
_P{pressure}GPasuffix is inserted before the file extension to avoid overwriting files across pressures.
- Parameters:
calculator – ASE calculator or universal model name string.
t_step – Temperature sampling step (K).
t_max – Maximum temperature (K).
t_min – Minimum temperature (K).
pressure – Pressure in GPa for Gibbs terms. Accepts a single float, a list of floats, or None. When multiple pressures are supplied the phonon calculations are performed only once and the QHA fit is repeated for each pressure.
fmax – Force tolerance for relaxations.
max_steps – Max steps per relaxation.
optimizer – ASE optimizer name.
eos – EOS key for
PhonopyQHA.allow_shape_change – Allow shape relaxation at constant volume for scaled cells.
relax_structure – Relax input once before scanning
scale_factors.relax_calc_kwargs – Extra kwargs for every
RelaxCalc.phonon_calc_kwargs – Extra kwargs for each
PhononCalc.scale_factors – Volume scale factors applied to the relaxed structure.
imaginary_freq_tol – Imaginary-mode threshold (THz) for
PhononCalc.on_imaginary_modes –
"warn"or"error".fix_imaginary_attempts – Imaginary-mode retries per scale factor in
PhononCalc.write_helmholtz_volume – Write F(V); True selects default filename.
write_volume_temperature – Write V(T).
write_thermal_expansion – Write thermal expansion alpha(T).
write_gibbs_temperature – Write G(T).
write_bulk_modulus_temperature – Write B(T).
write_heat_capacity_p_numerical – Write Cp(T) numerical.
write_heat_capacity_p_polyfit – Write Cp(T) polyfit.
write_gruneisen_temperature – Write Gruneisen gamma(T).
- _calculate_thermal_properties(structure: Structure) dict[source]
Helper to calculate the thermal properties of a structure.
- Parameters:
structure – Pymatgen structure for which the thermal properties are calculated.
- Returns:
Full result dict from PhononCalc, containing “energy” (eV, from the volume-fixed ionic relaxation) and “thermal_properties” (free energies, entropies and heat capacities).
- _collect_properties(structure: Structure) dict[str, list][source]
Helper to collect properties like volumes, electronic energies, and thermal properties.
- Parameters:
structure – Primitive cell structure at the reference volume.
- Returns:
Dict of lists keyed by
volumes,electronic_energies,free_energies,entropies,heat_capacities, andscaled_structures.
- _scale_structure(structure: Structure, scale_factor: float) Structure[source]
Helper to scale the lattice of a structure.
- Parameters:
structure – Pymatgen structure to be scaled.
scale_factor – Factor by which the lattice constants are scaled.
- Returns:
Pymatgen structure with scaled lattice constants.
- _write_output_files(qha: PhonopyQHA, pressure: float | None = None) None[source]
Helper to write various output files based on the QHA calculation.
When multiple pressures are requested, a
_P{pressure}GPasuffix is inserted before the file extension to avoid overwriting files across pressures.- Parameters:
qha – Phonopy.qha object.
pressure – The pressure (GPa) associated with this QHA fit, or None.
- calc(structure: Structure | Atoms | dict[str, Any]) dict[source]
Quasi-harmonic thermodynamics via phonopy over a volume scan.
- Parameters:
structure – Pymatgen structure, ASE atoms, or dict with structure keys.
- Returns:
Dict with per-volume data (
scale_factors,volumes,electronic_energies,scaled_structures), apressureslist, and aqha_resultslist of per-pressure dicts each containingpressure,qha,temperatures,thermal_expansion_coefficients,gibbs_free_energies,bulk_modulus_P,heat_capacity_P, andgruneisen_parameters. When only a single pressure was requested the top-level dict also contains those keys directly for backward compatibility. Merged with any relaxation fields from earlier steps. Units follow phonopy QHA.