torch_bsf package

Submodules

torch_bsf.active_learning module

torch_bsf.active_learning.suggest_next_points(models: List[BezierSimplex], n_suggestions: int = 1, n_candidates: int = 1000, method: str = 'qbc', params: Tensor | None = None) → Tensor[source]

Suggest points on the simplex where new data should be sampled.

Parameters:

  • models (List[BezierSimplex]) – An ensemble of models (e.g., from k-fold cross-validation).

  • n_suggestions (int, default=1) – The number of points to suggest.

  • n_candidates (int, default=1000) – The number of candidate points to evaluate.

  • method (str, default="qbc") – The method to use: - “qbc”: Query-By-Committee. Suggests points where models disagree most. - “density”: Suggests points that are furthest from existing training points.

  • params (torch.Tensor, optional) – The existing training parameters. Required for method=”density”.

Returns:

The suggested points in shape (n_suggestions, n_params).

Return type:

torch.Tensor

torch_bsf.bezier_simplex module

class torch_bsf.bezier_simplex.BezierSimplex(control_points: ControlPoints | dict[str, Tensor] | dict[str, list[float]] | dict[str, tuple[float, ...]] | dict[tuple[int, ...], Tensor] | dict[tuple[int, ...], list[float]] | dict[tuple[int, ...], tuple[float, ...]] | dict[Tensor, Tensor] | dict[Tensor, list[float]] | dict[Tensor, tuple[float, ...]] | None = None, smoothness_weight: float = 0.0, *, _n_params: int | None = None, _degree: int | None = None, _n_values: int | None = None)[source]

Bases: LightningModule

A Bezier simplex model.

Parameters:

  • control_points – The control points of the Bezier simplex. Pass None only when reconstructing a model from a Lightning checkpoint via load_from_checkpoint() — in that case all three shape parameters (_n_params, _degree, _n_values) must be provided so that a correctly-shaped placeholder can be built before the saved state dict is loaded into it.

  • smoothness_weight – The weight of the smoothness penalty term added to the training loss. When greater than zero, adjacent control points are encouraged to have similar values. Defaults to 0.0 (no penalty).

  • _n_params – Checkpoint-reconstruction parameter — do not set manually. The number of parameters (source dimension + 1) used to build the placeholder control points when control_points is None. Automatically saved to, and restored from, Lightning checkpoints.

  • _degree – Checkpoint-reconstruction parameter — do not set manually. The degree of the Bezier simplex used to build the placeholder when control_points is None. Automatically saved to, and restored from, Lightning checkpoints.

  • _n_values – Checkpoint-reconstruction parameter — do not set manually. The number of values (target dimension) used to build the placeholder when control_points is None. Automatically saved to, and restored from, Lightning checkpoints.

Examples

>>> import lightning.pytorch as L
>>> from lightning.pytorch.callbacks.early_stopping import EarlyStopping
>>> from torch.utils.data import DataLoader, TensorDataset
>>> ts = torch.tensor(  # parameters on a simplex
...     [
...         [3/3, 0/3, 0/3],
...         [2/3, 1/3, 0/3],
...         [2/3, 0/3, 1/3],
...         [1/3, 2/3, 0/3],
...         [1/3, 1/3, 1/3],
...         [1/3, 0/3, 2/3],
...         [0/3, 3/3, 0/3],
...         [0/3, 2/3, 1/3],
...         [0/3, 1/3, 2/3],
...         [0/3, 0/3, 3/3],
...     ]
... )
>>> xs = 1 - ts * ts  # values corresponding to the parameters
>>> dl = DataLoader(TensorDataset(ts, xs))
>>> bs = torch_bsf.bezier_simplex.randn(
...     n_params=int(ts.shape[1]),
...     n_values=int(xs.shape[1]),
...     degree=3,
... )
>>> trainer = L.Trainer(
...     callbacks=[EarlyStopping(monitor="train_mse")],
...     enable_progress_bar=False,
... )
>>> trainer.fit(bs, dl)
>>> ts, xs = bs.meshgrid()
configure_optimizers() → Optimizer[source]
property degree: int[source]

The degree of the Bezier simplex.

fix_row(index: torch_bsf.bezier_simplex.Index) → None[source]

Freeze a control point so its gradient is zeroed after every backward.

Parameters:

index – The index of the control point to freeze.

forward(t: Tensor) → Tensor[source]

Process a forwarding step of training.

Parameters:

t – A minibatch of parameter vectors \(\mathbf t\).

Return type:

A minibatch of value vectors.

meshgrid(num: int = 100) → tuple[Tensor, Tensor][source]

Computes a meshgrid of the Bezier simplex.

Parameters:

num – The number of grid points on each edge.

Returns:

  • ts – A parameter matrix of the mesh grid.

  • xs – A value matrix of the mesh grid.

property n_params: int[source]

The number of parameters, i.e., the source dimension + 1.

property n_values: int[source]

The number of values, i.e., the target dimension.

on_after_backward() → None[source]

Zero gradients for frozen control-point rows after each backward pass.

smoothness_penalty() → Tensor[source]

