Metadata-Version: 2.5
Name: bluebird-dt
Version: 0.3.0
Summary: A simulation and AI development framework for air traffic control.
Project-URL: Documentation, http://docs.projectbluebird.ai
Project-URL: Repository, https://github.com/project-bluebird/BluebirdATC
Author: Project Bluebird
License-Expression: AGPL-3.0-or-later
Requires-Python: <3.15,>=3.10
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: geojson<4,>=3.2.0
Requires-Dist: geopy<3,>=2.5.0
Requires-Dist: matplotlib<4,>=3.10.8
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas<3,>=2.2.3
Requires-Dist: platformdirs<5,>=4.11.3
Requires-Dist: pyarrow<26,>=24.0.0
Requires-Dist: pydantic<3,>=2.12.5
Requires-Dist: pyproj<3.8,>=3.7.1
Requires-Dist: python-dateutil<3,>=2.9.0
Requires-Dist: requests<3,>=2.33.0
Requires-Dist: scipy<2,>=1.15.3
Requires-Dist: shapely<3,>=2.1.2
Description-Content-Type: text/markdown

# The Digital Twin [![PyPI version](https://img.shields.io/pypi/v/bluebird-dt?logo=pypi&logoColor=white)](https://pypi.org/project/bluebird-dt/) <img src="../images/BBATC_logo.png" alt="BluebirdATC logo" align="right" height="160" />

`bluebird_dt` encodes a digital twin of an airspace, including classes that represent:
* The geometry of the airspace - Sectors, Volumes, Airways, Fixes, ...
* Aircraft, with properties such as location, heading, flight level, ...
* Predictors, to model how the aircraft parameters evolve with the simulation.
* Action, defining the schema by which agents can interact with the simulation.
* Infrastructure classes such as Simulator, ScenarioManagers, EventHandlers, logger, to allow the user to define and run simulated ATC scenarios.

## Getting started

### Installation

`bluebird-dt` is available on pypi, therefore it can be installed using

```bash
pip install bluebird-dt
```

or, if using [UV](https://docs.astral.sh/uv/), you can add it to your environment using
```bash
uv add bluebird-dt
```

### Making an agent

To run your first simulation, run the following script which issues a single instruction to an aircraft. 

```
from bluebird_dt.core import Action
from bluebird_dt.simulator.simulator import Simulator

# Use Simulator
sim = Simulator.from_category("Artificial", "I-Sector Two Aircraft")

# Evolve for 60 seconds, in 6 second radar sweeps
for _ in range(0, 10):
    sim.evolve(6)

# List all the aircraft in the airspace
print(sim.manager.environment.aircraft)

# Issue an action to one of the aircraft
sim.manager.receive_actions(
        [
            Action("AIR0", "change_flight_level_to", 200)
            ]
        )
```

### Running the digital twin as a server.

A FastApi app is available as `bluebird-api`, allowing the simulation to be run as a server, with the user (or an agent) interacting via a REST API. For information on this, see [GitHub](https://github.com/project-bluebird/BluebirdATC/blob/main/bluebird-api/README.md) or [Pypi](https://pypi.org/project/bluebird-api/).

## Documentation

The full documentation for the `bluebird-dt` package can be found at in [https://docs.projectbluebird.ai](https://docs.projectbluebird.ai)

<div align="center"><img src="../images/BB_logo.png" alt="ProjectBluebird"></div>

## Where logs are saved

When a simulation saves its logs (the per-run `.log` file and the replay `.tar.gz` archive), they are written to a per-user data directory rather than inside the installed package, so they are not lost when the virtual environment is rebuilt.

The location is resolved with [`platformdirs`](https://pypi.org/project/platformdirs/), a small cross-platform library that returns each operating system's conventional per-user data directory. The logs live under a `bluebird-scenario-logs/bluebird_dt` folder inside that directory:

| Platform | Default log location |
| --- | --- |
| Linux   | `~/.local/share/bluebird-scenario-logs/bluebird_dt` (or `$XDG_DATA_HOME/...`) |
| macOS   | `~/Library/Application Support/bluebird-scenario-logs/bluebird_dt` |
| Windows | `%LOCALAPPDATA%\bluebird-scenario-logs\bluebird_dt` |

To use a different location, set the `BLUEBIRD_LOG_DIR` environment variable before importing `bluebird_dt`; its value is used as the base directory instead of the platformdirs default.
