ssapy_toolkit.Compute.sampling

Sampling utilities.

This module provides a collection of small helper functions for random sampling, including:

• Sampling from sequences (with/without replacement)

• Uniform scalar and array sampling

• Gaussian (normal) scalar and array sampling

• Log-normal, exponential, Poisson, binomial, Dirichlet, and multivariate normal sampling

• Cached sigma perturbation generator for 6D state vectors (get_sigmas)

All random draws are implemented via NumPy’s RNG.

Functions

binomial_array([n, p, size, dtype])	Binomial(n, p) array sample.
dirichlet_array(alpha[, size])	Dirichlet(alpha) sampling.
exponential_array([scale, size, dtype])	Exponential(scale) array sample.
get_sigmas([n, path])	Return an (n, 6) array of random sigma perturbations, cached on disk.
lognormal_array([mean, sigma, size, dtype])	Log-normal array sample: exp( N(mean, sigma^2) ).
multivariate_normal_array(mean, cov[, size, ...])	Multivariate normal N(mean, cov) sampling.
normal_array([mean, std, size, dtype])	Gaussian N(mean, std^2) array sample.
normal_scalar([mean, std])	Gaussian N(mean, std^2) scalar sample.
perturb_state_3d(r, v[, pos_scale, ...])	Perturb a 3D position and velocity with isotropic spherical uncertainty.
poisson_array([lam, size, dtype])	Poisson(lam) array sample.
rand_num([low, high])	Draw a single uniform random float in [low, high).
random_arr([low, high, size, dtype])	Generate a random array with specified bounds and size.
sample_from_sequence(seq, n[, replacement])	Uniformly sample n elements from a sequence.
shuffle(x)	Shuffle a list in-place using Python's built-in RNG.
uniform_array([low, high, size, dtype])	Uniform( low, high ) array sample.
uniform_scalar([low, high])	Uniform( low, high ) scalar sample.

ssapy_toolkit.Compute.sampling.binomial_array(n: int = 1, p: float = 0.5, size: tuple = (1, 10), dtype: str = 'int64') → ndarray

Binomial(n, p) array sample.

Parameters:

• n (int) – Number of trials.

• p (float) – Success probability.

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.dirichlet_array(alpha: Sequence[float], size: int = 1) → ndarray

Dirichlet(alpha) sampling.

Parameters:

• alpha (sequence of float) – Concentration parameters (> 0).

• size (int) – Number of samples.

Returns:

Shape (size, len(alpha)).

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.exponential_array(scale: float = 1.0, size: tuple = (1, 10), dtype: str = 'float64') → ndarray

Exponential(scale) array sample.

Parameters:

scale (float) – 1 / lambda, the mean of the distribution.

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.get_sigmas(n: int = 25, path: str | None = None) → ndarray

Return an (n, 6) array of random sigma perturbations, cached on disk.

Each row is:

[dx, dy, dz, dvx, dvy, dvz]

Generation logic (when cache is recomputed):

• Positions are uniformly sampled inside a 3D ball of radius 10.

• Velocities are uniformly sampled inside a 3D ball of radius 1.

Cache path resolution when path is None:

1. Use directory from env var ssapy_toolkit_CACHE (file name: covariance_sigmas.npy)

2. Fallback to ~/.cache/ssapy_toolkit/covariance_sigmas.npy

If path is provided, it is treated as an explicit file path.

Parameters:

• n (int, default 25) – Number of sigma samples (rows).

• path (str or None) – Optional explicit path for the cache file.

Returns:

Array of shape (n, 6).

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.lognormal_array(mean: float = 0.0, sigma: float = 1.0, size: tuple = (1, 10), dtype: str = 'float64') → ndarray

Log-normal array sample: exp( N(mean, sigma^2) ).

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.multivariate_normal_array(mean: Sequence[float], cov: ndarray, size: int = 1, dtype: str = 'float64') → ndarray

Multivariate normal N(mean, cov) sampling.

Parameters:

• mean (sequence of float) – Mean vector.

• cov (np.ndarray) – Covariance matrix.

• size (int) – Number of samples.

Returns:

Shape (size, dim).

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.normal_array(mean: float = 0.0, std: float = 1.0, size: tuple = (1, 10), dtype: str = 'float64') → ndarray

