Quickstart

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

Run as an MLflow project

If you have parameters and values for training a Bézier simplex in common file formats such as CSV, JSON, etc., then the easiest way is to invoke PyTorch-BSF via MLflow. In this way, some CLI commands for training and prediction are provided without installing PyTorch-BSF. On each training and prediction, separation of runtime environment and installation of PyTorch-BSF are automatically handled by MLflow!

Installation

First, install Miniconda. 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
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

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

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

Assume you have installed Python 3.10 or above. Then, install the package:

pip install pytorch-bsf

Then, run torch_bsf as a module:

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

Run as Python code

Assume you have installed Python 3.10 or above. Then, install the package:

pip install pytorch-bsf

Train a model by fit(), and 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)