PyTorch-BSF

Fit smooth, high-dimensional manifolds to your data — from a single GPU to a multi-node cluster.

pytorch-bsf brings Bézier Simploid Fitting (BSF) to PyTorch. A Bézier simplex is a high-dimensional generalization of the Bézier curve: where a curve models a 1-D path, a Bézier simplex can model an arbitrarily complex point cloud as a smooth parametric hyper-surface in any number of dimensions. Bézier simploids go further: they are tensor products of Bézier simplices defined on products of simplices such as prisms and cubes, and simploidal sets glue such cells along common faces. This makes them a natural tool for representing Pareto fronts in multi-objective optimization, interpolating scattered observations, and fitting geometric structures in high-dimensional spaces.

Key features:

• Simple, Pythonic API — fit a model in one line with torch_bsf.fit(), which solves the least-squares problem exactly by default, call it like any PyTorch module, and persist control points in .pt, .csv, .tsv, .json, or .yaml formats.
• Scalable Training — fully vectorized forward pass, and an optional PyTorch Lightning trainer (solver="trainer", installed with pip install "pytorch-bsf[lightning]") for seamless scaling from a single CPU to multi-GPU, multi-node clusters.
• Robust & Automatic Fitting — built-in smoothness regularization tames noisy data, and automatic degree selection via k-fold cross-validation removes guesswork.
• Rich ML Ecosystem — scikit-learn-compatible BezierSimploidRegressor for use in Pipeline and GridSearchCV; MLflow experiment tracking for the CLI (optional, installed with pip install "pytorch-bsf[mlflow]"); active learning; and advanced sampling strategies (Dirichlet, Sobol).
• Beyond Simplices — the same torch_bsf.fit() fits Bézier simploids (e.g., simploid_type=(2, 1) for a prism), and torch_bsf.simploidal fits simploidal sets, when a single simplex is not the right parameter domain.
• Ready to Run — CLI entry points, a pre-built Docker image, and a Conda/MLflow project so you can run pytorch-bsf without installing it into your local environment.

BSF formerly stood for Bézier Simplex Fitting, which remains the special case where the parameter domain is a single simplex.

See Full Documentation and the following papers for technical details.

• Kobayashi, K., Hamada, N., Sannai, A., Tanaka, A., Bannai, K., & Sugiyama, M. (2019). Bézier Simplex Fitting: Describing Pareto Fronts of Simplicial Problems with Small Samples in Multi-Objective Optimization. Proceedings of the AAAI Conference on Artificial Intelligence, 33(01), 2304-2313. https://doi.org/10.1609/aaai.v33i01.33012304
• Tanaka, A., Sannai, A., Kobayashi, K., & Hamada, N. (2020). Asymptotic Risk of Bézier Simplex Fitting. Proceedings of the AAAI Conference on Artificial Intelligence, 34(03), 2416-2424. https://doi.org/10.1609/aaai.v34i03.5622

Quickstart

Requirements: For local installation and CLI/library usage, Python >=3.10. For Docker-only usage, only Docker is required.

Optional extras: Lightning (solver="trainer"), MLflow (CLI experiment tracking), SciPy, scikit-learn and matplotlib are optional; install them with extras, e.g. pip install "pytorch-bsf[lightning,mlflow]". See Installation for the list of extras and the features each one enables, and for upgrading from a version that installed Lightning and MLflow by default.

First, prepare your data:

cat <<EOS > params.csv
1.00, 0.00
0.75, 0.25
0.50, 0.50
0.25, 0.75
0.00, 1.00
EOS
cat <<EOS > values.csv
0.00, 1.00
3.00, 2.00
4.00, 5.00
7.00, 6.00
8.00, 9.00
EOS

1. via Docker (No Installation Required)

Prerequisites: Docker.

A pre-built image is available on GHCR, built on condaforge/miniforge3 with PyTorch (CPU build) installed from the conda-forge channel:

docker run --rm \
  --user "$(id -u)":"$(id -g)" \
  -v "$(pwd)":/workspace \
  ghcr.io/opthub-org/pytorch-bsf \
  python -m torch_bsf \
  --params=params.csv \
  --values=values.csv \
  --degree=3

