pyCASX – A Python implementation of ACAS X_A and ACAS X_U for Flightgear

Implementation of ACAS X_A and ACAS X_U with neural networks for FlightGear.

• Description
• Installation
  • Requirements
  • Users
    • Installation via pipx
    • Installation via pip
  • Development
  • pre-commit
  • VS Code
• Usage
  • Launching ACAS X
  • Other options
    • onnx or make_onnx
    • launch
    • acasx
  • Overwriting parameters
• Citation

Description

Implementation of Horizontal- and VerticalCAS using neural networks for FlightGear. The HCAS and VCAS implementations are based upon Stanford Intelligent Systems Laboratory's HorizontalCAS and VerticalCAS.

Installation

Please read the following sections carefully. Please also see the documentation at https://pycasx.readthedocs.io.

Requirements

• Python 3.8 or higher (3.12 is currently not supported)
• FlightGear 2020.3.18 or higher

Users

If you only want to use pycasx as a command-line tool and not develop it, you can install it via pip or pipx. However, pipx is recommended, as it will install the package in an isolated environment and thus not interfere with other packages.

Installation via pipx

Ensure you have pipx installed. If not, install it via

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Afterwards, install pycasx via

pipx install git+https://https://github.com/DLR-KI/pycasx.git

Installation via pip

This is not recommended! Proceed at your own risk! For just using the package, pipx is recommended

First, clone the repository

git clone https://https://github.com/DLR-KI/pycasx.git

Optional: create yourself a virtual environment and activate it.

pip install virtualenv
virtualenv .pycasx-venv
source .pycasx-venv/bin/activate

Now, install the package via

pip install -e .

for basic features.

NOTE: for some virtual environments, especially with Windows, you might need to use python instead of python3 and might also need to use python -m pip instead of pip.

Development

First, clone the repository into a directory of your choice:

git clone https://https://github.com/DLR-KI/pycasx.git

Then, it is recommended to create a virtual environment for the software:

pip install virtualenv
virtualenv .pycasx-venv
source .pycasx-venv/bin/activate

Afterwards, install the software and its dependencies:

pip install -e '.[all]'

Next, install the provided pre-commit hooks:

pre-commit install

pre-commit

Prior to any commit, the hooks defined in .pre-commit-config.yaml will be ran. A failure in any hook will block the commit. Although, most of the errors, like formatting, will correct themselves. You just have to re-add all changed files and commit again. Be also aware, that the pipeline can take a few seconds to complete.

Alternatively, you can run the pipeline at any time to invoke changes before they block commits with

pre-commit run --all-files

Running the pre-commit pipeline manually once before the first commit is recommended. It will install all required tools and dependencies and you'll see what's going on. Otherwise you might be surprised why committing takes so long.

VS Code

For VS Code, we provide a set of recommended extensions. Please install them to smooth the development process. You'll find them in your extensions tab under the Workspace Recommendations section.

Usage

This package provides a command-line interface with the pycasx command. General information is available via pycasx [-h|--help] and the current version via pycasx [-v|--version]. All other commands are explained in the following.

Launching ACAS X

You can launch FlightGear via

pycasx launch

Once FlightGear is up and running, just run:

pycasx acasx

This will start the ACAS X with the default settings.

Other options

onnx or make_onnx

pycasx onnx

Convert the provided .nnet files into .onnx files. This is required if one wants to use the ONNX or PyTorch backend. BE WARNED: BOTH THE ONNX AND PYTORCH BACKEND ARE EXPERIMENTAL AND NOT FULLY TESTED. THE RESULTING ADVISORIES ARE NOT VALID!

launch

pycasx launch

Launch FlightGear with options defined in pycasx/cli/launch.py.

acasx

pycasx acasx

Runs the ACAS X with the default settings. This includes the API backend to fetch the advisories via REST calls. Please see the official documentation for more information.

Overwriting parameters

Every launch script has a set of default parameters. Those are handled via Hydra. Accordingly, overwriting parameters can be achieved by following the Hydra documentation.

Nevertheless, overwriting (or adding) new default properties for pycasx launch is not as straight forward as one might try. The correct syntax to overwrite (or add) a default property is

pycasx launch ++prop='{/autopilot/settings/target-speed-kt: 123456789}'

Citation

If you found our work useful, please cite our paper:

@InProceedings{Christensen2024,
  author    = {Christensen, Johann Maximilian and Anilkumar Girija, Akshay and Stefani, Thomas and Durak, Umut and Hoemann, Elena and K{\"{o}}ster, Frank and Kr{\"{u}}ger, Thomas and Hallerbach, Sven},
  booktitle = {36th {IEEE} International Conference on Tools with Artificial Intelligence ({ICTAI})},
  date      = {2024-10},
  title     = {Advancing the AI-Based Realization of ACAS X Towards Real-World Application},
}