Create and Run Parametric Analysis, and Collect Results

EplusGroupJob class is a wrapper of run_multi() and provides an interface to group multiple EnergyPlus simulations together for running and collecting outputs.

group_job() takes IDFs and EPWs as input and returns a EplusGroupJob.

group_job(idfs, epws)

Arguments

idfs: Paths to EnergyPlus IDF files or a list of IDF files and Idf objects.
epws: Paths to EnergyPlus EPW files or a list of EPW files and Epw objects. Each element in the list can 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 that Idf. If epws is NULL, design-day-only simulation will be conducted for all input models.

Value

A EplusGroupJob object.

Author

Hongyuan Jia

Methods

Public methods

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

Method `new()`

Create an EplusGroupJob object

Usage

EplusGroupJob$new(idfs, epws)

Arguments

idfs: Paths to EnergyPlus IDF files or a list of IDF files and Idf objects. If only one IDF supplied, it will be used for simulations with all EPWs.
epws: Paths to EnergyPlus EPW files or a list of EPW files and Epw objects. Each element in the list can be NULL, which will force design-day-only simulation. Note this needs at least one Sizing:DesignDay object exists in that Idf. If epws is NULL, design-day-only simulation will be conducted for all input models. If only one EPW supplied, it will be used for simulations with all IDFs.

Returns

An EplusGroupJob object.

Examples

\dontrun{
if (is_avail_eplus(8.8)) {
    dir <- eplus_config(8.8)$dir
    path_idfs <- list.files(file.path(dir, "ExampleFiles"), "\\.idf",
        full.names = TRUE)[1:5]
    path_epws <- list.files(file.path(dir, "WeatherData"), "\\.epw",
        full.names = TRUE)[1:5]

    # create from local files
    group <- group_job(path_idfs, path_epws)

    # create from Idfs and Epws object
    group_job(lapply(path_idfs, read_idf), lapply(path_epws, read_epw))
}
}

Method `run()`

Run grouped simulations

Usage

EplusGroupJob$run(
  dir = NULL,
  wait = TRUE,
  force = FALSE,
  copy_external = FALSE,
  echo = wait,
  separate = TRUE,
  readvars = TRUE
)

Arguments

dir: The parent output directory for specified simulations. Outputs of each simulation are placed in a separate folder under the parent directory.
wait: If TRUE, R will hang on and wait all EnergyPlus simulations finish. If FALSE, all EnergyPlus simulations are run in the background. Default: TRUE.
force: Only applicable when the last simulation 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.
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.
echo: Only applicable when wait is TRUE. Whether to simulation status. Default: same as wait.
separate: If TRUE, all models are saved in a separate folder with each model's name under dir when simulation. If FALSE, all models are saved in dir when simulation. Default: TRUE.
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 all grouped simulations in parallel. The number of parallel EnergyPlus process can be controlled by eplusr_option("num_parallel"). If wait is FALSE, then the job will be run in the background. You can get updated job status by just printing the EplusGroupJob object.

Returns

The EplusGroupJob object itself, invisibly.

Examples

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

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

# specify output directory
group$run(tempdir(), echo = FALSE)

# run in the background
group$run(wait = TRUE, echo = FALSE)
# see group job status
group$status()

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

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

Method `kill()`

Kill current running jobs

Usage

EplusGroupJob$kill()

Details

$kill() kills all background EnergyPlus processes that are current running if possible. It only works when simulations run in non-waiting mode.

Returns

A single logical value of TRUE or FALSE, invisibly.

Examples

\dontrun{
group$kill()
}

Method `status()`

Get the group job status

Usage

EplusGroupJob$status()

Details

$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 job is still running in the background. FALSE otherwise.
terminated: TRUE if the job was terminated during last simulation. FALSE otherwise. NA if the job has not been run yet.
successful: TRUE if all simulations ended successfully. FALSE if there is any simulation failed. NA if the job has not been run yet.
changed_after: TRUE if the models has been modified since last simulation. FALSE otherwise.
job_status: A data.table::data.table() contains meta data for each simulation job. For details, please see run_multi(). If the job has not been run before, a data.table::data.table() with 4 columns is returned:
- index: The index of simulation
- status: The status of simulation. As the simulation has not been run, status will always be "idle".
- idf: The path of input IDF file.
- epw: The path of input EPW file. If not provided, NA will be assigned.

Returns

A named list of 6 elements.

Examples

\dontrun{
group$status()
}

Method `errors()`

Read group simulation errors

Usage

EplusGroupJob$errors(which = NULL, info = FALSE)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.
info: If FALSE, only warnings and errors are printed. Default: FALSE.

Details

$errors() returns a list of ErrFile objects which contain all contents of the simulation error files (.err). If info is FALSE, only warnings and errors are printed.

Returns

A list of ErrFile objects.

Examples

