Idf {eplusr}R Documentation

Read, Modify, and Run an EnergyPlus Model

Description

eplusr provides parsing EnergyPlus Input Data File (IDF) files and strings in a hierarchical structure, which was extremely inspired by OpenStudio utilities library, but with total different data structure under the hook.

Details

eplusr uses Idf class to present the whole IDF file and use IdfObject to present a single object in IDF. Both Idf and IdfObject contain member functions for helping modify the data in IDF so it complies with the underlying IDD (EnergyPlus Input Data Dictionary).

Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD data in different data.table::data.tables. So to modify an EnergyPlus model in eplusr is equal to change the data in those IDF tables accordingly, in the context of specific IDD data. This means that a corresponding Idd object is needed whenever creating an Idf object. eplusr provides several helpers to easily download IDD files and create Idd objects.

All IDF reading process starts with function read_idf() which returns an Idf object. Idf class provides lots of methods to programmatically query and modify EnergyPlus models.

Internally, the powerful data.table package is used to speed up the whole IDF parsing process and store the results. Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD data in data.table::data.table format. Every IDF will be parsed and stored in three tables:

Methods

Public methods

Method new()

Create an Idf object

Usage
Idf$new(path, idd = NULL, 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 File (IDF). If a file path, that file usually has a extension .idf.

idd

Any acceptable input of use_idd(). If NULL, which is the default, the version of IDF will be passed to use_idd(). If the input is an .ddy file which does not have a version field, the latest version of Idf cached will be used.

encoding

The file encoding of input IDF. 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 File (IDF) as input and returns an Idf object.

Currently, Imf file is not fully supported. All EpMacro lines will be treated as normal comments of the nearest downwards object. If input is an Imf file, a warning will be given during parsing. It is recommended to convert the Imf file to an Idf file and use ParametricJob class to conduct parametric analysis.

Returns

An Idf object.

Examples
\dontrun{
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8

# If neither EnergyPlus v8.8 nor Idd v8.8 was found, error will
# occur. If Idd v8.8 is found, it will be used automatically.
idf <- Idf$new(path_idf)

# argument `idd` can be specified explicitly using `use_idd()`
idf <- Idf$new(path_idf, idd = use_idd(8.8))

# you can set `download` arugment to "auto" in `use_idd()` if you
# want to automatically download corresponding IDD file when
# necessary
idf <- Idf$new(path_idf, use_idd(8.8, download = "auto"))

# Besides use a path to an IDF file, you can also provide IDF in literal
# string format
string_idf <-
    "
    Version, 8.8;
    Building,
        Building;                !- Name
    "

Idf$new(string_idf, use_idd(8.8, download = "auto"))
}

Method version()

Get the version of current Idf

Usage
Idf$version()
Details

⁠$version()⁠ returns the version of current Idf in a base::numeric_version() format. This makes it easy to direction compare versions of different Idfs, e.g. idf$version() > 8.6 or idf1$version() > idf2$version().

Returns

A base::numeric_version() object.

Examples
\dontrun{
# get version
idf$version()
}

Method path()

Get the file path of current Idf

Usage
Idf$path()
Details

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

Returns

NULL or a single string.

Examples
\dontrun{
# get path
idf$path()

# return `NULL` if Idf is not created from a file
Idf$new("Version, 8.8;\n")$path()
}

Method group_name()

Get names of groups

Usage
Idf$group_name(all = FALSE, sorted = TRUE)
Arguments
all

If FALSE, only names of groups in current Idf object will be returned. If TRUE, all group names in the underlying Idd will be returned. Default: FALSE.

sorted

Only applicable when all is FALSE. If TRUE, duplications in returned group or class names are removed, and unique names are further sorted according to their occurrences in the underlying Idd. Default: TRUE.

Details

⁠$group_name()⁠ returns names of groups current Idf contains or the underlying Idd object contains.

Returns

A character vector.

Examples
\dontrun{
# get names of all groups Idf contains
idf$group_name()

# get group name of each object in Idf
idf$group_name(sorted = FALSE)

# get names of all available groups in underlying Idd
idf$group_name(all = TRUE)
}

Method class_name()

Get names of classes

Usage
Idf$class_name(all = FALSE, sorted = TRUE, by_group = FALSE)
Arguments
all

If FALSE, only names of classes in current Idf object will be returned. If TRUE, all class names in the underlying Idd will be returned. Default: FALSE.

sorted

Only applicable when all is FALSE. If TRUE, duplications in returned group or class names are removed, and unique names are further sorted according to their occurrences in the underlying Idd. Default: TRUE.

by_group

Only applicable when all or sorted is TRUE. If TRUE, a list is returned which separates class names by the group they belong to.

Details

⁠$class_name()⁠ returns names of classes current Idf contains or the underlying Idd object 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 all classes in Idf
idf$class_name()

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

# get class name of each object in Idf
idf$class_name(sorted = FALSE)

# get names of all available classes in underlying Idd
idf$class_name(all = TRUE)

# get names of all available classes grouped by group names in
# underlying Idd
idf$class_name(all = TRUE, by_group = TRUE)
}

Method is_valid_group()

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

Usage
Idf$is_valid_group(group, all = FALSE)
Arguments
group

A character vector to check.

all

If FALSE, check if input characters are valid group names for current Idf. If TRUE, check if input characters are valid group names for underlying Idd. Default: FALSE

Details

⁠$is_valid_group()⁠ returns TRUEs if given character vector contains valid group names in the context of current Idf (when all is FALSE) or current underlying Idd (when all is TRUE).

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{
# check if input is a valid group name in current Idf
idf$is_valid_group(c("Schedules", "Compliance Objects"))

# check if input is a valid group name in underlying Idd
idf$is_valid_group(c("Schedules", "Compliance Objects"), all = TRUE)
}

Method is_valid_class()

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

Usage
Idf$is_valid_class(class, all = FALSE)
Arguments
class

A character vector to check.

all

If FALSE, check if input characters are valid class names for current Idf. If TRUE, check if input characters are valid class names for underlying Idd. Default: FALSE

Details

⁠$is_valid_class()⁠ returns TRUEs if given character vector contains valid class names in the context of current Idf (when all is FALSE) or current underlying Idd (when all is TRUE), 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{
# check if input is a valid class name in current Idf
idf$is_valid_class(c("Building", "ShadowCalculation"))

# check if input is a valid class name in underlying Idd
idf$is_valid_class(c("Building", "ShadowCalculation"), all = TRUE)
}

Method definition()

Get the IddObject object for specified class.

Usage
Idf$definition(class = NULL)
Arguments
class

A single string of valid class name in current Idd. If NULL, the underlying Idd object is returned. Default: NULL.

Details

⁠$definition()⁠ returns an IddObject of given class. IddObject contains all data used for parsing and creating an IdfObject. For details, please see IddObject class.

Returns

An IddObject object if class is not NULL or an Idd object if class is NULL.

Examples
\dontrun{
# get the IddObject object for specified class
idf$definition("Version")
}

Method object_id()

Get the unique ID for each object in specified classes in the Idf.

Usage
Idf$object_id(class = NULL, simplify = FALSE)
Arguments
class

A character vector that contains valid class names for current Idf object. If NULL, all classes in current Idf object are used. Default: NULL.

simplify

If TRUE, an integer vector contains object IDs of all specified classes is returned. If FALSE, a named list that contains object IDs for each specified class is returned. Default: FALSE.

Details

In Idf, each object is assigned with an integer as an universally unique identifier (UUID) in the context of current Idf. UUID is not reused even if the object associated is deleted.

⁠$object_id()⁠ returns an integer vector (when simplify is TRUE) or a named list (when simplify is FALSE) of integer vectors that contain object IDs in each specified class. The returned list is named using specified class names.

Returns

An integer vector (when simplify is TRUE) or a named list of integer vectors (when simplify is FALSE).

Examples
\dontrun{
# get IDs of all objects in current Idf object
idf$object_id()

# get IDs of all objects in current Idf object, and merge them into a
# single integer vector
idf$object_id(simplify = TRUE)

# get IDs of objects in class Version and Zone
idf$object_id(c("Version", "Zone"))

# get IDs of objects in class Version and Zone, and merge them into a
# single integer vector
idf$object_id(c("Version", "Zone"), simplify = TRUE)
}

Method object_name()

Get names for objects in specified classes in the Idf.

Usage
Idf$object_name(class = NULL, simplify = FALSE)
Arguments
class

A character vector that contains valid class names for current Idf. If NULL, all classes in current Idf are used. Default: NULL.

simplify

If TRUE, a character vector contains object names of all specified classes is returned. If FALSE, a named list that contains a character vector for each specified class is returned. Default: FALSE.

Details

In Idf, each object is assigned with a single string as the name for it, if the class it belongs to has name attribute, e.g. class RunPeriod, Material and etc. That name should be unique among all objects in that class. EnergyPlus will fail with an error if duplications are found among object names in a class.

⁠$object_name()⁠ returns a character vector (when simplify is TRUE) or a named list (when simplify is FALSE) of character vectors that contain object IDs in each specified class. The returned list is named using specified class names. If specified class does not have name attribute, NAs are returned.

Returns

A character vector (when simplify is TRUE) or a named list of character vectors (when simplify is FALSE).

Examples
\dontrun{
# get names of all objects in current Idf object
idf$object_name()

# get names of all objects in current Idf object, and merge them into
# a single character vector
idf$object_name(simplify = TRUE)

# get names of objects in class Version and Zone
idf$object_name(c("Version", "Zone"))

# get names of objects in class Version and Zone, and merge them into
# a single character vector
idf$object_name(c("Version", "Zone"), simplify = TRUE)
}

Method object_num()

Get number of objects in specified classes in the Idf object.

Usage
Idf$object_num(class = NULL)
Arguments
class

A character vector that contains valid class names for underlying Idd. If NULL, all classes in current Idf are used, and the total object number is returned. Default: NULL.

Details

⁠$object_num()⁠ returns an integer vector of object number in specified classes. 0 is returned if there is no object in that class.

Returns

An integer vector.

Examples
\dontrun{
# get total number of objects
idf$object_num()

# get number of objects in class Zone and Schedule:Compact
idf$object_num(c("Zone", "Schedule:Compact"))
}

Method is_valid_id()

Check if elements in input integer vector are valid object IDs.

Usage
Idf$is_valid_id(id, class = NULL)
Arguments
id

An integer vector to check.

class

