Create and Run Parametric Analysis, and Collect Results

Source: R/param.R

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.

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.

Value

A ParametricJob object.

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.

See also

eplus_job() for creating an EnergyPlus single simulation job.

Author

Hongyuan Jia

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 parameter 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, ...)): 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 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 argument input, argument 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 argument 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()
}

Examples


## ------------------------------------------------
## Method `ParametricJob$new`
## ------------------------------------------------

if (FALSE) { # \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 `ParametricJob$version`
## ------------------------------------------------

if (FALSE) { # \dontrun{
param$version()
} # }


## ------------------------------------------------
## Method `ParametricJob$seed`
## ------------------------------------------------

if (FALSE) { # \dontrun{
param$seed()
} # }


## ------------------------------------------------
## Method `ParametricJob$weather`
## ------------------------------------------------

if (FALSE) { # \dontrun{
param$weather()
} # }


## ------------------------------------------------
## Method `ParametricJob$param`
## ------------------------------------------------

if (FALSE) { # \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 `ParametricJob$apply_measure`
## ------------------------------------------------

if (FALSE) { # \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 `ParametricJob$models`
## ------------------------------------------------

if (FALSE) { # \dontrun{
param$models()
} # }


## ------------------------------------------------
## Method `ParametricJob$cases`
## ------------------------------------------------

if (FALSE) { # \dontrun{
param$cases()
} # }


## ------------------------------------------------
## Method `ParametricJob$save`
## ------------------------------------------------

if (FALSE) { # \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 `ParametricJob$run`
## ------------------------------------------------

if (FALSE) { # \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 `ParametricJob$print`
## ------------------------------------------------

if (FALSE) { # \dontrun{
param$print()

Sys.sleep(10)
param$print()
} # }