\dontrun{
group$errors()

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

Method `output_dir()`

Get simulation output directory

Usage

EplusGroupJob$output_dir(which = NULL)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.

Details

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

Returns

A character vector.

Examples

\dontrun{
# get output directories of all simulations
group$output_dir()

# get output directories of specified simulations
group$output_dir(c(1, 4))
}

Method `list_files()`

List all output files in simulations

Usage

EplusGroupJob$list_files(which = NULL, simplify = FALSE, full = FALSE)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.
simplify: If TRUE, a list of character vectors of EnergyPlus input and output file names in the output directory for each simulation is given. If FALSE, a data.table giving 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 the grouped EnergyPlus simulations.

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 summary
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 screen 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 simplify is TRUE, a list. Otherwise, a data.table of 3 columns:

index: Integer type. Simulation indices.
type: Character type. Input or output types. See table above for the meaning
file: List type. File names if full is FALSE. Full file paths if full is TRUE

Examples

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

# get a data.table that contains a full list of all possible inputs
# and outputs even though they may not exist for current simulation
group$list_files()

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

Method `locate_output()`

Get paths of output file

Usage

EplusGroupJob$locate_output(which = NULL, suffix = ".err", strict = TRUE)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.
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 of specified simulations.

Returns

A character vector.

Examples

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

# can detect if certain output file exists
group$locate_output(c(1, 4), ".expidf", strict = TRUE)
}

Method `list_table()`

List all table names in EnergyPlus SQL outputs

Usage

EplusGroupJob$list_table(which = NULL)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.

Details

$list_table() returns a list of character vectors that contain all available table and view names in the EnergyPlus SQLite files for group simulations. The list is named using IDF names.

Returns

A named list of character vectors.

Examples

\dontrun{
group$list_table(c(1, 4))
}

Method `read_table()`

Read the same table from EnergyPlus SQL outputs

Usage

EplusGroupJob$read_table(which = NULL, name)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.
name: A single string specifying the name of table to read.

Details

$read_table() takes a simulation index and a valid table name of those from $list_table() and returns that table data in a data.table::data.table() format. The two column will always be index and case which can be used to distinguish output from different simulations. index contains the indices of simulated models and case contains the model names without extensions.

Returns

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

Examples

\dontrun{
# read a specific table
group$read_table(c(1, 4), "Zones")
}

Method `read_rdd()`

Read Report Data Dictionary (RDD) files

Usage

EplusGroupJob$read_rdd(which = NULL)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.

Details

$read_rdd() return the core data of Report Data Dictionary (RDD) files. For details, please see read_rdd(). The two column will always be index and case which can be used to distinguish output from different simulations. index contains the indices of simulated models and case contains the model names without extensions.

Returns

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

Examples

\dontrun{
group$read_rdd(c(1, 4))
}

Method `read_mdd()`

Read Meter Data Dictionary (MDD) files

Usage

EplusGroupJob$read_mdd(which = NULL)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.

Details

$read_mdd() return the core data of Meter Data Dictionary (MDD) files. For details, please see read_mdd(). The two column will always be index and case which can be used to distinguish output from different simulations. index contains the indices of simulated models and case contains the model names without extensions.

Returns

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

Examples

\dontrun{
group$read_mdd(c(1, 4))
}

Method `report_data_dict()`

Read report data dictionary from EnergyPlus SQL outputs

Usage

EplusGroupJob$report_data_dict(which = NULL)

Arguments

which: An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.

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:

index: The index of simulated model. This column can be used to distinguish output from different simulations
case: The model name without extension. This column can be used to distinguish output from different simulations
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:
schedule_name: Name of the the schedule that controls reporting frequency.
units: The data units

Examples

\dontrun{
group$report_data_dict(c(1, 4))
}

Method `report_data()`

Read report data

Usage

