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 four tables:
group: contains group index and group names.
class: contains class names and properties.
class_reference: contains reference names of classes.
field: contains field names and field properties.
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$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.
$object 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.