Gaussian N(mean, std^2) array sample.

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.normal_scalar(mean: float = 0.0, std: float = 1.0) → float

Gaussian N(mean, std^2) scalar sample.

Return type:

float

ssapy_toolkit.Compute.sampling.perturb_state_3d(r: ndarray, v: ndarray, pos_scale: float = 1.0, vel_scale: float = 0.1, pos_distribution: str = 'uniform', vel_distribution: str = 'uniform', rng: Generator | None = None) → tuple[ndarray, ndarray]

Perturb a 3D position and velocity with isotropic spherical uncertainty.

Parameters:

• r (array-like, shape (3,)) – Nominal 3D position vector.

• v (array-like, shape (3,)) – Nominal 3D velocity vector.

• pos_scale (float, default 1.0) –

  Characteristic scale of the position perturbation. Interpretation depends on pos_distribution:

  • ’uniform’ : max radius of solid ball

  • ’normal’ : standard deviation per component

  • ’shell’ : fixed radius

  • ’laplace’ : Laplace scale per component

• vel_scale (float, default 0.1) – Same idea as pos_scale, but for the velocity perturbation.

• pos_distribution ({'uniform', 'normal', 'gaussian', 'shell', 'surface', 'laplace'}) – Distribution for position offset (see _sample_3d_offset).

• vel_distribution ({'uniform', 'normal', 'gaussian', 'shell', 'surface', 'laplace'}) – Distribution for velocity offset.

• rng (np.random.Generator or None) – Optional RNG for reproducibility.

Returns:

(r_pert, v_pert) – Perturbed position and velocity, each shape (3,).

Return type:

tuple of np.ndarray

Examples

>>> r = np.array([7000e3, 0.0, 0.0])
>>> v = np.array([0.0, 7.5e3, 0.0])
>>> r_p, v_p = perturb_state_3d(r, v, pos_scale=100.0, vel_scale=0.1,
...                             pos_distribution='uniform',
...                             vel_distribution='normal')

ssapy_toolkit.Compute.sampling.poisson_array(lam: float = 1.0, size: tuple = (1, 10), dtype: str = 'int64') → ndarray

Poisson(lam) array sample.

Parameters:

lam (float) – Expected value (lambda).

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.rand_num(low: float = 0.0, high: float = 1.0) → float

Draw a single uniform random float in [low, high).

Parameters:

• low (float, default 0.0) – Lower bound (inclusive).

• high (float, default 1.0) – Upper bound (exclusive).

Returns:

Uniform random number in [low, high).

Return type:

float

ssapy_toolkit.Compute.sampling.random_arr(low: float = 0, high: float = 1, size: tuple = (1, 10), dtype: str = 'float64') → ndarray

Generate a random array with specified bounds and size.

Parameters:

• low (float, default 0) – Lower bound.

• high (float, default 1) – Upper bound (for floats) or inclusive upper bound (for ints).

• size (tuple, default (1, 10)) – Shape of the array.

• dtype (str, default 'float64') – Data type. If ‘int’ is in the string, integer sampling is used.

Returns:

Random array.

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.sample_from_sequence(seq: Sequence, n: int, replacement: bool = False) → ndarray

Uniformly sample n elements from a sequence.

Parameters:

• seq (Sequence) – The sequence to sample from.

• n (int) – Number of elements to sample.

• replacement (bool, default False) – If True, sample with replacement; otherwise without replacement.

Returns:

Array of sampled elements.

Return type:

np.ndarray

Notes

This is a thin wrapper around numpy.random.choice with p=None (uniform discrete sampling over the sequence indices).

ssapy_toolkit.Compute.sampling.shuffle(x: list) → None

Shuffle a list in-place using Python’s built-in RNG.

Parameters:

x (list) – List to shuffle.

Return type:

None

ssapy_toolkit.Compute.sampling.uniform_array(low: float = 0.0, high: float = 1.0, size: tuple = (1, 10), dtype: str = 'float64') → ndarray

Uniform( low, high ) array sample.

Return type:

np.ndarray

ssapy_toolkit.Compute.sampling.uniform_scalar(low: float = 0.0, high: float = 1.0) → float

Uniform( low, high ) scalar sample.

Return type:

float