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.
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.
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)
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 TRUE
s 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 TRUE
s 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.
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.
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
.
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
.
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.
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)
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)
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))
.
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)
.
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)
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:
.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)
.
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)
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)
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)
.
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")
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.
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.
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
.
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
.
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
.
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
.
IdfObject class
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") }