llg3d.io

Input/Output functions.

Extensibility Guide

The I/O system is designed to be fully extensible. You can add arbitrary fields to metrics and records without modifying this module.

Adding custom metrics

>>> solver.metrics['custom_value'] = 42.0
>>> solver.metrics['convergence_rate'] = 0.95

Adding custom records

>>> # Simple array
>>> solver.records['energy_evolution'] = np.array([...])

>>> # Nested structure (automatically flattened in .npz)
>>> solver.records['field_snapshots'] = {
...     'times': np.array([0, 1, 2]),
...     'data': np.array([...])
... }

>>> # Deeply nested (unlimited depth)
>>> solver.records['analysis'] = {
...     'spectra': {
...         'fourier': np.array([...]),
...         'wavelets': np.array([...])
...     }
... }

TypedDicts (Metrics, Records, etc.) are documentation only. Runtime accepts any dict[str, Any] structure.

Functions

format_profiling_table(profiling_dict[, ...])	Format profiling statistics as a table.
get_tqdm_file()	Get a TQDM-compatible file for progress bar output in MPI.
load_results(result_file)	Loads simulation results from a .npz file with hierarchical structure.
save_results(output_file, params, metrics[, ...])	Saves simulation results to a .npz file with hierarchical structure.

Classes

Metrics	Structure for simulation metrics (extensible).
MetricsRequired	Required fields for simulation metrics.
Observables	Physical observables from the simulation (extensible).
Records	Records after saving (finalized with numpy arrays).
RecordsBuffer	Records during simulation (accumulation phase with lists).
RunResults(params, results, file)	Structure for loaded simulation results.
SimulationResults	Structure for simulation results.
XProfiles	Structure for cross-sectional profiles (arrays in final records).
XProfilesBuffer	Structure for cross-sectional profiles during accumulation (lists).

get_tqdm_file()

Get a TQDM-compatible file for progress bar output in MPI.

Return type:

TextIO | None

class MetricsRequired

Bases: TypedDict

Required fields for simulation metrics.

total_time: float

Total wall-clock time of the simulation

time_per_ite: float

Average time per iteration

efficiency: float

Time per iteration per cell

CFL: float

CFL condition value

class Metrics

Bases: dict

Structure for simulation metrics (extensible).

Required fields: total_time, time_per_ite, efficiency, CFL All other fields are optional and can be added dynamically.

profiling_stats: NotRequired[dict[str, dict[str, float]]]

Profiling statistics

class Observables

Bases: TypedDict

Physical observables from the simulation (extensible).

All fields are optional and can be added dynamically.

m1_mean: float

Time-averaged magnetization in x direction

class XProfiles

Bases: TypedDict

Structure for cross-sectional profiles (arrays in final records).

t: ndarray

Time points for profiles

m1: ndarray

m1 component profiles

m2: ndarray

m2 component profiles

m3: ndarray

m3 component profiles

class XProfilesBuffer

Bases: TypedDict

Structure for cross-sectional profiles during accumulation (lists).

t: list[float]

Time points for profiles

m1: list[ndarray]

m1 component profiles

m2: list[ndarray]

m2 component profiles

m3: list[ndarray]

m3 component profiles

class RecordsBuffer

Bases: TypedDict

Records during simulation (accumulation phase with lists).

BaseSolver.records uses this structure during simulation, accumulating data as lists. Before saving, BaseSolver.save() converts lists to arrays.

xyz_average: list[tuple[float, float]]

Accumulated (t, value) pairs

x_profiles: XProfilesBuffer

Profiles during accumulation

class Records

Bases: TypedDict

Records after saving (finalized with numpy arrays).

Returned by load_results() with all data as read-only numpy arrays.

xyz_average: ndarray

(2, N))

Type:

Space-averaged magnetization over time (shape

x_profiles: XProfiles

Cross-sectional profiles in yz plane

class SimulationResults

Bases: TypedDict

Structure for simulation results.

metrics: Metrics

Simulation metrics (performance, numerical quality)

observables: NotRequired[Observables]

Physical observables (results)

records: NotRequired[Records]

Optional time-series records

class RunResults(params, results, file)

Bases: object

Structure for loaded simulation results.

Parameters:

• params (RunParameters)

• results (SimulationResults)

• file (str | Path)

get_record(record_name)

Return a record by name from results or raise a descriptive error.

Parameters:

record_name (str)

Return type:

ndarray | dict[str, ndarray]

save_results(output_file, params, metrics, observables=None, records_buffer=None)

Saves simulation results to a .npz file with hierarchical structure.

Parameters:

• output_file (str | Path) – Path to the output .npz file.

• params (RunParameters) – Dataclass of simulation parameters.

• metrics (Metrics) – Dictionary of simulation metrics. Must contain required fields: total_time, time_per_ite, CFL. Additional fields are allowed.

• observables (Observables | None) – Dictionary of physical observables (results).

• records_buffer (RecordsBuffer | None) – RecordsBuffer or custom dict of records (accumulation phase with lists/dicts).

Return type:

None

Note

Both metrics and records accept any key-value pairs, allowing easy extension without modifying this function. See Metrics and Records TypedDict for recommended structure.

Example

>>> records_buffer = {
...     'xyz_average': arr1,
...     'x_profiles': {'t': t, 'm1': m1, ...},
...     'custom_data': arr2  # Any new field works automatically
... }
>>> save_results('run.npz', params, metrics, records_buffer=records_buffer)

load_results(result_file)

Loads simulation results from a .npz file with hierarchical structure.

Numpy arrays are set to read-only to prevent accidental modification.

Example

>>> run_results = load_results("run.npz")
>>> params = run_results["params"]
>>> metrics = run_results["results"]["metrics"]
>>> xyz_average = run_results["results"]["records"]["xyz_average"]
>>> m1_prof = run_results["results"]["records"]["x_profiles"]["m1"]

Parameters:

result_file (str | Path) – path to the .npz file.

Returns:

Dictionary containing the loaded data with hierarchical structure.

Return type:

RunResults

format_profiling_table(profiling_dict, total_time=None)

Format profiling statistics as a table.

Parameters:

• profiling_dict (dict[str, dict[str, float | int]]) – Dictionary with profiling stats, where each entry has ‘time’ (float) and ‘calls’ (int) keys

• total_time (float | None) – Total simulation time for percentage calculation. If None, the percentage column is omitted.

Returns:

A formatted table string

Return type:

str