eplusr (version 0.9.4)

EplusJob: Run EnergyPlus Simulation and Collect Outputs

Description

EplusJob class wraps the EnergyPlus command line interface and provides methods to extract simulation outputs.

NOTE

When using $run() in Idf class, which internally creates an EplusJob object and calls its $run() method, an object in Output:SQLite with Option Type value of SimpleAndTabular will be automatically created if it does not exists.

However, when creating an EplusJob using eplus_job(), the IDF file is not parsed but directly pass its path to EnergyPlus. Thus, that process of handling Output:SQLite class is not performed. If you want to ensure that the output collection functionality in EplusJob class works successfully, it is recommended to first read that IDF file using read_idf() and then use $run() method in Idf class by doing idf$run().

Usage

job$run(wait = TRUE)
job$kill()
job$status()
job$errors(info = FALSE)
job$output_dir(open = FALSE)
job$locate_output(suffix = ".err", strict = TRUE)
job$report_data_dict()
job$report_data(key_value = NULL, name = NULL, year = NULL, tz = "GMT", case = "auto")
job$tabular_data()
job$clone(deep = FALSE)
job$print()

Create

job <- eplus_job(idf, epw)

Arguments

• idf: Path to an local EnergyPlus IDF file or an Idf object.

• epw: Path to an local EnergyPlus EPW file or an Epw object.

Basic info

job$path(type = c("all", "idf", "epw"))

$path() returns the path of IDF or EPW of current job.

Arguments

• type: If "all", both the IDF path and EPW path are returned. If "idf", only IDF path is returned. If "epw", only EPW path is returned. Default: "all".

Run

job$run(wait = TRUE)
job$kill()
job$status()

$run() runs the simulation using input model and weather file. If wait is FALSE, then the job will be run in the background. You can get updated job status by just print the EplusJob object.

$kill() kills the background EnergyPlus process if possible. It only works when simulation runs in non-waiting mode.

$status() returns a named list of values indicates the status of the job:

• run_before: TRUE if the job has been run before. FALSE otherwise.

• alive: TRUE if the simulation is still running in the background. FALSE otherwise.

• terminated: TRUE if the simulation was terminated during last simulation. FALSE otherwise. NA if the job has not been run yet.

• successful: TRUE if last simulation ended successfully. FALSE otherwise. NA if the job has not been run yet.

• changed_after: TRUE if the IDF file has been changed since last simulation. FALSE otherwise. NA if the job has not been run yet.

Arguments

• wait: If TRUE, R will hang on and wait for the simulation to complete. EnergyPlus standard output (stdout) and error (stderr) is printed to the R console. If FALSE, simulation will be run in a background process. Default: TRUE.

Results Extraction

job$output_dir(open = FALSE)
job$locate_output(suffix = ".err", strict = TRUE)
job$report_data_dict()
job$report_data(key_value = NULL, name = NULL, year = NULL, tz = "GMT", case = "auto")
job$tabular_data()

$output_dir() returns the output directory of simulation results.

$locate_output() returns the path of a single output file specified by file suffix.

$report_data_dict() returns a data.table which contains all information about report data. For details on the meaning of each columns, please see "2.20.2.1 ReportDataDictionary Table" in EnergyPlus "Output Details and Examples" documentation.

$report_data() extracts the report data in a data.table using key values and variable names.

$tabular_data() extracts all tabular data in a data.table.

Arguments:

• open: If TRUE, the output directory will be opened. It may only work well on Windows.

• suffix: A string that indicates the file suffix of simulation output. Default: ".err".

• strict: If TRUE, it will check if the simulation was terminated, is still running or the file exists or not. Default: TRUE.

• key_value: A character vector to identify key name of the data. If NULL, all keys of that variable will be returned. Default: NULL.

• name: A character vector to specify the actual data name. If NULL, all variables will be returned. Default: NULL.

• year: The year of the date and time in column DateTime. If NULL, it will be the current year. Default: NULL

• tz: Time zone of date and time in column DateTime. Default: "GMT".

• case: If not NULL, a character column will be added indicates the case of this simulation. If "auto", the name of the IDF file will be used.

Clone

job$clone(deep = FALSE)

$clone() copies and returns the cloned job. Because EplusJob uses R6Class under the hook which has "modify-in-place" semantics, job_2 <- job_1 does not copy job_1 at all but only create a new binding to job_1. Modify job_1 will also affect job_2 as well, as these two are exactly the same thing underneath. In order to create a complete cloned copy, please use $clone(deep = TRUE).

Arguments

• deep: Has to be TRUE if a complete cloned copy is desired.

Printing

job$print()
print(job)

$print() shows the core information of this EplusJob, including the path of model and weather, the version and path of EnergyPlus used to run simulations, and 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.

Details

eplusr uses the EnergyPlus SQL output for extracting simulation outputs. EplusJob has provide some wrappers that do SQL query to get report data results, i.e. results from Output:Variable and Output:Meter*. But for Output:Table results, you have to be familiar with the structure of the EnergyPlus SQL results, especially for table "TabularDataWithStrings". For details, please see "2.20 eplusout.sql", especially "2.20.4.4 TabularData Table" in EnergyPlus "Output Details and Examples" documentation.

See Also

ParametricJob class for EnergyPlus parametric simulations.

Examples

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

    # copy to tempdir
    file.copy(c(idf_path, epw_path), tempdir())

    # create an EplusJob from local an IDF and an EPW file
    job <- eplus_job(file.path(tempdir(), idf_name), file.path(tempdir(), epw_name))

    # get paths of idf and epw
    job$path("all")
    job$path("idf")
    job$path("epw")

    # get current job status
    job$status()

    # check if the job has been run before
    job$status()$run_before

    # run the job in waiting mode
    job$run(wait = TRUE)

    # check the job status again
    job$status()$run_before
    job$status()$successful

    # get output directory
    job$output_dir()

    # open the output directory
    job$output_dir(open = TRUE)

    # check simulation errors
    job$errors()

    # check simulation errors, only including warnings and errors
    job$errors(info = FALSE)

    # get the file path of an output with a given suffix
    job$locate_output(".err")

    # give an error when simulation did not complete successfully or that file
    # does not exist
    job$locate_output(".exe", strict = TRUE)

    # retrieve simulation results will fail if there is no EnergyPlus SQL output.
    job$report_data_dict()

    # instead, using `$run()` method in Idf class, which will add an
    # `Output:SQLite` object automatically
    idf <- read_idf(file.path(tempdir(), idf_name))
    job <- idf$run(file.path(tempdir(), epw_name), dir = NULL)

    # get report data dictionary
    str(job$report_data_dict())

    # extract all report data
    str(job$report_data())

    # extract some report variable
    str(job$report_data(name = "EnergyTransfer:Building", case = NULL))

    # add a "Case" column in the returned data.table
    str(job$report_data(name = "EnergyTransfer:Building", case = "Test"))

    # change the format of datetime column in the returned data.table
    str(job$report_data(name = "EnergyTransfer:Building", year = 2016L, tz = Sys.timezone()))

    # get all tabular data
    str(job$tabular_data())
}
# }