dft.pseudopotentials

Pseudopotential and ion models for the DFT prototype.

import mlx_atomistic.dft.pseudopotentials

Classes

Ion

class Ion
    def __init__(symbol: str, position: Sequence[float], pseudopotential: PseudopotentialData)

Ion center with a parsed pseudopotential.

Parameters

Name	Type	Default	Description
symbol	str
position	Sequence[float]
pseudopotential	PseudopotentialData

Properties

• charge float — Valence charge represented by this pseudopotential.

IonCollection

class IonCollection
    def __init__(ions: Sequence[Ion])

Collection of ions and their pseudopotentials.

Parameters

Name	Type	Default	Description
ions	Sequence[Ion]

Properties

• centers mx.array — Ion center coordinates.
• charges tuple[float, ...] — Valence charges.
• formats tuple[str, ...] — Pseudopotential formats in ion order.
• nonlocal_available bool — Whether any ion has parsed nonlocal projectors.
• symbols tuple[str, ...] — Ion symbols.
• valence_electron_count float — Neutral valence electron count.

Methods

with_positions

def with_positions(positions: Sequence[Sequence[float]]) -> IonCollection

Return a copy with updated positions.

Parameters

Name	Type	Default	Description
positions	Sequence[Sequence[float]]

Returns

• IonCollection

LocalPseudopotentialField

class LocalPseudopotentialField
    def __init__(ions: IonCollection)

Real-space local potential generated by an IonCollection.

Parameters

Name	Type	Default	Description
ions	IonCollection

Properties

• centers mx.array — Ion center coordinates.
• nonlocal_available bool — Whether nonlocal metadata is present.

Methods

field

def field(grid: RealSpaceGrid) -> mx.array

Evaluate the total local ion potential on a real-space grid.

Parameters

Name	Type	Default	Description
grid	RealSpaceGrid

Returns

• mx.array

forces

def forces(density: mx.array, grid: RealSpaceGrid) -> mx.array

Return local electron-ion forces from a density.

Parameters

Name	Type	Default	Description
density	mx.array
grid	RealSpaceGrid

Returns

• mx.array

NonlocalProjectorData

class NonlocalProjectorData
    def __init__(angular_momentum: int, values: tuple[float, ...] = (), radial_grid: RadialGrid | None = None, cutoff_radius: float | None = None, coefficients: tuple[float, ...] = (), coupling: float = 0.0, metadata: dict[str, str | int | float] | None = None)

Parsed nonlocal projector metadata.

Milestone 4 stores this data but intentionally does not apply nonlocal projectors in the Kohn-Sham operator yet.

Parameters

Name	Type	Default	Description
angular_momentum	int
values	tuple[float, ...]	()
radial_grid	RadialGrid | None	None
cutoff_radius	float | None	None
coefficients	tuple[float, ...]	()
coupling	float	0.0
metadata	dict[str, str | int | float] | None	None

PseudopotentialData

class PseudopotentialData
    def __init__(element: str, format: PseudopotentialFormat, valence_charge: float, local_grid: RadialGrid | None = None, gth_rloc: float | None = None, gth_coefficients: tuple[float, ...] = (), nonlocal_projectors: tuple[NonlocalProjectorData, ...] = (), metadata: dict[str, str | int | float | bool] | None = None)

Parsed pseudopotential data used by ion-centered local fields.

Parameters

Name	Type	Default	Description
element	str
format	PseudopotentialFormat
valence_charge	float
local_grid	RadialGrid | None	None
gth_rloc	float | None	None
gth_coefficients	tuple[float, ...]	()
nonlocal_projectors	tuple[NonlocalProjectorData, ...]	()
metadata	dict[str, str | int | float | bool] | None	None

Properties

• nonlocal_available bool — Whether the source file contained nonlocal projector metadata.

Methods

apply_nonlocal

def apply_nonlocal(_orbitals: mx.array, _grid: RealSpaceGrid) -> mx.array

Reject nonlocal application until the Milestone 5+ operator path exists.

Parameters

Name	Type	Default	Description
_orbitals	mx.array
_grid	RealSpaceGrid

Returns

• mx.array

local_derivative

def local_derivative(radius: np.ndarray) -> np.ndarray

Evaluate dV_local/dr in Hartree/bohr.

Parameters

Name	Type	Default	Description
radius	np.ndarray

Returns

• np.ndarray

local_potential

def local_potential(radius: np.ndarray) -> np.ndarray

Evaluate the local potential in Hartree on radii in bohr.

Parameters

Name	Type	Default	Description
radius	np.ndarray

Returns

• np.ndarray

PseudopotentialFormat

class PseudopotentialFormat(StrEnum)

Supported pseudopotential file families.

RadialGrid

class RadialGrid
    def __init__(radii: Sequence[float], values: Sequence[float])

Radial samples for a local pseudopotential channel.

Parameters

Name	Type	Default	Description
radii	Sequence[float]
values	Sequence[float]

Properties

• size int — Number of radial samples.

Methods

derivative

def derivative(r: np.ndarray, *, tail_charge: float | None = None) -> np.ndarray

Interpolate dV/dr at radius r.

Parameters

Name	Type	Default	Description
r	np.ndarray
tail_charge	float | None	None

Returns

• np.ndarray

interpolate

def interpolate(r: np.ndarray, *, tail_charge: float | None = None) -> np.ndarray

Interpolate values at radius r with a Coulomb tail fallback.

Parameters

Name	Type	Default	Description
r	np.ndarray
tail_charge	float | None	None

Returns

• np.ndarray

Functions

read_gth

def read_gth(path_or_database: str | Path, *, element: str | None = None, name: str | None = None) -> PseudopotentialData

Read a single GTH file or one entry from a CP2K-style GTH database.

Parameters

Name	Type	Default	Description
path_or_database	str | Path
element	str | None	None
name	str | None	None

Returns

• PseudopotentialData

read_upf

def read_upf(path: str | Path) -> PseudopotentialData

Read a UPF v2-style pseudopotential file.

Parameters

Name	Type	Default	Description
path	str | Path

Returns

• PseudopotentialData