qiu_classical_simulation.wave_optics.storage

Storage of lens experiments, one folder per run.

A run folder holds initial_parameters.json, the parameters together with the scalar results, and results.npz, the snapshots. Runs are stored as <results_dir>/<uuid>; older ones as <results_dir>/<timestamp>, which reads the same way.

Functions:

• save_experiment –

  Store a run in the folder <results_dir>/<uuid>, and return the folder.

• load_stored_values –

  Return the stored parameters and scalar results of a run.

• load_parameters –

  Load the parameters of a run, see ExperimentParameters.from_dict.

• load_result –

  Load the result of a run.

• load_experiment –

  Load the parameters and the result of a run.

• run_folders –

  Return the run folders in a results directory, sorted by name.

Attributes:

• PARAMETERS_FILENAME –
• RESULTS_FILENAME –

PARAMETERS_FILENAME module-attribute

PARAMETERS_FILENAME = 'initial_parameters.json'

RESULTS_FILENAME module-attribute

RESULTS_FILENAME = 'results.npz'

save_experiment

save_experiment(results_dir: str | Path, parameters: ExperimentParameters, result: ExperimentResult) -> Path

Store a run in the folder <results_dir>/<uuid>, and return the folder.

Returns:

• Path –

  The folder of the run, <results_dir>/<uuid>.

Raises:

• FileExistsError –

  If a run of the same uuid is stored already, e.g. of parameters copied with dataclasses.replace, which keeps the uuid; give the copy a new one, e.g. replace(parameters, ..., uuid=uuid.uuid4().hex).

Source code in packages/qiu-classical-simulation/src/qiu_classical_simulation/wave_optics/storage.py

def save_experiment(
    results_dir: str | Path, parameters: ExperimentParameters, result: ExperimentResult
) -> Path:
    """Store a run in the folder `<results_dir>/<uuid>`, and return the folder.

    Returns:
        The folder of the run, `<results_dir>/<uuid>`.

    Raises:
        FileExistsError: If a run of the same uuid is stored already, e.g. of parameters
            copied with `dataclasses.replace`, which keeps the uuid; give the copy a new
            one, e.g. `replace(parameters, ..., uuid=uuid.uuid4().hex)`.
    """  # noqa: DOC502 (raised by Path.mkdir)
    folder = Path(results_dir) / parameters.uuid
    folder.parent.mkdir(parents=True, exist_ok=True)
    folder.mkdir()  # never overwrite a stored run
    with open(folder / PARAMETERS_FILENAME, "w") as file:
        json.dump({**parameters.to_dict(), **result.summary()}, file)
    np.savez(folder / RESULTS_FILENAME, allow_pickle=False, **result.snapshots)
    return folder

load_stored_values

load_stored_values(folder: str | Path) -> dict[str, Any]

Return the stored parameters and scalar results of a run.

Source code in packages/qiu-classical-simulation/src/qiu_classical_simulation/wave_optics/storage.py

def load_stored_values(folder: str | Path) -> dict[str, Any]:
    """Return the stored parameters and scalar results of a run."""
    with open(Path(folder) / PARAMETERS_FILENAME) as file:
        return json.load(file)

load_parameters

load_parameters(folder: str | Path, defaults: dict[str, Any] | None = None) -> ExperimentParameters

Load the parameters of a run, see ExperimentParameters.from_dict.

Source code in packages/qiu-classical-simulation/src/qiu_classical_simulation/wave_optics/storage.py

def load_parameters(
    folder: str | Path, defaults: dict[str, Any] | None = None
) -> ExperimentParameters:
    """Load the parameters of a run, see `ExperimentParameters.from_dict`."""
    return ExperimentParameters.from_dict(load_stored_values(folder), defaults)

load_result

load_result(folder: str | Path) -> ExperimentResult

Load the result of a run.

Source code in packages/qiu-classical-simulation/src/qiu_classical_simulation/wave_optics/storage.py

def load_result(folder: str | Path) -> ExperimentResult:
    """Load the result of a run."""
    values = load_stored_values(folder)
    with np.load(Path(folder) / RESULTS_FILENAME, allow_pickle=False) as data:
        snapshots = {name: data[name] for name in data.files}
    return ExperimentResult(
        snapshots=snapshots,
        total_lenses_simulated=values["total_lenses_simulated"],
        total_probability_of_success=values.get("total_probability_of_success"),
        success_probabilities=values.get("success_probabilities"),
    )

load_experiment

load_experiment(folder: str | Path, defaults: dict[str, Any] | None = None) -> tuple[ExperimentParameters, ExperimentResult]

Load the parameters and the result of a run.

Source code in packages/qiu-classical-simulation/src/qiu_classical_simulation/wave_optics/storage.py

def load_experiment(
    folder: str | Path, defaults: dict[str, Any] | None = None
) -> tuple[ExperimentParameters, ExperimentResult]:
    """Load the parameters and the result of a run."""
    return load_parameters(folder, defaults), load_result(folder)

run_folders

run_folders(results_dir: str | Path) -> list[Path]

Return the run folders in a results directory, sorted by name.

Source code in packages/qiu-classical-simulation/src/qiu_classical_simulation/wave_optics/storage.py

def run_folders(results_dir: str | Path) -> list[Path]:
    """Return the run folders in a results directory, sorted by name."""
    return sorted(
        path
        for path in Path(results_dir).iterdir()
        if (path / PARAMETERS_FILENAME).is_file()
    )