ParametricJob class provides a prototype of conducting parametric analysis of EnergyPlus simulations.

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.

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)) {
idf_name <- "1ZoneUncontrolled.idf"
epw_name <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

idf_path <- file.path(eplus_config(8.8)$dir, "ExampleFiles", idf_name)
epw_path <- file.path(eplus_config(8.8)$dir, "WeatherData", epw_name)

# create from an Idf and an Epw object
param <- ParametricJob$new(idf_path, epw_path)
}
}


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

Get created parametric Idf objects

Usage

ParametricJob$models()

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 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 arguments 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 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. Currently, only Schedule:File class is supported. This ensures that the output directory will have all files needed for the model to run. Default: FALSE.

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
)

Arguments

dir

The parent output directory for specified simulations. Outputs of each simulation are placed in a separate folder under the parent directory.

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.

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` ## ------------------------------------------------ # \dontrun{ if (is_avail_eplus(8.8)) { idf_name <- "1ZoneUncontrolled.idf" epw_name <- "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw" idf_path <- file.path(eplus_config(8.8)$dir, "ExampleFiles", idf_name) epw_path <- file.path(eplus_config(8.8)$dir, "WeatherData", epw_name) # create from an Idf and an Epw object param <- ParametricJob$new(idf_path, epw_path) } # } ## ------------------------------------------------ ## Method `ParametricJob$version` ## ------------------------------------------------ # \dontrun{ param$version()
#> [1] ‘8.8.0’
# } ## ------------------------------------------------ ## Method `ParametricJob$seed` ## ------------------------------------------------ # \dontrun{ param$seed()
#> ── EnergPlus Input Data File ─────────────────────────────────────────────────── #> * Path: '/home/travis/.local/EnergyPlus-8-8-0/ExampleFiles/1ZoneUncontroll... #> * Version: '8.8.0' #> #> Group: <Simulation Parameters> #> ├─ [01<O>] Class: <Version> #> │─ [01<O>] Class: <SimulationControl> #> │─ [01<O>] Class: <Building> #> │─ [01<O>] Class: <SurfaceConvectionAlgorithm:Inside> #> │─ [01<O>] Class: <SurfaceConvectionAlgorithm:Outside> #> │─ [01<O>] Class: <HeatBalanceAlgorithm> #> └─ [01<O>] Class: <Timestep> #> #> Group: <Location and Climate> #> ├─ [01<O>] Class: <Site:Location> #> │─ [02<O>] Class: <SizingPeriod:DesignDay> #> └─ [01<O>] Class: <RunPeriod> #> #> Group: <Schedules> #> ├─ [02<O>] Class: <ScheduleTypeLimits> #> └─ [01<O>] Class: <Schedule:Constant> #> #> Group: <Surface Construction Elements> #> ├─ [01<O>] Class: <Material> #> │─ [02<O>] Class: <Material:NoMass> #> └─ [03<O>] Class: <Construction> #> #> Group: <Thermal Zones and Surfaces> #> ├─ [01<O>] Class: <GlobalGeometryRules> #> │─ [01<O>] Class: <Zone> #> └─ [06<O>] Class: <BuildingSurface:Detailed> #> #> Group: <Internal Gains> #> └─ [02<O>] Class: <OtherEquipment> #> #> Group: <Exterior Equipment> #> └─ [01<O>] Class: <Exterior:Lights> #> #> Group: <Output Reporting> #> ├─ [01<O>] Class: <Output:VariableDictionary> #> │─ [01<O>] Class: <Output:Surfaces:Drawing> #> │─ [01<O>] Class: <Output:Constructions> #> │─ [01<O>] Class: <Output:Table:SummaryReports> #> │─ [01<O>] Class: <OutputControl:Table:Style> #> │─ [14<O>] Class: <Output:Variable> #> │─ [03<O>] Class: <Output:Meter:MeterFileOnly> #> └─ [01<O>] Class: <Output:SQLite>
# } ## ------------------------------------------------ ## Method `ParametricJob$weather` ## ------------------------------------------------ # \dontrun{ param$weather()
#> ══ EnergyPlus Weather File ═════════════════════════════════════════════════════ #> [Location ]: San Francisco Intl Ap, CA, USA #> {N 37°37'}, {W 122°24'}, {UTC-08:00} #> [Elevation]: 2m above see level #> [Data Src ]: TMY3 #> [WMO Stat ]: 724940 #> [Leap Year]: FALSE #> [Interval ]: 60 mins #> #> ── Data Periods ──────────────────────────────────────────────────────────────── #> Name StartDayOfWeek StartDay EndDay #> 1: Data Sunday 1/ 1 12/31 #> #> ────────────────────────────────────────────────────────────────────────────────
# } ## ------------------------------------------------ ## Method `ParametricJob$models` ## ------------------------------------------------ # \dontrun{ param$models()
#> NULL
# } ## ------------------------------------------------ ## Method `ParametricJob$apply_measure` ## ------------------------------------------------ # \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))
#> Measure 'rotate_building' has been applied with 12 new models created: #> [01]: rotate_building_1 #> [02]: rotate_building_2 #> [03]: rotate_building_3 #> [04]: rotate_building_4 #> [05]: rotate_building_5 #> [06]: rotate_building_6 #> [07]: rotate_building_7 #> [08]: rotate_building_8 #> [09]: rotate_building_9 #> [10]: rotate_building_10 #> [11]: rotate_building_11 #> [12]: rotate_building_12
# apply measure with new names specified param$apply_measure(rotate_building, degree = seq(30, 360, 30), .names = paste0("rotate_", seq(30, 360, 30)) )
#> Measure 'rotate_building' has been applied with 12 new models created: #> [01]: rotate_30 #> [02]: rotate_60 #> [03]: rotate_90 #> [04]: rotate_120 #> [05]: rotate_150 #> [06]: rotate_180 #> [07]: rotate_210 #> [08]: rotate_240 #> [09]: rotate_270 #> [10]: rotate_300 #> [11]: rotate_330 #> [12]: rotate_360
# } ## ------------------------------------------------ ## Method `ParametricJob$save` ## ------------------------------------------------ # \dontrun{ # save all parametric models with each model in a separate folder param$save(tempdir())
#> model #> 1: /tmp/Rtmpa0qSDH/rotate_30/rotate_30.idf #> 2: /tmp/Rtmpa0qSDH/rotate_60/rotate_60.idf #> 3: /tmp/Rtmpa0qSDH/rotate_90/rotate_90.idf #> 4: /tmp/Rtmpa0qSDH/rotate_120/rotate_120.idf #> 5: /tmp/Rtmpa0qSDH/rotate_150/rotate_150.idf #> 6: /tmp/Rtmpa0qSDH/rotate_180/rotate_180.idf #> 7: /tmp/Rtmpa0qSDH/rotate_210/rotate_210.idf #> 8: /tmp/Rtmpa0qSDH/rotate_240/rotate_240.idf #> 9: /tmp/Rtmpa0qSDH/rotate_270/rotate_270.idf #> 10: /tmp/Rtmpa0qSDH/rotate_300/rotate_300.idf #> 11: /tmp/Rtmpa0qSDH/rotate_330/rotate_330.idf #> 12: /tmp/Rtmpa0qSDH/rotate_360/rotate_360.idf #> weather #> 1: /tmp/Rtmpa0qSDH/rotate_30/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 2: /tmp/Rtmpa0qSDH/rotate_60/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 3: /tmp/Rtmpa0qSDH/rotate_90/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 4: /tmp/Rtmpa0qSDH/rotate_120/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 5: /tmp/Rtmpa0qSDH/rotate_150/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 6: /tmp/Rtmpa0qSDH/rotate_180/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 7: /tmp/Rtmpa0qSDH/rotate_210/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 8: /tmp/Rtmpa0qSDH/rotate_240/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 9: /tmp/Rtmpa0qSDH/rotate_270/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 10: /tmp/Rtmpa0qSDH/rotate_300/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 11: /tmp/Rtmpa0qSDH/rotate_330/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 12: /tmp/Rtmpa0qSDH/rotate_360/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw
# save all parametric models with all models in the same folder param$save(tempdir(), separate = FALSE)
#> model #> 1: /tmp/Rtmpa0qSDH/rotate_30.idf #> 2: /tmp/Rtmpa0qSDH/rotate_60.idf #> 3: /tmp/Rtmpa0qSDH/rotate_90.idf #> 4: /tmp/Rtmpa0qSDH/rotate_120.idf #> 5: /tmp/Rtmpa0qSDH/rotate_150.idf #> 6: /tmp/Rtmpa0qSDH/rotate_180.idf #> 7: /tmp/Rtmpa0qSDH/rotate_210.idf #> 8: /tmp/Rtmpa0qSDH/rotate_240.idf #> 9: /tmp/Rtmpa0qSDH/rotate_270.idf #> 10: /tmp/Rtmpa0qSDH/rotate_300.idf #> 11: /tmp/Rtmpa0qSDH/rotate_330.idf #> 12: /tmp/Rtmpa0qSDH/rotate_360.idf #> weather #> 1: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 2: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 3: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 4: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 5: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 6: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 7: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 8: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 9: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 10: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 11: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw #> 12: /tmp/Rtmpa0qSDH/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw
# } ## ------------------------------------------------ ## Method `ParametricJob$run` ## ------------------------------------------------ # \dontrun{ # run parametric simulations param$run(wait = TRUE, echo = FALSE)
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_30/rotate_30.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_60/rotate_60.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_90/rotate_90.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_120/rotate_120.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_150/rotate_150.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_180/rotate_180.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_210/rotate_210.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_240/rotate_240.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_270/rotate_270.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_300/rotate_300.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_330/rotate_330.idf.
#> Replace the existing IDF located at /tmp/Rtmpa0qSDH/rotate_360/rotate_360.idf.
#> ── EnergPlus Parametric Simulation Job ───────────────────────────────────────── #> * Seed: '/home/travis/.local/EnergyPlus-8-8-0/ExampleFiles/1ZoneUncontrolle... #> * Weather: '/home/travis/.local/EnergyPlus-8-8-0/WeatherData/USA_CA_San.Fra... #> * EnergyPlus Version: '8.8.0' #> * EnergyPlus Path: '/home/travis/.local/EnergyPlus-8-8-0' #> Applied Measure: 'rotate_building' #> Parametric Models [12]: #> [01]: 'rotate_30' <-- SUCCEEDED #> [02]: 'rotate_60' <-- SUCCEEDED #> [03]: 'rotate_90' <-- SUCCEEDED #> [04]: 'rotate_120' <-- SUCCEEDED #> [05]: 'rotate_150' <-- SUCCEEDED #> [06]: 'rotate_180' <-- SUCCEEDED #> [07]: 'rotate_210' <-- SUCCEEDED #> [08]: 'rotate_240' <-- SUCCEEDED #> [09]: 'rotate_270' <-- SUCCEEDED #> [10]: 'rotate_300' <-- SUCCEEDED #> [11]: 'rotate_330' <-- SUCCEEDED #> [12]: 'rotate_360' <-- SUCCEEDED #> Simulation started at '2020-02-20 12:22:11' and completed successfully after 29.68 secs.
# run in background param$run(wait = FALSE)
#> ── EnergPlus Parametric Simulation Job ───────────────────────────────────────── #> * Seed: '/home/travis/.local/EnergyPlus-8-8-0/ExampleFiles/1ZoneUncontrolle... #> * Weather: '/home/travis/.local/EnergyPlus-8-8-0/WeatherData/USA_CA_San.Fra... #> * EnergyPlus Version: '8.8.0' #> * EnergyPlus Path: '/home/travis/.local/EnergyPlus-8-8-0' #> Applied Measure: 'rotate_building' #> Parametric Models [12]: #> Job started at '2020-02-20 12:22:41' and is still running...
# get detailed job status by printing print(param)
#> ── EnergPlus Parametric Simulation Job ───────────────────────────────────────── #> * Seed: '/home/travis/.local/EnergyPlus-8-8-0/ExampleFiles/1ZoneUncontrolle... #> * Weather: '/home/travis/.local/EnergyPlus-8-8-0/WeatherData/USA_CA_San.Fra... #> * EnergyPlus Version: '8.8.0' #> * EnergyPlus Path: '/home/travis/.local/EnergyPlus-8-8-0' #> Applied Measure: 'rotate_building' #> Parametric Models [12]: #> Job started at '2020-02-20 12:22:41' and is still running...
# } ## ------------------------------------------------ ## Method `ParametricJob$print` ## ------------------------------------------------ # \dontrun{ param$print()
#> ── EnergPlus Parametric Simulation Job ───────────────────────────────────────── #> * Seed: '/home/travis/.local/EnergyPlus-8-8-0/ExampleFiles/1ZoneUncontrolle... #> * Weather: '/home/travis/.local/EnergyPlus-8-8-0/WeatherData/USA_CA_San.Fra... #> * EnergyPlus Version: '8.8.0' #> * EnergyPlus Path: '/home/travis/.local/EnergyPlus-8-8-0' #> Applied Measure: 'rotate_building' #> Parametric Models [12]: #> Job started at '2020-02-20 12:22:41' and is still running...
Sys.sleep(10) param$print()
#> ── EnergPlus Parametric Simulation Job ───────────────────────────────────────── #> * Seed: '/home/travis/.local/EnergyPlus-8-8-0/ExampleFiles/1ZoneUncontrolle... #> * Weather: '/home/travis/.local/EnergyPlus-8-8-0/WeatherData/USA_CA_San.Fra... #> * EnergyPlus Version: '8.8.0' #> * EnergyPlus Path: '/home/travis/.local/EnergyPlus-8-8-0' #> Applied Measure: 'rotate_building' #> Parametric Models [12]:
#> Error in ifelse(exit_status == 0L, paste0(str_trunc(rpad(nm), getOption("width", 60L) - 14L), " <-- SUCCEEDED"), paste0(str_trunc(rpad(nm), getOption("width", 60L) - 11L), " <-- FAILED")): object 'exit_status' not found
# }