Quickstart

PyTorch-BSF can be used in four ways depending on your workflow: as a Docker container (no installation required), as a zero-install MLflow project (great for one-off experiments with experiment tracking), as a CLI module (scriptable, no Python coding required), or as a Python library (for full programmatic control). Pick the option that best fits your setup.

Run as a Docker Container

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

Prerequisites: Docker.

Training

Let’s prepare sample parameters and values files for training:

cat << EOS > params.csv
00,0.00
75,0.25
50,0.50
25,0.75
00,1.00
EOS
cat << EOS > values.csv
00,1.00
00,2.00
00,5.00
00,6.00
00,9.00
EOS

Warning

The parameters file and the values file must have the same number of lines.

Mount the current directory as /workspace inside the container and run training:

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

The trained model will be saved under mlruns/ in the current directory.

Run as an MLflow Project

MLflow can run PyTorch-BSF directly from its GitHub repository without a manual installation step. It automatically creates a conda environment from the project’s environment.yml, which installs PyTorch and the other dependencies from the conda-forge channel only. This makes it the easiest way to get started with experiment tracking.

Installation

Install Miniforge. 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. Then, install mlflow package from conda-forge channel:

conda install -c conda-forge mlflow

Training

Let’s prepare sample parameters and values files for training:

cat << EOS > params.csv
00,0.00
75,0.25
50,0.50
25,0.75
00,1.00
EOS
cat << EOS > values.csv
00,1.00
00,2.00
00,5.00
00,6.00
00,9.00
EOS

Warning

The parameters file and the values file must have the same number of lines.

Now, you can fit a Bézier simplex model using the latest version of PyTorch-BSF directly from its GitHub repository:

MLFLOW_PROJECT_URL=https://github.com/opthub-org/pytorch-bsf
MLFLOW_ENV_MANAGER=conda

mlflow run "$MLFLOW_PROJECT_URL" \
  -P params=params.csv \
  -P values=values.csv \
  -P degree=3

Tip

To fit a Bézier simploid (e.g., on a prism) instead of a Bézier simplex, add -P simploid_type=2,1, or --simploid-type=2,1 on the command line. See Simploidal Sets.

After the command finishes, the trained model will be saved in mlruns/0 directory. Note the Run ID automatically set to the command execution, as you will need it for prediction.

Prediction

To make predictions, MLflow may use virtualenv and pyenv to create an isolated environment for the model. Please ensure it’s available in your system.

First, find the Run ID (e.g., 47a7…) from the previous training step.

LATEST_RUN_ID=$(ls -td mlruns/0/*/ | grep -v "models" | head -1 | xargs basename)
echo "Tested Run ID: ${LATEST_RUN_ID}"

Next, you can predict with the model and output the results to a specified file (in this example, test_values.json).

mlflow models predict \
  --env-manager=$MLFLOW_ENV_MANAGER \
  --model-uri "runs:/${LATEST_RUN_ID}/model" \
  --content-type csv \
  --input-path params.csv \
  --output-path test_values.json
cat test_values.json
# result will be shown like {"predictions": [{"0": 0.05797366052865982, ...}

See https://mlflow.org/docs/latest/api_reference/cli.html#mlflow-models-predict for details.

Serve Prediction API

You can also serve a Web API for prediction.

First, find the Run ID (e.g., a1b2c3…) set to the model training.

LATEST_RUN_ID=$(ls -td mlruns/0/*/ | grep -v "models" | head -1 | xargs basename)
echo "Tested Run ID: ${LATEST_RUN_ID}"

Then, start a prediction server using the Run ID.

mlflow models serve \
  --env-manager=$MLFLOW_ENV_MANAGER \
  --model-uri "runs:/${LATEST_RUN_ID}/model" \
  --host localhost \
  --port 5001 &

Now, you can request a prediction with HTTP POST method:

curl http://localhost:5001/invocations -H 'Content-Type: application/json' -d '{
  "dataframe_split":{
    "columns": ["t1", "t2"],
    "data": [
       [0.2, 0.8],
       [0.7, 0.3]
    ]
  }
}'

See https://mlflow.org/docs/latest/genai/serving/ for details.

Run as a Python Package

First, install the package (requires Python 3.10 or above):

pip install pytorch-bsf

MLflow is an optional dependency. To log the parameters, metrics and models of the CLI runs to MLflow (--loglevel=1 or 2, the default), install the mlflow extra (or all) instead:

pip install "pytorch-bsf[mlflow]"

Without it, the CLI still fits the model and saves the control points and the predictions, but prints a warning and logs nothing. See Installation for all extras.

Then run torch_bsf as a CLI module:

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

Run as Python Code

First, install the package (requires Python 3.10 or above):

pip install pytorch-bsf

To train with the Lightning trainer (solver="trainer", see Hardware Acceleration), install the lightning extra instead:

pip install "pytorch-bsf[lightning]"

See Installation for the other extras and for upgrading from a version that installed Lightning and MLflow by default.

Train a model by calling fit(), then call the model to predict.

import torch
import torch_bsf

# Prepare training parameters
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

# Train a model
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(x)