aeroptimpy

AerOptimPy

AerOptimPy is an early-stage Python package for fleet-aware airline route-network and flight-frequency optimization.

The package uses the free, open-source HiGHS optimizer by default through scipy.optimize.milp. Gurobi remains available as an optional backend for users with an appropriate Gurobi license.

The first model answers this planning question:

Given passenger demand, fares, aircraft capacity, fleet availability, airport slots, aircraft range, and operating costs, which direct routes should an airline operate and how frequently should it fly them?

Documentation

Full guides for GitHub readers:

• User guide — what to input, how to solve, how to read results & maps
• API reference — classes, parameters, and return fields
• Docs index

Installation

pip install aeroptimpy

No solver license is required for the default HiGHS backend.

Optional Gurobi support:

pip install "aeroptimpy[gurobi]"

Optional interactive maps:

pip install "aeroptimpy[viz]"

Requires Python 3.10+.

What users provide

You supply three ingredients:

1. Airports — codes, coordinates, optional slot limits
2. Fleet — aircraft types with seats, counts, range, speed, and block-hour cost
3. Demand — directed markets with passengers and average fares

Then AerOptimPy returns an optimized frequency plan (which routes, which aircraft, how many flights).

Minimal example

from aeroptimpy import Aircraft, Airport, Demand, RouteNetwork, RouteOptimizer

airports = [
    Airport("DTW", 42.2162, -83.3554, slot_limit=40),
    Airport("ATL", 33.6407, -84.4277, slot_limit=50),
]

fleet = [
    Aircraft(
        name="A320",
        capacity=180,
        count=2,
        range_km=6100,
        cruise_speed_kmh=830,
        cost_per_block_hour=6500,
    )
]

demand = [
    Demand("DTW", "ATL", passengers=240, average_fare=210),
    Demand("ATL", "DTW", passengers=220, average_fare=205),
]

network = RouteNetwork(airports=airports, aircraft=fleet, demand=demand)
optimizer = RouteOptimizer(network)  # solver="highs" is the default
result = optimizer.solve(planning_days=1, max_flights_per_leg=5)

print(result.summary())
for route in result.routes:
    print(route)

Select Gurobi explicitly when it is installed and licensed:

optimizer = RouteOptimizer(network, solver="gurobi")

Visualize optimal routes

from aeroptimpy.viz import plot_routes

fmap = plot_routes(
    network,
    result,
    theme="midnight",
    weight_by="flights",
    rank_by="contribution",  # value ranking, not flight order
    animate=True,
)
fmap.save("optimal_routes.html")

On the map:

• Airplane icon (top-left, under zoom) — filter by aircraft type
• Route inspector (bottom-right) — tap a route to read details at your pace
• Play / Pause — optional slow ranked tour

Run the map example with:

python examples/plot_optimal_routes.py

Current scope

• Validated airport, aircraft, and passenger-demand data models
• Great-circle distance and aircraft-range feasibility checks
• Solver-independent mixed-integer route activation and frequency model
• Free HiGHS backend enabled by default; optional Gurobi backend
• Passenger demand, seat capacity, fleet hours, slots, and flow-balance constraints
• Optional carbon-price penalty
• Structured results and interactive Folium maps
• Synthetic multi-airport examples

Development install

git clone https://github.com/GodsentIzzy123/aeroptimpy.git
cd aeroptimpy
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,viz]"
pytest

Run the basic optimizer example:

python examples/basic_route_optimization.py

Model summary

For airport pair (i, j) and aircraft type k, the model uses:

• activate[i,j,k]: binary route-aircraft activation variable
• flights[i,j,k]: integer number of flights
• served[i,j]: passengers carried

The objective maximizes passenger revenue minus flight operating cost and an optional carbon-price penalty.

Map rankings by contribution show economic priority, not a single-aircraft itinerary.

Research roadmap

1. Add BTS T-100 and DB1C data ingestion.
2. Add demand forecasting and scenario generation.
3. Compare deterministic, stochastic, robust, and chance-constrained models.
4. Add emissions and reliability Pareto-front analysis.
5. Benchmark HiGHS and Gurobi on increasingly large route networks.
6. Publish benchmark instances and reproducible computational experiments.

Citation

If you use AerOptimPy in academic work, please cite it (see CITATION.cff).

License

MIT