R: Create and Modify an EnergyPlus Object

IdfObject {eplusr}

R Documentation

Create and Modify an EnergyPlus Object

Description

IdfObject is an abstraction of a single object in an Idf. It provides more detail methods to modify object values and comments. An IdfObject object can also be created using function idf_object() or from methods of a parent Idf object, using ⁠$object()⁠, ⁠$objects_in_class()⁠ and equivalent.

Methods

Public methods

IdfObject$new()
IdfObject$version()
IdfObject$parent()
IdfObject$id()
IdfObject$name()
IdfObject$group_name()
IdfObject$class_name()
IdfObject$definition()
IdfObject$comment()
IdfObject$value()
IdfObject$set()
IdfObject$value_possible()
IdfObject$validate()
IdfObject$is_valid()
IdfObject$value_relation()
IdfObject$ref_to_object()
IdfObject$ref_by_object()
IdfObject$ref_to_node()
IdfObject$has_ref_to()
IdfObject$has_ref_by()
IdfObject$has_ref_node()
IdfObject$has_ref()
IdfObject$to_table()
IdfObject$to_string()
IdfObject$print()
IdfObject$clone()

Method `new()`

Create an IdfObject object

Usage

IdfObject$new(object, class = NULL, parent)

Arguments

object: An integer specifying an object ID.
class: An integer specifying a class index.
parent: An Idf object specifying the parent object.

Details

It is not recommended to directly use ⁠$new()⁠ method to create an IdfObject object, instead considering to use idf_object, Idf$object() and other equivalent to create IdfObject objects. They provide more user-friendly interfaces. ⁠$new()⁠ is a lower level API which is mainly used inside methods in other classes.

Returns

An IdfObject object.

Examples

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

roof <- IdfObject$new(26, parent = idf)

# get the IdfObject of material named "C5 - 4 IN HW CONCRETE"
mat <- idf$Material[["C5 - 4 IN HW CONCRETE"]]
}

Method `version()`

Get the version of parent Idf

Usage

IdfObject$version()

Details

⁠$version()⁠ returns the version of parent Idf in a base::numeric_version() format. This makes it easy to direction compare versions of different IdfObjects, e.g. idfobj$version() > 8.6 or idfobj1$version() > idfobj2$version().

Returns

A base::numeric_version() object.

Examples

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

Method `parent()`

Get parent Idf

Usage

IdfObject$parent()

Details

⁠$parent()⁠ returns parent Idf object.

Returns

A Idf object.

Examples

\dontrun{
roof$parent()
}

Method `id()`

Get the unique ID for current object

Usage

IdfObject$id()

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.

⁠$id()⁠ returns an integer of current object unique ID.

Returns

A single integer.

Examples

\dontrun{
roof$id()
}

Method `name()`

Get the name for current object.

Usage

IdfObject$name()

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.

⁠$name()⁠ returns a single string of current object name. If specified class does not have name attribute, NA is returned.

Returns

A single string.

Examples

\dontrun{
roof$name()

# NA will be returned if the class does not have name attribute. For example,
# "Version" class
idf$Version$name()
}

Method `group_name()`

Get name of group for current object.

Usage

IdfObject$group_name()

Details

⁠$group_name()⁠ returns a single string of group name current IdfObject belongs to.

Returns

A single string.

Examples

\dontrun{
roof$group_name()
}

Method `class_name()`

Get name of class for current object.

Usage

IdfObject$class_name()

Details

⁠$class_name()⁠ returns a single string of class name current IdfObject belongs to.

Returns

A single string.

Examples

\dontrun{
roof$class_name()
}

Method `definition()`

Get the IddObject object for current class.

Usage

IdfObject$definition()

Details

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

Returns

An IddObject object.

Examples

\dontrun{
roof$definition()
}

Method `comment()`

Get and modify object comments

Usage

IdfObject$comment(comment, append = TRUE, width = 0L)

Arguments

comment

A character vector.

If missing, current comments are returned. If there is no comment in current IdfObject, NULL is returned.
If NULL, all comments in current IdfObject is deleted.
If a character vector, it is inserted as comments depending on the append value.

append

Only applicable when commment is a character vector. Default: FALSE.

