rizer.spice.backend.services.results_discovery

Discovery of simulation runs and experiment files for the Results Explorer API.

Identifiers returned to (and accepted back from) the frontend are paths relative to data/figures/ (for runs) or data/experiments/ (for experiments), validated on every use to stay confined under that root – never a raw, unchecked filesystem path from the client.

Attributes

RUN_INPUT_YAML_NAME

Functions

figures_root(→ pathlib.Path)
experiments_root(→ pathlib.Path)
resolve_run_path(→ pathlib.Path)	Resolve a run id to its validated, existing run folder.
resolve_experiment_path(→ pathlib.Path)	Resolve an experiment id to its validated, existing file.
discover_runs(→ list[dict])	Recursively find every simulation run under root (default data/figures/).
discover_experiments(→ tuple[list[dict], list[str]])	Recursively find every recognized, parseable experiment .npz under root.

Module Contents

rizer.spice.backend.services.results_discovery.RUN_INPUT_YAML_NAME = 'simulation_input_parameters.yaml'

rizer.spice.backend.services.results_discovery.figures_root() → pathlib.Path

rizer.spice.backend.services.results_discovery.experiments_root() → pathlib.Path

rizer.spice.backend.services.results_discovery.resolve_run_path(run_id: str) → pathlib.Path

Resolve a run id to its validated, existing run folder.

Raises:

ValueError – If run_id escapes data/figures/, or the resolved folder has no inputs/simulation_input_parameters.yaml.

rizer.spice.backend.services.results_discovery.resolve_experiment_path(experiment_id: str) → pathlib.Path

Resolve an experiment id to its validated, existing file.

Raises:

ValueError – If experiment_id escapes data/experiments/, or does not point at an existing file.

rizer.spice.backend.services.results_discovery.discover_runs(*, include_archived: bool = False, root: pathlib.Path | None = None) → list[dict]

Recursively find every simulation run under root (default data/figures/).

Parameters:

• include_archived (bool, optional) – If False (default), skip any run whose path has an archived path segment.

• root (pathlib.Path or None, optional) – Root to scan; defaults to figures_root(). Exposed for testing.

Returns:

One entry per run, matching rizer.spice.backend.models.results_schemas.RunInfo. Only runs with a simulation_results.npz are included – a run with only the pre-refactor simulation_results.yaml/.csv, or one whose simulation hasn’t finished/saved yet, has nothing rizer.misc.simulation.post_process_io.load_simulation_results can read, so it would otherwise show up in the picker and fail as soon as it’s selected.

Return type:

list of dict

rizer.spice.backend.services.results_discovery.discover_experiments(*, root: pathlib.Path | None = None) → tuple[list[dict], list[str]]

Recursively find every recognized, parseable experiment .npz under root.

Parameters:

root (pathlib.Path or None, optional) – Root to scan; defaults to experiments_root(). Exposed for testing.

Returns:

• experiments (list of dict) – One entry per successfully-parsed .npz, matching rizer.spice.backend.models.results_schemas.ExperimentFileInfo.

• skipped (list of str) – Relative paths (posix-style) of files not attempted at all (name doesn’t start with a RECOGNIZED_EXPERIMENT_PREFIXES prefix), a recognized-prefix .csv (the retired, self-describing-header format – not parsed, only .npz is), or a recognized-prefix .npz that still failed to parse (an unrecognized array name, or one missing from its schema) – reported rather than silently dropped, so a file that has not been migrated yet (e.g. T176’s) or a genuine regression in a migrated one is visibly absent rather than invisibly absent.