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.

Overview

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. Below is the detailed documentation on each method.

Usage

model <- read_idf(path)
model$version()
model$path()
model$group_name(all = FALSE, sorted = TRUE)
model$class_name(all = FALSE, sorted = TRUE, by_group = FALSE)
model$is_valid_group(group, all = FALSE)
model$is_valid_class(class, all = FALSE)
model$definition(class)
model$object_id(class = NULL, simplify = FALSE)
model$object_name(class = NULL, simplify = FALSE)
model$is_valid_id(id)
model$is_valid_name(name)
model$object_num(class = NULL)
model$object(which)
model$object_unique(class)
model$objects(which)
model$objects_in_class(class)
model$objects_in_group(group)
model$object_relation(which, direction = c("all", "ref_to", "ref_by", "node"),
                      recursive = FALSE, depth = 1L)
model$objects_in_relation(which, direction = c("ref_to", "ref_by", "node"),
                          class = NULL, recursive = FALSE, depth = 1L)
model$search_object(pattern, class = NULL, ignore.case = FALSE, perl = FALSE,
                    fixed = FALSE, useBytes = FALSE)
model$ClassName
model[[ClassName]]
model$dup(...)
model$add(..., .default = TRUE, .all = FALSE)
model$set(..., .default = TRUE, .empty = FALSE)
model$del(..., .ref_by = FALSE, .ref_to = FALSE, .recursive = FALSE, .force = FALSE)
model$insert(..., .unique = TRUE, .empty = FALSE)
model$load(..., .unique = TRUE, .default = TRUE, .empty = FALSE)
model$update(..., .default = TRUE, .empty = FALSE)
model$rename(...)
model$paste(in_ip = FALSE, ver = NULL, unique = TRUE, empty = FALSE)
model$search_value(pattern, class = NULL, ignore.case = FALSE, perl = FALSE,
                   fixed = FALSE, useBytes = FALSE)
model$replace_value(pattern, class = NULL, replacement, ignore.case = FALSE,
                    perl = FALSE, fixed = FALSE, useBytes = FALSE)
model$is_unsaved()
model$validate(level = eplusr_option("validate_level"))
model$is_valid(level = eplusr_option("validate_level"))
model$to_table(which = NULL, class = NULL, string_value = TRUE, unit = FALSE,
               wide = FALSE, align = FALSE, all = FALSE)
model$to_string(which = NULL, class = NULL, comment = TRUE, header = TRUE,
                format = eplusr_option("save_format"), leading = 4L, sep_at = 29L)
model$save(path = NULL, format = eplusr_option("save_format"), overwrite = FALSE,
           copy_external = TRUE)
model$run(weather, dir = NULL, wait = TRUE, force = FALSE, copy_external = FALSE, echo = wait)
model$clone(deep = TRUE)
model$print(zoom = c("object", "class", "group", "field"), order = TRUE)
print(model)

Basic Info

model <- read_idf(path)
model$version()
model$path()
model$group_name(all = FALSE, sorted = TRUE)
model$class_name(all = FALSE, sorted = TRUE, by_group = FALSE)
model$is_valid_group(group, all = FALSE)
model$is_valid_class(class, all = FALSE)

$version() returns the version of current model in a numeric_version format. This makes it easy to direction compare versions of different model, e.g. model1$version() > 8.6 or model1$version() > model2$version().

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

$group_name() returns all groups the model contains when all is FALSE or all groups the underlying Idd object contains when all is TRUE.

$class_name() returns all classes the model contains when all is FALSE or all classes the underlying Idd object contains when all is TRUE.

$is_valid_group() returns TRUEs if given group names are valid for current model (when all is FALSE) or current underlying Idd object (when all is TRUE).

$is_valid_class() returns TRUEs if given class names are valid for current model (when all is FALSE) or underlying Idd object (when all is TRUE).

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

  • all: If FALSE, only values in current Idf object will be returned. If TRUE, all values in the underlying Idd will be returned. For $is_valid_group() and $is_valid_class(), all equals to TRUE means that input group or class names are checked in all existing ones in the underlying Idd object. 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 object. Default: TRUE.

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

  • group: A character vector of valid group names.

  • class: A character vector of valid class names.

Definition

model$definition(class)

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

Arguments:

  • class: A single string of valid class name in current IDD.

Object Info

