R: Create and Run Parametric Analysis, and Collect Results

ParametricJob {eplusr}

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

Inherited methods

Method `new()`

Create a ParametricJob object

Usage

ParametricJob$new(idf, epw)

Arguments

idf: Path to EnergyPlus IDF file or an Idf object.
epw: 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.

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.
.names: A 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.
.cross: If 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

measure: A 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.
.names: A 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

names: A 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

dir: The parent output directory for models to be saved. If NULL, the directory of the seed model will be used. Default: NULL.
separate: If 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_external: Only 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

dir: The 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.
wait: If TRUE, R will hang on and wait all EnergyPlus simulations finish. If FALSE, all EnergyPlus simulations are run in the background. Default: TRUE.
force: Only applicable when the last simulation runs with wait equals to FALSE and is still running. If TRUE, current running job is forced to stop and a new one will start. Default: FALSE.
copy_external: If TRUE, the external files that current Idf object depends on will also be copied into the simulation output directory. The values of file paths in the Idf will be changed automatically. Currently, only Schedule:File class is supported. This ensures that the output directory will have all files needed for the model to run. Default is FALSE.
echo: Only applicable when wait is TRUE. Whether to simulation status. Default: same as wait.
separate: If 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.
readvars: If 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

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)

[Package eplusr version 0.16.2 Index]

Create and Run Parametric Analysis, and Collect Results

Description

Usage

Arguments

Details

Value

Super class

Methods

Public methods

Method new()

Usage

Arguments

Returns

Examples

Method version()

Usage

Details

Returns

Examples

Method seed()

Usage

Details

Examples

Method weather()

Usage

Details

Examples

Method param()

Usage

Arguments

Details

Returns

Examples

Method apply_measure()

Usage

Arguments

Details

Returns

Examples

Method models()

Usage

Arguments

Details

Examples

Method cases()

Usage

Details

Returns

Examples

Method save()

Usage

Arguments

Details

Returns

Examples

Method run()

Usage

Arguments

Details

Returns

Examples

Method print()

Usage

Details

Returns

Examples

Author(s)

See Also

Examples

Method `new()`

Method `version()`

Method `seed()`

Method `weather()`

Method `param()`

Method `apply_measure()`

Method `models()`

Method `cases()`

Method `save()`

Method `run()`

Method `print()`