Conduct Sensitivity Analysis for An EnergyPlus Model

sensi_job() takes an IDF and EPW as input and returns a SensitivityJob, which provides a prototype of conducting sensitivity analysis of EnergyPlus simulations using Morris method.

Details

SensitivityJob inherits from eplusr::ParametricJob class, which means that all methods provided by eplusr::ParametricJob class are also available for SensitivityJob class.

The basic workflow is basically:

1. Adding parameters for sensitivity analysis using $param() or $apply_measure().

2. Check parameter sampled values and generated parametric models using $samples() and $models(), respectively.

3. Run EnergyPlus simulations in parallel using $run(),

4. Gather EnergyPlus simulated data using $report_data() or $tabular_data().

5. Evaluate parameter sensitivity using $evaluate().

Author

Hongyuan Jia

Super classes

eplusr::EplusGroupJob -> eplusr::ParametricJob -> SensitivityJob

Methods

Public methods

• SensitivityJob$param()

• SensitivityJob$apply_measure()

• SensitivityJob$samples()

• SensitivityJob$evaluate()

• SensitivityJob$print()

Inherited methods

• eplusr::EplusGroupJob$errors()

• eplusr::EplusGroupJob$kill()

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

• eplusr::ParametricJob$initialize()

• eplusr::ParametricJob$models()

• eplusr::ParametricJob$run()

• eplusr::ParametricJob$save()

• eplusr::ParametricJob$seed()

• eplusr::ParametricJob$version()

• eplusr::ParametricJob$weather()

---

Method param()

Set parameters for sensitivity analysis

Usage

SensitivityJob$param(
...,
.names = NULL,
.r = 12L,
.grid_jump = 4L,
.scale = TRUE
)

Arguments

...

Lists of paramter definitions. Please see above on the syntax.

.names

A character vector of the parameter names. If NULL, the parameter will be named in format theta + number, where number is the index of parameter. Default: NULL.

.r

An positive integer specifying the number of elementary effect computed per factor. For details, see sensitivity::morris. Default: 12.

.grid_jump

An integer or a vector of integers specifying the number of levels that are increased/decreased for computing the elementary effects. Default: 1L. For details, see sensitivity::morris.

.scale

If TRUE, the input design of experiments is scaled after building the design and before computing the elementary effects so that all factors vary within the range [0,1]. Default: TRUE. For details, see sensitivity::morris.

Details

$param() takes parameter definitions in list format, which is similar to $set() in eplusr::Idf class except that each field is not assigned with a single value, but a numeric vector of length 3, indicating the minimum value, maximum value and number of levels of each parameter.

Similar like the way of modifying object field values in eplusr::Idf$set(), there are 3 different ways of defining a parameter in epluspar:

• object = list(field = c(min, max, levels)): 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(min, max, levels)): 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(min, max, levels)): 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 eplusr::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 minimum, maximum and number of levels being 0.1, 1.0 and 5, respectively.

• Field Thickness in all objects in class Material, with minimum, maximum and number of levels being 0.01, 1.0 and 5, respectively.

• Field Conductivity in all objects in class Material, with minimum, maximum and number of levels being 0.1, 0.6 and 10, respectively.

sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)

Returns

The modified SensitivityJob object itself.

Examples

\dontrun{
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
}

---

Method apply_measure()

Set parameters for sensitivity analysis using function

Usage

SensitivityJob$apply_measure(
measure,
...,
.r = 12L,
.grid_jump = 4L,
.scale = TRUE
)

Arguments

measure

A function that takes an eplusr::Idf and other arguments as input and returns an eplusr::Idf object as output.

...

Arguments except first Idf argument that are passed to that measure.

.r

An positive integer specifying the number of elementary effect computed per factor. For details, see sensitivity::morris.

.grid_jump

An integer or a vector of integers specifying the number of levels that are increased/decreased for computing the elementary effects. For details, see sensitivity::morris.

.scale

If TRUE, the input design of experiments is scaled after building the design and before computing the elementary effects so that all factors vary within the range [0,1]. Default: TRUE. For details, see sensitivity::morris.

Details

