hkust-octad-lab / airtrafficsim Goto Github PK

Web-based air traffic simulation and visualization platform for ATM research.

Home Page: https://hkust-octad-lab.github.io/AirTrafficSim/

License: GNU General Public License v3.0

JavaScript 0.03% HTML 0.32% CSS 2.39% TypeScript 14.37% Python 82.89%

air-transport simulation aviation atm utm

airtrafficsim's Introduction

AirTrafficSim is a web-based air traffic simulation software written in Python and javascript. It is designed to visualize historical and simulated flight data and perform microscopic studies of air traffic movement with the integration of a historical weather database. It aims to assist users to evaluate the performance of ATM algorithms.

Features

Replay historical flights with user-provided data (e.g. from FlightRadar 24)
Air traffic simulation using BADA 3.15 performance data and OpenAP
Navigation data simulation and visualization from x-plane 11
Autopilot and Flight Management System simulation
ATC commands (e.g. holding, vectoring, and direct to) simulation
Simulation and visualisation with weather data from ECMWF ERA5 and custom radar image (HKO 256km radar images)
Aircraft is controlled with an API interface to simulate ATC interaction

Credits

If you find AirTrafficSim useful for your research, please cite the following:

@article{Hui2023,
  title = {AirTrafficSim: An open-source web-based air traffic simulation platform.}, 
  author = {Ka Yiu Hui and Chris Hc. Nguyen and Go Nam Lui and Rhea P. Liem}, 
  journal = {Journal of Open Source Software},
  publisher = {The Open Journal}, 
  year = {2023}, 
  volume = {8}, 
  number = {86}, 
  pages = {4916},
  doi = {10.21105/joss.04916}, 
  url = {https://doi.org/10.21105/joss.04916}
}

Installation

Linux or WSL on window is recommended for AirTrafficSim. The latest stable release of AirTrafficSim can be installed from conda-forge. All dependencies will be installed automatically with the web client pre-built and ready for use directly after installation.

It is recommended to install AirTrafficSim in a new conda environment:

conda create -n airtrafficsim -c conda-forge airtrafficsim

Then, please initialise AirTrafficSim by specifying a folder path to create a symbolic link to the airtrafficsim_data folder:

conda activate airtrafficsim
airtrafficsim --init <path to a folder>

This will alow you to provide or retrieve any data and create simulation environments to AirTrafficSim through this folder alias. Please visit the documentation for more information.

After installation, please also download, unzip, and store BADA 3.15 data files in airtrafficsim_data/performance/BADA. In addition, follow this guide to set up the API key for the weather database from ECMWF Climate Data Store.

Running AirTrafficSim

You can run AirTrafficSim by executing the following commands. Please be reminded to activate the conda environment when you use AirTrafficSim.

conda activate airtrafficsim
airtrafficsim

AirTrafficSim uses port 6111 for communication. Please open or forward the port accordingly if needed. You should be able to open the UI using any modern browser at http://localhost:6111. You may also check the console for any messages when using AirTrafficSim.

You can also run AirTrafficSim without the UI by providing the name of the simulation environment which is listed in environment. The environment name should be identical to the file name.

conda activate airtrafficsim
airtrafficsim --headless <environment name>

Documentation

The detailed documentation for AirTrafficSim is available at https://hkust-octad-lab.github.io/AirTrafficSim/, which includes tutorials on UI navigation and project structure as well as running different simulation environment.

Contribution

AirTrafficSim is under active development. We welcome everyone interested to contribute to the project and make AirTrafficSim more feature-rich. Please feel free to visit the detailed contribution guide in this repository or the documentation.

airtrafficsim's People

Contributors

Stargazers

Watchers

Forkers

kyfrankie ursa-inc harrylui1995 paveenju ajaneshwara cathaypacific8747

airtrafficsim's Issues

Adjustable simulation timestep

Add a simulation variable delta_t to enable adjustable timestep in simulation. Right now, each timestep is defaulting to 1 second.

New performance model: OpenAP

Implement more performance models, especially the open-source OpenAP model. Suggestions and contributions are welcomed for adding new performance models, including drones and UAM models.

Docstring completeness and format

The docstrings format is somewhat inconsistent across the code. It would be good to stick to one format.

Also, some functions lack a doctring or have one which does not give much information. This could be improved to help contributions and future maintenance.

Part of JOSS review here

VNAV and Top of Descent

Right now, VNAV and top of descent are not implemented. It is important to add these functions to enable AirTrafficSim to achieve full-flight simulation. Feel free to propose methodologies here!

UI rework

To update the client-side code for better code packaging and UI/UX.

Code update

Remove Resium dependencies
Update Cesium.js to newest version
Improve code structure with React.FC

UI update

Update setting box
Improve imagery layer selection
Improve default Mapbox map loading time

Suggestions are welcomed!

Clarify statement in paper

The following sentence was unclear to me while reading the article/paper submitted to JOSS:
"It can also control the aircraft based on the target state inputted by the user and algorithm to simulate ATC command". Could you elaborate on this in the paper or in the documentation?

Part of JOSS review here

Bada 3.15 files - what to download?

The instructions and documentation tell the user to download and unzip the Bada 3.15 files.

In the EuroControl site there are over 160 files associated with my Bada 3 license. It is unclear which file(s) need to be downloaded and unzipped.

I believe the base file is: Release Files | 3.15 | 24 June 2019 | 1.39 MB

But then there are monthly files for every month since June 2019. Do all of those need to be downloaded and installed as well?

Add contribution guidelines in main folder

It would be good to add a contribution guide document at the top level of the repo, to summarise what process the users should follow when proposing changes, adding issues, code etc. Example here.

Part of JOSS review here

Using a negative longitude in DemoEnv.py throws an error.

If I modify DemoEnv.py as follows:

self.aircraft_head = Aircraft(self.traffic, call_sign="GHOST", aircraft_type="C25C", flight_phase=FlightPhase.CRUISE, configuration=Config.CLEAN, lat=43.223267, long=71.631273, alt=5000.0, heading=175.0, cas=250.0, fuel_weight=10000.0, payload_weight=12000.0)

Then the simulation runs as expected.

If I try to place the aircraft at Concord, NH, USA using the following code:

self.aircraft_head = Aircraft(self.traffic, call_sign="GHOST", aircraft_type="C25C", flight_phase=FlightPhase.CRUISE, configuration=Config.CLEAN, lat=43.223267, long=-71.631273, alt=5000.0, heading=175.0, cas=250.0, fuel_weight=10000.0, payload_weight=12000.0)

Then the simulation fails with the following:

emitting event "loadingMsg" to all [/] ERA5 data exists. Traffic.py - add_aircraft() GHOST Type: C25C Traffic.py - add_aircraft() FOLLOW Type: A20N emitting event "simulationEnvironment" to all [/] Exception in thread Thread-7 (_handle_event_internal): Traceback (most recent call last): File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/threading.py", line 1038, in _bootstrap_inner self.run() File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/threading.py", line 975, in run self._target(*self._args, **self._kwargs) File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/socketio/server.py", line 733, in _handle_event_internal r = server._trigger_event(data[0], namespace, sid, *data[1:]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/socketio/server.py", line 758, in _trigger_event return self.handlers[namespace][event](*args) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/flask_socketio/__init__.py", line 282, in _handler return self._handle_event(handler, message, namespace, sid, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/flask_socketio/__init__.py", line 828, in _handle_event ret = handler(*args) ^^^^^^^^^^^^^^ File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/airtrafficsim/server/server.py", line 153, in run_simulation env.run(socketio) File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/airtrafficsim/core/environment.py", line 134, in run self.step(socketio) File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/airtrafficsim/core/environment.py", line 81, in step self.traffic.update(self.global_time) File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/airtrafficsim/core/traffic.py", line 262, in update self.weather.update(self.lat, self.long, self.alt, File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/airtrafficsim/core/weather/weather.py", line 124, in update ds = self.weather_data.sel(longitude=xr.DataArray(long, dims="points"), latitude=xr.DataArray(lat, dims="points"), time=np.datetime64( ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/xarray/core/dataset.py", line 2642, in sel query_results = map_index_queries( ^^^^^^^^^^^^^^^^^^ File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/xarray/core/indexing.py", line 190, in map_index_queries results.append(index.sel(labels, **options)) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/opt/homebrew/Caskroom/miniforge/base/envs/airtrafficsim/lib/python3.11/site-packages/xarray/core/indexes.py", line 498, in sel raise KeyError(f"not all values found in index {coord_name!r}") KeyError: "not all values found in index 'longitude'"

The only difference between the two is the negative sign on the longitude.

Instructions on how to add BADA data

The installation instructions should go through the steps needed to add BADA data or some alternative. At the moment this is only discussed in the docs. As mentioned by the other reviewer I was able to run with BADA data because I have a license but other users might be confused and not be able to run the software.

Part of JOSS review here

Simulation button in UI fails to load data

I installed locally and was able to see the UI and use it in replay mode. But when I click on the "Simulate" button in the bottom of the screen and select a scenario, it loads forever and does not show anything. Note that when I click replay and then select "Simulation" from the box that opens, I can run those scenarios.

This should be fixed or fail more gracefully if there is a reason (e.g. missing data files)

Part of JOSS review here

hkust-octad-lab / airtrafficsim Goto Github PK

airtrafficsim's Introduction

Features

Credits

Installation

Running AirTrafficSim

Documentation

Contribution

airtrafficsim's People

Contributors

Stargazers

Watchers

Forkers

airtrafficsim's Issues

Code update

UI update

Recommend Projects

Recommend Topics

Recommend Org