Computes the smoothness penalty of the Bezier simplex.

Return type:

The smoothness penalty.

test_step(batch, batch_idx) → dict[str, Any][source]
training_step(batch, batch_idx) → dict[str, Any][source]
validation_step(batch, batch_idx) → None[source]
class torch_bsf.bezier_simplex.BezierSimplexDataModule(params: Path, values: Path, header: int = 0, batch_size: int | None = None, split_ratio: float = 1.0, normalize: Literal['max', 'std', 'quantile', 'none'] = 'none')[source]

Bases: LightningDataModule

A data module for training a Bezier simplex.

Parameters:

  • params – The path to a parameter file.

  • values – The path to a value file.

  • header – The number of header rows in the parameter file and the value file. The first header rows are skipped in reading the files.

  • batch_size – The size of each minibatch.

  • split_ratio – The ratio of train-val split. Must be greater than 0 and less than or equal to 1. If it is set to 1, then all the data are used for training and the validation step will be skipped.

  • normalize – The data normalization method. Either "max", "std", "quantile", or "none".

fit_transform(values: Tensor) → Tensor[source]
inverse_transform(values: Tensor) → Tensor[source]
load_data(path) → Tensor[source]
load_params() → Tensor[source]
load_values() → Tensor[source]
setup(stage: str | None = None)[source]
test_dataloader() → DataLoader[source]
train_dataloader() → DataLoader[source]
val_dataloader() → DataLoader[source]
torch_bsf.bezier_simplex.fit(params: Tensor, values: Tensor, degree: int | None = None, init: BezierSimplex | ControlPoints | dict[str, Tensor] | dict[str, list[float]] | dict[str, tuple[float, ...]] | dict[tuple[int, ...], Tensor] | dict[tuple[int, ...], list[float]] | dict[tuple[int, ...], tuple[float, ...]] | dict[Tensor, Tensor] | dict[Tensor, list[float]] | dict[Tensor, tuple[float, ...]] | None = None, smoothness_weight: float = 0.0, fix: Iterable[str | Sequence[int] | Tensor] | None = None, batch_size: int | None = None, **kwargs) → BezierSimplex[source]

Fits a Bezier simplex.

Parameters:

  • params – The data.

  • values – The label data.

  • degree – The degree of the Bezier simplex.

  • init – The initial values of a bezier simplex or control points.

  • smoothness_weight – The weight of smoothness penalty.

  • fix – The indices of control points to exclude from training.

  • batch_size – The size of minibatch.

  • kwargs – All arguments for lightning.pytorch.Trainer

Return type:

A trained Bezier simplex.

Raises:

  • TypeError – From Trainer or DataLoader.

  • MisconfigurationException – From Trainer.

Examples

>>> import torch
>>> import torch_bsf

Prepare training data

>>> ts = torch.tensor(  # parameters on a simplex
...     [
...         [3/3, 0/3, 0/3],
...         [2/3, 1/3, 0/3],
...         [2/3, 0/3, 1/3],
...         [1/3, 2/3, 0/3],
...         [1/3, 1/3, 1/3],
...         [1/3, 0/3, 2/3],
...         [0/3, 3/3, 0/3],
...         [0/3, 2/3, 1/3],
...         [0/3, 1/3, 2/3],
...         [0/3, 0/3, 3/3],
...     ]
... )
>>> xs = 1 - ts * ts  # values corresponding to the parameters

Train a model

>>> bs = torch_bsf.fit(params=ts, values=xs, degree=3)

Predict by the trained model

>>> t = [[0.2, 0.3, 0.5]]
>>> x = bs(t)
>>> print(f"{t} -> {x}")
[[0.2, 0.3, 0.5]] -> tensor([[..., ..., ...]], grad_fn=<...>)

See also

lightning.pytorch.Trainer

Argument descriptions.

torch.DataLoader

Argument descriptions.

torch_bsf.bezier_simplex.load(path: str | Path, *, pt_weights_only: bool | None = None) → BezierSimplex[source]

Loads a Bezier simplex from a file.

Parameters:

  • path – The path to a file.

  • pt_weights_only – Whether to load weights only. This parameter is only effective when loading PyTorch (.pt) files. For other formats (e.g., .json, .yml), data loading is inherently safe and this parameter is ignored. If None, it defaults to False.

Return type:

A Bezier simplex.

Raises:

  • ValueError – If the file type is unknown.

  • ValidationError – If the control points are invalid.

Notes

Setting pt_weights_only=True will fail if the model contains classes not allowed by PyTorch’s WeightsUnpickler (like lightning’s AttributeDict), even if they are in the safe globals list.

Examples

>>> from torch_bsf import bezier_simplex
>>> bs = bezier_simplex.load("tests/data/bezier_simplex.csv")
>>> print(bs)
BezierSimplex(
  (control_points): ControlPoints(n_params=2, degree=2, n_values=3)
)
>>> print(bs(torch.tensor([[0.2, 0.8]])))
tensor([[..., ..., ...]], grad_fn=<...>)
torch_bsf.bezier_simplex.monomial(variable: Iterable[float], degree: Iterable[int]) → Tensor[source]

