,
Ricarda Rosemann [aut] | Title: | Building sector model with heterogeneous renovation and construction of the stock |
|---|---|
| Description: | This building stock model represents residential and commercial buildings at customisable regional and temporal resolution. The building stock is quantified in floor area and distinguished by building type (SFH/MFH) and location (rural/urban). In each building category, construction cohorts are tracked explicitly. This allows to characterise buildings specifically for each subset of buildings. The evolution of the building stock follows from the flows of constructed, renovated and demolished buildings and is optimised under cost minimisation with a benefit for heterogeneity in the choice of construction and renovation alternatives. This benefit captures heterogeneity in the preferences of the agents and the building structure. |
| Authors: | Robin Hasse [aut, cre] ,
Ricarda Rosemann [aut] |
| Maintainer: | Robin Hasse <[email protected]> |
| License: | LGPL-3 |
| Version: | 0.5.9 |
| Built: | 2024-10-09 10:19:45 UTC |
| Source: | https://github.com/pik-piam/brick |
This building stock model represents residential and commercial buildings at customisable regional and temporal resolution. The building stock is quantified in floor area and distinguished by building type (SFH/MFH) and location (rural/urban). In each building category, construction cohorts are tracked explicitly. This allows to characterise buildings specifically for each subset of buildings. The evolution of the building stock follows from the flows of constructed, renovated and demolished buildings and is optimised under cost minimisation with a benefit for heterogeneity in the choice of construction and renovation alternatives. This benefit captures heterogeneity in the preferences of the agents and the building structure.
Maintainer: Robin Hasse [email protected] (ORCID)
Authors:
Ricarda Rosemann [email protected] (ORCID)
Useful links:
remove all records of temporal parameters that are outside of thist
and make zero values explicit by filling with EPS.
.cropParamsToThist(gdx, thist).cropParamsToThist(gdx, thist)
gdx |
character, file path to gdx |
thist |
numeric vector of historic periods |
Replace zeros in value column with the gams special value EPS. This way, the value is saved in gdx files by gams.
.explicitZero(x, value = "value").explicitZero(x, value = "value")
x |
data.frame |
value |
character, name of value column |
data.frame with explicit zeros in value column
Robin Hasse
used to select a specifc level or scenario from a data frame with alternative values.
.filterLevel(df, lvl, switchName = "", lvlCol = "level").filterLevel(df, lvl, switchName = "", lvlCol = "level")
df |
data.frame |
lvl |
value used to select rows |
switchName |
character, corresponding BRICK switch name (only used for more informative error message) |
lvlCol |
character, colname containing |
data.frame with selected rows without lvlCol
Search for config file in multiple steps. The file is found if
* config is a full file path already
* config is the name of a file in the config folder
* there is exactly one file in configFolder matching the pattern
passed via config
.findCfg(config, configFolder, isFinalCfg).findCfg(config, configFolder, isFinalCfg)
config |
character, config file, either a path to a yaml file or the name of the file in 'inst/config/' |
configFolder |
character, directory to search for configs. If NULL, the BRICK-internal config folder is used. |
isFinalCfg |
logical, is this the final config and not an intermediate? |
file path to config
Depending on what is passed via originGDX, this function returns the
file path if it exists, looks for recognised file names in the given
directory if it exists or looks for the latest run with the given name in the
outputFolder.
.findOriginGdxFile(originGdx, outputFolder).findOriginGdxFile(originGdx, outputFolder)
originGdx |
character, file path to run or gdx file used as historical or scenario name |
outputFolder |
directory of output folder, only required if
|
file path to origin gdx file
Just a check to get a helpful error if gamstransfer is missing. Once the
package is available on GitHub, it should be listed as a dependency and this
file can be removed. The check is disabled during contiunous integration (CI)
i.a. GitHub actions and during devtools:check which is called by
lucode2::buildLibrary.
.onLoad(libname, pkgname).onLoad(libname, pkgname)
libname |
not used |
pkgname |
not used |
Robin Hasse
Overwrite a named list with another named list. The result corresponds to the overwritten list unless a value is overwritten by the overwriting list.
.overwriteList(x, y, isFinalCfg, defaultCfgPath).overwriteList(x, y, isFinalCfg, defaultCfgPath)
x |
named list, provides the structure and default values that can be
overwritten by |
y |
named list, overwrites |
isFinalCfg |
logical, is this the final config and not an intermediate? |
defaultCfgPath |
character, path to default config. Only used for more helpful error message. |
This function is called recursively until the default config is reached. Therefor, the list structure will always correspond to the default config. No config based directly or indirectly on the default can have list keys that the default config doesn't have.
named list with the structure of x that is (partly)
overwritten by y.
Read yaml file from given path, check minimum requirement (title exists) and save the file path as a attribute.
.readCfg(file).readCfg(file)
file |
character, path to config file |
named list with config parameters
Add assumed intangible costs
addAssump(df, assumpFile)addAssump(df, assumpFile)
df |
data.frame for the cost of construction or renovation |
assumpFile |
character, file path to assumption file |
data frame with added intangible cost
Robin Hasse
Temporary function that prepares historic stock and flows for calibration
aggregateMatching(path, config, overwrite = FALSE)aggregateMatching(path, config, overwrite = FALSE)
path |
character, path to calibration run |
config |
named list, configuration of calibration run |
overwrite |
logical, should existing data be overwritten? |
This functionality will migrate to mredgebuidlings but this infrastructure requires more time to be developed.
Robin Hasse
This is meant to work with the installed package BRICK but also when loading
the package via devtools::load_all("path/to/brick")
brick.file(..., mustWork = TRUE)brick.file(..., mustWork = TRUE)
... |
character vectors, specifying subdirectory and files within brick |
mustWork |
if TRUE, an error is given if there are no matching files |
A character vector of positive length, containing the file paths
that matched ... in BRICK.
Robin Hasse
Check which output file was written and derive state of Gams run
checkGamsSuccess(path)checkGamsSuccess(path)
path |
character, path to search for gams output files |
If output.gdx was written, give success message.
If abort.gdx was written or no output file exists, stop with error message.
Ricarda Rosemann
Copy gams scripts to output folder
copyGamsFiles(path, overwrite = FALSE)copyGamsFiles(path, overwrite = FALSE)
path |
character vector with folders to write input data into |
overwrite |
logical, should existing input.gdx be overwritten? |
Robin Hasse
Copy history gdx to output folder
copyHistoryGdx( path, outputFolder = NULL, config, overwrite = FALSE, thistOnly = TRUE )copyHistoryGdx( path, outputFolder = NULL, config, overwrite = FALSE, thistOnly = TRUE )
path |
character vector with folders to write input data into |
outputFolder |
directory of output folder |
config |
named list with run configuration |
overwrite |
logical, should existing input.gdx be overwritten? |
thistOnly |
logical, crop temporal parameters to historic periods |
Robin Hasse
Copy initial gdx to output folder
copyInitialGdx(path, config, overwrite = FALSE)copyInitialGdx(path, config, overwrite = FALSE)
path |
character vector with folders to write input data into |
config |
named list with run configuration |
overwrite |
logical, should existing input.gdx be overwritten? |
Robin Hasse
Create a complete set of input data for the gams optimisation.
createInputData(path, config, overwrite = FALSE)createInputData(path, config, overwrite = FALSE)
path |
character vector with folders to write input data into |
config |
named list with run configuration |
overwrite |
logical, should existing input.gdx be overwritten? |
This function reads static input data according to the input data revision in the config and creates all required sets and parameters for the gams optimisation depending on the switches in the config.
Robin Hasse
Create data for reference matching
createMatchingData(path, config, overwrite = FALSE)createMatchingData(path, config, overwrite = FALSE)
path |
character vector with folders to run the model in |
config |
run configurations |
overwrite |
logical, should existing data be overwritten? |
Robin Hasse
Add all parameters to gams container based on config
createParameters(m, config, inputDir)createParameters(m, config, inputDir)
m |
gams Container, central object to store all data for input.gdx |
config |
named list with run configuration |
inputDir |
directory of input folder |
gams Container with parameters added
Robin Hasse
Create a folder for the model to run in and copy required gams files there.
createRunFolder( path, config = NULL, overwrite = FALSE, recursive = FALSE, showWarnings = TRUE )createRunFolder( path, config = NULL, overwrite = FALSE, recursive = FALSE, showWarnings = TRUE )
path |
character vector, containing |
config |
list with run configuration |
overwrite |
logical; Should exiting folders be overwritten? |
recursive |
logical; Should exiting folders be overwritten? |
showWarnings |
logical; Should exiting folders be overwritten? |
Robin Hasse
Add all sets to gams container based on config
createSets(m, config)createSets(m, config)
m |
gams Container, central object to store all data for input.gdx |
config |
named list with run configuration |
gams Container with sets added
Robin Hasse
Create a data frame that has a column for each set and the full crossing of all set entries as rows
expandSets(..., .m = NULL)expandSets(..., .m = NULL)
... |
gams sets |
.m |
gams Container with sets referenced in |
data.frame with full crossing of set entries
Robin Hasse
Search the given output folder for the run with the most recent time stamp and return the path to this run. If the output folder contains only one run, return its path, also if it does not contain a time stamp.
findLastRun(outputFolder)findLastRun(outputFolder)
outputFolder |
character, output folder to search in |
Ricarda Rosemann
Retrieve mapping file from BRICK
getBrickMapping( name, type = "sectoral", error.missing = TRUE, returnPathOnly = FALSE )getBrickMapping( name, type = "sectoral", error.missing = TRUE, returnPathOnly = FALSE )
name |
character, file name of the mapping file |
type |
character, Mapping type (e.g. "regional", or "sectoral") |
error.missing |
logical, return error if the file does not exist |
returnPathOnly |
logical, file name of the mapping file |
Robin Hasse
guess column names based on column values
guessColnames(x, m)guessColnames(x, m)
x |
data.frame with unknown column names |
m |
gams Conatiner with sets |
data.frame with guessed column names
Robin Hasse
Preparations of a model run, send the model to SLURM if desired
initModel( config = NULL, path = NULL, configFolder = NULL, outputFolder = "output", references = NULL, restart = FALSE, sendToSlurm = NULL, slurmQOS = NULL, tasksPerNode = NULL, timeLimit = NULL, tasks32 = FALSE )initModel( config = NULL, path = NULL, configFolder = NULL, outputFolder = "output", references = NULL, restart = FALSE, sendToSlurm = NULL, slurmQOS = NULL, tasksPerNode = NULL, timeLimit = NULL, tasks32 = FALSE )
config |
run configurations |
path |
character vector with folders to run the model in |
configFolder |
character, directory to search for configs. If NULL, the BRICK-internal config folder is used. |
outputFolder |
directory of output folder |
references |
named character vector of matching references |
restart |
logical or character vector of elements to be restarted. If FALSE (default), then no restart is initiated. If TRUE, then the run in the given path or the latest run is restarted with default settings. Allowed elements of the character vector are:
|
sendToSlurm |
boolean whether or not the run should be started via SLURM |
slurmQOS |
character, slurm QOS to be used |
tasksPerNode |
numeric, number of tasks per node to be requested |
timeLimit |
character, time limit of the slurm job given in the format hh:mm:ss |
tasks32 |
boolean whether or not the SLURM run should be with 32 tasks |
This function creates the run folder with the necessary config and gams files. It then either calls the function to start the model directly or passes the model to SLURM.
path (invisible)
Ricarda Rosemann
Checks whether slurm is available so that jobs can be submitted, e.g., via sbatch ....
isSlurmAvailable()isSlurmAvailable()
logical(1). Whether slurm is available.
Convert nested named list to long data.frame
listToDf(x, n = 1)listToDf(x, n = 1)
x |
named list with identical depth on each branch |
n |
Integer, number of nested function calls, leave default |
data.frame with column for each level of the named list
Robin Hasse
Load Input data from mredgebuildings
loadMadratData(config)loadMadratData(config)
config |
named list with run configuration |
directory of input folder
Robin Hasse
Helper function to turn a named list into a string appended to the gams command line call
makeHandle(lst, type = c("gams", "model"))makeHandle(lst, type = c("gams", "model"))
lst |
named list of flags |
type |
character, type of flags (either '"gams"' or '"model') |
Gams parameters are lower case flags and follow one minus '-'. Model switches are upper case flags and follow two minuses '–'.
character of flags
Robin Hasse
extract different periods from a given BRICK config
periodFromConfig(config, periodType)periodFromConfig(config, periodType)
config |
named list with run configuration |
periodType |
type of period(s) |
numeric vector with periods
Robin Hasse
Plot heat map of reference deviation
plotRefDeviation(path)plotRefDeviation(path)
path |
character; directory of output folder |
Robin Hasse
Plot an overview of the stock and flows
plotSummary(path, facet = "typ", showHistStock = FALSE, splitRen = FALSE)plotSummary(path, facet = "typ", showHistStock = FALSE, splitRen = FALSE)
path |
character, path to the run |
facet |
character, dimension to resolve as facets |
showHistStock |
logical, show given historic next to the modeled stock |
splitRen |
logical, plot renovation with identical replacement semi-transparent |
Robin Hasse
Read config file in yaml format
readConfig(config = NULL, configFolder = NULL, readDirect = FALSE)readConfig(config = NULL, configFolder = NULL, readDirect = FALSE)
config |
character, config file, either a path to a yaml file or the
name of the file in |
configFolder |
character, directory to search for configs. If NULL, the BRICK-internal config folder is used. |
readDirect |
logical, specify whether |
If no argument is given, the default config is used.
named list with run config
Robin Hasse
Read madrat input files from input folder
readInput(filename, dims, inputDir = NULL)readInput(filename, dims, inputDir = NULL)
filename |
character, filename |
dims |
character vector, column names |
inputDir |
character, directory of input folder |
data.frame with data of the given input file
Robin Hasse
Read symbol from gams container
readSymbol(x, symbol = NULL, selectArea = TRUE, stringAsFactor = TRUE)readSymbol(x, symbol = NULL, selectArea = TRUE, stringAsFactor = TRUE)
x |
gams Container, Parameter, Variable or Set |
symbol |
character, name of gams object if x is a Container else NULL |
selectArea |
logical, select area quantity and remove this dimension |
stringAsFactor |
logical, keep default factors from gams |
Robin Hasse
The mif file contains reporting variables for the given model run.
reportMif(path, file = NULL, tmpl = NULL)reportMif(path, file = NULL, tmpl = NULL)
path |
character, path to the run |
file |
character, path of mif file. If |
tmpl |
character, BRICK reporting template. There has to be a brickSets
mapping named with the same suffix: |
Robin Hasse
Run the gams model in a given directory.
runGams( path, gamsOptions = NULL, switches = NULL, fileName = "main.gms", gamsCall = "gams" )runGams( path, gamsOptions = NULL, switches = NULL, fileName = "main.gms", gamsCall = "gams" )
path |
character vector with folders to run gams in |
gamsOptions |
named list of GAMS options |
switches |
named list of model switches |
fileName |
character vector with gams file names |
gamsCall |
system command to call gams |
The file 'input.gdx' has to exist in the given directory.
Robin Hasse
Based on user input, construct the SLURM configuration string.
setSlurmConfig(slurmQOS, tasksPerNode = 16, tasks32 = FALSE, timeLimit = NULL)setSlurmConfig(slurmQOS, tasksPerNode = 16, tasks32 = FALSE, timeLimit = NULL)
slurmQOS |
string, name of the desired QOS (Quality of Service) |
tasksPerNode |
numeric, number of tasks per node to be requested |
tasks32 |
boolean, specify whether a node with 32 tasks should be requested |
timeLimit |
character, time limit of the slurm job given in the format hh:mm:ss |
Check if SLURM configuration is admissible.
string with SLURM configuration
Ricarda Rosemann
Run the model with given configuration.
startModel(path)startModel(path)
path |
character vector with folders to run the model in |
This function creates a run folder with necessary gams files if missing. It then computes the input data and finally runs the optimisation.
Robin Hasse
Missing periods are interpolated linearly and extrapolated constantly, additional periods are removed and all other dimensions are filtered to the elements dined in the model sets.
toModelResolution(x, m, value = "value")toModelResolution(x, m, value = "value")
x |
data.frame with temporal dimension |
m |
gams Container with sets as known dimensions |
value |
character, name of value column |
data.frame with temporal resolution according to model
Robin Hasse