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 2-3 sec per IDD. Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD data in data.table::data.table format. Every IDD will be parsed and stored in four tables:

  • group: contains group index and group names.

  • class: contains class names and properties.

  • field: contains field names and field properties.

  • reference: contains cross-reference data of fields.

Usage

idd <- use_idd(ver)
idd$version()
idd$build()
idd$group_index(group = NULL)
idd$group_name()
idd$from_group(class)
idd$class_index(class = NULL, by_group = FALSE)
idd$class_name(index = NULL, by_group = FALSE)
idd$required_class_name()
idd$unique_class_name()
idd$extenesible_class_name()
idd$is_valid_group(group)
idd$is_valid_class(class)
idd$object_relation(class, direction = c("all", "ref_by", "ref_to"))
idd$object(class)
idd$objects(class)
idd$objects_in_relation(class, direction = c("ref_to", "ref_by"))
idd$objects_in_group(group)
idd$ClassName
idd[[ClassName]]
idd$to_table(class, all = FALSE)
idd$to_string(class, leading = 4L, sep_at = 29L, sep_each = 0L, all = FALSE)
idd$print()
print(idd)

Arguments

  • ver: A valid EnergyPlus IDD version, e.g. 8.8, "8.6.0".

  • idd: An Idd object.

  • group: A character vector of valid group names. For $objects_in_group(), a single string of valid group name.

  • index: An integer vector giving indexes of name appearance in the IDD file of specified classes.

  • class: A character vector of valid class names. For $object_relation() and $objects_in_relation(), a single string of valid class name.

  • ClassName: A single string of valid class name.

  • direciton: The relation direction to extract. Should be either "all", "ref_to" or "ref_by". For $objects_in_relation(), only "ref_to" and "ref_by" are acceptable.

  • all: If TRUE, all fields in specified classes are returned. If FALSE, only minimum required fields are returned. Default: FALSE.

  • leading: Leading spaces added to each field. Default: 4L.

  • sep_at: The character width to separate value string and field string. Default: 29L which is the same as IDF Editor.

  • sep_each: A single integer of how many empty strings to insert between different classes. Default: 0.

  • by_group: If TRUE, a list is returned which separates class indexes or names by the group they belongs to. Default: FALSE.

Detail

$version() returns the IDD version in numeric_version.

$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. If by_group is TRUE, a list is returned which separate class indexes by the group they belong to. Otherwise, an integer vector is returned.

$class_name() returns class names of specified class indexes. If by_group is TRUE, a list is returned which separate class names by the group they belong to. Otherwise, a character vector is returned.

$required_class_name() returns the names of all required classes.

$unique_class_name() returns the names of all unique-object 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 an IddObject of specified class.

$objects() returns a list of IddObjects of specified classes.

$object_relation() returns an IddRelation object which contains field data that have relation with specified class. For instance, if idd$object_relation("Class 1", "ref_to") gives results below:

-- Refer to Others ---------------------
  Class: <Class 1>
  +- Field: <1: Field 1>
  |  v~~~~~~~~~~~~~~~~~~
  |  \- Class: <Class 2>
  |     \- Field: <2: Field 2>
  |
  \- Field: <2: Field 2>

This means that Field 2 in class Class 1 does not refer to any other fields. But Field 1 in class Class 2 refers to Field 2 in class named Class 2.

$objects_in_relation() returns a list of IddObjects that have relations. The first element is always the IddObject of that class. If specified class does not have any relation with other classes, a list that only contains the IddObject of that class is returned. For instance, idd$objects_in_relation("Construction", "ref_to") will return a list of an IddObject of class Construction and also all IddObjects that class Construction refers to; similarly, idd$objects_in_relation("Construction", "ref_by") will return a list of an IddObject of class Construction and also all IddObjects that refer to class Construction.

$objects_in_group() returns a list of IddObjects of specified 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.

$to_table() returns a data.table that contains core data of specified class. It has 3 columns:

  • class: Character type. Class names.

  • index: Integer type. Field indexes.

  • field: Character type. Field names.

$to_string() returns empty objects of specified class in a character vector format. It is formatted exactly the same as in IDF Editor.

$print() prints basic info ob current Idd object, including version, build tag and total class number.

References

IDFEditor, OpenStudio utilities library

See also

IddObject class which provides detailed information of curtain class

Examples

if (FALSE) { # 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$object("SimulationControl") # OR idd$SimulationControl # OR idd[["SimulationControl"]] # IddObject of Construction and Material class idd$objects(c("Construction", "Material")) # show all classes that refer to Material class length(idd$object_relation("Material", "ref_by")) # IddObjects that refer to class Construction length(idd$objects_in_relation("Construction", "ref_by")) # IddObjects that class Construction refers to length(idd$objects_in_relation("Construction", "ref_to")) # All IddObjects in group Schedules length(idd$objects_in_group("Schedules")) # Extract core data of class Material and Construction idd$to_table(c("Material", "Construction")) # Get empty Material object and Construction object in a character vector idd$to_string(c("Material", "Construction")) }