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.

See also

IddObject class which provides detailed information of curtain class

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/Rtmpy9RLgy.
#> IDD file found: '/tmp/Rtmpy9RLgy/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()
} # }