$apply_measure() works in a similar way as the $apply_measure in eplusr::ParametricJob class, with only exception that each argument supplied in ... should be a numeric vector of length 3, indicating the minimum, maximum and number of levels of each parameter.

Basically $apply_measure() allows to apply a measure to an eplusr::Idf. A measure here is just a function that takes an eplusr::Idf object and other arguments as input, and returns a modified eplusr::Idf object as output.

The names of function parameter will be used as the names of sensitivity parameter. For example, the equivalent version of specifying parameters described in $param() using $apply_measure() can be:

# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)

Returns

The modified SensitivityJob object itself.

Examples

\dontrun{
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
}

---

Method samples()

Get sampled parameter values

Usage

SensitivityJob$samples()

Details

$samples() returns a data.table::data.table() which contains the sampled value for each parameter using Morris method. The returned data.table has 1 + n columns, where n is the parameter number, while 1 indicates an extra column named case giving the index of each sample.

Returns

A data.table::data.table().

Examples

\dontrun{
sensi$samples()
}

---

Method evaluate()

Evaluate sensitivity

Usage

SensitivityJob$evaluate(results)

Arguments

results

A numeric vector. Usually the output of parametric simulations extracted using $report_data() or $tabular_data().

Details

$evaluate() takes a numeric vector with the same length as total sample number and returns the a sensitivity::morris() object. The statistics of interest (mu, mu* and sigma) are stored as an attribute named data and can be retrieved using atrr(sensi$evaluate(), "data").

Returns

a sensitivity::morris() object with an extra data attribute.

Examples

\dontrun{
# run parametric simulations
sensi$run(wait = TRUE)

# status now includes a data.table with detailed information on each simulation
sensi$status()

# print simulation errors
sensi$errors()

# extract a target simulation output value for each case to evaluate the
# sensitivity results
eng <- sen$tabular_data(table_name = "site and source energy",
column_name = "energy per total building area",
row_name = "total site energy")[, as.numeric(value)]
(result <- sensi$evaluate(eng))

# extract sensivitity data
attr(result, "data")

# plot
plot(result)
}

---

Method print()

Print SensitivityJob object

Usage

SensitivityJob$print()

Details

$print() shows the core information of this SensitivityJob, 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 SensitivityJob object itself, invisibly.

Examples

\dontrun{
sen$print()
}

Examples

## ------------------------------------------------
## Method `SensitivityJob$param`
## ------------------------------------------------

# \dontrun{
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
#> Error in eval(expr, envir, enclos): object 'sensi' not found
# }


## ------------------------------------------------
## Method `SensitivityJob$apply_measure`
## ------------------------------------------------

# \dontrun{
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
#> Error in eval(expr, envir, enclos): object 'sensi' not found
# }


## ------------------------------------------------
## Method `SensitivityJob$samples`
## ------------------------------------------------

# \dontrun{
sensi$samples()
#> Error in eval(expr, envir, enclos): object 'sensi' not found
# }


## ------------------------------------------------
## Method `SensitivityJob$evaluate`
## ------------------------------------------------

# \dontrun{
# run parametric simulations
sensi$run(wait = TRUE)
#> Error in eval(expr, envir, enclos): object 'sensi' not found

# status now includes a data.table with detailed information on each simulation
sensi$status()
#> Error in eval(expr, envir, enclos): object 'sensi' not found

# print simulation errors
sensi$errors()
#> Error in eval(expr, envir, enclos): object 'sensi' not found

# extract a target simulation output value for each case to evaluate the
# sensitivity results
eng <- sen$tabular_data(table_name = "site and source energy",
column_name = "energy per total building area",
row_name = "total site energy")[, as.numeric(value)]
#> Error in eval(expr, envir, enclos): object 'sen' not found
(result <- sensi$evaluate(eng))
#> Error in eval(expr, envir, enclos): object 'sensi' not found

# extract sensivitity data
attr(result, "data")
#> Error in eval(expr, envir, enclos): object 'result' not found

# plot
plot(result)
#> Error in plot(result): object 'result' not found
# }


## ------------------------------------------------
## Method `SensitivityJob$print`
## ------------------------------------------------

# \dontrun{
sen$print()
#> Error in eval(expr, envir, enclos): object 'sen' not found
# }