Configuration and diagnostics API

Simulation configuration

NmagConfig dataclass

NmagConfig(default_name: str = 'nmag_simulation', output_directory: Path = Path('.'), output_policy: OutputPolicy = 'error', accelerator: AcceleratorMode = 'auto', accelerator_overrides: Mapping[RustKernel, AcceleratorMode] = _empty_overrides(), integrator_backend: IntegratorBackend = 'scipy', demag_bem_storage: DemagBemStorage = 'auto', hierarchical_bem: HierarchicalBemConfig = HierarchicalBemConfig())

Define immutable output, acceleration, storage, and integrator policy.

Attributes:

Name	Type	Description
default_name	str	Simulation name used when Simulation(name=...) is omitted.
output_directory	Path	Directory for NDT, HDF5, and default checkpoint files. The directory must exist before output is written.
output_policy	OutputPolicy	"error"` protects old output,"replace"starts it again, and"append"`` validates and extends the NDT schema.
accelerator	AcceleratorMode	Global "auto", "off", or strict "rust" mode.
accelerator_overrides	Mapping[RustKernel, AcceleratorMode]	Per-:class:RustKernel mode overrides.
integrator_backend	IntegratorBackend	"scipy" or experimental "diffsol".
demag_bem_storage	DemagBemStorage	"auto", "dense", "hierarchical", or "matrix-free" boundary-operator storage.
hierarchical_bem	HierarchicalBemConfig	Accuracy and resource settings for hierarchy builds.

from_environment classmethod

from_environment() -> NmagConfig

Build default configuration from supported process-level selectors.

Returns:

Type	Description
NmagConfig	Configuration using NMAG_ACCELERATOR and
NmagConfig	NMAG_DEMAG_BEM_STORAGE_BACKEND when set.

accelerator_mode_for

accelerator_mode_for(kernel: RustKernel) -> AcceleratorMode

Return a kernel override, falling back to the global accelerator mode.

HierarchicalBemConfig dataclass

HierarchicalBemConfig(relative_tolerance: float = 1e-06, admissibility_eta: float = 2.0, leaf_size: int = 32, max_rank: int = 128, validation_vectors: int = 4, validation_rows: int = 64, memory_fraction: float = 0.2)

Control accuracy and resources for compressed Lindholm BEM.

Attributes:

Name	Type	Description
relative_tolerance	float	Requested relative compression/certification error.
admissibility_eta	float	Geometric separation threshold for low-rank blocks.
leaf_size	int	Maximum cluster leaf size.
max_rank	int	Maximum accepted low-rank block rank.
validation_vectors	int	Random vectors used to certify completed action.
validation_rows	int	Exact rows sampled during certification.
memory_fraction	float	Fraction of currently available memory allowed for the completed hierarchy.

RustKernel

Rust-accelerated calculation families accepted as override keys.

LINDHOLM_BEM class-attribute instance-attribute

LINDHOLM_BEM = 'lindholm_bem'

PROBE_GEOMETRY class-attribute instance-attribute

PROBE_GEOMETRY = 'probe_geometry'

FEM_GEOMETRY class-attribute instance-attribute

FEM_GEOMETRY = 'fem_geometry'

BOUNDARY_FACES class-attribute instance-attribute

BOUNDARY_FACES = 'boundary_faces'

FEM_ASSEMBLY class-attribute instance-attribute

FEM_ASSEMBLY = 'fem_assembly'

NODAL_RECOVERY class-attribute instance-attribute

NODAL_RECOVERY = 'nodal_recovery'

CELL_AVERAGE class-attribute instance-attribute

CELL_AVERAGE = 'cell_average'

LLG class-attribute instance-attribute

LLG = 'llg'

MAXANGLE class-attribute instance-attribute

MAXANGLE = 'maxangle'

Runtime diagnostics

IntegratorConfig dataclass

IntegratorConfig(relative_tolerance: float = 1e-06, absolute_tolerance: float = 1e-06, maximum_step_seconds: float = 1e-12, exact_tstop: bool = True)

Snapshot of effective public DOP853 controls.

Attributes:

Name	Type	Description
relative_tolerance	float	Relative local-error tolerance.
absolute_tolerance	float	Absolute local-error tolerance.
maximum_step_seconds	float	Configured upper step bound in seconds.
exact_tstop	bool	Whether fixed-time requests normally stop exactly.

IntegratorStats dataclass

IntegratorStats(accepted_steps: int = 0, rhs_evaluations: int = 0, rejected_steps: int | None = None, failed: bool = False, status: str = 'not_started', last_step_seconds: float = 0.0, simulated_seconds: float = 0.0, wall_seconds: float = 0.0, jacobian_vector_evaluations: int | None = None, nonlinear_iterations: int | None = None, nonlinear_failures: int | None = None, linear_solver_setups: int | None = None)

Measurements from the most recent integration operation.

Attributes:

Name	Type	Description
accepted_steps	int	Accepted adaptive steps.
rhs_evaluations	int	Landau-Lifshitz-Gilbert right-hand-side evaluations.
rejected_steps	int | None	Rejected steps when the backend reports them.
failed	bool	Whether the operation raised a numerical failure.
status	str	Backend status at completion.
last_step_seconds	float	Size of the final accepted step.
simulated_seconds	float	Physical time advanced by the operation.
wall_seconds	float	Elapsed wall-clock time.
jacobian_vector_evaluations	int | None	Optional implicit-backend measurement.
nonlinear_iterations	int | None	Optional implicit-backend Newton iterations.
nonlinear_failures	int | None	Optional implicit-backend failure count.
linear_solver_setups	int | None	Optional implicit-backend setup count.

BemOperatorStats dataclass

BemOperatorStats(requested_backend: str, effective_backend: str, fallback_reason: str | None, boundary_nodes: int, boundary_faces: int, setup_seconds: float, storage_bytes: int, dense_equivalent_bytes: int, dense_blocks: int = 0, low_rank_blocks: int = 0, maximum_rank: int = 0, mean_rank: float = 0.0, sampled_relative_error: float = 0.0)

Describe construction and storage of the active BEM operator.

Attributes:

Name	Type	Description
requested_backend	str	Storage mode requested by configuration.
effective_backend	str	Storage implementation actually constructed.
fallback_reason	str | None	Explanation when construction changed modes.
boundary_nodes	int	Number of boundary degrees of freedom.
boundary_faces	int	Number of oriented surface triangles.
setup_seconds	float	Operator construction time.
storage_bytes	int	Bytes retained by the effective operator.
dense_equivalent_bytes	int	Bytes required by an equivalent dense matrix.
dense_blocks	int	Exact blocks in a hierarchy.
low_rank_blocks	int	Compressed blocks in a hierarchy.
maximum_rank	int	Largest compressed-block rank.
mean_rank	float	Mean compressed-block rank.
sampled_relative_error	float	Certification error measured during setup.

ParallelRuntimeInfo dataclass

ParallelRuntimeInfo(logical_cpus: int, rust_available: bool, rust_worker_threads: int | None, rust_parallel_min_items: int | None)

Shared-memory execution settings visible to the current process.

Attributes:

Name	Type	Description
logical_cpus	int	Logical processors reported by the operating system.
rust_available	bool	Whether a compatible native extension is installed.
rust_worker_threads	int | None	Rayon worker count when Rust is available.
rust_parallel_min_items	int | None	Operation-size crossover for parallel kernels.

parallel_runtime_info

parallel_runtime_info() -> ParallelRuntimeInfo

Return effective Rust worker and crossover settings without changing them.