Skip to content

Sampling#

cheersafe.tools.Sampling provides deterministic random-number helpers and Latin hypercube sampling methods.

Purpose And When To Use#

Use Sampling when you need CHEERSafe's centralized seed policy or want to generate component samples with normal or SciPy-supported marginal distributions. Damage probability workflows use these helpers to make stochastic simulation reproducible.

Inputs#

Method Inputs Units, indexing, or shapes
resolve_seed(seed=None) Optional seed. Returns Config.RANDOM_SEED when seed is None; otherwise returns int(seed).
derive_seed(label, *parts, seed=None) Text label, seed parts, optional base seed. Produces a deterministic 32-bit seed from JSON-stable normalized inputs.
create_rng(seed=None) Optional seed, NumPy Generator, or RNG-like object. Returns a fresh NumPy generator for numeric seeds; returns supplied generator/RNG-like objects.
random(rng=None) Optional seed or RNG. Returns one uniform random value in [0, 1).
permutation(n, rng=None) Integer n, optional seed or RNG. Returns a permutation of np.arange(n).
weibull_min(shape, scale, rng=None) Weibull shape and scale. Returns one zero-location Weibull-min draw multiplied by scale.
generate_lhs_samples_norm(n, mean, covariance, seed=None) Sample count, mean vector, covariance matrix, optional seed. mean length is the dimension d; covariance shape is [d, d]; return shape is [n, d].
generate_lhs_samples_general(n, distributions_details, mean, covariance, seed=None) Sample count, SciPy distribution specs, means, covariance, optional seed. distributions_details length must be 1 or d. Each dict needs a SciPy distribution type, such as "norm" or "lognorm". Return shape is [n, d].

generate_lhs_samples_* pass Config.NUM_OF_WORKERS_SAMPLING to SciPy's LatinHypercube random() call.

Outputs And Returns#

All Sampling methods return values directly and do not assign state. generate_lhs_samples_norm() and generate_lhs_samples_general() return NumPy arrays with rows as samples and columns as variables.

AUTO_LOAD_DATASETS Behavior#

Sampling does not load files and does not inspect Config.AUTO_LOAD_DATASETS.

AUTO_EXECUTE_METHODS Behavior#

Sampling has no constructor and no automatic execution behavior. The methods run only when called.

Minimal Automatic Example#

There is no constructor-side automatic behavior for Sampling; the direct call is the normal use:

PYTHONPATH=src python3 - <<'PY'
import numpy as np
from cheersafe.config import Config
from cheersafe.tools import Sampling

Config.reset_flags()
samples = Sampling.generate_lhs_samples_norm(
    4,
    np.array([10.0, 20.0]),
    np.array([[1.0, 0.2], [0.2, 4.0]]),
    seed=7,
)
print(samples.shape)
print(np.round(samples.mean(axis=0), 2))

Config.reset_flags()
PY

Minimal Manual-Control Example#

PYTHONPATH=src python3 - <<'PY'
from cheersafe.config import Config
from cheersafe.tools import Sampling

Config.reset_flags()
Config.RANDOM_SEED = 123

seed = Sampling.derive_seed("component", 1, {"config": 2})
rng = Sampling.create_rng(seed)

print(seed)
print(round(Sampling.random(rng), 6))
print(Sampling.permutation(5, rng).tolist())

Config.reset_flags()
PY