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.
Internally, the powerful data.table package is used to speed up the whole IDF parsing process and store the results. Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD data in data.table::data.table format. Every IDF will be parsed and stored in three tables:
object: contains object IDs, names and comments.
value: contains field values
reference: contains cross-reference data of field values.
IdfObject class for a single object in an IDF.
new()Create an Idf object
Idf$new(path, idd = NULL, encoding = "unknown")pathEither a path, a connection, or literal data (either a single
string or a raw vector) to an EnergyPlus Input Data File
(IDF). If a file path, that file usually has a extension
.idf.
iddAny acceptable input of use_idd(). If NULL, which is the
default, the version of IDF will be passed to use_idd(). If
the input is an .ddy file which does not have a version
field, the latest version of Idf cached will be used.
encodingThe file encoding of input IDF. Should be one of
"unknown", "Latin-1" and "UTF-8". The default is "unknown"` which means that the file is encoded in the native
encoding.
It takes an EnergyPlus Input Data File (IDF) as input and returns an
Idf object.
Currently, Imf file is not fully supported. All EpMacro lines will be treated as normal comments of the nearest downwards object. If input is an Imf file, a warning will be given during parsing. It is recommended to convert the Imf file to an Idf file and use ParametricJob class to conduct parametric analysis.
\dontrun{
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8
# If neither EnergyPlus v8.8 nor Idd v8.8 was found, error will
# occur. If Idd v8.8 is found, it will be used automatically.
idf <- Idf$new(path_idf)
# argument `idd` can be specified explicitly using `use_idd()`
idf <- Idf$new(path_idf, idd = use_idd(8.8))
# you can set `download` arugment to "auto" in `use_idd()` if you
# want to automatically download corresponding IDD file when
# necessary
idf <- Idf$new(path_idf, use_idd(8.8, download = "auto"))
# Besides use a path to an IDF file, you can also provide IDF in literal
# string format
string_idf <-
"
Version, 8.8;
Building,
Building; !- Name
"
Idf$new(string_idf, use_idd(8.8, download = "auto"))
}
version()Get the version of current Idf
$version() returns the version of current Idf in a
base::numeric_version() format. This makes it easy to direction
compare versions of different Idfs, e.g. idf$version() > 8.6 or
idf1$version() > idf2$version().
A base::numeric_version() object.
path()Get the file path of current Idf
group_name()Get names of groups
allIf FALSE, only names of groups in current Idf object
will be returned. If TRUE, all group names in the underlying
Idd will be returned. Default: FALSE.
sortedOnly applicable when all is FALSE. If TRUE,
duplications in returned group or class names are removed, and
unique names are further sorted according to their occurrences
in the underlying Idd. Default: TRUE.
$group_name() returns names of groups current Idf contains or
the underlying Idd object contains.
class_name()Get names of classes
allIf FALSE, only names of classes in current Idf object
will be returned. If TRUE, all class names in the underlying
Idd will be returned. Default: FALSE.
sortedOnly applicable when all is FALSE. If TRUE,
duplications in returned group or class names are removed, and
unique names are further sorted according to their occurrences
in the underlying Idd. Default: TRUE.
by_groupOnly applicable when all or sorted is TRUE. If
TRUE, a list is returned which separates class names by the
group they belong to.
$class_name() returns names of classes current Idf contains or
the underlying Idd object contains.
A character vector if by_group is FALSE and a list of
character vectors when by_group is TRUE.
\dontrun{
# get names of all classes in Idf
idf$class_name()
# get names of all classes grouped by group names in Idf
idf$class_name(by_group = TRUE)
# get class name of each object in Idf
idf$class_name(sorted = FALSE)
# get names of all available classes in underlying Idd
idf$class_name(all = TRUE)
# get names of all available classes grouped by group names in
# underlying Idd
idf$class_name(all = TRUE, by_group = TRUE)
}
is_valid_group()Check if elements in input character vector are valid group names.
groupA character vector to check.
allIf FALSE, check if input characters are valid group names
for current Idf. If TRUE, check if input characters are
valid group names for underlying Idd. Default: FALSE
$is_valid_group() returns TRUEs if given character vector
contains valid group names in the context of current Idf (when
all is FALSE) or current underlying Idd (when all is TRUE).
Note that case-sensitive matching is performed, which means that
"Location and Climate" is a valid group name but "location and climate" is not.
is_valid_class()Check if elements in input character vector are valid class names.
classA character vector to check.
allIf FALSE, check if input characters are valid class names
for current Idf. If TRUE, check if input characters are
valid class names for underlying Idd. Default: FALSE
$is_valid_class() returns TRUEs if given character vector
contains valid class names in the context of current Idf (when
all is FALSE) or current underlying Idd (when all is TRUE),
and FALSEs otherwise.
Note that case-sensitive matching is performed, which means that
"Version" is a valid class name but "version" is not.
definition()Get the IddObject object for specified class.
object_id()Get the unique ID for each object in specified classes in the Idf.
classA character vector that contains valid class names for
current Idf object. If NULL, all classes in current Idf
object are used. Default: NULL.
simplifyIf TRUE, an integer vector contains object IDs of
all specified classes is returned. If FALSE, a named list
that contains object IDs for each specified class is returned.
Default: FALSE.
In Idf, each object is assigned with an integer as an universally
unique identifier (UUID) in the context of current Idf. UUID is
not reused even if the object associated is deleted.
$object_id() returns an integer vector (when simplify is TRUE)
or a named list (when simplify is FALSE) of integer vectors that
contain object IDs in each specified class. The returned list is
named using specified class names.
An integer vector (when simplify is TRUE) or a named list
of integer vectors (when simplify is FALSE).
\dontrun{
# get IDs of all objects in current Idf object
idf$object_id()
# get IDs of all objects in current Idf object, and merge them into a
# single integer vector
idf$object_id(simplify = TRUE)
# get IDs of objects in class Version and Zone
idf$object_id(c("Version", "Zone"))
# get IDs of objects in class Version and Zone, and merge them into a
# single integer vector
idf$object_id(c("Version", "Zone"), simplify = TRUE)
}
object_name()Get names for objects in specified classes in the Idf.
classA character vector that contains valid class names for
current Idf. If NULL, all classes in current Idf are
used. Default: NULL.
simplifyIf TRUE, a character vector contains object names
of all specified classes is returned. If FALSE, a named list
that contains a character vector for each specified class is
returned. Default: FALSE.
In Idf, each object is assigned with a single string as the name
for it, if the class it belongs to has name attribute, e.g. class
RunPeriod, Material and etc. That name should be unique among all
objects in that class. EnergyPlus will fail with an error if
duplications are found among object names in a class.
$object_name() returns a character vector (when simplify is
TRUE) or a named list (when simplify is FALSE) of character
vectors that contain object IDs in each specified class. The returned
list is named using specified class names. If specified class does
not have name attribute, NAs are returned.
A character vector (when simplify is TRUE) or a named
list of character vectors (when simplify is FALSE).
\dontrun{
# get names of all objects in current Idf object
idf$object_name()
# get names of all objects in current Idf object, and merge them into
# a single character vector
idf$object_name(simplify = TRUE)
# get names of objects in class Version and Zone
idf$object_name(c("Version", "Zone"))
# get names of objects in class Version and Zone, and merge them into
# a single character vector
idf$object_name(c("Version", "Zone"), simplify = TRUE)
}
object_num()Get number of objects in specified classes in the Idf object.
classA character vector that contains valid class names for
underlying Idd. If NULL, all classes in current Idf are
used, and the total object number is returned. Default: NULL.
is_valid_id()Check if elements in input integer vector are valid object IDs.
idAn integer vector to check.
classA single string indicates the class where the objects to
check against. If NULL, all classes in current Idf are
used. Default: NULL.
is_valid_name()Check if elements in input character vector are valid object names.
nameA character vector to check.
classA single string indicates the class where the objects to
check against. If NULL, all classes in current Idf are
used. Default: NULL.
object()Extract an IdfObject object using object ID or name.
whichA single integer specifying the object ID or a single string specifying the object name.
classA character vector that contains valid class names for
current Idf object used to locate objects. If NULL, all
classes in current Idf object are used. Default: NULL.
$object() returns an IdfObject object specified by an object ID
or name.
Note that unlike object ID, which is always unique across the whole
Idf object, different objects can have the same name. If the name
given matches multiple objects, an error is issued showing what
objects are matched by the same name. This behavior is consistent in
all methods that take object name(s) as input. In this case, it is
suggested to directly use object ID instead of name.
Note that case-insensitive matching is performed for object
names, which means that "rOoF" is equivalent to "roof". This
behavior is consistent in all methods that take object name(s) as
input.
An IdfObject object.
objects()Extract multiple IdfObject objects using object IDs or names.
whichAn integer vector specifying object IDs or a character vector specifying object names.
$objects() returns a named list of IdfObject objects using object
IDS or names. The returned list is named using object names.
Note that unlike object ID, which is always unique across the whole
Idf object, different objects can have the same name. If the name
given matches multiple objects, an error is issued showing what
objects are matched by the same name. This behavior is consistent in
all methods that take object name(s) as input. In this case, it is
suggested to directly use object ID instead of name.
Note that case-insensitive matching is performed for object
names, which means that "rOoF" is equivalent to "roof". This
behavior is consistent in all methods that take object name(s) as
input.
A named list of IdfObject objects.
object_unique()Extract the IdfObject in class with unique-object attribute.
For each version of an Idf object, the corresponding underlying
Idd describe how many objects can be defined in each class. Classes
that have unique-object attribute can only hold a single object,
e.g. Version, SimulationControl and etc. $object_unique() can
be used to directly return the IdfObject in one unique-object
class. An error will be issued if there are multiple objects in that
class or input class is not an unique-object class. This makes sure
that $object_unique() always returns a single IdfObject.
Idf class also provides custom S3 method of $ and [[ to
make it more convenient to get the IdfObject in unique-object
class. Basically, idf$ClassName and idf[["ClassName"]],
where ClassName is a single valid class name, is equivalent to
idf$object_unique(ClassName) if ClassName is an unique-object
class. For convenience, underscore-style names are allowed when using
$, e.g. Site_Location is equivalent to Site:Location. For
instance, idf$Site_Location and also idf[["Site_Location"]] will
both return the IdfObjects in Site:Location class. Note that
unlike $object_unique(), idf$ClassName and idf[["ClassName"]]
will directly return NULL instead of giving an error when
ClassName is not a valid class name in current Idf object. This
makes it possible to use is.null(idf$ClassName) to check if
ClassName is a valid class or not.
An IdfObject object.
objects_in_class()Extract all IdfObject objects in one class.
$objects_in_class() returns a named list of all IdfObject objects
in specified class. The returned list is named using object names.
Idf class also provides custom S3 method of $ and [[ to
make it more convenient to get all IdfObject objects in one class.
Basically, idf$ClassName and idf[["ClassName"]], where
ClassName is a single valid class name, is equivalent to
idf$objects_in_class(ClassName) if ClassName is not an
unique-object class. For convenience, underscore-style names are
allowed, e.g. BuildingSurface_Detailed is equivalent to
BuildingSurface:Detailed when using $. For instance,
idf$BuildingSurface_Detailed and also
idf[["BuildingSurface:Detailed"]] will both return all IdfObject
objects in BuildingSurface:Detailed class. Note that
unlike $objects_in_class(), idf$ClassName and
idf[["ClassName"]] will directly return NULL instead of giving
an error when ClassName is not a valid class name in current Idf
object. This makes it possible to use is.null(idf$ClassName) to
check if ClassName is a valid class or not.
A named list of IdfObject objects.
objects_in_group()Extract all IdfObject objects in one group.
$objects_in_group() returns a named list of all IdfObject objects
in specified group. The returned list is named using object names.
A named list of IdfObject objects.
object_relation()Extract the relationship between object field values.
whichA single integer specifying object ID or a single string specifying object name.
directionThe relation direction to extract. Should be either
"all", "ref_to", "ref_by" and "node".
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
depthIf > 0, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. If NULL,
all possible recursive relations are returned. Default: 0.
keepIf TRUE, all fields of specified object are returned
regardless they have any relations with other objects or not.
If FALSE, only fields in specified object that have
relations with other objects are returned. Default: FALSE.
class_refSpecify how to handle class-name-references. Class
name references refer to references in like field Component 1 Object Type in Branch objects. Their value refers to other
many class names of objects, instaed of referring to specific
field values. There are 3 options in total, i.e. "none",
"both" and "all", with "both" being the default.
* "none": just ignore class-name-references. It is a reasonable
option, as for most cases, class-name-references always come
along with field value references. Ignoring
class-name-references will not impact the most part of the
relation structure.
* "both": only include class-name-references if this object
also reference field values of the same one. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, only the object that is referenced in the
next field Component 1 Name is treated as referenced by
Component 1 Object Type. This is the default option.
* "all": include all class-name-references. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, all objects in Coil:Heating:Water will
be treated as referenced by that field. This is the most
aggressive option.
Many fields in Idd can be referred by others. For example, the
Outside Layer and other fields in Construction class refer to the
Name field in Material class and other material related classes.
Here it means that the Outside Layer field refers to the Name
field and the Name field is referred by the Outside Layer. In
EnergyPlus, there is also a special type of field called Node,
which together with Branch, BranchList and other classes define
the topography of the HVAC connections. A outlet node of a component
can be referred by another component as its inlet node, but can also
exists independently, such as zone air node.
$object_relation() provides a simple interface to get this kind of
relation. It takes a single object ID or name and also a relation
direction, and returns an IdfRelation object which contains data
presenting such relation above. For instance, if
model$object_relation("WALL-1", "ref_to") gives results below:
-- Refer to Others ------------------------
Class: <Construction>
\- Object [ID:2] <WALL-1>
\- 2: "WD01"; !- Outside Layer
v~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\- Class: <Material>
\- Object [ID:1] <WD01>
\- 1: "WD01"; !- NameThis 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.
An IdfRelation object, which is a list of 3
data.table::data.table()s named ref_to, ref_by and node.
Each data.table::data.table() contains 24 columns.
objects_in_relation()Extract multiple IdfObject objects referencing each others.
whichA single integer specifying object ID or a single string specifying object name.
directionThe relation direction to extract. Should be one of
"ref_to", "ref_by" or "node".
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of valid class names in the
underlying Idd. It is used to restrict the classes to be
returned. If NULL, all possible classes are considered and
corresponding IdfObject objects are returned if
relationships are found. Default: NULL.
groupA character vector of valid group names in the
underlying Idd. It is used to restrict the groups to be
returned. If NULL, all possible groups are considered and
corresponding IdfObject objects are returned if
relationships are found. Default: NULL.
depthIf > 0, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. If NULL,
all possible recursive relations are returned. Default: 0.
class_refSpecify how to handle class-name-references. Class
name references refer to references in like field Component 1 Object Type in Branch objects. Their value refers to other
many class names of objects, instaed of refering to specific
field values. There are 3 options in total, i.e. "none",
"both" and "all", with "both" being the default.
* "none": just ignore class-name-references. It is a reasonable
option, as for most cases, class-name-references always come
along with field value references. Ignoring
class-name-references will not impact the most part of the
relation structure.
* "both": only include class-name-references if this object
also reference field values of the same one. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, only the object that is referenced in the
next field Component 1 Name is treated as referenced by
Component 1 Object Type. This is the default option.
* "all": include all class-name-references. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, all objects in Coil:Heating:Water will
be treated as referenced by that field. This is the most
aggressive option.
$objects_in_relation() returns a named list of IdfObject objects
that have specified relationship with given object. The first element of
returned list is always the specified object itself. If that
object does not have specified relationship with other objects in
specified class, a list that only contains specified object itself
is returned.
For instance, assuming that const is a valid object name in
Construction class, idf$objects_in_relation("const", "ref_by", "BuildingSurface:Detailed")
will return a named list of an IdfObject object named const and
also all other IdfObject objects in BuildingSurface:Detailed
class that refer to field values in const. Similarly,
idf$objects_in_relation("const", "ref_to", "Material")
will return a named list of an IdfObject object named const and
also all other IdfObject objects in Material class that const
refers to. This makes it easy to directly extract groups of related
objects and then use $insert() method or other methods
described below to insert them or extract data.
There are lots of recursive references in a model. For instance, a
material can be referred by a construction, that construction can be
referred by a building surface, and that building surface can be
referred by a window on that surface. These objects related
recursively can be extracted by setting recursive to TRUE.
An named list of IdfObject objects.
search_object()Extract multiple IdfObject objects using regular expression on names.
Idf$search_object(
pattern,
class = NULL,
ignore.case = FALSE,
perl = FALSE,
fixed = FALSE,
useBytes = FALSE
)pattern, ignore.case, perl, fixed, useBytesAll are directly passed to base::grepl.
classA character vector of valid class names in the
underlying Idd. It is used to restrict the classes to be
returned. If NULL, all possible classes are considered and
corresponding IdfObject objects are returned if
pattern is met Default: NULL.
$search_object() returns a named list of IdfObject objects whose
names meet the given regular expression in specified classes.
A named list of IdfObject objects.
dup()Duplicate existing objects.
...Integer vectors of object IDs and character vectors of object names. If input is named, its name will be used as the name of newly created objects.
$dup() takes integer vectors of object IDs and character vectors of
object names, duplicates objects specified, and returns a list of
newly created IdfObject objects. The names of input are used as new
names for created IdfObjects. If input is not named, new names are
the names of duplicated objects with a suffix "_1", "_2" and etc,
depending on how many times that object has been duplicated. Note an
error will be issued if trying to assign a new name to an object
which belongs to a class that does not have name attribute.
Assigning newly added objects with an existing name in current Idf
object is prohibited if current validation level includes object name
conflicting checking. For details, please see level_checks().
A named list of IdfObject objects.
\dontrun{
# duplicate an object named "FLOOR"
idf$dup("floor") # New object name 'FLOOR_1' is auto-generated
# duplicate that object again by specifing object ID
idf$dup(16) # New object name 'FLOOR_2' is auto-generated
# duplicate that object two times and giving new names
idf$dup(new_floor = "floor", new_floor2 = 16)
# duplicate that object multiple times using variable inputs
floors_1 <- c(new_floor3 = "floor", new_floor4 = "floor")
floors_2 <- setNames(rep(16, 5), paste0("flr", 1:5))
idf$dup(floors_1, floors_2)
}
add()Add new objects.
...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.
.defaultIf TRUE, default values are used for those blank
fields if possible. If FALSE, empty fields are kept blank.
Default: TRUE.
.allIf TRUE, all fields are added. If FALSE, only minimum
required fields are added. Default: FALSE.
$add() takes new object definitions in list format, adds
corresponding objects in specified classes, returns a list of newly
added IdfObject objects. The returned list will be named using
newly added object names. Every list should be named using a valid
class name. Underscore-style class name is allowed for class name.
Names in each list element are treated as field names. Values without
names will be inserted according to their position. There is a
special element named .comment in each list, which will be used as
the comments of newly added object.
Empty objects can be added using an empty list, e.g.
idf$add(Building = list()). All empty fields will be filled with
corresponding default value if .default is TRUE, leaving other
fields as blanks. However, adding blank objects may not be allowed if
there are required fields in that class and current validate level
includes missing-required-field checking. For what kind of validation
components will be performed during adding new objects, please see
level_checks().
Note that .() can be used as an alias as list(), e.g.
idf$add(Building = .()) is equivalent to
idf$add(Building = list()).
Field name matching is case-insensitive. For convenience,
underscore-style field names are also allowed, e.g. eNd_MoNtH is
equivalent to End Month. This behavior is consistent among all
methods that take field names as input.
There is no need to give all field values if only specific fields are
interested, as long as other fields are not required. For example, to
define a new object in RunPeriod class, the following is enough (at
least for EnergyPlus v8.8):
idf$add(
RunPeriod = list(
"my run period",
begin_month = 1, begin_day_of_month = 1,
end_month = 1, end_day_of_month = 31
),
.default = TRUE
)If not all field names are given, positions of those values without
field names are determined after those values with names. E.g. in
idf$add(Construction = list("out_layer", name = "name")),
"out_layer" will be treated as the value for field Outside Layer
in Construction class, since the value for field Name has been
specified using explicit field name.
A named list of IdfObject objects.
\dontrun{
# add a new Building object with all default values
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .())
# add a new Building object with all default values and comments
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .(.comment = c("this is", "a new building")))
# add a new RunPeriod object with all possible fields
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = list(), RunPeriod = list("rp", 1, 1, 1, 31), .all = TRUE)
# add objects using variable inputs
empty <- empty_idf(8.8) # create an empty Idf
objs1 <- list(Schedule_Constant = list("const"), Building = list())
rp <- list(RunPeriod = list("rp", 2, 1, 2, 28))
empty$add(objs1, rp)
}
set()Set values of existing objects.
...Lists of object definitions. Each list should be named
with a valid object name or ID denoted in style ..ID. There
is a special element .comment in each list, which will be
used as new comments of modified object, overwriting existing
comments if any.
.defaultIf TRUE, default values are used for those blank
fields if possible. If FALSE, empty fields are kept blank.
Default: TRUE.
.emptyIf TRUE, trailing empty fields are kept. Default:
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. The returned list will be named using names of
modified objects. Every list in $set() should be named with a
valid object name. Object ID can also be used but have to be combined
with prevailing two periods .., e.g. ..10 indicates the object
with ID 10. Similar to
$add(), a
special element .comment in each list will be used as the new
comments for modified object, overwriting the old ones. Names in list
element are treated as field names.
Note that .() can be used as an alias as list(), e.g.
idf$set(Building = .(...)) is equivalent to
idf$set(Building = list(...)).
There is two special syntax in $set(), which is inspired by the
data.table package:
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): Similar 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.
You can delete a field by assigning NULL to it, e.g. list(fld = NULL) means to delete the value of field fld, in the condition
that .default is FALSE, fld is not a required field and the
index of fld is larger than the number minimum fields required for
that class. If those conditions are not required, fld will be left
as blank if .default is FALSE or filled with default value if
.default is TRUE.
By default, trailing empty fields that are not required will be
removed and only minimum required fields are kept. For example, if
rp is an object in RunPeriod class in an Idf of version 8.8,
by default empty field with index larger than 11 will be removed
since they are all non-required fields. You can keep the trailing
empty fields by setting .empty to TRUE.
New fields that currently do not exist in that object can also be set. They will be automatically added on the fly.
Field name matching is case-insensitive. For convenience,
underscore-style field names are also allowed, e.g. eNd_MoNtH is
equivalent to End Month.
If not all field names are given, positions of those values without
field names are determined after those values with names. E.g. in
idf$set(floor = list("out_layer", name = "name")), "out_layer"
will be treated as the value for field Outside Layer in an object
named floor, since the value for field Name has been specified
using explicit field name.
A named list of IdfObject objects.
\dontrun{
# modify an object by name (case-insensitive)
idf$set(r13layer = list(roughness = "smooth"))
# modify an object by ID
idf$set(..12 = list(roughness = "rough"))
# overwrite existing object comments
idf$set(r13layer = list(.comment = c("New comment")))
# assign default values to fields
idf$set(r13layer = list(solar_absorptance = NULL), .default = TRUE)
# set field values to blanks
idf$set(r13layer = list(solar_absorptance = NULL), .default = FALSE)
# set field values to blank and delete trailing fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE)
# set field values to blank and keep blank fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE, .empty = TRUE)
# set all fields in one class
idf$set(Material_NoMass := list(visible_absorptance = 0.9))
# set multiple objects in one class
idf$set(.("r13layer", "r31layer") := list(solar_absorptance = 0.8))
# above is equivalent to
idf$set(r13layer = list(solar_absorptance = 0.8),
r31layer = list(solar_absorptance = 0.8)
)
# use variable input
sets <- list(r13layer = list(roughness = "smooth"))
idf$set(sets)
}
del()Delete existing objects
...integer vectors of object IDs and character vectors of
object names in current Idf object.
.ref_byIf TRUE, objects whose fields refer to input objects
will also be deleted. Default: FALSE.
.ref_toIf TRUE, objects whose fields are referred by input
objects will also be deleted. Default: FALSE.
.recursiveIf 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.
.forceIf TRUE, objects are deleted even if they are
referred by other objects.
$del() takes integer vectors of object IDs and character vectors of
object names, and deletes objects specified.
If current validate level includes reference
checking, objects will not be allowed to be deleted if they are
referred by other objects. For example, an error will be issued if
you want to delete one material that is referred by other
constructions, because doing so will result in invalid field value
references. You may bypass this if you really want to by setting
.force to TRUE.
When .ref_by or .ref_to is TRUE, objects will be deleted
only when they have and only have relation with input objects but not
any other objects. For example, a construction const consist of 4
different materials. If .ref_to is TRUE, that 4 materials will
only be deleted when they are only used in const, but not used in
any other objects.
There are recursively reference relations in Idf object. For
example, one material's name is referenced by one construction, and
that construction's name can be referred by another surface. You can
delete all of them by setting .recursive to TRUE.
If .ref_by is TRUE, objects whose fields refer to input objects
will also be deleted.
IF .ref_to is TRUE, objects whose fields
are referred by input objects will also be deleted.
\dontrun{
# delete objects using names
idf$object("Fraction") # ScheduleTypeLimits
idf$del("Fraction")
# delete objects using IDs
idf$objects(c(39, 40)) # Output:Variable
idf$del(39, 40)
# cannot delete objects that are referred by others
level_checks()$reference # reference-checking is enable by default
idf$del("r13layer") # error
# force to delete objects even thay are referred by others
idf$del("r13layer", .force = TRUE)
# delete objects and also objects that refer to them
idf$del("r31layer", .ref_by = TRUE) # Construction 'ROOF31' will be kept
# delete objects and also objects that they refer to
idf$del("extlights", .ref_to = TRUE) # Schedule 'AlwaysOn' will be kept
# delete objects and also other objects that refer to them recursively
idf$del("roof31", .ref_by = TRUE, .recursive = TRUE)
# delete objects using variable inputs
ids <- idf$object_id("Output:Variable", simplify = TRUE)
idf$del(ids)
}
purge()Purge resource objects that are not used
objectan integer vector of object IDs or a character vector
of object names in current Idf object. Default: NULL.
classA character vector of valid class names in current Idf
object. Default: NULL.
groupA character vector of valid group names in current Idf
object. Default: NULL.
$purge() takes an integer vector of object IDs or a character
vectors of object names, and deletes resource objects specified that
are not used by any objects.
Here resource objects indicate all objects that can be referenced by
other objects, e.g. all schedules. $purge() will ignore any inputs
that are not resources. If inputs contain objects from multiple
classes, references among them are also taken into account, which
means purging is performed hierarchically. If both materials and
constructions are specified, the latter will be purged first, because
it is possible that input constructions reference input materials.
duplicated()Determine duplicated objects
objectan integer vector of object IDs or a character vector
of object names in current Idf object. Default: NULL.
classA character vector of valid class names in current Idf
object. Default: NULL.
groupA character vector of valid group names in current Idf
object. Default: NULL.
If all object, class and group are NULL, duplication checking
is performed on the whole Idf.
$duplicated() takes an integer vector of object IDs or a character
vectors of object names, and returns a data.table::data.table()
to show whether input objects contain duplications or not.
Here duplicated objects refer to objects whose field values are the same except the names. Object comments are just ignored during comparison.
A data.table::data.table() of 4 columns:
class: Character. Names of classes that input objects belong to
id: Integer. Input object IDs
name: Character. Input object names
duplicate: Integer. The IDs of objects that input objects
duplicate. If input object is not a duplication, NA is returned
\dontrun{
# check if there are any duplications in the Idf
idf$duplicated(class = "ScheduleTypeLimits")
# check if there are any duplications in the schedule types
idf$duplicated(class = "ScheduleTypeLimits")
# check if there are any duplications in the schedule groups and
# material class
idf$duplicated(class = "Material", group = "Schedules")
}
unique()Remove duplicated objects
objectan integer vector of object IDs or a character vector
of object names in current Idf object. Default: NULL.
classA character vector of valid class names in current Idf
object. Default: NULL.
groupA character vector of valid group names in current Idf
object. Default: NULL.
If all object, class and group are NULL, duplication checking
is performed on the whole Idf.
$unique() takes an integer vector of object IDs or a character
vectors of object names, and remove duplicated objects.
Here duplicated objects refer to objects whose field values are the same except the names. Object comments are just ignored during comparison.
$unique() will only keep the first unique object and remove all
redundant objects. Value referencing the redundant objects will be
redirected into the unique object.
rename()Rename existing objects
...Integer vectors of valid object IDs and character vectors
of valid object names in current Idf object. Each element
should be named. Names of input vectors are used as the new
object names
$rename() takes named character vectors of object names and named
integer vectors of object IDs, renames specified objects to names of
input vectors and returns a list of renamed IdfObjects. The
returned list will be named using names of modified objects. An error
will be issued if trying to "rename" an object which does not have
name attribute. When renaming an object that is referred by other
objects, corresponding fields that refer to that object's name will
also be changed accordingly.
A named list of renamed IdfObject objects.
insert()Insert new objects from IdfObjects
$insert() takes IdfObjects or lists of IdfObjects as input,
inserts them into current Idf objects, and returns a list of
inserted IdfObjects. The returned list will be named using names of
inserted objects.
$insert() is quite useful to insert objects from other Idf
objects. However, you cannot insert an IdfObject which comes from a
different version than current Idf object.
$insert() will skip IdfObjects that have exactly same fields in
current Idf object. If input IdfObject has the same name as one
IdfObject in current Idf object but field values are not equal,
an error will be issued if current validate level
includes conflicted-name checking.
By default, trailing empty fields that are not required will be
removed and only minimum required fields are kept. You can keep the
trailing empty fields by setting .empty to TRUE.
A named list of inserted IdfObject objects.
load()Load new objects from characters or data.frames
...Character vectors or data.frames of object definitions.
.uniqueIf TRUE, and there are duplications in input
IdfObjects or there is same object in current Idf object,
duplications in input are removed. Default: TRUE.
.defaultIf TRUE, default values are filled for those blank
fields if possible. Default: TRUE.
.emptyIf TRUE, trailing empty fields are kept. Default:
FALSE.
$load() is similar to
$insert(),
except it takes directly character vectors or data.frames as
IdfObject definitions, insert corresponding objects into current
Idf object and returns a named list of newly added IdfObjects.
The returned list will be named using names of added objects. This
makes it easy to create objects using the output from$to_string()
and $to_table() method from
Idd,
IddObject,
also from
Idf,
and
IdfObject,
class.
For object definitions in character vector format, they follow the same rules as a normal IDF file:
Each object starts with a class name and a comma (,);
Separates each values with a comma (,);
Ends an object with a semicolon (;) for the last value.
Each character vector can contain:
One single object, e.g. c("Building,", "MyBuilding;"), or
"Building, MyBuilding;".
Multiple objects, e.g. c("Building, MyBuilding;", "SimulationControl, Yes").
You can also provide an option header to indicate if input objects
are presented in IP units, using !-Option ViewInIPunits. If this
header does not exist, then all values are treated as in SI units.
For object definitions in data.frame format, it is highly recommended
to use $to_table() method in
Idd,
Idd,
IddObject,
IddObject,
Idf,
and
IdfObject,
class to create an acceptable data.frame template. A
valid definition requires at least three columns described below.
Note that column order does not matter.
class:Character type. Valid class names in the underlying
Idd object.
index:Integer type. Valid field indices for each class.
value:Character type or list type. Value for each field
to be added.
If character type, usually when string_value is TRUE
in method $to_table() in
Idf
and
IdfObject
class. Note that
each value should be given as a string even if the corresponding
field is a numeric type.
If list type, 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 if current
validation level includes invalid-type checking.
id: Optional. Integer type. If input data.frame includes
multiple object definitions in a same class, values in id column
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 that $load() assumes all definitions are from the same version
as current Idf object. If input definition is from different
version, parsing error may occur.
By default, trailing empty fields that are not required will be
removed and only minimum required fields are kept. You can keep the
trailing empty fields by setting .empty to TRUE.
A named list of loaded IdfObject objects.
\dontrun{
# load objects from character vectors
idf$load(
c("Material,",
" mat, !- Name",
" MediumSmooth, !- Roughness",
" 0.667, !- Thickness {m}",
" 0.115, !- Conductivity {W/m-K}",
" 513, !- Density {kg/m3}",
" 1381; !- Specific Heat {J/kg-K}"),
"Construction, const, mat;"
)
# load objects from data.frame definitions
dt <- idf$to_table(class = "Material")
dt[field == "Name", value := paste(value, 1)]
dt[field == "Thickness", value := "0.5"]
idf$load(dt)
# by default, duplications are removed
idf$load(idf$to_table(class = "Material"))
# keep empty fields as they are
idf$load("Material, mat1, smooth, 0.5, 0.2, 500, 1000,,, 0.5;", .default = FALSE)
# keep trailing empty fields
idf$load("Material, mat2, smooth, 0.5, 0.2, 500, 1000,,,;",
.default = FALSE, .empty = TRUE
)
}
update()Update existing object values from characters or data.frames
...Character vectors or data.frames of object definitions.
.defaultIf TRUE, default values are filled for those blank
fields if possible. Default: TRUE.
.emptyIf TRUE, trailing empty fields are kept. Default:
FALSE.
$update() is similar to
$set(), except
it takes directly character vectors or data.frames as IdfObject
definitions, updates new values for fields in objects specified, and
returns a named list of modified IdfObjects. The returned list will
be named using names of modified objects. This makes it easy to
update object values using the output from $to_string() and
$to_table method from
Idf,
and
IdfObject,
class.
The format of object definitions is similar to $load().
For object definitions in character vector format, object names are used to locate which objects to update. Objects that have name attribute should have valid names. This means that there is no way to update object names using character vector format, but this can be achieved using data.frame format as it uses object IDs instead of object names to locate objects. The format of acceptable characters follows the same rules as a normal IDF file:
Each object starts with a class name and a comma (,);
Separates each values with a comma (,);
Ends an object with a semicolon (;) for the last value.
Each character vector can contain:
One single object, e.g. c("Building,", "MyBuilding;"), or
"Building, MyBuilding;".
Multiple objects, e.g. c("Building, MyBuilding;", "SimulationControl, Yes").
You can also provide an option header to indicate if input objects
are presented in IP units, using !-Option ViewInIPunits. If this
header does not exist, then all values are treated as in SI units.
For object definitions in data.frame format, it is highly recommended
to use $to_table() method in
Idf,
and
IdfObject,
class to create an acceptable data.frame template. A valid definition
requires three columns described below. Note that column order does
not matter.
id: Integer type. Valid IDs of objects to update.
index:Integer type. Valid field indices for each object.
value:Character type or list type. Value for each field
to be added.
If character type, usually when string_value is TRUE
in method $to_table() in
Idf
and
IdfObject
class. Note that
each value should be given as a string even if the corresponding
field is a numeric type.
If list type, 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 if current
validation level includes invalid-type checking.
Note that $update() assumes all definitions are from the same version
as current Idf object. If input definition is from different
version, parsing error may occur.
By default, trailing empty fields that are not required will be
removed and only minimum required fields are kept. You can keep the
trailing empty fields by setting .empty to TRUE.
A named list of updated IdfObject objects.
\dontrun{
# update objects from string definitions:
str <- idf$to_string("zone one", header = FALSE, format = "new_top")
str[8] <- "2," # Multiplier
idf$update(str)
# update objects from data.frame definitions:
dt <- idf$to_table("zone one")
dt[field == "Multiplier", value := "1"]
idf$update(dt)
}
paste()Paste new objects from IDF Editor
in_ipSet 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.
verThe version of IDF file open by IDF Editor, e.g. 8.6,
"8.8.0". If NULL, assume that the file has the same
version as current Idf object. Default: NULL.
uniqueIf TRUE, and there are duplications in copied objects
from IDF Editor or there is same object in current Idf,
duplications in input are removed. Default: TRUE.
emptyIf TRUE, trailing empty fields are kept. Default:
FALSE.
$paste() reads the contents (from clipboard) of copied objects from IDF
Editor (after hitting Copy Obj button), inserts corresponding
objects into current Idf object and returns a named list of newly
added IdfObjects. The returned list will be named using names of
added objects. As IDF Editor is only available on Windows platform,
$paste() only works on Windows too.
There is no version data copied to the clipboard when copying objects in
IDF Editor. $paste() assumes the file open in IDF Editor has the
same version as current Idf object. This may not be always true.
Please check the version before running $paste(), or explicitly
specify the version of file opened by IDF Editor using ver
parameter. Parsing error may occur if there is a version mismatch.
By default, trailing empty fields that are not required will be
removed and only minimum required fields are kept. You can keep the
trailing empty fields by setting .empty to TRUE.
A named list of loaded IdfObject objects.
search_value()Search objects by field values using regular expression
Idf$search_value(
pattern,
class = NULL,
ignore.case = FALSE,
perl = FALSE,
fixed = FALSE,
useBytes = FALSE
)pattern, ignore.case, perl, fixed, useBytesAll of them are directly passed to base::grepl and base::gsub.
classA character vector of invalid class names in current
Idf object to search for values. If NULL, all classes are
used. Default: NULL.
$search_value() returns a list of IdfObjects that contain values
which match the given pattern. If no matched found, NULL is
returned invisibly. The returned list will be named using names of
matched objects.
Note that during matching, all values are treated as characters, including numeric values.
A named list of IdfObject objects.
replace_value()Replace object field values using regular expression
Idf$replace_value(
pattern,
replacement,
class = NULL,
ignore.case = FALSE,
perl = FALSE,
fixed = FALSE,
useBytes = FALSE
)pattern, replacement, ignore.case, perl, fixed, useBytesAll of them are directly passed to base::grepl and base::gsub.
classA character vector of invalid class names in current
Idf object to search for values. If NULL, all classes are
used. Default: NULL.
$replace_value() returns a list of IdfObjects whose values have
been replaced using given pattern. If no matched found, NULL is
returned invisibly. The returned list will be named using names of
matched objects.
Note that during matching, all values are treated as characters, including numeric values.
Modifying object values using regular expression is not recommended.
Consider to use
$set()
and
$update()
if possible.
Validation rules also apply during replacing.
A named list of IdfObject objects.
validate()Check possible object field value errors
Idf$validate(level = eplusr_option("validate_level"))levelOne of "none", "draft", "final" or a list of 10
elements with same format as custom_validate() output.
$validate() checks if there are errors in current Idf object
under specified validation level and returns an IdfValidity object.
$validate() is useful to help avoid some common errors before
running the model. By default, validation is performed when calling
all methods that modify objects, e.g.
$dup()
$add(),
$set(),
$del(),
and etc.
In total, there are 10 different validate checking components:
required_object: Check if required objects are missing in current
Idf.
unique_object: Check if there are multiple objects in one
unique-object class. An unique-object class means that there should
be at most only one object existing in that class.
unique_name: Check if all objects in each class have unique names.
extensible: Check if all fields in an extensible group have
values. An extensible group is a set of fields that should be
treated as a whole, such like the X, Y and Z vertices of a building
surfaces. An extensible group should be added or deleted together.
extensible component checks if there are some, but not all,
fields in an extensible group are empty.
required_field: Check if all required fields have values.
auto_field: Check if all fields filled with value "Autosize" and
"Autocalculate" are actual autosizable and autocalculatable
fields or not.
type: Check if all fields have value types complied with their
definitions, i.e. character, numeric and integer fields should be
filled with corresponding type of values.
choice: Check if all choice fields are filled with valid choice
values.
range: Check if all numeric fields have values within prescibed
ranges.
reference: Check if all fields whose values refer to other fields
are valid.
The level argument controls what checkings should be performed.
level here is just a list of 10 element which specify the toggle
status of each component. You can use helper custom_validate() to
get that list and pass it directly to level.
There are 3 predefined validate level that indicates different
combinations of checking components, i.e. none, draft and
final. Basically, none level just does not perform any
checkings; draft includes 5 components, i.e. auto_field, type,
unique_name, choice and range; and final level includes all
10 components. You can always get what components each level contains
using level_checks(). By default, the result from
eplusr_option("validate_level") is passed to level. If not set,
final level is used.
Underneath, an IdfValidity object which $validate() returns is a
list of 13 element as shown below. Each element or several elements
represents the results from a single validation checking component.
missing_object: Result of required_object checking.
duplicate_object: Result of unique_object checking.
conflict_name: Result of unique_name checking.
incomplete_extensible: Result of extensible checking.
missing_value: Result of required_field checking.
invalid_autosize: Result of auto_field checking for invalid
Autosize field values.
invalid_autocalculate: Result of auto_field checking for
invalid Autocalculate field values.
invalid_character: Result of type checking for invalid
character field values.
invalid_numeric: Result of type checking for invalid
numeric field values.
invalid_integer: Result of type checking for invalid
integer field values.
invalid_choice: Result of choice checking.
invalid_range: Result of range checking.
invalid_reference: Result of reference checking.
Except missing_object, which is a character vector of class names
that are missing, all other elements are
data.table with 9 columns containing data
of invalid field values:
object_id: IDs of objects that contain invalid values
object_name: names of objects that contain invalid values
class_id: indexes of classes that invalid objects belong to
class_name: names of classes that invalid objects belong to
field_id: indexes (at Idd level) of object fields that are invalid
field_index: indexes of object fields in corresponding that are invalid
field_name: names (without units) of object fields that are invalid
units: SI units of object fields that are invalid
ip_units: IP units of object fields that are invalid
type_enum: An integer vector indicates types of invalid fields
value_id: indexes (at Idf level) of object field values that are invalid
value_chr: values (converted to characters) of object fields that are
invalid
value_num: values (converted to numbers in SI units) of object fields
that are invalid
Knowing the internal structure of IdfValidity, it is easy to extract
invalid IdfObjects you interested in. For example, you can get all IDs of
objects that contain invalid value references using
model$validate()$invalid_reference$object_id. Then using
$set()
method to correct them.
Different validate result examples are shown below:
No error is found:
v No error found.Above result shows that there is no error found after conducting all validate checks in specified validate level.
Errors are found:
x [2] Errors found during validation.
=========================================================================
-- [2] Invalid Autocalculate Field --------------------------------------
Fields below cannot be `autocalculate`:
Class: <AirTerminal:SingleDuct:VAV:Reheat>
\- Object [ID:176] <SPACE5-1 VAV Reheat>
+- 17: AUTOCALCULATE, !- Maximum Flow per Zone Floor Area During Reheat {m3/s-m2}
\- 18: AUTOCALCULATE; !- Maximum Flow Fraction During ReheatAbove result shows that after all validate components
performed under current validate level, 2 invalid field values
are found. All of them are in a object named SPACE5-1 VAV Reheat
with ID 176. They are invalid because those two fields do not
have an autocalculatable attribute but are given AUTOCALCULATE
value. Knowing this info, one simple way to fix the
error is to correct those two fields by doing:
idf$set(..176 =
list(`Maximum Flow per Zone Floor Area During Reheat` = "autosize",
`Maximum Flow Fraction During Reheat` = "autosize"
)
)is_valid()Check if there is any error in current Idf
Idf$is_valid(level = eplusr_option("validate_level"))levelOne of "none", "draft", "final" or a list of 10
elements with same format as custom_validate() output.
$is_valid() checks if there are errors in current Idf object
under specified validation level and returns TRUE or FALSE
accordingly. For detailed description on validate checking, see
$validate()
documentation above.
to_string()Format Idf as a character vector
Idf$to_string(
which = NULL,
class = NULL,
comment = TRUE,
header = TRUE,
format = eplusr_option("save_format"),
leading = 4L,
sep_at = 29L
)whichEither 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.
classA character vector of class names. If NULL, all
classed in current Idf object is converted. Default: NULL.
commentIf FALSE, all comments will not be included.
Default: TRUE.
headerIf FALSE, the header will not be included. Default:
TRUE.
formatSpecific format used when formatting. Should be one of
"asis", "sorted", "new_top", and "new_bot".
If "asis", Idf object will be formatted in the same way as it
was when first read. If Idf object does not contain any format
saving option, which is typically the case when the model was not
saved using eplusr or IDFEditor, "sorted" will be used.
"sorted", "new_top" and "new_bot" are the same as the save
options "Sorted", "Original with New at Top", and "Original with New at Bottom" in IDFEditor. Default:
eplusr_option("save_format").
leadingLeading spaces added to each field. Default: 4L.
sep_atThe character width to separate value string and field
string. Default: 29L which is the same as IDF Editor.
\dontrun{
# get text format of the whole Idf
head(idf$to_string())
# get text format of the whole Idf, excluding the header and all comments
head(idf$to_string(comment = FALSE, header = FALSE))
# get text format of all objects in class Material
head(idf$to_string(class = "Material", comment = FALSE, header = FALSE))
# get text format of some objects
head(idf$to_string(c("floor", "zone one")))
# tweak output formatting
head(idf$to_string("floor", leading = 0, sep_at = 0))
}
to_table()Format Idf as a data.frame
Idf$to_table(
which = NULL,
class = NULL,
string_value = TRUE,
unit = FALSE,
wide = FALSE,
align = FALSE,
all = FALSE,
group_ext = c("none", "group", "index"),
force = FALSE,
init = FALSE
)whichEither 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.
classA character vector of class names. If NULL, all
classed in current Idf object is converted. Default: NULL.
string_valueIf 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.
unitOnly applicable when string_value is FALSE. If
TRUE, values of numeric fields are assigned with units using
units::set_units() if applicable. Default: FALSE.
wideOnly applicable if target objects belong to a same class.
If TRUE, a wide table will be returned, i.e. first three
columns are always id, name and class, and then every
field in a separate column. Note that this requires all
objects specified must from the same class.
Default: FALSE.
alignIf 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.
allIf TRUE, all available fields defined in IDD for the
class that objects belong to will be returned. Default:
FALSE.
group_extShould be one of "none", "group" or "index".
If not "none", value column in returned
data.table::data.table() will be converted into a list.
If "group", values from extensible fields will be grouped by the
extensible group they belong to. For example, coordinate
values of each vertex in class BuildingSurface:Detailed will
be put into a list. If "index", values from extensible fields
will be grouped by the extensible field indice they belong to.
For example, coordinate values of all x coordinates will be
put into a list. If "none", nothing special will be done.
Default: "none".
forceIf TRUE, wide can be TRUE even though there are
multiple classes in input. This can result in a data.table
with lots of columns. But may be useful when you know that
target classes have the exact same fields, e.g.
Ceiling:Adiabatic and Floor:Adiabatic. Default: FALSE.
initIf TRUE, a table for new object input will be returned
with all values filled with defaults. In this case, object
input will be ignored. The id column will be filled with
possible new object IDs. Default: FALSE.
$to_table() returns a data.table that
contains core data of specified objects.
The returned data.table has 5 columns:
id: Integer type. Object IDs.
name: Character type. Object names.
class: Character type. Current class name.
index: Integer type. Field indexes.
field: Character type. Field names.
value: Character type if string_value is TRUE or list type if
string_value is FALSE or group_ext is not "none". Field values.
Note that when group_ext is not "none", index and field
values will not match the original field indices and names. In this
case, index will only indicate the indices of sequences. For
field column, specifically:
When group_ext is "group", each field name in a extensible group
will be abbreviated using abbreviate() with minlength being
10L and all abbreviated names will be separated by | and
combined together. For example, field names in the extensible group
(Vertex 1 X-coordinate, Vertex 1 Y-coordinate, Vertex 1 Z-coordinate) in class BuildiBuildingSurface:Detailed will be
merged into one name Vrtx1X-crd|Vrtx1Y-crd|Vrtx1Z-crd.
When group_ext is "index", the extensible group indicator in field
names will be removed. Take the same example as above, the
resulting field names will be Vertex X-coordinate, Vertex Y-coordinate, and Vertex Z-coordinate.
A data.table with 6 columns (if
wide is FALSE) or at least 6 columns (if wide is TRUE).
\dontrun{
# extract whole Idf data
idf$to_table()
# extract all data from class Material
idf$to_table(class = "Material")
# extract multiple object data
idf$to_table(c("FLOOR", "ZONE ONE"))
# keep value types and put actual values into a list column
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE)$value
# add the unit to each value
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE, unit = TRUE)
# get all possible fields
idf$to_table("ZONE ONE", all = TRUE)
# make sure all objects in same class have the same number of fields
idf$to_table(class = "Construction", align = TRUE)
# get a wide table with string values
idf$to_table(class = "Construction", wide = TRUE)
# get a wide table with actual values
idf$to_table(class = "OtherEquipment", wide = TRUE, string_value = FALSE)
# group extensible by extensible group number
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group")
# group extensible by extensible group number and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group", wide = TRUE)
# group extensible by extensible field index
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index")
# group extensible by extensible field index and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index", wide = TRUE)
# when grouping extensible, 'string_value' and 'unit' still take effect
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index",
wide = TRUE, string_value = FALSE, unit = TRUE
)
# create table for new object input
idf$to_table(class = "BuildingSurface:Detailed", init = TRUE)
}
external_deps()Get external file dependencies that the Idf needs for simulation.
fullIf TRUE, a data.table is
returned giving details about the objects and fields that use those
external file dependencies. Default: FALSE.
$external_deps() returns information of files that are used as
external resources for the simulation.
Currently, classes below are checked:
Schedule:File:Shading
Schedule:File
Construction:WindowDataFile
ExternalInterface:FunctionalMockupUnitImport
ExternalInterface:FunctionalMockupUnitImport:From:Variable
ExternalInterface:FunctionalMockupUnitImport:To:Schedule
ExternalInterface:FunctionalMockupUnitImport:To:Actuator
ExternalInterface:FunctionalMockupUnitImport:To:Variable
Table:IndependentVariable
Table:Lookup
Note that, for ExternalInterface:FunctionalMockupUnitImport and
ExternalInterface:FunctionalMockupUnitImport:*, resources of FMU
will also be extracted.
When full is FALSE, which is the default, a character vector.
When full is TRUE, a data.table of 8
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. Field values.
path: Character type. Full file paths.
exist: Logical type. TRUE if file exists, FALSE otherwise.
If there are any FMUs using external file resources, the returned
data.table will have an attribute named extra which is a list
giving the FMU name and external file resources it use.
is_unsaved()Check if there are unsaved changes in current Idf
save()Save Idf object as an IDF file
Idf$save(
path = NULL,
format = eplusr_option("save_format"),
overwrite = FALSE,
copy_external = TRUE
)pathA path where to save the IDF file. If NULL, the path of
the Idf itself, i.e.
$path(),
will be used.
formatSpecific format used when formatting. Should be one of
"asis", "sorted", "new_top", and "new_bot".
If "asis", Idf object will be formatted in the same way as it
was when first read. If Idf object does not contain any format
saving option, which is typically the case when the model was not
saved using eplusr or IDFEditor, "sorted" will be used.
"sorted", "new_top" and "new_bot" are the same as the save
options "Sorted", "Original with New at Top", and "Original with New at Bottom" in IDFEditor. Default:
eplusr_option("save_format").
overwriteWhether to overwrite the file if it already exists.
Default: FALSE.
copy_externalIf TRUE, the external files extracted from
$external_deps() will also be copied into the same directory.
The values of file paths in the Idf will be changed into
relative path automatically. This makes it possible to create
fully reproducible simulation conditions. If FALSE, the
values of those fields that reference external file paths will
be updated to absolute paths. Default: FALSE.
$save() formats current Idf object, saves it as an IDF file and
returns the path of saved file invisibly. After saving,
$path()
will also be updated to return the path of saved file.
\dontrun{
# save Idf as a new file
idf$save(tempfile(fileext = ".idf"))
# save and overwrite current file
idf$save(overwrite = TRUE)
# save the model with newly created and modified objects at the top
idf$save(overwrite = TRUE, format = "new_top")
# save the model to a new file and copy all external csv files used in
# "Schedule:File" class into the same folder
idf$save(path = file.path(tempdir(), "test1.idf"), copy_external = TRUE)
}
run()Run simulation using EnergyPlus
Idf$run(
weather,
dir = NULL,
wait = TRUE,
force = FALSE,
copy_external = FALSE,
echo = wait
)weatherA path to an .epw file or an Epw object. weather
can also be NULL which will force design-day-only
simulation. Note that this needs at least one
Sizing:DesignDay object exists in the Idf.
dirThe directory to save the simulation results. If NULL,
the folder of Idf path will be used. Default: NULL.
waitWhether to wait until the simulation completes and print
the standard output and error of EnergyPlus. If FALSE, the
simulation will run in the background. Default is TRUE.
forceOnly 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_externalIf TRUE, the external files that current Idf
object depends on will also be copied into the simulation
output directory. The values of file paths in the Idf will be
changed automatically. This ensures that the output directory
will have all files needed for the model to run. Default is
FALSE.
echoOnly applicable when wait is TRUE. Whether to show
standard output and error from EnergyPlus. Default: same as
wait.
$run() calls corresponding version of EnergyPlus to run the current
Idf object together with specified weather. The model and the
weather used will be copied into the output directory. An EplusJob
object is returned which provides detailed info of the simulation and
methods to collect simulation results. Please see EplusJob for
details.
eplusr uses the EnergyPlus command line interface which was
introduced since EnergyPlus 8.3.0. So $run() only supports models
with version no lower than 8.3.0.
When calling $run(), eplusr will do steps below to make sure the
output collecting methods work as expected. Please note that this may
result in an IDF file that may not be exactly same as your current
Idf object.
eplusr uses 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.
An EplusJob object of current simulation.
\dontrun{
idf <- Idf$new(path_idf)
# save the model to tempdir()
idf$save(file.path(tempdir(), "test_run.idf"))
# use the first epw file in "WeatherData" folder in EnergyPlus v8.8
# installation path
epw <- list.files(file.path(eplus_config(8.8)$dir, "WeatherData"),
pattern = "\\.epw$", full.names = TRUE)[1]
# if `dir` is NULL, the directory of IDF file will be used as simulation
# output directory
job <- idf$run(epw, dir = NULL)
# run simulation in the background
idf$run(epw, dir = tempdir(), wait = FALSE)
# copy all external files into the directory run simulation
idf$run(epw, dir = tempdir(), copy_external = TRUE)
# check for simulation errors
job$errors()
# get simulation status
job$status()
# get output directory
job$output_dir()
# re-run the simulation
job$run()
# get simulation results
job$report_data()
}
last_job()Get the last simulation job
$last_job() returns the last EplusJob object that was created
using
$run(). If the
Idf hasn't been run yet, NULL is returned.
NULL or an EplusJob object.
geometry()Extract Idf geometries
$geometry() extracts all geometry objects into an IdfGeometry
object. IdfGeometry is an abstraction of a collection of geometry
in an Idf. It provides more detail methods to query geometry
properties, update geometry vertices and visualize geometry in 3D
using the rgl package.
An IdfGeometry object.
view()View 3D Idf geometry
Idf$view(
new = FALSE,
render_by = "surface_type",
wireframe = TRUE,
x_ray = FALSE,
axis = TRUE
)newIf TRUE, a new rgl window will be open using
rgl::open3d(). If FALSE, existing rgl window will be
reused if possible. Default: FALSE.
render_byA single string specifying the way of rendering the geometry. Possible values are:
"surface_type": Default. Render the model by surface type
model. Walls, roofs, windows, doors, floors, and shading
surfaces will have unique colors.
"boundary": Render the model by outside boundary condition.
Only surfaces that have boundary conditions will be rendered
with a color. All other surfaces will be white.
"construction": Render the model by surface constructions.
"zone": Render the model by zones assigned.
"normal": Render the model by surface normal. The outside
face of a heat transfer face will be rendered as white and the
inside face will be rendered as red.
wireframeIf TRUE, the wireframe of each surface will be
shown. Default: TRUE.
x_rayIf TRUE, all surfaces will be rendered translucently.
Default: FALSE.
axisIf TRUE, the X, Y and Z axes will be drawn at the
global origin. Default: TRUE.
$view() uses the rgl
package to visualize the IDF geometry in 3D in a similar way as
OpenStudio.
$view() returns an IdfViewer object which can be used to further
tweak the viewer scene.
In the rgl window, you can control the view using your mouse:
Left button: Trackball
Right button: Pan
Middle button: Field-of-view (FOV). '0' means orthographic projection.
Wheel: Zoom
An IdfViewer object
print()Print Idf object
zoomControl how detailed of the Idf object should be printed.
Should be one of "group", "class", "object" and
"field". Default: "group".
"group": all group names current existing are shown with prevailing
square bracket showing how many Classes existing in that group.
"class": all class names are shown with prevailing square bracket
showing how many Objects existing in that class, together with
parent group name of each class.
"object": all object IDs and names are shown, together with parent
class name of each object.
"field": all object IDs and names, field names and values are shown,
together with parent class name of each object.
orderOnly 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.
$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.
## ------------------------------------------------
## Method `Idf$new`
## ------------------------------------------------
if (FALSE) {
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8
# If neither EnergyPlus v8.8 nor Idd v8.8 was found, error will
# occur. If Idd v8.8 is found, it will be used automatically.
idf <- Idf$new(path_idf)
# argument `idd` can be specified explicitly using `use_idd()`
idf <- Idf$new(path_idf, idd = use_idd(8.8))
# you can set `download` arugment to "auto" in `use_idd()` if you
# want to automatically download corresponding IDD file when
# necessary
idf <- Idf$new(path_idf, use_idd(8.8, download = "auto"))
# Besides use a path to an IDF file, you can also provide IDF in literal
# string format
string_idf <-
"
Version, 8.8;
Building,
Building; !- Name
"
Idf$new(string_idf, use_idd(8.8, download = "auto"))
}
## ------------------------------------------------
## Method `Idf$version`
## ------------------------------------------------
if (FALSE) {
# get version
idf$version()
}
## ------------------------------------------------
## Method `Idf$path`
## ------------------------------------------------
if (FALSE) {
# get path
idf$path()
# return `NULL` if Idf is not created from a file
Idf$new("Version, 8.8;\n")$path()
}
## ------------------------------------------------
## Method `Idf$group_name`
## ------------------------------------------------
if (FALSE) {
# get names of all groups Idf contains
idf$group_name()
# get group name of each object in Idf
idf$group_name(sorted = FALSE)
# get names of all available groups in underlying Idd
idf$group_name(all = TRUE)
}
## ------------------------------------------------
## Method `Idf$class_name`
## ------------------------------------------------
if (FALSE) {
# get names of all classes in Idf
idf$class_name()
# get names of all classes grouped by group names in Idf
idf$class_name(by_group = TRUE)
# get class name of each object in Idf
idf$class_name(sorted = FALSE)
# get names of all available classes in underlying Idd
idf$class_name(all = TRUE)
# get names of all available classes grouped by group names in
# underlying Idd
idf$class_name(all = TRUE, by_group = TRUE)
}
## ------------------------------------------------
## Method `Idf$is_valid_group`
## ------------------------------------------------
if (FALSE) {
# check if input is a valid group name in current Idf
idf$is_valid_group(c("Schedules", "Compliance Objects"))
# check if input is a valid group name in underlying Idd
idf$is_valid_group(c("Schedules", "Compliance Objects"), all = TRUE)
}
## ------------------------------------------------
## Method `Idf$is_valid_class`
## ------------------------------------------------
if (FALSE) {
# check if input is a valid class name in current Idf
idf$is_valid_class(c("Building", "ShadowCalculation"))
# check if input is a valid class name in underlying Idd
idf$is_valid_class(c("Building", "ShadowCalculation"), all = TRUE)
}
## ------------------------------------------------
## Method `Idf$definition`
## ------------------------------------------------
if (FALSE) {
# get the IddObject object for specified class
idf$definition("Version")
}
## ------------------------------------------------
## Method `Idf$object_id`
## ------------------------------------------------
if (FALSE) {
# get IDs of all objects in current Idf object
idf$object_id()
# get IDs of all objects in current Idf object, and merge them into a
# single integer vector
idf$object_id(simplify = TRUE)
# get IDs of objects in class Version and Zone
idf$object_id(c("Version", "Zone"))
# get IDs of objects in class Version and Zone, and merge them into a
# single integer vector
idf$object_id(c("Version", "Zone"), simplify = TRUE)
}
## ------------------------------------------------
## Method `Idf$object_name`
## ------------------------------------------------
if (FALSE) {
# get names of all objects in current Idf object
idf$object_name()
# get names of all objects in current Idf object, and merge them into
# a single character vector
idf$object_name(simplify = TRUE)
# get names of objects in class Version and Zone
idf$object_name(c("Version", "Zone"))
# get names of objects in class Version and Zone, and merge them into
# a single character vector
idf$object_name(c("Version", "Zone"), simplify = TRUE)
}
## ------------------------------------------------
## Method `Idf$object_num`
## ------------------------------------------------
if (FALSE) {
# get total number of objects
idf$object_num()
# get number of objects in class Zone and Schedule:Compact
idf$object_num(c("Zone", "Schedule:Compact"))
}
## ------------------------------------------------
## Method `Idf$is_valid_id`
## ------------------------------------------------
if (FALSE) {
idf$is_valid_id(c(51, 1000))
}
## ------------------------------------------------
## Method `Idf$is_valid_name`
## ------------------------------------------------
if (FALSE) {
idf$is_valid_name(c("Simple One Zone (Wireframe DXF)", "ZONE ONE", "a"))
# name matching is case-insensitive
idf$is_valid_name(c("simple one zone (wireframe dxf)", "zone one", "a"))
}
## ------------------------------------------------
## Method `Idf$object`
## ------------------------------------------------
if (FALSE) {
# get an object whose ID is 3
idf$object(3)
# get an object whose name is "simple one zone (wireframe dxf)"
# NOTE: object name matching is case-insensitive
idf$object("simple one zone (wireframe dxf)")
}
## ------------------------------------------------
## Method `Idf$objects`
## ------------------------------------------------
if (FALSE) {
# get objects whose IDs are 3 and 10
idf$objects(c(3,10))
# get objects whose names are "Simple One Zone (Wireframe DXF)" and "ZONE ONE"
# NOTE: object name matching is case-insensitive
idf$objects(c("Simple One Zone (Wireframe DXF)", "zone one"))
}
## ------------------------------------------------
## Method `Idf$object_unique`
## ------------------------------------------------
if (FALSE) {
# get the SimulationColtrol object
idf$object_unique("SimulationControl")
# S3 "[[" and "$" can also be used
idf$SimulationControl
idf[["SimulationControl"]]
}
## ------------------------------------------------
## Method `Idf$objects_in_class`
## ------------------------------------------------
if (FALSE) {
# get all objects in Zone class
idf$objects_in_class("Zone")
# S3 "[[" and "$" can also be used
idf$Zone
idf[["Zone"]]
}
## ------------------------------------------------
## Method `Idf$objects_in_group`
## ------------------------------------------------
if (FALSE) {
# get all objects in Schedules group
idf$objects_in_group("Schedules")
}
## ------------------------------------------------
## Method `Idf$object_relation`
## ------------------------------------------------
if (FALSE) {
# check each layer's reference of a construction named FLOOR
idf$object_relation("floor", "ref_to")
# check where is this construction being used
idf$object_relation("floor", "ref_by")
}
## ------------------------------------------------
## Method `Idf$objects_in_relation`
## ------------------------------------------------
if (FALSE) {
# get a construction named FLOOR and all materials it uses
idf$objects_in_relation("floor", "ref_to")
# get a construction named FLOOR and all surfaces that uses it
idf$objects_in_relation("floor", "ref_by", class = "BuildingSurface:Detailed")
}
## ------------------------------------------------
## Method `Idf$search_object`
## ------------------------------------------------
if (FALSE) {
# get all objects whose names contains "floor"
idf$search_object("floor", ignore.case = TRUE)
}
## ------------------------------------------------
## Method `Idf$dup`
## ------------------------------------------------
if (FALSE) {
# duplicate an object named "FLOOR"
idf$dup("floor") # New object name 'FLOOR_1' is auto-generated
# duplicate that object again by specifing object ID
idf$dup(16) # New object name 'FLOOR_2' is auto-generated
# duplicate that object two times and giving new names
idf$dup(new_floor = "floor", new_floor2 = 16)
# duplicate that object multiple times using variable inputs
floors_1 <- c(new_floor3 = "floor", new_floor4 = "floor")
floors_2 <- setNames(rep(16, 5), paste0("flr", 1:5))
idf$dup(floors_1, floors_2)
}
## ------------------------------------------------
## Method `Idf$add`
## ------------------------------------------------
if (FALSE) {
# add a new Building object with all default values
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .())
# add a new Building object with all default values and comments
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = .(.comment = c("this is", "a new building")))
# add a new RunPeriod object with all possible fields
empty <- empty_idf(8.8) # create an empty Idf
empty$add(Building = list(), RunPeriod = list("rp", 1, 1, 1, 31), .all = TRUE)
# add objects using variable inputs
empty <- empty_idf(8.8) # create an empty Idf
objs1 <- list(Schedule_Constant = list("const"), Building = list())
rp <- list(RunPeriod = list("rp", 2, 1, 2, 28))
empty$add(objs1, rp)
}
## ------------------------------------------------
## Method `Idf$set`
## ------------------------------------------------
if (FALSE) {
# modify an object by name (case-insensitive)
idf$set(r13layer = list(roughness = "smooth"))
# modify an object by ID
idf$set(..12 = list(roughness = "rough"))
# overwrite existing object comments
idf$set(r13layer = list(.comment = c("New comment")))
# assign default values to fields
idf$set(r13layer = list(solar_absorptance = NULL), .default = TRUE)
# set field values to blanks
idf$set(r13layer = list(solar_absorptance = NULL), .default = FALSE)
# set field values to blank and delete trailing fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE)
# set field values to blank and keep blank fields
idf$set(r13layer = list(visible_absorptance = NULL), .default = FALSE, .empty = TRUE)
# set all fields in one class
idf$set(Material_NoMass := list(visible_absorptance = 0.9))
# set multiple objects in one class
idf$set(.("r13layer", "r31layer") := list(solar_absorptance = 0.8))
# above is equivalent to
idf$set(r13layer = list(solar_absorptance = 0.8),
r31layer = list(solar_absorptance = 0.8)
)
# use variable input
sets <- list(r13layer = list(roughness = "smooth"))
idf$set(sets)
}
## ------------------------------------------------
## Method `Idf$del`
## ------------------------------------------------
if (FALSE) {
# delete objects using names
idf$object("Fraction") # ScheduleTypeLimits
idf$del("Fraction")
# delete objects using IDs
idf$objects(c(39, 40)) # Output:Variable
idf$del(39, 40)
# cannot delete objects that are referred by others
level_checks()$reference # reference-checking is enable by default
idf$del("r13layer") # error
# force to delete objects even thay are referred by others
idf$del("r13layer", .force = TRUE)
# delete objects and also objects that refer to them
idf$del("r31layer", .ref_by = TRUE) # Construction 'ROOF31' will be kept
# delete objects and also objects that they refer to
idf$del("extlights", .ref_to = TRUE) # Schedule 'AlwaysOn' will be kept
# delete objects and also other objects that refer to them recursively
idf$del("roof31", .ref_by = TRUE, .recursive = TRUE)
# delete objects using variable inputs
ids <- idf$object_id("Output:Variable", simplify = TRUE)
idf$del(ids)
}
## ------------------------------------------------
## Method `Idf$purge`
## ------------------------------------------------
if (FALSE) {
# purge unused "Fraction" schedule type
idf$purge("on/off") # ScheduleTypeLimits
# purge all unused schedule types
idf$purge(class = "ScheduleTypeLimits")
# purge all unused schedule related objects
idf$purge(group = "Schedules")
}
## ------------------------------------------------
## Method `Idf$duplicated`
## ------------------------------------------------
if (FALSE) {
# check if there are any duplications in the Idf
idf$duplicated(class = "ScheduleTypeLimits")
# check if there are any duplications in the schedule types
idf$duplicated(class = "ScheduleTypeLimits")
# check if there are any duplications in the schedule groups and
# material class
idf$duplicated(class = "Material", group = "Schedules")
}
## ------------------------------------------------
## Method `Idf$unique`
## ------------------------------------------------
if (FALSE) {
# remove duplications in the Idf
idf$unique(class = "ScheduleTypeLimits")
# remove duplications in the schedule types
idf$unique(class = "ScheduleTypeLimits")
# remove duplications in the schedule groups and material class
idf$unique(class = "Material", group = "Schedules")
}
## ------------------------------------------------
## Method `Idf$rename`
## ------------------------------------------------
if (FALSE) {
idf$objects(c("on/off", "test 352a"))
idf$rename(on_off = "on/off", test_352a = 51)
}
## ------------------------------------------------
## Method `Idf$insert`
## ------------------------------------------------
if (FALSE) {
# insert all material from another IDF
path_idf2 <- file.path(eplus_config(8.8)$dir, "ExampleFiles/5ZoneTDV.idf")
idf2 <- Idf$new(path_idf2)
idf$insert(idf2$Material)
# insert objects from same Idf is equivalent to using Idf$dup()
idf$insert(idf$SizingPeriod_DesignDay)
}
## ------------------------------------------------
## Method `Idf$load`
## ------------------------------------------------
if (FALSE) {
# load objects from character vectors
idf$load(
c("Material,",
" mat, !- Name",
" MediumSmooth, !- Roughness",
" 0.667, !- Thickness {m}",
" 0.115, !- Conductivity {W/m-K}",
" 513, !- Density {kg/m3}",
" 1381; !- Specific Heat {J/kg-K}"),
"Construction, const, mat;"
)
# load objects from data.frame definitions
dt <- idf$to_table(class = "Material")
dt[field == "Name", value := paste(value, 1)]
dt[field == "Thickness", value := "0.5"]
idf$load(dt)
# by default, duplications are removed
idf$load(idf$to_table(class = "Material"))
# keep empty fields as they are
idf$load("Material, mat1, smooth, 0.5, 0.2, 500, 1000,,, 0.5;", .default = FALSE)
# keep trailing empty fields
idf$load("Material, mat2, smooth, 0.5, 0.2, 500, 1000,,,;",
.default = FALSE, .empty = TRUE
)
}
## ------------------------------------------------
## Method `Idf$update`
## ------------------------------------------------
if (FALSE) {
# update objects from string definitions:
str <- idf$to_string("zone one", header = FALSE, format = "new_top")
str[8] <- "2," # Multiplier
idf$update(str)
# update objects from data.frame definitions:
dt <- idf$to_table("zone one")
dt[field == "Multiplier", value := "1"]
idf$update(dt)
}
## ------------------------------------------------
## Method `Idf$search_value`
## ------------------------------------------------
if (FALSE) {
# search values that contains "floor"
idf$search_value("floor", ignore.case = TRUE)
# search values that contains "floor" in class Construction
idf$search_value("floor", "Construction", ignore.case = TRUE)
}
## ------------------------------------------------
## Method `Idf$replace_value`
## ------------------------------------------------
if (FALSE) {
# search values that contains "win" and replace them with "windows"
idf$replace_value("win", "windows")
}
## ------------------------------------------------
## Method `Idf$validate`
## ------------------------------------------------
if (FALSE) {
idf$validate()
# check at predefined validate level
idf$validate("none")
idf$validate("draft")
idf$validate("final")
# custom validate checking components
idf$validate(custom_validate(auto_field = TRUE, choice = TRUE))
}
## ------------------------------------------------
## Method `Idf$is_valid`
## ------------------------------------------------
if (FALSE) {
idf$is_valid()
# check at predefined validate level
idf$is_valid("none")
idf$is_valid("draft")
idf$is_valid("final")
# custom validate checking components
idf$is_valid(custom_validate(auto_field = TRUE, choice = TRUE))
}
## ------------------------------------------------
## Method `Idf$to_string`
## ------------------------------------------------
if (FALSE) {
# get text format of the whole Idf
head(idf$to_string())
# get text format of the whole Idf, excluding the header and all comments
head(idf$to_string(comment = FALSE, header = FALSE))
# get text format of all objects in class Material
head(idf$to_string(class = "Material", comment = FALSE, header = FALSE))
# get text format of some objects
head(idf$to_string(c("floor", "zone one")))
# tweak output formatting
head(idf$to_string("floor", leading = 0, sep_at = 0))
}
## ------------------------------------------------
## Method `Idf$to_table`
## ------------------------------------------------
if (FALSE) {
# extract whole Idf data
idf$to_table()
# extract all data from class Material
idf$to_table(class = "Material")
# extract multiple object data
idf$to_table(c("FLOOR", "ZONE ONE"))
# keep value types and put actual values into a list column
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE)$value
# add the unit to each value
idf$to_table(c("FLOOR", "ZONE ONE"), string_value = FALSE, unit = TRUE)
# get all possible fields
idf$to_table("ZONE ONE", all = TRUE)
# make sure all objects in same class have the same number of fields
idf$to_table(class = "Construction", align = TRUE)
# get a wide table with string values
idf$to_table(class = "Construction", wide = TRUE)
# get a wide table with actual values
idf$to_table(class = "OtherEquipment", wide = TRUE, string_value = FALSE)
# group extensible by extensible group number
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group")
# group extensible by extensible group number and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "group", wide = TRUE)
# group extensible by extensible field index
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index")
# group extensible by extensible field index and convert into a wide table
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index", wide = TRUE)
# when grouping extensible, 'string_value' and 'unit' still take effect
idf$to_table(class = "BuildingSurface:Detailed", group_ext = "index",
wide = TRUE, string_value = FALSE, unit = TRUE
)
# create table for new object input
idf$to_table(class = "BuildingSurface:Detailed", init = TRUE)
}
## ------------------------------------------------
## Method `Idf$external_deps`
## ------------------------------------------------
if (FALSE) {
idf$external_deps()
}
## ------------------------------------------------
## Method `Idf$is_unsaved`
## ------------------------------------------------
if (FALSE) {
idf$is_unsaved()
}
## ------------------------------------------------
## Method `Idf$save`
## ------------------------------------------------
if (FALSE) {
# save Idf as a new file
idf$save(tempfile(fileext = ".idf"))
# save and overwrite current file
idf$save(overwrite = TRUE)
# save the model with newly created and modified objects at the top
idf$save(overwrite = TRUE, format = "new_top")
# save the model to a new file and copy all external csv files used in
# "Schedule:File" class into the same folder
idf$save(path = file.path(tempdir(), "test1.idf"), copy_external = TRUE)
}
## ------------------------------------------------
## Method `Idf$run`
## ------------------------------------------------
if (FALSE) {
idf <- Idf$new(path_idf)
# save the model to tempdir()
idf$save(file.path(tempdir(), "test_run.idf"))
# use the first epw file in "WeatherData" folder in EnergyPlus v8.8
# installation path
epw <- list.files(file.path(eplus_config(8.8)$dir, "WeatherData"),
pattern = "\\.epw$", full.names = TRUE)[1]
# if `dir` is NULL, the directory of IDF file will be used as simulation
# output directory
job <- idf$run(epw, dir = NULL)
# run simulation in the background
idf$run(epw, dir = tempdir(), wait = FALSE)
# copy all external files into the directory run simulation
idf$run(epw, dir = tempdir(), copy_external = TRUE)
# check for simulation errors
job$errors()
# get simulation status
job$status()
# get output directory
job$output_dir()
# re-run the simulation
job$run()
# get simulation results
job$report_data()
}
## ------------------------------------------------
## Method `Idf$last_job`
## ------------------------------------------------
if (FALSE) {
idf$last_job()
}
## ------------------------------------------------
## Method `Idf$geometry`
## ------------------------------------------------
if (FALSE) {
idf$geometry()
}
## ------------------------------------------------
## Method `Idf$view`
## ------------------------------------------------
if (FALSE) {
idf$view()
idf$view(render_by = "zone")
idf$view(render_by = "construction")
}
## ------------------------------------------------
## Method `Idf$print`
## ------------------------------------------------
if (FALSE) {
idf$print("group")
idf$print("class")
idf$print("object")
idf$print("field")
# order objects by there classes
idf$print("object", order = FALSE)
idf$print("field", order = FALSE)
}