geopulse.uq

Uncertainty-quantification utilities.

Provides the Uncertain wrapper type and Monte-Carlo propagation helpers used across the pipeline.

class geopulse.uq.Uncertain(nominal, samples=None, distribution='deterministic', params=<factory>)[source]

Bases: Generic[T]

A value that may carry uncertainty information.

Parameters:

nominal (TypeVar(T)) – The central / best-estimate value.
samples (Optional[list[TypeVar(T)]]) – Monte-Carlo samples, if uncertainty has been propagated. Length equals the number of MC draws.
distribution (str) – Distribution family. One of "deterministic", "gaussian", "uniform", "ensemble". Default: "deterministic".
params (dict) – Distribution parameters. For gaussian: {"std": ...}. For uniform: {"low": ..., "high": ...}. For ensemble: empty (samples ARE the distribution).

Notes

Uncertain is not frozen: generate_samples() is a query method and does not mutate the instance, but downstream propagation code may attach freshly-drawn samples after construction.

nominal: T

samples: list[T] | None = None

distribution: str = 'deterministic'

params: dict

property is_deterministic: bool: Whether this value carries no uncertainty.

property n_samples: int: Number of Monte-Carlo samples, or 0 if deterministic.

property mean: Any: Mean of samples, or nominal if deterministic.

property std: Any: Standard deviation of samples, or zero if deterministic.

generate_samples(n, rng=None)[source]

Draw n Monte-Carlo samples from the declared distribution.

Parameters:

n (int) – Number of samples to generate.
rng (Optional[Generator]) – Reproducible RNG. If None, a fresh default RNG is created.

Return type:

list

Returns:

list – n samples, each with the same shape/type as nominal.

Raises:

ValueError – If distribution is not one of the supported families.

geopulse.uq.propagate_uncertainty(func, *args, n_samples=100, seed=42, **kwargs)[source]

Propagate uncertainty through a function via Monte Carlo.

Any argument that is an Uncertain with a non-deterministic distribution is sampled; deterministic arguments pass through unchanged.

Parameters:

func (Callable[..., Any]) – The function to propagate through.
*args (Any) – Positional arguments — may include Uncertain values.
n_samples (int) – Number of Monte-Carlo samples. Default: 100.
seed (int) – Random seed for reproducibility. Default: 42.
**kwargs (Any) – Keyword arguments — may include Uncertain values.

Return type:

Uncertain

Returns:

Uncertain – Result with distribution="ensemble" and samples populated.

Examples

>>> u = Uncertain(nominal=1.0, distribution="gaussian", params={"std": 0.1})
>>> out = propagate_uncertainty(lambda x: x * 2, u, n_samples=100)
>>> out.n_samples
100

Modules

`distributions`	Distribution representations for uncertainty quantification — STUB (WP2).
`montecarlo`	Monte-Carlo propagation engine — STUB (WP2).
`sensitivity`	Sensitivity-analysis utilities (Sobol, Morris) — STUB (WP3).
`uncertain`	Core uncertainty type: `Uncertain[T]`.