PyTorch-BSF

Bézier Simploid Fitting in PyTorch.

PyTorch-BSF is a Python library for fitting parametric curves, surfaces and higher-dimensional models to data. It is useful for approximating Pareto fronts in multi-objective optimization, building surrogate response models and interpolating observations on meshes.

A Bézier simplex generalizes a Bézier curve to a simplex, such as a triangle or tetrahedron. A simploid is a product of simplices, allowing domains such as squares and prisms. Cells can also be joined along shared faces. These geometries use the same BezierSpace, BezierModel and regression API.

Documentation · PyPI · Changelog · Issue tracker

Features

• Regression and point cloud fitting: fit known parameter-response pairs, or estimate unknown coordinates for points on a single Bézier simplex or simploid.
• Controlled geometry: use simplex, product and joined-cell domains, with shared control points, exact fixed controls and quadratic regularization.
• Interpolation and optimization: construct shape-preserving interpolants on simplicial meshes or optimize coefficients against a differentiable cost.
• Numerical diagnostics: solve least-squares problems with dense SVD or optional sparse LSMR, and inspect errors, conditioning and termination state.
• Model evaluation and reuse: cross-validation, degree selection, ensembles, random/Sobol/grid sampling, plotting and versioned model archives.
• Optional integrations: scikit-learn estimators, Lightning execution and explicit MLflow experiment recording.

Installation

Requires Python 3.11 or later and PyTorch 2.3 or later (below 3.0).

CI covers Python 3.11 through 3.15. The optional mlflow and all extras are tested on Python 3.11 through 3.14.

For Python 3.15, install the other integrations with python -m pip install "pytorch-bsf[lightning,sparse,sklearn,plot]".

Install the package and its core dependencies with:

python -m pip install pytorch-bsf

Add integrations as needed, for example:

python -m pip install 'pytorch-bsf[sparse,plot]'

Dense fitting and random, Sobol and grid sampling work with the core installation. See the installation guide for details and alternative environments.

Quickstart

Fit the quadratic response y = 4x² from three observations on 0 ≤ x ≤ 1, then predict at two new locations. A segment uses barycentric coordinates [1-x, x]: each row contains two nonnegative weights that sum to one.

import torch
from torch_bsf import BezierSpace, Samples, fit

space = BezierSpace.simplex(dimension=1, degree=2)
parameters = torch.tensor([[1.0, 0.0], [0.5, 0.5], [0.0, 1.0]], dtype=torch.float64)
result = fit(space, Samples(parameters, [[0.0], [1.0], [4.0]]))
result.require_success()

# x = 0.25 and x = 0.75
query = torch.tensor([[0.75, 0.25], [0.25, 0.75]], dtype=torch.float64)
with torch.no_grad():
    print(result.model(query))
# tensor([[0.2500],
#         [2.2500]], dtype=torch.float64)

fit returns a FitResult containing a model, metrics, diagnostics and termination state. require_success() raises if the numerical solve failed. Predictions have shape (n_points, n_outputs); result.model is a PyTorch module supporting automatic differentiation. Core least-squares fitting runs on CPU in float64, with both dense and sparse solvers.

Choose a different entry point when your inputs differ:

Command line

The same fitting and prediction operations are available from the CLI. First create params.csv and values.csv using the Quickstart CSV example, then run in the directory containing those files:

python -m torch_bsf fit --params params.csv --values values.csv --degree 2 --save model.bsf
python -m torch_bsf predict --model model.bsf --params params.csv --save predictions.csv

Fitting saves a reusable model archive to model.bsf; prediction writes one output row per parameter row to predictions.csv. Use python -m torch_bsf --help or see the CLI guide for more operations and options.

Documentation

Start at the documentation home and choose the tag matching your installed version under Other Versions. Guide links in this README target development (master) and may describe unreleased changes. Before 1.0, minor releases may include breaking API changes; consult the migration guide when upgrading.

Runnable scripts are available in examples. With a repository checkout and Bash, run bash examples/quickstart/run.sh from the repository root for the complete CLI walkthrough.

Contributing and support

Bug reports, documentation improvements and code contributions are welcome. Use the issue tracker for bugs and feature requests; include a minimal reproducer and environment details when reporting a bug. The FAQ covers common usage questions.

See the contributing guide for development setup, running tests and pull request requirements.

Research references

For research using Bézier simplex fitting, cite the relevant methodological papers:

• Kobayashi et al. (AAAI 2019), Bézier Simplex Fitting: Describing Pareto Fronts of Simplicial Problems with Small Samples in Multi-Objective Optimization.
• Tanaka et al. (AAAI 2020), Asymptotic Risk of Bézier Simplex Fitting.

See the bibliography for further background and references for individual methods.

License

PyTorch-BSF is distributed under the MIT License.