R Interface for Hector

Basic usage

Creating a Hector core

library(hector)
library(ggplot2)
library(ggthemes)
inifile <- system.file('input/hector_rcp45.ini', package='hector', mustWork=TRUE)
hcore <- newcore(inifile, suppresslogging=TRUE, name='RCP45')
print(hcore)

Hector core:    RCP45
Start date: 1745
End date:   2300
Current date:   1745
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp45.ini

Running Hector

run(hcore, 2100)

Hector core:    RCP45
Start date: 1745
End date:   2300
Current date:   2100
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp45.ini

Geting data

hdata <- fetchvars(hcore, 1990:2100, c(ATMOSPHERIC_CO2(), GLOBAL_TEMP(), RF_TOTAL()))
ggplot(data=hdata, aes(x=year, y=value)) + geom_line(col="darkgrey", size=1.1) + facet_wrap(~variable, scales='free_y') + 
    theme_solarized(light = TRUE)

The core and the date are mandatory. The list of variables is optional. If you don’t specify it, a default set is fetched. You can change that default by setting the hector.default.fetchvars option. There is also an optional scenario argument that sets the value of the scenario column. If you don’t supply it, the name of the hector core is used.

Cleanup

Hector cores will automatically be cleaned up when they are garbage collected, but you can shut them down manually if you wish.

shutdown(hcore)

Hector core (INACTIVE)

Multiple Hector cores

Cores are separate from one another and can be run independently.

inifile45 <- system.file('input/hector_rcp45.ini', package='hector', mustWork=TRUE)
inifile85 <- system.file('input/hector_rcp85.ini', package='hector', mustWork=TRUE)
hcore45 <- newcore(inifile45, suppresslogging=TRUE, name='RCP45')
hcore85 <- newcore(inifile85, suppresslogging=TRUE, name='RCP85')
invisible(run(hcore45, 2100))
getdate(hcore45)

[1] 2100

getdate(hcore85)

[1] 1745

The results from several runs can easily be put together for comparison.

invisible(run(hcore85, 2100))
hdata45 <- fetchvars(hcore45, 1990:2100)                  # default vars
hdata85 <- fetchvars(hcore85, 1990:2100)
hdata <- rbind(hdata45, hdata85)
ggplot(data=hdata, aes(x=year, y=value, color=scenario)) + geom_line() + 
    facet_wrap(~variable, scales='free_y') + 
    theme_solarized(light = TRUE)

Intermediate usage

Reset a core to an earlier date

reset(hcore85)

Hector core:    RCP85
Start date: 1745
End date:   2300
Current date:   1745
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp85.ini

Rerunning it should produce the same values.

invisible(run(hcore85, 2100))
hdata85_new <- fetchvars(hcore85, 1990:2100)
all.equal(hdata85, hdata85_new)

[1] TRUE

Set a custom emissions pathway

ffi85 <- fetchvars(hcore85, 2000:2100, FFI_EMISSIONS())
invisible(reset(hcore85))                               # Without a year specified, resets to the beginning
ffinew <- ffi85$value * 0.5
setvar(hcore85, ffi85$year, FFI_EMISSIONS(), ffinew, as.character(ffi85$units[1]))
invisible(run(hcore85, 2100))
hdata_lo <- fetchvars(hcore85, 1990:2100, scenario='Low_Emiss')
hdata <- rbind(hdata45, hdata85, hdata_lo)
ggplot(data=hdata, aes(x=year, y=value, color=scenario)) + geom_line() + 
    facet_wrap(~variable, scales='free_y') + 
    theme_solarized(light = TRUE)

The hector core remembers changes like this, so we’ll shut it down so we don’t accidentally use it again.

shutdown(hcore85)

Hector core (INACTIVE)

Changing model parameters

hcore85_lo_ecs <- newcore(inifile85, suppresslogging=TRUE, name='RCP85_low_ecs')
setvar(hcore85_lo_ecs, NA, ECS(), 2.5, 'degC')
reset(hcore85_lo_ecs)

Hector core:    RCP85_low_ecs
Start date: 1745
End date:   2300
Current date:   1745
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp85.ini

run(hcore85_lo_ecs, 2100)

Hector core:    RCP85_low_ecs
Start date: 1745
End date:   2300
Current date:   2100
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp85.ini

hdata85_low_ecs <- fetchvars(hcore85_lo_ecs, 1990:2100)
hdata <- rbind(hdata45, hdata85, hdata85_low_ecs)
ggplot(data=hdata, aes(x=year, y=value, color=scenario)) + geom_line() + 
    facet_wrap(~variable, scales='free_y') + 
    theme_solarized(light = TRUE)

Caution: You must reset a hector core to the beginning of the simulation (i.e., with no year argument) after changing a model parameter. This reruns the initialization and spinup, both of which are needed for Hector to use the new parameters correctly.

Advanced usage

When combined with other R packages Hector can be very powerful. Here’s an example where we search for an emissions pathway the produces a specified (constant) atmospheric methane concentration. Note: If you use Hector in an algorithm that will run the model many times, you will probably want to turn off the logging using the suppresslogging argument to newcore.

hector_inifile <- file.path(system.file('input', package='hector'), 'hector_rcp60.ini')
hcore_solv <- newcore(hector_inifile, suppresslogging=TRUE)
run(hcore_solv, 1999)

Hector core:    unnamed hector core
Start date: 1745
End date:   2300
Current date:   1999
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp60.ini

We will need a target function for our solver.
Caution: a function created this way will not be thread safe because the hector core stores persistent data in its internal data structures. If you try to use something like this in a parallel algorithm, you will have to find a way for each thread to have its own private hector core.

mktargfun <- function(targlevel, hcore) {
    function(emiss){
        setvar(hcore, 2000:2100, EMISSIONS_CH4(), emiss, "Tg CH4")
        reset(hcore, 1999)
        run(hcore, 2100)
        hout <- fetchvars(hcore, 2000:2100, ATMOSPHERIC_CH4())
        ## return the difference between the target and the actual
        hout$value - targlevel
    }
}
f <- mktargfun(1820, hcore_solv)

initguess <- rep(300.0, times=101)  # 2000:2001 includes both endpoints
slv <- nleqslv::nleqslv(initguess, f, method="Broyden")
ch4emiss <- slv$x
pltdata <- data.frame(year=2000:2100, ch4_emiss=ch4emiss)
ggplot(data=pltdata, aes(x=year, y=ch4_emiss)) + geom_line(col="darkgrey", size=1.25) + 
    theme_solarized(light = TRUE)

reset(hcore_solv, 1999)

Hector core:    unnamed hector core
Start date: 1745
End date:   2300
Current date:   1999
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp60.ini

setvar(hcore_solv, 2000:2100, EMISSIONS_CH4(), ch4emiss, "Tg CH4")
run(hcore_solv, 2100)

Hector core:    unnamed hector core
Start date: 1745
End date:   2300
Current date:   2100
Input file: /Users/link593/Library/R/3.3/library/hector/input/hector_rcp60.ini

ch4conc <- fetchvars(hcore_solv, 2000:2100, ATMOSPHERIC_CH4())
ggplot(data=ch4conc, aes(x=year, y=value)) + geom_line(col='darkgrey', size=1.25) + theme_solarized(light=TRUE) + ylim(1800,1830)