Computes a monomial \(\mathbf t^{\mathbf d} = t_1^{d_1} t_2^{d_2}\cdots t_M^{d^M}\).

Parameters:

  • variable – The bases \(\mathbf t\).

  • degree – The powers \(\mathbf d\).

Return type:

The monomial \(\mathbf t^{\mathbf d}\).

torch_bsf.bezier_simplex.polynom(degree: int, index: Iterable[int]) → float[source]

Computes a polynomial coefficient \(\binom{D}{\mathbf d} = \frac{D!}{d_1!d_2!\cdots d_M!}\).

Parameters:

  • degree – The degree \(D\).

  • index – The index \(\mathbf d\).

Return type:

The polynomial coefficient \(\binom{D}{\mathbf d}\).

torch_bsf.bezier_simplex.rand(n_params: int, n_values: int, degree: int, smoothness_weight: float = 0.0) → BezierSimplex[source]

Generates a random Bezier simplex.

The control points are initialized by random values. The values are uniformly distributed in [0, 1).

Parameters:

  • n_params – The number of parameters, i.e., the source dimension + 1.

  • n_values – The number of values, i.e., the target dimension.

  • degree – The degree of the Bezier simplex.

  • smoothness_weight – The weight of smoothness penalty.

Return type:

A random Bezier simplex.

Raises:

ValueError – If n_params or n_values or degree is negative.

Examples

>>> import torch
>>> from torch_bsf import bezier_simplex
>>> bs = bezier_simplex.rand(n_params=2, n_values=3, degree=2)
>>> print(bs)
BezierSimplex(
  (control_points): ControlPoints(n_params=2, degree=2, n_values=3)
)
>>> print(bs(torch.tensor([[0.2, 0.8]])))
tensor([[..., ..., ...]], grad_fn=<...>)
torch_bsf.bezier_simplex.randn(n_params: int, n_values: int, degree: int, smoothness_weight: float = 0.0) → BezierSimplex[source]

Generates a random Bezier simplex.

The control points are initialized by random values. The values are normally distributed with mean 0 and standard deviation 1.

Parameters:

  • n_params – The number of parameters, i.e., the source dimension + 1.

  • n_values – The number of values, i.e., the target dimension.

  • degree – The degree of the Bezier simplex.

  • smoothness_weight – The weight of smoothness penalty.

Return type:

A random Bezier simplex.

Raises:

ValueError – If n_params or n_values or degree is negative.

Examples

>>> import torch
>>> from torch_bsf import bezier_simplex
>>> bs = bezier_simplex.randn(n_params=2, n_values=3, degree=2)
>>> print(bs)
BezierSimplex(
  (control_points): ControlPoints(n_params=2, degree=2, n_values=3)
)
>>> print(bs(torch.tensor([[0.2, 0.8]])))
tensor([[..., ..., ...]], grad_fn=<...>)
torch_bsf.bezier_simplex.save(path: str | Path, data: BezierSimplex) → None[source]

Saves a Bezier simplex to a file.

Parameters:

  • path – The file path to save.

  • data – The Bezier simplex to save.

Raises:

ValueError – If the file type is unknown.

Examples

>>> import torch_bsf
>>> bs = torch_bsf.bezier_simplex.randn(n_params=2, n_values=3, degree=2)
>>> torch_bsf.bezier_simplex.save("tests/data/bezier_simplex.pt", bs)
>>> torch_bsf.bezier_simplex.save("tests/data/bezier_simplex.csv", bs)
>>> torch_bsf.bezier_simplex.save("tests/data/bezier_simplex.tsv", bs)
>>> torch_bsf.bezier_simplex.save("tests/data/bezier_simplex.json", bs)
>>> torch_bsf.bezier_simplex.save("tests/data/bezier_simplex.yml", bs)
torch_bsf.bezier_simplex.validate_control_points(data: dict[str, list[float]])[source]

Validates control points.

Parameters:

data – The control points.

Raises:

ValidationError – If the control points are invalid.

Examples

>>> from torch_bsf.bezier_simplex import validate_control_points
>>> validate_control_points({
...     "(1, 0, 0)": [1.0, 0.0, 0.0],
...     "(0, 1, 0)": [0.0, 1.0, 0.0],
...     "(0, 0, 1)": [0.0, 0.0, 1.0],
... })

>>> validate_control_points({
...     "(1, 0, 0)": [1.0, 0.0, 0.0],
...     "(0, 1, 0)": [0.0, 1.0, 0.0],
...     "0, 0, 1": [0.0, 0.0, 1.0],
... })
Traceback (most recent call last):
    ...
jsonschema.exceptions.ValidationError: '0, 0, 1' is not valid under any of the given schemas

>>> validate_control_points({
...     "(1, 0, 0)": [1.0, 0.0, 0.0],
...     "(0, 1, 0)": [0.0, 1.0, 0.0],
...     "(0, 0, 1)": [0.0, 0.0, 1.0],
...     "(0, 0)": [0.0, 0.0, 0.0],
... })
Traceback (most recent call last):
    ...
