Idd: Parse, Query and Modify EnergyPlus Input Data Dictionary...

Description Overview Usage Arguments Detail Author(s) References See Also Examples

Description

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.

Overview

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:

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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)

Arguments

Detail

$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).

Author(s)

Hongyuan Jia

References

IDFEditor OpenStudio utilities library

See Also

IddObject class which provides detailed information of curtain class

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 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"]]

hongyuanjia/eplusr documentation built on Oct. 14, 2018, 10:59 a.m.