Run simulations of EnergyPlus models.

run_idf(
  model,
  weather,
  output_dir,
  design_day = FALSE,
  annual = FALSE,
  expand_obj = TRUE,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL
)

run_multi(
  model,
  weather,
  output_dir,
  design_day = FALSE,
  annual = FALSE,
  expand_obj = TRUE,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL
)

Arguments

model: A path (for run_idf()) or a vector of paths (for run_multi()) of EnergyPlus IDF or IMF files.
weather: A path (for run_idf()) or a vector of paths (for run_multi()) of EnergyPlus EPW weather files. If set to NULL, design-day-only simulation will be triggered, regardless of the design-day value. For run_multi(), weather can also be a single EPW file path. In this case, that weather will be used for all simulations; otherwise, model and weather should have the same length. You can set to design-day-only simulation to some specific simulations by setting the corresponding weather to NA.
output_dir: Output directory path (for rum_idf()) or paths (for run_mult()). If NULL, the directory of input model is used. For run_multi(), output_dir, if not NULL, should have the same length as model. Any duplicated combination of model and output_dir is prohibited.
design_day: Force design-day-only simulation. For rum_multi(), design_day can also be a logical vector which has the same length as model. Note that design_day and annual cannot be all TRUE at the same time. Default: FALSE.
annual: Force annual simulation. For rum_multi(), annual can also be a logical vector which has the same length as model. Note that design_day and annual cannot be all TRUE at the same time. Default: FALSE.
expand_obj: Whether to run ExpandObject preprocessor before simulation. Default: TRUE.
wait: If TRUE, R will hang on and wait all EnergyPlus simulations finish. If FALSE, all EnergyPlus simulations are run in the background, and a process object is returned.
echo: Only applicable when wait is TRUE. Whether to show standard output and error from EnergyPlus for run_idf() and simulation status for run_multi(). Default: TRUE.
eplus: An acceptable input (for run_idf()) or inputs (for run_multi()) of use_eplus() and eplus_config(). If NULL, which is the default, the version of EnergyPlus to use is determined by the version of input model. For run_multi(), eplus, if not NULL, should have the same length as model.

Value

For run_idf(), if wait is TRUE, a named list of 11 elements:

No.	Column	Type	Description
1	`idf`	`character(1)`	Full path of input IDF file
2	`epw`	`character(1)` or `NULL`	Full path of input EPW file
3	`version`	`character(1)`	Version of called EnergyPlus
4	`exit_status`	`integer(1)` or `NULL`	Exit status of EnergyPlus. `NULL` if terminated or `wait` is `FALSE`
5	`start_time`	`POSIXct(1)`	Start of time of simulation
6	`end_time`	`POSIXct(1)` or `NULL`	End of time of simulation. `NULL` if `wait` is `FALSE`
7	`output_dir`	`character(1)`	Full path of simulation output directory
8	`energyplus`	`character(1)`	Full path of called EnergyPlus executable
9	`stdout`	`character(1)` or `NULL`	Standard output of EnergyPlus during simulation
10	`stderr`	`character(1)` or `NULL`	Standard error of EnergyPlus during simulation
11	`process`	r_process	A process object which called EnergyPlus and ran the simulation

If wait is FALSE, the R process is directly returned. You can get the results by calling result <- proc$get_result() (proc is the returned process). Please note that in this case, result$process will alwasy be NULL. But you can easily assign it by running result$process <- proc

For rum_multi(), if wait is TRUE, a data.table of 12 columns:

No.	Column	Type	Description
1	`index`	`integer`	Index of simulation
2	`status`	`character`	Simulation status
3	`idf`	`character`	Full path of input IDF file
4	`epw`	`character`	Full path of input EPW file. `NA` for design-day-only simulation
5	`version`	`character`	Version of EnergyPlus
6	`exit_status`	`integer`	Exit status of EnergyPlus. `NA` if terminated
7	`start_time`	`POSIXct`	Start of time of simulation
8	`end_time`	`POSIXct`	End of time of simulation.
9	`output_dir`	`character`	Full path of simulation output directory
10	`energyplus`	`character`	Full path of called EnergyPlus executable
11	`stdout`	`list`	Standard output of EnergyPlus during simulation
12	`stderr`	`list`	Standard error of EnergyPlus during simulation

For column status, there are 4 possible values:

"completed": the simulation job is completed successfully
"failed": the simulation job ended with error
"terminated": the simulation job started but was terminated
"cancelled": the simulation job was cancelled, i.e. did not start at all

For run_multi(), if wait is FALSE, a r_process object of background R process which handles all simulation jobs is returned. You can check if the jobs are completed using $is_alive() and get the final data.table using $get_result() method.

Details

run_idf() is a wrapper of EnergyPlus itself, plus various pre-processors and post-processors which enables to run EnergyPlus model with different options.

run_multi() provides the functionality of running multiple models in parallel.

It is suggested to run simulations using EplusJob class and EplusGroupJob class, which provide much more detailed controls on the simulation and also methods to extract simulation outputs.

Note

If your input model has external file dependencies, e.g. FMU, schedule files, etc. run_idf() and run_multi() will not work if the output directory is different that where the input mode lives. If this is the case, parse the model using read_idf() and use Idf$run() or eplus_job() instead. They are able to automatically change the paths of external files to absolute paths or copy them into the output directory, based on your choice.

References

Running EnergyPlus from Command Line (EnergyPlus GitHub Repository)

Author

Hongyuan Jia

Examples

if (FALSE) {
idf_path <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr")

if (is_avail_eplus("8.8")) {
    # run a single model
    epw_path <- file.path(
        eplus_config("8.8")$dir,
        "WeatherData",
        "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
    )

    run_idf(idf_path, epw_path, output_dir = tempdir())

    # run multiple model in parallel
    idf_paths <- file.path(eplus_config("8.8")$dir, "ExampleFiles",
        c("1ZoneUncontrolled.idf", "1ZoneUncontrolledFourAlgorithms.idf")
    )
    epw_paths <- rep(epw_path, times = 2L)
    output_dirs <- file.path(tempdir(), tools::file_path_sans_ext(basename(idf_paths)))
    run_multi(idf_paths, epw_paths, output_dir = output_dirs)
}
}