A single string indicates the class where the objects to check against. If NULL, all classes in current Idf are used. Default: NULL.

Details

⁠$is_valid_id()⁠ returns TRUEs if given integer vector contains valid object IDs in current Idf object.

Returns

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

Examples
\dontrun{
idf$is_valid_id(c(51, 1000))
}

Method is_valid_name()

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

Usage
Idf$is_valid_name(name, class = NULL)
Arguments
name

A character vector to check.

class

A single string indicates the class where the objects to check against. If NULL, all classes in current Idf are used. Default: NULL.

Details

⁠$is_valid_name()⁠ returns TRUEs if given character vector contains valid object names in current Idf object.

Note that case-insensitive matching is performed, which means that "rOoF" is equivalent to "roof". This behavior is consistent in all methods that take object name(s) as input.

Returns

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

Examples
\dontrun{
idf$is_valid_name(c("Simple One Zone (Wireframe DXF)", "ZONE ONE", "a"))

# name matching is case-insensitive
idf$is_valid_name(c("simple one zone (wireframe dxf)", "zone one", "a"))
}

Method object()

Extract an IdfObject object using object ID or name.

Usage
Idf$object(which, class = NULL)
Arguments
which

A single integer specifying the object ID or a single string specifying the object name.

class

A character vector that contains valid class names for current Idf object used to locate objects. If NULL, all classes in current Idf object are used. Default: NULL.

Details

⁠$object()⁠ returns an IdfObject object specified by an object ID or name.

Note that unlike object ID, which is always unique across the whole Idf object, different objects can have the same name. If the name given matches multiple objects, an error is issued showing what objects are matched by the same name. This behavior is consistent in all methods that take object name(s) as input. In this case, it is suggested to directly use object ID instead of name.

Note that case-insensitive matching is performed for object names, which means that "rOoF" is equivalent to "roof". This behavior is consistent in all methods that take object name(s) as input.

Returns

An IdfObject object.

Examples
\dontrun{
# get an object whose ID is 3
idf$object(3)

# get an object whose name is "simple one zone (wireframe dxf)"
# NOTE: object name matching is case-insensitive
idf$object("simple one zone (wireframe dxf)")
}

Method objects()

Extract multiple IdfObject objects using object IDs or names.

Usage
Idf$objects(which)
Arguments
which

An integer vector specifying object IDs or a character vector specifying object names.

Details

⁠$objects()⁠ returns a named list of IdfObject objects using object IDS or names. The returned list is named using object names.

Note that unlike object ID, which is always unique across the whole Idf object, different objects can have the same name. If the name given matches multiple objects, an error is issued showing what objects are matched by the same name. This behavior is consistent in all methods that take object name(s) as input. In this case, it is suggested to directly use object ID instead of name.

Note that case-insensitive matching is performed for object names, which means that "rOoF" is equivalent to "roof". This behavior is consistent in all methods that take object name(s) as input.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# get objects whose IDs are 3 and 10
idf$objects(c(3,10))

# get objects whose names are "Simple One Zone (Wireframe DXF)" and "ZONE ONE"
# NOTE: object name matching is case-insensitive
idf$objects(c("Simple One Zone (Wireframe DXF)", "zone one"))
}

Method object_unique()

Extract the IdfObject in class with unique-object attribute.

Usage
Idf$object_unique(class)
Arguments
class

A single string of valid class name for current Idf object.

Details

For each version of an Idf object, the corresponding underlying Idd describe how many objects can be defined in each class. Classes that have unique-object attribute can only hold a single object, e.g. Version, SimulationControl and etc. ⁠$object_unique()⁠ can be used to directly return the IdfObject in one unique-object class. An error will be issued if there are multiple objects in that class or input class is not an unique-object class. This makes sure that ⁠$object_unique()⁠ always returns a single IdfObject.

Idf class also provides custom S3 method of $ and [[ to make it more convenient to get the IdfObject in unique-object class. Basically, idf$ClassName and idf[["ClassName"]], where ClassName is a single valid class name, is equivalent to idf$object_unique(ClassName) if ClassName is an unique-object class. For convenience, underscore-style names are allowed when using $, e.g. Site_Location is equivalent to Site:Location. For instance, idf$Site_Location and also idf[["Site_Location"]] will both return the IdfObjects in Site:Location class. Note that unlike ⁠$object_unique()⁠, idf$ClassName and idf[["ClassName"]] will directly return NULL instead of giving an error when ClassName is not a valid class name in current Idf object. This makes it possible to use is.null(idf$ClassName) to check if ClassName is a valid class or not.

Returns

An IdfObject object.

Examples
\dontrun{
# get the SimulationColtrol object
idf$object_unique("SimulationControl")

# S3 "[[" and "$" can also be used
idf$SimulationControl
idf[["SimulationControl"]]
}

Method objects_in_class()

Extract all IdfObject objects in one class.

Usage
Idf$objects_in_class(class)
Arguments
class

A single string of valid class name for current Idf object.

Details

⁠$objects_in_class()⁠ returns a named list of all IdfObject objects in specified class. The returned list is named using object names.

Idf class also provides custom S3 method of $ and [[ to make it more convenient to get all IdfObject objects in one class. Basically, idf$ClassName and idf[["ClassName"]], where ClassName is a single valid class name, is equivalent to idf$objects_in_class(ClassName) if ClassName is not an unique-object class. For convenience, underscore-style names are allowed, e.g. BuildingSurface_Detailed is equivalent to BuildingSurface:Detailed when using $. For instance, idf$BuildingSurface_Detailed and also idf[["BuildingSurface:Detailed"]] will both return all IdfObject objects in BuildingSurface:Detailed class. Note that unlike ⁠$objects_in_class()⁠, idf$ClassName and idf[["ClassName"]] will directly return NULL instead of giving an error when ClassName is not a valid class name in current Idf object. This makes it possible to use is.null(idf$ClassName) to check if ClassName is a valid class or not.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# get all objects in Zone class
idf$objects_in_class("Zone")

# S3 "[[" and "$" can also be used
idf$Zone
idf[["Zone"]]
}

Method objects_in_group()

Extract all IdfObject objects in one group.

Usage
Idf$objects_in_group(group)
Arguments
group

A single string of valid group name for current Idf object.

Details

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

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# get all objects in Schedules group
idf$objects_in_group("Schedules")
}

Method object_relation()

Extract the relationship between object field values.

Usage
Idf$object_relation(
  which,
  direction = c("all", "ref_to", "ref_by", "node"),
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L,
  keep = FALSE,
  class_ref = c("both", "none", "all")
)
Arguments
which

A single integer specifying object ID or a single string specifying object name.

direction

The relation direction to extract. Should be either "all", "ref_to", "ref_by" and "node".

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

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.

keep

If TRUE, all fields of specified object are returned regardless they have any relations with other objects or not. If FALSE, only fields in specified object that have relations with other objects are returned. Default: FALSE.

class_ref

Specify how to handle class-name-references. Class name references refer to references in like field ⁠Component 1 Object Type⁠ in Branch objects. Their value refers to other many class names of objects, instaed of referring to specific field values. There are 3 options in total, i.e. "none", "both" and "all", with "both" being the default. * "none": just ignore class-name-references. It is a reasonable option, as for most cases, class-name-references always come along with field value references. Ignoring class-name-references will not impact the most part of the relation structure. * "both": only include class-name-references if this object also reference field values of the same one. For example, if the value of field ⁠Component 1 Object Type⁠ is Coil:Heating:Water, only the object that is referenced in the next field ⁠Component 1 Name⁠ is treated as referenced by ⁠Component 1 Object Type⁠. This is the default option. * "all": include all class-name-references. For example, if the value of field ⁠Component 1 Object Type⁠ is Coil:Heating:Water, all objects in Coil:Heating:Water will be treated as referenced by that field. This is the most aggressive option.

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⁠. In EnergyPlus, there is also a special type of field called Node, which together with Branch, BranchList and other classes define the topography of the HVAC connections. A outlet node of a component can be referred by another component as its inlet node, but can also exists independently, such as zone air node.

⁠$object_relation()⁠ provides a simple interface to get this kind of relation. It takes a single object ID or name and also a relation direction, and returns an IdfRelation object which contains data presenting such relation above. For instance, if model$object_relation("WALL-1", "ref_to") gives results below: 

-- Refer to Others ------------------------
  Class: <Construction>
  \- Object [ID:2] <WALL-1>
     \- 2: "WD01";        !- Outside Layer
        v~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        \- Class: <Material>
           \- Object [ID:1] <WD01>
              \- 1: "WD01";        !- Name

This means that the value "WD01" of ⁠Outside Layer⁠ in a construction named WALL-1 refers to a material named WD01. All those objects can be further easily extracted using ⁠$objects_in_relation()⁠ method described below.

Returns

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

Examples
\dontrun{
# check each layer's reference of a construction named FLOOR
idf$object_relation("floor", "ref_to")

# check where is this construction being used
idf$object_relation("floor", "ref_by")
}

Method objects_in_relation()

Extract multiple IdfObject objects referencing each others.

Usage
Idf$objects_in_relation(
  which,
  direction = c("ref_to", "ref_by", "node"),
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L,
  class_ref = c("both", "none", "all")
)
Arguments
which

A single integer specifying object ID or a single string specifying object name.

direction

The relation direction to extract. Should be one of "ref_to", "ref_by" or "node".

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of valid class names in the underlying Idd. It is used to restrict the classes to be returned. If NULL, all possible classes are considered and corresponding IdfObject objects are returned if relationships are found. Default: NULL.

group

A character vector of valid group names in the underlying Idd. It is used to restrict the groups to be returned. If NULL, all possible groups are considered and corresponding IdfObject 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.

class_ref

Specify how to handle class-name-references. Class name references refer to references in like field ⁠Component 1 Object Type⁠ in Branch objects. Their value refers to other many class names of objects, instaed of refering to specific field values. There are 3 options in total, i.e. "none", "both" and "all", with "both" being the default. * "none": just ignore class-name-references. It is a reasonable option, as for most cases, class-name-references always come along with field value references. Ignoring class-name-references will not impact the most part of the relation structure. * "both": only include class-name-references if this object also reference field values of the same one. For example, if the value of field ⁠Component 1 Object Type⁠ is Coil:Heating:Water, only the object that is referenced in the next field ⁠Component 1 Name⁠ is treated as referenced by ⁠Component 1 Object Type⁠. This is the default option. * "all": include all class-name-references. For example, if the value of field ⁠Component 1 Object Type⁠ is Coil:Heating:Water, all objects in Coil:Heating:Water will be treated as referenced by that field. This is the most aggressive option.

Details

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

For instance, assuming that const is a valid object name in Construction class, idf$objects_in_relation("const", "ref_by", "BuildingSurface:Detailed") will return a named list of an IdfObject object named const and also all other IdfObject objects in BuildingSurface:Detailed class that refer to field values in const. Similarly, idf$objects_in_relation("const", "ref_to", "Material") will return a named list of an IdfObject object named const and also all other IdfObject objects in Material class that const refers to. This makes it easy to directly extract groups of related objects and then use ⁠$insert()⁠ method or other methods described below to insert them or extract data.

There are lots of recursive references in a model. For instance, a material can be referred by a construction, that construction can be referred by a building surface, and that building surface can be referred by a window on that surface. These objects related recursively can be extracted by setting recursive to TRUE.

Returns

An named list of IdfObject objects.

Examples
\dontrun{
# get a construction named FLOOR and all materials it uses
idf$objects_in_relation("floor", "ref_to")

# get a construction named FLOOR and all surfaces that uses it
idf$objects_in_relation("floor", "ref_by", class = "BuildingSurface:Detailed")
}

Method search_object()

Extract multiple IdfObject objects using regular expression on names.

Usage
Idf$search_object(
  pattern,
  class = NULL,
  ignore.case = FALSE,
  perl = FALSE,
  fixed = FALSE,
  useBytes = FALSE
)
Arguments
pattern, ignore.case, perl, fixed, useBytes

All are directly passed to base::grepl.

class

A character vector of valid class names in the underlying Idd. It is used to restrict the classes to be returned. If NULL, all possible classes are considered and corresponding IdfObject objects are returned if pattern is met Default: NULL.

Details

⁠$search_object()⁠ returns a named list of IdfObject objects whose names meet the given regular expression in specified classes.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# get all objects whose names contains "floor"
idf$search_object("floor", ignore.case = TRUE)
}

Method dup()

Duplicate existing objects.

Usage
Idf$dup(...)
Arguments
...

Integer vectors of object IDs and character vectors of object names. If input is named, its name will be used as the name of newly created objects.

Details

⁠$dup()⁠ takes integer vectors of object IDs and character vectors of object names, duplicates objects specified, and returns a list of newly created IdfObject objects. The names of input are used as new names for created IdfObjects. If input is not named, new names are the names of duplicated objects with a suffix "_1", "_2" and etc, depending on how many times that object has been duplicated. Note an error will be issued if trying to assign a new name to an object which belongs to a class that does not have name attribute.

Assigning newly added objects with an existing name in current Idf object is prohibited if current validation level includes object name conflicting checking. For details, please see level_checks().

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# duplicate an object named "FLOOR"
idf$dup("floor") # New object name 'FLOOR_1' is auto-generated

# duplicate that object again by specifing object ID
idf$dup(16) # New object name 'FLOOR_2' is auto-generated

# duplicate that object two times and giving new names
idf$dup(new_floor = "floor", new_floor2 = 16)

# duplicate that object multiple times using variable inputs
floors_1 <- c(new_floor3 = "floor", new_floor4 = "floor")
floors_2 <- setNames(rep(16, 5), paste0("flr", 1:5))
idf$dup(floors_1, floors_2)
}

