eplusr provides parsing EnergyPlus Input Data File (IDF) files and strings in a hierarchical structure, which was extremely inspired by OpenStudio utilities library, but with total different data structure under the hook.
eplusr uses Idf class to present the whole IDF file and use IdfObject
to present a single object in IDF. Both Idf and IdfObject contain member
functions for helping modify the data in IDF so it complies with the
underlying IDD (EnergyPlus Input Data Dictionary).
Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD
data in data.frame format. To speed up the whole process, the
data.table::data.table() is used instead of the base data.frame. Every
IDF is parsed and stored in four tables:
object: contains object IDs and names.
value: contains field values.
comment: contains object comments.
value_reference: contains cross-reference of field values.
IDD file is parsed and stored in a similar structure. For details, please see Idd class.
So to modify an EnergyPlus model in eplusr is equal to change the data in those four tables accordingly, in the context of specific IDD data.
All IDF reading process starts with read_idf() which returns an Idf
object. The model will be printed in a similar style you see in IDFEditor,
with additional heading lines show the Path, Version of the model. The
classes of objects in the model are ordered by group and the number of
objects in classes are shown in square bracket.
# basic info model$version() model$path() model$group_name(all = FALSE) model$class_name(all = FALSE) model$is_valid_group(group, all = FALSE) model$is_valid_class(class, all = FALSE)
# definitaion model$definition(class)
# object info model$object_id(class = NULL, simplify = FALSE) model$object_name(class = NULL, simplify = FALSE) model$object_num(class = NULL) model$is_valid_id(id) model$is_valid_name(name)
# object query model$object(id) model$object_in_class(class) model$search_object(pattern, class = NULL) model$ClassName model[[ClassName]]
# model modification model$dup_object(object, new_name = NULL) model$add_object(class, value = NULL, comment = NULL, default = TRUE, all = FALSE) model$ins_object(object) model$set_object(object) model$del_object(object, referenced = FALSE) model$search_value(pattern) model$replace_value(pattern, replacement)
# model validation model$validate() model$is_valid
# model formatting model$string(comment = TRUE, header = TRUE, ...)
# model saving model$is_unsaved() model$save(path = NULL, format = c("sorted", "new_top", "new_bot"), overwrite = FALSE, copy_external = TRUE)
# model clone model$clone()
# run simulation model$run(weather = NULL, dir = NULL, wait = TRUE, force = FALSE)
# print model$print(plain = FALSE)
model$version() model$path() model$group_name(all = FALSE) model$class_name(all = FALSE) model$is_valid_group(group, all = FALSE) model$is_valid_class(class, all = FALSE)
$version will return the version of current model.
$path will return the path of current model or NULL if the model is
created using a character vector.
$group_name will return all groups the model contains when all is FALSE
or all groups the Idd contains when all is TRUE.
$class_name will return all classes the model contains when all is FALSE
or all classes the Idd contains when all is TRUE.
$is_valid_group will return TRUEs if given group names are valid for
current model (when all is FALSE) or current Idd (when all is
TRUE).
$is_valid_class will return TRUEs if given class names are valid for
current model (when all is FALSE) or current Idd (when all is
TRUE).
Arguments
all: If FALSE, only values in current model will be returned. If
TRUE, all values in Idd will be returned. Default: FALSE.
group: A character vector contains group names.
class: A character vector contains class names.
model$definition(class)
$definition will return the definitions, i.e. the IddObjects, of given
classes which contain all data used for parsing IdfObjects. For details
of IdfObject, please see IddObject class.
Arguments
class: A character vector contains class names.
model$object_id(class = NULL, simplify = FALSE) model$object_name(class = NULL, simplify = FALSE) model$object_num(class = NULL) model$is_valid_id(id) model$is_valid_name(name)
$object_id and $object_name will return all object IDs and names
in specified class respectively. For $object_name, if the specified
class does not have name attributes, such as SimulationContrl, NA
will be returned.
$is_valid_id and $is_valid_name will return TRUEs if given integers or
strings are valid object IDs or object names respectively.
$object_num will return the number of objects in specified classes.
Arguments
id: An integer vector to check.
name: A character vector to check.
class: A character vector contains valid class names.
simplify: If FALSE, a list with each member being the data per class will
be returned. Otherwise, an integer vector (for $object_id) or a
character vector (for $object_name) will be returned.
model$object(which) model$object_in_class(class) model$search_object(pattern, class = NULL) model$ClassName model[[ClassName]]
$object will return a list of IdfObjects specified by object IDs or
names.
$object_in_class will return a list of all IdfObjects in specified
classes.
$search_object will return a list of IdfObjects whose names meet the
given pattern in specified classes.
eplusr also provides custom S3 method of $ and [[ to make it more
convenient to get IdfObjects in class. Basically, model$ClassName and
model[[ClassName]], where ClassName is a single valid class name, is
equivalent to model$object_in_class(ClassName).
All above methods will return a named list of IdfObjects. If the class does
not have name attribute, then NA will be used.
IdfObject is a class that provides more detailed information methods to
modify a single object in an Idf object. For detailed explanations,
please see IdfObject class.
Arguments
object: Either an integer vector of valid object IDs or a character vector
of valid object names.
class: A character vector of valid class names.
pattern: A regular expression. It will be directly passed to
stringr::str_detect.
ClassName: A single length character vector of one valid class name,
where all characters other than letters and numbers are replaced by a
underscore _.
model$dup_object(object, new_name = NULL) model$add_object(class, value = NULL, comment = NULL, default = TRUE, all = FALSE) model$ins_object(object) model$set_object(object) model$del_object(object, referenced = FALSE) model$search_value(pattern) model$replace_value(pattern, replacement)
$dup_object will duplicate objects specified by object IDs or names. The
newly created objects will be renamed automatically if new names are not
given, with a suffix "_1", "_2" and etc.
$add_object will add objects in the specified class.
$ins_object will insert objects from other IDF into current IDF.
$set_object will set the value of fields in the objects specified by object
IDs or names.
$del_object will delete objects specified by object IDs or names.
$search_value will return values that match the given pattern.
$replace_value will return replace values that match the given pattern.
Arguments
object: Either an integer vector of valid object IDs or a character vector
of valid object names.
new_name: A character vector with the same length as the number of
objects to be duplicated.
value: A list which contains field values to set to the newly created
objects. The class of each field value should comply with the definition
in corresponding IDD. Field names of value in each class can be given. If
not named, the input values will be set to fields according to their
order of appearance.
comment: A list which contains comments to set to the newly created
objects.
default: If TRUE, all empty fields will be filled with their default
values if possible.
all: If TRUE, all fields in the class will be returned, even if there
are no input values for them. If FALSE, only minimum fields will be
returned.
referenced: If TRUE, all objects that reference the targets to delete
will also be deleted.
pattern: A regular expression used to search for values.
replacement: A regular expression used to replace values.
model$validate() model$is_valid()
$validate will check if there are errors in current model under different
strictness level.
$is_valid will check if there are no errors in current model under different
strictness level.
The strictness level can be changed using eplusr_option(). Default is
"final".There are three different validate levels, i.e. "none",
"draft" and "final":
For "none", none validation will be done;
For "draft", checking of invalid autosize, autocalculate, numeric,
integer, and choice field values will be done;
For "final", besides above, checking of missing required objects,
duplicated unique objects, object name conflicts, missing required fields
and invalid field value reference will also be done.
model$string(comment = TRUE, header = TRUE)
$string will return the text format of an IDF file.
Arguments
comment: If FALSE, all comments will not be included.
header: If FALSE, the header will not be included.
model$is_unsaved()
model$save(path = NULL, format = c("asis", "sorted", "new_top", "new_bot"), overwrite = FALSE, copy_external = TRUE)
$is_unsaved() will check if there are modifications on the model since it was
read or since last time it was saved.
$save() will save the model into local disk.
Arguments
path: A path where to save the model. If NULL, the path of the model
itself will be used.
format: A string to specify the saving format. Should be one of "asis",
"sorted", "new_top", and "new_bot". If "asis", which is the default, the
model will be saved in the same format as it is. If the model does not
contain any format saving option, which is typically the case when the
model was not saved using eplusr or IDFEditor, "sorted" will be used.
"sorted", "new_top" and "new_bot" are the same as the save options
"Sorted", "Original with New at Top", and "Original with New at Bottom"
in IDFEditor.
overwrite: Whether to overwrite the file if it already exists. Default is
FALSE.
copy_external: If TRUE, the external files will also be copied into the
same directory. Currently, only Schedule:File class is supported.
Default is FALSE.
model$clone(deep = FALSE)
$clone will copy and returned the cloned model. Because Idf use
R6Class under the hook, idf_2 <- idf_1 does not copy idf_1 at all but
only create a new binding to idf_1. Modify idf_1 will also affect idf_2
as well, as these two are exactly the same thing underneath.
Arguments
deep: Not used. Keep it here just for compatible with the default clone
method provided by R6Class.
model$run(weather, dir = NULL, wait = TRUE, force = FALSE)
$run will run the current model within specified weather using
corresponding version of EnergyPlus. The model and the weather used will
be copied to the output directory. An EplusJob will be returned which
provides detailed info of the simulation and methods to collect
simulation results. Please see eplus_job() for more detailed.
eplusr uses the EnergyPlus command line interface which was introduced since
EnergyPlus 8.3.0. So $run only supports models with version higher
than 8.3.0.
eplusr uses the EnergyPlus SQL output for extracting simulation results. In
order to do so, a object in Output:SQLite with Option Type value of
SimpleAndTabular will be automatically created if it does not exists.
Arguments
weather: A path to an .epw file or an Epw object.
dir: The directory to save the simulation results. If NULL, which is
the default, the model folder will be used.
echo: Whether to print the standard output and error of EnergyPlus to
the screen. Default is FALSE.
force: Whether to stop the background EnergyPlus process and start the
simulation again.
model$print(plain = FALSE) print(model)
$print will print the model in the similar format as what you will see in
IDFEditor.
Arguments
plain: If TRUE, the model will be printed in plain text format.