R: Run EnergyPlus Simulation and Collect Outputs

EplusJob {eplusr}

R Documentation

Run EnergyPlus Simulation and Collect Outputs

Description

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

eplus_job() takes an IDF and EPW as input, and returns an EplusJob object for running EnergyPlus simulation and collecting outputs.

Usage

eplus_job(idf, epw)

Arguments

`idf`	A path to an local EnergyPlus IDF file or an `Idf` object.
`epw`	A path to an local 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.

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. An object in Output:SQLite with ⁠Option Type⁠ value of SimpleAndTabular will be automatically created if it does not exists, to ensure that the output collection functionality works successfully.

In order to make sure .rdd (Report Data Dictionary) and .mdd (Meter Data Dictionary) files are created during simulation, an object in Output:VariableDictionary class with ⁠Key Field⁠ value being IDF will be automatically created if it does not exists.

Value

An EplusJob object.

Methods

Public methods

EplusJob$new()
EplusJob$version()
EplusJob$path()
EplusJob$run()
EplusJob$kill()
EplusJob$status()
EplusJob$errors()
EplusJob$output_dir()
EplusJob$list_files()
EplusJob$locate_output()
EplusJob$read_rdd()
EplusJob$read_mdd()
EplusJob$list_table()
EplusJob$read_table()
EplusJob$report_data_dict()
EplusJob$report_data()
EplusJob$tabular_data()
EplusJob$print()

Method `new()`

Create an EplusJob object

Usage