Method add()

Add new objects.

Usage
Idf$add(..., .default = TRUE, .all = FALSE)
Arguments
...

Lists of object definitions. Each list should be named with a valid class name. There is a special element .comment in each list, which will be used as the comments of newly added object.

.default

If TRUE, default values are used for those blank fields if possible. If FALSE, empty fields are kept blank. Default: TRUE.

.all

If TRUE, all fields are added. If FALSE, only minimum required fields are added. Default: FALSE.

Details

⁠$add()⁠ takes new object definitions in list format, adds corresponding objects in specified classes, returns a list of newly added IdfObject objects. The returned list will be named using newly added object names. Every list should be named using a valid class name. Underscore-style class name is allowed for class name. Names in each list element are treated as field names. Values without names will be inserted according to their position. There is a special element named .comment in each list, which will be used as the comments of newly added object.

Empty objects can be added using an empty list, e.g. idf$add(Building = list()). All empty fields will be filled with corresponding default value if .default is TRUE, leaving other fields as blanks. However, adding blank objects may not be allowed if there are required fields in that class and current validate level includes missing-required-field checking. For what kind of validation components will be performed during adding new objects, please see level_checks().

Note that .() can be used as an alias as list(), e.g. idf$add(Building = .()) is equivalent to idf$add(Building = list()).

Field name matching is case-insensitive. For convenience, underscore-style field names are also allowed, e.g. eNd_MoNtH is equivalent to ⁠End Month⁠. This behavior is consistent among all methods that take field names as input.

There is no need to give all field values if only specific fields are interested, as long as other fields are not required. For example, to define a new object in RunPeriod class, the following is enough (at least for EnergyPlus v8.8): 

idf$add(
    RunPeriod = list(
        "my run period",
        begin_month = 1, begin_day_of_month = 1,
        end_month = 1, end_day_of_month = 31
    ),
    .default = TRUE
)

If not all field names are given, positions of those values without field names are determined after those values with names. E.g. in idf$add(Construction = list("out_layer", name = "name")), "out_layer" will be treated as the value for field ⁠Outside Layer⁠ in Construction class, since the value for field Name has been specified using explicit field name.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# add a new Building object with all default values
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .())

# add a new Building object with all default values and comments
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .(.comment = c("this is", "a new building")))

# add a new RunPeriod object with all possible fields
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = list(), RunPeriod = list("rp", 1, 1, 1, 31), .all = TRUE)

# add objects using variable inputs
empty <- empty_idf(8.8) # create an empty Idf
objs1 <- list(Schedule_Constant = list("const"), Building = list())
rp <- list(RunPeriod = list("rp", 2, 1, 2, 28))
empty$add(objs1, rp)
}

Method set()

Set values of existing objects.

Usage
Idf$set(..., .default = TRUE, .empty = FALSE)
Arguments
...

Lists of object definitions. Each list should be named with a valid object name or ID denoted in style ..ID. There is a special element .comment in each list, which will be used as new comments of modified object, overwriting existing comments if any.

.default

If TRUE, default values are used for those blank fields if possible. If FALSE, empty fields are kept blank. Default: TRUE.

.empty

If TRUE, trailing empty fields are kept. Default: FALSE.

Details

⁠$set()⁠ takes new field value definitions in list format, sets new values for fields in objects specified, and returns a list of modified IdfObjects. The returned list will be named using names of modified objects. Every list in ⁠$set()⁠ should be named with a valid object name. Object ID can also be used but have to be combined with prevailing two periods .., e.g. ..10 indicates the object with ID 10. Similar to $add(), a special element .comment in each list will be used as the new comments for modified object, overwriting the old ones. Names in list element are treated as field names.

Note that .() can be used as an alias as list(), e.g. idf$set(Building = .(...)) is equivalent to idf$set(Building = list(...)).

There is two special syntax in ⁠$set()⁠, which is inspired by the data.table package:

You can delete a field by assigning NULL to it, e.g. list(fld = NULL) means to delete the value of field fld, in the condition that .default is FALSE, fld is not a required field and the index of fld is larger than the number minimum fields required for that class. If those conditions are not required, fld will be left as blank if .default is FALSE or filled with default value if .default is TRUE.

By default, trailing empty fields that are not required will be removed and only minimum required fields are kept. For example, if rp is an object in RunPeriod class in an Idf of version 8.8, by default empty field with index larger than 11 will be removed since they are all non-required fields. You can keep the trailing empty fields by setting .empty to TRUE.

New fields that currently do not exist in that object can also be set. They will be automatically added on the fly.

Field name matching is case-insensitive. For convenience, underscore-style field names are also allowed, e.g. eNd_MoNtH is equivalent to ⁠End Month⁠.

If not all field names are given, positions of those values without field names are determined after those values with names. E.g. in idf$set(floor = list("out_layer", name = "name")), "out_layer" will be treated as the value for field ⁠Outside Layer⁠ in an object named floor, since the value for field Name has been specified using explicit field name.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# modify an object by name (case-insensitive)
idf$set(r13layer = list(roughness = "smooth"))

# modify an object by ID
idf$set(..12 = list(roughness = "rough"))

# overwrite existing object comments
idf$set(r13layer = list(.comment = c("New comment")))

# assign default values to fields
idf$set(r13layer = list(solar_absorptance = NULL), .default = TRUE)

# set field values to blanks
idf$set(r13layer = list(solar_absorptance = NULL), .default = FALSE)

# set field values to blank and delete trailing fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE)

# set field values to blank and keep blank fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE, .empty = TRUE)

# set all fields in one class
idf$set(Material_NoMass := list(visible_absorptance = 0.9))

# set multiple objects in one class
idf$set(.("r13layer", "r31layer") := list(solar_absorptance = 0.8))
# above is equivalent to
idf$set(r13layer = list(solar_absorptance = 0.8),
        r31layer = list(solar_absorptance = 0.8)
)

# use variable input
sets <- list(r13layer = list(roughness = "smooth"))
idf$set(sets)
}

Method del()

Delete existing objects

Usage
Idf$del(
  ...,
  .ref_by = FALSE,
  .ref_to = FALSE,
  .recursive = FALSE,
  .force = FALSE
)
Arguments
...

integer vectors of object IDs and character vectors of object names in current Idf object.

.ref_by

If TRUE, objects whose fields refer to input objects will also be deleted. Default: FALSE.

.ref_to

If TRUE, objects whose fields are referred by input objects will also be deleted. Default: FALSE.

.recursive

If TRUE, relation searching is performed recursively, in case that objects whose fields refer to target object are also referred by another object, and also objects whose fields are referred by target object are also referred by another object. Default: FALSE.

.force

If TRUE, objects are deleted even if they are referred by other objects.

Details

⁠$del()⁠ takes integer vectors of object IDs and character vectors of object names, and deletes objects specified.

If current validate level includes reference checking, objects will not be allowed to be deleted if they are referred by other objects. For example, an error will be issued if you want to delete one material that is referred by other constructions, because doing so will result in invalid field value references. You may bypass this if you really want to by setting .force to TRUE.