EplusGroupJob$report_data(
  which = NULL,
  key_value = NULL,
  name = NULL,
  year = NULL,
  tz = "UTC",
  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

which

An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.

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

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(NULL, "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(NULL, "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(NULL, "Time"). A few grouped options are also provided:

"Weekday": All working days, i.e. from Monday to Friday
"Weekend": Saturday and Sunday
"DesignDay": Equivalent to "SummerDesignDay" plus "WinterDesignDay"
"CustomDay": CustomDay1 and CustomDay2
"SpecialDay": Equivalent to "DesignDay" plus "CustomDay"
"NormalDay": Equivalent to "Weekday" and "Weekend" plus "Holiday"

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(NULL, "EnvironmentPeriods")

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.

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:
- index: The index of simulated model. This column can be used to distinguish output from different simulations
- case: The model name. This column can be used to distinguish output from different simulations
- 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 report data
group$report_data(c(1, 4))

# specify output variables using report data dictionary
dict <- group$report_data_dict(1)
group$report_data(c(1, 4), dict[units == "C"])

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

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

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

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

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

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

Method `tabular_data()`

Read tabular data

Usage

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

Arguments

which

An integer vector of the indexes or a character vector or names of parametric simulations. If NULL, results of all parametric simulations are returned. Default: NULL.

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:

index: The index of simulated model. This column can be used to distinguish output from different simulations
case: The model name. This column can be used to distinguish output from different simulations
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 9 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
group$tabular_data(c(1, 4))

# explicitly specify data you want
str(group$tabular_data(c(1, 4),
    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(group$tabular_data(c(1, 4),
    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 EplusGroupJob object

Usage

EplusGroupJob$print()

Details

$print() shows the core information of this EplusGroupJob, including the path of IDFs and EPWs and also 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 EplusGroupJob object itself, invisibly.

Examples

\dontrun{
group$print()
}

Examples


## ------------------------------------------------
## Method `EplusGroupJob$new`
## ------------------------------------------------

if (FALSE) { # \dontrun{
if (is_avail_eplus(8.8)) {
    dir <- eplus_config(8.8)$dir
    path_idfs <- list.files(file.path(dir, "ExampleFiles"), "\\.idf",
        full.names = TRUE)[1:5]
    path_epws <- list.files(file.path(dir, "WeatherData"), "\\.epw",
        full.names = TRUE)[1:5]

    # create from local files
    group <- group_job(path_idfs, path_epws)

    # create from Idfs and Epws object
    group_job(lapply(path_idfs, read_idf), lapply(path_epws, read_epw))
}
} # }


## ------------------------------------------------
## Method `EplusGroupJob$run`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# only run design day
group$run(NULL)

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

# specify output directory
group$run(tempdir(), echo = FALSE)

# run in the background
group$run(wait = TRUE, echo = FALSE)
# see group job status
group$status()

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

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


## ------------------------------------------------
## Method `EplusGroupJob$kill`
## ------------------------------------------------

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


## ------------------------------------------------
## Method `EplusGroupJob$status`
## ------------------------------------------------

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


## ------------------------------------------------
## Method `EplusGroupJob$errors`
## ------------------------------------------------

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

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


## ------------------------------------------------
## Method `EplusGroupJob$output_dir`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get output directories of all simulations
group$output_dir()

# get output directories of specified simulations
group$output_dir(c(1, 4))
} # }


## ------------------------------------------------
## Method `EplusGroupJob$list_files`
## ------------------------------------------------

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

# get a data.table that contains a full list of all possible inputs
# and outputs even though they may not exist for current simulation
group$list_files()

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


## ------------------------------------------------
## Method `EplusGroupJob$locate_output`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# get the file path of the error file
group$locate_output(c(1, 4), ".err", strict = FALSE)

# can detect if certain output file exists
group$locate_output(c(1, 4), ".expidf", strict = TRUE)
} # }


## ------------------------------------------------
## Method `EplusGroupJob$list_table`
## ------------------------------------------------

if (FALSE) { # \dontrun{
group$list_table(c(1, 4))
} # }


## ------------------------------------------------
## Method `EplusGroupJob$read_table`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# read a specific table
group$read_table(c(1, 4), "Zones")
} # }


## ------------------------------------------------
## Method `EplusGroupJob$read_rdd`
## ------------------------------------------------

if (FALSE) { # \dontrun{
group$read_rdd(c(1, 4))
} # }


## ------------------------------------------------
## Method `EplusGroupJob$read_mdd`
## ------------------------------------------------

if (FALSE) { # \dontrun{
group$read_mdd(c(1, 4))
} # }


## ------------------------------------------------
## Method `EplusGroupJob$report_data_dict`
## ------------------------------------------------

if (FALSE) { # \dontrun{
group$report_data_dict(c(1, 4))
} # }


## ------------------------------------------------
## Method `EplusGroupJob$report_data`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# read report data
group$report_data(c(1, 4))

# specify output variables using report data dictionary
dict <- group$report_data_dict(1)
group$report_data(c(1, 4), dict[units == "C"])

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

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

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

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

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

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


## ------------------------------------------------
## Method `EplusGroupJob$tabular_data`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# read all tabular data
group$tabular_data(c(1, 4))

# explicitly specify data you want
str(group$tabular_data(c(1, 4),
    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(group$tabular_data(c(1, 4),
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))
} # }


## ------------------------------------------------
## Method `EplusGroupJob$print`
## ------------------------------------------------

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

Create and Run Parametric Analysis, and Collect Results

Arguments

Value

See also

Author

Methods

Public methods

Method new()

Usage

Arguments

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

Returns

Examples

Method list_files()

Usage

Arguments

Details

Returns

Examples

Method locate_output()

Usage

Arguments

Details

Returns

Examples

Method list_table()

Usage

Arguments

Details

Returns

Examples

Method read_table()

Usage

Arguments

Details

Returns

Examples

Method read_rdd()

Usage

Arguments

Details

Returns

Examples

Method read_mdd()

Usage

Arguments

Details

Returns

Examples

Method report_data_dict()

Usage

Arguments

Details

Method `new()`

Method `run()`

Method `kill()`

Method `status()`

Method `errors()`

Method `output_dir()`

Method `list_files()`

Method `locate_output()`

Method `list_table()`

Method `read_table()`

Method `read_rdd()`

Method `read_mdd()`

Method `report_data_dict()`

Method `report_data()`

Method `tabular_data()`

Method `print()`