A python package for Command & control (C2) of Autonomous Random finite set- (RFS-) Based Swarms (CARBS) developed by the Laboratory for Autonomy, GNC, and Estimation Research (LAGER) at the University of Alabama (UA). This package was previously named CASER (Command control & information of Autonomous Swarms Employing Random finite sets), and before that GASUR (Guidance navigation and control of Autonomous Swarms Using Random finite sets) but neither had releases on PyPI. Some references may exist to those packages but they have been migrated to CARBS.

This project uses the pytest for developing and running the tests (with extensions for generating summary and coverage reports), tox automates setting up and running the test environment (as well as the documentation), Sphinx is used for documenting the code, and the Black formatter is used to auto format the python code. This project also follows semantic versioning where any api breaking changes will increment the major version number. Additionally, a prebuilt docker container image is provided to get started with developing for this library. It contains all of the needed tools to compile the code, run the tests, and build the documentation. The docker container can be used within VS Code through their dev container extension to allow editing local files but compiling using the toolchain provided within the container.

It is recommended to use VS Code with the dev containers extension for developing. Development containers allow the full toolchain to be automatically setup on most any machine capable of running Docker. For information on dev-containers see here for an overview, here for auto installing extensions in the container and here for an example setup. The provided dev container also has useful extensions installed to ease development.

To being, make sure VS Code and git are installed. Additionally, make sure docker is installed for your system (Windows, Mac, Linux). Next, install the dev containers extension within VS Code. Clone the repository locally on your computer, for windows it is recommended to clone it within your linux subsystem directory (e.g. a sub-directory of your linux home folder) to improve performance within the container (the linux directories on Windows can be accessed through the file browser by typing \\wsl$ in the address bar and clicking on your distro). Now open the repo folder within VS Code (for windows you may need to connect to the linux subsystem first). Then you should be prompted to open the folder in the container, click yes. If you are not prompted, you can go to the command palette and start typing "Open folder in container". Now your terminal within VS Code will be running commands within the container but the files your are editing/creating will be accessible from your local machine's file browser.

Note if you click the open in container button on the repo's page it will automatically open VS Code, open the container, and clone the repo for you. However, it will do this within a docker volume so the files are only accessible within the container (ie you can't view them through your local file browser).

Once the repository is open in the container, you can edit files, run tests, and make commits just like normal. For example, after editing some files and adding some validation tests to run these tests you would simply call the following from the root of the repository.

tox

This will attempt to run the all the validation tests, except those marked as slow, on multiple versions of python. If the python version can not be found, it will be skipped.

After running tests, it may be helpful to check the documentation build locally to ensure code comments are being pulled correctly. This can be done with

tox -e clean_docs
tox -e docs_html

to remove any existing documenation builds and generate the html version. The output is placed in docs/build/html and can be viewed by opening the docs/build/html/index.html file in your web browser.

Tox will automatically create virtual environements, install dependencies, install the package, and run some commands in the virtual environment. These are defined in the tox.ini file in the repository. If tox is called without specifying an envrionment, it will run all of the default environments. The available environments can be listed with

tox -av

and a specific environment run by calling

tox -e ENV

where ENV is replaced with the environment name. To pass positional arguments into the commands run within the tox environment you must use -- after the environment name but before the positional arguments. For example to run validation tests using Python 3.9 and pass the --runslow option to pytest you would call tox -e py39-validation_test -- --runslow.

Note, all tox commands must be run from the root of the repository because this is where the tox.ini file lives.

Please cite the CARBS using the following bibtex data,

@Misc{carbs,
    author       = {Jordan D. Larson and Ryan W. Thomas and Vaughn Weirens and Vincent W. Hill},
    howpublished = {Web page},
    title        = {{CARBS}: A {P}ython library for {C}ommand & control of {A}utonomous {R}andom finite set-{B}ased {S}warms},
    year         = {2023},
    url          = {https://github.com/drjdlarson/carbs},
}

For reference, the prior iteration of this package, named CASER was cited as follows,

@Misc{caser,
    author       = {Jordan D. Larson and Ryan W. Thomas and Vaughn Weirens and Vincent W. Hill},
    howpublished = {Web page},
    title        = {{CASER}: A {P}ython library for {C}ommand & control of {A}utonomous {S}warms {E}mploying {R}andom finite sets},
    year         = {2019},
    url          = {https://github.com/drjdlarson/caser},
}