Analysis code to generate figures and artifacts presented in Smith and Chapman, “On Exponential Utility and Conditional Value-at-Risk as Risk-Averse Performance Criteria,” submitted to IEEE Transactions on Control Systems Technology, August 2021.
We have tested this repository on Windows 10 and Red Hat Enterprise Linux Server release 7.8 using the various dependencies listed below.
Running the code in this repository requires a recent version of Matlab as well as the Statistics and Machine Learning Toolbox and the Parallel Computing Toolbox.
We used:
- Matlab 2019b
- Parallel Computing Toolbox version 7.1
- Statistics and Machine Learning Toolbox version 11.6
Access to Wolfram Mathematica is optional. We present an example of a skewnormal distribution in the paper. A Mathematica notebook presents this derivation in detail and produces several .mat files that are included in this repository (but that can be re-produced if you have access to Mathematica). The Mathematica notebook (.nb), an accompanying Matlab analysis file (.m), and the artifacts generated by Mathematica (.mat) can be found in misc/skewnormal_example/.
We used Mathematica 12.3.
Using git is the easiest way to download a copy of all the files you need to get up and running in Matlab. We tested these instructions against git v2.30.0.windows.2.
The files will be downloaded to a folder named IEEE-TCST-2021.
From a command line interface, navigate to the directory where you would like to download IEEE-TCST-2021.
Then execute the following command:
git clone https://github.com/risk-sensitive-reachability/IEEE-TCST-2021
To setup your Matlab workspace:
- navigate to the parent directory containing IEEE-TCST-2021
- from the left-hand file tree, right click on IEEE-TCST-2021 and select Add To Path > Selected Folders and Subfolders.
The first major step in the analysis of a particular configuration and scenario combination is to call Run_Recursion. The first argument is a string identifying the scenario to run and the second argument is an integer identifying the simulator configuration to use. See the computational prerequisites column in the list of figures at the bottom of this page for examples. Note that running this will create files in the {Matlab_Working_Directory}/staging/ directory. These include both 'checkpoint' files that save results periodically and 'complete' files that are created once the entire recursion is finished. Once you have obtained a 'Transform_complete.mat' file you may run the Monte Carlo analysis.
Note: this process can take a long time to complete, so operations are performed in parallel by default. A parallel pool will be started if none is already active. If you want to run the analysis using a limited number of cores, run parpool('local', number_of_cores) prior to starting this analysis.
The second step in the analysis of a particular configuration and scenario combination is to call Plot_Tradeoffs. This assumes you have already called Run_Recursion and that process completed by producing a 'Transform_complete.mat' file. The first argument to Plot_Tradeoffs is a string identifying the scenario to run and the second argument is an integer identifying the simulator configuration to use. An optional third parameter specifies the initial condition; otherwise, default initial conditions will be run. Note that Plot_Tradeoffs will look for Monte Carlo results and use those if they are available. Otherwise, it will compute 10 million sample trajectories, which will take some time. You can speed up the workflow by running parts of it on multiple machines (i.e., by using the third parameter to constrain the analysis to a single initial condition per machine). See the computational prerequisites column in the list of figures at the bottom of this page for examples. Note that running this will create files in the {Matlab_Working_Directory}/staging/ directory.
Note: this process can take a long time to complete, so operations are performed in parallel by default. A parallel pool will be started if none is already active. If you want to run the analysis using a limited number of cores, run parpool('local', number_of_cores) prior to starting this analysis.
There are several methods available to visualize the results of the above steps.
The Plot_Disturbance_Pofile method takes only a single string argument identifying the scenario. It then plots the probability distribution associated with the disturbances for that scenario.
The Plot_Stormwater_System_Computational_Grid takes two arguments. The first argument to Plot_Stormwater_System_Computational_Grid is a string identifying the scenario to run and the second argument is an integer identifying the simulator configuration to use. This method plots the 2D computational grid of real states relevant to the stormwater system for the given scenario and configuration.
The Plot_Stormwater_System_Stage_Discharge_Curves takes two arguments. The first argument to Plot_Stormwater_System_Stage_Discharge_Curves is a string identifying the scenario to run and the second argument is an integer identifying the simulator configuration to use. This method plots stage (i.e., water elevation) to discharge relationships for the stormwater system for the given scenario and configuration.
Plot_Figure generates the plots shown in a particular figure in this paper and saves them to the IEEE-TCST-2021/figures directory. Plot_Figure takes a single argument specifying the figure number from the paper (e.g., Plot_Figure(3)). When called, the Plot_Figure method will try to fulfill the computational dependencies of each figure if they do not yet exist. For speed, the listed prerequisites can be run on separate machines, with the caveat that all calls to Plot_Tradeoffs depend on results from the corresponding Run_Recursion call.
The convenience method Generate_Figures() will generate all figures. This will take a long time if computational prerequisites are not yet fulfilled. However, if Generate_Figures is interrupted during this process, it will pick up where it left off and will not attempt to generate any computational prerequisites that are already satisfied.
| Figure | Command | Computational Prerequisites |
|---|---|---|
| 1 | Plot_Figure(1); | none |
| 2 | Plot_Figure(2); | none |
| 3 | Plot_Figure(3); | none |
| 4 | Plot_Figure(4); | none |
| 5 | Plot_Figure(5); | none |
| 6 | Plot_Figure(6); | none |
| 7 | Plot_Figure(7); | Run_Recursion('ATRS',0); Plot_Tradeoffs('ATRS',0,19.8); Plot_Tradeoffs('ATRS',0,20); Plot_Tradeoffs('ATRS',0,20.5); Plot_Tradeoffs('ATRS',0,21); Plot_Tradeoffs('ATRS',0,21.2); |
| 8 | Plot_Figure(8); | Run_Recursion('ETRS',0); Plot_Tradeoffs('ETRS',0,19.8); Plot_Tradeoffs('ETRS',0,20); Plot_Tradeoffs('ETRS',0,20.5); Plot_Tradeoffs('ETRS',0,21); Plot_Tradeoffs('ETRS',0,21.2); Run_Recursion('ETRS',6); Plot_Tradeoffs('ETRS',6,20.5); Plot_Tradeoffs('ETRS',6,21); Plot_Tradeoffs('ETRS',6,21.2); |
| 9 | Plot_Figure(9); | Run_Recursion('EPRS',5); Plot_Tradeoffs('EPRS',5,19.8); Plot_Tradeoffs('EPRS',5,20); Plot_Tradeoffs('EPRS',5,20.5); Plot_Tradeoffs('EPRS',5,21); Plot_Tradeoffs('EPRS',5,21.2); |
| 10 | Plot_Figure(10); | Run_Recursion('QTGS',3); Plot_Tradeoffs('QTGS',3,19.8); Plot_Tradeoffs('QTGS',3,20); Plot_Tradeoffs('QTGS',3,20.5); Plot_Tradeoffs('QTGS',3,21); Plot_Tradeoffs('QTGS',3,21.2); |
| 11 | Plot_Figure(11); | Run_Recursion('EWRS',1); Plot_Tradeoffs('EWRS',1,[2 2]); Plot_Tradeoffs('EWRS',1,[2.3 2.3]); Plot_Tradeoffs('EWRS',1,[3 4]); Plot_Tradeoffs('EWRS',1,[2 5.5]); Plot_Tradeoffs('EWRS',1,[2 5]); |
| 12 | Plot_Figure(12); | Run_Recursion('AWRS',1); Plot_Tradeoffs('AWRS',1,[2 2]); Plot_Tradeoffs('AWRS',1,[2.3 2.3]); Plot_Tradeoffs('AWRS',1,[3 4]); Plot_Tradeoffs('AWRS',1,[2 5.5]); Plot_Tradeoffs('AWRS',1,[2 5]); |
| 13 | Plot_Figure(13); | Run_Recursion('AWRS',1); Run_Recursion('EWRS',1); |