dft.periodic_density_volume

Portable periodic charge and magnetization density volumes.

import mlx_atomistic.dft.periodic_density_volume

Classes

PeriodicDensityVolume

class PeriodicDensityVolume
    def __init__(cell_matrix_bohr: np.ndarray, positions_bohr: np.ndarray, symbols: tuple[str, ...], charge_density_electron_per_bohr3: np.ndarray, magnetization_density_electron_per_bohr3: np.ndarray | None, electron_count: float, integrated_magnetization: float | None, system_fingerprint: str)

Validated periodic scalar fields and their full-rank geometry.

Parameters

Name	Type	Default	Description
cell_matrix_bohr	np.ndarray
positions_bohr	np.ndarray
symbols	tuple[str, ...]
charge_density_electron_per_bohr3	np.ndarray
magnetization_density_electron_per_bohr3	np.ndarray | None
electron_count	float
integrated_magnetization	float | None
system_fingerprint	str

Properties

• cell_volume_bohr3 float — Return the right-handed cell volume in bohr cubed.
• grid_shape tuple[int, int, int] — Return the stored fractional-grid shape.

Methods

to_dict

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

Return a JSON-safe volume summary without field arrays.

Returns

• dict[str, object]

Functions

periodic_density_volume

def periodic_density_volume(system: PeriodicDFTSystem, source: PeriodicSCFResult) -> PeriodicDensityVolume

Build a portable density volume from a matching converged periodic SCF.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic system that produced source.
source	PeriodicSCFResult		Converged scalar or collinear-spin SCF result.

Returns

• PeriodicDensityVolume — Validated immutable charge and optional magnetization volume.

Raises

• TypeError — If inputs use unsupported types.
• ValueError — If convergence, fingerprint, shape, or normalization differ.

read_periodic_density_volume

def read_periodic_density_volume(path: str | Path) -> PeriodicDensityVolume

Load and validate a portable periodic density volume without pickle.

Parameters

Name	Type	Default	Description
path	str | Path		Existing density-volume NPZ file.

Returns

• PeriodicDensityVolume — Validated immutable periodic density volume.

Raises

• ValueError — If schema, inventory, metadata, arrays, or normalization are invalid.

write_periodic_density_volume

def write_periodic_density_volume(path: str | Path, system: PeriodicDFTSystem, source: PeriodicSCFResult) -> Path

Atomically publish a portable no-pickle periodic density volume.

Parameters

Name	Type	Default	Description
path	str | Path		Previously absent output NPZ path.
system	PeriodicDFTSystem		Periodic system that produced source.
source	PeriodicSCFResult		Converged scalar or collinear-spin SCF result.

Returns

• Path — Resolved published path.

Raises

• FileExistsError — If the destination already exists.
• ValueError — If the source cannot form a valid density volume.