Merge pull request #21 from JGCRI/dev

GCAM 6 changes and features

NAMESPACE

@@ -15,11 +15,14 @@ export(get_fx)
 export(get_price_scale_factor)
 export(get_prices)
 export(get_quantity_scale_factor)
+export(get_scenario_name)
 export(get_slope)
 export(get_supply)
-export(run_to_period)
+export(print_xmldb)
+export(run_period)
 export(set_data)
 export(set_prices)
+export(set_scenario_name)
 export(set_slope)
 importFrom(Rcpp,cpp_object_initializer)
 importFrom(Rcpp,loadModule)

R/gcamwrapper.R

@@ -21,18 +21,34 @@ create_and_initialize <- function(configuration = "configuration.xml", workdir =
 #' been run will be kept track of and will not be run again.  HOWEVER,
 #' we do not attempt to keep track of if those model periods are "dirty"
 #' such as if a user has called `set_data` in such a way that would invalidate
-#' that solution.
+#' that solution.  Users can supply a call back function which will be called
+#' after initCalc and before solving.  Such a call back could be necessary if
+#' if data a user wanted to set would have been overridden during initializations.
 #' @param gcam (gcam) An initialized GCAM instance
 #' @param period (integer) The GCAM model period to run up to or the
 #" `get_current_period` + 1 if \code{NULL}
+#' @param post_init_calback (function) A call back function
+#' @param ... Additional params to pass to the callback function
 #' @return GCAM instance
 #' @importFrom Rcpp cpp_object_initializer
 #' @export
-run_to_period <- function(gcam, period = NULL) {
+run_period <- function(gcam, period = NULL, post_init_calback = NULL, ...) {
   if(is.null(period)) {
       period <- get_current_period(gcam) + 1
   }
-  gcam$run_to_period(period)
+
+  if(is.null(post_init_calback)) {
+    # if we are not running a call back function just do the whole thing together
+    # which will generate less confusing log messages
+    gcam$run_period(period)
+  } else {
+    # otherwise we will need to partition the calls
+    # if we are not already at period the log messages may be confusing as it will
+    # show as running period-1 then a seperate running period
+    gcam$run_period_pre(period)
+    post_init_calback(gcam, ...)
+    gcam$run_period_post(period)
+  }
 
   invisible(gcam)
 }
@@ -120,10 +136,10 @@ convert_period_to_year <- function(gcam, period) {
     ret
 }
 
-#' Convert from a GCAM model year to model period 
+#' Convert from a GCAM model year to model period
 #' @param gcam (gcam) An initialized GCAM instance
 #' @param year (integer vector) The model year to convert to period
-#' @return (integer vector) The corresponding model period 
+#' @return (integer vector) The corresponding model period
 #' @export
 convert_year_to_period <- function(gcam, year) {
     if(length(year) == 0) {
@@ -139,20 +155,50 @@ convert_year_to_period <- function(gcam, year) {
     ret
 }
 
+#' Write the full results to an XML Database
+#' @details At the moment all of the options governing XML Database output are
+#' locked into the values set in the \code{configuration} as well as the
+#' \code{XMLDBDriver.properties} file.
+#' @param gcam (gcam) An initialized GCAM instance
+#' @param xmldb_location (string) Override the location to write the XMLDB if non-empty
+#' @return (string) The XMLDB location, particuarly useful if relying on defaults from the config.
+#' @export
+print_xmldb <- function(gcam, xmldb_location = "") {
+  gcam$print_xmldb(xmldb_location)
+}
+
+#' Get the scenario name
+#' @param gcam (gcam) An initialized GCAM instance
+#' @return (string) The name of the scenario
+#' @export
+get_scenario_name <- function(gcam) {
+  gcam$get_scenario_name()
+}
+
+#' Set the scenario name
+#' @param gcam (gcam) An initialized GCAM instance
+#' @param name (string) The name of the scenario to set
+#' @export
+set_scenario_name <- function(gcam, name) {
+  gcam$set_scenario_name(name)
+}
+
 #' Create a solution debugging object
 #' @details Create a solution debugging object which can be used a single
 #' evaluation of the model and see how it affects prices, supplies,
 #' and demands amongst other things.
 #' @param gcam (gcam) An initialized GCAM instance
 #' @param period (integer) GCAM model period to create the debugger or if NULL
 #' use the last run model period.
+#' @param market_filter (string) A \code{<solution-info-filter>} string in the same
+#' format as in the solver config XML.  The default is "solvable".
 #' @return A SolutionDebugger object
 #' @export
-create_solution_debugger <- function(gcam, period = NULL) {
+create_solution_debugger <- function(gcam, period = NULL, market_filter = "solvable") {
   if(is.null(period)) {
       period <- get_current_period(gcam)
   }
-  gcam$create_solution_debugger(period)
+  gcam$create_solution_debugger(period, market_filter)
 }
 
 #' Gets the prices

R/query_library.R

@@ -47,6 +47,7 @@ wrap_get_query <- function() {
 #' @return (string) The raw query from the query file with units set as an attribute
 #' if specified.
 #' @importFrom yaml read_yaml
+#' @export
 get_query <- wrap_get_query()
 
 

gcamwrapper/main.py

@@ -10,7 +10,7 @@ class Gcam(gcam_module.gcam):
        instance.
     """
 
-    def run_to_period(self, period=None):
+    def run_period(self, period=None, post_init_calback=None):
         """ Run GCAM up to and including some model period.
             Model periods which have already been run will be kept track
             of and will not be run again.  HOWEVER, we do not attempt to
@@ -25,7 +25,18 @@ def run_to_period(self, period=None):
 
         if period is None:
             period = self.get_current_period() + 1
-        super(Gcam, self).run_to_period(period)
+
+        if post_init_calback is None:
+           # if we are not running a call back function just do the whole thing together
+           # which will generate less confusing log messages
+           super(Gcam, self).run_period(period)
+        else:
+           # otherwise we will need to partition the calls
+           # if we are not already at period the log messages may be confusing as it will
+           # show as running period-1 then a seperate running period
+           super(Gcam, self).run_period_pre(period)
+           post_init_calback(self)
+           super(Gcam, self).run_period_post(period)
 
     def get_data(self, query, *args, **kwargs):
         """Queries for arbitrary data from a running instance of GCAM.
@@ -143,21 +154,40 @@ def convert_year_to_period(self, year):
         else:
             return list(map(lambda x: self.convert_year_to_period(x), year))
 
-    def create_solution_debugger(self, period=None):
+    def print_xmldb(self, xmldb_location = ""):
+        """Write the full results to an XML Database
+           At the moment all of the options governing XML Database output are
+           locked into the values set in the `configuration` as well as the
+           `XMLDBDriver.properties` file.
+        """
+
+        return super(Gcam, self).print_xmldb(xmldb_location)
+
+    def get_scenario_name(self):
+        return super(Gcam, self).get_scenario_name()
+
+    def set_scenario_name(self, name):
+        super(Gcam, self).set_scenario_name(name)
+
+
+    def create_solution_debugger(self, period=None, market_filter="solvable"):
         """Create a solution debugging object which can be used a single
            evaluation of the model and see how it affects prices, supplies,
            and demands amongst other things..
 
         :param period:   GCAM model period to create the debugger
         :type period:    integer
+        :param market_filter: A `<solution-info-filter>` string in the same
+                              format as in the solver config XML.  The default is "solvable".
+        :type market_filter:  str
 
         :returns:        A SolutionDebugger object
 
         """
 
         if period is None:
             period = self.get_current_period()
-        sd = super(Gcam, self).create_solution_debugger(period)
+        sd = super(Gcam, self).create_solution_debugger(period, market_filter)
         sd.__class__ = SolutionDebugger
         return sd