folf

Python library implementation of first-order loss function tooling, mirroring the Java classes in java/folf and java/utilities.

Features

• Empirical first-order and complementary first-order loss functions
• Scalar-product variants, including multivariate normal closed-form approximation
• Jensen partitioners (uniform and minimax)
• Piecewise linearization helpers and linearization-parameter chooser
• Probability sampling utilities (SRS and LHS)
• Utility modules for SHA-256 and JSON serialization

Who This Is For

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.

Installation

pip install -e .

Command-line usage:

folf-cli --help

For development:

pip install -e .[dev]

Quick Start

CLI: Plot a loss function and its piecewise linearisation

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.png

Supported distributions in CLI:

• poisson:<lambda>
• norm:<mu>:<sigma>
• gamma:<shape>:<scale>

The command produces a plot with:

• Empirical loss function curve
• Piecewise linearisation curve

1. Empirical first-order loss from sampled distributions

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)

1b. Compare SRS vs LHS sampling strategies

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.

2. Scalar-product first-order loss with multivariate normal demand

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)

3. Choose piecewise linearization parameters

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 use
• q: 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)

Typical Workflow

1. Model your demand distribution(s) with SciPy distributions or a normal mean/covariance pair.
2. Compute CL(x) or L(x) either empirically (sampling) or from the MVN closed-form helper.
3. If building optimization models, use the Jensen partitioners or linearization factory to derive approximation parameters.

Public API At A Glance

• FirstOrderLossFunction
• FirstOrderLossFunctionScalarProduct
• FirstOrderLossFunctionScalarProductMVN
• JensenUniformPartitioner
• JensenMinimaxPartitioner
• PiecewiseStandardNormalFirstOrderLossFunction
• LinearisationFactory

Quality Checks

./venv/bin/python -m pytest -q
./venv/bin/python -m ruff check .
./venv/bin/python -m mypy src/folf

Release Metadata

• Homepage: https://github.com/gwren/folf
• Repository: https://github.com/gwren/folf
• Issue Tracker: https://github.com/gwren/folf/issues
• Changelog: CHANGELOG.md

Package Layout

• src/folf: Main library package
• src/folf/utilities: Utility modules analogous to Java utilities
• tests: Basic smoke and behavior tests

Changelog

Release notes follow Keep a Changelog. See CHANGELOG.md.