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.

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.

Value

An EplusJob object.

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.

See also

ParametricJob class for EnergyPlus parametric simulations.

param_job() for creating an EnergyPlus parametric job.

Author

Hongyuan Jia

Methods


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 simulation

Usage

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

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)

# run simulation without generating CSV files from ESO output
job$run(epw, dir = tempdir(), readvars = FALSE)
}


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.

#ElementDescription
1adsEnergyPlus AirflowNetwork related output
2auditEnergyPlus inputs echo
3bndEnergyPlus branch node details
4bsmt_auditBasement input Echo
5bsmt_csvBasement CSV output
6bsmt_idfBasement IDF output
7bsmt_outBasement Output
8cborEnergyplus CBOR binary output introduced since v9.5
9dbgEnergyplus debug output
10delightEnergyPlus DElight simulation inputs and outputs
11dfsEnergyPlus daylighting factor for exterior windows
12dxfEnergyPlus surface drawing output
13eddEnergyPlus EMS report
14eioEnergyPlus standard and optional reports
15endEnergyPlus simulation status in one line
16epjsonEnergyPlus epJSON input converted from IDF
17epmdetEPMacro inputs echo
18epmidfEPMacro IDF output
19epwEnergyPlus Weather File input
20errEnergyPlus error summary
21esoEnergyPlus standard output
22experrExpandObjects error summary
23expidfExpandObjects IDF output
24glheEnergyPlus ground heat exchange file
25idfEnergyPlus IDF input
26imfEPMacro IMF input
27iperrconvertESOMTR error summary
28ipesoconvertESOMTR standard output in IP units
29ipmtrconvertESOMTR meter output in IP units
30jsonEnergyPlus JSON time series output introduced since v9.5
31logEnergyPlus log output
32mapEnergyPlus daylighting intensity map output
33mddEnergyPlus meter list
34meterEnergyPlus meter CSV output
35msgpackEnergyPlus MessagePack binary output introduced since v9.5
36mtdEnergyPlus meter details
37mtrEnergyPlus meter output
38perflogEnergyPlus log for `PerformancePrecisionTradeoffs
39rddEnergyPlus report variable names
40rvauditReadVarsESO input echo
41sciEnergyPlus cost benefit calculation information
42screenEnergyPlus window screen transmittance map output
43shadingEnergyPlus surface shading CSV output
44shdEnergyPlus surface shading combination report
45slab_gerSlab error summary
46slab_gtpSlab ground temperature output
47slab_outSlab IDF output
48slnEnergyPlus Output:Surfaces:List, Lines output
49sqliteEnergyPlus SQLite output
50sqlite_errEnergyPlus SQLite error summary
51sszEnergyPlus system sizing outputs in CSV, TAB or TXT format
52svgHVAC-Diagram HVAC diagram output
53tableEnergyPlus tabular outputs in CSV, TAB, TXT, HTM, or XML format
54variableEnergyPlus report variable CSV output
55wrlEnergyPlus Output:Surfaces:List, VRML output
56zszEnergyPlus system sizing outputs in CSV, TAB or TXT format
57resourceExternal 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.

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.

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()
}

Examples


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

if (FALSE) { # \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 `EplusJob$version`
## ------------------------------------------------

if (FALSE) { # \dontrun{
job$version()
} # }


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

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


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

if (FALSE) { # \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)

# run simulation without generating CSV files from ESO output
job$run(epw, dir = tempdir(), readvars = FALSE)
} # }


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

if (FALSE) { # \dontrun{
job$kill()
} # }


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

if (FALSE) { # \dontrun{
job$status()
} # }


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

if (FALSE) { # \dontrun{
job$errors()

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


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

if (FALSE) { # \dontrun{
job$output_dir()

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


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

if (FALSE) { # \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 `EplusJob$locate_output`
## ------------------------------------------------

if (FALSE) { # \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 `EplusJob$read_rdd`
## ------------------------------------------------

if (FALSE) { # \dontrun{
job$read_rdd()
} # }


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

if (FALSE) { # \dontrun{
job$read_mdd()
} # }


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

if (FALSE) { # \dontrun{
job$list_table()
} # }


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

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


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

if (FALSE) { # \dontrun{
job$report_data_dict()
} # }


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

if (FALSE) { # \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 `EplusJob$tabular_data`
## ------------------------------------------------

if (FALSE) { # \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 `EplusJob$print`
## ------------------------------------------------

if (FALSE) { # \dontrun{
job$print()
} # }