EplusJob: Run EnergyPlus Simulation and Collect Outputs

Description Details NOTE Usage Create Basic info Run Results Extraction Clone Printing Author(s) See Also Examples

Description

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

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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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

1
job <- eplus_job(idf, epw)

Arguments

Basic info

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

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

Arguments

Run

1
2
3
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:

Arguments

Results Extraction

1
2
3
4
5
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:

Clone

1
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

Printing

1
2
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.

Author(s)

Hongyuan Jia

See Also

ParametricJob class for EnergyPlus parametric simulations.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
## 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())
}

## End(Not run)

hongyuanjia/eplusr documentation built on Oct. 14, 2018, 10:59 a.m.