When .ref_by or .ref_to is TRUE, objects will be deleted only when they have and only have relation with input objects but not any other objects. For example, a construction const consist of 4 different materials. If .ref_to is TRUE, that 4 materials will only be deleted when they are only used in const, but not used in any other objects.

There are recursively reference relations in Idf object. For example, one material's name is referenced by one construction, and that construction's name can be referred by another surface. You can delete all of them by setting .recursive to TRUE.

If .ref_by is TRUE, objects whose fields refer to input objects will also be deleted.

IF .ref_to is TRUE, objects whose fields are referred by input objects will also be deleted.

Returns

The modified Idf object itself, invisibly.

Examples
\dontrun{
# delete objects using names
idf$object("Fraction") # ScheduleTypeLimits
idf$del("Fraction")

# delete objects using IDs
idf$objects(c(39, 40)) # Output:Variable
idf$del(39, 40)

# cannot delete objects that are referred by others
level_checks()$reference # reference-checking is enable by default
idf$del("r13layer") # error

# force to delete objects even thay are referred by others
idf$del("r13layer", .force = TRUE)

# delete objects and also objects that refer to them
idf$del("r31layer", .ref_by = TRUE) # Construction 'ROOF31' will be kept

# delete objects and also objects that they refer to
idf$del("extlights", .ref_to = TRUE) # Schedule 'AlwaysOn' will be kept

# delete objects and also other objects that refer to them recursively
idf$del("roof31", .ref_by = TRUE, .recursive = TRUE)

# delete objects using variable inputs
ids <- idf$object_id("Output:Variable", simplify = TRUE)
idf$del(ids)
}

Method purge()

Purge resource objects that are not used

Usage
Idf$purge(object = NULL, class = NULL, group = NULL)
Arguments
object

an integer vector of object IDs or a character vector of object names in current Idf object. Default: NULL.

class

A character vector of valid class names in current Idf object. Default: NULL.

group

A character vector of valid group names in current Idf object. Default: NULL.

Details

⁠$purge()⁠ takes an integer vector of object IDs or a character vectors of object names, and deletes resource objects specified that are not used by any objects.

Here resource objects indicate all objects that can be referenced by other objects, e.g. all schedules. ⁠$purge()⁠ will ignore any inputs that are not resources. If inputs contain objects from multiple classes, references among them are also taken into account, which means purging is performed hierarchically. If both materials and constructions are specified, the latter will be purged first, because it is possible that input constructions reference input materials.

Returns

The modified Idf object itself, invisibly.

Examples
\dontrun{
# purge unused "Fraction" schedule type
idf$purge("on/off") # ScheduleTypeLimits

# purge all unused schedule types
idf$purge(class = "ScheduleTypeLimits")

# purge all unused schedule related objects
idf$purge(group = "Schedules")
}

Method duplicated()

Determine duplicated objects

Usage
Idf$duplicated(object = NULL, class = NULL, group = NULL)
Arguments
object

an integer vector of object IDs or a character vector of object names in current Idf object. Default: NULL.

class

A character vector of valid class names in current Idf object. Default: NULL.

group

A character vector of valid group names in current Idf object. Default: NULL.

If all object, class and group are NULL, duplication checking is performed on the whole Idf.

Details

⁠$duplicated()⁠ takes an integer vector of object IDs or a character vectors of object names, and returns a data.table::data.table() to show whether input objects contain duplications or not.

Here duplicated objects refer to objects whose field values are the same except the names. Object comments are just ignored during comparison.

Returns

A data.table::data.table() of 4 columns:

Examples
\dontrun{
# check if there are any duplications in the Idf
idf$duplicated(class = "ScheduleTypeLimits")

# check if there are any duplications in the schedule types
idf$duplicated(class = "ScheduleTypeLimits")

# check if there are any duplications in the schedule groups and
# material class
idf$duplicated(class = "Material", group = "Schedules")
}

Method unique()

Remove duplicated objects

Usage
Idf$unique(object = NULL, class = NULL, group = NULL)
Arguments
object

an integer vector of object IDs or a character vector of object names in current Idf object. Default: NULL.

class

A character vector of valid class names in current Idf object. Default: NULL.

group

A character vector of valid group names in current Idf object. Default: NULL.

If all object, class and group are NULL, duplication checking is performed on the whole Idf.

Details

⁠$unique()⁠ takes an integer vector of object IDs or a character vectors of object names, and remove duplicated objects.

Here duplicated objects refer to objects whose field values are the same except the names. Object comments are just ignored during comparison.

⁠$unique()⁠ will only keep the first unique object and remove all redundant objects. Value referencing the redundant objects will be redirected into the unique object.

Returns

The modified Idf object itself, invisibly.

Examples
\dontrun{
# remove duplications in the Idf
idf$unique(class = "ScheduleTypeLimits")

# remove duplications in the schedule types
idf$unique(class = "ScheduleTypeLimits")

# remove duplications in the schedule groups and material class
idf$unique(class = "Material", group = "Schedules")
}

Method rename()

Rename existing objects

Usage
Idf$rename(...)
Arguments
...

Integer vectors of valid object IDs and character vectors of valid object names in current Idf object. Each element should be named. Names of input vectors are used as the new object names

Details

⁠$rename()⁠ takes named character vectors of object names and named integer vectors of object IDs, renames specified objects to names of input vectors and returns a list of renamed IdfObjects. The returned list will be named using names of modified objects. An error will be issued if trying to "rename" an object which does not have name attribute. When renaming an object that is referred by other objects, corresponding fields that refer to that object's name will also be changed accordingly.

Returns

A named list of renamed IdfObject objects.

Examples
\dontrun{
idf$objects(c("on/off", "test 352a"))
idf$rename(on_off = "on/off", test_352a = 51)
}

Method insert()

Insert new objects from IdfObjects

Usage
Idf$insert(..., .unique = TRUE, .empty = FALSE)
Arguments
...

IdfObjects or lists of IdfObjects from same version as current Idf object.

.unique

If there are duplications in input IdfObjects or there is same object in current Idf object, duplications in input are removed. Default: TRUE.

.empty

If TRUE, trailing empty fields are kept. Default: FALSE.

Details

⁠$insert()⁠ takes IdfObjects or lists of IdfObjects as input, inserts them into current Idf objects, and returns a list of inserted IdfObjects. The returned list will be named using names of inserted objects.

⁠$insert()⁠ is quite useful to insert objects from other Idf objects. However, you cannot insert an IdfObject which comes from a different version than current Idf object.

⁠$insert()⁠ will skip IdfObjects that have exactly same fields in current Idf object. If input IdfObject has the same name as one IdfObject in current Idf object but field values are not equal, an error will be issued if current validate level includes conflicted-name checking.

By default, trailing empty fields that are not required will be removed and only minimum required fields are kept. You can keep the trailing empty fields by setting .empty to TRUE.

Returns

A named list of inserted IdfObject objects.

Examples
\dontrun{
# insert all material from another IDF
path_idf2 <- file.path(eplus_config(8.8)$dir, "ExampleFiles/5ZoneTDV.idf")
idf2 <- Idf$new(path_idf2)
idf$insert(idf2$Material)

# insert objects from same Idf is equivalent to using Idf$dup()
idf$insert(idf$SizingPeriod_DesignDay)
}

Method load()

Load new objects from characters or data.frames

Usage
Idf$load(..., .unique = TRUE, .default = TRUE, .empty = FALSE)
Arguments
...

Character vectors or data.frames of object definitions.

.unique

If TRUE, and there are duplications in input IdfObjects or there is same object in current Idf object, duplications in input are removed. Default: TRUE.

.default

If TRUE, default values are filled for those blank fields if possible. Default: TRUE.

.empty

If TRUE, trailing empty fields are kept. Default: FALSE.

Details

⁠$load()⁠ is similar to $insert(), except it takes directly character vectors or data.frames as IdfObject definitions, insert corresponding objects into current Idf object and returns a named list of newly added IdfObjects. The returned list will be named using names of added objects. This makes it easy to create objects using the output from⁠$to_string()⁠ and ⁠$to_table()⁠ method from Idd, IddObject, also from Idf, and IdfObject, class.

For object definitions in character vector format, they follow the same rules as a normal IDF file:

Each character vector can contain:

You can also provide an option header to indicate if input objects are presented in IP units, using ⁠!-Option ViewInIPunits⁠. If this header does not exist, then all values are treated as in SI units.

For object definitions in data.frame format, it is highly recommended to use ⁠$to_table()⁠ method in Idd, Idd, IddObject, IddObject, Idf, and IdfObject, class to create an acceptable data.frame template. A valid definition requires at least three columns described below. Note that column order does not matter.

Note that ⁠$load()⁠ assumes all definitions are from the same version as current Idf object. If input definition is from different version, parsing error may occur.

By default, trailing empty fields that are not required will be removed and only minimum required fields are kept. You can keep the trailing empty fields by setting .empty to TRUE.

Returns

A named list of loaded IdfObject objects.

Examples
\dontrun{
# load objects from character vectors
idf$load(
    c("Material,",
      "    mat,                     !- Name",
      "    MediumSmooth,            !- Roughness",
      "    0.667,                   !- Thickness {m}",
      "    0.115,                   !- Conductivity {W/m-K}",
      "    513,                     !- Density {kg/m3}",
      "    1381;                    !- Specific Heat {J/kg-K}"),

    "Construction, const, mat;"
)

# load objects from data.frame definitions
dt <- idf$to_table(class = "Material")
dt[field == "Name", value := paste(value, 1)]
dt[field == "Thickness", value := "0.5"]
idf$load(dt)

# by default, duplications are removed
idf$load(idf$to_table(class = "Material"))

# keep empty fields as they are
idf$load("Material, mat1, smooth, 0.5, 0.2, 500, 1000,,, 0.5;", .default = FALSE)

# keep trailing empty fields
idf$load("Material, mat2, smooth, 0.5, 0.2, 500, 1000,,,;",
    .default = FALSE, .empty = TRUE
)
}

Method update()

Update existing object values from characters or data.frames

Usage
Idf$update(..., .default = TRUE, .empty = FALSE)
Arguments
...

Character vectors or data.frames of object definitions.

.default

If TRUE, default values are filled for those blank fields if possible. Default: TRUE.

.empty

If TRUE, trailing empty fields are kept. Default: FALSE.

Details