jsonschema.exceptions.ValidationError: Dimension mismatch: (0, 0)

>>> validate_control_points({
...     "(1, 0, 0)": [1.0, 0.0, 0.0],
...     "(0, 1, 0)": [0.0, 1.0, 0.0],
...     "(0, 0, 1, 0)": [0.0, 0.0, 1.0],
... })
Traceback (most recent call last):
    ...
jsonschema.exceptions.ValidationError: Dimension mismatch: (0, 0, 1, 0)

>>> validate_control_points({
...     "(1, 0, 0)": [1.0, 0.0, 0.0],
...     "(0, 1, 0)": [0.0, 1.0, 0.0],
...     "(0, 0, 1)": [0.0, 0.0, 1.0, 0.0],
... })
Traceback (most recent call last):
    ...
jsonschema.exceptions.ValidationError: Dimension mismatch: [0.0, 0.0, 1.0, 0.0]

>>> validate_control_points({
...     "(1, 0, 0)": [1.0, 0.0, 0.0],
...     "(0, 1, 0)": [0.0, 1.0, 0.0],
...     "(0, 0, 1)": [0.0, 0.0],
... })
Traceback (most recent call last):
    ...
jsonschema.exceptions.ValidationError: Dimension mismatch: [0.0, 0.0]
torch_bsf.bezier_simplex.zeros(n_params: int, n_values: int, degree: int, smoothness_weight: float = 0.0) → BezierSimplex[source]

Generates a Bezier simplex with control points at origin.

Parameters:

  • n_params – The number of parameters, i.e., the source dimension + 1.

  • n_values – The number of values, i.e., the target dimension.

  • degree – The degree of the Bezier simplex.

  • smoothness_weight – The weight of smoothness penalty.

Return type:

A Bezier simplex filled with zeros.

Raises:

ValueError – If n_params or n_values or degree is negative.

Examples

>>> import torch
>>> from torch_bsf import bezier_simplex
>>> bs = bezier_simplex.zeros(n_params=2, n_values=3, degree=2)
>>> print(bs)
BezierSimplex(
  (control_points): ControlPoints(n_params=2, degree=2, n_values=3)
)
>>> print(bs(torch.tensor([[0.2, 0.8]])))
tensor([[..., ..., ...]], grad_fn=<...>)

torch_bsf.control_points module

class torch_bsf.control_points.ControlPoints(data: dict[str, Tensor] | dict[str, list[float]] | dict[str, tuple[float, ...]] | dict[tuple[int, ...], Tensor] | dict[tuple[int, ...], list[float]] | dict[tuple[int, ...], tuple[float, ...]] | dict[Tensor, Tensor] | dict[Tensor, list[float]] | dict[Tensor, tuple[float, ...]] | None = None)[source]

Bases: Module

Control points of a Bezier simplex stored as a single parameter matrix.

All control points are stored in one nn.Parameter matrix of shape (n_indices, n_values). This eliminates the Python-level loop and torch.stack call that would otherwise occur on every forward pass, giving a direct O(1) access path to the parameter data.

matrix[source]

nn.Parameter of shape (n_indices, n_values) holding all control points in canonical simplex-index order.

degree[source]

The degree of the Bezier simplex.

n_params[source]

The number of parameters (source dimension + 1).

n_values[source]

The number of values (target dimension).

Examples

>>> import torch_bsf
>>> control_points = torch_bsf.control_points.ControlPoints({
...     (1, 0): [0.0, 0.1, 0.2],
...     (0, 1): [1.0, 1.1, 1.2],
... })

>>> control_points.degree
1
>>> control_points.n_params
2
>>> control_points.n_values
3

>>> control_points[(1, 0)]
tensor([0.0000, 0.1000, 0.2000], grad_fn=<SelectBackward0>)
>>> control_points[(0, 1)]
tensor([1.0000, 1.1000, 1.2000], grad_fn=<SelectBackward0>)
extra_repr() → str[source]
indices() → Iterator[tuple[int, ...]][source]

Iterates the index of control points of the Bezier simplex.

Return type:

The indices in canonical order.

items() → Iterator[tuple[str, Tensor]][source]

Iterates (str_key, value_tensor) pairs in canonical order.

Return type:

An iterator of (key, value) pairs.

keys() → Iterator[str][source]

Iterates canonical string keys in canonical order.

torch_bsf.control_points.ControlPointsData: TypeAlias = dict[str, torch.Tensor] | dict[str, list[float]] | dict[str, tuple[float, ...]] | dict[tuple[int, ...], torch.Tensor] | dict[tuple[int, ...], list[float]] | dict[tuple[int, ...], tuple[float, ...]] | dict[torch.Tensor, torch.Tensor] | dict[torch.Tensor, list[float]] | dict[torch.Tensor, tuple[float, ...]][source]

The data type of control points of a Bezier simplex.

torch_bsf.control_points.Index: TypeAlias = str | typing.Sequence[int] | torch.Tensor[source]

The index type of control points of a Bezier simplex.

