Metadata-Version: 2.4
Name: aeroptimpy
Version: 0.3.1
Summary: Fleet-aware airline route-network optimization in Python.
Project-URL: Homepage, https://github.com/GodsentIzzy123/aeroptimpy
Project-URL: Repository, https://github.com/GodsentIzzy123/aeroptimpy
Project-URL: Issues, https://github.com/GodsentIzzy123/aeroptimpy/issues
Project-URL: Changelog, https://github.com/GodsentIzzy123/aeroptimpy/blob/main/CHANGELOG.md
Author-email: Osayimwense Izinyon <godsentizinyon20@gmail.com>
License: MIT
License-File: LICENSE
Keywords: airline,aviation,folium,geospatial,gurobi,highs,mixed integer programming,operations research,route optimization
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: scipy<2,>=1.11
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: folium>=0.15; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: gurobi
Requires-Dist: gurobipy<14,>=13.0; extra == 'gurobi'
Provides-Extra: viz
Requires-Dist: folium>=0.15; extra == 'viz'
Description-Content-Type: text/markdown

# 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](docs/user-guide.md)** — what to input, how to solve, how to read results & maps
- **[API reference](docs/api-reference.md)** — classes, parameters, and return fields
- **[Docs index](docs/README.md)**

## Installation

```bash
pip install aeroptimpy
```

No solver license is required for the default HiGHS backend.

Optional Gurobi support:

```bash
pip install "aeroptimpy[gurobi]"
```

Optional interactive maps:

```bash
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

```python
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:

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

## Visualize optimal routes

```python
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:

```bash
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

```bash
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:

```bash
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