2. via MLflow (No Installation Required)

Prerequisites: Miniforge, and pip install mlflow. Another conda installation also works, but conda 26.7 and later still add the channels in your .condarc to the environment (conda/conda#16816), so remove defaults there (conda config --remove channels defaults) to keep it out.

MLflow creates a conda environment from the project's environment.yml, which installs PyTorch and the other dependencies from the conda-forge channel only:

mlflow run https://github.com/opthub-org/pytorch-bsf \
  -P params=params.csv \
  -P values=values.csv \
  -P degree=3

3. via CLI (After Installation)

This method is suitable when you do not need experiment tracking. If you prefer to install the package, you can run it via the command line interface.

Installation:

pip install pytorch-bsf

MLflow is optional. To log the parameters, metrics and models of the CLI runs to MLflow (see loglevel below), install the mlflow extra (or all); without it, the CLI fits and saves the model but logs nothing:

pip install "pytorch-bsf[mlflow]"

Execution:

python -m torch_bsf \
  --params=params.csv \
  --values=values.csv \
  --degree=3

4. via Python Script

This is the most flexible method. Fit a model using the Python API fit(), and call the resulting model to predict.

import torch
import torch_bsf

# Prepare training data
ts = torch.tensor(  # parameters on a simplex
    [
        [8 / 8, 0 / 8],
        [7 / 8, 1 / 8],
        [6 / 8, 2 / 8],
        [5 / 8, 3 / 8],
        [4 / 8, 4 / 8],
        [3 / 8, 5 / 8],
        [2 / 8, 6 / 8],
        [1 / 8, 7 / 8],
        [0 / 8, 8 / 8],
    ]
)
xs = 1 - ts * ts  # values corresponding to the parameters

# Fit a model (exact least squares; pass solver="trainer" and Lightning options to train instead)
bs = torch_bsf.fit(params=ts, values=xs, degree=3)

# Predict with the trained model
t = [
    [0.2, 0.8],
    [0.7, 0.3],
]
x = bs(t)
print(f"{t} -> {x}")

Saving and Loading Models

Save a trained model and reload it later:

import torch_bsf
from torch_bsf.simploidal import save, load

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

# Save (supported formats: .pt, .csv, .tsv, .json, .yml/.yaml)
save("model.pt", bs)

# Load
bs = load("model.pt")

K-Fold Cross-Validation

Run k-fold cross-validation via the CLI:

python -m torch_bsf.model_selection.kfold \
  --params=params.csv \
  --values=values.csv \
  --degree=3 \
  --num_folds=5

Additional parameters for k-fold (all standard parameters except split_ratio and save are also accepted):

The command prints the errors of each fold model on its held-out fold (val_mse and val_mae) and their means, which are also logged to MLflow (unless --loglevel=0, and if the mlflow extra is installed). It saves per-fold meshgrid predictions as well as an ensemble mean:

• {params},{values},{num_folds}fold,meshgrid,t_{type},d_{degree},{k}.csv (per fold)
• {params},{values},{num_folds}fold,meshgrid,t_{type},d_{degree}.csv (mean over folds)

Here {type} is the simploid type joined by - (e.g., 2 for a triangle, 2-1 for a prism), and {degree} is the degree, joined by - if the factors have different degrees.

In Python, torch_bsf.fit_kfold(params, values, degree=3, n_folds=5) returns the models of the folds.

Elastic Net Grid Search

Generate a grid of 3D parameter points on the standard 2-simplex for elastic net hyperparameter search:

python -m torch_bsf.model_selection.elastic_net_grid \
  --n_lambdas=102 \
  --n_alphas=12 \
  --n_vertex_copies=10 \
  --base=10

The output is printed to stdout as CSV with three columns (one row per grid point).

Advanced Topics

The library includes several capabilities beyond basic fitting. Full documentation for each topic is linked below.

Author

OptHub Inc. and FUJITSU LIMITED

License

MIT