torch_bsf.control_points.Value: TypeAlias = typing.Sequence[float] | torch.Tensor[source]

The value type of control points of a Bezier simplex.

torch_bsf.control_points.simplex_indices(n_params: int, degree: int) → Iterable[tuple[int, ...]][source]

Iterates the index of control points of a Bezier simplex.

Parameters:

  • n_params – The tuple length of each index.

  • degree – The degree of the Bezier simplex.

Return type:

The indices.

torch_bsf.control_points.to_parameterdict(data: dict[str, Tensor] | dict[str, list[float]] | dict[str, tuple[float, ...]] | dict[tuple[int, ...], Tensor] | dict[tuple[int, ...], list[float]] | dict[tuple[int, ...], tuple[float, ...]] | dict[Tensor, Tensor] | dict[Tensor, list[float]] | dict[Tensor, tuple[float, ...]]) → dict[str, Tensor][source]

Convert data to a dictionary with canonical string keys.

Parameters:

data (dict) – Data to be converted.

Returns:

Converted data.

Return type:

dict

torch_bsf.control_points.to_parameterdict_key(index: str | Sequence[int] | Tensor) → str[source]

Convert an index to a canonical string key.

Parameters:

index (str or tuple[int]) – An index of control points.

Returns:

A canonical string key.

Return type:

str

torch_bsf.control_points.to_parameterdict_value(value: Sequence[float] | Tensor) → Tensor[source]

Convert a value to a tensor.

Parameters:

value (list[float]) – A value.

Returns:

A tensor.

Return type:

torch.Tensor

torch_bsf.plotting module

torch_bsf.plotting.plot_bezier_simplex(model: BezierSimplex, num: int = 100, ax=None, show_control_points: bool = True, **kwargs)[source]

Plots the Bezier simplex.

Parameters:

  • model – The Bezier simplex model.

  • num – The number of grid points for each edge.

  • ax – The matplotlib axes to plot on.

  • show_control_points – Whether to show control points.

  • kwargs – Additional arguments for the plot.

torch_bsf.preprocessing module

class torch_bsf.preprocessing.MinMaxScaler[source]

Bases: object

Min-max scaler that normalizes values to the [0, 1] range.

mins[source]

Minimum values per feature dimension.

Type:

torch.Tensor

scales[source]

Scale factors (max - min) per feature dimension. Dimensions where max equals min are set to 1 to avoid division by zero.

Type:

torch.Tensor

fit(values: Tensor) → None[source]

Fit the scaler to the data.

Computes the per-feature minimum and scale (max - min) from values.

Parameters:

values (torch.Tensor) – Input tensor of shape (n_samples, n_features).

fit_transform(values: Tensor) → Tensor[source]

Fit the scaler to the data and return the normalized tensor.

Parameters:

values (torch.Tensor) – Input tensor of shape (n_samples, n_features).

Returns:

Normalized tensor of the same shape as values, with each feature scaled to the [0, 1] range.

Return type:

torch.Tensor

inverse_transform(values: Tensor) → Tensor[source]

Reverse the normalization applied by fit_transform().

Parameters:

values (torch.Tensor) – Normalized tensor of shape (n_samples, n_features).

Returns:

Tensor rescaled back to the original value range.

Return type:

torch.Tensor

mins: Tensor[source]
scales: Tensor[source]
class torch_bsf.preprocessing.NoneScaler[source]

Bases: object

Pass-through scaler that leaves values unchanged.

Useful as a no-op placeholder when normalization is not required, while still providing the same fit(), fit_transform(), and inverse_transform() interface as the other scalers.

fit(values: Tensor) → None[source]

No-op fit method included for API compatibility.

Parameters:

values (torch.Tensor) – Input tensor (ignored).

fit_transform(values: Tensor) → Tensor[source]

Return values unchanged.

Parameters:

values (torch.Tensor) – Input tensor of any shape.

Returns:

The same tensor as values without any modification.

Return type:

torch.Tensor

inverse_transform(values: Tensor) → Tensor[source]

Return values unchanged.

Parameters:

values (torch.Tensor) – Input tensor of any shape.

Returns:

The same tensor as values without any modification.

Return type:

torch.Tensor

class torch_bsf.preprocessing.QuantileScaler[source]

Bases: object

Quantile-based scaler that normalizes values using percentile-based ranges.

Values are scaled so that the q-th percentile maps to 0 and the (1 - q)-th percentile maps to 1, without clipping values to this range. This makes the scaler robust to outliers compared to MinMaxScaler.

q[source]

The lower quantile fraction used as the effective minimum. Defaults to 0.05 (5th percentile), ignoring the bottom and top 5% of values.

Type:

float

mins[source]

Per-feature values at the q-th quantile, computed during fit().

Type:

torch.Tensor

scales[source]

Per-feature scale factors ((1-q)-quantile minus q-quantile). Dimensions where the scale is zero are set to 1 to avoid division by zero.

Type:

torch.Tensor

fit(values: Tensor) → None[source]

Fit the scaler to the data.

Computes per-feature quantile bounds from values.

