Skip to content

Samplers

pybasin.sampler.Sampler

Bases: ABC

Abstract base class for sampling initial conditions using PyTorch.

Functions

__init__ 

__init__(
    min_limits: list[float],
    max_limits: list[float],
    device: str | None = None,
)

Initialize the sampler.

Parameters:

Name Type Description Default
min_limits list[float]

List of minimum values for each state.

 required
max_limits list[float]

List of maximum values for each state.

 required
device str | None

Device to use ('cuda', 'cpu', or None for auto-detect).

 None

sample abstractmethod 

sample(n: int) -> torch.Tensor

Generate n samples for the initial conditions.

Parameters:

Name Type Description Default
n int

Number of samples.

 required

Returns:

Type Description
Tensor

Sampled initial conditions as a tensor of shape (n, state_dim).

pybasin.sampler.UniformRandomSampler

Bases: Sampler

Generates random samples using a uniform distribution within the specified range.

pybasin.sampler.GridSampler

Bases: Sampler

Generates evenly spaced samples in a grid pattern within the specified range.

Handles fixed dimensions (where min == max) by only distributing grid points along varying dimensions. For example, with limits [-10, 10], [-20, 20], [0, 0] and n=20000, the grid uses n^(1/2) ≈ 142 points per varying dimension (x, y) and a single point for the fixed dimension (z), yielding 142 x 142 x 1 = 20164 unique samples instead of 28 x 28 x 28 = 21952 with many duplicates.

pybasin.sampler.GaussianSampler

Bases: Sampler

Generates samples using a Gaussian distribution around the midpoint.

pybasin.sampler.CsvSampler

Bases: Sampler

Loads samples from a CSV file.

This sampler reads initial conditions from a CSV file, useful for reproducing exact results from MATLAB or other reference implementations.

Attributes

labels property 

labels: ndarray | None

Return ground truth labels from the CSV file, or None if no label column was specified.

n_samples property 

n_samples: int

Return the total number of samples in the CSV file.

Functions

__init__ 

__init__(
    csv_path: str | Path,
    coordinate_columns: list[str],
    label_column: str | None = None,
    device: str | None = None,
)

Initialize the CSV sampler.

Parameters:

Name Type Description Default
csv_path str | Path

Path to the CSV file containing samples.

 required
coordinate_columns list[str]

List of column names to use as coordinates (e.g., ["x1", "x2"] or ["disp", "vel"]).

 required
label_column str | None

Column name containing ground truth labels (e.g., "label"). If None, no labels are loaded.

 None
device str | None

Device to use ('cuda', 'cpu', or None for auto-detect).

 None

sample 

sample(n: int | None = None) -> torch.Tensor

Return samples from the CSV file.

Parameters:

Name Type Description Default
n int | None

Number of samples to return. If None, returns all samples. If n is larger than available samples, raises ValueError. If n is smaller than available samples, returns first n samples.

 None

Returns:

Type Description
Tensor

Sampled initial conditions as a tensor of shape (n, state_dim).