run-time-assurance 1.18.5

The run-time-assurance library provides an interface and implementations for Run Time Assurance (RTA) safety filters.

Run Time Assurance

Intro

The run-time-assurance library provides an interface and implementations for Run Time Assurance (RTA) safety filters. RTA is a technique for guaranteeing the safety of a control system by performing online safety filtering of desired control actions to ensure the control system does not and will not violate defined safety constraints. This allows an unverified controller, such as a neural network, to be utilized in safety critical applications.

This package contains base classes for implementing RTA modules and defining RTA safety constraints. Also included are generic implementations of the RTA algorithms Explicit Simplex, Implicit Simplex, Explicit Acitive Set Invariance Filter (ASIF), and Implicit ASIF which simply require contraints and control system state transition models to become functional RTA modules for any custom application. Additionally, the RTA Zoo includes our growing library of custom RTA implementations for various safety critical control problems.

Docs

Library documentation and api reference located at https://rta.github.com/act3-ace/safe-autonomy-stack/run-time-assurance/

Installation

The following instructions detail how to install the run-time-assurance library on your local system. It is recommended to install the python modules within a virtualenv or conda environment. run-time-assurance utilizes Poetry to handle installation. Poetry can install run-time-assurance into an auto-generated virtualenv or within the currently active environment.

Installing run-time-assurance

Clone a copy of the run-time-assurance source code onto your local machine via SSH:

git clone [e-mail]:act3-ace/run-time-assurance.git

or HTTPS:

git clone [e-mail]:act3-ace/run-time-assurance.git

You can install the run-time-assurance module using either pip or poetry.

Installing run-time-assurance with pip

To install the run-time-assurance module into your environment using pip:

cd run-time-assurance
pip install .

For a local development version, please install using the -e, --editable option:

pip install -e .

Installing run-time-assurance with Poetry

To install the run-time-assurance module into your environment using poetry:

cd run-time-assurance
poetry install

Poetry will handle installing appropriate versions of the dependencies for run-time-assurance into your environment, if they aren't already installed. Poetry will install an editable version of run-time-assurance to the environment.

Build Docs Locally

First make sure the mkdocs requirements are installed

poetry install --with docs

Now, build the documentation and serve it locally. By default, you should be able to reach the docs on your local web browser at 127.0.0.1:8000

rm -r site
poetry run mkdocs build
cp -r docs/. site/
poetry run mkdocs serve

Tutorial

A Jupyter Notebook tutorial discussing how to build RTA modules is given at run-time-assurance/tutorials/Double_Integrator_Tutorial.ipynb.

Citation

The paper associated with this repository was presented at the 2023 American Control Conference, and can be cited with the following bibtex entry:

@inproceedings{ravaioli2023universal,
  title={A Universal Framework for Generalized Run Time Assurance with JAX Automatic Differentiation},
  author={Ravaioli, Umberto J and Dunlap, Kyle and Hobbs, Kerianne},
  booktitle={2023 American Control Conference (ACC)},
  pages={4264--4269},
  year={2023},
  organization={IEEE}
}

Public Release

Approved for public release; distribution is unlimited. Case Number: AFRL-2023-6154

A prior version of this repository was approved for public release. Case Number: AFRL-2022-3202

Team

Umberto Ravaioli, Kyle Dunlap, Jamie Cunningham, John McCarroll, Kerianne Hobbs, Charles Keating