Skip to content

Oracle Paper¶

Documentation of the implemented code for the paper: "An Oracle-based Approach for Price-setting Problems in Logistics" (N. Pommerening, M. Hügging, D. Henke, C. Buchheim, U. Clausen, 2026).

Built on top of BilevelPy.

Section	Description
Problem Formulation	The PS-BHLP model: leader, follower, and full bilevel formulation
Solution Approaches	Three approaches: Big-M, Lagrange, and Fast
API Reference	Auto-generated documentation for every module, class, and function with reference to the paper

Solution Approaches at a Glance¶

All three approaches solve the same bilevel price-setting problem. They differ in how with large performance gaps.

Paper Name	Code Convention	Code	Method	Speed
PS-HLP	Big M	`PS_HLP`	Compact single-level formulation from Section 2, linearized as described in Section 5.	Slowest
PPC-HLP	Lagrange	`PPC_HLP`	Lagrangian decomposition with precedence constraints	Faster
PC-HLP	Fast Lagrange	`PC_HLP`	Lagrangian with merged customers — no precedence (Lemma 3)	Fastest

See Solution Approaches for the full methodology, theoretical results, and computational benchmarks.

Variables¶

Notation	Reproduces	Code Name	API Reference	Used In
\(x_{ik}\)	—	`AllocationVariable`	bilevelpy.core	All models
\(p_{ij}\)	—	`PriceVariable`	`PriceVariable`	PS-HLP
\(y_{ij}^z\)	—	`ClientDecisionVariable`	`ClientDecisionVariable`	PS-HLP, PPC-HLP
\(\bar{y}_{ij}^z\)	—	`RecursiveClientDecisionVariable`	`RecursiveClientDecisionVariable`	PC-HLP (merged clients)
\(X_{ijkm}^z\)	\(y_{ij}^z \cdot x_{ik} \cdot x_{jm}\)	`LinearXYVariable`	`LinearXYVariable`	PS-HLP, PPC-HLP
\(X_{ijkm}^z\)	\(y_{ij}^z \cdot x_{ik} \cdot x_{jm}\)	`RecursiveLinearXYVariable`	`RecursiveLinearXYVariable`	PC-HLP (merged clients)

Constraints¶

Constraint	Code	Used In	Description
Exactly \(\kappa\) hubs	`NumberOfHubsConstraint`	All models	(bilevelpy core)
Single allocation	`SingleAllocationConstraint`	All models	(bilevelpy core)
Assignment restriction	`AssignmentRestrictionConstraint`	All models	(bilevelpy core)
\(y = \sum X\), \(X \leq x\)	`LinearizationConstraint`	PS-HLP, PPC-HLP	Section 5.1 linearization
Big-M coupling	`BigMConstraint`	PS-HLP	Section 2 - PS-HLP
Precedence \(y^z \geq y^{z+1}\)	`PrecedenceConstraint`	PPC-HLP	Section 3
Recursive linearization	`RecursiveLinearizationConstraint`	PC-HLP	Section 5.1 linearization

Quick Example¶

from bilevelpy.core.datasets import Dataset
from bilevelpy.data.builder import DatasetBuilder
from bilevelpy.data.loaders import HLPLoader
from bilevelpy.data.processor import HLPNodeSelector, HLPCostScaling
from bilevelpy.solver import ModelSolver
from oracle_paper.data.generator.bilevel_client_generator import BilevelClientGenerator
from oracle_paper.data.processor.client_ranker import LinearClientRanker
from oracle_paper.models.ps_hlp import PS_HLP

dataset = (
    DatasetBuilder()
    .pipe(HLPLoader(Dataset.CAB100))
    .pipe(HLPNodeSelector(n_nodes=10))
    .pipe(HLPCostScaling(scaling_factor=100))
    .pipe(BilevelClientGenerator(clients_per_route=5))
    .pipe(LinearClientRanker())
    .build()
)

model = PS_HLP(n_hubs=2, alpha=0.5, data=dataset)
solution = ModelSolver(model).solve()
print(solution)