rOpenscmRunner

Introduction

Using rOpenscmRunner, you can simulate the climate response to emissions. To do this, it uses the python package openscm-runner. This makes it possible to run several simple climate models using a unified interface. At the moment, the models FaIR, MAGICC, and Cicero-SCM are supported by openscm-runner, and therefore usable from rOpenscmRunner.

openscm-runner only supports emissions-driven runs. This means that you provide an emissions scenario specifying the emissions of forcing agents over time, choose which model(s) you want to run with which configuration(s) and which outputs you are interested in, and hand this all over to rOpenscmRunner and you will get back the simulated climate response(s), e.g. temperatures. The available response variables depend on the chosen model and configuration.

Installation

For installation of rOpenscmRunner an additional repository has to be added in R:

options(repos = c(CRAN = "@CRAN@", pik = "https://rse.pik-potsdam.de/r/packages"))

The additional repository can be made available permanently by adding the line above to a file called .Rprofile stored in the home folder of your system (Sys.glob("~") in R returns the home directory).

After that the most recent version of the package can be installed using install.packages:

install.packages("rOpenscmRunner")

Additionally, you will need a Python installation and the openscm-runner Python package installed, as well as some climate models. If you don’t have a Python installation so far, you can find one at anaconda. Use the package management of your Python distribution to install openscm-runner. You can then specify which simple climate models you want to also install. If you use pip, choose what you need and run from the command line:

$ pip install --user openscm-runner[fair]  # openscm-runner and everything needed to run the model FaIR
$ pip install --user openscm-runner[magicc]  # openscm-runner and everything needed to integrate with the model MAGICC
$ pip install --user openscm-runner[models]  # openscm-runner and all available models

If you are using conda instead of pip, or want to know further details about the installation, check the openscm-runner installation documentation.

If you want to run the MAGICC model, you also have to install it. Download the most recent version from magicc.org. Extract it to a location suitable to you, and copy the default configuration from the run/defaults/ folder into the run/ folder.

Setup

FaIR and Cicero-SCM are installed via the Python package management or included in openscm-runner, so it knows where to find them. However, MAGICC is installed separately, so you have to tell rOpenscmRunner where to find it using the rOpenscmRunner::setup function. Additionally, you have to also provide a path to a folder where MAGICC can store temporary files:

rOpenscmRunner::setup(magiccExecutable7 = "/path/to/magicc/bin/magicc",  # nolint: absolute_path_linter
                      magiccWorkerRootDir = "/path/to/temp/folder")  # nolint: absolute_path_linter

If you are on windows, you have to give the full path to the magicc.exe file in the MAGICC installation in the bin/ folder. On Linux, give the full path to the magicc file in the bin/ folder in the MAGICC installation. The temporary folder must not be inside the magicc folder where the magiccExecutable7 is. You can simply use R’s standard temporary folder like this:

rOpenscmRunner::setup(magiccWorkerRootDir = tempdir())

Using the same mechanism, you can also configure other parts of the MAGICC integration, but they are not required:

rOpenscmRunner::setup(magiccWorkerNumber = 4)

The default for the number of workers is to use as many workers as there are processors in your system. This should be a sensible default on laptops and workstations, but probably needs manual setup on shared machines like compute clusters.

All settings supplied via rOpenscmRunner::setup() are remembered for the duration of your current R session. If you don’t want to call rOpenscmRunner::setup() in each session, you can also supply these settings via environment variables, check the documentation of rOpenscmRunner::setup() for details.

Usage

To run simple climate model(s), use the rOpenscmRunner::run() function. It takes the emission scenario(s) as a data.frame in a format like the IAMC format for scenarios. In particular, it is a data.frame where each row is a time series and the columns are model for the model that produced the emissions scenario, scenario for a name of the scenario, region for the area (most likely, World for simple climate models), and variable and unit to specify what is in the timeseries. The remaining columns are the time points, most likely years. An example for a very short and incomplete emissions scenario would be:

# create very minimal emissions scenario.
df <- data.frame(
  model = c("rand", "rand"),
  scenario = c("weirdEMI", "weirdEMI"),
  region = c("World", "World"),
  variable = c("Emissions|CO2", "Emissions|CH4"),
  unit = c("Mt CO2 / yr", "Mt CH4 / yr"),
  "2015" = c(9., 12.),
  "2020" = c(10., 11.),
  check.names = FALSE
)
df
#>   model scenario region      variable        unit 2015 2020
#> 1  rand weirdEMI  World Emissions|CO2 Mt CO2 / yr    9   10
#> 2  rand weirdEMI  World Emissions|CH4 Mt CH4 / yr   12   11

Note the usage of check.names = FALSE to be able to use years as column names.

With the rOpenscmRunner::run() function, you can then simulate all scenarios in the data frame at once:

# simulate the scenario(s) using MAGICC7 with default settings.
result <- rOpenscmRunner::run(climateModelsConfigs = list("MAGICC7" = NULL), scenarios = df)

You will then find the simulated climate scenario in the same format as the input scenarios in result$df and any metadata generated by the climate model in result$metadata. Note that if you run these examples as-is, you will get a lot of warnings and errors from MAGICC because the example emissions scenario is so incomplete. For serious work, you will obviously need a complete emissions scenario.

You can also change configuration values in the models or even run multiple configurations at once and request other outputs from the model(s). As an example, we simulate the surface temperature and sea level rise using MAGICC with two different non-standard climate sensitivity settings. Note that we have to include CORE_CLIMATESENSITIVITY in outConfig so that we can distinguish the runs in the result data frame.

# output sea level rise and surface temperature for two different climate sensitivity settings.
res <- rOpenscmRunner::run(
  climateModelsConfigs = list("MAGICC7" = list(list("CORE_CLIMATESENSITIVITY" = 3.),
                                               list("CORE_CLIMATESENSITIVITY" = 4.))),
  scenarios = df,
  outConfig = list("MAGICC7" = list("CORE_CLIMATESENSITIVITY")),
  outputVariables = list("Surface Temperature", "Sea Level Rise")
)

The available configuration settings depend on the climate model and have to be looked up in the respective documentation. The names of outputVariables are standardized for the most common output variables by openscm-runner according to the names used in the Special Report: Global Warming of 1,5°. You can find them all in the SR15 database in the tab “Documentation” in the section “Variables” (available after login, guest login works). Some climate models provide additional non-standard outputs, if you want to request any of those, you have to use the non-standard name of the climate model.

It is also possible to run multiple models at once. Expanding on the sea level rise example, we could also add a run of FaIR in the default configuration:

# output sea level rise and surface temperature for two different climate
# sensitivity settings for MAGICC and a default run of FaIR for comparison.
res <- rOpenscmRunner::run(
  climateModelsConfigs = list("MAGICC7" = list(list("CORE_CLIMATESENSITIVITY" = 3.),
                                               list("CORE_CLIMATESENSITIVITY" = 4.)),
                              "FaIR" = NULL),
  scenarios = df,
  outConfig = list("MAGICC7" = list("CORE_CLIMATESENSITIVITY")),
  outputVariables = list("Surface Temperature", "Sea Level Rise")
)

Debugging

If you run into problems and errors, it might be easier to try and run openscm-runner directly from Python to isolate your problem. You will get more complete error messages from openscm-runner when run directly from Python.