dft.artifacts

Atomic compact checkpoint publication and explicit periodic-SCF resume.

import mlx_atomistic.dft.artifacts

Classes

PeriodicSCFCheckpoint

class PeriodicSCFCheckpoint
    def __init__(root: Path, manifest: Mapping[str, object], metadata: Mapping[str, object], _state: _PeriodicSCFContinuationState)

Validated checkpoint envelope and private continuation payload.

Parameters

Name	Type	Default	Description
root	Path		Completed generation root.
manifest	Mapping[str, object]		Validated shared atomic-generation manifest.
metadata	Mapping[str, object]		Validated checkpoint payload metadata.
_state	_PeriodicSCFContinuationState

Methods

to_dict

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

Return a JSON-safe checkpoint summary without numerical arrays.

Returns

• dict[str, object]

PeriodicSCFExecutionIdentity

class PeriodicSCFExecutionIdentity
    def __init__(workload_fingerprint: str, protocol_fingerprint: str, runtime_fingerprint: str, execution_contract_fingerprint: str, execution_contract: Mapping[str, object])

Path-independent pre-execution identity required for checkpoint reuse.

Parameters

Name	Type	Default	Description
workload_fingerprint	str		Canonical workload and GTH-resource fingerprint.
protocol_fingerprint	str		Frozen measurement-protocol source fingerprint.
runtime_fingerprint	str		Complete executing periodic-DFT source fingerprint.
execution_contract_fingerprint	str		Hash of execution_contract.
execution_contract	Mapping[str, object]		Full canonical pre-run execution contract.

Methods

from_context

def from_context(context: Mapping[str, object]) -> PeriodicSCFExecutionIdentity

Construct identity from the existing DFT execution-context mapping.

Parameters

Name	Type	Default	Description
context	Mapping[str, object]		Mapping returned by the frozen build_execution_context function, or an equivalent path-independent mapping.

Returns

• PeriodicSCFExecutionIdentity — Validated checkpoint execution identity.

to_dict

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

Return the four non-circular artifact-manifest identity fields.

Returns

• dict[str, str]

Functions

inspect_periodic_scf_checkpoint

def inspect_periodic_scf_checkpoint(artifact: str | Path, *, expected_execution_context: PeriodicSCFExecutionIdentity | Mapping[str, object] | None = None) -> dict[str, object]

Validate checkpoint integrity and identity metadata without array loading.

Parameters

Name	Type	Default	Description
artifact	str | Path		Explicit completed checkpoint generation or nested payload.
expected_execution_context	PeriodicSCFExecutionIdentity | Mapping[str, object] | None	None	Optional current context requiring an exact workload/protocol/runtime/execution-contract identity match.

Returns

• dict[str, object] — JSON-safe checkpoint summary.

Raises

• ArtifactIntegrityError — If integrity, schema, or identity validation fails.

load_periodic_scf_checkpoint

def load_periodic_scf_checkpoint(artifact: str | Path, *, system: PeriodicDFTSystem, cutoff_hartree: float, kpoint_mesh: KPointMesh, execution_context: PeriodicSCFExecutionIdentity | Mapping[str, object], n_bands: int | None = None, config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None) -> PeriodicSCFCheckpoint

Load one explicit checkpoint after complete identity and payload validation.

Parameters

Name	Type	Default	Description
artifact	str | Path		Explicit completed checkpoint generation or nested payload.
system	PeriodicDFTSystem		Current periodic GTH system.
cutoff_hartree	float		Current plane-wave cutoff in Hartree.
kpoint_mesh	KPointMesh		Current weighted reduced-coordinate k-point mesh.
execution_context	PeriodicSCFExecutionIdentity | Mapping[str, object]		Current complete execution context or validated identity.
n_bands	int | None	None	Current occupied band count. Defaults to half the electron count.
config	PeriodicSCFConfig | None	None	Current exact SCF controls. Defaults to PeriodicSCFConfig.
xc_functional	ExchangeCorrelationFunctional | None	None	Current exchange-correlation functional.

Returns

• PeriodicSCFCheckpoint — Validated checkpoint containing a private continuation state.

Raises

• ArtifactIntegrityError — If integrity, identity, settings, or arrays differ.

periodic_scf_calculation_contract

def periodic_scf_calculation_contract(system: PeriodicDFTSystem, *, cutoff_hartree: float, kpoint_mesh: KPointMesh, n_bands: int | None = None, config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None) -> dict[str, object]

Build the path-independent calculation contract used by checkpoints.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic GTH system.
cutoff_hartree	float		Plane-wave kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Weighted reduced-coordinate k-point mesh.
n_bands	int | None	None	Occupied band count. Defaults to half the electron count.
config	PeriodicSCFConfig | None	None	SCF controls. Defaults to PeriodicSCFConfig.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional. Only the deterministic production PBE path is checkpointable.

Returns