model$object_id(class = NULL, simplify = FALSE)
model$is_valid_id(id)
model$object_name(class = NULL, simplify = FALSE)
model$is_valid_name(name)
model$object_num(class = NULL)

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

$object_name() returns a character vector (when simplify is TRUE) or a named list (when simplify is FALSE) of all object names in specified classes. The returned list is named using specified class names.

$is_valid_id() and $is_valid_name() returns a logical vector whether the given integer vector or character vector contains valid object IDs or names respectively. Note that for $is_valid_name(), object name matching is case-insensitive.

$object_num() returns an integer vector of object numbers in specified classes.

Arguments:

  • id: An integer vector to check.

  • name: A character vector to check.

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

  • simplify: If TRUE, an integer vector (for $object_id()) or a character vector (for $object_name()) is returned. If FALSE, a list with each element being the data per class is returned. If class is NULL, the order of classes returned is the same as that in the underlying Idd object. Default: FALSE.

Object Relation

model$object_relation(which, direction = c("all", "ref_to", "ref_by", "node"),
                      recursive = TRUE, depth = 1L)

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.

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

Arguments:

  • which: Either a single integer of object ID or a string of object name.

  • direciton: The relation direction to extract. Should be either "all", "ref_to" or "ref_by".

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

  • depth: Only applicable when recursive is TRUE. This is a depth to when searching value relations recursively. If NULL, all recursive relations are returned. Default: 1.

Object Query

model$object(which)
model$objects(which)
model$object_unique(class)
model$objects_in_class(class)
model$objects_in_group(group)
model$objects_in_relation(which, direction = c("ref_to", "ref_by", "node"),
                          class = NULL, recursive = FALSE, depth = 1L)
model$search_object(pattern, class = NULL, ignore.case = FALSE, perl = FALSE,
                    fixed = FALSE, useBytes = FALSE)
model$ClassName
model[[ClassName]]

$object() returns an IdfObject specified by an object ID or name. Note that unlike object ID, which is always unique across the whole Idf object, sometimes 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 an object name(s) as input.

$object_unique() returns the IdfObject in unique-object class, e.g. SimulationControl class. This makes it easy to directly extract and modify those unique objects, e.g.

model$object_unique("SimulationContrl")$set(...)

Note that if there are multiple objects in that unique-object class, an error is issued. This makes sure that $object_unique() always returns a single IdfObject.

$objects() returns a named list of IdfObjects specified by object IDs or names.

$objects_in_class() returns a named list of all IdfObjects in specified class.

$objects_in_group() returns a named list of all IdfObjects in specified group.

$objects_in_relation() returns a named list of IdfObjects that have specified relations with given object. The first element of returned list is always the IdfObject of specified object. If that object does not have specified relation with other objects in specified class, a list that only contains that IdfObject is returned. For instance, assume that const is a valid object name in Construction class, model$objects_in_relation("const", "ref_by", "BuildingSurface:Detailed") will return a named list of an IdfObject named const and also all other IdfObjects in BuildingSurface:Detailed that refer to field values in const. Similarly, model$objects_in_relation("const", "ref_to", "Material") will return a named list of an IdfObject named const and also all other IdfObjects in Material class that const refers to. This makes it easy to directly extract groups of related objects and then use $insert() method described below to insert them. For example, copy a construction named const from an Idf object model1 to another Idf object model2 is simply to do:

model2$insert(model1$objects_in_relation("const", "ref_to"))

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.

$search_object() returns a named list of IdfObjects whose names meet the given pattern in specified classes.

