folf computes Edmundson-Madansky (UB) and Jensen-based (LB) piecewise linear approximations suitable for embedding the first order loss function in mixed-integer linear optimization models.
- Empirical first-order and complementary first-order loss functions for sums of independent SciPy distributions, with series, plotting, and CSV export
- Simple random and Latin hypercube sampling, including empirical loss functions for weighted scalar products of random variables
- Exact closed-form loss functions for scalar projections of multivariate normal demand, using either full covariance or independent-demand variance
- Uniform and minimax Jensen partitions for standard normal demand, including partition probabilities, conditional means, and maximum approximation error
- Numerically stable partitioning and linearisation calculations, with tail-safe normal probabilities, log-space breakpoints, and tolerance-aware mass allocation
- Empirical Jensen piecewise linear lower approximations for both loss-function orientations, with pointwise and maximum error calculations
- Cached standard normal linearization data and automatic selection of segment and variance-partition counts for a requested error tolerance
This library is useful when you need approximate or empirical first-order loss functions for inventory and stochastic optimization workflows, especially with normal or sampled demand models.
R. Rossi, S. A. Tarim, B. Hnich, and S. Prestwich, "Piecewise linear lower and upper bounds for the standard normal first order loss function," Applied Mathematics and Computation, Elsevier, vol. 231, pp. 489-502, 2014.
R. Rossi, E.M.T. Hendrix, "Computing linearisation parameters of arbitrarily distributed first order loss functions," in Proceedings of MAGO'14, XII Global Optimization Workshop (GOW).
R. Rossi, S. Prestwich, and S. A. Tarim, "Mixed-Integer Linear Programming Approximations for the Stochastic Knapsack," Computers & Operations Research, Elsevier, Vol. 194: 107571, 2026.
pip install -e .Command-line usage:
folf-cli --helpFor development:
pip install -e .[dev]folf-cli plot-loss \
--distribution poisson:20 \
--distribution norm:8:2 \
--distribution gamma:4:1.5 \
--sampling LHS \
--samples 5000 \
--x-min 10 \
--x-max 60 \
--precision 0.5 \
--piecewise-masses 0.25,0.25,0.25,0.25 \
--loss-type complementary \
--output artifacts/loss_piecewise.pngSupported distributions in CLI:
poisson:<lambda>norm:<mu>:<sigma>gamma:<shape>:<scale>
The command produces a plot with:
- Empirical loss function curve
- Piecewise linearisation curve
from scipy.stats import gamma, norm, poisson
from folf import FirstOrderLossFunction
from folf.utilities.probability.sampling import SAMPLING
folf = FirstOrderLossFunction(
distributions=[
poisson(20), # discrete demand component
norm(8, 2), # approximately normal component
gamma(a=4, scale=1.5), # right-skewed positive component
],
sampling_strategy=SAMPLING.SRS,
)
x = 70.0
nb_samples = 5_000
complementary = folf.get_complementary_first_order_loss_function_value(x, nb_samples)
regular = folf.get_first_order_loss_function_value(x, nb_samples)
print("CL(x):", complementary)
print("L(x):", regular)from scipy.stats import gamma, norm, poisson
from folf import FirstOrderLossFunction
from folf.utilities.probability.sampling import SAMPLING
distributions = [
poisson(20),
norm(8, 2),
gamma(a=4, scale=1.5),
]
srs_model = FirstOrderLossFunction(distributions, sampling_strategy=SAMPLING.SRS)
lhs_model = FirstOrderLossFunction(distributions, sampling_strategy=SAMPLING.LHS)
x = 70.0
nb_samples = 2_000
cl_srs = srs_model.get_complementary_first_order_loss_function_value(x, nb_samples)
cl_lhs = lhs_model.get_complementary_first_order_loss_function_value(x, nb_samples)
print("CL(x) using SRS:", cl_srs)
print("CL(x) using LHS:", cl_lhs)Use SRS for a straightforward baseline and LHS when you want lower Monte Carlo
variance for the same sample count.
import numpy as np
from folf import FirstOrderLossFunctionScalarProductMVN
model = FirstOrderLossFunctionScalarProductMVN(
mean=np.array([10.0, 15.0, 20.0]),
covariance=np.array(
[
[4.0, 1.2, 0.8],
[1.2, 9.0, 2.0],
[0.8, 2.0, 16.0],
]
),
independent_demand=False,
)
weights = np.array([0.5, 0.3, 0.2])
y = 14.0
cl = model.get_complementary_first_order_loss_function_value(y, weights)
l = model.get_first_order_loss_function_value(y, weights)
print("CL(y):", cl)
print("L(y):", l)If you are embedding first-order loss terms in an optimization model (for
example MILP or MIP), you typically replace nonlinear loss expressions with a
piecewise linear approximation. LinearisationFactory.choose_linearisation_parameters
helps pick:
w_segments: how many loss-function segments to useq: how many variance/sqrt partitions to use
for a requested approximation tolerance epsilon, variance bound vmax, and
cost coefficient c.
from folf import LinearisationFactory
epsilon = 0.5
vmax = 4.0
c = 10.0
w_segments, q = LinearisationFactory.choose_linearisation_parameters(epsilon, vmax, c)
print("segments:", w_segments)
print("q:", q)- Model your demand distribution(s) with SciPy distributions or a normal mean/covariance pair.
- Compute CL(x) or L(x) either empirically (sampling) or from the MVN closed-form helper.
- If building optimization models, use the Jensen partitioners or linearization factory to derive approximation parameters.
- FirstOrderLossFunction
- FirstOrderLossFunctionScalarProduct
- FirstOrderLossFunctionScalarProductMVN
- JensenUniformPartitioner
- JensenMinimaxPartitioner
- PiecewiseStandardNormalFirstOrderLossFunction
- LinearisationFactory
./venv/bin/python -m pytest -q
./venv/bin/python -m ruff check .
./venv/bin/python -m mypy src/folf- Homepage: https://github.com/gwren/folf
- Repository: https://github.com/gwren/folf
- Issue Tracker: https://github.com/gwren/folf/issues
- Changelog: CHANGELOG.md
src/folf: Main library packagesrc/folf/utilities: Utility modulestests: Basic smoke and behavior tests