ParametricJob class provides a prototype of conducting parametric analysis
of EnergyPlus simulations.
param <- param_job(idf, epw) param$seed() param$weater() param$apply_measure(measure, ..., .names = NULL) param$run(dir = NULL, wait = TRUE) param$kill() param$status() param$errors(info = FALSE) param$output_dir(which = NULL) param$locate_output(which = NULL, suffix = ".err", strict = TRUE) param$report_data_dict(which = NULL) param$report_data(which = NULL, key_value = NULL, name = NULL, year = NULL, tz = "GMT", case = "auto") param$tabular_data(which = NULL) job$clone(deep = FALSE) param$print()
param <- param_job(idf, epw)
Arguments
idf: Path to EnergyPlus IDF file or an Idf object.
epw: Path to EnergyPlus EPW file or an Epw object.
param$seed() param$weather()
$seed() will return the input Idf object.
$weather() will return the input Epw object.
param$apply_measure(measure, ..., .names = NULL)
$apply_measure() allows to apply a measure to an Idf and creates
parametric models for analysis. Basically, a measure is just a function
that takes an Idf object and other arguments as input, and returns a
modified Idf object as output. Use ... to supply different arguments
to that measure. Under the hook, mapply() is used to create multiple
Idfs according to the input values.
Arguments
measure: A function that takes an Idf and other arguments as input and
returns an Idf object as output.
...: Other arguments passed to that measure.
.names: A character vector of the names of parametric Idfs. If NULL,
the new Idfs will be named in format measure_name + number.
param$run(dir = NULL, wait = TRUE) param$kill() param$status() param$errors(info = FALSE) param$output_dir(which = NULL) param$locate_output(which = NULL, suffix = ".err", strict = TRUE) param$report_data_dict(which = NULL) param$report_data(which = NULL, key_value = NULL, name = NULL, year = NULL, tz = "GMT", case = "auto") param$tabular_data(which = NULL)
All those functions have the same meaning as in EplusJob class, except that they only return the results of specified simulations. Most arguments have the same meanings as in EplusJob class.
$run() runs the all parametric simulations in parallel. The number of
parallel EnergyPlus process can be controlled by
eplusr_option("num_parallel"). If wait is FALSE, then the job will be
run in the background. You can get updated job status by just print the
ParametricJob object.
$kill() kills the all background EnergyPlus processes that are current
running if possible. It only works when simulation runs in non-waiting
mode.
$status() returns a named list of values indicates the status of the job:
run_before: TRUE if the job has been run before. FALSE otherwise.
alive: TRUE if the job is still running in the background. FALSE
otherwise.
terminated: TRUE if the job was terminated during last
simulation. FALSE otherwise. NA if the job has not been run yet.
successful: TRUE if last simulation ended successfully. FALSE
otherwise. NA if the job has not been run yet.
changed_after: TRUE if the seed model has been modified since last
simulation. FALSE otherwise.
$output_dir() returns the output directory of specified simulations.
$locate_output() returns the path of a single output file of specified
simulations.
$report_data_dict() returns a data.table which contains all information
about report data for specified simulations. For details on the meaning
of each columns, please see "2.20.2.1 ReportDataDictionary Table" in
EnergyPlus "Output Details and Examples" documentation.
$report_data() extracts the report data in a data.table using key values
and variable names.
$tabular_data() extracts all tabular data in a data.table.
For $report_data_dict(), $report_data() and $tabular_data(), the
returned data.table has a Case column in the returned data.table that
indicates the names of parametric models.
Arguments
which: An integer vector of the indexes or a character vector or names of
parametric simulations. If NULL, which is the default, results of all
parametric simulations are returned.
dir: The parent output directory for all simulation. Outputs of each
simulation are placed in a separate folder under the parent directory.
wait: If TRUE, R will hang on and wait all EnergyPlus simulations
finish. If FALSE, all EnergyPlus simulations are run in the background.
Default: TRUE.
suffix: A string that indicates the file suffix of simulation output.
Default: ".err".
strict: If TRUE, it will check if the simulation was terminated, is
still running or the file exists or not. Default: TRUE.
key_value: A character vector to identify key name of the data. If
NULL, all keys of that variable will be returned. Default: NULL.
name: A character vector to specify the actual data name. If NULL, all
variables will be returned. Default: NULL.
year: The year of the date and time in column DateTime. If NULL, it
will be the current year. Default: NULL
tz: Time zone of date and time in column DateTime. Default: "GMT".
job$clone(deep = FALSE)
$clone() copies and returns the cloned job. Because ParametricJob uses
R6Class under the hook which has "modify-in-place" semantics, job_2 <- job_1 does not copy job_1 at all but only create a new binding to
job_1. Modify job_1 will also affect job_2 as well, as these two
are exactly the same thing underneath. In order to create a complete
cloned copy, please use $clone(deep = TRUE).
Arguments
deep: Has to be TRUE if a complete cloned copy is desired.
param$print() print(param)
$print() shows the core information of this ParametricJob, including the
path of seed model and weather, the version and path of EnergyPlus used
to run simulations, the measured that has been applied and parametric
models generated, and the simulation job status.
$print() is quite useful to get the simulation status, especially when
wait is FALSE in $run(). The job status will be updated and printed
whenever $print() is called.
Basically, it is a collection of multiple EplusJob objects. However, the
model is first parsed and the Idf object is stored internally, instead of
storing only the path of Idf in EplusJob class. Also, an object
in Output:SQLite with Option Type value of SimpleAndTabular will be
automatically created if it does not exists like Idf class.
# NOT RUN {
if (is_avail_eplus(8.8)) {
idf_name <- "1ZoneUncontrolled.idf"
epw_name <- "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
idf_path <- file.path(eplus_config(8.8)$dir, "ExampleFiles", idf_name)
epw_path <- file.path(eplus_config(8.8)$dir, "WeatherData", epw_name)
# create from local files
param_job(idf_path, epw_path)
# create from an Idf and an Epw object
param_job(read_idf(idf_path), read_epw(epw_path))
}
# }
Run the code above in your browser using DataLab