ParametricJob: Create and Run Parametric Analysis, and Collect Results
In eplusr: A Toolkit for Using Whole Building Simulation Program 'EnergyPlus'
ParametricJob R Documentation
Create and Run Parametric Analysis, and Collect Results
Description
ParametricJob class provides a prototype of conducting parametric analysis
of EnergyPlus simulations.
param_job() takes an IDF and EPW as input and returns a ParametricJob.
For details on ParametricJob, please see ParametricJob class.
Usage
param_job(idf, epw)
Arguments
idf
A path to EnergyPlus IDF or IMF file or an Idf object.
epw
A path to EnergyPlus EPW file or an Epw object. epw can also
be NULL which will force design-day-only simulation when
$run() method is called. Note this needs at least
one Sizing:DesignDay object exists in the Idf.
Details
Basically, it is a collection of multiple EplusJob objects. However, the
model is first parsed and the Idf object is stored internally, instead of
storing only the path of Idf like in EplusJob class. Also, an object in
Output:SQLite with Option Type value of SimpleAndTabular will be
automatically created if it does not exists, like Idf class does.
Value
A ParametricJob object.
Super class
eplusr::EplusGroupJob -> ParametricJob
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
Inherited methods
eplusr::EplusGroupJob$errors()eplusr::EplusGroupJob$kill()eplusr::EplusGroupJob$list_files()eplusr::EplusGroupJob$list_table()eplusr::EplusGroupJob$locate_output()eplusr::EplusGroupJob$output_dir()eplusr::EplusGroupJob$read_mdd()eplusr::EplusGroupJob$read_rdd()eplusr::EplusGroupJob$read_table()eplusr::EplusGroupJob$report_data()eplusr::EplusGroupJob$report_data_dict()eplusr::EplusGroupJob$status()eplusr::EplusGroupJob$tabular_data()
Method new()
Create a ParametricJob object
Usage
ParametricJob$new(idf, epw)
Arguments
idfPath to EnergyPlus IDF file or an Idf object.
epwPath to EnergyPlus EPW file or an Epw object. epw can
also be NULL which will force design-day-only simulation
when $run() method is called. Note this needs at least one
Sizing:DesignDay object exists in the Idf.
Returns
A ParametricJob object.
Examples
\dontrun{
if (is_avail_eplus("8.8")) {
path_idf <- path_eplus_example("8.8", "5Zone_Transformer.idf")
path_epw <- path_eplus_weather("8.8", "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw")
# create from an IDF and an EPW
param <- param_job(path_idf, path_epw)
param <- ParametricJob$new(path_idf, path_epw)
# create from an Idf and an Epw object
param_job(read_idf(path_idf), read_epw(path_epw))
}
}
Method version()
Get the version of seed IDF
Usage
ParametricJob$version()
Details
$version() returns the version of input seed Idf object.
Returns
A base::numeric_version() object.
Examples
\dontrun{
param$version()
}
Method seed()
Get the seed Idf object
Usage
ParametricJob$seed()
Details
$seed() returns the parsed input seed Idf object.
Examples
\dontrun{
param$seed()
}
Method weather()
Get the Epw object
Usage
ParametricJob$weather()
Details
$weather() returns the input Epw object. If no Epw is provided
when creating the ParametricJob object, NULL is returned.
Examples
\dontrun{
param$weather()
}
Method param()
Set parameters for parametric simulations
Usage
ParametricJob$param(..., .names = NULL, .cross = FALSE)
Arguments
...Lists of paramter definitions. Please see above on the
syntax.
.namesA character vector of the parameter names. If NULL,
the parameter will be named in format param_X, where
X is the index of parameter. Default: NULL.
.crossIf TRUE, all combinations of parameter values will be
used to create models. If FALSE, each parameter should have
the same length of values. Default: FALSE.
Details
$param() takes parameter definitions in list format, which is
similar to Idf$set() except that each field is not assigned
with a single value, but a vector of any length, indicating the
levels of each parameter.
Similar like the way of modifying object field values in
Idf$set(), there are 3 different ways of defining a parameter
in epluspar:
-
object = list(field = c(value1, value2, ...)): Where object is
a valid object ID or name. Note object ID should be denoted with
two periods .., e.g. ..10 indicates the object with ID 10, It
will set that specific field in that object as one parameter.
-
.(object, object) := list(field = c(value1, value2, ...)):
Simimar like above, but note the use of .() in the left hand
side. You can put multiple object ID or names in .(). It will
set the field of all specified objects as one parameter.
-
class := list(field = c(value1, value2, ...)): 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. It will set that field of all objects in specified
class as one parameter.
For example, the code block below defines 3 parameters:
Field Fan Total Efficiency in object named Supply Fan 1 in class
Fan:VariableVolume class, with 10 levels being 0.1 to 1.0 with a
0.1 step.
Field Thickness in all objects in class Material, with 10
levels being 0.01 to 0.1 m with a 0.1 m step.
Field Conductivity in all objects in class Material, with 10
levels being 0.1 to 1.0 W/m-K with a 0.1 W/m-K step.
param$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = seq(0.1, 1.0, 0.1)),
Material := list(
Thickness = seq(0.01, 0.1, 0.1),
Conductivity = seq(0.1, 1.0, 0.1)
)
)
Returns
The modified ParametricJob object invisibly.
Examples
\dontrun{
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = .(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
# specify parameter values
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.names = c("thickness", "conduct", "fan_eff")
)
# each parameter should have the same length of values
try(
param$param(
Material := list(Thickness = c(0.1, 0.2)),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
)
# use all combinations of parameters
param$param(
Material := list(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.cross = TRUE
)
}
Method apply_measure()
Create parametric models
Usage
ParametricJob$apply_measure(measure, ..., .names = NULL)
Arguments
measureA function that takes an Idf and other arguments as
input and returns an Idf object as output.
...Arguments except first Idf argument that are passed
to that measure.
.namesA character vector of the names of parametric Idfs.
If NULL, the new Idfs will be named in format
measure_name + number.
Details
$apply_measure() allows to apply a measure to an Idf and creates
parametric models for analysis. Basically, a measure is just a
function that takes an Idf object and other arguements as input, and
returns a modified Idf object as output. Use ... to supply
different arguments, except for the first Idf argument, to that
measure. Under the hook, base::mapply() is used to create multiple
Idfs according to the input values.
Returns
The modified ParametricJob object itself, invisibly.
Examples
\dontrun{
# create a measure to change the orientation of the building
rotate_building <- function(idf, degree = 0L) {
if (!idf$is_valid_class("Building")) {
stop("Input model does not have a Building object")
}
if (degree > 360 || degree < -360 ) {
stop("Input degree should in range [-360, 360]")
}
cur <- idf$Building$North_Axis
new <- cur + degree
if (new > 360) {
new <- new %% 360
warning("Calculated new north axis is greater than 360. ",
"Final north axis will be ", new
)
} else if (new < -360) {
new <- new %% -360
warning("Calculated new north axis is smaller than -360. ",
"Final north axis will be ", new
)
}
idf$Building$North_Axis <- new
idf
}
# apply measure
# this will create 12 models
param$apply_measure(rotate_building, degree = seq(30, 360, 30))
# apply measure with new names specified
param$apply_measure(rotate_building, degree = seq(30, 360, 30),
.names = paste0("rotate_", seq(30, 360, 30))
)
}
Method models()
Get created parametric Idf objects
Usage
ParametricJob$models(names = NULL)
Arguments
namesA character vector of new names for parametric models.
If a single string, it will be used as a prefix and all models
will be named in pattern names_X, where X is the model
index. If NULL, existing parametric models are directly
returned. Default: NULL.
Details
$models() returns a list of parametric models generated using input
Idf object and
$apply_measure()
method. Model names are assigned in the same way as the .names
arugment in
$apply_measure().
If no measure has been applied, NULL is returned. Note that it is
not recommended to conduct any extra modification on those models
directly, after they were created using
$apply_measure(),
as this may lead to an un-reproducible process. A warning message
will be issued if any of those models has been modified when running
simulations.
Examples
\dontrun{
param$models()
}
Method cases()
Get a summary of parametric models and parameters
Usage
ParametricJob$cases()
Details
$cases() returns a data.table giving a
summary of parametric models and parameter values.
The returned data.table has the following columns:
-
index: Integer type. The indices of parameter models
-
case: Character type. The names of parameter models
Parameters: Type depends on the parameter values. Each parameter
stands in a separate column. For parametric models created using
ParametricJob$param(), the column names will be the same as what
you specified in .names. For the case of
ParametricJob$apply_measure(), this will be the argument names of
the measure functions.
Returns
If no parametric models have been created, NULL is
returned. Otherwise, a data.table.
Examples
\dontrun{
param$cases()
}
Method save()
Save parametric models
Usage
ParametricJob$save(dir = NULL, separate = TRUE, copy_external = FALSE)
Arguments
dirThe parent output directory for models to be saved. If
NULL, the directory of the seed model will be used. Default:
NULL.
separateIf TRUE, all models are saved in a separate folder
with each model's name under specified directory. If FALSE,
all models are saved in the specified directory. Default:
TRUE.
copy_externalOnly applicable when separate is TRUE. If
TRUE, the external files that every Idf object depends on
will also be copied into the saving directory. The values of
file paths in the Idf will be changed automatically.
Details
$save() saves all parametric models in specified folder. An error
will be issued if no measure has been applied.
Returns
A data.table::data.table() with two columns:
model: The path of saved parametric model files.
weather: The path of saved weather files.
Examples
\dontrun{
# save all parametric models with each model in a separate folder
param$save(tempdir())
# save all parametric models with all models in the same folder
param$save(tempdir(), separate = FALSE)
}
Method run()
Run parametric simulations
Usage
ParametricJob$run(
dir = NULL,
wait = TRUE,
force = FALSE,
copy_external = FALSE,
echo = wait,
separate = TRUE,
readvars = TRUE
)
Arguments
dirThe parent output directory for specified simulations.
Outputs of each simulation are placed in a separate folder
under the parent directory. If NULL, the directory of the
seed model will be used. Default: NULL.
waitIf TRUE, R will hang on and wait all EnergyPlus
simulations finish. If FALSE, all EnergyPlus simulations are
run in the background. Default: 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. Currently, only Schedule:File class
is supported. This ensures that the output directory will
have all files needed for the model to run. Default is
FALSE.
echoOnly applicable when wait is TRUE. Whether to
simulation status. Default: same as wait.
separateIf TRUE, all models are saved in a separate folder
with each model's name under dir when simulation. If FALSE,
all models are saved in dir when simulation. Default:
TRUE.
readvarsIf TRUE, the ReadVarESO post-processor will run
to generate CSV files from the ESO output. Since those CSV
files are never used when extracting simulation data in eplusr,
setting it to FALSE can speed up the simulation if there are
hundreds of output variables or meters. Default: TRUE.
Details
$run() runs all parametric simulations in parallel. The number of
parallel EnergyPlus process can be controlled by
eplusr_option("num_parallel"). If wait is FALSE, then the job
will be run in the background. You can get updated job status by just
printing the ParametricJob object.
Returns
The ParametricJob object itself, invisibly.
Examples
\dontrun{
# run parametric simulations
param$run(wait = TRUE, echo = FALSE)
# run in background
param$run(wait = FALSE)
# get detailed job status by printing
print(param)
}
Method print()
Print ParametricJob object
Usage
ParametricJob$print()
Details
$print() shows the core information of this ParametricJob,
including the path of IDFs and EPWs and also the simulation job
status.
$print() is quite useful to get the simulation status, especially
when wait is FALSE in $run(). The job status will be updated
and printed whenever $print() is called.
Returns
The ParametricJob object itself, invisibly.
Examples
\dontrun{
param$print()
Sys.sleep(10)
param$print()
}
Author(s)
Hongyuan Jia
See Also
eplus_job() for creating an EnergyPlus single simulation job.
Examples
## ------------------------------------------------
## Method `ParametricJob$new`
## ------------------------------------------------
## Not run:
if (is_avail_eplus("8.8")) {
path_idf <- path_eplus_example("8.8", "5Zone_Transformer.idf")
path_epw <- path_eplus_weather("8.8", "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw")
# create from an IDF and an EPW
param <- param_job(path_idf, path_epw)
param <- ParametricJob$new(path_idf, path_epw)
# create from an Idf and an Epw object
param_job(read_idf(path_idf), read_epw(path_epw))
}
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$version`
## ------------------------------------------------
## Not run:
param$version()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$seed`
## ------------------------------------------------
## Not run:
param$seed()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$weather`
## ------------------------------------------------
## Not run:
param$weather()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$param`
## ------------------------------------------------
## Not run:
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = .(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
# specify parameter values
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.names = c("thickness", "conduct", "fan_eff")
)
# each parameter should have the same length of values
try(
param$param(
Material := list(Thickness = c(0.1, 0.2)),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
)
# use all combinations of parameters
param$param(
Material := list(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.cross = TRUE
)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$apply_measure`
## ------------------------------------------------
## Not run:
# create a measure to change the orientation of the building
rotate_building <- function(idf, degree = 0L) {
if (!idf$is_valid_class("Building")) {
stop("Input model does not have a Building object")
}
if (degree > 360 || degree < -360 ) {
stop("Input degree should in range [-360, 360]")
}
cur <- idf$Building$North_Axis
new <- cur + degree
if (new > 360) {
new <- new %% 360
warning("Calculated new north axis is greater than 360. ",
"Final north axis will be ", new
)
} else if (new < -360) {
new <- new %% -360
warning("Calculated new north axis is smaller than -360. ",
"Final north axis will be ", new
)
}
idf$Building$North_Axis <- new
idf
}
# apply measure
# this will create 12 models
param$apply_measure(rotate_building, degree = seq(30, 360, 30))
# apply measure with new names specified
param$apply_measure(rotate_building, degree = seq(30, 360, 30),
.names = paste0("rotate_", seq(30, 360, 30))
)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$models`
## ------------------------------------------------
## Not run:
param$models()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$cases`
## ------------------------------------------------
## Not run:
param$cases()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$save`
## ------------------------------------------------
## Not run:
# save all parametric models with each model in a separate folder
param$save(tempdir())
# save all parametric models with all models in the same folder
param$save(tempdir(), separate = FALSE)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$run`
## ------------------------------------------------
## Not run:
# run parametric simulations
param$run(wait = TRUE, echo = FALSE)
# run in background
param$run(wait = FALSE)
# get detailed job status by printing
print(param)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$print`
## ------------------------------------------------
## Not run:
param$print()
Sys.sleep(10)
param$print()
## End(Not run)
eplusr documentation built on Aug. 25, 2023, 5:18 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| ParametricJob | R Documentation |
Create and Run Parametric Analysis, and Collect Results
Description
ParametricJob class provides a prototype of conducting parametric analysis
of EnergyPlus simulations.
param_job() takes an IDF and EPW as input and returns a ParametricJob.
For details on ParametricJob, please see ParametricJob class.
Usage
param_job(idf, epw)
Arguments
idf |
A path to EnergyPlus IDF or IMF file or an |
epw |
A path to EnergyPlus EPW file or an |
Details
Basically, it is a collection of multiple EplusJob objects. However, the
model is first parsed and the Idf object is stored internally, instead of
storing only the path of Idf like in EplusJob class. Also, an object in
Output:SQLite with Option Type value of SimpleAndTabular will be
automatically created if it does not exists, like Idf class does.
Value
A ParametricJob object.
Super class
eplusr::EplusGroupJob -> ParametricJob
Methods
Public methods
Inherited methods
eplusr::EplusGroupJob$errors()eplusr::EplusGroupJob$kill()eplusr::EplusGroupJob$list_files()eplusr::EplusGroupJob$list_table()eplusr::EplusGroupJob$locate_output()eplusr::EplusGroupJob$output_dir()eplusr::EplusGroupJob$read_mdd()eplusr::EplusGroupJob$read_rdd()eplusr::EplusGroupJob$read_table()eplusr::EplusGroupJob$report_data()eplusr::EplusGroupJob$report_data_dict()eplusr::EplusGroupJob$status()eplusr::EplusGroupJob$tabular_data()
Method new()
Create a ParametricJob object
Usage
ParametricJob$new(idf, epw)
Arguments
idfPath to EnergyPlus IDF file or an
Idfobject.epwPath to EnergyPlus EPW file or an
Epwobject.epwcan also beNULLwhich will force design-day-only simulation when$run()method is called. Note this needs at least oneSizing:DesignDayobject exists in the Idf.
Returns
A ParametricJob object.
Examples
\dontrun{
if (is_avail_eplus("8.8")) {
path_idf <- path_eplus_example("8.8", "5Zone_Transformer.idf")
path_epw <- path_eplus_weather("8.8", "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw")
# create from an IDF and an EPW
param <- param_job(path_idf, path_epw)
param <- ParametricJob$new(path_idf, path_epw)
# create from an Idf and an Epw object
param_job(read_idf(path_idf), read_epw(path_epw))
}
}
Method version()
Get the version of seed IDF
Usage
ParametricJob$version()
Details
$version() returns the version of input seed Idf object.
Returns
A base::numeric_version() object.
Examples
\dontrun{
param$version()
}
Method seed()
Get the seed Idf object
Usage
ParametricJob$seed()
Details
$seed() returns the parsed input seed Idf object.
Examples
\dontrun{
param$seed()
}
Method weather()
Get the Epw object
Usage
ParametricJob$weather()
Details
$weather() returns the input Epw object. If no Epw is provided
when creating the ParametricJob object, NULL is returned.
Examples
\dontrun{
param$weather()
}
Method param()
Set parameters for parametric simulations
Usage
ParametricJob$param(..., .names = NULL, .cross = FALSE)
Arguments
...Lists of paramter definitions. Please see above on the syntax.
.namesA character vector of the parameter names. If
NULL, the parameter will be named in formatparam_X, whereXis the index of parameter. Default:NULL..crossIf
TRUE, all combinations of parameter values will be used to create models. IfFALSE, each parameter should have the same length of values. Default:FALSE.
Details
$param() takes parameter definitions in list format, which is
similar to Idf$set() except that each field is not assigned
with a single value, but a vector of any length, indicating the
levels of each parameter.
Similar like the way of modifying object field values in Idf$set(), there are 3 different ways of defining a parameter in epluspar:
-
object = list(field = c(value1, value2, ...)): Whereobjectis a valid object ID or name. Note object ID should be denoted with two periods.., e.g...10indicates the object with ID10, It will set that specific field in that object as one parameter. -
.(object, object) := list(field = c(value1, value2, ...)): Simimar like above, but note the use of.()in the left hand side. You can put multiple object ID or names in.(). It will set the field of all specified objects as one parameter. -
class := list(field = c(value1, value2, ...)): 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. It will set that field of all objects in specified class as one parameter.
For example, the code block below defines 3 parameters:
Field
Fan Total Efficiencyin object namedSupply Fan 1in classFan:VariableVolumeclass, with 10 levels being 0.1 to 1.0 with a 0.1 step.Field
Thicknessin all objects in classMaterial, with 10 levels being 0.01 to 0.1 m with a 0.1 m step.Field
Conductivityin all objects in classMaterial, with 10 levels being 0.1 to 1.0 W/m-K with a 0.1 W/m-K step.
param$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = seq(0.1, 1.0, 0.1)),
Material := list(
Thickness = seq(0.01, 0.1, 0.1),
Conductivity = seq(0.1, 1.0, 0.1)
)
)
Returns
The modified ParametricJob object invisibly.
Examples
\dontrun{
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = .(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
# specify parameter values
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.names = c("thickness", "conduct", "fan_eff")
)
# each parameter should have the same length of values
try(
param$param(
Material := list(Thickness = c(0.1, 0.2)),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
)
# use all combinations of parameters
param$param(
Material := list(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.cross = TRUE
)
}
Method apply_measure()
Create parametric models
Usage
ParametricJob$apply_measure(measure, ..., .names = NULL)
Arguments
measureA function that takes an
Idfand other arguments as input and returns an Idf object as output....Arguments except first
Idfargument that are passed to thatmeasure..namesA character vector of the names of parametric
Idfs. IfNULL, the newIdfs will be named in formatmeasure_name + number.
Details
$apply_measure() allows to apply a measure to an Idf and creates
parametric models for analysis. Basically, a measure is just a
function that takes an Idf object and other arguements as input, and
returns a modified Idf object as output. Use ... to supply
different arguments, except for the first Idf argument, to that
measure. Under the hook, base::mapply() is used to create multiple
Idfs according to the input values.
Returns
The modified ParametricJob object itself, invisibly.
Examples
\dontrun{
# create a measure to change the orientation of the building
rotate_building <- function(idf, degree = 0L) {
if (!idf$is_valid_class("Building")) {
stop("Input model does not have a Building object")
}
if (degree > 360 || degree < -360 ) {
stop("Input degree should in range [-360, 360]")
}
cur <- idf$Building$North_Axis
new <- cur + degree
if (new > 360) {
new <- new %% 360
warning("Calculated new north axis is greater than 360. ",
"Final north axis will be ", new
)
} else if (new < -360) {
new <- new %% -360
warning("Calculated new north axis is smaller than -360. ",
"Final north axis will be ", new
)
}
idf$Building$North_Axis <- new
idf
}
# apply measure
# this will create 12 models
param$apply_measure(rotate_building, degree = seq(30, 360, 30))
# apply measure with new names specified
param$apply_measure(rotate_building, degree = seq(30, 360, 30),
.names = paste0("rotate_", seq(30, 360, 30))
)
}
Method models()
Get created parametric Idf objects
Usage
ParametricJob$models(names = NULL)
Arguments
namesA character vector of new names for parametric models. If a single string, it will be used as a prefix and all models will be named in pattern
names_X, whereXis the model index. IfNULL, existing parametric models are directly returned. Default:NULL.
Details
$models() returns a list of parametric models generated using input
Idf object and
$apply_measure()
method. Model names are assigned in the same way as the .names
arugment in
$apply_measure().
If no measure has been applied, NULL is returned. Note that it is
not recommended to conduct any extra modification on those models
directly, after they were created using
$apply_measure(),
as this may lead to an un-reproducible process. A warning message
will be issued if any of those models has been modified when running
simulations.
Examples
\dontrun{
param$models()
}
Method cases()
Get a summary of parametric models and parameters
Usage
ParametricJob$cases()
Details
$cases() returns a data.table giving a
summary of parametric models and parameter values.
The returned data.table has the following columns:
-
index: Integer type. The indices of parameter models -
case: Character type. The names of parameter models Parameters: Type depends on the parameter values. Each parameter stands in a separate column. For parametric models created using
ParametricJob$param(), the column names will be the same as what you specified in.names. For the case ofParametricJob$apply_measure(), this will be the argument names of the measure functions.
Returns
If no parametric models have been created, NULL is
returned. Otherwise, a data.table.
Examples
\dontrun{
param$cases()
}
Method save()
Save parametric models
Usage
ParametricJob$save(dir = NULL, separate = TRUE, copy_external = FALSE)
Arguments
dirThe parent output directory for models to be saved. If
NULL, the directory of the seed model will be used. Default:NULL.separateIf
TRUE, all models are saved in a separate folder with each model's name under specified directory. IfFALSE, all models are saved in the specified directory. Default:TRUE.copy_externalOnly applicable when
separateisTRUE. IfTRUE, the external files that everyIdfobject depends on will also be copied into the saving directory. The values of file paths in the Idf will be changed automatically.
Details
$save() saves all parametric models in specified folder. An error
will be issued if no measure has been applied.
Returns
A data.table::data.table() with two columns:
model: The path of saved parametric model files.
weather: The path of saved weather files.
Examples
\dontrun{
# save all parametric models with each model in a separate folder
param$save(tempdir())
# save all parametric models with all models in the same folder
param$save(tempdir(), separate = FALSE)
}
Method run()
Run parametric simulations
Usage
ParametricJob$run( dir = NULL, wait = TRUE, force = FALSE, copy_external = FALSE, echo = wait, separate = TRUE, readvars = TRUE )
Arguments
dirThe parent output directory for specified simulations. Outputs of each simulation are placed in a separate folder under the parent directory. If
NULL, the directory of the seed model will be used. Default:NULL.waitIf
TRUE, R will hang on and wait all EnergyPlus simulations finish. IfFALSE, all EnergyPlus simulations are run in the background. Default:TRUE.forceOnly applicable when the last simulation runs with
waitequals toFALSEand is still running. IfTRUE, current running job is forced to stop and a new one will start. Default:FALSE.copy_externalIf
TRUE, the external files that currentIdfobject depends on will also be copied into the simulation output directory. The values of file paths in the Idf will be changed automatically. Currently, onlySchedule:Fileclass is supported. This ensures that the output directory will have all files needed for the model to run. Default isFALSE.echoOnly applicable when
waitisTRUE. Whether to simulation status. Default: same aswait.separateIf
TRUE, all models are saved in a separate folder with each model's name underdirwhen simulation. IfFALSE, all models are saved indirwhen simulation. Default:TRUE.readvarsIf
TRUE, theReadVarESOpost-processor will run to generate CSV files from the ESO output. Since those CSV files are never used when extracting simulation data in eplusr, setting it toFALSEcan speed up the simulation if there are hundreds of output variables or meters. Default:TRUE.
Details
$run() runs all parametric simulations in parallel. The number of
parallel EnergyPlus process can be controlled by
eplusr_option("num_parallel"). If wait is FALSE, then the job
will be run in the background. You can get updated job status by just
printing the ParametricJob object.
Returns
The ParametricJob object itself, invisibly.
Examples
\dontrun{
# run parametric simulations
param$run(wait = TRUE, echo = FALSE)
# run in background
param$run(wait = FALSE)
# get detailed job status by printing
print(param)
}
Method print()
Print ParametricJob object
Usage
ParametricJob$print()
Details
$print() shows the core information of this ParametricJob,
including the path of IDFs and EPWs and also the simulation job
status.
$print() is quite useful to get the simulation status, especially
when wait is FALSE in $run(). The job status will be updated
and printed whenever $print() is called.
Returns
The ParametricJob object itself, invisibly.
Examples
\dontrun{
param$print()
Sys.sleep(10)
param$print()
}
Author(s)
Hongyuan Jia
See Also
eplus_job() for creating an EnergyPlus single simulation job.
Examples
## ------------------------------------------------
## Method `ParametricJob$new`
## ------------------------------------------------
## Not run:
if (is_avail_eplus("8.8")) {
path_idf <- path_eplus_example("8.8", "5Zone_Transformer.idf")
path_epw <- path_eplus_weather("8.8", "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw")
# create from an IDF and an EPW
param <- param_job(path_idf, path_epw)
param <- ParametricJob$new(path_idf, path_epw)
# create from an Idf and an Epw object
param_job(read_idf(path_idf), read_epw(path_epw))
}
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$version`
## ------------------------------------------------
## Not run:
param$version()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$seed`
## ------------------------------------------------
## Not run:
param$seed()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$weather`
## ------------------------------------------------
## Not run:
param$weather()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$param`
## ------------------------------------------------
## Not run:
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = .(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
# specify parameter values
param$param(
Material := .(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.names = c("thickness", "conduct", "fan_eff")
)
# each parameter should have the same length of values
try(
param$param(
Material := list(Thickness = c(0.1, 0.2)),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8))
)
)
# use all combinations of parameters
param$param(
Material := list(
Thickness = seq(0.1, 1, length.out = 3),
Conductivity = seq(0.1, 0.6, length.out = 3)
),
"Supply Fan 1" = list(fan_total_efficiency = c(0.1, 0.5, 0.8)),
.cross = TRUE
)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$apply_measure`
## ------------------------------------------------
## Not run:
# create a measure to change the orientation of the building
rotate_building <- function(idf, degree = 0L) {
if (!idf$is_valid_class("Building")) {
stop("Input model does not have a Building object")
}
if (degree > 360 || degree < -360 ) {
stop("Input degree should in range [-360, 360]")
}
cur <- idf$Building$North_Axis
new <- cur + degree
if (new > 360) {
new <- new %% 360
warning("Calculated new north axis is greater than 360. ",
"Final north axis will be ", new
)
} else if (new < -360) {
new <- new %% -360
warning("Calculated new north axis is smaller than -360. ",
"Final north axis will be ", new
)
}
idf$Building$North_Axis <- new
idf
}
# apply measure
# this will create 12 models
param$apply_measure(rotate_building, degree = seq(30, 360, 30))
# apply measure with new names specified
param$apply_measure(rotate_building, degree = seq(30, 360, 30),
.names = paste0("rotate_", seq(30, 360, 30))
)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$models`
## ------------------------------------------------
## Not run:
param$models()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$cases`
## ------------------------------------------------
## Not run:
param$cases()
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$save`
## ------------------------------------------------
## Not run:
# save all parametric models with each model in a separate folder
param$save(tempdir())
# save all parametric models with all models in the same folder
param$save(tempdir(), separate = FALSE)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$run`
## ------------------------------------------------
## Not run:
# run parametric simulations
param$run(wait = TRUE, echo = FALSE)
# run in background
param$run(wait = FALSE)
# get detailed job status by printing
print(param)
## End(Not run)
## ------------------------------------------------
## Method `ParametricJob$print`
## ------------------------------------------------
## Not run:
param$print()
Sys.sleep(10)
param$print()
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.