EplusJob$new(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.

Returns

An EplusJob object.

Examples

\dontrun{
if (is_avail_eplus("8.8")) {
    name_idf <- "1ZoneUncontrolled.idf"
    name_epw <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

    path_idf <- path_eplus_example("8.8", name_idf)
    path_epw <- path_eplus_weather("8.8", name_epw)

    # create from local files
    job <- eplus_job(path_idf, path_epw)

    # create from an Idf and an Epw object
    job <- eplus_job(read_idf(path_idf), read_epw(path_epw))
}
}

Method `version()`

Get the version of IDF in current job

Usage

EplusJob$version()

Details

⁠$version()⁠ returns the version of IDF that current EplusJob uses.

Returns

A base::numeric_version() object.

Examples

\dontrun{
job$version()
}

Method `path()`

Get the paths of file that current EpwSql uses

Usage

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

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. If epw is NULL, NA is returned for EPW path. Default: "all".

Details

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

Returns

A character vector.

Examples

\dontrun{
job$path()
job$path("idf")
job$path("epw")
}

Method `run()`

Run simulationA

Usage

EplusJob$run(
  epw,
  dir = NULL,
  wait = TRUE,
  force = FALSE,
  echo = wait,
  copy_external = FALSE
)

Arguments

epw: A path to an .epw file or an Epw object. epw can also be NULL which will force design-day-only simulation. Note this needs EnergyPlus v8.3 and later, and at least one Sizing:DesignDay object exists in the Idf. If not given, the epw input used when creating this EplusJob object will be used.
dir: The directory to save the simulation results. If NULL, the input idf folder will be used. Default: NULL.
wait: If TRUE, R will hang on and wait for the simulation to complete. EnergyPlus standard output (stdout) and error (stderr) is printed to R console. If FALSE, simulation will be run in a background process. Default: TRUE.
force: Only applicable when the last job 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.
echo: Only applicable when wait is TRUE. Whether to show standard output and error from EnergyPlus. Default: same as wait.
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. This ensures that the output directory will have all files needed for the model to run. Default is FALSE.
readvars: If TRUE, the ReadVarESO post-processor will run to generate CSV files from the ESO output. Since those CSV files are never used when extracting simulation data in eplusr, setting it to FALSE can speed up the simulation if there are hundreds of output variables or meters. Default: TRUE.

Details

⁠$run()⁠ runs the simulation using input IDF and EPW file. If wait is FALSE, the job is run in the background. You can get updated job status by just printing the EplusJob object.

Parameter epw can be used to reset the EPW file to use for simulation. If not given, the epw input used when creating this EplusJob object will be used.

Returns

The EplusJob object itself, invisibly.

Examples

\dontrun{
# only run design day
job$run(NULL)

# specify output directory
job$run(dir = tempdir())

# run in the background
job$run(wait = TRUE)
# see job status
job$status()

# force to kill background job before running the new one
job$run(force = TRUE)

# do not show anything in the console
job$run(echo = FALSE)

# copy external files used in the model to simulation output directory
job$run(copy_external = TRUE)
}

Method `kill()`

Kill current running job

Usage

EplusJob$kill()

Details

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

Returns

A single logical value of TRUE or FALSE, invisibly.

Examples

\dontrun{
job$kill()
}

Method `status()`

Get the job status

Usage

EplusJob$status()

Details

⁠$status()⁠ returns a named list of values that 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.

Returns

A named list of 5 elements.

Examples

\dontrun{
job$status()
}

Method `errors()`

Read simulation errors

Usage

EplusJob$errors(info = FALSE)

Arguments

info: If FALSE, only warnings and errors are printed. Default: FALSE.

Details

$errors() returns an ErrFile object which contains all contents of the simulation error file (.err). If info is FALSE, only warnings and errors are printed.

Returns

An ErrFile object.

Examples

\dontrun{
job$errors()

# show all information
job$errors(info = TRUE)
}

Method `output_dir()`

Get simulation output directory

Usage

EplusJob$output_dir(open = FALSE)

Arguments

open: If TRUE, the output directory will be opened.

Details

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

Examples

\dontrun{
job$output_dir()

# Below will open output directory
# job$output_dir(open = TRUE)
}

Method `list_files()`

List all output files in current simulation

Usage

EplusJob$list_files(simplify = FALSE, full = FALSE)

Arguments

simplify: If TRUE, a character vector of EnergyPlus input and output file names in the output directory is given. If FALSE, a full named list of all possible input and output types is given. NA is returned if no input or output files are found for that type. Default: FALSE.
full: If TRUE, the full file paths in the output directory are returned. Otherwise, only the file names are returned. Default: FALSE.

Details

⁠$list_files()⁠ returns all input and output files for current EnergyPlus simulation.

Description of all possible outputs from EnergyPlus can be found in EnergyPlus documentation "Output Details and Examples".

Below gives a brief summary on the meaning of elements in the returned list.

#	Element	Description
1	`ads`	EnergyPlus AirflowNetwork related output
2	`audit`	EnergyPlus inputs echo
3	`bnd`	EnergyPlus branch node details
4	`bsmt_audit`	Basement input Echo
5	`bsmt_csv`	Basement CSV output
6	`bsmt_idf`	Basement IDF output
7	`bsmt_out`	Basement Output
8	`cbor`	Energyplus CBOR binary output introduced since v9.5
9	`dbg`	Energyplus debug output
10	`delight`	EnergyPlus DElight simulation inputs and outputs
11	`dfs`	EnergyPlus daylighting factor for exterior windows
12	`dxf`	EnergyPlus surface drawing output
13	`edd`	EnergyPlus EMS report
14	`eio`	EnergyPlus standard and optional reports
15	`end`	EnergyPlus simulation status in one line
16	`epjson`	EnergyPlus epJSON input converted from IDF
17	`epmdet`	EPMacro inputs echo
18	`epmidf`	EPMacro IDF output
19	`epw`	EnergyPlus Weather File input
20	`err`	EnergyPlus error summarry
21	`eso`	EnergyPlus standard output
22	`experr`	ExpandObjects error summary
23	`expidf`	ExpandObjects IDF output
24	`glhe`	EnergyPlus ground heat exchange file
25	`idf`	EnergyPlus IDF input
26	`imf`	EPMacro IMF input
27	`iperr`	convertESOMTR error summary
28	`ipeso`	convertESOMTR standard output in IP units
29	`ipmtr`	convertESOMTR meter output in IP units
30	`json`	EnergyPlus JSON time series output introduced since v9.5
31	`log`	EnergyPlus log output
32	`map`	EnergyPlus daylighting intensity map output
33	`mdd`	EnergyPlus meter list
34	`meter`	EnergyPlus meter CSV output
35	`msgpack`	EnergyPlus MessagePack binary output introduced since v9.5
36	`mtd`	EnergyPlus meter details
37	`mtr`	EnergyPlus meter output
38	`perflog`	EnergyPlus log for `PerformancePrecisionTradeoffs
39	`rdd`	EnergyPlus report variable names
40	`rvaudit`	ReadVarsESO input echo
41	`sci`	EnergyPlus cost benefit calculation information
42	`screen`	EnergyPlus window scrren transmittance map output
43	`shading`	EnergyPlus surface shading CSV output
44	`shd`	EnergyPlus surface shading combination report
45	`slab_ger`	Slab error summary
46	`slab_gtp`	Slab ground temperature output
47	`slab_out`	Slab IDF output
48	`sln`	EnergyPlus `⁠Output:Surfaces:List, Lines⁠` output
49	`sqlite`	EnergyPlus SQLite output
50	`sqlite_err`	EnergyPlus SQLite error summary
51	`ssz`	EnergyPlus system sizing outputs in CSV, TAB or TXT format
52	`svg`	HVAC-Diagram HVAC diagram output
53	`table`	EnergyPlus tabular outputs in CSV, TAB, TXT, HTM, or XML format
54	`variable`	EnergyPlus report variable CSV output
55	`wrl`	EnergyPlus `⁠Output:Surfaces:List, VRML⁠` output
56	`zsz`	EnergyPlus system sizing outputs in CSV, TAB or TXT format
57	`resource`	External file resources used for the simulation, e.g. `Schedule:File`

Returns

If FALSE, a character vector. Otherwise, a named list.

Examples

\dontrun{
# list all files in the output directory
job$list_files(simplify = TRUE)

# get a full list of all possible inputs and outputs even though they
# may not exist for current simulation
job$list_files()

# return the full paths instead of just file names
job$locate_output(full = TRUE)
}

Method `locate_output()`

Get path of output file

Usage

EplusJob$locate_output(suffix = ".err", strict = TRUE)

Arguments

suffix: A string that indicates the file extension 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.

Details

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

Examples

\dontrun{
# get the file path of the error file
job$locate_output(".err", strict = FALSE)

# can use to detect if certain output file exists
job$locate_output(".expidf", strict = TRUE)
}

Method `read_rdd()`

Read Report Data Dictionary (RDD) file

Usage

EplusJob$read_rdd()

Details

⁠$read_rdd()⁠ return the core data of Report Data Dictionary (RDD) file. For details, please see read_rdd().

Returns

An RddFile object.

Examples

\dontrun{
job$read_rdd()
}

Method `read_mdd()`

Read Report Data Dictionary (RDD) file

Usage

EplusJob$read_mdd()

Details

⁠$read_mdd()⁠ return the core data of Meter Data Dictionary (MDD) file. For details, please see read_mdd().

Returns

An MddFile object.

Examples

\dontrun{
job$read_mdd()
}

Method `list_table()`

List all table names in EnergyPlus SQL output

Usage

EplusJob$list_table()

Details

⁠$list_table()⁠ returns all available table and view names in the EnergyPlus SQLite file.

Returns

A character vector

Examples

\dontrun{
job$list_table()
}

Method `read_table()`

Read a single table from EnergyPlus SQL output

Usage

EplusJob$read_table(name)

Arguments

name: A single string specifying the name of table to read.

Details

⁠$read_table()⁠ takes a valid table name of those from $list_table() and returns that table data in a data.table::data.table() format.

Returns

A data.table::data.table().

Examples

\dontrun{
# read a specific table
job$read_table("Zones")
}

Method `report_data_dict()`

Read report data dictionary from EnergyPlus SQL output

Usage

EplusJob$report_data_dict()

Details

⁠$report_data_dict()⁠ returns a data.table::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.

Returns

A data.table::data.table() of 10 columns:

report_data_dictionary_index: The integer used to link the dictionary data to the variable data. Mainly useful when joining different tables
is_meter: Whether report data is a meter data. Possible values: 0 and 1
timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠
key_value: Key name of the data
name: Actual report data name
reporting_frequency: Data reporting frequency
schedule_name: Name the the schedule that controls reporting frequency.
units: The data units

Examples

\dontrun{
job$report_data_dict()
}

Method `report_data()`

Read report data

Usage

EplusJob$report_data(
  key_value = NULL,
  name = NULL,
  year = NULL,
  tz = "UTC",
  case = "auto",
  all = FALSE,
  wide = FALSE,
  period = NULL,
  month = NULL,
  day = NULL,
  hour = NULL,
  minute = NULL,
  interval = NULL,
  simulation_days = NULL,
  day_type = NULL,
  environment_name = NULL
)

Arguments

key_value

A character vector to identify key values of the data. If NULL, all keys of that variable will be returned. key_value can also be data.frame that contains key_value and name columns. In this case, name argument in ⁠$report_data()⁠ is ignored. All available key_value for current simulation output can be obtained using $report_data_dict(). Default: NULL.

name

A character vector to identify names of the data. If NULL, all names of that variable will be returned. If key_value is a data.frame, name is ignored. All available name for current simulation output can be obtained using $report_data_dict(). Default: NULL.

year

Year of the date time in column datetime. If NULL, it will calculate a year value that meets the start day of week restriction for each environment. Default: NULL.

tz

Time zone of date time in column datetime. Default: "UTC".

case

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

all

If TRUE, extra columns are also included in the returned data.table::data.table().

wide

If TRUE, the output is formatted in the same way as standard EnergyPlus csv output file.

period

A Date or POSIXt vector used to specify which time period to return. The year value does not matter and only month, day, hour and minute value will be used when subsetting. If NULL, all time period of data is returned. Default: NULL.

month, day, hour, minute

Each is an integer vector for month, day, hour, minute subsetting of datetime column when querying on the SQL database. If NULL, no subsetting is performed on those components. All possible month, day, hour and minute can be obtained using $read_table("Time"). Default: NULL.

interval

An integer vector used to specify which interval length of report to extract. If NULL, all interval will be used. Default: NULL.

simulation_days

An integer vector to specify which simulation day data to extract. Note that this number resets after warmup and at the beginning of an environment period. All possible simulation_days can be obtained using $read_table("Time"). If NULL, all simulation days will be used. Default: NULL.

day_type

A character vector to specify which day type of data to extract. All possible day types are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Holiday, SummerDesignDay, WinterDesignDay, CustomDay1, and CustomDay2. All possible values for current simulation output can be obtained using $read_table("Time").

environment_name

A character vector to specify which environment data to extract. If NULL, all environment data are returned. Default: NULL. All possible environment_name for current simulation output can be obtained using:

$read_table("EnvironmentPeriods")

Details

⁠$report_data()⁠ extracts the report data in a data.table::data.table() using key values, variable names and other specifications.

⁠$report_data()⁠ can also directly take all or subset output from ⁠$report_data_dict()⁠ as input, and extract all data specified.

The returned column numbers varies depending on all argument.

all is FALSE, the returned data.table::data.table() has 6 columns:
- case: Simulation case specified using case argument
- datetime: The date time of simulation result
- key_value: Key name of the data
- name: Actual report data name
- units: The data units
- value: The data value
all is TRUE, besides columns described above, extra columns are also included:
- month: The month of reported date time
- day: The day of month of reported date time
- hour: The hour of reported date time
- minute: The minute of reported date time
- dst: Daylight saving time indicator. Possible values: 0 and 1
- interval: Length of reporting interval
- simulation_days: Day of simulation
- day_type: The type of day, e.g. Monday, Tuesday and etc.
- environment_period_index: The indices of environment.
- environment_name: A text string identifying the environment.
- is_meter: Whether report data is a meter data. Possible values: 0 and 1
- type: Nature of data type with respect to state. Possible values: Sum and Avg
- index_group: The report group, e.g. Zone, System
- timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠
- reporting_frequency: The reporting frequency of the variable, e.g. ⁠HVAC System Timestep⁠, ⁠Zone Timestep⁠.
- schedule_name: Name of the the schedule that controls reporting frequency.

With the datetime column, it is quite straightforward to apply time-series analysis on the simulation output. However, another painful thing is that every simulation run period has its own ⁠Day of Week for Start Day⁠. Randomly setting the year may result in a date time series that does not have the same start day of week as specified in the RunPeriod objects.

eplusr provides a simple solution for this. By setting year to NULL, which is the default behavior, eplusr will calculate a year value (from year 2017 backwards) for each run period that compliances with the start day of week restriction.

It is worth noting that EnergyPlus uses 24-hour clock system where 24 is only used to denote midnight at the end of a calendar day. In EnergyPlus output, "00:24:00" with a time interval being 15 mins represents a time period from "00:23:45" to "00:24:00", and similarly "00:15:00" represents a time period from "00:24:00" to "00:15:00" of the next day. This means that if current day is Friday, day of week rule applied in schedule time period "00:23:45" to "00:24:00" (presented as "00:24:00" in the output) is also Friday, but not Saturday. However, if you try to get the day of week of time "00:24:00" in R, you will get Saturday, but not Friday. This introduces inconsistency and may cause problems when doing data analysis considering day of week value.

With wide equals TRUE, ⁠$report_data()⁠ will format the simulation output in the same way as standard EnergyPlus csv output file. Sometimes this can be useful as there may be existing tools/workflows that depend on this format. When both wide and all are TRUE, columns of runperiod environment names and date time components are also returned, including: ⁠environment_period_index", "environment_name⁠, simulation_days, datetime, month, day, hour, minute, day_type.

For convenience, input character arguments matching in ⁠$report_data()⁠ are case-insensitive.

Returns

A data.table::data.table().

Examples

\dontrun{
# read all report data
job$report_data()

# specify output variables using report data dictionary
dict <- job$report_data_dict()
job$report_data(dict[units == "C"])

# specify output variables using 'key_value' and 'name'
job$report_data("environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
job$report_data(dict[1], year = 2020, tz = "Etc/GMT+8")

# explicitly specify case name
job$report_data(dict[1], case = "example")

# get all possible columns
job$report_data(dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
job$report_data(dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
job$report_data(dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
job$report_data(dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)

# only get specified run period data
job$read_table("EnvironmentPeriods") # possible environment name
job$report_data(dict[1], environment_name = "San Francisco Intl Ap CA USA TMY3 WMO#=724940")
# can also be done using 'environment_period_index' column
job$report_data(dict[1], all = TRUE)[environment_period_index == 3L]
}

Method `tabular_data()`

Read tabular data

Usage

EplusJob$tabular_data(
  report_name = NULL,
  report_for = NULL,
  table_name = NULL,
  column_name = NULL,
  row_name = NULL,
  wide = FALSE,
  string_value = !wide
)

Arguments

report_name, report_for, table_name, column_name, row_name

Each is a character vector for subsetting when querying the SQL database. For the meaning of each argument, please see the description above.

wide

If TRUE, each table will be converted into the similar format as it is shown in EnergyPlus HTML output file. Default: FALSE.

string_value

Only applicable when wide is TRUE. If string_value is FALSE, instead of keeping all values as characters, values in possible numeric columns are converted into numbers. Default: the opposite of wide. Possible numeric columns indicate column that:

columns that have associated units
columns that contents numbers

Details

⁠$tabular_data()⁠ extracts the tabular data in a data.table::data.table() using report, table, column and row name specifications. The returned data.table::data.table() has 9 columns:

case: Simulation case specified using case argument
index: Tabular data index
report_name: The name of the report that the record belongs to
report_for: The For text that is associated with the record
table_name: The name of the table that the record belongs to
column_name: The name of the column that the record belongs to
row_name: The name of the row that the record belongs to
units: The units of the record
value: The value of the record in string format by default

For convenience, input character arguments matching in ⁠$tabular_data()⁠ are case-insensitive.

Returns

A data.table::data.table() with 8 columns (when wide is FALSE) or a named list of data.table::data.table()s where the names are the combination of report_name, report_for and table_name.

Examples

\dontrun{
# read all tabular data
job$tabular_data()

# explicitly specify data you want
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))
}

Method `print()`

Print EplusSql object

Usage

EplusJob$print()

Details

⁠$print()⁠ shows the core information of this EplusJob object, 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.

Returns

The EplusSql object itself, invisibly.

Examples

\dontrun{
job$print()
}

Author(s)

Hongyuan Jia

Examples


## ------------------------------------------------
## Method `EplusJob$new`
## ------------------------------------------------

## Not run: 
if (is_avail_eplus("8.8")) {
    name_idf <- "1ZoneUncontrolled.idf"
    name_epw <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

    path_idf <- path_eplus_example("8.8", name_idf)
    path_epw <- path_eplus_weather("8.8", name_epw)

    # create from local files
    job <- eplus_job(path_idf, path_epw)

    # create from an Idf and an Epw object
    job <- eplus_job(read_idf(path_idf), read_epw(path_epw))
}

## End(Not run)

## ------------------------------------------------
## Method `EplusJob$version`
## ------------------------------------------------

## Not run: 
job$version()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$path`
## ------------------------------------------------

## Not run: 
job$path()
job$path("idf")
job$path("epw")

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$run`
## ------------------------------------------------

## Not run: 
# only run design day
job$run(NULL)

# specify output directory
job$run(dir = tempdir())

# run in the background
job$run(wait = TRUE)
# see job status
job$status()

# force to kill background job before running the new one
job$run(force = TRUE)

# do not show anything in the console
job$run(echo = FALSE)

# copy external files used in the model to simulation output directory
job$run(copy_external = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$kill`
## ------------------------------------------------

## Not run: 
job$kill()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$status`
## ------------------------------------------------

## Not run: 
job$status()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$errors`
## ------------------------------------------------

## Not run: 
job$errors()

# show all information
job$errors(info = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$output_dir`
## ------------------------------------------------

## Not run: 
job$output_dir()

# Below will open output directory
# job$output_dir(open = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$list_files`
## ------------------------------------------------

## Not run: 
# list all files in the output directory
job$list_files(simplify = TRUE)

# get a full list of all possible inputs and outputs even though they
# may not exist for current simulation
job$list_files()

# return the full paths instead of just file names
job$locate_output(full = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$locate_output`
## ------------------------------------------------

## Not run: 
# get the file path of the error file
job$locate_output(".err", strict = FALSE)

# can use to detect if certain output file exists
job$locate_output(".expidf", strict = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$read_rdd`
## ------------------------------------------------

## Not run: 
job$read_rdd()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$read_mdd`
## ------------------------------------------------

## Not run: 
job$read_mdd()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$list_table`
## ------------------------------------------------

## Not run: 
job$list_table()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$read_table`
## ------------------------------------------------

## Not run: 
# read a specific table
job$read_table("Zones")

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$report_data_dict`
## ------------------------------------------------

## Not run: 
job$report_data_dict()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$report_data`
## ------------------------------------------------

## Not run: 
# read all report data
job$report_data()

# specify output variables using report data dictionary
dict <- job$report_data_dict()
job$report_data(dict[units == "C"])

# specify output variables using 'key_value' and 'name'
job$report_data("environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
job$report_data(dict[1], year = 2020, tz = "Etc/GMT+8")

# explicitly specify case name
job$report_data(dict[1], case = "example")

# get all possible columns
job$report_data(dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
job$report_data(dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
job$report_data(dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
job$report_data(dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)

# only get specified run period data
job$read_table("EnvironmentPeriods") # possible environment name
job$report_data(dict[1], environment_name = "San Francisco Intl Ap CA USA TMY3 WMO#=724940")
# can also be done using 'environment_period_index' column
job$report_data(dict[1], all = TRUE)[environment_period_index == 3L]

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$tabular_data`
## ------------------------------------------------

## Not run: 
# read all tabular data
job$tabular_data()

# explicitly specify data you want
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$print`
## ------------------------------------------------

## Not run: 
job$print()

## End(Not run)

[Package eplusr version 0.16.2 Index]

Run EnergyPlus Simulation and Collect Outputs

Description

Usage

Arguments

Details

Value

Methods

Public methods

Method new()

Usage

Arguments

Returns

Examples

Method version()

Usage

Details

Returns

Examples

Method path()

Usage

Arguments

Details

Returns

Examples

Method run()

Usage

Arguments

Details

Returns

Examples

Method kill()

Usage

Details

Returns

Examples

Method status()

Usage

Details

Returns

Examples

Method errors()

Usage

Arguments

Details

Returns

Examples

Method output_dir()

Usage

Arguments

Details

Examples

Method list_files()

Usage

Arguments

Details

Returns

Examples

Method locate_output()

Usage

Arguments

Details

Examples

Method read_rdd()

Usage

Details

Returns

Examples

Method read_mdd()

Usage

Details

Returns

Examples

Method list_table()

Usage

Details

Returns

Examples

Method read_table()

Usage

Arguments

Method `new()`

Method `version()`

Method `path()`

Method `run()`

Method `kill()`

Method `status()`

Method `errors()`

Method `output_dir()`

Method `list_files()`

Method `locate_output()`

Method `read_rdd()`

Method `read_mdd()`

Method `list_table()`

Method `read_table()`

Method `report_data_dict()`

Method `report_data()`

Method `tabular_data()`

Method `print()`