EplusGroupJob {eplusr} | R Documentation |
Create and Run Parametric Analysis, and Collect Results
Description
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
.
Usage
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 |
Value
A EplusGroupJob
object.
Methods
Public methods
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 oneSizing:DesignDay
object exists in that Idf. Ifepws
isNULL
, 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. IfFALSE
, all EnergyPlus simulations are run in the background. Default:TRUE
.force
Only applicable when the last simulation runs with
wait
equals toFALSE
and is still running. IfTRUE
, current running job is forced to stop and a new one will start. Default:FALSE
.copy_external
If
TRUE
, the external files that currentIdf
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 isFALSE
.echo
Only applicable when
wait
isTRUE
. Whether to simulation status. Default: same aswait
.separate
If
TRUE
, all models are saved in a separate folder with each model's name underdir
when simulation. IfFALSE
, all models are saved indir
when simulation. Default:TRUE
.readvars
If
TRUE
, theReadVarESO
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 toFALSE
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
: Adata.table::data.table()
contains meta data for each simulation job. For details, please seerun_multi()
. If the job has not been run before, adata.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. IfFALSE
, 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 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 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 iffull
isFALSE
. Full file paths iffull
isTRUE
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
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
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
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
and1
-
timestep_type
: Type of data timestep. Possible values:Zone
andHVAC 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 containskey_value
andname
columns. In this case,name
argument in$report_data()
is ignored. All availablekey_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. Ifkey_value
is a data.frame,name
is ignored. All availablename
for current simulation output can be obtained using$report_data_dict()
. Default:NULL
.year
Year of the date time in column
datetime
. IfNULL
, 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 returneddata.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. IfNULL
, no subsetting is performed on those components. All possiblemonth
,day
,hour
andminute
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")
. IfNULL
, 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
, andCustomDay2
. 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 possibleenvironment_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
isFALSE
, the returneddata.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
isTRUE
, 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
and1
-
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
and1
-
type
: Nature of data type with respect to state. Possible values:Sum
andAvg
-
index_group
: The report group, e.g.Zone
,System
-
timestep_type
: Type of data timestep. Possible values:Zone
andHVAC 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
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
isTRUE
. Ifstring_value
isFALSE
, instead of keeping all values as characters, values in possible numeric columns are converted into numbers. Default: the opposite ofwide
. 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
: TheFor
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() }
Author(s)
Hongyuan Jia
See Also
eplus_job()
for creating an EnergyPlus single simulation job.
Examples
## ------------------------------------------------
## Method `EplusGroupJob$new`
## ------------------------------------------------
## Not run:
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))
}
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$run`
## ------------------------------------------------
## Not run:
# 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)
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$kill`
## ------------------------------------------------
## Not run:
group$kill()
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$status`
## ------------------------------------------------
## Not run:
group$status()
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$errors`
## ------------------------------------------------
## Not run:
group$errors()
# show all information
group$errors(info = TRUE)
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$output_dir`
## ------------------------------------------------
## Not run:
# get output directories of all simulations
group$output_dir()
# get output directories of specified simulations
group$output_dir(c(1, 4))
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$list_files`
## ------------------------------------------------
## Not run:
# 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)
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$locate_output`
## ------------------------------------------------
## Not run:
# 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)
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$list_table`
## ------------------------------------------------
## Not run:
group$list_table(c(1, 4))
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$read_table`
## ------------------------------------------------
## Not run:
# read a specific table
group$read_table(c(1, 4), "Zones")
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$read_rdd`
## ------------------------------------------------
## Not run:
group$read_rdd(c(1, 4))
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$read_mdd`
## ------------------------------------------------
## Not run:
group$read_mdd(c(1, 4))
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$report_data_dict`
## ------------------------------------------------
## Not run:
group$report_data_dict(c(1, 4))
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$report_data`
## ------------------------------------------------
## Not run:
# 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)
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$tabular_data`
## ------------------------------------------------
## Not run:
# 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
))
## End(Not run)
## ------------------------------------------------
## Method `EplusGroupJob$print`
## ------------------------------------------------
## Not run:
group$print()
## End(Not run)