Package: carbs
CARBSA 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.Table of ContentsDevelopment Environment SetupExample WorkflowNotes on toxThis 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 followssemantic versioningwhere 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.Development Environment SetupIt 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 seeherefor an overview,herefor auto installing extensions in the container
andherefor 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).Example WorkflowOnce 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.toxThis 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 withtox -e clean_docs
tox -e docs_htmlto remove any existing documenation builds and generate the html version. The output is placed indocs/build/htmland can be viewed by opening thedocs/build/html/index.htmlfile in your web browser.Notes on toxTox will automatically create virtual environements, install dependencies, install the package, and run some commands in the virtual environment. These are defined in thetox.inifile 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 withtox -avand a specific environment run by callingtox -e ENVwhereENVis 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--runslowoption to pytest you would calltox -e py39-validation_test -- --runslow.Note, all tox commands must be run from the root of the repository because this is where thetox.inifile lives.CitePlease 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},}