⁠$update()⁠ is similar to $set(), except it takes directly character vectors or data.frames as IdfObject definitions, updates new values for fields in objects specified, and returns a named list of modified IdfObjects. The returned list will be named using names of modified objects. This makes it easy to update object values using the output from ⁠$to_string()⁠ and ⁠$to_table⁠ method from Idf, and IdfObject, class.

The format of object definitions is similar to ⁠$load()⁠.

For object definitions in character vector format, object names are used to locate which objects to update. Objects that have name attribute should have valid names. This means that there is no way to update object names using character vector format, but this can be achieved using data.frame format as it uses object IDs instead of object names to locate objects. The format of acceptable characters follows the same rules as a normal IDF file:

Each character vector can contain:

You can also provide an option header to indicate if input objects are presented in IP units, using ⁠!-Option ViewInIPunits⁠. If this header does not exist, then all values are treated as in SI units.

For object definitions in data.frame format, it is highly recommended to use ⁠$to_table()⁠ method in Idf, and IdfObject, class to create an acceptable data.frame template. A valid definition requires three columns described below. Note that column order does not matter.

Note that ⁠$update()⁠ assumes all definitions are from the same version as current Idf object. If input definition is from different version, parsing error may occur.

By default, trailing empty fields that are not required will be removed and only minimum required fields are kept. You can keep the trailing empty fields by setting .empty to TRUE.

Returns

A named list of updated IdfObject objects.

Examples
\dontrun{
# update objects from string definitions:
str <- idf$to_string("zone one", header = FALSE, format = "new_top")
str[8] <- "2," # Multiplier
idf$update(str)

# update objects from data.frame definitions:
dt <- idf$to_table("zone one")
dt[field == "Multiplier", value := "1"]
idf$update(dt)
}

Method paste()

Paste new objects from IDF Editor

Usage
Idf$paste(in_ip = FALSE, ver = NULL, unique = TRUE, empty = FALSE)
Arguments
in_ip

Set to TRUE if the IDF file is open with Inch-Pound view option toggled. Numeric values will automatically converted to SI units if necessary. Default: FALSE.

ver

The version of IDF file open by IDF Editor, e.g. 8.6, "8.8.0". If NULL, assume that the file has the same version as current Idf object. Default: NULL.

unique

If TRUE, and there are duplications in copied objects from IDF Editor or there is same object in current Idf, duplications in input are removed. Default: TRUE.

empty

If TRUE, trailing empty fields are kept. Default: FALSE.

Details

⁠$paste()⁠ reads the contents (from clipboard) of copied objects from IDF Editor (after hitting ⁠Copy Obj⁠ button), inserts corresponding objects into current Idf object and returns a named list of newly added IdfObjects. The returned list will be named using names of added objects. As IDF Editor is only available on Windows platform, ⁠$paste()⁠ only works on Windows too.

There is no version data copied to the clipboard when copying objects in IDF Editor. ⁠$paste()⁠ assumes the file open in IDF Editor has the same version as current Idf object. This may not be always true. Please check the version before running ⁠$paste()⁠, or explicitly specify the version of file opened by IDF Editor using ver parameter. Parsing error may occur if there is a version mismatch.

By default, trailing empty fields that are not required will be removed and only minimum required fields are kept. You can keep the trailing empty fields by setting .empty to TRUE.

Returns

A named list of loaded IdfObject objects.

Method search_value()

Search objects by field values using regular expression

Usage
Idf$search_value(
  pattern,
  class = NULL,
  ignore.case = FALSE,
  perl = FALSE,
  fixed = FALSE,
  useBytes = FALSE
)
Arguments
pattern, ignore.case, perl, fixed, useBytes

All of them are directly passed to base::grepl and base::gsub.

class

A character vector of invalid class names in current Idf object to search for values. If NULL, all classes are used. Default: NULL.

Details

⁠$search_value()⁠ returns a list of IdfObjects that contain values which match the given pattern. If no matched found, NULL is returned invisibly. The returned list will be named using names of matched objects.

Note that during matching, all values are treated as characters, including numeric values.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# search values that contains "floor"
idf$search_value("floor", ignore.case = TRUE)

# search values that contains "floor" in class Construction
idf$search_value("floor", "Construction", ignore.case = TRUE)
}

Method replace_value()

Replace object field values using regular expression

Usage
Idf$replace_value(
  pattern,
  replacement,
  class = NULL,
  ignore.case = FALSE,
  perl = FALSE,
  fixed = FALSE,
  useBytes = FALSE
)
Arguments
pattern, replacement, ignore.case, perl, fixed, useBytes

All of them are directly passed to base::grepl and base::gsub.

class

A character vector of invalid class names in current Idf object to search for values. If NULL, all classes are used. Default: NULL.

Details

⁠$replace_value()⁠ returns a list of IdfObjects whose values have been replaced using given pattern. If no matched found, NULL is returned invisibly. The returned list will be named using names of matched objects.

Note that during matching, all values are treated as characters, including numeric values.

Modifying object values using regular expression is not recommended. Consider to use $set() and $update() if possible. Validation rules also apply during replacing.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# search values that contains "win" and replace them with "windows"
idf$replace_value("win", "windows")
}

Method validate()

Check possible object field value errors

Usage
Idf$validate(level = eplusr_option("validate_level"))
Arguments
level

One of "none", "draft", "final" or a list of 10 elements with same format as custom_validate() output.

Details

⁠$validate()⁠ checks if there are errors in current Idf object under specified validation level and returns an IdfValidity object. ⁠$validate()⁠ is useful to help avoid some common errors before running the model. By default, validation is performed when calling all methods that modify objects, e.g. $dup() $add(), $set(), $del(), and etc.

In total, there are 10 different validate checking components:

The level argument controls what checkings should be performed. level here is just a list of 10 element which specify the toggle status of each component. You can use helper custom_validate() to get that list and pass it directly to level.

There are 3 predefined validate level that indicates different combinations of checking components, i.e. none, draft and final. Basically, none level just does not perform any checkings; draft includes 5 components, i.e. auto_field, type, unique_name, choice and range; and final level includes all 10 components. You can always get what components each level contains using level_checks(). By default, the result from eplusr_option("validate_level") is passed to level. If not set, final level is used.

Underneath, an IdfValidity object which ⁠$validate()⁠ returns is a list of 13 element as shown below. Each element or several elements represents the results from a single validation checking component.

Except missing_object, which is a character vector of class names that are missing, all other elements are data.table with 9 columns containing data of invalid field values:

Knowing the internal structure of IdfValidity, it is easy to extract invalid IdfObjects you interested in. For example, you can get all IDs of objects that contain invalid value references using model$validate()$invalid_reference$object_id. Then using $set() method to correct them.

Different validate result examples are shown below:

Returns

An IdfValidity object.

Examples
\dontrun{
idf$validate()

# check at predefined validate level
idf$validate("none")
idf$validate("draft")
idf$validate("final")

# custom validate checking components
idf$validate(custom_validate(auto_field = TRUE, choice = TRUE))
}

Method is_valid()

Check if there is any error in current Idf

Usage
Idf$is_valid(level = eplusr_option("validate_level"))
Arguments
level

One of "none", "draft", "final" or a list of 10 elements with same format as custom_validate() output.

Details

⁠$is_valid()⁠ checks if there are errors in current Idf object under specified validation level and returns TRUE or FALSE accordingly. For detailed description on validate checking, see $validate() documentation above.

Returns

A single logical value of TRUE or FALSE.

Examples
\dontrun{
idf$is_valid()

# check at predefined validate level
idf$is_valid("none")
idf$is_valid("draft")
idf$is_valid("final")

# custom validate checking components
idf$is_valid(custom_validate(auto_field = TRUE, choice = TRUE))
}

Method to_string()

Format Idf as a character vector

Usage
Idf$to_string(
  which = NULL,
  class = NULL,
  comment = TRUE,
  header = TRUE,
  format = eplusr_option("save_format"),
  leading = 4L,
  sep_at = 29L
)
Arguments
which

Either an integer vector of valid object IDs or a character vector of valid object names. If NULL, the whole Idf object is converted. Default: NULL.

class

A character vector of class names. If NULL, all classed in current Idf object is converted. Default: NULL.

comment

If FALSE, all comments will not be included. Default: TRUE.

header

If FALSE, the header will not be included. Default: TRUE.

format

Specific format used when formatting. Should be one of "asis", "sorted", "new_top", and "new_bot".

  • If "asis", Idf object will be formatted in the same way as it was when first read. If Idf object does not contain any format saving option, which is typically the case when the model was not saved using eplusr or IDFEditor, "sorted" will be used.

  • "sorted", "new_top" and "new_bot" are the same as the save options "Sorted", "Original with New at Top", and "Original with New at Bottom" in IDFEditor. Default: eplusr_option("save_format").

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.

Details

⁠$to_string()⁠ returns the text format of parts or whole Idf object.

Returns

A character vector.

Examples
\dontrun{
# get text format of the whole Idf
head(idf$to_string())

# get text format of the whole Idf, excluding the header and all comments
head(idf$to_string(comment = FALSE, header = FALSE))

# get text format of all objects in class Material
head(idf$to_string(class = "Material", comment = FALSE, header = FALSE))

# get text format of some objects
head(idf$to_string(c("floor", "zone one")))

# tweak output formatting
head(idf$to_string("floor", leading = 0, sep_at = 0))
}

Method to_table()

Format Idf as a data.frame

Usage
Idf$to_table(
  which = NULL,
  class = NULL,
  string_value = TRUE,
  unit = FALSE,
  wide = FALSE,
  align = FALSE,
  all = FALSE,
  group_ext = c("none", "group", "index"),
  force = FALSE,
  init = FALSE
)
Arguments
which

Either an integer vector of valid object IDs or a character vector of valid object names. If NULL, the whole Idf object is converted. Default: NULL.

class

A character vector of class names. If NULL, all classed in current Idf object is converted. Default: NULL.

string_value

If TRUE, all field values are returned as character. If FALSE, value column in returned data.table is a list column with each value stored as corresponding type. Note that if the value of numeric field is set to "Autosize" or "Autocalculate", it is left as it is, leaving the returned type being a string instead of a number. Default: TRUE.

unit

Only applicable when string_value is FALSE. If TRUE, values of numeric fields are assigned with units using units::set_units() if applicable. Default: FALSE.

wide

Only applicable if target objects belong to a same class. If TRUE, a wide table will be returned, i.e. first three columns are always id, name and class, and then every field in a separate column. Note that this requires all objects specified must from the same class. Default: FALSE.

