eplusr provides parsing of and programmatic access to EnergyPlus
Input Data Dictionary (IDD) files, and objects. It contains all data needed
to parse EnergyPlus models. Idd class provides parsing and printing while
IddObject provides detailed information of curtain class.
EnergyPlus operates off of text input files written in its own Input Data File (IDF) format. IDF files are similar to XML files in that they are intended to conform to a data schema written using similar syntax. For XML, the schema format is XSD; for IDF, the schema format is IDD. For each release of EnergyPlus, valid IDF files are defined by the "Energy+.idd" file shipped with the release.
eplusr tries to detect all installed EnergyPlus in default installation
locations when loading, i.e. C:\EnergyPlusVX-X-0 on Windows,
/usr/local/EnergyPlus-X-Y-0 on Linux, and
/Applications/EnergyPlus-X-Y-0 on macOS and stores all found locations
internally. This data is used to locate the distributed "Energy+.idd" file of
each EnergyPlus version. And also, every time an IDD file is parsed, an Idd
object is created and cached in an environment.
Parsing an IDD file starts from use_idd(). When using use_idd(), eplusr
will first try to find the cached Idd object of that version, if possible.
If failed, and EnergyPlus of that version is available (see avail_eplus()),
the "Energy+.idd" distributed with EnergyPlus will be parsed and cached. So
each IDD file only needs to be parsed once and can be used when parsing every
IDF file of that version.
Internally, the powerful data.table
package is used to speed up the whole IDD parsing process and store the
results. However, it will still take about 3-4 sec per IDD. Under the hook,
eplusr uses a SQL-like structure to store both IDF and IDD data in
data.frame format. Every IDD will be parsed and stored in twelve tables:
group: contains group index and group names.
class: contains class names and properties.
class_memo: contains class memos, i.e. a brief description on each class.
class_reference: contains reference names of classes.
field: contains field names and field properties.
field_note: contains field notes.
field_reference: contains reference names of fields.
field_default: contains default values of fields.
field_choice: contains choices of choice-type fields.
field_range: contains range data of fields.
field_object_list: contains object-list data of fields.
field_external_list: contains external-list data of fields.
idd$version() idd$build() idd$group_index(group = NULL) idd$group_name() idd$is_valid_group(group) idd$from_group(class) idd$class_index(class = NULL) idd$class_name() idd$is_valid_class(class) idd$required_class_name() idd$unique_class_name() idd$extenesible_class_name() idd$object(class) idd$object_in_group(group) idd$ClassName idd[[ClassName]] idd$clone(deep = FALSE) idd$print() print(idd)
idd: An Idd object.
group: A valid group name or valid group names.
class: A valid class name or valid class names.
ClassName: A single length character vector of one valid class name.
$version() returns the version string.
$build() returns the build tag string.
$group_index() returns integer indexes (indexes of name appearance in
the IDD file) of specified groups.
$group_name() returns all group names.
$from_group() returns the names of group that specified classes belongs to.
$is_valid_group() return TRUE if the input is a valid group name.
$class_index() returns integer indexes (indexes of name appearance in
the IDD file) of specified classes.
$class_name() returns all class names.
$required_class_name() returns the names of all required classes.
$unique_class_name() returns the names of all unique classes.
$extensible_class_name() returns the names of all extensible classes.
$is_valid_class() return TRUE if the input is a valid class name.
$objectN returns a list of IddObjects of specified classes.
$object_in_group() returns a list of IddObjects in that group.
eplusr also provides custom S3 method of $ and [[ to make it
more convenient to get a single IddObject. Basically, idd$ClassName and
idd[[ClassName]], is equivalent to idd$object(ClassName)[[1]].
Here, ClassName is a single valid class name where all characters other
than letters and numbers are replaced by a underscore _.
For details about IddObject, please see IddObject class.
$clone() copies and returns the cloned Idd object. Because Idd uses
R6Class under the hook which has "modify-in-place" semantics, idd_2 <- idd_1 does not copy idd_1 at all but only create a new binding to idd_1.
Modify idd_1 will also affect idd_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).
IddObject class which provides detailed information of curtain class
# NOT RUN {
# get the Idd object of EnergyPlus v8.8
idd <- use_idd(8.8, download = "auto")
# version
idd$version()
# build
idd$build()
# all group names
str(idd$group_name())
# all class names
str(idd$class_name())
# all required class names
str(idd$required_class_name())
# all unique class names
str(idd$unique_class_name())
# IddObject of SimulationControl class
idd$SimulationControl
# OR
idd[["SimulationControl"]]
# }
Run the code above in your browser using DataLab