eplusr (version 0.9.4)

run_idf: Run simulations of EnergyPlus models.

Description

run_idf() is a wrapper of EnergyPlus command line interface which enables to run EnergyPlus model with different options.

Usage

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, 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. 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.

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. Default: FALSE.

annual

Force design-day-only simulation. 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 processx::process object is returned. Note that, if FALSE, R is not blocked even when echo is TRUE. Default: TRUE.

echo

Whether to show standard output and error from EnergyPlus command line interface 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

A list for run_idf(). For rum_multi(), a data.table if wait is TRUE or a process if wait is FALSE.

Details

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

later package is used to poll the standard output and error of background EnergyPlus process or background R process that handles parallel simulations. The print interval is set to 0.5 sec.

For run_idf(), a named list will be returned:

• idf: The path of IDF file

• epw: The path of EPW file

• exit_status: The exit code of the process if it has finished and NULL otherwise. Always being NULL if wait is FALSE, but you can manually get the exit code using the process object, i.e. process$get_exit_status() after simulation completed.

• start_time: When the EnergyPlus process started.

• end_time: When the EnergyPlus process stopped. All being NULL if wait is FALSE, but you can manually check EnergyPlus stdout to get the simulation time

• output_dir: The simulation output directory

• energyplus: The path of EnergyPlus executable

• stdout: All standard output from EnergyPlus. Always being NULL if wait is FALSE, but you can manually get all standard output using process$read_all_output_lines().

• stderr: All standard error from EnergyPlus. Always being NULL if wait is FALSE, but you can manually get all standard output using process$read_all_output_lines().

• process: A processx::process object of current EnergyPlus simulation

For run_multi(), if wait is TRUE, a data.table contains all data (excluding process) with same column names as above, and also another two columns:

• index: The index of simulation

• status: The status of simulation status. Should be one of below:

  • "completed": the simulation job is completed. This only indicates that the calling of EnergyPlus was successfully and EnergyPlus was not terminated during simulation. Even "completed" isTRUE, the job can still end with error. Please checkexit_status` to determine whether EnergyPlus ran successfully

  • "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().

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

References

Running EnergyPlus from Command Line (EnergyPlus GitHub Repository)

See Also

EplusJob class and ParametricJob class which provide a more friendly interface to run EnergyPlus simulations and collect outputs.

Examples

# NOT RUN {
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)
}
# }