align

If TRUE, all objects in the same class will have the same field number. The number of fields is the same as the object that have the most fields among objects specified. Default: FALSE.

all

If TRUE, all available fields defined in IDD for the class that objects belong to will be returned. Default: FALSE.

group_ext

Should be one of "none", "group" or "index". If not "none", value column in returned data.table::data.table() will be converted into a list. If "group", values from extensible fields will be grouped by the extensible group they belong to. For example, coordinate values of each vertex in class BuildingSurface:Detailed will be put into a list. If "index", values from extensible fields will be grouped by the extensible field indice they belong to. For example, coordinate values of all x coordinates will be put into a list. If "none", nothing special will be done. Default: "none".

force

If TRUE, wide can be TRUE even though there are multiple classes in input. This can result in a data.table with lots of columns. But may be useful when you know that target classes have the exact same fields, e.g. Ceiling:Adiabatic and Floor:Adiabatic. Default: FALSE.

init

If TRUE, a table for new object input will be returned with all values filled with defaults. In this case, object input will be ignored. The id column will be filled with possible new object IDs. Default: FALSE.

Details

⁠$to_table()⁠ returns a data.table that contains core data of specified objects. The returned data.table has 5 columns:

Note that when group_ext is not "none", index and field values will not match the original field indices and names. In this case, index will only indicate the indices of sequences. For field column, specifically:

Returns

A data.table with 6 columns (if wide is FALSE) or at least 6 columns (if wide is TRUE).

Examples
\dontrun{
# extract whole Idf data
idf$to_table()

# extract all data from class Material
idf$to_table(class = "Material")

# extract multiple object data
idf$to_table(c("FLOOR", "ZONE ONE"))

# keep value types and put actual values into a list column
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE)$value

# add the unit to each value
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE, unit = TRUE)

# get all possible fields
idf$to_table("ZONE ONE", all = TRUE)

# make sure all objects in same class have the same number of fields
idf$to_table(class = "Construction", align = TRUE)

# get a wide table with string values
idf$to_table(class = "Construction", wide = TRUE)

# get a wide table with actual values
idf$to_table(class = "OtherEquipment", wide = TRUE, string_value = FALSE)

# group extensible by extensible group number
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group")

# group extensible by extensible group number and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group", wide = TRUE)

# group extensible by extensible field index
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index")

# group extensible by extensible field index and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index", wide = TRUE)

# when grouping extensible, 'string_value' and 'unit' still take effect
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index",
    wide = TRUE, string_value = FALSE, unit = TRUE
)

# create table for new object input
idf$to_table(class = "BuildingSurface:Detailed", init = TRUE)
}

Method external_deps()

Get external file dependencies that the Idf needs for simulation.

Usage
Idf$external_deps(full = FALSE)
Arguments
full

If TRUE, a data.table is returned giving details about the objects and fields that use those external file dependencies. Default: FALSE.

Details

⁠$external_deps()⁠ returns information of files that are used as external resources for the simulation.

Currently, classes below are checked:

Note that, for ExternalInterface:FunctionalMockupUnitImport and ⁠ExternalInterface:FunctionalMockupUnitImport:*⁠, resources of FMU will also be extracted.

Returns

When full is FALSE, which is the default, a character vector.

When full is TRUE, a data.table of 8 columns:

If there are any FMUs using external file resources, the returned data.table will have an attribute named extra which is a list giving the FMU name and external file resources it use.

Examples
\dontrun{
idf$external_deps()
}

Method is_unsaved()

Check if there are unsaved changes in current Idf

Usage
Idf$is_unsaved()
Details

⁠$is_unsaved()⁠ returns TRUE if there are modifications on the model since it was read or since last time it was saved, and returns FALSE otherwise.

Returns

A single logical value of TRUE or FALSE.

Examples
\dontrun{
idf$is_unsaved()
}

Method save()

Save Idf object as an IDF file

Usage
Idf$save(
  path = NULL,
  format = eplusr_option("save_format"),
  overwrite = FALSE,
  copy_external = TRUE
)
Arguments
path

A path where to save the IDF file. If NULL, the path of the Idf itself, i.e. $path(), will be used.

format

Specific format used when formatting. Should be one of "asis", "sorted", "new_top", and "new_bot".

  • If "asis", Idf object will be formatted in the same way as it was when first read. If Idf object does not contain any format saving option, which is typically the case when the model was not saved using eplusr or IDFEditor, "sorted" will be used.

  • "sorted", "new_top" and "new_bot" are the same as the save options "Sorted", "Original with New at Top", and "Original with New at Bottom" in IDFEditor. Default: eplusr_option("save_format").

overwrite

Whether to overwrite the file if it already exists. Default: FALSE.

copy_external

If TRUE, the external files extracted from ⁠$external_deps()⁠ will also be copied into the same directory. The values of file paths in the Idf will be changed into relative path automatically. This makes it possible to create fully reproducible simulation conditions. If FALSE, the values of those fields that reference external file paths will be updated to absolute paths. Default: FALSE.

Details

⁠$save()⁠ formats current Idf object, saves it as an IDF file and returns the path of saved file invisibly. After saving, $path() will also be updated to return the path of saved file.

Returns

A length-one character vector, invisibly.

Examples
\dontrun{
# save Idf as a new file
idf$save(tempfile(fileext = ".idf"))

# save and overwrite current file
idf$save(overwrite = TRUE)

# save the model with newly created and modified objects at the top
idf$save(overwrite = TRUE, format = "new_top")

# save the model to a new file and copy all external csv files used in
# "Schedule:File" class into the same folder
idf$save(path = file.path(tempdir(), "test1.idf"), copy_external = TRUE)
}

Method run()

Run simulation using EnergyPlus

Usage
Idf$run(
  weather,
  dir = NULL,
  wait = TRUE,
  force = FALSE,
  copy_external = FALSE,
  echo = wait
)
Arguments
weather

A path to an .epw file or an Epw object. weather can also be NULL which will force design-day-only simulation. Note that this needs at least one Sizing:DesignDay object exists in the Idf.

dir

The directory to save the simulation results. If NULL, the folder of Idf path will be used. Default: NULL.

wait

Whether to wait until the simulation completes and print the standard output and error of EnergyPlus. If FALSE, the simulation will run in the background. Default is TRUE.

force

Only applicable when the last simulation runs with wait equals to FALSE and is still running. If TRUE, current running job is forced to stop and a new one will start. Default: FALSE.

copy_external

If TRUE, the external files that current Idf object depends on will also be copied into the simulation output directory. The values of file paths in the Idf will be changed automatically. This ensures that the output directory will have all files needed for the model to run. Default is FALSE.

echo

Only applicable when wait is TRUE. Whether to show standard output and error from EnergyPlus. Default: same as wait.

Details

⁠$run()⁠ calls corresponding version of EnergyPlus to run the current Idf object together with specified weather. The model and the weather used will be copied into the output directory. An EplusJob object is returned which provides detailed info of the simulation and methods to collect simulation results. Please see EplusJob for details.

eplusr uses the EnergyPlus command line interface which was introduced since EnergyPlus 8.3.0. So ⁠$run()⁠ only supports models with version no lower than 8.3.0.

When calling ⁠$run()⁠, eplusr will do steps below to make sure the output collecting methods work as expected. Please note that this may result in an IDF file that may not be exactly same as your current Idf object.

Returns

An EplusJob object of current simulation.

Examples
\dontrun{
idf <- Idf$new(path_idf)
# save the model to tempdir()
idf$save(file.path(tempdir(), "test_run.idf"))

# use the first epw file in "WeatherData" folder in EnergyPlus v8.8
# installation path
epw <- list.files(file.path(eplus_config(8.8)$dir, "WeatherData"),
    pattern = "\\.epw$", full.names = TRUE)[1]

# if `dir` is NULL, the directory of IDF file will be used as simulation
# output directory
job <- idf$run(epw, dir = NULL)

# run simulation in the background
idf$run(epw, dir = tempdir(), wait = FALSE)

# copy all external files into the directory run simulation
idf$run(epw, dir = tempdir(), copy_external = TRUE)

# check for simulation errors
job$errors()

# get simulation status
job$status()

# get output directory
job$output_dir()

# re-run the simulation
job$run()

# get simulation results
job$report_data()
}

Method last_job()

Get the last simulation job

Usage
Idf$last_job()
Details

⁠$last_job()⁠ returns the last EplusJob object that was created using $run(). If the Idf hasn't been run yet, NULL is returned.

Returns

NULL or an EplusJob object.

Examples
\dontrun{
idf$last_job()
}

Method geometry()

Extract Idf geometries

Usage
Idf$geometry()
Details

⁠$geometry()⁠ extracts all geometry objects into an IdfGeometry object. IdfGeometry is an abstraction of a collection of geometry in an Idf. It provides more detail methods to query geometry properties, update geometry vertices and visualize geometry in 3D using the rgl package.

Returns

An IdfGeometry object.

Examples
\dontrun{
idf$geometry()
}

Method view()

View 3D Idf geometry

Usage
Idf$view(
  new = FALSE,
  render_by = "surface_type",
  wireframe = TRUE,
  x_ray = FALSE,
  axis = TRUE
)
Arguments
new

If TRUE, a new rgl window will be open using rgl::open3d(). If FALSE, existing rgl window will be reused if possible. Default: FALSE.

render_by

A single string specifying the way of rendering the geometry. Possible values are:

  • "surface_type": Default. Render the model by surface type model. Walls, roofs, windows, doors, floors, and shading surfaces will have unique colors.

  • "boundary": Render the model by outside boundary condition. Only surfaces that have boundary conditions will be rendered with a color. All other surfaces will be white.

  • "construction": Render the model by surface constructions.

  • "zone": Render the model by zones assigned.

  • "normal": Render the model by surface normal. The outside face of a heat transfer face will be rendered as white and the inside face will be rendered as red.

wireframe

If TRUE, the wireframe of each surface will be shown. Default: TRUE.

x_ray

If TRUE, all surfaces will be rendered translucently. Default: FALSE.

axis

If TRUE, the X, Y and Z axes will be drawn at the global origin. Default: TRUE.

Details

⁠$view()⁠ uses the rgl package to visualize the IDF geometry in 3D in a similar way as OpenStudio.

⁠$view()⁠ returns an IdfViewer object which can be used to further tweak the viewer scene.

