V3.5.0 Development

.github/ISSUE_TEMPLATE/new_release_checklist.md

@@ -0,0 +1,22 @@
+---
+name: Release
+about: Checklist! 
+---
+
+Since the dev branch only includes materials that have been peer-reviewed at least once this PR review process should be relatively smooth should. That being said, before merging this branch into main and the new release is created several things must be completed first. 
+
+* Open a PR into main branch, it should be titled with the new release number  
+* Let Leeyabot generate a report detailing how the Hector output has changed! 
+* Add text to the PR documenting the major model changes. The PR is going to serve as an important record 
+* Pass automated checks
+* Change the version number in the DESCRIPTION file 
+* Update the NEWS.md, are links additional materials necessary? Does the release need a new naming file? 
+* Check to make sure the internal package data is up to date (fxntable, inputstable, unitstable)
+
+After merging PR 
+
+* Create the release via zenodo 
+* Add the zenodo links to README / NEWS & push directly to main 
+* Create new dev branch & update the DESCRIPTION version number to support the pkgdown documentation for the developmental branch!
+* Add archived outputstreams to release assets!
+

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: hector
 Title: The Hector Simple Climate Model
-Version: 3.2.0
+Version: 3.5.0
 Authors@R: c(person("Kalyn", "Dorheim", 
 	        email = "kalyn.dorheim@pnnl.gov",
 	        role = c("aut", "cre"),
@@ -31,6 +31,10 @@ Authors@R: c(person("Kalyn", "Dorheim",
 	        email = "leeya.pressburger@pnnl.gov", 
 	        role = c("ctb", "dtc"),
 	        comment = c(ORCID = "0000-0002-6850-2504")),
+	    person("Peter", "Scully",
+	        email = "ptrscll@gmail.com",
+	        role = "ctb",
+	        comment = c(ORCID = "0009-0007-0234-0366")),
 	     person("Alexey", "Shiklomanov",
 	        email = "alexey.shiklomanov@nasa.gov",
 	        role = "ctb",
@@ -47,7 +51,8 @@ Description: Provides an R interface for the Hector Simple Climate
     change model parameters and emissions inputs, run Hector, and
     retrieve model outputs. Note that the package authors are not
     identical to the C++ model authors.
-Depends: R (>= 3.3)
+Depends: 
+    R (>= 3.5)
 License: GPL-3
 Encoding: UTF-8
 LazyData: true
@@ -70,7 +75,7 @@ Collate:
     'units.R'
 VignetteBuilder: knitr
 Config/Needs/website: kableExtra, nleqslv
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 SystemRequirements: GNU make
 URL: https://github.com/JGCRI/hector, https://jgcri.github.io/hector/
 BugReports: https://github.com/JGCRI/hector/issues

NAMESPACE

@@ -3,6 +3,7 @@
 S3method(format,hcore)
 S3method(print,hcore)
 export(AERO_SCALE)
+export(ALL_VARS)
 export(ATMOSPHERIC_CO2)
 export(BETA)
 export(C2F6_CONSTRAIN)
@@ -238,6 +239,8 @@ export(RHO_NH3)
 export(RHO_OC)
 export(RHO_SF6)
 export(RHO_SO2)
+export(RH_DETRITUS)
+export(RH_SOIL)
 export(SF6_CONSTRAIN)
 export(SOIL_C)
 export(SST)

NEWS.md

@@ -1,5 +1,22 @@
+# hector 3.5.0 
+
+* Minor documentation changes 
+* Several variables/parameters were renamed, FCH4 -> RF_CH4, alpha -> aero_scalar, & volscl -> vol_scalar 
+* Change RF vol implementation so it is not negative in the future period
+* Expose soil and detritus RH fluxes as possible Hector outputs, RH_DETRITUS() & RH_SOIL()
+* Add ALL_VARS() which helps users fetch all Hector output variables 
+* Update [CH4] lifetime parameters
+* Allow for time varying historical N2O and CH4 natural emissions 
+* New default parameter values for ocean heat diffusivity, CO2 fertilization, and heterotrophic respiration temperature sensitivity 
+
+
+
+
+
 # hector 3.2.0 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10698028.svg)](https://doi.org/10.5281/zenodo.10698028)
+
+* Fully documented in Dorheim, K., Gering, S., Gieseke, R., Hartin, C., Pressburger, L., Shiklomanov, A. N., Smith, S. J., Tebaldi, C., Woodard, D. L., and Bond-Lamberty, B.: Hector V3.2.0: functionality and performance of a reduced-complexity climate model, Geosci. Model Dev., 17, 4855–4869, https://doi.org/10.5194/gmd-17-4855-2024, 2024.
 * Correct aerosol forcing coefficients based on Zelinka et al. (2023)
 * Enable permafrost module and recalibrate model's default parameterization
 

R/RcppExports.R

@@ -1292,6 +1292,18 @@ RH <- function() {
     .Call('_hector_RH', PACKAGE = 'hector')
 }
 
+#' @rdname carboncycle
+#' @export
+RH_DETRITUS <- function() {
+    .Call('_hector_RH_DETRITUS', PACKAGE = 'hector')
+}
+
+#' @rdname carboncycle
+#' @export
+RH_SOIL <- function() {
+    .Call('_hector_RH_SOIL', PACKAGE = 'hector')
+}
+
 #' @describeIn parameters Preindustrial CO2 concentration (\code{"ppmv CO2"})
 #' @export
 PREINDUSTRIAL_CO2 <- function() {

R/aadoc.R

@@ -312,3 +312,8 @@ NULL
 #'  \item{string}{String of variable name}
 #' }
 "fxntable"
+
+#' A vector containing all the hector output names.
+#'
+#' @format A vector of length 82.
+"all_vars"

R/biome.R

@@ -22,19 +22,19 @@ create_biome <- function(core, biome,
                          npp_flux0,
                          warmingfactor, beta, q10_rh,
                          f_nppv, f_nppd, f_litterd) {
-    create_biome_impl(core, biome)
-    setvar(core, 0, VEG_C(biome), veg_c0, "Pg C")
-    setvar(core, 0, DETRITUS_C(biome), detritus_c0, "Pg C")
-    setvar(core, 0, SOIL_C(biome), soil_c0, "Pg C")
-    setvar(core, 0, PERMAFROST_C(biome), permafrost_c0, "Pg C")
-    setvar(core, NA, NPP_FLUX0(biome), npp_flux0, "Pg C/yr")
-    setvar(core, NA, WARMINGFACTOR(biome), warmingfactor, NA)
-    setvar(core, NA, BETA(biome), beta, NA)
-    setvar(core, NA, Q10_RH(biome), q10_rh, NA)
-    setvar(core, NA, F_NPPV(biome), f_nppv, NA)
-    setvar(core, NA, F_NPPD(biome), f_nppd, NA)
-    setvar(core, NA, F_LITTERD(biome), f_litterd, NA)
-    invisible(core)
+  create_biome_impl(core, biome)
+  setvar(core, 0, VEG_C(biome), veg_c0, "Pg C")
+  setvar(core, 0, DETRITUS_C(biome), detritus_c0, "Pg C")
+  setvar(core, 0, SOIL_C(biome), soil_c0, "Pg C")
+  setvar(core, 0, PERMAFROST_C(biome), permafrost_c0, "Pg C")
+  setvar(core, NA, NPP_FLUX0(biome), npp_flux0, "Pg C/yr")
+  setvar(core, NA, WARMINGFACTOR(biome), warmingfactor, NA)
+  setvar(core, NA, BETA(biome), beta, NA)
+  setvar(core, NA, Q10_RH(biome), q10_rh, NA)
+  setvar(core, NA, F_NPPV(biome), f_nppv, NA)
+  setvar(core, NA, F_NPPD(biome), f_nppd, NA)
+  setvar(core, NA, F_LITTERD(biome), f_litterd, NA)
+  invisible(core)
 }
 
 #' Create new biomes by splitting up an existing biome
@@ -67,64 +67,66 @@ split_biome <- function(core,
                         fpermafrost_c = fveg_c,
                         fnpp_flux0 = fveg_c,
                         ...) {
-    stopifnot(
-        length(old_biome) == 1,
-        old_biome %in% get_biome_list(core),
-        !any(new_biomes %in% get_biome_list(core)),
-        length(fveg_c) == length(new_biomes),
-        length(fdetritus_c) == length(new_biomes),
-        length(fsoil_c) == length(new_biomes),
-        length(fpermafrost_c) == length(new_biomes),
-        length(fnpp_flux0) == length(new_biomes),
-        sum(fveg_c) == 1, all(fveg_c > 0),
-        sum(fdetritus_c) == 1, all(fdetritus_c > 0),
-        sum(fsoil_c) == 1, all(fsoil_c > 0),
-        sum(fpermafrost_c) == 1, all(fpermafrost_c >= 0),
-        sum(fnpp_flux0) == 1, all(fnpp_flux0 > 0)
-    )
+  stopifnot(
+    length(old_biome) == 1,
+    old_biome %in% get_biome_list(core),
+    !any(new_biomes %in% get_biome_list(core)),
+    length(fveg_c) == length(new_biomes),
+    length(fdetritus_c) == length(new_biomes),
+    length(fsoil_c) == length(new_biomes),
+    length(fpermafrost_c) == length(new_biomes),
+    length(fnpp_flux0) == length(new_biomes),
+    sum(fveg_c) == 1, all(fveg_c > 0),
+    sum(fdetritus_c) == 1, all(fdetritus_c > 0),
+    sum(fsoil_c) == 1, all(fsoil_c > 0),
+    sum(fpermafrost_c) == 1, all(fpermafrost_c >= 0),
+    sum(fnpp_flux0) == 1, all(fnpp_flux0 > 0)
+  )
 
-    # If user supplied values in ... for warmingfactor, etc., use those
-    # Otherwise use the old biome's values
-    cv <- get_biome_inits(core, old_biome) # current values
-    dots <- list(...)
-    # We can't use ifelse for this because return shape may differ
-    pick <- function(x, y) { if (is.null(x)) y else x } # nolint
-    warmingfactor <- pick(dots$warmingfactor, cv[["warmingfactor"]])
-    beta <- pick(dots$beta, cv[["beta"]])
-    q10_rh <- pick(dots$q10_rh, cv[["q10_rh"]])
-    f_nppv <- pick(dots$f_nppv, cv[["f_nppv"]])
-    f_nppd <- pick(dots$f_nppd, cv[["f_nppd"]])
-    f_litterd <- pick(dots$f_litterd, cv[["f_litterd"]])
+  # If user supplied values in ... for warmingfactor, etc., use those
+  # Otherwise use the old biome's values
+  cv <- get_biome_inits(core, old_biome) # current values
+  dots <- list(...)
+  # We can't use ifelse for this because return shape may differ
+  pick <- function(x, y) {
+    if (is.null(x)) y else x
+  } # nolint
+  warmingfactor <- pick(dots$warmingfactor, cv[["warmingfactor"]])
+  beta <- pick(dots$beta, cv[["beta"]])
+  q10_rh <- pick(dots$q10_rh, cv[["q10_rh"]])
+  f_nppv <- pick(dots$f_nppv, cv[["f_nppv"]])
+  f_nppd <- pick(dots$f_nppd, cv[["f_nppd"]])
+  f_litterd <- pick(dots$f_litterd, cv[["f_litterd"]])
 
-    # This allows users to split the `global` biome without having to
-    # rename it first. Otherwise, we hit an error about using non-global
-    # biomes when a "global" biome is present.
-    if (old_biome == "global") {
-        invisible(rename_biome(core, "global", "_zzz"))
-        old_biome <- "_zzz"
-    }
+  # This allows users to split the `global` biome without having to
+  # rename it first. Otherwise, we hit an error about using non-global
+  # biomes when a "global" biome is present.
+  if (old_biome == "global") {
+    invisible(rename_biome(core, "global", "_zzz"))
+    old_biome <- "_zzz"
+  }
 
-    mapply(
-        create_biome,
-        biome = new_biomes,
-        veg_c0 = cv[["veg_c"]] * fveg_c,
-        detritus_c0 = cv[["detritus_c"]] * fdetritus_c,
-        soil_c0 = cv[["soil_c"]] * fsoil_c,
-        permafrost_c0 = cv[["permafrost_c"]] * fpermafrost_c,
-        npp_flux0 = cv[["npp_flux0"]] * fnpp_flux0,
-        warmingfactor = warmingfactor,
-        beta = beta,
-        q10_rh = q10_rh,
-        f_nppv = f_nppv,
-        f_nppd = f_nppd,
-        f_litterd = f_litterd,
-        MoreArgs = list(core = core)
-    )
+  mapply(
+    create_biome,
+    biome = new_biomes,
+    veg_c0 = cv[["veg_c"]] * fveg_c,
+    detritus_c0 = cv[["detritus_c"]] * fdetritus_c,
+    soil_c0 = cv[["soil_c"]] * fsoil_c,
+    permafrost_c0 = cv[["permafrost_c"]] * fpermafrost_c,
+    npp_flux0 = cv[["npp_flux0"]] * fnpp_flux0,
+    warmingfactor = warmingfactor,
+    beta = beta,
+    q10_rh = q10_rh,
+    f_nppv = f_nppv,
+    f_nppd = f_nppd,
+    f_litterd = f_litterd,
+    MoreArgs = list(core = core)
+  )
 
-    delete_biome_impl(core, old_biome)
+  delete_biome_impl(core, old_biome)
 
-    reset(core, 0)
-    invisible(core)
+  reset(core, 0)
+  invisible(core)
 }
 
 #' Retrieve the initial conditions and parameters for a given biome
@@ -136,29 +138,29 @@ split_biome <- function(core,
 #' @return Named numeric vector of biome initial conditions and parameters
 #' @author Alexey Shiklomanov
 get_biome_inits <- function(core, biome) {
-    # `fetchvars` requires date to be between start and end date, so
-    # we need to call the lower-level `sendmessage` method here.
-    current_data_1 <- rbind.data.frame(
-        sendmessage(core, GETDATA(), VEG_C(biome), 0, NA, ""),
-        sendmessage(core, GETDATA(), DETRITUS_C(biome), 0, NA, ""),
-        sendmessage(core, GETDATA(), SOIL_C(biome), 0, NA, ""),
-        sendmessage(core, GETDATA(), PERMAFROST_C(biome), 0, NA, ""),
-        sendmessage(core, GETDATA(), THAWEDP_C(biome), 0, NA, "")
-    )
-    current_data_2 <- fetchvars(core, NA, c(
-        NPP_FLUX0(biome),
-        F_LITTERD(biome),
-        F_NPPD(biome),
-        F_NPPV(biome),
-        BETA(biome),
-        Q10_RH(biome),
-        WARMINGFACTOR(biome)
-    ))[, -1]
-    current_data <- rbind.data.frame(current_data_1, current_data_2)
-    current_values <- current_data[["value"]]
-    names(current_values) <- gsub(paste0(biome, BIOME_SPLIT_CHAR()), "",
-                                  current_data[["variable"]],
-                                  fixed = TRUE
-    )
-    current_values
+  # `fetchvars` requires date to be between start and end date, so
+  # we need to call the lower-level `sendmessage` method here.
+  current_data_1 <- rbind.data.frame(
+    sendmessage(core, GETDATA(), VEG_C(biome), 0, NA, ""),
+    sendmessage(core, GETDATA(), DETRITUS_C(biome), 0, NA, ""),
+    sendmessage(core, GETDATA(), SOIL_C(biome), 0, NA, ""),
+    sendmessage(core, GETDATA(), PERMAFROST_C(biome), 0, NA, ""),
+    sendmessage(core, GETDATA(), THAWEDP_C(biome), 0, NA, "")
+  )
+  current_data_2 <- fetchvars(core, NA, c(
+    NPP_FLUX0(biome),
+    F_LITTERD(biome),
+    F_NPPD(biome),
+    F_NPPV(biome),
+    BETA(biome),
+    Q10_RH(biome),
+    WARMINGFACTOR(biome)
+  ))[, -1]
+  current_data <- rbind.data.frame(current_data_1, current_data_2)
+  current_values <- current_data[["value"]]
+  names(current_values) <- gsub(paste0(biome, BIOME_SPLIT_CHAR()), "",
+    current_data[["variable"]],
+    fixed = TRUE
+  )
+  current_values
 }

R/fxns.R

@@ -9,14 +9,33 @@
 #' getfxn("beta")
 #' getfxn("q10_rh")
 getfxn <- function(str) {
+  rows <- match(str, hector::fxntable$string)
+  rslt <- hector::fxntable$fxn[rows]
+  if (any(is.na(rows))) {
+    warning(
+      "Functions for the following are not found: ",
+      paste(str[is.na(rslt)], collapse = ", ")
+    )
+  }
+  as.character(rslt)
+}
+
 
-    rows <- match(str, hector::fxntable$string)
-    rslt <- hector::fxntable$fxn[rows]
-    if (any(is.na(rows))) {
-        warning(
-            "Functions for the following are not found: ",
-            paste(str[is.na(rslt)], collapse = ", ")
-        )
-    }
-    as.character(rslt)
+#' Get all of the possible Hector output variables
+#'
+#' This function returns all of the possible hector output variables
+#' that can be accessed with \code{\link{fetchvars}}.
+#' @return Character vector of variable names.
+#' @export
+#' @family outputs
+#' @examples
+#' \dontrun{
+#' ini <- system.file(package = "hector", "input/hector_ssp245.ini")
+#' hc <- newcore(ini)
+#' run(hc)
+#' out <- fetchvars(core = hc, dates = 1900:2100, vars = ALL_VARS())
+#' print(out)
+#' }
+ALL_VARS <- function() {
+  hector::all_vars
 }