Source code for morphogen.seeding

"""Reproducible random number generation.

Every random draw in morphoGen goes through a :class:`numpy.random.Generator` built
from a seed. The realizations of a study get seeds derived from the study seed and
their indices (``SeedSequence(seed, spawn_key=(size_index, realization_index))``), so
a result does not depend on how the study was split across processes or cluster jobs.
"""

from __future__ import annotations

import numpy as np

SeedLike = int | np.random.SeedSequence | np.random.Generator | None


[docs] def derive_seed(base: int | None, *key: int) -> np.random.SeedSequence: """Seed of the item ``key`` (e.g. ``(size_index, realization_index)``) of a study.""" return np.random.SeedSequence(entropy=base, spawn_key=tuple(int(k) for k in key))
[docs] def make_rng(seed: SeedLike = None) -> tuple[np.random.Generator, dict | None]: """Return a generator and a JSON-able description that reproduces it. ``seed`` may be an integer, a :class:`~numpy.random.SeedSequence`, an existing generator (used as is, not reproducible from the description) or ``None`` (fresh entropy, recorded so that the realization can be regenerated). """ if isinstance(seed, np.random.Generator): return seed, None if isinstance(seed, np.random.SeedSequence): ss = seed elif seed is None: ss = np.random.SeedSequence() else: if isinstance(seed, bool) or int(seed) != seed or int(seed) < 0: raise ValueError(f"seed: expected a non-negative integer, got {seed!r}") ss = np.random.SeedSequence(int(seed)) return np.random.default_rng(ss), describe_seed(ss)
[docs] def describe_seed(ss: np.random.SeedSequence) -> dict: """The entropy and spawn key of a seed sequence, which recreate it (recorded with the results).""" return {"entropy": ss.entropy, "spawn_key": list(ss.spawn_key)}
[docs] def seed_from_description(desc: dict | int | None) -> np.random.SeedSequence | int | None: """Inverse of :func:`describe_seed` (also accepts a plain integer).""" if desc is None or isinstance(desc, int): return desc return np.random.SeedSequence(entropy=desc["entropy"], spawn_key=tuple(desc["spawn_key"]))