Parameters:

values (torch.Tensor) – Input tensor of shape (n_samples, n_features).

fit_transform(values: Tensor) → Tensor[source]

Fit the scaler to the data and return the scaled tensor.

Parameters:

values (torch.Tensor) – Input tensor of shape (n_samples, n_features).

Returns:

Scaled tensor of the same shape as values. Values outside the fitted quantile range may exceed [0, 1].

Return type:

torch.Tensor

inverse_transform(values: Tensor) → Tensor[source]

Reverse the scaling applied by fit_transform().

Parameters:

values (torch.Tensor) – Scaled tensor of shape (n_samples, n_features).

Returns:

Tensor rescaled back to the original value range.

Return type:

torch.Tensor

mins: Tensor[source]
q: float = 0.05[source]
scales: Tensor[source]
class torch_bsf.preprocessing.StdScaler[source]

Bases: object

Standard-score (z-score) scaler that normalizes values to zero mean and unit variance.

means[source]

Per-feature means computed during fit().

Type:

torch.Tensor

stds[source]

Per-feature standard deviations computed during fit(). Dimensions with zero standard deviation are set to 1 to avoid division by zero.

Type:

torch.Tensor

fit(values: Tensor) → None[source]

Fit the scaler to the data.

Computes the per-feature mean and standard deviation from values.

Parameters:

values (torch.Tensor) – Input tensor of shape (n_samples, n_features).

fit_transform(values: Tensor) → Tensor[source]

Fit the scaler to the data and return the standardized tensor.

Parameters:

values (torch.Tensor) – Input tensor of shape (n_samples, n_features).

Returns:

Standardized tensor of the same shape as values, with each feature having zero mean and unit standard deviation.

Return type:

torch.Tensor

inverse_transform(values: Tensor) → Tensor[source]

Reverse the standardization applied by fit_transform().

Parameters:

values (torch.Tensor) – Standardized tensor of shape (n_samples, n_features).

Returns:

Tensor rescaled back to the original value range.

Return type:

torch.Tensor

means: Tensor[source]
stds: Tensor[source]

torch_bsf.sampling module

torch_bsf.sampling.simplex_grid(n_params: int, degree: int) → Tensor[source]

Generates a uniform grid on a simplex.

Parameters:

  • n_params (int) – The number of parameters (vertices of the simplex).

  • degree (int) – The degree of the grid.

Returns:

Array of grid points in shape (N, n_params), where N = binom(degree + n_params - 1, n_params - 1).

Return type:

torch.Tensor

torch_bsf.sampling.simplex_random(n_params: int, n_samples: int) → Tensor[source]

Generates random points on a simplex using Dirichlet distribution.

Parameters:

  • n_params (int) – The number of parameters (vertices of the simplex).

  • n_samples (int) – The number of samples.

Returns:

Array of sample points in shape (n_samples, n_params).

Return type:

torch.Tensor

Raises:

ValueError – If n_params is not positive or n_samples is negative.

torch_bsf.sampling.simplex_sobol(n_params: int, n_samples: int) → Tensor[source]

Generates quasi-random points on a simplex using Sobol sequence.

Parameters:

  • n_params (int) – The number of parameters (vertices of the simplex). Must be at least 2.

  • n_samples (int) – The number of samples.

Returns:

Array of sample points in shape (n_samples, n_params).

Return type:

torch.Tensor

Raises:

  • ImportError – If SciPy is not installed.

  • ValueError – If n_params is less than 2 or n_samples is negative.

torch_bsf.sklearn module

class torch_bsf.sklearn.BezierSimplexRegressor(*args: Any, **kwargs: Any)[source]

Bases: BaseEstimator, RegressorMixin

Scikit-learn wrapper for Bezier Simplex Fitting.

Parameters:

  • degree (int, default=3) – The degree of the Bezier simplex.

  • smoothness_weight (float, default=0.0) – The weight of smoothness penalty.

  • init (BezierSimplex | ControlPointsData | None, default=None) – Initial control points or model.

  • fix (Iterable[Index] | None, default=None) – Indices of control points to fix during training.

  • batch_size (int | None, default=None) – Size of minibatches.

  • max_epochs (int, default=1000) – Maximum number of epochs to train.

  • accelerator (str, default="auto") – Hardware accelerator to use (“cpu”, “gpu”, “auto”, etc.).

  • devices (int | str, default="auto") – Number of devices to use.

  • precision (str, default="32-true") – Floating point precision.

  • trainer_kwargs (dict | None, default=None) – Additional keyword arguments for lightning.pytorch.Trainer.

fit(X: Any, y: Any)[source]

Fit the Bezier simplex model.

Parameters:

  • X (array-like of shape (n_samples, n_params)) – Training data (parameters on a simplex).

  • y (array-like of shape (n_samples, n_values)) – Target values.

Returns:

self – Fitted estimator.

Return type:

object

predict(X: Any) → ndarray[source]

Predict using the Bezier simplex model.

Parameters:

X (array-like of shape (n_samples, n_params)) – Input parameters.

Returns:

