| Title: | 'GAMS' Modularization Support Package |
|---|---|
| Description: | A collection of tools to create, use and maintain modularized model code written in the modeling language 'GAMS' (<https://www.gams.com/>). Out-of-the-box 'GAMS' does not come with support for modularized model code. This package provides the tools necessary to convert a standard 'GAMS' model to a modularized one by introducing a modularized code structure together with a naming convention which emulates local environments. In addition, this package provides tools to monitor the compliance of the model code with modular coding guidelines. |
| Authors: | Jan Philipp Dietrich [aut, cre] (Potsdam Institute for Climate Impact Research, <https://orcid.org/0000-0002-4309-6431>), David Klein [aut] (Potsdam Institute for Climate Impact Research), Anastasis Giannousakis [aut], Felicitas Beier [aut] (Potsdam Institute for Climate Impact Research), Johannes Koch [aut] (Potsdam Institute for Climate Impact Research), Lavinia Baumstark [aut] (Potsdam Institute for Climate Impact Research), Mika Pflüger [aut], Oliver Richters [aut] (Potsdam Institute for Climate Impact Research) |
| Maintainer: | Jan Philipp Dietrich <[email protected]> |
| License: | BSD_2_clause + file LICENSE |
| Version: | 0.33.3 |
| Built: | 2024-11-16 06:06:49 UTC |
| Source: | https://github.com/pik-piam/gms |
A collection of tools to create, use and maintain modularized model code written in the modeling language 'GAMS' (https://www.gams.com/). Out-of-the-box 'GAMS' does not come with support for modularized model code. This package provides the tools necessary to convert a standard 'GAMS' model to a modularized one by introducing a modularized code structure together with a naming convention which emulates local environments. In addition, this package provides tools to monitor the compliance of the model code with modular coding guidelines.
Maintainer: Jan Philipp Dietrich [email protected] (ORCID) (Potsdam Institute for Climate Impact Research)
Authors:
David Klein (Potsdam Institute for Climate Impact Research)
Anastasis Giannousakis
Felicitas Beier (Potsdam Institute for Climate Impact Research)
Johannes Koch (Potsdam Institute for Climate Impact Research)
Lavinia Baumstark (Potsdam Institute for Climate Impact Research)
Mika Pflüger
Oliver Richters (Potsdam Institute for Climate Impact Research)
Useful links:
Report bugs at https://github.com/pik-piam/gms/issues
Checks a model configuration file for consistency by comparing it to a reference config file and the given module structure of the model. The function will throw out an error if settings are missing in the config which exist in the reference config, of if settings are set in the config which do not exist in the reference config file or if a realization is chosen for a module which does not exist, not allowed setting combinations.
check_config( icfg, reference_file = "config/default.cfg", modulepath = "modules/", settings_config = NULL, extras = NULL, saveCheck = FALSE )check_config( icfg, reference_file = "config/default.cfg", modulepath = "modules/", settings_config = NULL, extras = NULL, saveCheck = FALSE )
icfg |
Input config which should be checked for consistency (either as the config itself or as a file path linking to the config) |
reference_file |
Reference config which is having the right format (either as the config itself or as a file path linking to the config) |
modulepath |
The path where the modules are stored. If set to NULL the corresponding module check is deactivated. |
settings_config |
path where the table of possible setting combinations is stored, if NULL it is ignored |
extras |
vector of setting names that are allowed to appear in the input config even if they are missing in the reference config. That can be useful to allow for additional settings/information which does not necessarily have to exist |
saveCheck |
additional check which makes sure that saving and loading it to/from YAML format does not change its contents |
The checked config as a config list ready for further usage.
Jan Philipp Dietrich, Lavinia Baumstark
Checks for all declared objects in which parts of the model they appear and calculates the type of each object (core object, interface object, module object of module xy,...)
checkAppearance(x, capitalExclusionList = NULL)checkAppearance(x, capitalExclusionList = NULL)
x |
A code list as returned by |
capitalExclusionList |
A vector of names that should be ignored when checking for unified capitalization of variables |
A list with four elements: appearance, setappearance, type and warnings. Appearance is a matrix containing values which indicate whether an object appears in a part of the code or not (e.g. indicates whether "vm_example" appears in realization "on" of module "test" or not.). 0 means that it does not appear, 1 means that it appears in the code and 2 means that it appears in the not_used.txt. setappearance contains the same information but for sets instead of other objects. Type is a vector containing the type of each object (exluding sets). And warnings contains a list of warnings created during that process.
Jan Philipp Dietrich
Checks whether all Declarations of a GAMS code come with a Description, throws out a warning in case of a missing description.
checkDescription(x, w = NULL)checkDescription(x, w = NULL)
x |
GAMS declarations matrix as returned by |
w |
a vector of warnings the warnings should be added to
|
vector of warnings
Jan Philipp Dietrich
Check all files (also in subdirectories) matching the given pattern for tabs. Will throw an error with a list of files where tabs were found if any.
checkNoTabs(pattern, exclude = NULL, excludeFolders = NULL)checkNoTabs(pattern, exclude = NULL, excludeFolders = NULL)
pattern |
A regular expression. Only files matching this pattern will be checked for tabs. |
exclude |
A regular expression. Files matching this pattern will never be checked. |
excludeFolders |
Paths to folders that should not be checked. |
Invisibly, the list of files that were checked.
Pascal Sauer
## Not run: gms::checkNoTabs(pattern = "\\.(R|Rprofile|gms|cfg|bib)$", excludeFolders = c("output", "renv", ".git")) gms::checkNoTabs(utils::glob2rx("*.R")) ## End(Not run)## Not run: gms::checkNoTabs(pattern = "\\.(R|Rprofile|gms|cfg|bib)$", excludeFolders = c("output", "renv", ".git")) gms::checkNoTabs(utils::glob2rx("*.R")) ## End(Not run)
Checks for all declared switches in which parts of the model they appear and calculates the type of each object (core object, interface object, module object of module xy,...)
checkSwitchAppearance(code)checkSwitchAppearance(code)
code |
Model code returned by |
A list with three elements: switches, appearance and type. Switches is a vector containing all switches. The names of the vector contain the information where the switch is set. Appearance is a matrix containing values which indicate whether an object appears in a part of the code or not (e.g. indicates whether "vm_example" appears in realization "on" of module "test" or not.). 0 means that it does not appear, 1 means that it appears in the code and 2 means that it appears in the not_used.txt. Type is a vector containing the type of each object.
Jan Philipp Dietrich
codeCheck,readDeclarations,codeExtract,checkAppearance
Allows the user to select single or multiple items from a list. Entries can be selected based on individual choice, groups, regex or all.
chooseFromList( theList, type = "items", userinfo = NULL, addAllPattern = TRUE, returnBoolean = FALSE, multiple = TRUE, userinput = FALSE, errormessage = NULL )chooseFromList( theList, type = "items", userinfo = NULL, addAllPattern = TRUE, returnBoolean = FALSE, multiple = TRUE, userinput = FALSE, errormessage = NULL )
theList |
list or character vector to be selected from, names can specify groups |
type |
string in plural shown to user to understand what they have to choose |
userinfo |
string printed to the user before choosing |
addAllPattern |
boolean whether 'all' and 'Search by pattern' options are added |
returnBoolean |
TRUE: returns array with dimension of theList with FALSE and TRUE, which erases the order in which entries were selected FALSE: returns selected entries of theList, conserving the order in which entries were selected |
multiple |
TRUE: allows to select multiple entries. FALSE: no |
userinput |
string provided by the user. If not supplied, user is asked (mainly for testing) |
errormessage |
string used internally to tell the user before retrying that a selection does not make sense |
list or character vector, either a boolean with same length as theList or only the selected items.
Oliver Richters
## Not run: chooseFromList( theList = c(Letter = "A", Letter = "B", Number = "1", Number = "2"), type = "characters", userinfo = "Please don't select B, it hurts.", returnBoolean = FALSE, multiple = TRUE) ## End(Not run)## Not run: chooseFromList( theList = c(Letter = "A", Letter = "B", Number = "1", Number = "2"), type = "characters", userinfo = "Please don't select B, it hurts.", returnBoolean = FALSE, multiple = TRUE) ## End(Not run)
Checks GAMS code for consistency. Throws out warnings if something is wrong in the code and returns a list containing the interfaces of each module of the code.
codeCheck( path = ".", modulepath = "modules", core_files = c("core/*.gms", "main.gms"), returnDebug = FALSE, interactive = FALSE, test_switches = TRUE, strict = FALSE, details = FALSE )codeCheck( path = ".", modulepath = "modules", core_files = c("core/*.gms", "main.gms"), returnDebug = FALSE, interactive = FALSE, test_switches = TRUE, strict = FALSE, details = FALSE )
path |
path of the main folder of the model |
modulepath |
path to the module folder relative to "path" |
core_files |
list of files that belong to the core (wildcard expansion is supported) |
returnDebug |
If TRUE additional information will be returned useful for debugging the codeCheck function |
interactive |
activates an interactive developer mode in which some of the warnings can be fixed interactively. |
test_switches |
(boolean) Should realization switches in model core be tested for completeness? Usually set to TRUE but should be set to FALSE for standalone models only using a subset of existing modules |
strict |
(boolean) test strictness. If set to TRUE warnings from codeCheck will stop calculations at the end of the analysis. Useful to enforce clean code. |
details |
(boolean) If activated the function will return more detailed output. Besides interface information it will provide a table containing all declarations in the code, an appearance table listing the appearance of all objects in the code and information about the existing modules. The format is list(interfaceInfo,declarations,appearance,modulesInfo). This setting will be ignored when returnDebug is set to TRUE. |
Additional settings can be provided via a yaml file ".codeCheck" in the main folder of the model. Currently supported settings are: - capitalExclusionList: a list of names that should be ignored when checking for unified capitalization of variables
A list of all modules containing the interfaces for each module. Or more detailed output if either
details or returnDebug is set to TRUE.
Jan Philipp Dietrich
# check code consistency of dummy model codeCheck(system.file("dummymodel", package = "gms"))# check code consistency of dummy model codeCheck(system.file("dummymodel", package = "gms"))
Returns aggregated and cleaned GAMS code together with declaration matrix
codeExtract(codeFiles, name)codeExtract(codeFiles, name)
codeFiles |
A vector of file names of GAMS code files. |
name |
A name indicating what collection of code files this is (e.g. module name) |
A list with two elements: code and declarations. Code contains the
cleaned up gams code and declarations contains the declarations matrix as
returned by readDeclarations
Jan Philipp Dietrich
Converts modular GAMS code from an older modular definition to the newest one
convert.modularGAMS(path = ".", modulepath = "modules/")convert.modularGAMS(path = ".", modulepath = "modules/")
path |
path to the main folder of the model |
modulepath |
Module path within the model (relative to the model main folder) |
Jan Philipp Dietrich
Function to copy input files to their destination folders
copy_input(x, sourcepath, suffix = NULL, move = FALSE)copy_input(x, sourcepath, suffix = NULL, move = FALSE)
x |
Filepath or data frame containing the mapping of files to be deleted |
sourcepath |
Path to folder containing all input files |
suffix |
suffix that might be part of input names that should be deleted |
move |
If TRUE files will be moved instead of copied (default=FALSE) |
Jan Philipp Dietrich, David Klein
Delete data provided in mapping
delete_olddata(x)delete_olddata(x)
x |
Filepath or data frame containing the mapping of files to be deleted |
Jan Philipp Dietrich, David Klein
Downloads a list of tgz files from a list of repos and unpacks them
download_distribute( files, repositories = list(`/p/projects/rd3mod/inputdata/output` = NULL), modelfolder = ".", additionalDelete = NULL, debug = FALSE, stopOnMissing = FALSE )download_distribute( files, repositories = list(`/p/projects/rd3mod/inputdata/output` = NULL), modelfolder = ".", additionalDelete = NULL, debug = FALSE, stopOnMissing = FALSE )
files |
a vector of files containing input data, if a file is no .tgz it will be downloaded and not unpacked |
repositories |
a list of repositories (please pay attention to the list format!) in which the files should be searched for. Files will be searched in all repositories until found, always starting with the first repository in the list. The argument must have the format of a named list with the url of the repository as name and a corresponding list of options such as username or password to access the repository as value. If no options are required the value has to be NULL. (e.g. list("ftp://my_pw_protected_server.de/data"=list(user="me",password=12345), "http://free_server.de/dat"=NULL)) |
modelfolder |
main model folder |
additionalDelete |
information which additional data should be deleted before new data are downloaded and distributed |
debug |
switch for debug mode with additional diagnostic information |
stopOnMissing |
Boolean passed along to |
Information about the download process in form of a data.frame with data sets as row names and repositories (where it was downloaded from) and corresponding md5sum as columns
Jan Philipp Dietrich, Lavinia Baumstark
Downloads a list of tgz files from a list of repos and unpacks them. If a file is no .tgz-file it will be only downloaded.
download_unpack( input, targetdir = "input", repositories = NULL, debug = FALSE, unpack = TRUE, stopOnMissing = FALSE )download_unpack( input, targetdir = "input", repositories = NULL, debug = FALSE, unpack = TRUE, stopOnMissing = FALSE )
input |
a vector of files to be downloaded or a cfg list with settings to be used (e.g. containing cfg$input, cfg$repositories). Settings in the config list will be overwritten by other arguments of this function if they are not set to NULL |
targetdir |
directory the files should be downloaded and extracted to |
repositories |
a list of repositories (please pay attention to the list format!) in which the files should be searched for. Files will be searched in all repositories until found, always starting with the first repository in the list. The argument must have the format of a named list with the url of the repository as name and a corresponding list of options such as username or password to access the repository as value. If no options are required the value has to be NULL. (e.g. list("ftp://my_pw_protected_server.de/data"=list(user="me",password=12345), "http://free_server.de/dat"=NULL)) |
debug |
switch for debug mode with additional diagnostic information |
unpack |
if switched off the source files are purley downloaded |
stopOnMissing |
Boolean indicating whether to stop if any file in
|
Information about the download process in form of a data.frame with data sets as row names and repositories (where it was downloaded from) and corresponding md5sum as columns
Jan Philipp Dietrich
Creates GAMS code which stores automatically the levels, bounds and marginals of all equations and variables in time depending parameters.
fulldataOutput( declarations_file = "declarations.gms", definitions_file = "postsolve.gms", warn = TRUE, types = c("level", "marginal"), ignore = "_dummy$", loopset = "t" )fulldataOutput( declarations_file = "declarations.gms", definitions_file = "postsolve.gms", warn = TRUE, types = c("level", "marginal"), ignore = "_dummy$", loopset = "t" )
declarations_file |
A GAMS file containing declarations. The function
will read declarations from here and add own declarations in an R
environment as used by |
definitions_file |
A GAMS file which is executed after the solve
statement but within the time step loop. Also here code will be added using
|
warn |
Decides whether a warning should be thrown out, if the declarations file does not exist. |
types |
Types of outputs that should be written to gdx file. Available types are level, marginal, upper and lower. |
ignore |
regular expression pattern for variables/equations which should be ignored by fulldataOutput |
loopset |
Set over which loop runs |
Jan Philipp Dietrich, Felicitas Beier
readDeclarations,replace_in_file
Cleans GAMS code supplied from empty lines and comments.
GAMScodeFilter(x)GAMScodeFilter(x)
x |
A vector with lines of GAMS code (as you get by reading the code with readLines) |
The cleaned GAMS code
Jan Philipp Dietrich
GAMScodeFilter(c("","*comment","a=12;","","b=13;"))GAMScodeFilter(c("","*comment","a=12;","","b=13;"))
Function to extract information from info.txt
get_info(file, grep_expression, sep, pattern = "", replacement = "")get_info(file, grep_expression, sep, pattern = "", replacement = "")
file |
path to info.txt (including info.txt) |
grep_expression |
String before the information that should be extracted |
sep |
Separator between grep_expression and information |
pattern |
Optional pattern to be replaced (default pattern = "") |
replacement |
Optional replacement (default replacement = "") |
Jan Philipp Dietrich, David Klein
Create file2destination mapping based on information from the model, ignoring
top-level directories listed in .gitignore.
getfiledestinations(path = ".", ignoreFolders = "renv")getfiledestinations(path = ".", ignoreFolders = "renv")
path |
main model folder |
ignoreFolders |
folders to be ignored by the function, additionally to
directories listed in |
Jan Philipp Dietrich, David Klein
Get one line of user input regardless of whether running interactively or not (via Rscript). (base::readline does not wait for user input when running via Rscript.)
getLine()getLine()
The user input as a string.
Extract module information of a GAMS model.
getModules(modulepath)getModules(modulepath)
modulepath |
The path where the modules are stored. |
A matrix containing the different modules with name, corresponding module number and corresponding realizations
Jan Philipp Dietrich
Creates an interface plot of a modular model using
qgraph and returns the interface information.
interfaceplot( x = ".", modules_to_include = NULL, modules_to_exclude = NULL, links_to_include = NULL, links_to_exclude = NULL, items_to_include = NULL, items_to_exclude = NULL, items_to_display = NULL, default_groups = list(default1 = list(name = "core", nodes = "core", color = "black", shape = "rectangle"), default2 = list(name = "modules", nodes = NULL, color = "#6c9ebf", shape = "ellipse")), highlight_groups = NULL, max_length_node_names = NULL, add_nodeName_legend = FALSE, max_num_edge_labels = NULL, max_num_nodes_for_edge_labels = 30, ... )interfaceplot( x = ".", modules_to_include = NULL, modules_to_exclude = NULL, links_to_include = NULL, links_to_exclude = NULL, items_to_include = NULL, items_to_exclude = NULL, items_to_display = NULL, default_groups = list(default1 = list(name = "core", nodes = "core", color = "black", shape = "rectangle"), default2 = list(name = "modules", nodes = NULL, color = "#6c9ebf", shape = "ellipse")), highlight_groups = NULL, max_length_node_names = NULL, add_nodeName_legend = FALSE, max_num_edge_labels = NULL, max_num_nodes_for_edge_labels = 30, ... )
x |
Either an interface list as returned by
|
modules_to_include |
NULL (default value) or a vector of strings with names of modules to include, e.g. c("core", "macro"). If NULL all modules are included. |
modules_to_exclude |
NULL (default value) or a vector of strings with names of modules to exclude, e.g. c("core"). If NULL no modules are excluded. |
links_to_include |
NULL (default value) or list of lists with attributes "to" and "from", that each take a vector of module names, e.g. list(list(to="macro", from="core")). If NULL all links are included. |
links_to_exclude |
NULL (default value) or list of lists with attributes "to" and "from", that each take a vector of module names, e.g. list(list(to="macro", from="core")). If NULL no links are excluded. |
items_to_include |
NULL (default value) or a vector of strings with names of items to include, e.g. c("vm_cesIO", "pm_pvp"). Regex patterns can also be passed, e.g. c("(v|p)m_.*"). If NULL all items are included. |
items_to_exclude |
NULL (default value) or a vector of strings with names of items to exclude, e.g. c("vm_cesIO", "pm_pvp"). Regex patterns can also be passed, e.g. c("sm_.*"). If NULL no items are excluded. |
items_to_display |
NULL (default value) or a vector of strings with names of items to display, e.g. c("vm_cesIO", "pm_pvp"). Regex patterns can also be passed, e.g. c(.m\ S+). If NULL no items are displayed. |
default_groups |
List of lists with default group definitions. Defines the default formatting of the interface plot. By default, there are two groups, see usage, a "core" group made up of only the "core" module and a "modules" group made up of all the rest. If a "core" module doesn't exist, then that group is simply ignored. |
highlight_groups |
NULL (default value) or a list of lists with highlight-group definitions. By defining highligh groups, additional/specalized formatting can be applied to select modules. A group is defined by a list with the following attributes:
An example:
|
max_length_node_names |
NULL (default value) or an integer n giving the maximum number of characters allowed in the node names. If not NULL, node names are truncated after n characters, e.g. n=3: "example" -> "exa.". |
add_nodeName_legend |
Logical (default FALSE) to add node names in legend, structured by group. |
max_num_edge_labels |
NULL (default value), an integer or the string "adjust". If NULL, all edge lables are displayed. If given an integer n, a maximum of n edge labels are shown. If set to "adjust", the number of edge labels displayed decreases with the number of nodes. |
max_num_nodes_for_edge_labels |
Integer, (default value = 30). The maximum number of nodes after which no edge labels are displayed. |
... |
Optional arguments to |
What modules (=nodes), links (=edges) and items (=what is passed along the edges) are taken into account when creating the plot can be fine-tuned with the "_include", "_exclude" arguments.
The "default"- and "highlight_groups" arguments control the formatting (and also the composition through "highlight_group$edges_to_ignore"). Groups in qqgraph are a way of clustering nodes together. The default formatting of the plot is defined with the "default_groups" argument. On top of that additional groups can be defined with the "highlight_groups" argument.
The rest of the arguments are pretty self-explanatory. Just remember that
qgraph arguments can be passed on as well! Useful ones
include: fade=T/F, legend=T/F, legend.cex (size of the legend font), GLratio
(graph/legend size ratio, edge.label.cex (size of the edge label font)).
A tibble with the edge list and interface items.
Johannes Koch
Checks whether a folder seems to contain modular GAMS code or not.
is.modularGAMS(path = ".", version = FALSE, modulepath = "modules/")is.modularGAMS(path = ".", version = FALSE, modulepath = "modules/")
path |
path to the main folder of the model |
version |
if TRUE returns the version of the modular structure or FALSE, otherwise returns a boolean indicating whether it is modular or not. |
modulepath |
Module path within the model (relative to the model main folder) |
Jan Philipp Dietrich
is.modularGAMS(system.file("dummymodel",package="gms"))is.modularGAMS(system.file("dummymodel",package="gms"))
Load config in YAML format as written via
saveConfig.
loadConfig(cfg)loadConfig(cfg)
cfg |
Either a character string naming a file which containes the config or a character string containing the config as YAML code. |
To read in the default configuration (stored as R list in default.cfg or in a gams file), use
readDefaultConfig instead.
Jan Philipp Dietrich
cfg <- list(input = c(data1 = "blub.tgz", data2 = "bla.tgz"), mode = "default") yml <- saveConfig(cfg) loadConfig(yml)cfg <- list(input = c(data1 = "blub.tgz", data2 = "bla.tgz"), mode = "default") yml <- saveConfig(cfg) loadConfig(yml)
This function analyzes a model folder and all subfolders and searches for library and require statements.
model_dependencies(mainfolder = ".")model_dependencies(mainfolder = ".")
mainfolder |
main folder of the model to be analyzed |
A list of dependencies sorted by appearances
Jan Philipp Dietrich
Lock the model to coordinate multiple processes accessing the model. This is necessary if you change files within the model and have to avoid that another process reads from your half-written changes in the mean time. model_lock creates an exclusive lock on the given file and returns a lock id. When the lock id is handed to model_unlock the lock is dropped again, and another process can take the lock. The lock is also dropped when the lock id goes out of scope and is garbage collected in R or when the R process terminates or crashes. However, it is good practice to explicitly call model_unlock when you don't need the lock anymore. If you want to check for informational purposes if the model is currently locked by another process, you can use the is_model_locked() function. Note however that you should never use is_model_locked() to coordinate access to the model folder. The return value of is_model_locked() is only a snapshot at the time when the function is run. Note additionally that is_model_locked() checks if the model is locked by another process. If you currently hold the lock of the model yourself, it will return FALSE.
model_lock(folder = ".", file = ".lock", timeout1 = 12, timeout2 = NULL, check_interval = NULL, oncluster = NULL) model_unlock(id, folder = NULL, file = NULL, oncluster = NULL) is_model_locked(folder = ".", file = ".lock")model_lock(folder = ".", file = ".lock", timeout1 = 12, timeout2 = NULL, check_interval = NULL, oncluster = NULL) model_unlock(id, folder = NULL, file = NULL, oncluster = NULL) is_model_locked(folder = ".", file = ".lock")
folder |
path to the model folder |
file |
file name of the lock file. Don't use the lock file for anything else (i.e. don't read or write or open the lock file). |
timeout1 |
Time in hours to wait for other processes to free the lock before giving up and exiting with an error. |
timeout2 |
deprecated setting which will be ignored. |
check_interval |
deprecated setting which will be ignored. |
oncluster |
deprecated setting which will be ignored. |
id |
lock id as returned by model_lock. |
model_lock returns the lock id which is needed to identify the lock in model_unlock.
Jan Philipp Dietrich, David Klein, Mika Pflüger
#lock folder id <- model_lock(tempdir()) #unlock folder model_unlock(id)#lock folder id <- model_lock(tempdir()) #unlock folder model_unlock(id)
This function creates you a module skeleton which you can use to easily create your own modules.
module.skeleton( number, name, types, modelpath = ".", modulepath = "modules/", includefile = "modules/include.gms", version = is.modularGAMS(modelpath, version = TRUE) )module.skeleton( number, name, types, modelpath = ".", modulepath = "modules/", includefile = "modules/include.gms", version = is.modularGAMS(modelpath, version = TRUE) )
number |
Number of your module, typically something between 0-99. Sorts the execution of your modules. Please use a number which is not used, yet. |
name |
Name of your module (please choose a short name). If you want to extend an existing module (add a new realisation) use the name of the existing one. |
types |
Vector of names for the different module types (e.g. "on" or "off"). If you want to extend an existing module (add a new realisation), put here the additional type(s) |
modelpath |
Path of the MAgPIE version that should be updated (main folder). |
modulepath |
Module path within MAgPIE (relative to the MAgPIE main folder) |
includefile |
Name and location of the file which includes all modules (relative to main folder) |
version |
version of the modular GAMS code structure (1 or 2) |
Module phases are automatically detected checking the main code of the model, but not checking code in modules. If you want to use additional phases which are only included within a module, you need to specify them manually by adding a comment into your gams code indicating that there is an additional phase. The syntax is "* !add_phase!: <phase>", e.g. "* !add_phase!: new_phase"
Jan Philipp Dietrich
# copy dummymodel to temporary directory and add new module "bla" file.copy(system.file("dummymodel",package="gms"),tempdir(), recursive = TRUE) model <- paste0(tempdir(),"/dummymodel") module.skeleton(number="03", name="bla", types=c("on","off"), modelpath=model)# copy dummymodel to temporary directory and add new module "bla" file.copy(system.file("dummymodel",package="gms"),tempdir(), recursive = TRUE) model <- paste0(tempdir(),"/dummymodel") module.skeleton(number="03", name="bla", types=c("on","off"), modelpath=model)
Function that applies interfaceplot for a whole model and
all its modules.
modules_interfaceplot( x = ".", modulepath = "modules", filetype = "png", targetfolder = NULL, writetable = TRUE, includeCore = FALSE, ... )modules_interfaceplot( x = ".", modulepath = "modules", filetype = "png", targetfolder = NULL, writetable = TRUE, includeCore = FALSE, ... )
x |
Either the object returned by |
modulepath |
Path to the modules folder |
filetype |
Filetype that should be used (e.g. "png" or "pdf") |
targetfolder |
Folder outputs should be written to. If set to NULL outputs will be added to corresponding module folders |
writetable |
Logical deciding whether a csv containing the interfaces should be written as well. |
includeCore |
Logical to create plot for core or not, default FALSE. |
... |
Optional arguments to |
A list with interface tables for each module
Jan Philipp Dietrich
Small function to build a consistent path-string based on folder, filename and filetype. The function makes sure that slashes and the dot for the file ending are set correctly (you can supply your folder name either with or without a tailing slash in it. It does not matter.
path(..., ftype = NULL)path(..., ftype = NULL)
... |
the folders and the file name that should be pasted to a file/folder path |
ftype |
file type |
A string containing the path combined of folder, filename and filetype
Jan Philipp Dietrich
Downloads a list of tgz files from a list of repos, merge them and publish it on another server
publish_data( input, name = NULL, target = Sys.getenv("PUBLISH_DATA_TARGET", unset = "."), ... )publish_data( input, name = NULL, target = Sys.getenv("PUBLISH_DATA_TARGET", unset = "."), ... )
input |
a vector of files to be downloaded or a cfg list with settings to be used (e.g. containing cfg$input, cfg$repositories). Settings in the config list will be overwritten by other arguments of this function if they are not set to NULL |
name |
name of the data to be published (will be used in as file name). If no name is given (default) source files will be published as is (separate tgz files with original name). |
target |
target the data should be published in (format user@server:/folder/path) If a target vector, or targets separated by "|" are provided the user will be asked interactively where the file should be written to. By default it will look for target information in the environment variable PUBLISH_DATA_TARGET |
... |
further options provided to |
Jan Philipp Dietrich
Reads header written in yaml format from a file
read_yaml_header(file, n = 20)read_yaml_header(file, n = 20)
file |
path to the file which contains the YAML header |
n |
Number of lines to be read (header must be part of these lines in order to be read) |
A list containing the read in information
Jan Philipp Dietrich
Reads all declarations given in a GAMS code and returns them.
readDeclarations( file, unlist = TRUE, types = c("scalar", "(positive |)variable", "parameter", "table", "equation", "set") )readDeclarations( file, unlist = TRUE, types = c("scalar", "(positive |)variable", "parameter", "table", "equation", "set") )
file |
A gams file or a vector containing GAMS code. |
unlist |
A logical indicating whether the output should be returned as a list separated by object type or a matrix. |
types |
of declarations to be read. |
Either a list of declared objects or a matrix containing object name, the sets the object depends on and the description.
Jan Philipp Dietrich
Reads the default configuration of the model. Uses default.cfg and the model's main gms
as the source as appropriate.
To read a configuration from YAML format, use loadConfig instead.
readDefaultConfig(path = ".", mainfile = "main.gms")readDefaultConfig(path = ".", mainfile = "main.gms")
path |
path of the main folder of the model |
mainfile |
filename of main model file, defaults to 'main.gms' |
A vector of parameter values and their names.
Mika Pflüger
Input: a file name or a character vector. Output: a character vector of the contents of the file, or the character vector unchanged.
readFileOrVector(file)readFileOrVector(file)
file |
A file name or a character vector. |
A character vector of the inputs of the file.
Mika Pflüger
Read values of given parameters from a given GAMS code section.
readParameterValues(code, parameters)readParameterValues(code, parameters)
code |
A vector with GAMS code. |
parameters |
A vector with GAMS parameter names |
The GAMS code section should contain statements of the form parameter = value; for all the given parameters.
A vector of values the parameters are set to with parameter names as names.
Mika Pflüger
Reads all setglobals given in a GAMS code and returns them.
readSetglobals(file)readSetglobals(file)
file |
A gams file or a vector containing GAMS code. |
A vector of values the setglobal variables are set to with setglobal variables as names.
Jan Philipp Dietrich
Reads all settings (parameters, globals, and their respective values) in the given GAMS code.
readSettings(file)readSettings(file)
file |
A gams file or a vector containing GAMS code. |
A vector of parameter values and their names.
Mika Pflüger
Function to replace a marked paragaph in a text file. Paragraph has to be marked in the text file with an initial "##### R SECTION START (SUBJECT) #####" and "##### R SECTION END (SUBJECT) #####" as ending. The number of # symbols can be chosen by the user, but there has to be at least one at the beginning and one at the end. Furthermore it is allowed to add further symbols at the beginning or the end of the line. "SUBJECT" is chosen by the user and is used for identification, if a text file has more than one R section.
replace_in_file( file, content, subject = "CODE", add = FALSE, addfile = FALSE, comment = "*" )replace_in_file( file, content, subject = "CODE", add = FALSE, addfile = FALSE, comment = "*" )
file |
a connection object or a character string describing the file, that should be manipulated. |
content |
the content that should be used as replacement stored as a vector of strings. Each vector component will be written as a line. |
subject |
A string used for identification of a paragraph. |
add |
Determines behavior when marking is missing in the code. add=FALSE will throw out an error, if the marking is missing, add="top" will add the markings automatically at the beginning of the file, add="bottom" or add=TRUE will do the same but at the end of the file. |
addfile |
Determines the behavior when the file does not exist. If addfile=TRUE, file will be created when missing. |
comment |
Symbol which is used to indicate a comment in the language the file is written that should be manipulated. Only relevant if add or addfile are used. |
Jan Philipp Dietrich
Saves config in YAML format so that it can be read in again via
loadConfig.
saveConfig(cfg, file = NULL)saveConfig(cfg, file = NULL)
cfg |
Input config which should be saved |
file |
A character string naming a file. If set to NULL the YAML output will be returned by the function. |
Jan Philipp Dietrich
cfg <- list(input = c(data1 = "blub.tgz", data2 = "bla.tgz"), mode = "default") saveConfig(cfg)cfg <- list(input = c(data1 = "blub.tgz", data2 = "bla.tgz"), mode = "default") saveConfig(cfg)
Functions which allows for interactive selection of scripts/files.
selectScript(folder = ".", ending = "R")selectScript(folder = ".", ending = "R")
folder |
Folder in which the files/scripts are located which should be selected from. |
ending |
File ending of the files to be selected (without dot) |
A vector of paths to files selected by the user
Jan Philipp Dietrich
setScenario is adapting a given config to a predefined scenario, meaning that all settings which are fixed for the given scenario are written to the config. Settings not defined by the scenario remain unchanged.
setScenario(cfg, scenario, scenario_config = "config/scenario_config.csv")setScenario(cfg, scenario, scenario_config = "config/scenario_config.csv")
cfg |
Input config which should be adapted to the given scenario |
scenario |
name of scenario (e.g. "SSP2"). Can also be a vector of scenarios. In this case scenario settings are applied in the given order |
scenario_config |
A data frame containing the scenario config table or the path where the scenario config table is stored. |
The updated config as a config list ready for further usage.
The scenario config table is a table which contains as columns the different scenarios and as rows the different settings. Empty entries for a given scenario-setting combination indicate that this setting is not defined by the scenario and should not be changed by set Scenario!
Jan Philipp Dietrich, Anastasis Giannousakis
Checks GAMS setglobals in code for consistency. Creates a warning if a setglobal command for an existing module is missing or a module is set to a realization which does not exist.
settingsCheck(path = ".", modulepath = "modules", fileName = "main.gms")settingsCheck(path = ".", modulepath = "modules", fileName = "main.gms")
path |
path of the main folder of the model |
modulepath |
path to the module folder relative to "path" |
fileName |
name of the file containing setglobals, relative to "path" |
Nothing is returned.
Jan Philipp Dietrich
This function merges GAMS code which is distributed over severals files into a single GAMS file. Optionally, it also embeds R scripts into the single GAMS file
singleGAMSfile( modelpath = ".", mainfile = "main.gms", output = "full.gms", embedRScripts = FALSE )singleGAMSfile( modelpath = ".", mainfile = "main.gms", output = "full.gms", embedRScripts = FALSE )
modelpath |
The path where the model is stored |
mainfile |
The path to the main gams file (relative to the model path) |
output |
Name of the single output GAMS file. |
embedRScripts |
If TRUE, R scripts called by GAMS via Execute are also embedded. Default FALSE |
Jan Philipp Dietrich, Anastasis Giannousakis
# copy dummymodel create single gms file out of it file.copy(system.file("dummymodel", package = "gms"), tempdir(), recursive = TRUE) model <- paste0(tempdir(), "/dummymodel") singlefile <- paste0(tempdir(), "/full.gms") singleGAMSfile(modelpath = model, output = singlefile)# copy dummymodel create single gms file out of it file.copy(system.file("dummymodel", package = "gms"), tempdir(), recursive = TRUE) model <- paste0(tempdir(), "/dummymodel") singlefile <- paste0(tempdir(), "/full.gms") singleGAMSfile(modelpath = model, output = singlefile)
Creates a tgz from all files in a directory
tardir(dir = ".", tarfile = "data.tgz")tardir(dir = ".", tarfile = "data.tgz")
dir |
directory from which the tar file should be generated |
tarfile |
name of the archive the data should be written to (tgz file) |
Jan Philipp Dietrich
# copy dummymodel to temporary directory and compress it file.copy(system.file("dummymodel",package="gms"),tempdir(), recursive = TRUE) model <- paste0(tempdir(),"/dummymodel") archive <- paste0(tempdir(),"/dummymodel.tgz") tardir(model,archive)# copy dummymodel to temporary directory and compress it file.copy(system.file("dummymodel",package="gms"),tempdir(), recursive = TRUE) model <- paste0(tempdir(),"/dummymodel") archive <- paste0(tempdir(),"/dummymodel.tgz") tardir(model,archive)
Creates GAMS code which stores automatically the levels and marginals of all equations and variables in time depending parameters.
update_fulldataOutput( modelpath = ".", modulepath = "modules", corepath = "core", loopset = "t" )update_fulldataOutput( modelpath = ".", modulepath = "modules", corepath = "core", loopset = "t" )
modelpath |
Path of the Model version that should be updated (main folder). |
modulepath |
Module path within the model (relative to the model main folder) |
corepath |
Core path within the model (relative to the model main folder) |
loopset |
Set over which loop runs |
Jan Philipp Dietrich, Felicitas Beier
fulldataOutput,replace_in_file
A function that updates in the GAMS code all include commands which are related to Modules. The function automatically checks which modules exist and which files in these modules exist and creates the corresponding include commands in GAMS
update_modules_embedding( modelpath = ".", modulepath = "modules/", includefile = "modules/include.gms", verbose = FALSE )update_modules_embedding( modelpath = ".", modulepath = "modules/", includefile = "modules/include.gms", verbose = FALSE )
modelpath |
Path to the model that should be updated (main folder). |
modulepath |
Module path within the model (relative to the model main folder) |
includefile |
Name and location of the file which includes all modules (relative to main folder) |
verbose |
Defines whether additional information should be printed or not. |
Module phases are automatically detected checking the main code of the model, but not checking code in modules. If you want to use additional phases which are only included within a module, you need to specify them manually by adding a comment into your gams code indicating that there is an additional phase. The syntax is "* !add_phase!: <phase>", e.g. "* !add_phase!: new_phase"
Jan Philipp Dietrich
# copy dummymodel to temporary directory and update module embedding file.copy(system.file("dummymodel", package="gms"), tempdir(), recursive = TRUE) model <- paste0(tempdir(),"/dummymodel") update_modules_embedding(model)# copy dummymodel to temporary directory and update module embedding file.copy(system.file("dummymodel", package="gms"), tempdir(), recursive = TRUE) model <- paste0(tempdir(),"/dummymodel") update_modules_embedding(model)
Function to update the mapping between interfaces and their origin modules.
updateInterfaceMapping(path = ".", modulepath = "modules")updateInterfaceMapping(path = ".", modulepath = "modules")
path |
path of the main folder of the model |
modulepath |
path to the module folder relative to "path" |
Jan Philipp Dietrich
Function to write a set declaration in GAMS syntax given either a a character vector or a data.frame (latter to represent a mapping set)
writeSets(sets, file = NULL)writeSets(sets, file = NULL)
sets |
a list of sets where every set is another list consisting of three entries: name (set name as character), desc (set description as character) and items (set elements, either as character vector or data.frame) |
file |
Name of the file the set declarations should be written to. If NULL the result will just be returned by the function. The file must exist and contain a line of the form "##### R SECTION START (SETS) #####" followed by a line of the form ##### R SECTION END (SETS) ##### to indicate the part of the file that should be replaced with the set declaration! |
set declaration in GAMS syntax
Jan Philipp Dietrich, Florian Humpenöder
countries <- c("DEU", "FRA", "ENG", "ITA", "NLD", "POL") map <- data.frame(region = rep(c("REG1","REG2"), 3), countries = countries) sets <- list(list(name = "countries", desc = "list of countries", items = countries), list(name = "country2region", desc = "mapping between countries and regions", items = map)) cat(writeSets(sets), sep="\n")countries <- c("DEU", "FRA", "ENG", "ITA", "NLD", "POL") map <- data.frame(region = rep(c("REG1","REG2"), 3), countries = countries) sets <- list(list(name = "countries", desc = "list of countries", items = countries), list(name = "country2region", desc = "mapping between countries and regions", items = map)) cat(writeSets(sets), sep="\n")