eplusr also provides custom S3 method of $ and [[ to make it more convenient to get IdfObjects in specified class. Basically, model$ClassName and model[[ClassName]], where ClassName is a single valid class name, is equivalent to model$objects_in_class(ClassName) if ClassName is not an unique-object class and model$object_unique(ClassName) if ClassName is an unique-object class. For convenience, underscore-style names are allowed, e.g. BuildingSurface_Detailed is equivalent to BuildingSurface:Detailed. For instance, model$BuildingSurface_Detailed and also model[["BuildingSurface:Detailed"]] will return all IdfObjects in BuildingSurface:Detailed class; model$Building and also model[["Building"]] will return the IdfObject in Building class which is an unique-object class.

Note: The returned list from $objects(), $objects_in_class() and other methods is named using the names of returned IdfObjects in that list. This will makes it easy to using object name to do further subsetting, e.g. model$objects_in_class("Material")$mat will return an IdfObject named mat in Material class, and model$objects_in_class("Material")[[1]] will return the first material in model. If returned IdfObjects belongs to a class that does not have name attribute, such like Version, SimulationControl and etc., NA is assigned as the name.

IdfObject class provides more detailed methods to modify a single object in an Idf. For detailed explanations, please see IdfObject class.

Arguments:

  • which: A single object ID or name for $object() and $objects_in_relation(); an integer vector of object IDs or a character vector of object names for $objects().

  • class: A single string of class name for $object_unique() and $objects_in_class(); a character vector of class names for $objects_in_relation() and $search_object().

  • group: A single string of group name.

  • pattern, ignore.case, perl, fixed and useBytes: All of them are directly passed to base::grepl.

  • ClassName: A single string of class name. For [[, ClassName can be an underscore-style class name, where all characters other than letters and numbers are replaced by underscores _.

  • direciton: The relation direction to extract. Should be either "ref_to" or "ref_by".

  • recursive: If TRUE, the relation is searched recursively, e.g. one material named mat is referred by a construction named const, and const is also referred by a surface named surf, all mat, const and surf are returned.

  • depth: Only applicable when recursive is TRUE. This is a depth to when searching value relations recursively. If NULL, all recursive relations are returned. Default: 1.

  • ignore.case, perl, fixed and useBytes: All are directly passed to base::grepl.

Object Modification

Duplicate Objects

model$dup(...)

$dup() takes integer vectors of object IDs and character vectors of object names, duplicates objects specified, and returns a list of newly created IdfObjects. 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 does not have name attribute.

Note:

  • Assign 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().

Argument:

  • ...: Integer vectors of object IDs and character vectors of valid object names. If input has names, they will be used as the names of newly created objects.

Usage:

  • Without new names: model$dup(c("name1", "name2"), 6:10).

  • With new names: model$dup(c(new_name1 = "name1", new_name2 = "name2"), new_name3 = 6).

  • Variable inputs:

    a <- c("name1", new_name2 = "name2")
    b <- 10:20
    c <- c(new_name3 = 10)
    model$dup(a, b, c)
    

Add Objects

model$add(..., .default = TRUE, .all = FALSE)

$add() takes object definitions in list format, adds corresponding objects in specified classes, returns a list of newly added IdfObjects. Every list should be named with a valid class name. Underscore-style class name is allowed. Names in 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.

Note:

  • Empty objects can be added using an empty list, e.g. model$add(building = list()). All empty fields will be filled with corresponding default value if .default is TRUE, leaving other fields as blank. However, adding blank objects may not be successful if required fields are not valued and current validate level includes missing-required-field checking. For what kind of validation components to be performed during modifications, please see level_checks().

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

  • There is no need to give all field values if only specific fields are interested, unless other fields are not required. For example, to define a new object in RunPeriod class, the following is enough:

    model$add(
        RunPeriod = list(
            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 model$add(Construction = list("out_layer", name = "name")), "out_layer" will be treated as the value of field Outside Layer in Construction class, as value of field Name has been given as "name".

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, each required field in input object must have one value. Otherwise, an error will be issued during validation. Default: TRUE.

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

Usage:

  • Empty object with default values: model$add(Building = list(), .default = TRUE).

  • Empty object with comments: model$add(Building = list(.comment = c("This", "is", "a", "comment"))).

  • Empty object with all fields: model$add(Building = list(), .all = TRUE).

  • New objects:

    model$add(
        RunPeriod = list("rp", 1, 1, end_month = 2, 1, "Monday"),
        list(Construction = list("const", "mat"), Material = list("mat"))
    )
    
  • New objects with comments:

    model$add(RunPeriod = list("rp", 1, 1, 2, 1, .comment = "comment1"))
    
  • Variable inputs:

    x <- list(Construction = list("const"), Building = list())
    model$add(x)
    
    

Set Values of Existing Objects

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

$set() takes new field value definitions in list format, sets new values for fields in objects specified, and returns a list of modified IdfObjects. 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.

There is two special syntax in $set():

  • class := list(field = value): Note the use of := instead of =. The main difference is that, unlike =, the left hand side of := should be a valid class name in current Idf object. It will set the field of all objects in specified class to specified value.

  • .(object, object) := list(field = value): Simimar like above, but note the use of .() in the left hand side. You can put multiple object ID or names in .(). It will set the field of all specified objects to specified value.

Note:

  • You can delete a field by assigning NULL to it, e.g. list(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".

Arguments:

  • ...: Lists of object definitions. Each list should be named with a valid object name or a valid object ID denoted in style ..1, ..2 and etc. There is a special element .comment in each list, which will be used as new comments of modified object, overwriting existing ones.

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

Usage:

  • Specify object with name: model$set(Object_Name = list(val1, val2, val3)).

  • Specify object with ID: model$set(..8 = list(val1)).

  • Overwrite existing object comments: model$set(..8 = list(.comment = c("new", "comment"))).

  • Delete field value: model$set(Object_Name = list(Field_1 = NULL), .default = FALSE).

  • Assign default field value: model$set(Object_Name = list(Field_1 = NULL), .default = TRUE).

  • Variable input: a <- list(Object_Name = list(Field_1 = val1)); model$set(a, .default = TRUE).

  • Set all values of field fld in a class cls: model$set(cls := list(fld = val)).

Deleting Existing Objects

model$del(..., .ref_by = FALSE, .ref_to = FALSE, .recursive = FALSE, .force = FALSE)

$del() takes integer vectors of object IDs and character vectors of object names, and deletes objects specified. 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.

Note:

  • 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 are only deleted when they only have relation with input 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.

Arguments:

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

Usage:

  • Specify object with name: model$del("Object_Name1", "Object_Name2").

  • Specify object with ID: model$del(1, 2, 10).

  • Delete objects even they are referred by other objects: model$del(1:5, .force = TRUE)

  • Delete objects and also other objects that refer to them: model$del(2, "Object_Name1", .ref_by = TRUE)

  • Delete objects and also other objects that refer to them recursively:

    model$del(1:5, .ref_by = TRUE, .recursive = TRUE)
    
  • Delete objects and also other objects that input objects refer to: model$del(1:5, .ref_to = TRUE)

  • Variable input: x <- c("Object_Name1", "Object_Name2"); y <- c(1:5); model$del(x, y).

Rename Objects

model$rename(...)

$rename() takes named character vectors of object names and named integer vectors of object IDs, renames specified object to names of input vectors and returns a list of renamed IdfObjects. An error will be issued if trying to "rename" an object which does not have name attribute.

Argument:

  • ...: Integer vectors of valid object IDs and character vectors of valid object names. Each element should be named. That name is used at the new object name.

Usage:

  • Rename objects: model$rename(c(new_name1 = "name1", new_name2 = "name2"), new_name3 = 6).

  • Variable inputs:

    a <- c(new_name1 = "name1", new_name2 = "name2")
    b <- c(new_name3 = 10)
    model$rename(a, b)
    

Insert Objects

model$insert(..., .unique = TRUE, .empty = FALSE)

$insert() takes IdfObjects or lists of IdfObjects as input, inserts them into current Idf, and returns a list of inserted IdfObjects.

Note:

  • You cannot insert an IdfObject which comes from a different version than current Idf object.

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

  • If input IdfObject has the same name as one IdfObject in current Idf object but field values are not equal, an error may be issued if current validation level includes conflicted-name checking. For what kind of validation components to be performed during modifications, please see level_checks().

Argument:

  • ...: IdfObjects or lists of IdfObjects.

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

Usage:

  • Insert objects without new names: model1$insert(model2$Material).

  • Insert an object without new name: model1$insert(my_material = model2$Material[[1]]).

  • Insert objects but keep duplications: model1$insert(model1$Output_Variable).

  • Variable input: mat <- model2$Material; names(mat) <- c("mat1", "mat2"); model1$insert(mat).

Load Objects from characters or data.frames

model$load(..., .unique = TRUE, .default = TRUE, .empty = FALSE)

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

For object definitions in character vector format, they follow the same rules as normal IDF file. Each object starts with a class name and a comma (,), separates each values with a comma (,) and ends with a semicolon (;). Noted that you can also provide headers 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, IddObject, Idf and IdfObject class. A valid definition requires at least three columns described below. Note that column order does not matter.

  • class: Mandatory. Character type. Valid class names in the underlying Idd object. You can get all valid class names using use_idd(model$version())$class_name()

  • index: Mandatory. Integer type. Valid field indexes for each class.

  • value: Mandatory. Character type or list type. The value of each field to be added.

    • If value is a character column, usually when string_value is TRUE in method $to_table() in Idf and IdfObject class. Each value should be given as a string even if the corresponding field is a numeric type.

    • If value is a list column, usually when string_value is set to FALSE in method $to_table() in Idf and IdfObject class. Each value should have the right type as the corresponding field definition. Otherwise, errors will be issued during if current validation level includes invalid-type checking. For what kind of validation components to be performed during modifications, please see level_checks().

  • id: Optional. Integer type. If input data.frame includes multiple object definitions in a same class, the value in id will be used to distinguish each definition. If id column does not exists, it assumes that each definition is separated by class column and will issue an error if there is any duplication in the index column.

Note:

  • $load() assume 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.

Argument:

  • ...: Character vectors or data.frames of object definitions For details, see above.

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

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

Usage:

  • Load objects from string definitions:

    model$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 <- model1$to_table(class = "Material")
    dt[field == "thickness", value := "0.5"]
    model$load(dt)
    

Update Objects from characters or data.frames

model$update(..., .unique = TRUE, .default = TRUE, .empty = FALSE)

$update() is similar to $load() except it update field values. This makes it easy to update object values using the output from $to_string() and $to_table method from Idd, IddObject, also Idf and IdfObject class.

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 it can be achieved using data.frame format as it uses object IDs instead of object names to locate objects.

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

  • id: Integer type. The value in id should be valid object IDs for current Idf.

  • class: Character type. Valid class names for current Idf.

  • index: Integer type. Valid field indexes for each class. If input field does not exist in specified object, it will be added on the fly.

  • value: Character type or list type. The value of each field to be added.

    • If value is a character column, usually when string_value is TRUE in method $to_table() in Idf and IdfObject class. Each value should be given as a string even if the corresponding field is a numeric type.

    • If value is a list column, usually when string_value is set to FALSE in method $to_table() in Idf and IdfObject class. Each value should have the right type as the corresponding field definition. Otherwise, errors will be issued during if current validation level includes invalid-type checking. For what kind of validation components to be performed during modifications, please see level_checks().

Note:

  • $update() assume 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.

Argument:

  • ...: Character vectors or data.frames of object definitions For details, see above.

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

Usage:

  • Update objects from string definitions:

    str <- model$Material[[1]]$to_string()
    str[4] <- "0.8"
    model$update(str)
    
  • Update objects from data.frame definitions:

    dt <- model1$to_table(class = "Material")
    dt[field == "thickness", value := "0.5"]
    model$update(dt)
    

Paste Objects from IDF Editor

model$paste(in_ip = FALSE, ver = NULL, unique = TRUE, empty = FALSE)

$paste() reads the contents (from clipboard) of copied objects from IDF Editor (after hitting Copy Obj button), parses it and inserts corresponding objects into current Idf. As IDF Editor only available on Windows platform, $paste() only works on Windows too.

Note:

  • There is no version data copied to the clipboard when copying objects in IDF Editor. It is possible that IDF Editor opens an IDF with different version than current IDF. 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.

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

Usage:

  • Paste objects from same version: model$paste().

  • Paste objects from different version: model$paste(ver = "version").

  • Paste objects that are viewed in IP units in IDF Editor: model$paste(in_ip = TRUE).

  • Paste objects but also keep duplications: model$paste(unique = FALSE).

Search and Replace Values

model$search_value(pattern, class = NULL, ignore.case = FALSE, perl = FALSE,
                   fixed = FALSE, useBytes = FALSE)
model$replace_value(pattern, class = NULL, replacement, ignore.case = FALSE,
                    perl = FALSE, fixed = FALSE, useBytes = FALSE)

$search_value() returns a list of IdfObjects that contain values which match the given pattern. If no matched found, NULL is returned invisibly.

$replace_value() returns a list of IdfObjects whose values have been replace with given pattern. If no matched found, NULL is returned invisibly.

Note:

  • During matching, all values are treated as characters, including numeric values.

  • Replacing values using regular expression is not recommended, because it is error prone. Validation rules also apply during replacing.

Arguments:

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

  • pattern, replacement, ignore.case, perl, fixed and useBytes: All of them are directly passed to base::grepl and base::gsub.

Usage:

  • Search values that contains supply: model$search_value("supply")

  • Search values that contains supply or demand in class Branch:

    model$search_value("supply|demand", "Branch")
    
  • Search values that contains win and replace them with windows:

    model$replace_value("win", "windows")
    

Validation

model$validate(level = eplusr_option("validate_level"))
model$is_valid(level = eplusr_option("validate_level"))

$validate() checks if there are errors in current Idf under specified validation level and returns an IdfValidity object which contains data of invalid field values. Different validation 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 validation checks in specified validation 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 validation results show that after all validation components performed under current validation level, 2 invalid field values are found. All of them are in 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 set those two fields to correct value by doing idf$set(..176 = list(Maximum Flow per Zone Floor Area During Reheat= "autosize",Maximum Flow Fraction During Reheat = "autosize" ))

$is_valid() returns TRUE if there is no error in current Idf object under specified validation level and FALSE otherwise.

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. In total, There are 10 different validation check components. To get the meaning of each component, please see level_checks() and custom_validate().

  • missing_object

  • duplicate_object

  • conflict_name

  • incomplete_extensible

  • missing_value

  • invalid_autosize

  • invalid_autocalculate

  • invalid_character

  • invalid_numeric

  • invalid_integer

  • invalid_choice

  • invalid_range

  • invalid_reference

Except missing_object, which is a character vector, 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.

Data Extraction

model$to_table(which = NULL, class = NULL, string_value = TRUE, unit = FALSE,
               wide = FALSE, align = FALSE, all = FALSE)
model$to_string(which = NULL, class = NULL, comment = TRUE, header = TRUE,
                format = eplusr_option("save_format"), leading = 4L, sep_at = 29L)

$to_table() returns a data.table that contains core data of specified objects. 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. Field values.

$to_string() returns the text format of an IDF file.

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. 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 of the class that objects specified belong to will be returned. Default: FALSE.

  • 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. For details, please see $save(). 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.

Save

model$is_unsaved()
model$save(path = NULL, format = eplusr_option("save_format"), overwrite = FALSE,
           copy_external = TRUE)

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

$save() saves the Idf object as an IDF file.

Arguments:

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

  • format: A string to specify the saving format. Should be one of "asis", "sorted", "new_top", and "new_bot".

    • If "asis", the model will be saved in the same format as it was when first read. If the model 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 that current Idf depends on 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. Currently, only Schedule:File class is supported. Default: FALSE.

Clone

model$clone(deep = TRUE)

$clone() returns the exactly the same cloned model. Because Idf uses R6::R6Class() under the hook which has "modify-in-place" semantics, idf_2 <- idf_1 does not copy idf_1 at all but only create a new binding to idf_1. Modify idf_1 will also affect idf_2 as well, as these two are exactly the same thing underneath. In order to create a complete cloned copy, use $clone(deep = TRUE).

Arguments:

  • deep: Has to be TRUE if a complete cloned copy is desired. Default: TRUE.

Run Model

model$run(weather, dir = NULL, wait = TRUE, force = FALSE, copy_external = FALSE, echo = wait)

$run() calls corresponding version of EnergyPlus to run the current model 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.

Note:

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

  • eplusr uses the EnergyPlus SQL output for extracting simulation results. In order to do so, an object in Output:SQLite class with Option Type value being SimpleAndTabular will be automatically created if it does not exists.

  • In order to make sure .rdd (Report Data Dictionary) and .mdd (Meter Data Dictionary) files are created during simulation, an object in Output:VariableDictionary class with Key Field value being IDF will be automatically created if it does not exists.

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 this needs at least one Sizing:DesignDay object exists in the Idf.

  • dir: The directory to save the simulation results. If NULL, the model folder will be used. Default: NULL

  • wait: Whether to wait until the simulation completes and print the standard output and error of EnergyPlus to the screen. 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. Currently, only Schedule:File class is supported. 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.

Print

model$print(zoom = c("object", "class", "group", "field"), order = TRUE)
print(model)

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

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 **<C>**lasses existing in that group.

    • "class": all class names are shown with prevailing square bracket showing how many **<O>**bjects 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.

See also

IdfObject class

Examples

if (FALSE) { # ===== CREATE ===== # read an IDF file idf <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"), idd = use_idd(8.8, download = "auto")) # ===== MODEL BASIC INFO ===== # get version idf$version() # get path idf$path() # get names of all groups in current model str(idf$group_name()) # get names of all defined groups in the IDD str(idf$group_name(all = TRUE)) # get names of all classes in current model str(idf$class_name()) # get names of all defined classes in the IDD str(idf$class_name(all = TRUE)) # check if input is a valid group name in current model idf$is_valid_group("Schedules") idf$is_valid_group("Compliance Objects") # check if input is a valid group name in IDD idf$is_valid_group("Compliance Objects", all = TRUE) # check if input is a valid class name in current model idf$is_valid_class("Building") idf$is_valid_class("ShadowCalculation") # check if input is a valid class name in IDD idf$is_valid_class("ShadowCalculation", all = TRUE) # ===== OBJECT DEFINITION (IDDOBJECT) ===== # get the a list of underlying IddObjects idf$definition("Version") # ===== OBJECT INFO ===== # get IDs of objects in classes idf$object_id(c("Version", "Zone")) # when `simplify` is TRUE, an integer vector will be returned instead of a # named list idf$object_id(c("Version", "Zone"), simplify = TRUE) # get names of objects in classes # NA will be returned if targeted class does not have a name attribute idf$object_name(c("Building", "Zone", "Version")) # if `simplify` is TRUE, a character vector will be returned instead of a # named list idf$object_name(c("Building", "Zone", "Version"), simplify = TRUE) # get number of objects in classes idf$object_num(c("Zone", "Schedule:Compact")) # check if input is a valid object ID, i.e. there is an object whose ID is # the same with input integer idf$is_valid_id(c(51, 1000)) # check if input is a valid object name, i.e., there is an object whose name is # the same with input string idf$is_valid_name(c("Simple One Zone (Wireframe DXF)", "ZONE ONE")) # ===== OBJECT QUERY ===== # get single object using object ID or name # NOTE: object name matching is case-insensitive idf$object(3) idf$object("simple one zone (wireframe dxf)") # get objects using object IDs or names # NOTE: object name matching is case-insensitive idf$objects(c(3,10)) idf$objects(c("Simple One Zone (Wireframe DXF)", "zone one")) # the names of returned list are object names names(idf$objects(c("Simple One Zone (Wireframe DXF)", "zone one"))) # get all objects in classes in a named list idf$objects_in_class("Zone") names(idf$objects_in_class("Zone")) # OR using shortcuts idf$Zone idf[["Zone"]] # get a single object in unique-object class idf$object_unique("SimulationControl") idf$SimulationControl idf[["SimulationControl"]] # search objects using regular expression length(idf$search_object("R13")) names(idf$search_object("R13")) # search objects using regular expression in specifc class length(idf$search_object("R13", class = "Construction")) names(idf$search_object("R13", class = "Construction")) # get more controls on matching length(idf$search_object("r\\d", ignore.case = TRUE, class = "Construction")) names(idf$search_object("r\\d", ignore.case = TRUE, class = "Construction")) # ===== DUPLICATE OBJECTS ===== # duplicate objects in "Construction" class names(idf$Construction) idf$dup("R13WALL") # new objects will have the same names as the duplicated objects but with a # suffix "_1", "_2" and etc. names(idf$Construction) # new names can also be explicitly specified idf$dup(My_R13Wall = "R13WALL") # duplicate an object multiple times idf$dup(rep("R13WALL", times = 10)) # ===== ADD OBJECTS ===== # add two new objects in "RunPeriod" class idf$add( RunPeriod = list("rp_test_1", 1, 1, 2, 1, .comment = c("Comment for new object 1", "Another comment") ), RunPeriod = list(name = "rp_test_2", begin_month = 3, begin_day_of_month = 1, end_month = 4, end_day_of_month = 1, .comment = "Comment for new object 2" ) ) # ===== LOAD OBJECTS ===== # load objects from character vector idf$load("RunPeriod, rp_test_3, 1, 1, 2, 1;") # load objects from data.frames dt <- idf$definition("RunPeriod")$to_table() ## (a) values can be supplied as characters dt[1:5, value := c("rp_test_4", "2", "1", "3", "1")] idf$load(dt) ## (b) values can be supplied as list dt[1:5, value := list("rp_test_5", 3, 1, 4, 1)] idf$load(dt) # ===== INSERT OBJECTS ===== # insert objects from other Idf object idf_1 <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"), idd = use_idd(8.8, download = "auto")) idf_1$object_name("Material") # rename material name from "C5 - 4 IN HW CONCRETE" to "test", otherwise # insertion will be aborted as there will be two materials with the same name # in the idf idf_1$Material$`C5 - 4 IN HW CONCRETE`$set(name = "test") # insert the object idf$insert(idf_1$Material$test) # check if material named "test" is there idf$object_name("Material") # $insert() is useful when importing design days from a ".ddy" file idf$insert(read_idf("foo.ddy")) # ===== SET OBJECTS ===== # set the thickness of newly inserted material "test" to 0.2 m idf$set(test = list(thickness = 0.2)) idf$Material$test$Thickness # set thermal absorptance of all material to 0.85 val <- rep(list(list(thermal_absorptance = 0.85)), idf$object_num("Material")) names(val) <- idf$object_name("Material", simplify = TRUE) idf$set(val) # check results lapply(idf$Material, function (mat) mat$Thermal_Absorptance) # reset thermal absorptance of all material to the default val <- rep(list(list(thermal_absorptance = NULL)), idf$object_num("Material")) names(val) <- idf$object_name("Material", simplify = TRUE) idf$set(val) # check results lapply(idf$Material, function (mat) mat$Thermal_Absorptance) # ===== UPDATE OBJECTS ===== # update roughness of new added material "test" to "Smooth" idf$update("Material, test, smooth;") # update solar absorptance of all materials to 0.8 dt <- idf$to_table(class = "Material", string_value = TRUE) idf$update(dt[field == "Solar Absorptance", value := "0.8"]) # ===== RENAME OBJECTS ===== idf$rename(new_test = "test") idf$object_name("Material") # ===== DELELTE OBJECTS ===== # delete the added run period "rp_test_1", "rp_test_2" and "new_test" from above idf$del(c("new_test", "rp_test_1", "rp_test_2")) names(idf$Material) names(idf$RunPeriod) # In "final" validate level, delete will be aborted if the target objects are # referenced by other objects. # get objects that referenced material "R13LAYER" eplusr_option("validate_level") idf$Material_NoMass$R13LAYER$ref_by_object() length(idf$Material_NoMass$R13LAYER$ref_by_object()) idf$del("R13LAYER") # will give an error in "final" validate level # objects referencing target objects can also be deleted by setting # `referenced` to TRUE idf$del("R13LAYER", .ref_by = TRUE) # will give an error in "final" validate level # it is possible to force delete objects idf$del("R13LAYER", .ref_by = TRUE, .force = TRUE) # ===== SEARCH ADN REPLACE OBJECT VALUES ===== # get objects whose field values contains both "VAV" and "Node" idf$search_value("WALL") length(idf$search_value("WALL")) names(idf$search_value("WALL")) # replace values using regular expression idf$replace_value("WALL", "A_WALL") # ===== VALIDATE MODEL ===== # check if there are errors in current model idf$validate() idf$is_valid() # change validate level to "none", which will enable invalid modifications eplusr_option(validate_level = "none") # change the outside layer of floor to an invalid material idf$set(FLOOR = list(outside_layer = "wrong_layer")) # change validate level back to "final" and validate the model again eplusr_option(validate_level = "final") idf$validate() idf$is_valid() # get IDs of all objects that contains invalid reference fields idf$validate()$invalid_reference$object_id # fix the error idf$set(..16 = list(outside_layer = idf$Material[[1]]$name())) idf$validate() idf$is_valid() # ===== FORMAT MODEL ===== # get text format of the model head(idf$to_string()) # get text format of the model, excluding the header and all comments head(idf$to_string(comment = FALSE, header = FALSE)) # ===== SAVE MODEL ===== # check if the model has been modified since read or last saved idf$is_unsaved() # save and overwrite current model 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 idf$save(path = file.path(tempdir(), "test.idf")) # 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) # the path of this model will be changed to the saved path idf$path() # ===== CLONE MODEL ===== # Idf object are modified in place and has reference semantic. idf_2 <- idf idf_2$object_name("Building") idf$object_name("Building") # modify idf_2 will also affect idf as well idf_2$Building$set(name = "Building_Name_Changed") idf_2$object_name("Building") idf$object_name("Building") # in order to make a copy of an Idf object, use $clone() method idf_3 <- idf$clone(deep = TRUE) idf_3$Building$set(name = "Building_Name_Changed_Again") idf_3$object_name("Building") idf$object_name("Building") # ===== RUN MODEL ===== if (is_avail_eplus(8.8)) { # 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] basename(epw) # [1] "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw" # 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() } # ===== PRINT MODEL ===== idf$print("group") idf$print("class") idf$print("object") idf$print("field") }