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: _GTHProjectorCache | None = None, cache_budget_bytes: int = _GTHProjectorCache.DEFAULT_BUDGET_BYTES)

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

Parameters

Name	Type	Default
`pseudopotential`	`PseudopotentialData \| Sequence[PseudopotentialData]`
`basis`	`PlaneWaveBasis`
`positions`	`Sequence[Sequence[float]]`
`cache`	`_GTHProjectorCache \| None`	`None`
`cache_budget_bytes`	`int`	`_GTHProjectorCache.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	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	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_ewald_energy`

def periodic_ewald_energy(charges: Sequence[float], positions: Sequence[Sequence[float]], cell_lengths: Sequence[float], *, eta: float | None = None, tolerance: float = 1e-10) -> float

Return periodic point-charge Ewald energy with neutralizing background.

Parameters

Name	Type	Default	Description
`charges`	`Sequence[float]`		Point charges in atomic units.
`positions`	`Sequence[Sequence[float]]`		Cartesian positions in bohr.
`cell_lengths`	`Sequence[float]`		Orthorhombic cell lengths in bohr.
`eta`	`float \| None`	`None`	Optional Ewald splitting parameter in inverse bohr. Defaults to a cell-scaled value.
`tolerance`	`float`	`1e-10`	Real/reciprocal truncation target. Defaults to `1e-10`.

Returns

float — Ewald energy in Hartree.

`periodic_ewald_forces`

def periodic_ewald_forces(charges: Sequence[float], positions: Sequence[Sequence[float]], cell_lengths: Sequence[float], *, displacement: float = 0.0001, eta: float | None = None, tolerance: float = 1e-10, method: str = 'analytic') -> np.ndarray

Return forces for the periodic Ewald ion-ion energy.

Parameters

Name	Type	Default	Description
`charges`	`Sequence[float]`		Point charges in atomic units.
`positions`	`Sequence[Sequence[float]]`		Cartesian positions in bohr.
`cell_lengths`	`Sequence[float]`		Orthorhombic cell lengths in bohr.
`displacement`	`float`	`0.0001`	Central-difference step used only when `method="finite_difference"`. Defaults to `1e-4`.
`eta`	`float \| None`	`None`	Optional Ewald splitting parameter. Defaults to a cell-scaled value.
`tolerance`	`float`	`1e-10`	Ewald truncation target. Defaults to `1e-10`.
`method`	`str`	`'analytic'`	`"analytic"` or the validation-only `"finite_difference"`. Defaults to `"analytic"`.

Returns

np.ndarray — Force array with shape (n_ions, 3) in Hartree/bohr.

`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	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.