Introduction

Note

Currently, pygcam.mcs runs only on Unix-like platforms with the SLURM, PBS, or LSF job scheduling systems. See the Configuration page for more information.

Running a Monte Carlo simulation with pygcam involves the following steps:

  1. Configure ipyparallel for pygcam. The ippsetup sub-command handles this for the Slurm task scheduler. Support for PBS and LSF can be provided if users need this.
  2. Define parameters and distributions in the file parameters.xml.
  3. Define model results to save in the SQL database. These are defined in results.xml.
  4. Run the gensim sub-command to create the file structure and database required for the MCS and a CSV file containing the data for the Monte Carlo trials. Several sampling methods are available.
  5. Run the simulation by running the runsim sub-command. This runs “worker” tasks on compute nodes that receive information about which trials to run from the ipython-parallel scheduler. Results are passed back to the gcamtool and saved in a SQL database.
  6. Run the anaylze and/or the explore sub-commands to generate statistical information and various types of plots based on input values and results stored in the SQL database (analyze), and to interactively explore the parameter space (explore).

There are additional “utility” sub-commands for running shell commands on each trial sandbox, and other useful tools.

When an MCS trial runs, it:

  1. Reads the row of the generated CSV file corresponding to its trial number.
  2. Reads parameters.xml and runs the queries for each parameter to produce a sets of values.
  3. Modifies each set of values as per the parameter definition, i.e., by adding to, multiplying by, or replacing with the value drawn from the distribution for this trial. In the example above, the values returned by the query are multiplied by a value drawn from the Uniform distribution [0.5, 2].
  4. Writes the modified XML input files to the trial’s “sandbox” directory, and update the XML configuration for this scenario to load the modified file in place of the file previously indicated in the GCAM XML configuration file.

Sampling

The default sampling mode is Latin Hypercube sampling from the distributions defined in parameters.xml. Using the -m / --method argument to the gensim sub-command, you can use other alternatives provided via the SALib package, including:

  • The Method of Morris (-m morris),
  • Sobol sampling (-m sobol), and
  • Fourier Amplitude Sensitivity Test (-m fast).

Other methods can be added via custom plugins.

Note that when using the Morris, Sobol, or FAST methods, the corresponding sensitivity analysis method must be used to evaluate the results. This is accomplished by storing the choice of sampling method, optional arguments to the sampling method, and input data into a set of files within a directory “package” named data.sa in the run-time directory structure for the analysis. Invoking the analyze sub-command calls the appropriate sensitivity analysis method for the chosen sampling method.