idf: Read, modify, and run an EnergyPlus model

Description Overview Usage Basic Info Definition Object Info Object Query Object Modification Validation Format Output Save Clone Run Model Print Author(s) See Also

Description

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

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 data.frame format. To speed up the whole process, the data.table::data.table() is used instead of the base data.frame. Every IDF is parsed and stored in four tables:

IDD file is parsed and stored in a similar structure. For details, please see Idd class.

So to modify an EnergyPlus model in eplusr is equal to change the data in those four tables accordingly, in the context of specific IDD data.

All IDF reading process starts with read_idf() which returns an Idf object. The model will be printed in a similar style you see in IDFEditor, with additional heading lines show the Path, Version of the model. The classes of objects in the model are ordered by group and the number of objects in classes are shown in square bracket.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
model$version()
model$path()
model$group_name(all = FALSE)
model$class_name(all = 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$object_num(class = NULL)
model$is_valid_id(id)
model$is_valid_name(name)
model$object(id)
model$object_in_class(class)
model$search_object(pattern, class = NULL)
model$ClassName
model[[ClassName]]
model$dup_object(object, new_name = NULL)
model$add_object(class, value = NULL, comment = NULL, default = TRUE, all = FALSE)
model$ins_object(object)
model$set_object(object)
model$del_object(object, referenced = FALSE)
model$search_value(pattern)
model$replace_value(pattern, replacement)
model$validate()
model$is_valid
model$string(comment = TRUE, header = TRUE, ...)
model$is_unsaved()
model$save(path = NULL, format = c("sorted", "new_top", "new_bot"), overwrite = FALSE, copy_external = TRUE)
model$clone()
model$run(weather = NULL, dir = NULL, wait = TRUE, force = FALSE)
model$print(plain = FALSE)
print(model)

Basic Info

1
2
3
4
5
6
model$version()
model$path()
model$group_name(all = FALSE)
model$class_name(all = FALSE)
model$is_valid_group(group, all = FALSE)
model$is_valid_class(class, all = FALSE)

$version() will return the version of current model.

$path() will return the path of current model or NULL if the model is created using a character vector.

$group_name() will return all groups the model contains when all is FALSE or all groups the Idd contains when all is TRUE.

$class_name() will return all classes the model contains when all is FALSE or all classes the Idd contains when all is TRUE.

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

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

Arguments

Definition

1
model$definition(class)

$definition() will return the definitions, i.e. the IddObjects, of given classes which contain all data used for parsing IdfObjects. For details of IdfObject, please see IddObject class.

Arguments

Object Info

1
2
3
4
5
model$object_id(class = NULL, simplify = FALSE)
model$object_name(class = NULL, simplify = FALSE)
model$object_num(class = NULL)
model$is_valid_id(id)
model$is_valid_name(name)

$object_id() and $object_name() will return all object IDs and names in specified class respectively. For $object_name(), if the specified class does not have name attributes, such as SimulationContrl, NA will be returned.

$is_valid_id() and $is_valid_name() will return TRUEs if given integers or strings are valid object IDs or object names respectively.

$object_num() will return the number of objects in specified classes.

Arguments

Object Query

1
2
3
4
5
model$object(which)
model$object_in_class(class)
model$search_object(pattern, class = NULL)
model$ClassName
model[[ClassName]]

$object() will return a list of IdfObjects specified by object IDs or names.

$object_in_class() will return a list of all IdfObjects in specified classes.

$search_object() will return a 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 class. Basically, model$ClassName and model[[ClassName]], where ClassName is a single valid class name, is equivalent to model$object_in_class(ClassName).

All above methods will return a named list of IdfObjects. If the class does not have name attribute, then NA will be used.

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

Arguments

Object Modification

1
2
3
4
5
6
7
model$dup_object(object, new_name = NULL)
model$add_object(class, value = NULL, comment = NULL, default = TRUE, all = FALSE)
model$ins_object(object)
model$set_object(object)
model$del_object(object, referenced = FALSE)
model$search_value(pattern)
model$replace_value(pattern, replacement)

$dup_object() will duplicate objects specified by object IDs or names. The newly created objects will be renamed automatically if new names are not given, with a suffix "_1", "_2" and etc.

$add_object() will add objects in the specified class.

$ins_object() will insert objects from other IDF into current IDF.

$set_object() will set the value of fields in the objects specified by object IDs or names.

$del_object() will delete objects specified by object IDs or names.

$search_value() will return values that match the given pattern.

$replace_value() will return replace values that match the given pattern.

NOTE: There is no field validation when using $replace_value() to change field values. $replace_value() should be treated as a low-level method which should be used with caution.

Arguments

Validation

1
2
model$validate()
model$is_valid()

$validate() will check if there are errors in current model under different strictness level.

$is_valid() will check if there are no errors in current model under different strictness level.

The strictness level can be changed using eplusr_option(). Default is "final".There are three different validate levels, i.e. "none", "draft" and "final":

Format Output

1
model$string(comment = TRUE, header = TRUE)

$string() will return the text format of an IDF file.

Arguments

Save

1
2
model$is_unsaved()
model$save(path = NULL, format = c("asis", "sorted", "new_top", "new_bot"), overwrite = FALSE, copy_external = TRUE)

$is_unsaved() will check if there are modifications on the model since it was read or since last time it was saved.

$save() will save the model into local disk.

Arguments

Clone

1
model$clone(deep = FALSE)

$clone() will copy and returned the cloned model. Because Idf use R6Class under the hook, 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.

Arguments

Run Model

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

$run() will run the current model within specified weather using corresponding version of EnergyPlus. The model and the weather used will be copied to the output directory. An EplusJob will be returned which provides detailed info of the simulation and methods to collect simulation results. Please see eplus_job() for more detailed.

eplusr uses the EnergyPlus command line interface which was introduced since EnergyPlus 8.3.0. So $run only supports models with version higher than 8.3.0.

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

Arguments

Print

1
2
model$print(plain = FALSE)
print(model)

$print() will print the model in the similar format as what you will see in IDFEditor.

Arguments

Author(s)

Hongyuan Jia

See Also

IdfObject class


hongyuanjia/eplusr documentation built on Aug. 12, 2018, 12:24 p.m.