Parse, Query and Modify EnergyPlus Input Data Dictionary (IDD)

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.

References

IDFEditor, OpenStudio utilities library

Author

Hongyuan Jia

Methods

Method `new()`

Create an Idd object

Usage

Idd$new(path, encoding = "unknown")

Arguments

path: Either a path, a connection, or literal data (either a single string or a raw vector) to an EnergyPlus Input Data Dictionary (IDD). If a file path, that file usually has a extension .idd.
encoding: The file encoding of input IDD. Should be one of "unknown", "Latin-1" and "UTF-8". The default is "unknown"` which means that the file is encoded in the native encoding.

Details

It takes an EnergyPlus Input Data Dictionary (IDD) as input and returns an Idd object.

It is suggested to use helper use_idd() which supports to directly take a valid IDD version as input and search automatically the corresponding file path.

Returns

An Idd object.

Examples

\dontrun{Idd$new(file.path(eplus_config(8.8)$dir, "Energy+.idd"))

# Preferable way
idd <- use_idd(8.8, download = "auto")
}

Method `version()`

Get the version of current Idd

Usage

Idd$version()

Details

$version() returns the version of current Idd in a base::numeric_version() format. This makes it easy to direction compare versions of different Idds, e.g. idd$version() > 8.6 or idd1$version() > idd2$version().

Returns

A base::numeric_version() object.

Examples

\dontrun{
# get version
idd$version()
}

Method `build()`

Get the build tag of current Idd

Usage

Idd$build()

Details

$build() returns the build tag of current Idd. If no build tag is found, NA is returned.

Returns

A base::numeric_version() object.

Examples

\dontrun{
# get build tag
idd$build()
}

Method `path()`

Get the file path of current Idd

Usage

Idd$path()

Details

$path() returns the full path of current Idd or NULL if the Idd object is created using a character vector and not saved locally.

Returns

NULL or a single string.

Examples

\dontrun{
# get path
idd$path()
}

Method `group_name()`

Get names of groups

Usage

Idd$group_name()

Details

$group_name() returns names of groups current Idd contains.

Returns

A character vector.

Examples

\dontrun{
# get names of all groups Idf contains
idd$group_name()
}

Method `from_group()`

Get the name of group that specified class belongs to

Usage

Idd$from_group(class)

Arguments

class: A character vector of valid class names in current Idd.

Details

$from_group() returns the name of group that specified class belongs to.

Returns

A character vector.

Examples

\dontrun{
idd$from_group(c("Version", "Schedule:Compact"))
}

Method `class_name()`

Get names of classes

Usage

Idd$class_name(index = NULL, by_group = FALSE)

Arguments

index: An integer vector of class indices.
by_group: If TRUE, a list is returned which separates class names by the group they belong to. Default: FALSE.

Details

$class_name() returns names of classes current Idd contains

Returns

A character vector if by_group is FALSE and a list of character vectors when by_group is TRUE.

Examples

\dontrun{
# get names of the 10th to 20th class
idd$class_name(10:20)

# get names of all classes in Idf
idd$class_name()

# get names of all classes grouped by group names in Idf
idd$class_name(by_group = TRUE)
}

Method `required_class_name()`

Get the names of required classes

Usage

Idd$required_class_name()

Details

$required_class_name() returns the names of required classes in current Idd. "Require" means that for any Idf there should be at least one object.

Returns

A character vector.

Examples

\dontrun{
idd$required_class_name()
}

Method `unique_class_name()`

Get the names of unique-object classes

Usage

Idd$unique_class_name()

Details

$unique_class_name() returns the names of unique-object classes in current Idd. "Unique-object" means that for any Idf there should be at most one object in those classes.

Returns

A character vector.

Examples

\dontrun{
idd$unique_class_name()
}

Method `extensible_class_name()`

Get the names of classes with extensible fields

Usage

Idd$extensible_class_name()

Details

$extensible_class_name() returns the names of classes with extensible fields in current Idd. "Extensible fields" indicate fields that can be added dynamically, such like the X, Y and Z vertices of a building surface.

Returns

A character vector.

Examples

\dontrun{
idd$extensible_class_name()
}

Method `group_index()`

Get the indices of specified groups

Usage

Idd$group_index(group = NULL)

Arguments

group: A character vector of valid group names.

Details

$group_index() returns the indices of specified groups in current Idd. A group index is just an integer indicating its appearance order in the Idd.

Returns

An integer vector.

Examples

\dontrun{
idd$group_index()
}

Method `class_index()`

Get the indices of specified classes

Usage

Idd$class_index(class = NULL, by_group = FALSE)

Arguments

class: A character vector of valid class names.
by_group: If TRUE, a list is returned which separates class names by the group they belong to. Default: FALSE.

Details

$class_index() returns the indices of specified classes in current Idd. A class index is just an integer indicating its appearance order in the Idd.

Returns

An integer vector.

Examples

\dontrun{
idd$class_index()
}

Method `is_valid_group()`

Check if elements in input character vector are valid group names.

Usage

Idd$is_valid_group(group)

Arguments

group: A character vector to check.

Details

$is_valid_group() returns TRUEs if given character vector contains valid group names in the context of current Idd, and FALSEs otherwise.

Note that case-sensitive matching is performed, which means that "Location and Climate" is a valid group name but "location and climate" is not.

Returns

A logical vector with the same length as input character vector.

Examples

\dontrun{
idd$is_valid_group(c("Schedules", "Compliance Objects"))
}

Method `is_valid_class()`

Check if elements in input character vector are valid class names.

Usage

Idd$is_valid_class(class)

Arguments

class: A character vector to check.

Details

$is_valid_class() returns TRUEs if given character vector contains valid class names in the context of current Idd, and FALSEs otherwise.

Note that case-sensitive matching is performed, which means that "Version" is a valid class name but "version" is not.

Returns

A logical vector with the same length as input character vector.

Examples

\dontrun{
idd$is_valid_class(c("Building", "ShadowCalculation"))
}

Method `object()`

Extract an IddObject object using class index or name.

Usage

Idd$object(class)

Arguments

class: A single integer specifying the class index or a single string specifying the class name.

Details

$object() returns an IddObject object specified by a class ID or name.

Note that case-sensitive matching is performed, which means that "Version" is a valid class name but "version" is not.

For convenience, underscore-style names are allowed, e.g. Site_Location is equivalent to Site:Location.

Returns

An IddObject object.

Examples

\dontrun{
idd$object(3)

idd$object("Building")
}

Method `objects()`

Extract multiple IddObject objects using class indices or names.

Usage

Idd$objects(class)

Arguments

class: An integer vector specifying class indices or a character vector specifying class names.

Details

$objects() returns a named list of IddObject objects using class indices or names. The returned list is named using class names.

Note that case-sensitive matching is performed, which means that "Version" is a valid class name but "version" is not.

For convenience, underscore-style names are allowed, e.g. Site_Location is equivalent to Site:Location.

Returns

A named list of IddObject objects.

Examples

\dontrun{
idd$objects(c(3,10))

idd$objects(c("Version", "Material"))
}

Method `object_relation()`

Extract the relationship between class fields.

Usage

Idd$object_relation(
  which,
  direction = c("all", "ref_to", "ref_by"),
  class = NULL,
  group = NULL,
  depth = 0L
)

Arguments

which: A single integer specifying the class index or a single string specifying the class name.
direction: The relation direction to extract. Should be one of "all", "ref_to" or "ref_by".
class: A character vector of class names used for searching relations. Default: NULL.
group: A character vector of group names used for searching relations. Default: NULL.
depth: If > 0, the relation is searched recursively. A simple example of recursive reference: one material named mat is referred by a construction named const, and const is also referred by a surface named surf. If NULL, all possible recursive relations are returned. Default: 0.

Details

Many fields in Idd can be referred by others. For example, the Outside Layer and other fields in Construction class refer to the Name field in Material class and other material related classes. Here it means that the Outside Layer field refers to the Name field and the Name field is referred by the Outside Layer.

$object_relation() provides a simple interface to get this kind of relation. It takes a single class index or name and also a relation direction, and returns an IddRelation object which contains data presenting such relation above. For instance, if idd$object_relation("Construction", "ref_to") gives results below:

-- Refer to Others ---------------------------
  Class: <Construction>
  |- Field: <02: Outside Layer>
  |  v~~~~~~~~~~~~~~~~~~~~~~~~~
  |  |- Class: <Material>
  |  |  \- Field: <1: Name>
  |  |
  |  |- Class: <Material:NoMass>
  |  |  \- Field: <1: Name>
  |  |
  |  |- Class: <Material:InfraredTransparent>
  |  |  \- Field: <1: Name>
  |  |
  ......

This means that the value of field Outside Layer in class Construction can be one of values from field Name in class Material, field Name in class Material:NoMass, field Name in class Material:InfraredTransparent and etc. All those classes can be further easily extracted using $objects_in_relation() method described below.

Returns

An IddRelation object, which is a list of 3 data.table::data.table()s named ref_to and ref_by. Each data.table::data.table() contains 12 columns.

Examples

\dontrun{
# check each construction layer's possible references
idd$object_relation("Construction", "ref_to")

# check where construction being used
idd$object_relation("Construction", "ref_by")
}

Method `objects_in_relation()`

Extract multiple IddObject objects referencing each others.

Usage

Idd$objects_in_relation(
  which,
  direction = c("ref_to", "ref_by"),
  class = NULL,
  group = NULL,
  depth = 0L
)

Arguments

which: A single integer specifying the class index or a single string specifying the class name.
direction: The relation direction to extract. Should be either "ref_to" or "ref_by".
class: A character vector of valid class names in the current Idd. It is used to restrict the classes to be returned. If NULL, all possible classes are considered and corresponding IddObject objects are returned if relationships are found. Default: NULL.
group: A character vector of valid group names in the current Idd. It is used to restrict the groups to be returned. If NULL, all possible groups are considered and corresponding IddObject objects are returned if relationships are found. Default: NULL.
depth: If > 0, the relation is searched recursively. A simple example of recursive reference: one material named mat is referred by a construction named const, and const is also referred by a surface named surf. If NULL, all possible recursive relations are returned. Default: 0.

Details

$objects_in_relation() returns a named list of IddObject objects that have specified relationship with given class. The first element of returned list is always the specified class itself. If that class does not have specified relationship with other classes, a list that only contains specified class itself is returned.

For instance, idd$objects_in_relation("Construction", "ref_by") will return a named list of an IddObject object named Construction and also all other IddObject objects that can refer to field values in class Construction. Similarly, idd$objects_in_relation("Construction", "ref_to") will return a named list of an IddObject object named Construction and also all other IddObject objects that Construction can refer to.

Returns

An named list of IddObject objects.

Examples

\dontrun{
# get class Construction and all classes that it can refer to
idd$objects_in_relation("Construction", "ref_to")

# get class Construction and all classes that refer to it
idd$objects_in_relation("Construction", "ref_by")
}

Method `objects_in_group()`

Extract all IddObject objects in one group.

Usage

Idd$objects_in_group(group)

Arguments

group: A single string of valid group name for current Idd object.

Details

$objects_in_group() returns a named list of all IddObject objects in specified group. The returned list is named using class names.

Returns

A named list of IddObject objects.

Examples

\dontrun{
# get all classes in Schedules group
idd$objects_in_group("Schedules")
}

Method `to_table()`

Format Idd classes as a data.frame

Usage

Idd$to_table(class, all = FALSE)

Arguments

class: A character vector of class names.
all: If TRUE, all available fields defined in IDD for specified class will be returned. Default: FALSE.

Details

$to_table() returns a data.table that contains basic data of specified classes. The returned data.table has 3 columns:

class: Character type. Current class name.
index: Integer type. Field indexes.
field: Character type. Field names.

Returns

A data.table with 3 columns.

Examples

\dontrun{
# extract data of class Material
idd$to_table(class = "Material")

# extract multiple class data
idd$to_table(c("Construction", "Material"))
}

Method `to_string()`

Format Idf classes as a character vector

Usage

Idd$to_string(class, leading = 4L, sep_at = 29L, sep_each = 0L, all = FALSE)

Arguments

class: A character vector of class names.
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.
all: If TRUE, all available fields defined in IDD for specified class will be returned. Default: FALSE.

Details

$to_string() returns the text format of specified classes. The returned character vector can be pasted into an IDF file as empty objects of specified classes.

Returns

A character vector.

Examples

\dontrun{
# get text format of class Material
head(idd$to_string(class = "Material"))

# get text format of multiple class
idd$to_string(c("Material", "Construction"))

# tweak output formatting
idd$to_string(c("Material", "Construction"), leading = 0, sep_at = 0, sep_each = 5)
}

Method `print()`

Print Idd object

Usage

Idd$print()

Details

$print() prints the Idd object giving the information of version, build tag and total class numbers.

Returns

The Idd object itself, invisibly.

Examples

\dontrun{
idd$print()
}

Examples


## ------------------------------------------------
## Method `Idd$new`
## ------------------------------------------------

if (FALSE) Idd$new(file.path(eplus_config(8.8)$dir, "Energy+.idd"))

# Preferable way
idd <- use_idd(8.8, download = "auto")
#> IDD v8.8.0 has not been parsed before.
#> Try to locate 'Energy+.idd' in EnergyPlus v8.8.0 installation folder '/usr/local/EnergyPlus-8-8-0'.
#> Failed to locate 'Energy+.idd' because EnergyPlus v8.8.0 is not available.
#> Starting to download the IDD file from EnergyPlus GitHub repo...
#> EnergyPlus v8.8.0 IDD file 'V8-8-0-Energy+.idd' has been successfully downloaded into /tmp/Rtmp1xAVhR.
#> IDD file found: '/tmp/Rtmp1xAVhR/V8-8-0-Energy+.idd'.
#> Start parsing...
#> Parsing completed.
 # \dontrun{}


## ------------------------------------------------
## Method `Idd$version`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get version
idd$version()
} # }


## ------------------------------------------------
## Method `Idd$build`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get build tag
idd$build()
} # }


## ------------------------------------------------
## Method `Idd$path`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get path
idd$path()
} # }


## ------------------------------------------------
## Method `Idd$group_name`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get names of all groups Idf contains
idd$group_name()
} # }


## ------------------------------------------------
## Method `Idd$from_group`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$from_group(c("Version", "Schedule:Compact"))
} # }


## ------------------------------------------------
## Method `Idd$class_name`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get names of the 10th to 20th class
idd$class_name(10:20)

# get names of all classes in Idf
idd$class_name()

# get names of all classes grouped by group names in Idf
idd$class_name(by_group = TRUE)
} # }


## ------------------------------------------------
## Method `Idd$required_class_name`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$required_class_name()
} # }


## ------------------------------------------------
## Method `Idd$unique_class_name`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$unique_class_name()
} # }


## ------------------------------------------------
## Method `Idd$extensible_class_name`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$extensible_class_name()
} # }


## ------------------------------------------------
## Method `Idd$group_index`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$group_index()
} # }


## ------------------------------------------------
## Method `Idd$class_index`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$class_index()
} # }


## ------------------------------------------------
## Method `Idd$is_valid_group`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$is_valid_group(c("Schedules", "Compliance Objects"))
} # }


## ------------------------------------------------
## Method `Idd$is_valid_class`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$is_valid_class(c("Building", "ShadowCalculation"))
} # }


## ------------------------------------------------
## Method `Idd$object`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$object(3)

idd$object("Building")
} # }


## ------------------------------------------------
## Method `Idd$objects`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$objects(c(3,10))

idd$objects(c("Version", "Material"))
} # }


## ------------------------------------------------
## Method `Idd$object_relation`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# check each construction layer's possible references
idd$object_relation("Construction", "ref_to")

# check where construction being used
idd$object_relation("Construction", "ref_by")
} # }


## ------------------------------------------------
## Method `Idd$objects_in_relation`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get class Construction and all classes that it can refer to
idd$objects_in_relation("Construction", "ref_to")

# get class Construction and all classes that refer to it
idd$objects_in_relation("Construction", "ref_by")
} # }


## ------------------------------------------------
## Method `Idd$objects_in_group`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get all classes in Schedules group
idd$objects_in_group("Schedules")
} # }


## ------------------------------------------------
## Method `Idd$to_table`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# extract data of class Material
idd$to_table(class = "Material")

# extract multiple class data
idd$to_table(c("Construction", "Material"))
} # }


## ------------------------------------------------
## Method `Idd$to_string`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get text format of class Material
head(idd$to_string(class = "Material"))

# get text format of multiple class
idd$to_string(c("Material", "Construction"))

# tweak output formatting
idd$to_string(c("Material", "Construction"), leading = 0, sep_at = 0, sep_each = 5)
} # }


## ------------------------------------------------
## Method `Idd$print`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idd$print()
} # }

Parse, Query and Modify EnergyPlus Input Data Dictionary (IDD)

Overview

References

See also

Author

Methods

Public methods

Method new()

Usage

Arguments

Details

Returns

Examples

Method version()

Usage

Details

Returns

Examples

Method build()

Usage

Details

Returns

Examples

Method path()

Usage

Details

Returns

Examples

Method group_name()

Usage

Details

Returns

Examples

Method from_group()

Usage

Arguments

Details

Returns

Examples

Method class_name()

Usage

Arguments

Details

Returns

Examples

Method required_class_name()

Usage

Details

Returns

Examples

Method unique_class_name()

Usage

Details

Returns

Examples

Method extensible_class_name()

Usage

Details

Returns

Examples

Method group_index()

Usage

Arguments

Details

Returns

Examples

Method class_index()

Usage

Arguments

Details

Returns

Examples

Method is_valid_group()

Usage

Arguments

Details

Returns

Examples

Method is_valid_class()

Usage

Method `new()`

Method `version()`

Method `build()`

Method `path()`

Method `group_name()`

Method `from_group()`

Method `class_name()`

Method `required_class_name()`

Method `unique_class_name()`

Method `extensible_class_name()`

Method `group_index()`

Method `class_index()`

Method `is_valid_group()`

Method `is_valid_class()`

Method `object()`

Method `objects()`

Method `object_relation()`

Method `objects_in_relation()`

Method `objects_in_group()`

Method `to_table()`

Method `to_string()`

Method `print()`