In the rgl window, you can control the view using your mouse:

Returns

An IdfViewer object

Examples
\dontrun{
idf$view()
idf$view(render_by = "zone")
idf$view(render_by = "construction")
}

Method print()

Print Idf object

Usage
Idf$print(zoom = "class", order = TRUE)
Arguments
zoom

Control how detailed of the Idf object should be printed. Should be one of "group", "class", "object" and "field". Default: "group".

  • "group": all group names current existing are shown with prevailing square bracket showing how many Classes existing in that group.

  • "class": all class names are shown with prevailing square bracket showing how many Objects existing in that class, together with parent group name of each class.

  • "object": all object IDs and names are shown, together with parent class name of each object.

  • "field": all object IDs and names, field names and values are shown, together with parent class name of each object.

order

Only applicable when zoom is "object" or "field". If TRUE, objects are shown as the same order in the IDF. If FALSE, objects are grouped and ordered by classes. Default: TRUE.

Details

⁠$print()⁠ prints the Idf object according to different detail level specified using the zoom argument.

With the default zoom level object, contents of the Idf object is printed in a similar style as you see in IDF Editor, with additional heading lines showing Path, Version of the Idf object. Class names of objects are ordered by group and the number of objects in classes are shown in square bracket.

Returns

The Idf object itself, invisibly.

Examples
\dontrun{
idf$print("group")
idf$print("class")
idf$print("object")
idf$print("field")

# order objects by there classes
idf$print("object", order = FALSE)
idf$print("field", order = FALSE)
}

Method clone()

The objects of this class are cloneable with this method.

Usage
Idf$clone(deep = TRUE)
Arguments
deep

Whether to make a deep clone.

Author(s)

Hongyuan Jia

See Also

IdfObject class for a single object in an IDF.

Examples


## ------------------------------------------------
## Method `Idf$new`
## ------------------------------------------------

## Not run: 
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8

# If neither EnergyPlus v8.8 nor Idd v8.8 was found, error will
# occur. If Idd v8.8 is found, it will be used automatically.
idf <- Idf$new(path_idf)

# argument `idd` can be specified explicitly using `use_idd()`
idf <- Idf$new(path_idf, idd = use_idd(8.8))

# you can set `download` arugment to "auto" in `use_idd()` if you
# want to automatically download corresponding IDD file when
# necessary
idf <- Idf$new(path_idf, use_idd(8.8, download = "auto"))

# Besides use a path to an IDF file, you can also provide IDF in literal
# string format
string_idf <-
    "
    Version, 8.8;
    Building,
        Building;                !- Name
    "

Idf$new(string_idf, use_idd(8.8, download = "auto"))

## End(Not run)


## ------------------------------------------------
## Method `Idf$version`
## ------------------------------------------------

## Not run: 
# get version
idf$version()

## End(Not run)


## ------------------------------------------------
## Method `Idf$path`
## ------------------------------------------------

## Not run: 
# get path
idf$path()

# return `NULL` if Idf is not created from a file
Idf$new("Version, 8.8;\n")$path()

## End(Not run)


## ------------------------------------------------
## Method `Idf$group_name`
## ------------------------------------------------

## Not run: 
# get names of all groups Idf contains
idf$group_name()

# get group name of each object in Idf
idf$group_name(sorted = FALSE)

