The Digital Twin

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

pip install bluebird-dt

or, if using UV, you can add it to your environment using

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 or Pypi.

Documentation

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

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, 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:

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.