y_pred – Predicted values.

Return type:

ndarray of shape (n_samples, n_values)

score(X: Any, y: Any, sample_weight: Any = None) → float[source]

Return the coefficient of determination R^2 of the prediction.

Parameters:

  • X (array-like of shape (n_samples, n_params)) – Test samples.

  • y (array-like of shape (n_samples, n_values)) – True values.

  • sample_weight (array-like of shape (n_samples,), default=None) – Sample weights.

Returns:

score – R^2 of self.predict(X) wrt. y.

Return type:

float

torch_bsf.validator module

torch_bsf.validator.index_list(val: str) → list[list[int]][source]

Parse val into a list of indices.

Parameters:

val – A string expression of a list of indices.

Return type:

The persed indices.

torch_bsf.validator.indices_schema(n_params: int, degree: int) → dict[str, Any][source]

Generate a JSON schema for indices of the control points with given n_params and degree.

Parameters:

  • n_params – The number of index elements of control points.

  • degree – The degree of a Bezier surface.

Return type:

A JSON schema.

Raises:

ValueError – If n_params or degree is negative.

See also

validate_simplex_indices

Validate an instance that has appropriate n_params and degree.

torch_bsf.validator.int_or_str(val: str) → int | str[source]

Try to parse int. Return the int value if the parse is succeeded; the original string otherwise.

Parameters:

val – The value to try to convert into int.

Returns:

The converted integer or the original value.

Return type:

Union[int, str]

torch_bsf.validator.validate_simplex_indices(instance: object, n_params: int, degree: int) → None[source]

Validate an instance that has appropriate n_params and degree.

Parameters:

  • instance – An index list of a Bezier simplex.

  • n_params – The n_params of a Bezier simplex.

  • degree – The degree of a Bezier simplex.

Raises:

ValidationError – If instance does not comply with the following schema or has an inner array whose sum is not equal to degree. `     {         "$schema": "https://json-schema.org/draft/2020-12/schema",         "type": "array",         "items": {             "type": "array",             "items": {                 "type": "integer",                 "minimum": 0,                 "maximum": degree,             },             "minItems": n_params,             "maxItems": n_params,         },     }     `

Module contents

torch_bsf: PyTorch implementation of Bezier simplex fitting.

class torch_bsf.BezierSimplex(control_points: ControlPoints | dict[str, Tensor] | dict[str, list[float]] | dict[str, tuple[float, ...]] | dict[tuple[int, ...], Tensor] | dict[tuple[int, ...], list[float]] | dict[tuple[int, ...], tuple[float, ...]] | dict[Tensor, Tensor] | dict[Tensor, list[float]] | dict[Tensor, tuple[float, ...]] | None = None, smoothness_weight: float = 0.0, *, _n_params: int | None = None, _degree: int | None = None, _n_values: int | None = None)[source]

Bases: LightningModule

A Bezier simplex model.

Parameters:

  • control_points – The control points of the Bezier simplex. Pass None only when reconstructing a model from a Lightning checkpoint via load_from_checkpoint() — in that case all three shape parameters (_n_params, _degree, _n_values) must be provided so that a correctly-shaped placeholder can be built before the saved state dict is loaded into it.

  • smoothness_weight – The weight of the smoothness penalty term added to the training loss. When greater than zero, adjacent control points are encouraged to have similar values. Defaults to 0.0 (no penalty).

  • _n_params – Checkpoint-reconstruction parameter — do not set manually. The number of parameters (source dimension + 1) used to build the placeholder control points when control_points is None. Automatically saved to, and restored from, Lightning checkpoints.

  • _degree – Checkpoint-reconstruction parameter — do not set manually. The degree of the Bezier simplex used to build the placeholder when control_points is None. Automatically saved to, and restored from, Lightning checkpoints.

  • _n_values – Checkpoint-reconstruction parameter — do not set manually. The number of values (target dimension) used to build the placeholder when control_points is None. Automatically saved to, and restored from, Lightning checkpoints.

Examples

>>> import lightning.pytorch as L
>>> from lightning.pytorch.callbacks.early_stopping import EarlyStopping
>>> from torch.utils.data import DataLoader, TensorDataset
>>> ts = torch.tensor(  # parameters on a simplex
...     [
...         [3/3, 0/3, 0/3],
...         [2/3, 1/3, 0/3],
...         [2/3, 0/3, 1/3],
...         [1/3, 2/3, 0/3],
...         [1/3, 1/3, 1/3],
...         [1/3, 0/3, 2/3],
...         [0/3, 3/3, 0/3],
...         [0/3, 2/3, 1/3],
...         [0/3, 1/3, 2/3],
...         [0/3, 0/3, 3/3],
...     ]
... )
>>> xs = 1 - ts * ts  # values corresponding to the parameters
>>> dl = DataLoader(TensorDataset(ts, xs))
>>> bs = torch_bsf.bezier_simplex.randn(
...     n_params=int(ts.shape[1]),
...     n_values=int(xs.shape[1]),
...     degree=3,
... )
>>> trainer = L.Trainer(
...     callbacks=[EarlyStopping(monitor="train_mse")],
...     enable_progress_bar=False,
... )
>>> trainer.fit(bs, dl)
>>> ts, xs = bs.meshgrid()
configure_optimizers() → Optimizer[source]
property degree: int[source]

