dft.periodic_upf

Periodic local and nonlocal operators for numerical UPF data.

import mlx_atomistic.dft.periodic_upf

Classes

PeriodicUPFNonlocalOperator

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

Compact separable scalar norm-conserving UPF operator.

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 UPF operator to one orbital or a 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]

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 UPF 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-UPF 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 UPF metadata.

Returns

• dict[str, object]

Functions

periodic_upf_local_forces

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

Return analytic fixed-cell local-UPF Hellmann—Feynman forces.

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 UPF pseudopotential.
basis	PlaneWaveBasis		Plane-wave basis supplying reciprocal vectors and volume.
positions	Sequence[Sequence[float]]		Ionic Cartesian positions in bohr.

Returns

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

upf_local_potential_grid

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

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

Parameters

Name	Type	Default	Description
pseudopotential	PseudopotentialData | Sequence[PseudopotentialData]		One shared or one-per-ion parsed UPF 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.

upf_local_reciprocal_coefficients

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

Return periodic UPF local-potential Fourier coefficients.

The numerical transform follows Quantum ESPRESSO’s compensated vloc convention. It removes erf(r) / r before radial integration, restores the analytic reciprocal-space Coulomb tail, and uses the finite G=0 alpha term.

Parameters

Name	Type	Default	Description
pseudopotential	PseudopotentialData | Sequence[PseudopotentialData]		One shared or one-per-ion parsed UPF 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.