geopulse.types

Type aliases and custom types used across GeoPulse.

Centralising types here avoids circular imports and provides a single reference for all type contracts.

Module Attributes

FloatArray

1-D or N-D array of float64.

ComplexArray

1-D or N-D array of complex128.

LatLon

(latitude_deg, longitude_deg) pair, both in degrees.
geopulse.types.FloatArray

1-D or N-D array of float64. The workhorse type.

alias of NDArray[float64]

geopulse.types.ComplexArray

1-D or N-D array of complex128. For frequency-domain quantities.

alias of NDArray[complex128]

geopulse.types.LatLon

(latitude_deg, longitude_deg) pair, both in degrees.

alias of tuple[float, float]

class geopulse.types.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.