This repository contains a set of Python tools for specifying and running semidefinite programs to compute upper and lower bounds on exit-time moments of stochastic dynamics. For details on the moment-based method for safety analysis, please refer to the paper [here](https://arxiv.org/abs/2104.04892).
## Getting started
## Setup
1. Install Python 3.8 (The code may work with other versions of Python, but 3.8 is recommended).
To make it easy for you to get started with GitLab, here's a list of recommended next steps.
2. Install the required python dependencies. If using conda, install each package in `requirements.txt` into your conda environment manually. If using pip, install the dependencies with the following command:
```
pip install -r requirements.txt
```
Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
3. Run the provided `setup_check.py` file to verify that all dependencies are correct and accessible by the toolkit.
## Add your files
-[ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-[ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
Models are specified using YAML files. Each model should contain the following:
-`solver` - String specifying the solver for the optimization program.
-[ ] [Set up project integrations](https://gitlab.engr.illinois.edu/peterdu2/sde_toolkit/-/settings/integrations)
-`state_dim` - Integer specifying the dimensionality of the state space.
## Collaborate with your team
-`brownian_motion_dim` - Integer specifying the dimensionality of the Brownian motion driving the stochastic dynamics.
-[ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-[ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-[ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
-[ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
-`state_vars` - List of strings that provide a unique identifier to each state dimension. Number of list members must match `state_dim`.
## Test and Deploy
-`initial_conditions` - List of floats specifying the initial condition of each state dimension. Number of list members must match `state_dim`.
Use the built-in continuous integration in GitLab.
-`safe set` - List of strings specifying the semialgebraic safe set. Each member is a polynomial consisting of monomial terms where each monomial contains a leading coefficient (float) and entries for all state dimensions (see `models/brownian_motion.yaml` for example).
-[ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-[ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-[ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-[ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-[ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
-`safe_set_boundary` - String specifying the boundary of the safe set. The polynomial consists of monomial terms where each monomial contains a leading coefficient (float) and entries for all state dimensions (see `models/brownian_motion.yaml` for example).
***
-`drift` - List of strings specifying polynomials for the deterministic drift dynamics of the SDE (see `models/brownian_motion.yaml` for example).
# Editing this README
-`diffusion` - List of strings specifying the polynomials for the diffusion dynamics of the SDE. Polynomials for each dimension of the Brownian motion are separated by a semicolon (see `models/brownian_motion.yaml` for example).
When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.
## Suggestions for a good README
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
### Creating a Runner
A runner file is required to parse the SDE models and create/run an optimization program. An example of a runner file is provided in `example_runner.py`. Before creating a runner you must have 1) a configuration YAML file, 2) a model YAML file.
## Name
Choose a self-explaining name for your project.
You may create your own runner by using the following guideline:
## Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
1. Instantiate an `SDEModel` object by using the `utils.model.SDEModel` class. You must pass a valid path to a model YAML file when creating the object.
## Badges
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
2. Instantiate an instance of `OptimizationProgram` by using the `utils.optimization.OptimizationProgram` class. This class takes an `SDEModel` and creates the optimization program. Once instantiated, the object can be used to generate all variables and constraints required for the semidefinite program using the following member functions:
-`create_mm_constraints()` - Create and return all moment matrix constraints
-`create_lm_constraints()` - Create and return all localizing matrix constraints
-`create_lm_eq_constraints()` - Create and return all localizing matrix scalar equality constraints
-`create_mt_constraints()` - Create and return linear evolution (martingale) constriants
## Visuals
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
3. Generate the optimization objective with `cvxpy` and create the problem object using `cvxpy.Problem` and constraints from step 2.
## Installation
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
For more details, refer to the `example_runner.py` script included in the repository. You may also run the script and see the optimization run for a Brownian motion example by using the following command:
## Usage
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
```
python example_runner.py
```
## Support
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
The output will be stored in a text file: `example_output.txt`.
## Roadmap
If you have ideas for releases in the future, it is a good idea to list them in the README.
## Contributing
State if you are open to contributions and what your requirements are for accepting them.
<!-- ## Citation
If you find the code or the paper useful for your research, please cite our paper:
```
@inproceedings{liu2020decentralized,
title={Decentralized Structural-RNN for Robot Crowd Navigation with Deep Reinforcement Learning},
author={Liu, Shuijing and Chang, Peixin and Liang, Weihang and Chakraborty, Neeloy and Driggs-Campbell, Katherine},
booktitle={IEEE International Conference on Robotics and Automation (ICRA)},
For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
Part of the code is based on the following repositories:
You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
[1] C. Chen, Y. Liu, S. Kreiss, and A. Alahi, “Crowd-robot interaction: Crowd-aware robot navigation with attention-based deep reinforcement learning,” in International Conference on Robotics and Automation (ICRA), 2019, pp. 6015–6022.
(Github: https://github.com/vita-epfl/CrowdNav)
## Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
[2] I. Kostrikov, “Pytorch implementations of reinforcement learning algorithms,” https://github.com/ikostrikov/pytorch-a2c-ppo-acktr-gail, 2018.
## License
For open source projects, say how it is licensed.
[3] A. Vemula, K. Muelling, and J. Oh, “Social attention: Modeling attention in human crowds,” in IEEE international Conference on Robotics and Automation (ICRA), 2018, pp. 1–7.
(Github: https://github.com/jeanoh/big)
## Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
## Contact
If you have any questions or find any bugs, please feel free to open an issue or pull request. -->