The degree of the Bezier simplex.

fix_row(index: torch_bsf.bezier_simplex.Index) → None[source]

Freeze a control point so its gradient is zeroed after every backward.

Parameters:

index – The index of the control point to freeze.

forward(t: Tensor) → Tensor[source]

Process a forwarding step of training.

Parameters:

t – A minibatch of parameter vectors \(\mathbf t\).

Return type:

A minibatch of value vectors.

meshgrid(num: int = 100) → tuple[Tensor, Tensor][source]

Computes a meshgrid of the Bezier simplex.

Parameters:

num – The number of grid points on each edge.

Returns:

  • ts – A parameter matrix of the mesh grid.

  • xs – A value matrix of the mesh grid.

property n_params: int[source]

The number of parameters, i.e., the source dimension + 1.

property n_values: int[source]

The number of values, i.e., the target dimension.

on_after_backward() → None[source]

Zero gradients for frozen control-point rows after each backward pass.

smoothness_penalty() → Tensor[source]

Computes the smoothness penalty of the Bezier simplex.

Return type:

The smoothness penalty.

test_step(batch, batch_idx) → dict[str, Any][source]
training_step(batch, batch_idx) → dict[str, Any][source]
validation_step(batch, batch_idx) → None[source]
class torch_bsf.BezierSimplexDataModule(params: Path, values: Path, header: int = 0, batch_size: int | None = None, split_ratio: float = 1.0, normalize: Literal['max', 'std', 'quantile', 'none'] = 'none')[source]

Bases: LightningDataModule

A data module for training a Bezier simplex.

Parameters:

  • params – The path to a parameter file.

  • values – The path to a value file.

  • header – The number of header rows in the parameter file and the value file. The first header rows are skipped in reading the files.

  • batch_size – The size of each minibatch.

  • split_ratio – The ratio of train-val split. Must be greater than 0 and less than or equal to 1. If it is set to 1, then all the data are used for training and the validation step will be skipped.

  • normalize – The data normalization method. Either "max", "std", "quantile", or "none".

fit_transform(values: Tensor) → Tensor[source]
inverse_transform(values: Tensor) → Tensor[source]
load_data(path) → Tensor[source]
load_params() → Tensor[source]
load_values() → Tensor[source]
setup(stage: str | None = None)[source]
test_dataloader() → DataLoader[source]
train_dataloader() → DataLoader[source]
val_dataloader() → DataLoader[source]
torch_bsf.fit(params: Tensor, values: Tensor, degree: int | None = None, init: BezierSimplex | ControlPoints | dict[str, Tensor] | dict[str, list[float]] | dict[str, tuple[float, ...]] | dict[tuple[int, ...], Tensor] | dict[tuple[int, ...], list[float]] | dict[tuple[int, ...], tuple[float, ...]] | dict[Tensor, Tensor] | dict[Tensor, list[float]] | dict[Tensor, tuple[float, ...]] | None = None, smoothness_weight: float = 0.0, fix: Iterable[str | Sequence[int] | Tensor] | None = None, batch_size: int | None = None, **kwargs) → BezierSimplex[source]

Fits a Bezier simplex.

Parameters:

  • params – The data.

  • values – The label data.

  • degree – The degree of the Bezier simplex.

  • init – The initial values of a bezier simplex or control points.

  • smoothness_weight – The weight of smoothness penalty.

  • fix – The indices of control points to exclude from training.

  • batch_size – The size of minibatch.

  • kwargs – All arguments for lightning.pytorch.Trainer

Return type:

A trained Bezier simplex.

Raises:

  • TypeError – From Trainer or DataLoader.

  • MisconfigurationException – From Trainer.

Examples

>>> import torch
>>> import torch_bsf

Prepare training data

>>> ts = torch.tensor(  # parameters on a simplex
...     [
...         [3/3, 0/3, 0/3],
...         [2/3, 1/3, 0/3],
...         [2/3, 0/3, 1/3],
...         [1/3, 2/3, 0/3],
...         [1/3, 1/3, 1/3],
...         [1/3, 0/3, 2/3],
...         [0/3, 3/3, 0/3],
...         [0/3, 2/3, 1/3],
...         [0/3, 1/3, 2/3],
...         [0/3, 0/3, 3/3],
...     ]
... )
>>> xs = 1 - ts * ts  # values corresponding to the parameters

Train a model

>>> bs = torch_bsf.fit(params=ts, values=xs, degree=3)

Predict by the trained model

>>> t = [[0.2, 0.3, 0.5]]
>>> x = bs(t)
>>> print(f"{t} -> {x}")
[[0.2, 0.3, 0.5]] -> tensor([[..., ..., ...]], grad_fn=<...>)

See also

lightning.pytorch.Trainer

Argument descriptions.

torch.DataLoader

Argument descriptions.