# get names of all available groups in underlying Idd
idf$group_name(all = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$class_name`
## ------------------------------------------------

## Not run: 
# get names of all classes in Idf
idf$class_name()

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

# get class name of each object in Idf
idf$class_name(sorted = FALSE)

# get names of all available classes in underlying Idd
idf$class_name(all = TRUE)

# get names of all available classes grouped by group names in
# underlying Idd
idf$class_name(all = TRUE, by_group = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$is_valid_group`
## ------------------------------------------------

## Not run: 
# check if input is a valid group name in current Idf
idf$is_valid_group(c("Schedules", "Compliance Objects"))

# check if input is a valid group name in underlying Idd
idf$is_valid_group(c("Schedules", "Compliance Objects"), all = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$is_valid_class`
## ------------------------------------------------

## Not run: 
# check if input is a valid class name in current Idf
idf$is_valid_class(c("Building", "ShadowCalculation"))

# check if input is a valid class name in underlying Idd
idf$is_valid_class(c("Building", "ShadowCalculation"), all = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$definition`
## ------------------------------------------------

## Not run: 
# get the IddObject object for specified class
idf$definition("Version")

## End(Not run)


## ------------------------------------------------
## Method `Idf$object_id`
## ------------------------------------------------

## Not run: 
# get IDs of all objects in current Idf object
idf$object_id()

# get IDs of all objects in current Idf object, and merge them into a
# single integer vector
idf$object_id(simplify = TRUE)

# get IDs of objects in class Version and Zone
idf$object_id(c("Version", "Zone"))

# get IDs of objects in class Version and Zone, and merge them into a
# single integer vector
idf$object_id(c("Version", "Zone"), simplify = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$object_name`
## ------------------------------------------------

## Not run: 
# get names of all objects in current Idf object
idf$object_name()

# get names of all objects in current Idf object, and merge them into
# a single character vector
idf$object_name(simplify = TRUE)

# get names of objects in class Version and Zone
idf$object_name(c("Version", "Zone"))

# get names of objects in class Version and Zone, and merge them into
# a single character vector
idf$object_name(c("Version", "Zone"), simplify = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$object_num`
## ------------------------------------------------

## Not run: 
# get total number of objects
idf$object_num()

# get number of objects in class Zone and Schedule:Compact
idf$object_num(c("Zone", "Schedule:Compact"))

## End(Not run)


## ------------------------------------------------
## Method `Idf$is_valid_id`
## ------------------------------------------------

## Not run: 
idf$is_valid_id(c(51, 1000))

## End(Not run)


## ------------------------------------------------
## Method `Idf$is_valid_name`
## ------------------------------------------------

## Not run: 
idf$is_valid_name(c("Simple One Zone (Wireframe DXF)", "ZONE ONE", "a"))

# name matching is case-insensitive
idf$is_valid_name(c("simple one zone (wireframe dxf)", "zone one", "a"))

## End(Not run)


## ------------------------------------------------
## Method `Idf$object`
## ------------------------------------------------

## Not run: 
# get an object whose ID is 3
idf$object(3)

# get an object whose name is "simple one zone (wireframe dxf)"
# NOTE: object name matching is case-insensitive
idf$object("simple one zone (wireframe dxf)")

## End(Not run)


## ------------------------------------------------
## Method `Idf$objects`
## ------------------------------------------------

## Not run: 
# get objects whose IDs are 3 and 10
idf$objects(c(3,10))

# get objects whose names are "Simple One Zone (Wireframe DXF)" and "ZONE ONE"
# NOTE: object name matching is case-insensitive
idf$objects(c("Simple One Zone (Wireframe DXF)", "zone one"))

## End(Not run)


## ------------------------------------------------
## Method `Idf$object_unique`
## ------------------------------------------------

## Not run: 
# get the SimulationColtrol object
idf$object_unique("SimulationControl")

# S3 "[[" and "$" can also be used
idf$SimulationControl
idf[["SimulationControl"]]

## End(Not run)


## ------------------------------------------------
## Method `Idf$objects_in_class`
## ------------------------------------------------

## Not run: 
# get all objects in Zone class
idf$objects_in_class("Zone")

# S3 "[[" and "$" can also be used
idf$Zone
idf[["Zone"]]

## End(Not run)


## ------------------------------------------------
## Method `Idf$objects_in_group`
## ------------------------------------------------

## Not run: 
# get all objects in Schedules group
idf$objects_in_group("Schedules")

## End(Not run)


## ------------------------------------------------
## Method `Idf$object_relation`
## ------------------------------------------------

## Not run: 
# check each layer's reference of a construction named FLOOR
idf$object_relation("floor", "ref_to")

# check where is this construction being used
idf$object_relation("floor", "ref_by")

## End(Not run)


## ------------------------------------------------
## Method `Idf$objects_in_relation`
## ------------------------------------------------

## Not run: 
# get a construction named FLOOR and all materials it uses
idf$objects_in_relation("floor", "ref_to")

# get a construction named FLOOR and all surfaces that uses it
idf$objects_in_relation("floor", "ref_by", class = "BuildingSurface:Detailed")

## End(Not run)


## ------------------------------------------------
## Method `Idf$search_object`
## ------------------------------------------------

## Not run: 
# get all objects whose names contains "floor"
idf$search_object("floor", ignore.case = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$dup`
## ------------------------------------------------

## Not run: 
# duplicate an object named "FLOOR"
idf$dup("floor") # New object name 'FLOOR_1' is auto-generated

# duplicate that object again by specifing object ID
idf$dup(16) # New object name 'FLOOR_2' is auto-generated

# duplicate that object two times and giving new names
idf$dup(new_floor = "floor", new_floor2 = 16)

# duplicate that object multiple times using variable inputs
floors_1 <- c(new_floor3 = "floor", new_floor4 = "floor")
floors_2 <- setNames(rep(16, 5), paste0("flr", 1:5))
idf$dup(floors_1, floors_2)

## End(Not run)


## ------------------------------------------------
## Method `Idf$add`
## ------------------------------------------------

## Not run: 
# add a new Building object with all default values
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .())

# add a new Building object with all default values and comments
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .(.comment = c("this is", "a new building")))

# add a new RunPeriod object with all possible fields
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = list(), RunPeriod = list("rp", 1, 1, 1, 31), .all = TRUE)

# add objects using variable inputs
empty <- empty_idf(8.8) # create an empty Idf
objs1 <- list(Schedule_Constant = list("const"), Building = list())
rp <- list(RunPeriod = list("rp", 2, 1, 2, 28))
empty$add(objs1, rp)

## End(Not run)


## ------------------------------------------------
## Method `Idf$set`
## ------------------------------------------------

## Not run: 
# modify an object by name (case-insensitive)
idf$set(r13layer = list(roughness = "smooth"))

# modify an object by ID
idf$set(..12 = list(roughness = "rough"))

# overwrite existing object comments
idf$set(r13layer = list(.comment = c("New comment")))

# assign default values to fields
idf$set(r13layer = list(solar_absorptance = NULL), .default = TRUE)

# set field values to blanks
idf$set(r13layer = list(solar_absorptance = NULL), .default = FALSE)

# set field values to blank and delete trailing fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE)

# set field values to blank and keep blank fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE, .empty = TRUE)

# set all fields in one class
idf$set(Material_NoMass := list(visible_absorptance = 0.9))

# set multiple objects in one class
idf$set(.("r13layer", "r31layer") := list(solar_absorptance = 0.8))
# above is equivalent to
idf$set(r13layer = list(solar_absorptance = 0.8),
        r31layer = list(solar_absorptance = 0.8)
)

# use variable input
sets <- list(r13layer = list(roughness = "smooth"))
idf$set(sets)

## End(Not run)


## ------------------------------------------------
## Method `Idf$del`
## ------------------------------------------------

## Not run: 
# delete objects using names
idf$object("Fraction") # ScheduleTypeLimits
idf$del("Fraction")

# delete objects using IDs
idf$objects(c(39, 40)) # Output:Variable
idf$del(39, 40)

# cannot delete objects that are referred by others
level_checks()$reference # reference-checking is enable by default
idf$del("r13layer") # error

# force to delete objects even thay are referred by others
idf$del("r13layer", .force = TRUE)

# delete objects and also objects that refer to them
idf$del("r31layer", .ref_by = TRUE) # Construction 'ROOF31' will be kept

# delete objects and also objects that they refer to
idf$del("extlights", .ref_to = TRUE) # Schedule 'AlwaysOn' will be kept

# delete objects and also other objects that refer to them recursively
idf$del("roof31", .ref_by = TRUE, .recursive = TRUE)

# delete objects using variable inputs
ids <- idf$object_id("Output:Variable", simplify = TRUE)
idf$del(ids)

## End(Not run)


## ------------------------------------------------
## Method `Idf$purge`
## ------------------------------------------------

## Not run: 
# purge unused "Fraction" schedule type
idf$purge("on/off") # ScheduleTypeLimits

# purge all unused schedule types
idf$purge(class = "ScheduleTypeLimits")

# purge all unused schedule related objects
idf$purge(group = "Schedules")

## End(Not run)


## ------------------------------------------------
## Method `Idf$duplicated`
## ------------------------------------------------

## Not run: 
# check if there are any duplications in the Idf
idf$duplicated(class = "ScheduleTypeLimits")

# check if there are any duplications in the schedule types
idf$duplicated(class = "ScheduleTypeLimits")

# check if there are any duplications in the schedule groups and
# material class
idf$duplicated(class = "Material", group = "Schedules")

## End(Not run)


## ------------------------------------------------
## Method `Idf$unique`
## ------------------------------------------------

## Not run: 
# remove duplications in the Idf
idf$unique(class = "ScheduleTypeLimits")

# remove duplications in the schedule types
idf$unique(class = "ScheduleTypeLimits")

# remove duplications in the schedule groups and material class
idf$unique(class = "Material", group = "Schedules")

## End(Not run)


## ------------------------------------------------
## Method `Idf$rename`
## ------------------------------------------------

## Not run: 
idf$objects(c("on/off", "test 352a"))
idf$rename(on_off = "on/off", test_352a = 51)

## End(Not run)


## ------------------------------------------------
## Method `Idf$insert`
## ------------------------------------------------

## Not run: 
# insert all material from another IDF
path_idf2 <- file.path(eplus_config(8.8)$dir, "ExampleFiles/5ZoneTDV.idf")
idf2 <- Idf$new(path_idf2)
idf$insert(idf2$Material)

# insert objects from same Idf is equivalent to using Idf$dup()
idf$insert(idf$SizingPeriod_DesignDay)

## End(Not run)


## ------------------------------------------------
## Method `Idf$load`
## ------------------------------------------------

## Not run: 
# load objects from character vectors
idf$load(
    c("Material,",
      "    mat,                     !- Name",
      "    MediumSmooth,            !- Roughness",
      "    0.667,                   !- Thickness {m}",
      "    0.115,                   !- Conductivity {W/m-K}",
      "    513,                     !- Density {kg/m3}",
      "    1381;                    !- Specific Heat {J/kg-K}"),

    "Construction, const, mat;"
)

# load objects from data.frame definitions
dt <- idf$to_table(class = "Material")
dt[field == "Name", value := paste(value, 1)]
dt[field == "Thickness", value := "0.5"]
idf$load(dt)

# by default, duplications are removed
idf$load(idf$to_table(class = "Material"))

# keep empty fields as they are
idf$load("Material, mat1, smooth, 0.5, 0.2, 500, 1000,,, 0.5;", .default = FALSE)

# keep trailing empty fields
idf$load("Material, mat2, smooth, 0.5, 0.2, 500, 1000,,,;",
    .default = FALSE, .empty = TRUE
)

## End(Not run)


## ------------------------------------------------
## Method `Idf$update`
## ------------------------------------------------

## Not run: 
# update objects from string definitions:
str <- idf$to_string("zone one", header = FALSE, format = "new_top")
str[8] <- "2," # Multiplier
idf$update(str)

# update objects from data.frame definitions:
dt <- idf$to_table("zone one")
dt[field == "Multiplier", value := "1"]
idf$update(dt)

## End(Not run)


## ------------------------------------------------
## Method `Idf$search_value`
## ------------------------------------------------

## Not run: 
# search values that contains "floor"
idf$search_value("floor", ignore.case = TRUE)

# search values that contains "floor" in class Construction
idf$search_value("floor", "Construction", ignore.case = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$replace_value`
## ------------------------------------------------

## Not run: 
# search values that contains "win" and replace them with "windows"
idf$replace_value("win", "windows")

## End(Not run)


## ------------------------------------------------
## Method `Idf$validate`
## ------------------------------------------------

## Not run: 
idf$validate()

# check at predefined validate level
idf$validate("none")
idf$validate("draft")
idf$validate("final")

# custom validate checking components
idf$validate(custom_validate(auto_field = TRUE, choice = TRUE))

## End(Not run)


## ------------------------------------------------
## Method `Idf$is_valid`
## ------------------------------------------------

## Not run: 
idf$is_valid()

# check at predefined validate level
idf$is_valid("none")
idf$is_valid("draft")
idf$is_valid("final")

# custom validate checking components
idf$is_valid(custom_validate(auto_field = TRUE, choice = TRUE))

## End(Not run)


## ------------------------------------------------
## Method `Idf$to_string`
## ------------------------------------------------

## Not run: 
# get text format of the whole Idf
head(idf$to_string())

# get text format of the whole Idf, excluding the header and all comments
head(idf$to_string(comment = FALSE, header = FALSE))

# get text format of all objects in class Material
head(idf$to_string(class = "Material", comment = FALSE, header = FALSE))

# get text format of some objects
head(idf$to_string(c("floor", "zone one")))

# tweak output formatting
head(idf$to_string("floor", leading = 0, sep_at = 0))

## End(Not run)


## ------------------------------------------------
## Method `Idf$to_table`
## ------------------------------------------------

## Not run: 
# extract whole Idf data
idf$to_table()

# extract all data from class Material
idf$to_table(class = "Material")

# extract multiple object data
idf$to_table(c("FLOOR", "ZONE ONE"))

# keep value types and put actual values into a list column
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE)$value

# add the unit to each value
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE, unit = TRUE)

# get all possible fields
idf$to_table("ZONE ONE", all = TRUE)

# make sure all objects in same class have the same number of fields
idf$to_table(class = "Construction", align = TRUE)

# get a wide table with string values
idf$to_table(class = "Construction", wide = TRUE)

# get a wide table with actual values
idf$to_table(class = "OtherEquipment", wide = TRUE, string_value = FALSE)

# group extensible by extensible group number
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group")

# group extensible by extensible group number and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group", wide = TRUE)

# group extensible by extensible field index
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index")

# group extensible by extensible field index and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index", wide = TRUE)

# when grouping extensible, 'string_value' and 'unit' still take effect
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index",
    wide = TRUE, string_value = FALSE, unit = TRUE
)

# create table for new object input
idf$to_table(class = "BuildingSurface:Detailed", init = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$external_deps`
## ------------------------------------------------

## Not run: 
idf$external_deps()

## End(Not run)


## ------------------------------------------------
## Method `Idf$is_unsaved`
## ------------------------------------------------

## Not run: 
idf$is_unsaved()

## End(Not run)


## ------------------------------------------------
## Method `Idf$save`
## ------------------------------------------------

## Not run: 
# save Idf as a new file
idf$save(tempfile(fileext = ".idf"))

# save and overwrite current file
idf$save(overwrite = TRUE)

# save the model with newly created and modified objects at the top
idf$save(overwrite = TRUE, format = "new_top")

# save the model to a new file and copy all external csv files used in
# "Schedule:File" class into the same folder
idf$save(path = file.path(tempdir(), "test1.idf"), copy_external = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idf$run`
## ------------------------------------------------

## Not run: 
idf <- Idf$new(path_idf)
# save the model to tempdir()
idf$save(file.path(tempdir(), "test_run.idf"))

# use the first epw file in "WeatherData" folder in EnergyPlus v8.8
# installation path
epw <- list.files(file.path(eplus_config(8.8)$dir, "WeatherData"),
    pattern = "\\.epw$", full.names = TRUE)[1]

# if `dir` is NULL, the directory of IDF file will be used as simulation
# output directory
job <- idf$run(epw, dir = NULL)

# run simulation in the background
idf$run(epw, dir = tempdir(), wait = FALSE)

# copy all external files into the directory run simulation
idf$run(epw, dir = tempdir(), copy_external = TRUE)

# check for simulation errors
job$errors()

# get simulation status
job$status()

# get output directory
job$output_dir()

# re-run the simulation
job$run()

# get simulation results
job$report_data()

## End(Not run)


## ------------------------------------------------
## Method `Idf$last_job`
## ------------------------------------------------

## Not run: 
idf$last_job()

## End(Not run)


## ------------------------------------------------
## Method `Idf$geometry`
## ------------------------------------------------

## Not run: 
idf$geometry()

## End(Not run)


## ------------------------------------------------
## Method `Idf$view`
## ------------------------------------------------

## Not run: 
idf$view()
idf$view(render_by = "zone")
idf$view(render_by = "construction")

## End(Not run)


## ------------------------------------------------
## Method `Idf$print`
## ------------------------------------------------

## Not run: 
idf$print("group")
idf$print("class")
idf$print("object")
idf$print("field")

# order objects by there classes
idf$print("object", order = FALSE)
idf$print("field", order = FALSE)

## End(Not run)
[Package eplusr version 0.16.2 Index]