dft.periodic_gth

Analytical periodic GTH operators for cutoff-projected plane waves.

import mlx_atomistic.dft.periodic_gth

Classes

PeriodicGTHNonlocalOperator

class PeriodicGTHNonlocalOperator
    def __init__(pseudopotential: PseudopotentialData | Sequence[PseudopotentialData], basis: PlaneWaveBasis, positions: Sequence[Sequence[float]], *, cache: _ProjectorCache | None = None, cache_budget_bytes: int = _ProjectorCache.DEFAULT_BUDGET_BYTES)

Complete compact separable GTH operator at one Bloch k-point.

Parameters

Name	Type	Default	Description
pseudopotential	PseudopotentialData | Sequence[PseudopotentialData]
basis	PlaneWaveBasis
positions	Sequence[Sequence[float]]
cache	_ProjectorCache | None	None
cache_budget_bytes	int	_ProjectorCache.DEFAULT_BUDGET_BYTES

Methods

apply

def apply(coefficients: mx.array) -> mx.array

Apply the nonlocal operator to one orbital or an orbital stack.

Parameters

Name	Type	Default	Description
coefficients	mx.array		One admitted coefficient grid or a stack.

Returns

• mx.array — Nonlocal operator action with the same shape.

cache_info

def cache_info() -> dict[str, int]

Return bounded projector-cache accounting.

Returns

• dict[str, int] — Budget, retained/peak bytes, entries, evictions, and invalidations.

close

def close() -> None

Release an operator-owned projector cache context.

Returns

• None

energy

def energy(coefficients: mx.array, *, occupations: Sequence[float]) -> mx.array

Return occupied nonlocal energy in Hartree.

Parameters

Name	Type	Default	Description
coefficients	mx.array		Orbital stack in the admitted basis.
occupations	Sequence[float]		One occupation per orbital.

Returns

• mx.array — Real occupied nonlocal energy.

forces

def forces(coefficients: mx.array, *, occupations: Sequence[float]) -> mx.array

Return analytic nonlocal-GTH Hellmann—Feynman forces.

Parameters

Name	Type	Default	Description
coefficients	mx.array		Orbital stack in the admitted basis.
occupations	Sequence[float]		One occupation per orbital.

Returns

• mx.array — Nonlocal forces with shape (n_ions, 3) in Hartree/bohr.

to_dict

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

Return JSON-safe nonlocal operator metadata.

Returns

• dict[str, object] — Channel, projector, angular, ion, and k-point metadata.

Functions

gth_local_potential_grid

def gth_local_potential_grid(pseudopotential: PseudopotentialData | Sequence[PseudopotentialData], basis: PlaneWaveBasis, positions: Sequence[Sequence[float]]) -> mx.array

Return the real periodic local GTH potential on the FFT grid.

Parameters

Name	Type	Default	Description
pseudopotential	PseudopotentialData | Sequence[PseudopotentialData]		One shared or one-per-ion parsed GTH pseudopotential.
basis	PlaneWaveBasis		Plane-wave basis supplying the FFT grid.
positions	Sequence[Sequence[float]]		Ionic Cartesian positions in bohr.

Returns

• mx.array — Real local potential with shape basis.grid.shape.

gth_local_reciprocal_coefficients

def gth_local_reciprocal_coefficients(pseudopotential: PseudopotentialData | Sequence[PseudopotentialData], basis: PlaneWaveBasis, positions: Sequence[Sequence[float]]) -> mx.array

Return periodic local GTH Fourier-series coefficients.

The formula follows Quantum ESPRESSO’s analytical GTH transform in Hartree units, including the finite G=0 limit and ionic structure factor.

Parameters

Name	Type	Default	Description
pseudopotential	PseudopotentialData | Sequence[PseudopotentialData]		One shared or one-per-ion parsed GTH pseudopotential.
basis	PlaneWaveBasis		Plane-wave basis supplying reciprocal vectors and volume.
positions	Sequence[Sequence[float]]		Ionic Cartesian positions in bohr.

Returns

• mx.array — Complex local-potential coefficients with shape basis.grid.shape.

periodic_gth_local_forces

def periodic_gth_local_forces(density: mx.array, pseudopotential: PseudopotentialData | Sequence[PseudopotentialData], basis: PlaneWaveBasis, positions: Sequence[Sequence[float]]) -> mx.array

Return analytic local-GTH Hellmann—Feynman forces.

The derivative is evaluated in reciprocal space from the converged electron density and the phase derivative of each ionic local potential.

Parameters

Name	Type	Default	Description
density	mx.array		Positive electron density on basis.grid.
pseudopotential	PseudopotentialData | Sequence[PseudopotentialData]		One shared or one-per-ion parsed GTH pseudopotential.
basis	PlaneWaveBasis		Plane-wave basis supplying the FFT grid and reciprocal vectors.
positions	Sequence[Sequence[float]]		Ionic Cartesian positions in bohr.

Returns

• mx.array — Local electron-ion forces with shape (n_ions, 3) in Hartree/bohr.