dft.periodic_phonons

Symmetry-reduced finite-displacement phonons for periodic DFT systems.

import mlx_atomistic.dft.periodic_phonons

Functions

assemble_periodic_phonons

def assemble_periodic_phonons(plan: PeriodicDisplacementPlan, samples: PeriodicPhononSampleSet, masses_amu: Sequence[float], *, config: PeriodicPhononConfig | None = None) -> PeriodicPhononResult

Assemble raw force constants and admitted Gamma-point phonon modes.

Parameters

Name	Type	Default	Description
plan	PeriodicDisplacementPlan		Symmetry-independent displacement plan.
samples	PeriodicPhononSampleSet		Complete central-force samples bound to plan.
masses_amu	Sequence[float]		Positive per-atom masses in atomic mass units.
config	PeriodicPhononConfig | None	None	Numerical diagnostics. Its displacement must match plan.

Returns

• PeriodicPhononResult — Raw force constants, diagnostics, and modes only when raw force-
• PeriodicPhononResult — constant gates pass.

Raises

• TypeError — If inputs use unsupported types.
• ValueError — If samples, masses, displacement, or reconstruction differ.

compare_periodic_phonon_displacements

def compare_periodic_phonon_displacements(coarse: PeriodicPhononResult, fine: PeriodicPhononResult, *, config: PeriodicPhononConfig | None = None) -> PeriodicPhononConvergenceResult

Compare complete phonon modes at two displacement magnitudes.

Parameters

Name	Type	Default	Description
coarse	PeriodicPhononResult		Result at the larger displacement.
fine	PeriodicPhononResult		Result at the smaller displacement.
config	PeriodicPhononConfig | None	None	Convergence tolerances. Defaults to PeriodicPhononConfig.

Returns

• PeriodicPhononConvergenceResult — Maximum frequency and eigenvalue drifts with aggregate status.

evaluate_periodic_phonon_sample

def evaluate_periodic_phonon_sample(system: PeriodicDFTSystem, plan: PeriodicDisplacementPlan, representative_dof: int, *, cutoff_hartree: float, kpoint_mesh: KPointMesh, n_bands: int | None = None, scf_config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, observer: RuntimeObserver | None = None) -> PeriodicPhononSample

Evaluate both central-force signs for one planned displacement.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Equilibrium periodic system matching plan.
plan	PeriodicDisplacementPlan		Symmetry-independent displacement plan.
representative_dof	int		Planned degree of freedom to evaluate.
cutoff_hartree	float		Plane-wave kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Weighted reduced-coordinate electronic k-point mesh.
n_bands	int | None	None	Optional computed band count.
scf_config	PeriodicSCFConfig | None	None	Optional periodic SCF controls.
xc_functional	ExchangeCorrelationFunctional | None	None	Optional exchange-correlation functional.
observer	RuntimeObserver | None	None	Optional shared runtime observer for both signs.

Returns

• PeriodicPhononSample — Fingerprinted minus/plus analytic-force sample.

Raises

• ValueError — If either displaced SCF does not converge.

periodic_phonon_displaced_system

def periodic_phonon_displaced_system(system: PeriodicDFTSystem, plan: PeriodicDisplacementPlan, representative_dof: int, direction_sign: int) -> PeriodicDFTSystem

Return one plus or minus representative displaced periodic system.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Exact equilibrium system used to build plan.
plan	PeriodicDisplacementPlan		Matching displacement plan.
representative_dof	int		Planned independent Cartesian degree of freedom.
direction_sign	int		Minus one or plus one.

Returns

• PeriodicDFTSystem — New fixed-cell system with one Cartesian coordinate displaced.

plan_periodic_phonon_displacements

def plan_periodic_phonon_displacements(system: PeriodicDFTSystem, *, config: PeriodicPhononConfig | None = None, symmetry_operations: Sequence[PeriodicPhononSymmetry] = (), position_tolerance_bohr: float = 1e-06) -> PeriodicDisplacementPlan

Build a validated symmetry-independent Cartesian displacement plan.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic DFT system at its equilibrium geometry.
config	PeriodicPhononConfig | None	None	Phonon numerical controls. Defaults to PeriodicPhononConfig.
symmetry_operations	Sequence[PeriodicPhononSymmetry]	()	Explicit affine crystal symmetries. Identity is always added.
position_tolerance_bohr	float	1e-06	Atomic symmetry matching tolerance in bohr.

Returns

• PeriodicDisplacementPlan — Fingerprint-bound displacement orbits covering all Cartesian degrees
• PeriodicDisplacementPlan — of freedom.

Raises

• TypeError — If inputs use unsupported types.
• ValueError — If the system, tolerance, symmetries, or group action fail.