BilevelPy

An extensible Python framework for building, solving, and evaluating Gurobi-based optimization models, with built-in support for hub-location problems.

Project status: BilevelPy is an alpha release. Its public API may change before version 1.0.0.

Overview

BilevelPy provides reusable abstractions for implementing optimization models with Gurobi. It separates data preparation, model construction, solver execution, and solution extraction into focused components.

The current release includes:

• composable Variable and Constraint classes
• dependency-aware model construction through BaseModel
• structured datasets and preprocessing pipelines
• configurable Gurobi execution and structured solutions
• built-in hub-location components
• CAB25 and CAB100 benchmark datasets

Installation

pip install bilevelpy

Requirements:

• Python 3.11–3.14
• Gurobi Optimizer 11.0 or newer
• a valid Gurobi licence

BilevelPy is licensed separately from Gurobi. Installing BilevelPy does not provide a licence for Gurobi Optimizer.

See the installation guide for development setup and further details.

Typical workflow

from bilevelpy import Dataset, ModelSolver
from bilevelpy.data.builder import DatasetBuilder
from bilevelpy.data.loaders import HLPLoader
from bilevelpy.data.processor import HLPNodeSelector

dataset = (
    DatasetBuilder()
    .pipe(HLPLoader(Dataset.CAB100))
    .pipe(HLPNodeSelector(n_nodes=10))
    .build()
)

# Define a BaseModel subclass with the required variables,
# constraints, and objective.
model = MyModel(data=dataset)
solution = ModelSolver(model).solve()

print(solution)

The quickstart tutorial contains a complete single-allocation hub-location model.

Documentation

• Installation
• Quickstart tutorial
• Architecture
• Dataset guide
• Model guide
• Solver guide
• Full pipeline example
• API reference

Research implementation

A complete research implementation built with BilevelPy is available in An Oracle-based Approach for Price-setting Problems in Logistics.

Citation

Citation metadata is available in CITATION.cff.

Changelog

See CHANGELOG.md for the release history.

Licence

BilevelPy is licensed under the Apache License 2.0.

Gurobi Optimizer and gurobipy are proprietary software distributed and licensed separately by Gurobi Optimization, LLC.