rizer.io.experimental_data.load_experiment_data#

Loader for the fixed-schema experiment .npz files under data/experiments/.

Three fixed npz-key -> canonical-name tables, one per schema written by rizer.io.experimental_data.preprocess_data. Which schema applies to a given file is inferred from its filename prefix – the same electron_density/electrical_signals/section_diameters prefixes rizer.spice.backend.services.results_discovery.discover_experiments filters on (imported from here via RECOGNIZED_EXPERIMENT_PREFIXES, so the two modules cannot drift apart on which prefixes are recognized).

Unit contract: every schema’s on-disk npz stores SI units (time in s, d_mean/d_std in m, everything else already SI) – enforced by the writer, not re-validated here. load_experiment_data expands each quantity it reads into every unit variant listed in _UNIT_VARIANTS below, so a caller asks for the exact unit it needs directly (e.g. data[“voltage_kV”], data[“time_ns”], data[“ne_cm-3”]) rather than reading one fixed unit and rescaling it itself. A quantity with no entry in _UNIT_VARIANTS (only “r2”) is dimensionless and keeps its bare key, no unit suffix.

Attributes#

RECOGNIZED_EXPERIMENT_PREFIXES

ELECTRON_DENSITY_NPZ_KEYS

SECTION_DIAMETERS_NPZ_KEYS

ELECTRICAL_SIGNALS_NPZ_KEYS

Functions#

resolve_experiment_columns(→ list[str])

Return path's arrays' canonical quantity names, without loading values.

available_quantities(→ set[str])

Return the family-level quantity names present in a load_experiment_data result.

load_experiment_data(→ dict[str, numpy.ndarray])

Load an experiment .npz, keyed by unit-suffixed canonical quantity name.

load_experiment_trace_window(→ tuple[numpy.ndarray, ...)

Load one quantity from an experiment .npz, sliced to [t_start, t_end] and re-zeroed.

Module Contents#

rizer.io.experimental_data.load_experiment_data.RECOGNIZED_EXPERIMENT_PREFIXES: tuple[str, ...]#
rizer.io.experimental_data.load_experiment_data.ELECTRON_DENSITY_NPZ_KEYS: tuple[str, ...] = ('time', 'ne_mean', 'ne_std', 'r2')#
rizer.io.experimental_data.load_experiment_data.SECTION_DIAMETERS_NPZ_KEYS: tuple[str, ...] = ('time', 'd_mean', 'd_std', 'r2')#
rizer.io.experimental_data.load_experiment_data.ELECTRICAL_SIGNALS_NPZ_KEYS: tuple[str, ...] = ('time', 'V_mean', 'V_std', 'I_mean', 'I_std', 'E_mean', 'E_std')#
rizer.io.experimental_data.load_experiment_data.resolve_experiment_columns(path: str | pathlib.Path) → list[str]#

Return path’s arrays’ canonical quantity names, without loading values.

Parameters:

path (str or pathlib.Path) – Path to an experiment .npz under data/experiments/.

Returns:

Canonical quantity name per array in the file.

Return type:

list of str

Raises:

  • ValueError – If path’s filename does not start with a recognized prefix.

  • KeyError – If the file contains an array name not in that prefix’s schema.

rizer.io.experimental_data.load_experiment_data.available_quantities(data: dict[str, numpy.ndarray]) → set[str]#

Return the family-level quantity names present in a load_experiment_data result.

load_experiment_data expands each quantity it reads into every unit variant in _UNIT_VARIANTS; this recovers which quantity families are present, via each family’s guaranteed-present native-unit key, for compatibility checks like rizer.pipeline.plotting.plt_simulation.SimulationPlotter._matching_experiment_data and rizer.spice.backend.services.results_plotting._experiment_traces.

Parameters:

data (dict of str to numpy.ndarray) – A load_experiment_data result.

Returns:

Family-level quantity names present (e.g. “voltage”, “ne”, “r2”).

Return type:

set of str

rizer.io.experimental_data.load_experiment_data.load_experiment_data(path: str | pathlib.Path, quantity: str | None = None, unit: str | None = None) → dict[str, numpy.ndarray]#

Load an experiment .npz, keyed by unit-suffixed canonical quantity name.

Every quantity family present in the file is always expanded into its native (on-disk SI) unit only – a plain array reference, no multiplication – since available_quantities needs a guaranteed-present key per family to probe presence, and time’s “ns” variant is always expanded too, since every caller reads it unconditionally for the x-axis. Passing quantity/unit additionally expands that one family into the requested unit (and its _std_{unit} sibling, if present).

Every real caller (_experiment_traces, SimulationPlotter._matching_experiment_data and its own callers) already knows the single unit it wants before loading – eagerly expanding every family into every one of _UNIT_VARIANTS’s ~4 units regardless of what’s ever read back was pure wasted work on every load.

Parameters:

  • path (str or pathlib.Path) – Path to an experiment .npz under data/experiments/.

  • quantity (str or None, optional) – Canonical family name (e.g. “voltage”) to additionally expand into unit. Ignored (no extra expansion) if unit is None, the family isn’t present in this file, or unit isn’t one of its known unit variants – a caller that only needs to probe presence via available_quantities (not read any value) can pass quantity alone, or neither.

  • unit (str or None, optional) – Unit variant to expand quantity into (e.g. “kV”).

Returns:

Each present quantity family’s native-unit key, time’s “ns” key, and quantity’s unit key (if requested), all keyed “{quantity}_{unit}” (e.g. “voltage_V”, “time_ns”) per _UNIT_VARIANTS. “r2” has no unit and keeps its bare key. Use available_quantities to check which quantity families are present without needing any particular unit variant.

Return type:

dict of str to numpy.ndarray

Raises:

  • ValueError – If path’s filename does not start with a recognized prefix, or the file is missing an array its schema expects.

  • KeyError – If the file contains an array name not in that prefix’s schema.

rizer.io.experimental_data.load_experiment_data.load_experiment_trace_window(path: str | pathlib.Path, quantity: str, unit: str, t_start: float | None = None, t_end: float | None = None) → tuple[numpy.ndarray, numpy.ndarray]#

Load one quantity from an experiment .npz, sliced to [t_start, t_end] and re-zeroed.

Parameters:

  • path (str or pathlib.Path) – Path to an experiment .npz under data/experiments/.

  • quantity (str) – Canonical family name (e.g. “voltage”), per load_experiment_data.

  • unit (str) – Unit variant to load quantity in (e.g. “V”).

  • t_start (float or None, optional) – Window bounds [s] in the file’s own (raw/absolute) time axis. None (default) uses the file’s own start/end. Returned times are shifted so the window starts at t=0 – the convention every generator/ circuit’s own t clock uses.

  • t_end (float or None, optional) – Window bounds [s] in the file’s own (raw/absolute) time axis. None (default) uses the file’s own start/end. Returned times are shifted so the window starts at t=0 – the convention every generator/ circuit’s own t clock uses.

Returns:

(times, values), times strictly increasing from 0.

Return type:

tuple of numpy.ndarray

Raises:

ValueError – If t_end <= t_start, or the window selects fewer than 2 samples.