Dependencies & Installation

List of dependencies
Essential dependencies
Optional dependencies
Installation

We will denote MATLAB’s command prompt by >>, while the system command prompt by $ .

Dependencies

External dependencies of SReachTools are:

MATLAB’s Statistics and Machine Learning Toolbox
MPT3 (https://www.mpt3.org/)
CVX (http://cvxr.com/cvx/)
MATLAB’s Global Optimization Toolbox (optional)
MATLAB’s Optimization Toolbox (optional)
GeoCalcLib (https://github.com/sreachtools/GeoCalcLib) (optional)
GUROBI (optional)
MOSEK (optional)

Essential dependencies

These dependencies are platform-independent, and have been tested in Windows, MacOS, and Linux.

MATLAB (>2017a) with MATLAB’s Statistics and Machine Learning Toolbox
MPT3 (https://www.mpt3.org/) — for polytopic computational geometry
1. Copy the MATLAB script install_mpt3.m provided by MPT3 from the browser to your local computer.
2. Download and install MPT3 by running the following command in MATLAB’s command prompt (after changing directory to the folder containing install_mpt3.m)
```
>> install_mpt3
```
3. Add cd <PATH-TO-TBXMANAGER>;tbxmanager restorepath to your MATLAB startup script for the MPT3 installation to persist across MATLAB runs.
CVX (http://cvxr.com/cvx/) — for parsing convex and mixed-integer programs. Use the Standard bundles, including Gurobi and/or MOSEK, even if you do not plan to use Gurobi or MOSEK. CVX does not require any additional licenses to work with GUROBI or MOSEK in an academic setting.
1. Download the zip file from http://cvxr.com/cvx/download/, and extract it to the cvx folder.
2. Install CVX by running the following command in MATLAB’s command prompt (after changing the current working directory to the cvx folder)
```
>> cvx_setup
```
3. Add cd <PATH-TO-CVX>;cvx_setup to your MATLAB startup script for the CVX installation to persist across MATLAB runs.
4. Other notes:
  - Detailed installation instructions are given in http://cvxr.com/cvx/download/.
  - SDPT3 (the default backend solver of CVX) performs reasonably well with CVX, when compared to MOSEK, and significantly poorly when compared to GUROBI in the tested examples and CVX v2.1 version. See Step 5 for instructions in installing external solvers for SReachTools.

Optional dependencies

These dependencies will allow non-essential features of SReachTools or enable superior performance.

MATLAB’s Global Optimization Toolbox and Optimization Toolbox
- Affects genzps-open options in SReachPoint and SReachSet computation.
GeoCalcLib — a MATLAB interface to Avis’s LRS vertex-facet enumeration library. In empirical tests, we found LRS to be a superior alternative to MPT’s preferred approach for vertex-facet enumeration, CDD.
- Affects lag-over and lag-under options in SReachSet computation.
- See https://github.com/sreachtools/GeoCalcLib for detailed installation instructions.
- GeoCalcLib currently works only in Unix and MAC OS.
External solvers — GUROBI and/or MOSEK.
1. Why do we need to install external solvers?
  - Mixed-integer programming enabled by GUROBI or MOSEK is required for particle-based approaches in SReachPoint.
    - Affects voronoi-open and particle-open options in SReachPoint computation.
  - External solvers are typically more numerically robust and computationally faster than free solvers like SDPT3 that come with CVX.
    - Affects overall computation speed and solution quality.
2. GUROBI (http://www.gurobi.com/): A backend solver for CVX that also enables mixed-integer programming associated with particle-based approaches, apart from convex programming. MPT3 + GUROBI also provides robust polyhedral computation. ( Currently facing issues).
  1. GUROBI offers free academic license, which can be requested at http://www.gurobi.com/registration/download-reg.
  2. MPT3 + GUROBI: Requires the external installation.
    1. Obtain a copy of GUROBI Optimizer from http://www.gurobi.com/ (Requires signing up)
    2. Unzip the installation to desired folder.
    3. Generate the license file by running the following command in the Unix command prompt (after changing the current working directory to the <PATH-TO-GUROBI-HOME>/gurobi902/<OS>/bin/)
      $ grbgetkey OUTPUT_OF_GUROBI_LICENSE_REQUEST
    4. Setup GUROBI by running the following command in MATLAB’s command prompt (after changing the current working directory to <PATH-TO-GUROBI-HOME>/gurobi902/<OS>/matlab/)
      >> gurobi_setup
    5. Add GRB_LICENSE_FILE environment variable that has the location of the gurobi.lic file for MPT3 to detect GUROBI. Alternatively, add the following command in startup.m
      >> setenv('GRB_LICENSE_FILE','/home/ubuntu/gurobi.lic')
    6. Update MPT3 with GUROBI by running the following command in MATLAB’s command prompt
      >> mpt_init
  3. CVX + GUROBI: The current build of CVX v2.2 does not play well with GUROBI v9.0.2. ( Currently facing issues)
    - Previously, CVX v2.1 worked with GUROBI v7.5.2 successfully. We will update these instructions once CVX + GUROBI becomes a viable option again.
    - See the following CVX forum posts for more details:
      1. http://ask.cvxr.com/t/cvx-with-gurobi-error-warning/7072
      2. http://ask.cvxr.com/t/mismangement-of-matlab-path-in-cvxv2-2-and-external-gurobi-v9-0-2/7346/3
    - We found CVX + GUROBI to be faster than SDPT3 and MOSEK
3. MOSEK (https://www.mosek.com/): A backend solver for CVX that also enables mixed-integer programming associated with particle-based approaches, apart from convex programming.
  1. MOSEK offers free academic license, which can be requested at https://www.mosek.com/license/request/.
  2. CVX + MOSEK:
    1. Save the license file obtained via email in your home folder in a folder named mosek. See https://docs.mosek.com/9.2/licensing/quickstart.html for more details.
    2. To enable MOSEK bundled with CVX, run the following command in MATLAB command prompt
      >> cvx_setup
    3. See http://web.cvxr.com/cvx/doc/mosek.html for more details.
  3. MPT3 + MOSEK: Unfortunately, MPT3 does not support MOSEK. See https://www.mpt3.org/Main/FAQ.
  4. In empirical tests, SDPT3 and MOSEK have demonstrated similar performance in computation time and solution quality. We found MOSEK to be slower than GUROBI.

Installation

Install the necessary dependencies listed above
Clone the SReachTools repository (or download the latest zip file from Releases)
```
$ git clone https://github.com/sreachtools/SReachTools
```
Please do not add the folder to the MATLAB path manually.
Install SReachTools by running the following command in MATLAB command prompt (after changing the current working directory in MATLAB to SReachTools folder)
```
>> srtinit
```
- (Optional) Additional steps:
  - Run srtinit -t to run all the unit tests.
  - Run srtinit -v to visualize the steps the changes to the path and check for recommended dependencies.
  - Run srtinit -x to remove functions of SReachTools from MATLAB’s path after use.
You can add cd <PATH-TO-SREACHTOOLS>;srtinit to your MATLAB’s startup.m to automatically have this done in future.

Go to top