If NULL, existing comments is deleted before adding comment.
If TRUE, comment will be appended to existing comments.
If FALSE, comment is prepended to existing currents.

width

A positive integer giving the target width for wrapping inserted comment.

Details

⁠$comment()⁠ returns current IdfObject comments if comment is not given, or modifies current IdfObject comments if comment is given. If no comments found, NULL is returned.

Returns

If calling without any argument, a character vector or NULL (if no comments) is return. Otherwise, the modified object itself.

Examples

\dontrun{
# get object comments
roof$comment()

# add new object comments
roof$comment(c("This is a material named `WD01`", "This object has an ID of 47"))
roof$comment()

# append new comments
roof$comment("This is an appended comment")
roof$comment()

# prepend new comments
roof$comment("This is a prepended comment", append = FALSE)
roof$comment()

# wrap long comments
roof$comment("This is a very long comment that is needed to be wrapped.", width = 30)
roof$comment()

# delete old comments and add new one
roof$comment("This is the only comment", append = NULL)
roof$comment()

# delete all comments
roof$comment(NULL)
roof$comment()
}

Method `value()`

Get object field values.

Usage

IdfObject$value(which = NULL, all = FALSE, simplify = FALSE, unit = FALSE)

Arguments

which: An integer vector of field indexes or a character vector of field names.
all: If TRUE, values of all possible fields in current class the IdfObject belongs to are returned. Default: FALSE
simplify: If TRUE, values of fields are converted into characters and the converted character vector is returned.
unit: If TRUE, values of numeric fields are assigned with units using units::set_units() if applicable. Default: FALSE.

Details

⁠$value()⁠ takes an integer vector of valid field indexes or a character vector of valid field names, and returns a named list containing values of specified fields when simplify is FALSE and a character vector when simplify is TRUE.