• dict[str, object] — Canonical JSON-compatible calculation settings and physics identity.

Raises

• ValueError — If a custom exchange-correlation implementation lacks the stable production-PBE identity.

periodic_scf_execution_settings

def periodic_scf_execution_settings(config: PeriodicSCFConfig | None = None) -> dict[str, object]

Return settings that bind a frozen execution context to periodic SCF.

Parameters

Name	Type	Default	Description
config	PeriodicSCFConfig | None	None	Exact SCF controls. Defaults to PeriodicSCFConfig.

Returns

• dict[str, object] — Mapping suitable for build_execution_context(settings_override=...).

periodic_scf_initialization_identity

def periodic_scf_initialization_identity(*, initial_density: object | None = None, initial_coefficients: Sequence[object] | None = None) -> dict[str, object]

Build a path-independent identity for fresh periodic-SCF initialization.

Parameters

Name	Type	Default	Description
initial_density	object | None	None	Optional caller-supplied density grid.
initial_coefficients	Sequence[object] | None	None	Optional caller-supplied coefficient stack per explicit k-point.

Returns

• dict[str, object] — Canonical initialization identity for an execution contract.

publish_periodic_scf_checkpoint

def publish_periodic_scf_checkpoint(destination: str | Path, result: PeriodicSCFResult, *, system: PeriodicDFTSystem, cutoff_hartree: float, kpoint_mesh: KPointMesh, execution_context: PeriodicSCFExecutionIdentity | Mapping[str, object], n_bands: int | None = None, config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, provenance: Mapping[str, object] | None = None, fault_hook: Callable[[str], None] | None = None) -> dict[str, object]

Atomically publish an eligible periodic-SCF next-iteration checkpoint.

Parameters

Name	Type	Default	Description
destination	str | Path		Previously absent final generation directory.
result	PeriodicSCFResult		Non-converged SCF result ending at an accepted iteration.
system	PeriodicDFTSystem		Periodic GTH system used by result.
cutoff_hartree	float		Plane-wave kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Weighted reduced-coordinate k-point mesh.
execution_context	PeriodicSCFExecutionIdentity | Mapping[str, object]		Existing complete execution context or validated identity.
n_bands	int | None	None	Occupied band count. Defaults to half the electron count.
config	PeriodicSCFConfig | None	None	Exact SCF controls. Defaults to PeriodicSCFConfig.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional. Defaults to production PBE.
provenance	Mapping[str, object] | None	None	Optional non-identity Git or caller provenance.
fault_hook	Callable[[str], None] | None	None	Optional deterministic publication-stage test hook.

Returns

• dict[str, object] — Completed shared atomic-generation manifest.

Raises

• ValueError — If result has no eligible next-iteration state.
• FileExistsError — If destination already exists.

run_periodic_scf_checkpointed

def run_periodic_scf_checkpointed(system: PeriodicDFTSystem, *, cutoff_hartree: float, kpoint_mesh: KPointMesh, execution_context: PeriodicSCFExecutionIdentity | Mapping[str, object], n_bands: int | None = None, config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, initial_density: mx.array | None = None, initial_coefficients: Sequence[mx.array] | None = None, observer: RuntimeObserver | None = None, checkpoint_to: str | Path | None = None, checkpoint_iteration: int | None = None, resume_from: str | Path | None = None, provenance: Mapping[str, object] | None = None, fault_hook: Callable[[str], None] | None = None) -> PeriodicSCFResult

Run periodic SCF with opt-in atomic checkpointing or explicit resume.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic GTH system.
cutoff_hartree	float		Plane-wave kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Weighted reduced-coordinate k-point mesh.
execution_context	PeriodicSCFExecutionIdentity | Mapping[str, object]		Complete current execution context or validated identity.
n_bands	int | None	None	Occupied band count. Defaults to half the electron count.
config	PeriodicSCFConfig | None	None	Exact SCF controls. Defaults to PeriodicSCFConfig.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional. Defaults to production PBE.
initial_density	mx.array | None	None	Optional fresh-run starting density.
initial_coefficients	Sequence[mx.array] | None	None	Optional fresh-run orbital stacks.
observer	RuntimeObserver | None	None	Optional runtime observer.
checkpoint_to	str | Path | None	None	Previously absent output generation, or None.
checkpoint_iteration	int | None	None	Accepted iteration after which to publish and stop.
resume_from	str | Path | None	None	Explicit checkpoint generation to validate and load.
provenance	Mapping[str, object] | None	None	Optional non-identity Git or caller provenance.
fault_hook	Callable[[str], None] | None	None	Optional deterministic publication-stage test hook.

Returns

• PeriodicSCFResult — Periodic SCF result. Resumed results retain numerical lineage and mark
• PeriodicSCFResult — timing as ineligible for fresh evidence.

Raises

• ValueError — If checkpoint controls are incomplete or conflict with resume.
• ArtifactIntegrityError — If explicit resume validation fails.