Skip to contents

Add a new variable

C++ & R

Source: vignettes/articles/AddNewVariable.Rmd
AddNewVariable.Rmd

Adding a new variable to Hector’s C++ codebase using getData to obtain the information defined in the INI file and Rcpp to expose the variable to the R interface.

C++ Changes

In hector.ini

Under the corresponding component add the variable
Ex: SN = 42000;

In component_data.hpp

Add variable as tseries, unitval, double, etc. and add its associated time series (when necessary; see above).

Define the variables that are being added
Ex: # define D_ATMOSPHERIC_SO2 "SN"

These names do not have to match internal component variables but the INI definition has to match what appears in quotes.

In X_component.cpp

Under init, need to register the capability core->registerCapability( D_ATMOSPHERIC_SO2, getComponentName() );

Under getData and setData, add the new variables before the Error message.

See tseries documentation for more information on getData

(getData)

    else if(varName == D_ATMOSPHERIC_SO2 ) {
      returnval = SN;

(setData)

    else if( varName ==  D_ATMOSPHERIC_SO2  ) {
      H_ASSERT( data.date == Core::undefinedIndex(), "date not allowed");
    SN.set( lexical_cast<double>( value ), U_GG );
        }

If the variable is used in other X_component.cpp

For example, if adding in a variable within the forcing component:

unitval SN = core->getData( D_ATMOSPHERIC_SO2, runToDate);

If this variable is a unitval, the relevant code file must include unitval.hpp.

R changes

In order to be able to use the R Hector setvar and fetchvars functions, add a helper function to rcpp_constants.cpp

//' @describeIn DocumentationGroupName A description of the variable name. 
//' @export
// [[Rcpp::export]]
String R_FUNCTION_NAME() {
return D_VARIABLE_NAME;
}

Here is an example for GLOBAL_TAS() which is used to get global mean temperature data.

//' @describeIn temperature Global mean temperature anomaly
//' @export
// [[Rcpp::export]]
String GLOBAL_TAS() {
return D_GLOBAL_TEMP;
}