dft.periodic_stress

Controlled finite-difference stress for periodic plane-wave DFT.

import mlx_atomistic.dft.periodic_stress

Classes

PeriodicStressConfig

class PeriodicStressConfig
    def __init__(mode: PeriodicStressMode = 'symmetric', strain_step: float = 0.001, electronic_response: PeriodicStressElectronicResponse = 'frozen_variational', variational_energy_tolerance: float = 5e-05, stress_consistency_tolerance: float = 2e-05, reuse_scf_state: bool = True, require_fixed_basis_topology: bool = True)

Shared controls for analytic stress and its numerical oracle.

Parameters

Name	Type	Default	Description
mode	PeriodicStressMode	'symmetric'	isotropic, diagonal, or complete symmetric stress.
strain_step	float	0.001	Dimensionless central-difference oracle strain.
electronic_response	PeriodicStressElectronicResponse	'frozen_variational'	Oracle response: frozen_variational or diagnostic reconverged.
variational_energy_tolerance	float	5e-05	Maximum base frozen-functional mismatch in Hartree.
stress_consistency_tolerance	float	2e-05	Maximum oracle stress disagreement between primary and doubled frozen-variational strain steps.
reuse_scf_state	bool	True	Seed diagnostic reconverged oracle SCFs from the converged base density and compact orbitals.
require_fixed_basis_topology	bool	True	Transport the base integer-G topology in every oracle branch instead of reselecting at the cutoff.

Methods

to_dict

def to_dict() -> dict[str, object]

Return canonical JSON-safe stress controls.

Returns

• dict[str, object]

PeriodicStressResult

class PeriodicStressResult
    def __init__(stress: np.ndarray, pressure: float, base_scf: PeriodicSCFResult, samples: tuple[PeriodicStressSample, ...], config: PeriodicStressConfig, elapsed_ms: float, scf_evaluations: int, continuation_density_uses: int, effective_strain_steps: dict[str, float] = dict(), base_variational_energy_error: float | None = None, stress_consistency_errors: dict[str, float] = dict(), method: Literal['analytic', 'finite_difference'] = 'finite_difference', base_energy_by_term: dict[str, float] = dict())

Compression-positive stress from a converged periodic free energy.

Parameters

Name	Type	Default	Description
stress	np.ndarray
pressure	float
base_scf	PeriodicSCFResult
samples	tuple[PeriodicStressSample, ...]
config	PeriodicStressConfig
elapsed_ms	float
scf_evaluations	int
continuation_density_uses	int
effective_strain_steps	dict[str, float]	dict()
base_variational_energy_error	float | None	None
stress_consistency_errors	dict[str, float]	dict()
method	Literal['analytic', 'finite_difference']	'finite_difference'
base_energy_by_term	dict[str, float]	dict()

Properties

• pressure_gpa float — Return hydrostatic pressure in GPa.
• stress_gpa np.ndarray — Return the compression-positive stress tensor in GPa.

Methods

to_dict

def to_dict() -> dict[str, object]

Return a JSON-safe stress report without dense electronic arrays.

Returns

• dict[str, object]

PeriodicStressSample

class PeriodicStressSample
    def __init__(component: str, level: str, sign: int, strain: np.ndarray, energy: float, energy_by_term: dict[str, float], volume: float, scf_iterations: int | None, density_residual: float | None, energy_delta: float | None, used_density_continuation: bool, active_counts: tuple[int, ...])

One converged strained-energy sample.

Parameters

Name	Type	Default	Description
component	str
level	str
sign	int
strain	np.ndarray
energy	float
energy_by_term	dict[str, float]
volume	float
scf_iterations	int | None
density_residual	float | None
energy_delta	float | None
used_density_continuation	bool
active_counts	tuple[int, ...]

Methods

to_dict

def to_dict() -> dict[str, object]

Return a JSON-safe strained sample.

Returns

• dict[str, object]

Functions

periodic_analytic_stress

def periodic_analytic_stress(system: PeriodicDFTSystem, *, cutoff_hartree: float, kpoint_mesh: KPointMesh, n_bands: int | None = None, config: PeriodicStressConfig | None = None, scf_config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, observer: RuntimeObserver | None = None, base_result: PeriodicSCFResult | None = None) -> PeriodicStressResult

Evaluate compression-positive periodic stress by energy differentiation.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic GTH system at the current cell.
cutoff_hartree	float		Fixed plane-wave kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Fixed reduced-coordinate k-point mesh.
n_bands	int | None	None	Fixed computed band count.
config	PeriodicStressConfig | None	None	Tensor mode and analytic admission tolerances.
scf_config	PeriodicSCFConfig | None	None	Exact periodic SCF controls.
xc_functional	ExchangeCorrelationFunctional | None	None	MLX PBE exchange-correlation functional.
observer	RuntimeObserver | None	None	Optional shared runtime observer.
base_result	PeriodicSCFResult | None	None	Optional converged SCF state for the exact base system.

Returns

• PeriodicStressResult — Analytic compression-positive stress and its converged base state.

Raises

• TypeError — If public inputs have unsupported types.
• ValueError — If state identity, energy reconciliation, or functional support fails.

periodic_finite_difference_stress

def periodic_finite_difference_stress(system: PeriodicDFTSystem, *, cutoff_hartree: float, kpoint_mesh: KPointMesh, n_bands: int | None = None, config: PeriodicStressConfig | None = None, scf_config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, observer: RuntimeObserver | None = None, base_result: PeriodicSCFResult | None = None) -> PeriodicStressResult

Evaluate compression-positive periodic stress by central strain.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic GTH system at the unstrained cell.
cutoff_hartree	float		Fixed plane-wave kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Fixed reduced-coordinate k-point mesh.
n_bands	int | None	None	Fixed computed band count.
config	PeriodicStressConfig | None	None	Numerical strain and topology controls.
scf_config	PeriodicSCFConfig | None	None	Exact periodic SCF controls.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional.
observer	RuntimeObserver | None	None	Optional shared runtime observer.
base_result	PeriodicSCFResult | None	None	Optional converged SCF state for the exact base system.

Returns

• PeriodicStressResult — Compression-positive stress, pressure, and every strained sample.

Raises

• TypeError — If public inputs have unsupported types.
• ValueError — If SCF convergence, identity, or plane-wave topology fails.