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

Public 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:

For example, the code block below defines 3 parameters:

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:

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:

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

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)


[Package eplusr version 0.15.1 Index]