eplusr also provides custom S3 method of $ and [[ which make it more convenient to get a single value of current IdfObject. Basically, idfobj$FieldName and idfobj[[Field]] is equivalent to idfobj$value(FieldName)[[1]] and idfobj$value(Field)[[1]].

Returns

A named list.

Examples

\dontrun{
# get all existing field values
str(mat$value())

# get values of field 1, 3, 5
str(mat$value(c(1, 3, 5)))

# get character format values instead of a named list
mat$value(c(1, 3, 5), simplify = TRUE)

# get values of all field even those that are not set
str(roof$value())
str(roof$value(all = TRUE))

# get field values using shortcuts
mat$Roughness
mat[["Specific_Heat"]]
mat[c(1,2)]
mat[c("Name", "Density")]
}

Method `set()`

Modify object field values.

Usage

IdfObject$set(..., .default = TRUE, .empty = FALSE)

Arguments

...

New field value definitions in field = value format or a single list in format:

list(field1 = value1, field2 = value2)

.default

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

.empty

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

Details

⁠$set()⁠ takes new field value definitions in field = value format or in a single list format, sets new values for fields specified, and returns the modified IdfObject. Unlike ⁠$set()⁠ method in Idf class, the special element .comment is not allowed. To modify object comments, please use ⁠$comment()⁠.

Examples

\dontrun{
# set field values
mat$set(name = "new_name", Thickness = 0.02)
mat[c("Name", "Thickness")]

# When `default` argument is set to TRUE and input field values are empty, i.e.
# NULL, the field values will be reset to defaults.
mat[c("Thermal Absorptance", "Solar Absorptance")]

mat$set(visible_absorptance = NULL, Solar_Absorptance = NULL, .default = TRUE)
mat[c("Visible Absorptance", "Solar Absorptance")]

# set field values using shortcuts
mat$Name <- "another_name"
mat$Name
mat[["Thickness"]] <- 0.019
mat$Thickness
}

Method `value_possible()`

Get possible object field values.

Usage

IdfObject$value_possible(
  which = NULL,
  type = c("auto", "default", "choice", "range", "source")
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
type: A character vector. What types of possible values should be returned. Should be one of or a combination of "auto", "default", "choice", "range" and "source". Default: All of those.

Details

⁠$value_possible()⁠ takes an integer vector of valid field indexes or a character vector of valid field names, and returns all possible values for specified fields. For a specific field, there are 5 types of possible values:

auto: Whether the field can be filled with Autosize and Autocalculate. This field attribute can also be retrieved using:
```
idfobj$definition()$is_autosizable_field()
idfobj$definition()$is_autocalculatable_field()
```
default: The default value. This value can also be retrieved using idfobj$defintion()$field_default().
choice: The choices which the field can be set. This value can also be retrieved using idfobj$definition()$field_choice().
range: The range which the field value should fall in. This range can also be retrieved using idfobj$definition()$field_range().
source: All values from other objects that current field can refer to.

Returns

⁠$value_possible()⁠ returns an IdfValuePossible object which is a data.table with at most 15 columns:

class_id: index of class that current IdfObject belongs to
class_name: name of class that current IdfObject belongs to
object_id: ID of current IdfObject
object_name: name of current IdfObject
field_id: indexes (at Idd level) of object fields specified
field_index: indexes of object fields specified
field_name: names (without units) of object fields specified
value_id: value indexes (at Idf level) of object fields specified
value_chr: values (converted to characters) of object fields specified
value_num: values (converted to numbers in SI units) of object fields specified.
auto: Exists only when "auto" is one of type. Character type. Possible values are: "Autosize", "Autocalculate" and NA (if current field is neither autosizable nor autocalculatable).
default: Exists only when "default" is one of type. List type. The default value of current field. The value is converted into number if corresponding field type yells so. Note that if current field is a numeric field but the default value is "Autosize" or "Autocalculate", it is left as it is, leaving the returned type being a string instead of a number.
range: Exists only when "range" is one of type. List type. The range that field value should fall in. Every range has four components: minimum (lower limit), lower_incbounds (TRUE if the lower limit should be included), maximum (upper limit), and upper_incbounds (TRUE if the upper limit should be included). For fields of character type, empty lists are returned. For fields of numeric types with no specified ranges, minimum is set to -Inf, lower_incbounds is set to FALSE, upper is set to Inf, and upper_incbounds is set to FALSE. The field range is printed in number interval denotation.
source: Exists only when "source" is one of type. List type. Each element is a character vector which includes all values from other objects that current field can use as sources and refers to.

Examples

\dontrun{
mat$value_possible()
}

Method `validate()`

Check possible object field value errors

Usage

IdfObject$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 IdfObject 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. $set() and etc.

In total, there are 10 different validate checking components:

required_object: Check if required objects are missing in current Idf.
unique_object: Check if there are multiple objects in one unique-object class. An unique-object class means that there should be at most only one object existing in that class.
unique_name: Check if all objects in each class have unique names.
extensible: Check if all fields in an extensible group have values. An extensible group is a set of fields that should be treated as a whole, such like the X, Y and Z vertices of a building surfaces. An extensible group should be added or deleted together. extensible component checks if there are some, but not all, fields in an extensible group are empty.
required_field: Check if all required fields have values.
auto_field: Check if all fields filled with value "Autosize" and "Autocalculate" are actual autosizable and autocalculatable fields or not.
type: Check if all fields have value types complied with their definitions, i.e. character, numeric and integer fields should be filled with corresponding type of values.
choice: Check if all choice fields are filled with valid choice values.
range: Check if all numeric fields have values within prescibed ranges.
reference: Check if all fields whose values refer to other fields are valid.

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.

missing_object: Result of required_object checking.
duplicate_object: Result of unique_object checking.
conflict_name: Result of unique_name checking.
incomplete_extensible: Result of extensible checking.
missing_value: Result of required_field checking.
invalid_autosize: Result of auto_field checking for invalid Autosize field values.
invalid_autocalculate: Result of auto_field checking for invalid Autocalculate field values.
invalid_character: Result of type checking for invalid character field values.
invalid_numeric: Result of type checking for invalid numeric field values.
invalid_integer: Result of type checking for invalid integer field values.
invalid_choice: Result of choice checking.
invalid_range: Result of range checking.
invalid_reference: Result of reference checking.

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:

object_id: IDs of objects that contain invalid values
object_name: names of objects that contain invalid values
class_id: indexes of classes that invalid objects belong to
class_name: names of classes that invalid objects belong to
field_id: indexes (at Idd level) of object fields that are invalid
field_index: indexes of object fields in corresponding that are invalid
field_name: names (without units) of object fields that are invalid
units: SI units of object fields that are invalid
ip_units: IP units of object fields that are invalid
type_enum: An integer vector indicates types of invalid fields
value_id: indexes (at Idf level) of object field values that are invalid
value_chr: values (converted to characters) of object fields that are invalid
value_num: values (converted to numbers in SI units) of object fields that are invalid

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:

No error is found:
```
v No error found.
```
Above result shows that there is no error found after conducting all validate checks in specified validate level.

Errors are found:

 x [2] Errors found during validation.
=========================================================================

-- [2] Invalid Autocalculate Field --------------------------------------
   Fields below cannot be `autocalculate`:

    Class: <AirTerminal:SingleDuct:VAV:Reheat>
    \- Object [ID:176] <SPACE5-1 VAV Reheat>
       +- 17: AUTOCALCULATE, !- Maximum Flow per Zone Floor Area During Reheat {m3/s-m2}
       \- 18: AUTOCALCULATE; !- Maximum Flow Fraction During Reheat

Above result shows that after all validate components performed under current validate level, 2 invalid field values are found. All of them are in a object named ⁠SPACE5-1 VAV Reheat⁠ with ID 176. They are invalid because those two fields do not have an autocalculatable attribute but are given AUTOCALCULATE value. Knowing this info, one simple way to fix the error is to correct those two fields by doing:

idf$set(..176 =
    list(`Maximum Flow per Zone Floor Area During Reheat` = "autosize",
         `Maximum Flow Fraction During Reheat` = "autosize"
    )
)

Returns

An IdfValidity object.

Examples

\dontrun{
mat$validate()

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

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

Method `is_valid()`

Check if there is any error in current object

Usage

IdfObject$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()⁠ returns TRUE if there is no error in current IdfObject object under specified validation level and FALSE otherwise.

⁠$is_valid()⁠ checks if there are errors in current IdfObject 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{
mat$is_valid()

mat$definition()$field_range("Density")
eplusr_option(validate_level = "none") # have to set validate to "none" to do so
mat$Density <- -1
eplusr_option(validate_level = "final") # change back to "final" validate level
mat$is_valid()

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

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

Method `value_relation()`

Get value relations

Usage

IdfObject$value_relation(
  which = NULL,
  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: An integer vector of field indexes or a character vector of field names.
direction: The relation direction to extract. Should be either "all", "ref_to" or "ref_by".
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 input fields are returned regardless they have any relations with other objects or not. If FALSE, only fields in input 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 and BranchList 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.

⁠$value_relation()⁠ provides a simple interface to get this kind of relation. It takes field indexes or field names, together a relation direction, and returns an IdfRelation object which contains data presenting such relation described above. For instance, if idfobj$value_relation("Name", "ref_by") gives results below:

-- Referred by Others ------------------------
  \- 1: "WALL-1";      !- Name
     ^~~~~~~~~~~~~~~~~~~~~~~~~
     \- Class: <BuildingSurface:Detailed>
        \- Object [ID:3] <WALL-1PF>
           \- 3: "WALL-1";      !- Construction Name

This means that the value "WALL-1" of field Name is referred by field ⁠Construction Name⁠ in a surface named ⁠WALL-1PF⁠. All those objects can be further easily extracted using ⁠$ref_by_object()⁠ method.

Note that ⁠$value_relation()⁠ shows all fields specified, even some of them may do not have relation.

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
roof$value_relation("zone name", "ref_to")

# check where is this construction being used
roof$value_relation("name", direction = "ref_by")
}

Method `ref_to_object()`

Extract multiple IdfObject objects referred by specified field values

Usage

IdfObject$ref_to_object(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L,
  class_ref = c("both", "none", "all")
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
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.
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

For details on field value relations, see $value_relation().

⁠$ref_to_object()⁠ takes an integer vector of field indexes or a character vector of field names, and returns a list of IdfObjects that specified fields refer to.

Returns

A named list of IdfObject objects.

Examples

\dontrun{
# get other objects that this object refereces
mat$ref_to_object() # not referencing other objects
}

Method `ref_by_object()`

Extract multiple IdfObject objects referring to specified field values

Usage

IdfObject$ref_by_object(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L,
  class_ref = c("both", "none", "all")
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
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.
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

For details on field value relations, see $value_relation().

⁠$ref_by_object()⁠ takes an integer vector of field indexes or a character vector of field names, and returns a list of IdfObjects that refer to specified fields.

Returns

A named list of IdfObject objects.

Examples

\dontrun{
# get other objects that reference this object
mat$ref_by_object() # referenced by construction "FLOOR"
}

Method `ref_to_node()`

Extract multiple IdfObject objects referring to same nodes

Usage

IdfObject$ref_to_node(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
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.

Details

For details on field value relations, see $value_relation().

⁠$ref_to_node()⁠ takes an integer vector of field indexes or a character vector of field names, and returns a list of IdfObjects whose nodes are referred by specified fields.

Returns

A named list of IdfObject objects.

Examples

\dontrun{
if (is_avail_eplus(8.8)) {
    path <- file.path(eplus_config(8.8)$dir, "ExampleFiles/5Zone_Transformer.idf")
    idf_5z <- read_idf(path)
    idf_5z$NodeList$OutsideAirInletNodes$ref_to_node()
}
}

Method `has_ref_to()`

Check if object field values refer to others

Usage

IdfObject$has_ref_to(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE,
  class_ref = c("both", "none", "all")
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
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.
recursive: If TRUE, 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. 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

For details on field value relations, see $value_relation().

⁠$has_ref_to()⁠ takes an integer vector of field indexes or a character vector of field names, and returns a logical vector showing whether specified fields refer to other object values or not.

Returns

A logical vector with the same length as specified field.

Examples

\dontrun{
mat$has_ref_to()
}

Method `has_ref_by()`

Check if object field values are referred by others

Usage

IdfObject$has_ref_by(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE,
  class_ref = c("both", "none", "all")
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
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.
recursive: If TRUE, 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. 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

For details on field value relations, see $value_relation().

⁠$has_ref_by()⁠ takes an integer vector of field indexes or a character vector of field names, and returns a logical vector showing whether there are other object values ref to specified fields.

Returns

A logical vector with the same length as specified field.

Examples

\dontrun{
mat$has_ref_by()
}

Method `has_ref_node()`

Check if object field values refer to other nodes

Usage

IdfObject$has_ref_node(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
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.
recursive: If TRUE, 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. Default: FALSE.

Details

For details on field value relations, see $value_relation().

⁠$has_ref_node()⁠ takes an integer vector of field indexes or a character vector of field names, and returns a logical vector showing whether specified fields refer to other objects' nodes.

Returns

A logical vector with the same length as specified field.

Examples

\dontrun{
mat$has_ref_node()
}

Method `has_ref()`

Check if object field values refer to or are referred by others

Usage

IdfObject$has_ref(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE
)

Arguments

which: An integer vector of field indexes or a character vector of field names.
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.
recursive: If TRUE, 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. Default: FALSE.

Details

For details on field value relations, see $value_relation().

⁠$has_ref()⁠ takes an integer vector of field indexes or a character vector of field names, and returns a logical vector showing whether there are other object values ref to specified field values or specified field values refer to other object values or specified field values refer to other objects' nodes.

Returns

A logical vector with the same length as specified field.

Examples

\dontrun{
# check if having any referenced objects or is referenced by other objects
mat$has_ref()
}

Method `to_table()`

Format IdfObject as a data.frame

Usage

IdfObject$to_table(
  string_value = TRUE,
  unit = TRUE,
  wide = FALSE,
  all = FALSE,
  group_ext = c("none", "group", "index")
)

Arguments

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.
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".

Details

⁠$to_table()⁠ returns a data.table that contains core data of current IdfObject. It has 6 columns:

id: Integer type. Object IDs.
name: Character type. Object names.
class: Character type. Current class name.
index: Integer type. Field indexes.
field: Character type. Field names.
value: Character type if string_value is TRUE or list type if string_value is FALSE or group_ext is not "none". Field values.

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:

When group_ext is "group", each field name in a extensible group will be abbreviated using abbreviate() with minlength being 10L and all abbreviated names will be separated by | and combined together. For example, field names in the extensible group (⁠Vertex 1 X-coordinate⁠, ⁠Vertex 1 Y-coordinate⁠, ⁠Vertex 1 Z-coordinate⁠) in class BuildiBuildingSurface:Detailed will be merged into one name Vrtx1X-crd|Vrtx1Y-crd|Vrtx1Z-crd.
When group_ext is "index", the extensible group indicator in field names will be removed. Take the same example as above, the resulting field names will be ⁠Vertex X-coordinate⁠, ⁠Vertex Y-coordinate⁠, and ⁠Vertex Z-coordinate⁠.

Returns

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

Examples

\dontrun{
# get all object data in a data.table format without field units
str(mat$to_table(unit = FALSE))

# get all object data in a data.table format where all field values are put in a
# list column and field names without unit
str(mat$to_table(string_value = FALSE, unit = FALSE))

# get all object data in a data.table format, including tailing empty fields
str(idf$Zone$`ZONE ONE`$to_table(all = TRUE))

# get all object data in a data.table format where each field becomes a column
str(mat$to_table(wide = TRUE))

# group extensible by extensible group number
surf <- idf$BuildingSurface_Detailed[["Zn001:Roof001"]]
surf$to_table(group_ext = "group")

# group extensible by extensible group number and convert into a wide table
surf$to_table(group_ext = "group", wide = TRUE)

# group extensible by extensible field index
surf$to_table(group_ext = "index")

# group extensible by extensible field index and convert into a wide table
surf$to_table(group_ext = "index", wide = TRUE)

# when grouping extensible, 'string_value' and 'unit' still take effect
surf$to_table(group_ext = "index", wide = TRUE, string_value = FALSE, unit = TRUE)
}

Method `to_string()`

Format current object as a character vector

Usage

IdfObject$to_string(comment = TRUE, leading = 4L, sep_at = 29L, all = FALSE)

Arguments

comment: If FALSE, all comments will not be included. Default: TRUE.
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.
all: If TRUE, all available fields defined in IDD for the class that objects belong to will be returned. Default: FALSE.

Details

⁠$to_string()⁠ returns the text format of current object.

Returns

A character vector.

Examples

\dontrun{
# get string format object
mat$to_string()

# get string format of object, and decrease the space between field values and
# field names
mat$to_string(sep_at = 15)

# get string format of object, and decrease the leading space of field values
mat$to_string(leading = 0)
}

Method `print()`

Print IdfObject object

Usage

IdfObject$print(comment = TRUE, auto_sep = TRUE, brief = FALSE, all = FALSE)

Arguments

comment: If FALSE, all comments are not included.
auto_sep: If TRUE, values and field names are separated at the largest character length of values. Default: FALSE.
brief: If TRUE, only OBJECT part is printed. Default: FALSE.
all: If TRUE, all fields defined in Idd are printed even they do not exist in current object. Default: FALSE.

Details

⁠$print()⁠ prints the IdfObject. Basically, the print output can be divided into 3 parts:

OBJECT: Class name, object id and name (if applicable).
COMMENTS: Object comments if exist.
VALUES: fields and values of current IdfObject. Required fields are marked with start *. String values are quoted. Numeric values are printed as they are. Blank string values are printed as ⁠<"Blank">⁠ and blank number values are printed as ⁠<Blank>⁠.

Returns

The IdfObject itself, invisibly.

Examples

\dontrun{
# print the object without comment
mat$print(comment = FALSE)

# print the object, and auto separate field values and field names at the
# largetst character length of field values
mat$print(auto_sep = TRUE)
}

Method `clone()`

The objects of this class are cloneable with this method.

Usage

IdfObject$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Note

Only one single list is allowed, e.g. idfobj$set(lst1) where lst1 <- list(field1 = value1) is allowed, but idfobj$set(lst1, lst2) is not.
You can delete a field by assigning NULL to it, e.g. iddobj$set(fld = NULL) means to delete the value of field fld. If .default is FALSE, also fld is not a required field and the index of fld is larger than the number minimum fields required for that class, it will be deleted. Otherwise it will be left as blank. If .default is TRUE, that field will be filled with default value if applicable and left as blank if not.
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.
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 model$set(Construction = list("out_layer", name = "name")), "out_layer" will be treated as the value of field ⁠Outside Layer⁠ in Construction, as value of field Name has been given as "name".

eplusr also provides custom S3 method of ⁠$<-⁠ and [[<- which makes it more convenient to set a single field value of an IdfObject. Basically, idfobj$FieldName <- value and idfobj[[Field]] <- value is equivalent to idfobj$set(FieldName = value) and idfobjset(Field = value).

Author(s)

Hongyuan Jia

Examples


## ------------------------------------------------
## Method `IdfObject$new`
## ------------------------------------------------

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

roof <- IdfObject$new(26, parent = idf)

# get the IdfObject of material named "C5 - 4 IN HW CONCRETE"
mat <- idf$Material[["C5 - 4 IN HW CONCRETE"]]

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$version`
## ------------------------------------------------

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

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$parent`
## ------------------------------------------------

## Not run: 
roof$parent()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$id`
## ------------------------------------------------

## Not run: 
roof$id()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$name`
## ------------------------------------------------

## Not run: 
roof$name()

# NA will be returned if the class does not have name attribute. For example,
# "Version" class
idf$Version$name()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$group_name`
## ------------------------------------------------

## Not run: 
roof$group_name()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$class_name`
## ------------------------------------------------

## Not run: 
roof$class_name()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$definition`
## ------------------------------------------------

## Not run: 
roof$definition()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$comment`
## ------------------------------------------------

## Not run: 
# get object comments
roof$comment()

# add new object comments
roof$comment(c("This is a material named `WD01`", "This object has an ID of 47"))
roof$comment()

# append new comments
roof$comment("This is an appended comment")
roof$comment()

# prepend new comments
roof$comment("This is a prepended comment", append = FALSE)
roof$comment()

# wrap long comments
roof$comment("This is a very long comment that is needed to be wrapped.", width = 30)
roof$comment()

# delete old comments and add new one
roof$comment("This is the only comment", append = NULL)
roof$comment()

# delete all comments
roof$comment(NULL)
roof$comment()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$value`
## ------------------------------------------------

## Not run: 
# get all existing field values
str(mat$value())

# get values of field 1, 3, 5
str(mat$value(c(1, 3, 5)))

# get character format values instead of a named list
mat$value(c(1, 3, 5), simplify = TRUE)

# get values of all field even those that are not set
str(roof$value())
str(roof$value(all = TRUE))

# get field values using shortcuts
mat$Roughness
mat[["Specific_Heat"]]
mat[c(1,2)]
mat[c("Name", "Density")]

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$set`
## ------------------------------------------------

## Not run: 
# set field values
mat$set(name = "new_name", Thickness = 0.02)
mat[c("Name", "Thickness")]

# When `default` argument is set to TRUE and input field values are empty, i.e.
# NULL, the field values will be reset to defaults.
mat[c("Thermal Absorptance", "Solar Absorptance")]

mat$set(visible_absorptance = NULL, Solar_Absorptance = NULL, .default = TRUE)
mat[c("Visible Absorptance", "Solar Absorptance")]

# set field values using shortcuts
mat$Name <- "another_name"
mat$Name
mat[["Thickness"]] <- 0.019
mat$Thickness

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$value_possible`
## ------------------------------------------------

## Not run: 
mat$value_possible()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$validate`
## ------------------------------------------------

## Not run: 
mat$validate()

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

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

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$is_valid`
## ------------------------------------------------

## Not run: 
mat$is_valid()

mat$definition()$field_range("Density")
eplusr_option(validate_level = "none") # have to set validate to "none" to do so
mat$Density <- -1
eplusr_option(validate_level = "final") # change back to "final" validate level
mat$is_valid()

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

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

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$value_relation`
## ------------------------------------------------

## Not run: 
# check each layer's reference of a construction named FLOOR
roof$value_relation("zone name", "ref_to")

# check where is this construction being used
roof$value_relation("name", direction = "ref_by")

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$ref_to_object`
## ------------------------------------------------

## Not run: 
# get other objects that this object refereces
mat$ref_to_object() # not referencing other objects

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$ref_by_object`
## ------------------------------------------------

## Not run: 
# get other objects that reference this object
mat$ref_by_object() # referenced by construction "FLOOR"

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$ref_to_node`
## ------------------------------------------------

## Not run: 
if (is_avail_eplus(8.8)) {
    path <- file.path(eplus_config(8.8)$dir, "ExampleFiles/5Zone_Transformer.idf")
    idf_5z <- read_idf(path)
    idf_5z$NodeList$OutsideAirInletNodes$ref_to_node()
}

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref_to`
## ------------------------------------------------

## Not run: 
mat$has_ref_to()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref_by`
## ------------------------------------------------

## Not run: 
mat$has_ref_by()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref_node`
## ------------------------------------------------

## Not run: 
mat$has_ref_node()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref`
## ------------------------------------------------

## Not run: 
# check if having any referenced objects or is referenced by other objects
mat$has_ref()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$to_table`
## ------------------------------------------------

## Not run: 
# get all object data in a data.table format without field units
str(mat$to_table(unit = FALSE))

# get all object data in a data.table format where all field values are put in a
# list column and field names without unit
str(mat$to_table(string_value = FALSE, unit = FALSE))

# get all object data in a data.table format, including tailing empty fields
str(idf$Zone$`ZONE ONE`$to_table(all = TRUE))

# get all object data in a data.table format where each field becomes a column
str(mat$to_table(wide = TRUE))

# group extensible by extensible group number
surf <- idf$BuildingSurface_Detailed[["Zn001:Roof001"]]
surf$to_table(group_ext = "group")

# group extensible by extensible group number and convert into a wide table
surf$to_table(group_ext = "group", wide = TRUE)

# group extensible by extensible field index
surf$to_table(group_ext = "index")

# group extensible by extensible field index and convert into a wide table
surf$to_table(group_ext = "index", wide = TRUE)

# when grouping extensible, 'string_value' and 'unit' still take effect
surf$to_table(group_ext = "index", wide = TRUE, string_value = FALSE, unit = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$to_string`
## ------------------------------------------------

## Not run: 
# get string format object
mat$to_string()

# get string format of object, and decrease the space between field values and
# field names
mat$to_string(sep_at = 15)

# get string format of object, and decrease the leading space of field values
mat$to_string(leading = 0)

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$print`
## ------------------------------------------------

## Not run: 
# print the object without comment
mat$print(comment = FALSE)

# print the object, and auto separate field values and field names at the
# largetst character length of field values
mat$print(auto_sep = TRUE)

## End(Not run)

[Package eplusr version 0.16.2 Index]

Create and Modify an EnergyPlus Object

Description

Methods

Public methods

Method new()

Usage

Arguments

Details

Returns

Examples

Method version()

Usage

Details

Returns

Examples

Method parent()

Usage

Details

Returns

Examples

Method id()

Usage

Details

Returns

Examples

Method name()

Usage

Details

Returns

Examples

Method group_name()

Usage

Details

Returns

Examples

Method class_name()

Usage

Details

Returns

Examples

Method definition()

Usage

Details

Returns

Examples

Method comment()

Usage

Arguments

Details

Returns

Examples

Method value()

Usage

Arguments

Details

Returns

Examples

Method set()

Usage

Arguments

Details

Examples

Method value_possible()

Usage

Arguments

Details

Returns

Examples

Method validate()

Usage

Arguments

Details

Returns

Examples

Method is_valid()

Usage

Arguments

Details

Returns

Examples

Method `new()`

Method `version()`

Method `parent()`

Method `id()`

Method `name()`

Method `group_name()`

Method `class_name()`

Method `definition()`

Method `comment()`

Method `value()`

Method `set()`

Method `value_possible()`

Method `validate()`

Method `is_valid()`

Method `value_relation()`

Method `ref_to_object()`

Method `ref_by_object()`

Method `ref_to_node()`

Method `has_ref_to()`

Method `has_ref_by()`

Method `has_ref_node()`

Method `has_ref()`

Method `to_table()`

Method `to_string()`

Method `print()`

Method `clone()`