Title:	A Toolkit for Using Whole Building Simulation Program 'EnergyPlus'
Version:	0.16.3
Description:	A rich toolkit of using the whole building simulation program 'EnergyPlus'(https://energyplus.net), which enables programmatic navigation, modification of 'EnergyPlus' models and makes it less painful to do parametric simulations and analysis.
License:	MIT + file LICENSE
URL:	https://hongyuanjia.github.io/eplusr/, https://github.com/hongyuanjia/eplusr
BugReports:	https://github.com/hongyuanjia/eplusr/issues
Depends:	R (≥ 3.2.0)
Imports:	callr (≥ 2.0.4), checkmate, cli (≥ 3.0.0), data.table (≥ 1.14.6), lubridate, processx (≥ 3.2.0), R6, RSQLite, stringi, units
Suggests:	hms, decido, rgl (≥ 0.105.13), testthat (≥ 3.0.0)
Encoding:	UTF-8
RoxygenNote:	7.3.1
SystemRequirements:	EnergyPlus (optional) (<https://energyplus.net>); udunits2
Collate:	'constants.R' 'assert.R' 'diagram.R' 'eplusr.R' 'utils.R' 'impl.R' 'parse.R' 'impl-epw.R' 'impl-idd.R' 'impl-idf.R' 'idf.R' 'idd.R' 'epw.R' 'err.R' 'format.R' 'geom.R' 'group.R' 'iddobj.R' 'idfobj-sch.R' 'impl-idfobj.R' 'idfobj.R' 'impl-geom.R' 'impl-iddobj.R' 'impl-idfobj-sch.R' 'impl-sql.R' 'impl-viewer.R' 'install.R' 'job.R' 'options.R' 'param.R' 'rdd.R' 'reload.R' 'run.R' 'sql.R' 'transition.R' 'units.R' 'validate.R' 'viewer.R' 'zzz.R'
Config/testthat/edition:	3
Config/testthat/parallel:	true
NeedsCompilation:	yes
Packaged:	2025-04-22 10:19:20 UTC; hongyuanjia
Author:	Hongyuan Jia [aut, cre, cph], Adrian Chong [aut]
Maintainer:	Hongyuan Jia <hongyuanjia@cqust.edu.cn>
Repository:	CRAN
Date/Publication:	2025-04-22 11:20:05 UTC

eplusr: A Toolkit for Using EnergyPlus in R

Description

A rich toolkit of using the whole building simulation program 'EnergyPlus'(https://energyplus.net), which enables programmatic navigation, modification of 'EnergyPlus' models and makes it less painful to do parametric simulations and analysis.

Details

eplusr provides a rich toolkit of using EnergyPlus directly in R, which enables programmatic navigation, modification of EnergyPlus models and makes it less painful to do parametric simulations and analysis.

Features

• Download and install EnergyPlus in R

• Read, parse and modify EnergyPlus:

  • Input Data File (IDF)

  • Weather File (EPW)

  • Report Data Dictionary (RDD) & Meter Data Dictionary (MDD)

  • Error File (ERR)

• Modify multiple versions of IDFs and run corresponding EnergyPlus both in the background and in the front

• Rich-featured interfaces to query and modify IDFs

• Automatically handle referenced fields and validate input during modification

• Take fully advantage of most common used data structure for data science in R – data.frame

  • Extract model, weather data into data.frames

  • Modify multiple objects via data.frames input

  • Query output via SQL in Tidy format which is much better for data analysis and visualization

• Provide a simple yet extensible prototype of conducting parametric simulations and collect all results in one go

• A pure R-based version updater transition() which is much faster than VersionUpdater distributed with EnergyPlus

Author(s)

Hongyuan Jia

See Also

Useful links:

• https://hongyuanjia.github.io/eplusr/

• https://github.com/hongyuanjia/eplusr

• Report bugs at https://github.com/hongyuanjia/eplusr/issues

Run EnergyPlus and its various processors

Description

Run EnergyPlus and its various processors

Usage

EPMacro(
  model,
  output_dir = NULL,
  output_prefix = NULL,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL
)

ExpandObjects(
  model,
  output_dir = NULL,
  output_prefix = NULL,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL,
  idd = NULL
)

Basement(
  model,
  weather,
  output_dir = NULL,
  output_prefix = NULL,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL,
  idd = NULL
)

Slab(
  model,
  weather,
  output_dir = NULL,
  output_prefix = NULL,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL,
  idd = NULL
)

EnergyPlus(
  model,
  weather,
  output_dir = NULL,
  output_prefix = NULL,
  output_suffix = c("C", "L", "D"),
  wait = TRUE,
  echo = TRUE,
  annual = FALSE,
  design_day = FALSE,
  idd = NULL,
  eplus = NULL
)

convertESOMTR(
  eso,
  output_dir = NULL,
  output_prefix = NULL,
  rules = NULL,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL
)

ReadVarsESO(
  eso,
  output_dir = NULL,
  output_prefix = NULL,
  output_suffix = c("C", "L", "D"),
  max_col = NULL,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL
)

HVAC_Diagram(
  bnd,
  output_dir = NULL,
  output_prefix = NULL,
  wait = TRUE,
  echo = TRUE,
  eplus = NULL
)

energyplus(
  model,
  weather,
  output_dir = NULL,
  output_prefix = NULL,
  output_suffix = c("C", "L", "D"),
  epmacro = TRUE,
  expand_obj = TRUE,
  annual = FALSE,
  design_day = FALSE,
  eso_to_ip = FALSE,
  readvars = TRUE,
  echo = TRUE,
  wait = TRUE,
  idd = NULL,
  eplus = NULL,
  resources = NULL
)

Arguments

Details

EPMacro() calls the EnergyPlus EPMacro processor.

ExpandObjects() calls the EnergyPlus ExpandObjects processor.

Basement() calls the EnergyPlus Basement preprocessor.

Slab() calls the EnergyPlus Slab preprocessor.

EnergyPlus() calls EnergyPlus itself.

convertESOMTR() calls EnergyPlus convertESOMTR post-processor.

ReadVarsESO() calls EnergyPlus ReadVarsESO post-processor.

HVAC_Diagram() calls EnergyPlus HVAC-Diagram post-processor.

energyplus() is the one which correctly chains all the steps that call those pre- and post- processors to form a complete EnergyPlus simulation.

Value

Functions except for energyplus() return a list of two elements:

• file: a named list of full paths of output files

• run: a named list of outputs from the process.

energyplus() returns a list of 7 elements:

• ver: EnergyPlus version used

• energyplus: EnergyPlus installation directory

• start_time: a POSIXct() giving the local time when the simulation starts

• end_time: a POSIXct() giving the local time when the simulation ends

• output_dir: full path of output directory of simulation outputs

• file: a named list of relative paths of output files under output_dir

• run: a data.table of each outputs from the all called processes

Note

energyplus() can only run in waiting mode.

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

Value

A EplusGroupJob object.

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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)

Run EnergyPlus Simulation and Collect Outputs

Description

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

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

Usage

eplus_job(idf, epw)

Arguments

Details

eplusr uses the EnergyPlus SQL output for extracting simulation outputs.

EplusJob has provide some wrappers that do SQL query to get report data results, i.e. results from Output:Variable and ⁠Output:Meter*⁠. But for Output:Table results, you have to be familiar with the structure of the EnergyPlus SQL results, especially for table "TabularDataWithStrings". For details, please see "2.20 eplusout.sql", especially "2.20.4.4 TabularData Table" in EnergyPlus "Output Details and Examples" documentation. An object in Output:SQLite with ⁠Option Type⁠ value of SimpleAndTabular will be automatically created if it does not exists, to ensure that the output collection functionality works successfully.

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

Value

An EplusJob object.

Methods

Public methods

• EplusJob$new()

• EplusJob$version()

• EplusJob$path()

• EplusJob$run()

• EplusJob$kill()

• EplusJob$status()

• EplusJob$errors()

• EplusJob$output_dir()

• EplusJob$list_files()

• EplusJob$locate_output()

• EplusJob$read_rdd()

• EplusJob$read_mdd()

• EplusJob$list_table()

• EplusJob$read_table()

• EplusJob$report_data_dict()

• EplusJob$report_data()

• EplusJob$tabular_data()

• EplusJob$print()

Method new()

Create an EplusJob object

Usage

EplusJob$new(idf, epw)

Arguments

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

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

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

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

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

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.

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

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

Details

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

Returns

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

Examples

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

Method report_data_dict()

Read report data dictionary from EnergyPlus SQL output

Usage

EplusJob$report_data_dict()

Details

⁠$report_data_dict()⁠ returns a data.table::data.table() which contains all information about report data.

For details on the meaning of each columns, please see "2.20.2.1 ReportDataDictionary Table" in EnergyPlus "Output Details and Examples" documentation.

Returns

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

• report_data_dictionary_index: The integer used to link the dictionary data to the variable data. Mainly useful when joining different tables

• is_meter: Whether report data is a meter data. Possible values: 0 and 1

• timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

• key_value: Key name of the data

• name: Actual report data name

• reporting_frequency: Data reporting frequency

• schedule_name: Name the the schedule that controls reporting frequency.

• units: The data units

Examples

\dontrun{
job$report_data_dict()
}

Method report_data()

Read report data

Usage

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

Arguments

Details

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

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

The returned column numbers varies depending on all argument.

• all is FALSE, the returned data.table::data.table() has 6 columns:

  • case: Simulation case specified using case argument

  • datetime: The date time of simulation result

  • key_value: Key name of the data

  • name: Actual report data name

  • units: The data units

  • value: The data value

• all is TRUE, besides columns described above, extra columns are also included:

  • month: The month of reported date time

  • day: The day of month of reported date time

  • hour: The hour of reported date time

  • minute: The minute of reported date time

  • dst: Daylight saving time indicator. Possible values: 0 and 1

  • interval: Length of reporting interval

  • simulation_days: Day of simulation

  • day_type: The type of day, e.g. Monday, Tuesday and etc.

  • environment_period_index: The indices of environment.

  • environment_name: A text string identifying the environment.

  • is_meter: Whether report data is a meter data. Possible values: 0 and 1

  • type: Nature of data type with respect to state. Possible values: Sum and Avg

  • index_group: The report group, e.g. Zone, System

  • timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

  • reporting_frequency: The reporting frequency of the variable, e.g. ⁠HVAC System Timestep⁠, ⁠Zone Timestep⁠.

  • schedule_name: Name of the the schedule that controls reporting frequency.

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

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

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

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

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

Returns

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

Examples

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

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

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

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

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

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

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

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

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

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

Method tabular_data()

Read tabular data

Usage

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

Arguments

Details

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

• case: Simulation case specified using case argument

• index: Tabular data index

• report_name: The name of the report that the record belongs to

• report_for: The For text that is associated with the record

• table_name: The name of the table that the record belongs to

• column_name: The name of the column that the record belongs to

• row_name: The name of the row that the record belongs to

• units: The units of the record

• value: The value of the record in string format by default

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

Returns

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

Examples

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

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

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

Method print()

Print EplusSql object

Usage

EplusJob$print()

Details

⁠$print()⁠ shows the core information of this EplusJob object, including the path of model and weather, the version and path of EnergyPlus used to run simulations, and the simulation job status.

⁠$print()⁠ is quite useful to get the simulation status, especially when wait is FALSE in ⁠$run()⁠. The job status will be updated and printed whenever ⁠$print()⁠ is called.

Returns

The EplusSql object itself, invisibly.

Examples

\dontrun{
job$print()
}

Author(s)

Hongyuan Jia

See Also

ParametricJob class for EnergyPlus parametric simulations.

param_job() for creating an EnergyPlus parametric job.

Examples

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

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

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

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

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

## End(Not run)

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

## Not run: 
job$version()

## End(Not run)


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

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

## End(Not run)


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

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

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

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

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

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

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

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

## End(Not run)


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

## Not run: 
job$kill()

## End(Not run)


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

## Not run: 
job$status()

## End(Not run)


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

## Not run: 
job$errors()

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

## End(Not run)


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

## Not run: 
job$output_dir()

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

## End(Not run)


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

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

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

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

## End(Not run)


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

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

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

## End(Not run)


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

## Not run: 
job$read_rdd()

## End(Not run)


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

## Not run: 
job$read_mdd()

## End(Not run)


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

## Not run: 
job$list_table()

## End(Not run)


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

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

## End(Not run)


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

## Not run: 
job$report_data_dict()

## End(Not run)


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

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

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

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

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

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

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

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

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

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

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

## End(Not run)


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

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

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

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

## End(Not run)


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

## Not run: 
job$print()

## End(Not run)

Retrieve Simulation Outputs Using EnergyPlus SQLite Output File

Description

EplusSql class wraps SQL queries that can retrieve simulation outputs using EnergyPlus SQLite output file.

Details

SQLite output is an optional output format for EnergyPlus. It will be created if there is an object in class Output:SQLite. If the value of field Option in class Output:SQLite is set to "SimpleAndTabular", then database tables related to the tabular reports will be also included.

There are more than 30 tables in the SQLite output file which contains all of the data found in EnergyPlus's tabular output files, standard variable and meter output files, plus a number of reports that are found in the eplusout.eio output file. The full description for SQLite outputs can be found in the EnergyPlus "Output Details and Examples" documentation. Note that all column names of tables returned have been tidied, i.e. "KeyValue" becomes "key_value", "IsMeter" becomes "is_meter" and etc.

EplusSql class makes it possible to directly retrieve simulation results without creating an EplusJob object. EplusJob can only get simulation outputs after the job was successfully run before.

However, it should be noted that, unlike EplusJob, there is no checking on whether the simulation is terminated or completed unsuccessfully or, the parent Idf has been changed since last simulation. This means that you may encounter some problems when retrieve data from an unsuccessful simulation. It is suggested to carefully go through the .err file using read_err() to make sure the output data in the SQLite is correct and reliable.

Methods

Public methods

• EplusSql$new()

• EplusSql$path()

• EplusSql$path_idf()

• EplusSql$list_table()

• EplusSql$read_table()

• EplusSql$report_data_dict()

• EplusSql$report_data()

• EplusSql$tabular_data()

• EplusSql$print()

Method new()

Create an EplusSql object

Usage

EplusSql$new(sql)

Arguments

Returns

An EplusSql object.

Examples

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

    idf_path <- path_eplus_example("8.8", idf_name)
    epw_path <- path_eplus_weather("8.8", epw_name)

    # copy to tempdir and run the model
    idf <- read_idf(idf_path)
    idf$run(epw_path, tempdir(), echo = FALSE)

    # create from local file
    sql <- eplus_sql(file.path(tempdir(), "1ZoneUncontrolled.sql"))
}
}

Method path()

Get the file path of current EpwSql object

Usage

EplusSql$path()

Details

⁠$path()⁠ returns the path of EnergyPlus SQLite file.

Returns

A single string.

Examples

\dontrun{
# get path
sql$path()
}

Method path_idf()

Get the path of corresponding IDF file

Usage

EplusSql$path_idf()

Details

⁠$path_idf()⁠ returns the IDF file path with same name as the SQLite file in the same folder. NULL is returned if no corresponding IDF is found.

Returns

NULL or a single string.

Examples

\dontrun{
# get path
sql$path_idf()
}

Method list_table()

List all table names in current EnergyPlus SQL output

Usage

EplusSql$list_table()

Details

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

Returns

A character vector

Examples

\dontrun{
sql$list_table()
}

Method read_table()

Read a single table from current EnergyPlus SQL output

Usage

EplusSql$read_table(name)

Arguments

Details

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

Returns

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

Examples

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

Method report_data_dict()

Read report data dictionary from current EnergyPlus SQL output

Usage

EplusSql$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:

• schedule_name: Name of the the schedule that controls reporting frequency.

• units: The data units

Examples

\dontrun{
sql$report_data_dict()
}

Method report_data()

Read report data

Usage

EplusSql$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

Details

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

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

The returned column numbers varies depending on all argument.

• all is FALSE, the returned data.table::data.table() has 6 columns:

  • case: Simulation case specified using case argument

  • datetime: The date time of simulation result

  • key_value: Key name of the data

  • name: Actual report data name

  • units: The data units

  • value: The data value

• all is TRUE, besides columns described above, extra columns are also included:

  • month: The month of reported date time

  • day: The day of month of reported date time

  • hour: The hour of reported date time

  • minute: The minute of reported date time

  • dst: Daylight saving time indicator. Possible values: 0 and 1

  • interval: Length of reporting interval

  • simulation_days: Day of simulation

  • day_type: The type of day, e.g. Monday, Tuesday and etc.

  • environment_period_index: The indices of environment.

  • environment_name: A text string identifying the environment.

  • is_meter: Whether report data is a meter data. Possible values: 0 and 1

  • type: Nature of data type with respect to state. Possible values: Sum and Avg

  • index_group: The report group, e.g. Zone, System

  • timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

  • reporting_frequency: The reporting frequency of the variable, e.g. ⁠HVAC System Timestep⁠, ⁠Zone Timestep⁠.

  • schedule_name: Name of the the schedule that controls reporting frequency.

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

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

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

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

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

Returns

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

Examples

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

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

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

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

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

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

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

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

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

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

Method tabular_data()

Read tabular data

Usage

EplusSql$tabular_data(
  report_name = NULL,
  report_for = NULL,
  table_name = NULL,
  column_name = NULL,
  row_name = NULL,
  case = "auto",
  wide = FALSE,
  string_value = !wide
)

Arguments

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 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
sql$tabular_data()

# explicitly specify data you want
str(sql$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(sql$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

EplusSql$print()

Details

⁠$print()⁠ shows the core information of this EplusSql object, including the path of the EnergyPlus SQLite file, last modified time of the SQLite file and the path of the IDF file with the same name in the same folder.

Returns

The EplusSql object itself, invisibly.

Examples

\dontrun{
sql$print()
}

Author(s)

Hongyuan Jia

Examples

## ------------------------------------------------
## Method `EplusSql$new`
## ------------------------------------------------

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

    idf_path <- path_eplus_example("8.8", idf_name)
    epw_path <- path_eplus_weather("8.8", epw_name)

    # copy to tempdir and run the model
    idf <- read_idf(idf_path)
    idf$run(epw_path, tempdir(), echo = FALSE)

    # create from local file
    sql <- eplus_sql(file.path(tempdir(), "1ZoneUncontrolled.sql"))
}

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$path`
## ------------------------------------------------

## Not run: 
# get path
sql$path()

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$path_idf`
## ------------------------------------------------

## Not run: 
# get path
sql$path_idf()

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$list_table`
## ------------------------------------------------

## Not run: 
sql$list_table()

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$read_table`
## ------------------------------------------------

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

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$report_data_dict`
## ------------------------------------------------

## Not run: 
sql$report_data_dict()

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$report_data`
## ------------------------------------------------

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

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

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

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

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

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

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

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

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

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

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$tabular_data`
## ------------------------------------------------

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

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

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$print`
## ------------------------------------------------

## Not run: 
sql$print()

## End(Not run)

Read, and modify an EnergyPlus Weather File (EPW)

Description

Reading an EPW file starts with function read_epw(), which parses an EPW file and returns an Epw object. The parsing process is basically the same as [EnergyPlus/WeatherManager.cc] in EnergyPlus, with some simplifications.

Details

An EPW file can be divided into two parts, headers and weather data. The first eight lines of a standard EPW file are normally headers which contains data of location, design conditions, typical/extreme periods, ground temperatures, holidays/daylight savings, data periods and other comments. Epw class provides methods to directly extract those data. For details on the data structure of EPW file, please see "Chapter 2 - Weather Converter Program" in EnergyPlus "Auxiliary Programs" documentation. An online version can be found here.

There are about 35 variables in the core weather data. However, not all of them are used by EnergyPlus. Actually, despite of date and time columns, only 13 columns are used:

1. dry bulb temperature

2. dew point temperature

3. relative humidity

4. atmospheric pressure

5. horizontal infrared radiation intensity from sky

6. direct normal radiation

7. diffuse horizontal radiation

8. wind direction

9. wind speed

10. present weather observation

11. present weather codes

12. snow depth

13. liquid precipitation depth

Note the hour column in the core weather data corresponds to the period from (Hour-1)th to (Hour)th. For instance, if the number of interval per hour is 1, hour of 1 on a certain day corresponds to the period between 00:00:01 to 01:00:00, Hour of 2 corresponds to the period between 01:00:01 to 02:00:00, and etc. Currently, in EnergyPlus the minute column is not used to determine currently sub-hour time. For instance, if the number of interval per hour is 2, there is no difference between two rows with following time columns (a) Hour 1, Minute 0; Hour 1, Minute 30 and (b) Hour 1, Minute 30; Hour 1, Minute 60. Only the number of rows count. When EnergyPlus reads the EPW file, both (a) and (b) represent the same time period: 00:00:00 - 00:30:00 and 00:30:00 - 01:00:00. Missing data on the weather file used can be summarized in the eplusout.err file, if DisplayWeatherMissingDataWarnings is turned on in Output:Diagnostics object. In EnergyPlus, missing data is shown only for fields that EnergyPlus will use. EnergyPlus will fill some missing data automatically during simulation. Likewise out of range values are counted for each occurrence and summarized. However, note that the out of range values will not be changed by EnergyPlus and could affect your simulation.

Epw class provides methods to easily extract and inspect those abnormal (missing and out of range) weather data and also to know what kind of actions that EnergyPlus will perform on those data.

EnergyPlus energy model calibration often uses actual measured weather data. In order to streamline the error-prone process of creating custom EPW file, Epw provides methods to direction add, replace the core weather data.

Methods

Public methods

• Epw$new()

• Epw$path()

• Epw$definition()

• Epw$location()

• Epw$design_condition()

• Epw$typical_extreme_period()

• Epw$ground_temperature()

• Epw$holiday()

• Epw$comment1()

• Epw$comment2()

• Epw$num_period()

• Epw$interval()

• Epw$period()

• Epw$missing_code()

• Epw$initial_missing_value()

• Epw$range_exist()

• Epw$range_valid()

• Epw$fill_action()

• Epw$data()

• Epw$abnormal_data()

• Epw$redundant_data()

• Epw$make_na()

• Epw$fill_abnormal()

• Epw$add_unit()

• Epw$drop_unit()

• Epw$purge()

• Epw$add()

• Epw$set()

• Epw$del()

• Epw$is_unsaved()

• Epw$save()

• Epw$print()

• Epw$clone()

Method new()

Create an Epw object

Usage

Epw$new(path, encoding = "unknown")

Arguments

Details

It takes an EnergyPlus Weather File (EPW) as input and returns an Epw object.

Returns

An Epw object.

Examples

\dontrun{
# read an EPW file from EnergyPlus website
path_base <- "https://energyplus.net/weather-download"
path_region <- "north_and_central_america_wmo_region_4/USA/CA"
path_file <- "USA_CA_San.Francisco.Intl.AP.724940_TMY3/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
path_epw <- file.path(path_base, path_region, path_file)
epw <- read_epw(path_epw)

# read an EPW file distributed with EnergyPlus
if (is_avail_eplus(8.8)) {
    path_epw <- file.path(
        eplus_config(8.8)$dir,
        "WeatherData",
        "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
    )
    epw <- read_epw(path_epw)
}
}

Method path()

Get the file path of current Epw

Usage

Epw$path()

Details

⁠$path()⁠ returns the full path of current Epw or NULL if the Epw object is created using a character vector and not saved locally.

Returns

NULL or a single string.

Examples

\dontrun{
# get path
epw$path()
}

Method definition()

Get the IddObject object for specified EPW class.

Usage

Epw$definition(class)

Arguments

Details

⁠$definition()⁠ returns an IddObject of given EPW class. IddObject contains all data used for parsing that EPW class.

Currently, all supported EPW classes are:

• LOCATION

• ⁠DESIGN CONDITIONS⁠

• ⁠TYPICAL/EXTREME PERIODS⁠

• ⁠GROUND TEMPERATURES⁠

• ⁠HOLIDAYS/DAYLIGHT SAVINGS⁠

• ⁠COMMENTS 1⁠

• ⁠COMMENTS 2⁠

• ⁠DATA PERIODS⁠

• ⁠WEATHER DATA⁠

Examples

\dontrun{
# get path
epw$definition("LOCATION")
}

Method location()

Get and modify LOCATION header

Usage

Epw$location(
  city,
  state_province,
  country,
  data_source,
  wmo_number,
  latitude,
  longitude,
  time_zone,
  elevation
)

Arguments

Details

⁠$location()⁠ takes new values for LOCATION header fields and returns the parsed values of LOCATION header in a list format. If no input is given, current LOCATION header value is returned.

Returns

A named list of 9 elements.

Examples

\dontrun{
epw$location()

# modify location data
epw$location(city = "MyCity")
}

Method design_condition()

Get DESIGN CONDITION header

Usage

Epw$design_condition()

Details

⁠$design_condition()⁠ returns the parsed values of ⁠DESIGN CONDITION⁠ header in a list format with 4 elements:

• source: A string of source field

• heating: A list, usually of length 16, of the heading design conditions

• cooling: A list, usually of length 32, of the cooling design conditions

• extremes: A list, usually of length 16, of the extreme design conditions

For the meaning of each element, please see ASHRAE Handbook of Fundamentals.

Returns

A named list of 4 elements.

Examples

\dontrun{
epw$design_condition()
}

Method typical_extreme_period()

Get TYPICAL/EXTREME header

Usage

Epw$typical_extreme_period()

Details

⁠$typical_extreme_period()⁠ returns the parsed values of ⁠TYPICAL/EXTREME PERIOD⁠ header in a data.table format with 6 columns:

• index: Integer type. The index of typical or extreme period record

• name: Character type. The name of typical or extreme period record

• type: Character type. The type of period. Possible value: typical and extreme

• start_day: Date type with customized formatting. The start day of the period

• start_day: Date type with customized formatting. The end day of the period

Returns

A data.table::data.table() with 6 columns.

Examples

\dontrun{
epw$typical_extreme_period()
}

Method ground_temperature()

Get GROUND TEMPERATURE header

Usage

Epw$ground_temperature()

Details

⁠$ground_temperature()⁠ returns the parsed values of ⁠GROUND TEMPERATURE⁠ header in a data.table format with 17 columns:

• index: Integer type. The index of ground temperature record

• depth: Numeric type. The depth of the ground temperature is measured

• soil_conductivity: Numeric type. The soil conductivity at measured depth

• soil_density: Numeric type. The soil density at measured depth

• ⁠soil_specific heat⁠: Numeric type. The soil specific heat at measured depth

• January to December: Numeric type. The measured group temperature for each month.

Returns

A data.table::data.table() with 17 columns.

Examples

\dontrun{
epw$ground_temperature()
}

Method holiday()

Get and modify HOLIDAYS/DAYLIGHT SAVINGS header

Usage

Epw$holiday(leapyear, dst, holiday)

Arguments

Details

⁠$holiday()⁠ takes new value for leap year indicator, daylight saving time and holiday specifications, set these new values and returns the parsed values of ⁠HOLIDAYS/DAYLIGHT SAVINGS⁠ header. If no input is given, current values of ⁠HOLIDAYS/DAYLIGHT SAVINGS⁠ header is returned. It returns a list of 3 elements:

• leapyear: A single logical vector. TRUE means that the weather data contains leap year data

• dst: A Date vector contains the start and end day of daylight saving time

• holiday: A data.table contains 2 columns. If no holiday specified, an empty data.table

  • name: Name of the holiday

  • day: Date of the holiday

Validation process below is performed when changing the leapyear indicator:

• If current record of leapyear is TRUE, but new input is FALSE, the modification is only conducted when all data periods do not cover Feb 29.

• If current record of leapyear is FALSE, but new input is TRUE, the modification is only conducted when TMY data periods do not across Feb, e.g. [01/02, 02/28], [03/01, 12/31]; for AMY data, it is always OK.

The date specifications in dst and holiday should follow the rules of "Table 2.14: Weather File Date File Interpretation" in "AuxiliaryPrograms" documentation. eplusr is able to handle all those kinds of formats automatically. Basically, 5 formats are allowed:

1. A single integer is interpreted as the Julian day of year. For example, 1, 2, 3 and 4 will be parsed and presented as ⁠1st day⁠, ⁠2nd day⁠, ⁠3rd day⁠ and ⁠4th day⁠.

2. A single number is interpreted as Month.Day. For example, 1.2 and 5.6 will be parsed and presented as ⁠Jan 02⁠ and ⁠May 06⁠.

3. A string giving MonthName / DayNumber, DayNumber / MonthName, and MonthNumber / DayNumber. A year number can be also included. For example, "Jan/1", "05/Dec", "7/8", "02/10/2019", and "2019/04/05" will be parsed and presented as ⁠Jan 02⁠, ⁠Dec 06⁠, ⁠Jul 8⁠, 2019-02-10 and 2019-04-15.

4. A string giving ⁠number Weekday in Month⁠. For example, "2 Sunday in Jan" will be parsed and presented as ⁠2th Sunday in January⁠.

5. A string giving ⁠Last Weekday in Month⁠. For example, "last Sunday in Dec" will be parsed and presented as ⁠Last Sunday in December⁠.

For convenience, besides all the formats described above, dst and days in holiday also accept standard Dates input. They will be treated as the same way as No.3 format described above.

Returns

A named list of 3 elements.

Examples

\dontrun{
epw$holiday()

# add daylight saving time
epw$holiday(dst = c(3.10, 11.3))
}

Method comment1()

Get and modify COMMENT1 header

Usage

Epw$comment1(comment)

Arguments

Details

⁠$comment1()⁠ takes a single string of new comments and replaces the old comment with input one. If NULL is given, the comment is removed. Empty string or a string that contains only spaces will be treated as NULL. If no input is given, current comment is returned. If no comments exist, NULL is returned.

Returns

A single string.

Examples

\dontrun{
epw$comment1()

epw$comment1("Comment1")
}

Method comment2()

Get and modify COMMENT2 header

Usage

Epw$comment2(comment)

Arguments

Details

⁠$comment2()⁠ takes a single string of new comments and replaces the old comment with input one. If NULL is given, the comment is removed. Empty string or a string that contains only spaces will be treated as NULL. If no input is given, current comment is returned. If no comments exist, NULL is returned.

Returns

A single string.

Examples

\dontrun{
epw$comment2()

epw$comment2("Comment2")
}

Method num_period()

Get number of data periods in DATA PERIODS header

Usage

Epw$num_period()

Details

⁠$num_period()⁠ returns a single positive integer of how many data periods current Epw contains.

Returns

A single integer.

Examples

\dontrun{
epw$num_period()
}

Method interval()

Get the time interval in DATA PERIODS header

Usage

Epw$interval()

Details

⁠$interval()⁠ returns a single positive integer of how many records of weather data exist in one hour.

Returns

A single integer.

Examples

\dontrun{
epw$interval()
}

Method period()

Get and modify data period meta data in DATA PERIODS header

Usage

Epw$period(period, name, start_day_of_week)

Arguments

Details

⁠$period()⁠ takes a data period index, a new period name and start day of week specification, and uses that input to replace the data period's name and start day of week. If no input is given, data periods in current Epw is returned.

Returns

A data.table with 5 columns:

• index: Integer type. The index of data period.

• name: Character type. The name of data period.

• start_day_of_week: Character type. The start day of week of data period.

• start_day: Date (EpwDate) type. The start day of data period.

• end_day: Date (EpwDate) type. The end day of data period.

Examples

\dontrun{
# modify data period name
epw$period(1, name = "test")

# change start day of week
epw$period(1, start_day_of_week = 3)
}

Method missing_code()

Get missing code for weather data variables

Usage

Epw$missing_code()

Details

⁠$missing_code()⁠ returns a list of 29 elements containing the value used as missing value identifier for all weather data.

Returns

A named list of 29 elements.

Examples

\dontrun{
epw$missing_code()
}

Method initial_missing_value()

Get initial value for missing data of weather data variables

Usage

Epw$initial_missing_value()

Details

⁠$initial_missing_value()⁠ returns a list of 16 elements containing the initial value used to replace missing values for corresponding weather data.

Returns

A named list of 16 elements.

Examples

\dontrun{
epw$initial_missing_value()
}

Method range_exist()

Get value ranges for existing values of weather data variables

Usage

Epw$range_exist()

Details

⁠$range_exist()⁠ returns a list of 28 elements containing the range each numeric weather data should fall in. Any values out of this range are treated as missing.

Returns

A named list of 28 elements.

Examples

\dontrun{
epw$range_exist()
}

Method range_valid()

Get value ranges for valid values of weather data variables

Usage

Epw$range_valid()

Details

⁠$range_valid()⁠ returns a list of 28 elements containing the range each numeric weather data should fall in. Any values out of this range are treated as invalid.

Returns

A named list of 28 elements.

Examples

\dontrun{
epw$range_valid()
}

Method fill_action()

Get fill actions for abnormal values of weather data variables

Usage

Epw$fill_action(type = c("missing", "out_of_range"))

Arguments

Details

⁠$fill_action()⁠ returns a list containing actions that EnergyPlus will perform when certain abnormal data found for corresponding weather data. There are 3 types of actions in total:

• do_nothing: All abnormal values are left as they are.

• use_zero: All abnormal values are reset to zeros.

• use_previous: The first abnormal values of variables will be set to the initial missing values. All after are set to previous valid one.

Returns

A named list.

Examples

\dontrun{
epw$fill_action("missing")

epw$fill_action("out_of_range")
}

Method data()

Get weather data

Usage

Epw$data(
  period = 1L,
  start_year = NULL,
  align_wday = TRUE,
  tz = "UTC",
  update = FALSE,
  line = FALSE
)

Arguments

Details

⁠$data()⁠ returns weather data of specific data period.

Usually, EPW file downloaded from EnergyPlus website contains TMY weather data. As years of weather data is not consecutive, it may be more convenient to align the year values to be consecutive, which will makes it possible to direct analyze and plot weather data. The start_year argument in ⁠$data()⁠ method can help to achieve this. However, 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 ⁠DATA PERIODS⁠ header. eplusr provides a simple solution for this. By setting year to NULL and align_wday to TRUE, eplusr will calculate a year value (from current year backwards) for each data period that compliance with the start day of week restriction.

Note that if current data period contains AMY data and start_year is given, a warning is given because the actual year values will be overwritten by input start_year. An error is given if:

• Using input start_year introduces invalid date time. This may happen when weather data contains leap year but input start_year is not a leap year.

• Applying specified time zone specified using tz introduces invalid date time.

Returns

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

Examples

\dontrun{
# get weather data
str(epw$data())

# get weather data but change the year to 2018
# the year column is not changed by default, only the returned datetime column
head(epw$data(start_year = 2018)$datetime)
str(epw$data(start_year = 2018)$year)
# you can update the year column too
head(epw$data(start_year = 2018, update = TRUE)$year)

# change the time zone of datetime column in the returned weather data
attributes(epw$data()$datetime)
attributes(epw$data(tz = "Etc/GMT+8")$datetime)
}

Method abnormal_data()

Get abnormal weather data

Usage

Epw$abnormal_data(
  period = 1L,
  cols = NULL,
  keep_all = TRUE,
  type = c("both", "missing", "out_of_range")
)

Arguments

Details

⁠$abnormal_data()⁠ returns abnormal data of specific data period. Basically, there are 2 types of abnormal data in Epw, i.e. missing values and out-of-range values. Sometimes, it may be useful to extract and inspect those data especially when inserting measured weather data. ⁠$abnormal_data()⁠ does this.

In the returned data.table::data.table(), a column named line is created indicating the line numbers where abnormal data occur in the actual EPW file.

Returns

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

Examples

\dontrun{
epw$abnormal_data()

# only check if there are any abnormal values in air temperature and
# liquid precipitation rate
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"))

# save as above, but only return date time columns plus those 2 columns
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    keep_all = FALSE
)

# same as above, but only check for missing values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "missing"
)

# same as above, but only check for out-of-range values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "out_of_range"
)
}

Method redundant_data()

Get redundant weather data

Usage

Epw$redundant_data()

Details

⁠$redundant_data()⁠ returns weather data in Epw object that do not belong to any data period. This data can be further removed using $purge()' method described below.

In the returned data.table::data.table(), a column named line is created indicating the line numbers where redundant data occur in the actual EPW file.

Returns

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

Examples

\dontrun{
epw$redundant_data()
}

Method make_na()

Convert abnormal data into NAs

Usage

Epw$make_na(missing = FALSE, out_of_range = FALSE)

Arguments

Details

⁠$make_na()⁠ converts specified abnormal data into NAs in specified data period. This makes it easier to find abnormal data directly using is.na() instead of using $missing_code()

⁠$make_na()⁠ and $fill_abnormal() are reversible, i.e. ⁠$make_na()⁠ can be used to counteract the effects introduced by $make_na(), and vise a versa.

Note that ⁠$make_na⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$make_na()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$make_na(missing = TRUE)
summary(epw$data()$liquid_precip_rate)
}

Method fill_abnormal()

Fill abnormal data using prescribed pattern

Usage

Epw$fill_abnormal(missing = FALSE, out_of_range = FALSE, special = FALSE)

Arguments

Details

⁠$fill_abnormal()⁠ fills specified abnormal data using corresponding actions listed in $fill_action(). For what kinds of actions to be performed, please see $fill_action(). method described above. Note that only if special is TRUE, special actions listed in ⁠$fill_action()⁠ is performed. If special is FALSE, all abnormal data, including both missing values and out-of-range values, are filled with corresponding missing codes.

$make_na() and ⁠$fill_abnormal()⁠ are reversible, i.e. $make_na() can be used to counteract the effects introduced by ⁠$fill_abnormal()⁠, and vise a versa.

Note that ⁠$fill_abnormal⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$fill_abnormal()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$fill_abnormal(missing = TRUE)
summary(epw$data()$liquid_precip_rate)
}

Method add_unit()

Add units to weather data variables

Usage

Epw$add_unit()

Details

⁠$add_unit()⁠ assigns units to numeric weather data using units::set_units() if applicable.

⁠$add_unit()⁠ and $drop_unit() are reversible, i.e. ⁠$add_unit()⁠ can be used to counteract the effects introduced by $drop_unit(), and vise a versa.

Note that ⁠$add_unit⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$add_unit()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# get weather data with units
epw$add_unit()
head(epw$data())

# with units specified, you can easily perform unit conversion using units
# package
t_dry_bulb <- epw$data()$dry_bulb_temperature
units(t_dry_bulb) <- with(units::ud_units, "kelvin")

head(t_dry_bulb)
}

Method drop_unit()

Remove units in weather data variables

Usage

Epw$drop_unit()

Details

⁠$drop_unit()⁠ removes all units of numeric weather data.

$add_unit() and ⁠$drop_unit()⁠ are reversible, i.e. $add_unit() can be used to counteract the effects introduced by ⁠$drop_unit()⁠, and vise a versa.

Note that ⁠$add_unit⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$add_unit()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
epw$drop_unit()
epw$data()
}

Method purge()

Delete redundant weather data observations

Usage

Epw$purge()

Details

⁠$purge()⁠ deletes weather data in Epw object that do not belong to any data period.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
epw$purge()
}

Method add()

Add a data period

Usage

Epw$add(
  data,
  realyear = FALSE,
  name = NULL,
  start_day_of_week = NULL,
  after = 0L
)

Arguments

Details

⁠$add()⁠ adds a new data period into current Epw object at specified position.

The validity of input data is checked before adding according to rules following:

• Column datetime exists and has type of POSIXct. Note that time zone of input date time will be reset to UTC.

• It assumes that input data is already sorted, i.e. no further sorting is made during validation. This is because when input data is TMY data, there is no way to properly sort input data rows only using datetime column.

• Number of data records per hour should be consistent across input data.

• Input number of data records per hour should be the same as existing data periods.

• The date time of input data should not overlap with existing data periods.

• Input data should have all 29 weather data columns with correct types. The year, month, day, and minute column are not compulsory. They will be created according to values in the datetime column. Existing values will be overwritten.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# will fail since date time in input data has already been covered by
# existing data period
try(epw$add(epw$data()), silent = TRUE)
}

Method set()

Replace a data period

Usage

Epw$set(
  data,
  realyear = FALSE,
  name = NULL,
  start_day_of_week = NULL,
  period = 1L
)

Arguments

Details

⁠$set()⁠ replaces existing data period using input new weather data.

The validity of input data is checked before replacing according to rules following:

• Column datetime exists and has type of POSIXct. Note that time zone of input date time will be reset to UTC.

• It assumes that input data is already sorted, i.e. no further sorting is made during validation. This is because when input data is TMY data, there is no way to properly sort input data rows only using datetime column.

• Number of data records per hour should be consistent across input data.

• Input number of data records per hour should be the same as existing data periods.

• The date time of input data should not overlap with existing data periods.

• Input data should have all 29 weather data columns with right types. The year, month, day, and minute column are not compulsory. They will be created according to values in the datetime column. Existing values will be overwritten.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# change the weather data
epw$set(epw$data())
}

Method del()

Delete a data period

Usage

Epw$del(period)

Arguments

Details

⁠$del()⁠ removes a specified data period. Note that an error will be given if current Epw only contains one data period.

Returns

The modified Epw object itself, invisibly.

Method is_unsaved()

Check if there are unsaved changes in current Epw

Usage

Epw$is_unsaved()

Details

⁠$is_unsaved()⁠ returns TRUE if there are modifications on the Epw object since it was read or since last time it was saved, and returns FALSE otherwise.

Returns

A single logical value of TRUE or FALSE.

Examples

\dontrun{
epw$is_unsaved()
}

Method save()

Save Epw object as an EPW file

Usage

Epw$save(path = NULL, overwrite = FALSE, purge = FALSE, format_digit = TRUE)

Arguments

Details

⁠$save()⁠ saves current Epw to an EPW file. Note that if missing values and out-of-range values are converted to NAs using $make_na(), they will be filled with corresponding missing codes during saving.

Returns

A length-one character vector, invisibly.

Examples

\dontrun{
# save the weather file
epw$save(file.path(tempdir(), "weather.epw"), overwrite = TRUE)
}

Method print()

Print Idf object

Usage

Epw$print()

Details

⁠$print()⁠ prints the Epw object, including location, elevation, data source, WMO station, leap year indicator, interval and data periods.

Returns

The Epw object itself, invisibly.

Examples

\dontrun{
epw$print()
}

Method clone()

The objects of this class are cloneable with this method.

Usage

Epw$clone(deep = TRUE)

Arguments

Author(s)

Hongyuan Jia

Examples

## ------------------------------------------------
## Method `Epw$new`
## ------------------------------------------------

## Not run: 
# read an EPW file from EnergyPlus website
path_base <- "https://energyplus.net/weather-download"
path_region <- "north_and_central_america_wmo_region_4/USA/CA"
path_file <- "USA_CA_San.Francisco.Intl.AP.724940_TMY3/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
path_epw <- file.path(path_base, path_region, path_file)
epw <- read_epw(path_epw)

# read an EPW file distributed with EnergyPlus
if (is_avail_eplus(8.8)) {
    path_epw <- file.path(
        eplus_config(8.8)$dir,
        "WeatherData",
        "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
    )
    epw <- read_epw(path_epw)
}

## End(Not run)


## ------------------------------------------------
## Method `Epw$path`
## ------------------------------------------------

## Not run: 
# get path
epw$path()

## End(Not run)


## ------------------------------------------------
## Method `Epw$definition`
## ------------------------------------------------

## Not run: 
# get path
epw$definition("LOCATION")

## End(Not run)


## ------------------------------------------------
## Method `Epw$location`
## ------------------------------------------------

## Not run: 
epw$location()

# modify location data
epw$location(city = "MyCity")

## End(Not run)


## ------------------------------------------------
## Method `Epw$design_condition`
## ------------------------------------------------

## Not run: 
epw$design_condition()

## End(Not run)


## ------------------------------------------------
## Method `Epw$typical_extreme_period`
## ------------------------------------------------

## Not run: 
epw$typical_extreme_period()

## End(Not run)


## ------------------------------------------------
## Method `Epw$ground_temperature`
## ------------------------------------------------

## Not run: 
epw$ground_temperature()

## End(Not run)


## ------------------------------------------------
## Method `Epw$holiday`
## ------------------------------------------------

## Not run: 
epw$holiday()

# add daylight saving time
epw$holiday(dst = c(3.10, 11.3))

## End(Not run)


## ------------------------------------------------
## Method `Epw$comment1`
## ------------------------------------------------

## Not run: 
epw$comment1()

epw$comment1("Comment1")

## End(Not run)


## ------------------------------------------------
## Method `Epw$comment2`
## ------------------------------------------------

## Not run: 
epw$comment2()

epw$comment2("Comment2")

## End(Not run)


## ------------------------------------------------
## Method `Epw$num_period`
## ------------------------------------------------

## Not run: 
epw$num_period()

## End(Not run)


## ------------------------------------------------
## Method `Epw$interval`
## ------------------------------------------------

## Not run: 
epw$interval()

## End(Not run)


## ------------------------------------------------
## Method `Epw$period`
## ------------------------------------------------

## Not run: 
# modify data period name
epw$period(1, name = "test")

# change start day of week
epw$period(1, start_day_of_week = 3)

## End(Not run)


## ------------------------------------------------
## Method `Epw$missing_code`
## ------------------------------------------------

## Not run: 
epw$missing_code()

## End(Not run)


## ------------------------------------------------
## Method `Epw$initial_missing_value`
## ------------------------------------------------

## Not run: 
epw$initial_missing_value()

## End(Not run)


## ------------------------------------------------
## Method `Epw$range_exist`
## ------------------------------------------------

## Not run: 
epw$range_exist()

## End(Not run)


## ------------------------------------------------
## Method `Epw$range_valid`
## ------------------------------------------------

## Not run: 
epw$range_valid()

## End(Not run)


## ------------------------------------------------
## Method `Epw$fill_action`
## ------------------------------------------------

## Not run: 
epw$fill_action("missing")

epw$fill_action("out_of_range")

## End(Not run)


## ------------------------------------------------
## Method `Epw$data`
## ------------------------------------------------

## Not run: 
# get weather data
str(epw$data())

# get weather data but change the year to 2018
# the year column is not changed by default, only the returned datetime column
head(epw$data(start_year = 2018)$datetime)
str(epw$data(start_year = 2018)$year)
# you can update the year column too
head(epw$data(start_year = 2018, update = TRUE)$year)

# change the time zone of datetime column in the returned weather data
attributes(epw$data()$datetime)
attributes(epw$data(tz = "Etc/GMT+8")$datetime)

## End(Not run)


## ------------------------------------------------
## Method `Epw$abnormal_data`
## ------------------------------------------------

## Not run: 
epw$abnormal_data()

# only check if there are any abnormal values in air temperature and
# liquid precipitation rate
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"))

# save as above, but only return date time columns plus those 2 columns
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    keep_all = FALSE
)

# same as above, but only check for missing values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "missing"
)

# same as above, but only check for out-of-range values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "out_of_range"
)

## End(Not run)


## ------------------------------------------------
## Method `Epw$redundant_data`
## ------------------------------------------------

## Not run: 
epw$redundant_data()

## End(Not run)


## ------------------------------------------------
## Method `Epw$make_na`
## ------------------------------------------------

## Not run: 
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$make_na(missing = TRUE)
summary(epw$data()$liquid_precip_rate)

## End(Not run)


## ------------------------------------------------
## Method `Epw$fill_abnormal`
## ------------------------------------------------

## Not run: 
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$fill_abnormal(missing = TRUE)
summary(epw$data()$liquid_precip_rate)

## End(Not run)


## ------------------------------------------------
## Method `Epw$add_unit`
## ------------------------------------------------

## Not run: 
# get weather data with units
epw$add_unit()
head(epw$data())

# with units specified, you can easily perform unit conversion using units
# package
t_dry_bulb <- epw$data()$dry_bulb_temperature
units(t_dry_bulb) <- with(units::ud_units, "kelvin")

head(t_dry_bulb)

## End(Not run)


## ------------------------------------------------
## Method `Epw$drop_unit`
## ------------------------------------------------

## Not run: 
epw$drop_unit()
epw$data()

## End(Not run)


## ------------------------------------------------
## Method `Epw$purge`
## ------------------------------------------------

## Not run: 
epw$purge()

## End(Not run)


## ------------------------------------------------
## Method `Epw$add`
## ------------------------------------------------

## Not run: 
# will fail since date time in input data has already been covered by
# existing data period
try(epw$add(epw$data()), silent = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Epw$set`
## ------------------------------------------------

## Not run: 
# change the weather data
epw$set(epw$data())

## End(Not run)


## ------------------------------------------------
## Method `Epw$is_unsaved`
## ------------------------------------------------

## Not run: 
epw$is_unsaved()

## End(Not run)


## ------------------------------------------------
## Method `Epw$save`
## ------------------------------------------------

## Not run: 
# save the weather file
epw$save(file.path(tempdir(), "weather.epw"), overwrite = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Epw$print`
## ------------------------------------------------

## Not run: 
epw$print()

## End(Not run)

Parse, Query and Modify EnergyPlus Input Data Dictionary (IDD)

Description

eplusr provides parsing of and programmatic access to EnergyPlus Input Data Dictionary (IDD) files, and objects. It contains all data needed to parse EnergyPlus models. Idd class provides parsing and printing while IddObject provides detailed information of curtain class.

Overview

EnergyPlus operates off of text input files written in its own Input Data File (IDF) format. IDF files are similar to XML files in that they are intended to conform to a data schema written using similar syntax. For XML, the schema format is XSD; for IDF, the schema format is IDD. For each release of EnergyPlus, valid IDF files are defined by the "Energy+.idd" file shipped with the release.

eplusr tries to detect all installed EnergyPlus in default installation locations when loading, i.e. ⁠C:\\EnergyPlusVX-X-0⁠ on Windows, ⁠/usr/local/EnergyPlus-X-Y-0⁠ on Linux, and ⁠/Applications/EnergyPlus-X-Y-0⁠ on macOS and stores all found locations internally. This data is used to locate the distributed "Energy+.idd" file of each EnergyPlus version. And also, every time an IDD file is parsed, an Idd object is created and cached in an environment.

Parsing an IDD file starts from use_idd(). When using use_idd(), eplusr will first try to find the cached Idd object of that version, if possible. If failed, and EnergyPlus of that version is available (see avail_eplus()), the "Energy+.idd" distributed with EnergyPlus will be parsed and cached. So each IDD file only needs to be parsed once and can be used when parsing every IDF file of that version.

Internally, the powerful data.table package is used to speed up the whole IDD parsing process and store the results. However, it will still take about 2-3 sec per IDD. Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD data in data.table::data.table format. Every IDD will be parsed and stored in four tables:

• group: contains group index and group names.

• class: contains class names and properties.

• field: contains field names and field properties.

• reference: contains cross-reference data of fields.

Methods

Public methods

• Idd$new()

• Idd$version()

• Idd$build()

• Idd$path()

• Idd$group_name()

• Idd$from_group()

• Idd$class_name()

• Idd$required_class_name()

• Idd$unique_class_name()

• Idd$extensible_class_name()

• Idd$group_index()

• Idd$class_index()

• Idd$is_valid_group()

• Idd$is_valid_class()

• Idd$object()

• Idd$objects()

• Idd$object_relation()

• Idd$objects_in_relation()

• Idd$objects_in_group()

• Idd$to_table()

• Idd$to_string()

• Idd$print()

Method new()

Create an Idd object

Usage

Idd$new(path, encoding = "unknown")

Arguments

Details

It takes an EnergyPlus Input Data Dictionary (IDD) as input and returns an Idd object.

It is suggested to use helper use_idd() which supports to directly take a valid IDD version as input and search automatically the corresponding file path.

Returns

An Idd object.

Examples

\dontrun{Idd$new(file.path(eplus_config(8.8)$dir, "Energy+.idd"))

# Preferable way
idd <- use_idd(8.8, download = "auto")
}

Method version()

Get the version of current Idd

Usage

Idd$version()

Details

⁠$version()⁠ returns the version of current Idd in a base::numeric_version() format. This makes it easy to direction compare versions of different Idds, e.g. idd$version() > 8.6 or idd1$version() > idd2$version().

Returns

A base::numeric_version() object.

Examples

\dontrun{
# get version
idd$version()
}

Method build()

Get the build tag of current Idd

Usage

Idd$build()

Details

⁠$build()⁠ returns the build tag of current Idd. If no build tag is found, NA is returned.

Returns

A base::numeric_version() object.

Examples

\dontrun{
# get build tag
idd$build()
}

Method path()

Get the file path of current Idd

Usage

Idd$path()

Details

⁠$path()⁠ returns the full path of current Idd or NULL if the Idd object is created using a character vector and not saved locally.

Returns

NULL or a single string.

Examples

\dontrun{
# get path
idd$path()
}

Method group_name()

Get names of groups

Usage

Idd$group_name()

Details

⁠$group_name()⁠ returns names of groups current Idd contains.

Returns

A character vector.

Examples

\dontrun{
# get names of all groups Idf contains
idd$group_name()
}

Method from_group()

Get the name of group that specified class belongs to

Usage

Idd$from_group(class)

Arguments

Details

⁠$from_group()⁠ returns the name of group that specified class belongs to.

Returns

A character vector.

Examples

\dontrun{
idd$from_group(c("Version", "Schedule:Compact"))
}

Method class_name()

Get names of classes

Usage

Idd$class_name(index = NULL, by_group = FALSE)

Arguments

Details

⁠$class_name()⁠ returns names of classes current Idd contains

Returns

A character vector if by_group is FALSE and a list of character vectors when by_group is TRUE.

Examples

\dontrun{
# get names of the 10th to 20th class
idd$class_name(10:20)

# get names of all classes in Idf
idd$class_name()

# get names of all classes grouped by group names in Idf
idd$class_name(by_group = TRUE)
}

Method required_class_name()

Get the names of required classes

Usage

Idd$required_class_name()

Details

⁠$required_class_name()⁠ returns the names of required classes in current Idd. "Require" means that for any Idf there should be at least one object.

Returns

A character vector.

Examples

\dontrun{
idd$required_class_name()
}

Method unique_class_name()

Get the names of unique-object classes

Usage

Idd$unique_class_name()

Details

⁠$unique_class_name()⁠ returns the names of unique-object classes in current Idd. "Unique-object" means that for any Idf there should be at most one object in those classes.

Returns

A character vector.

Examples

\dontrun{
idd$unique_class_name()
}

Method extensible_class_name()

Get the names of classes with extensible fields

Usage

Idd$extensible_class_name()

Details

⁠$extensible_class_name()⁠ returns the names of classes with extensible fields in current Idd. "Extensible fields" indicate fields that can be added dynamically, such like the X, Y and Z vertices of a building surface.

Returns

A character vector.

Examples

\dontrun{
idd$extensible_class_name()
}

Method group_index()

Get the indices of specified groups

Usage

Idd$group_index(group = NULL)

Arguments

Details

⁠$group_index()⁠ returns the indices of specified groups in current Idd. A group index is just an integer indicating its appearance order in the Idd.

Returns

An integer vector.

Examples

\dontrun{
idd$group_index()
}

Method class_index()

Get the indices of specified classes

Usage

Idd$class_index(class = NULL, by_group = FALSE)

Arguments

Details

⁠$class_index()⁠ returns the indices of specified classes in current Idd. A class index is just an integer indicating its appearance order in the Idd.

Returns

An integer vector.

Examples

\dontrun{
idd$class_index()
}

Method is_valid_group()

Check if elements in input character vector are valid group names.

Usage

Idd$is_valid_group(group)

Arguments

Details

⁠$is_valid_group()⁠ returns TRUEs if given character vector contains valid group names in the context of current Idd, and FALSEs otherwise.

Note that case-sensitive matching is performed, which means that "Location and Climate" is a valid group name but "location and climate" is not.

Returns

A logical vector with the same length as input character vector.

Examples

\dontrun{
idd$is_valid_group(c("Schedules", "Compliance Objects"))
}

Method is_valid_class()

Check if elements in input character vector are valid class names.

Usage

Idd$is_valid_class(class)

Arguments

Details

⁠$is_valid_class()⁠ returns TRUEs if given character vector contains valid class names in the context of current Idd, and FALSEs otherwise.

Note that case-sensitive matching is performed, which means that "Version" is a valid class name but "version" is not.

Returns

A logical vector with the same length as input character vector.

Examples

\dontrun{
idd$is_valid_class(c("Building", "ShadowCalculation"))
}

Method object()

Extract an IddObject object using class index or name.

Usage

Idd$object(class)

Arguments

Details

⁠$object()⁠ returns an IddObject object specified by a class ID or name.

Note that case-sensitive matching is performed, which means that "Version" is a valid class name but "version" is not.

For convenience, underscore-style names are allowed, e.g. Site_Location is equivalent to Site:Location.

Returns

An IddObject object.

Examples

\dontrun{
idd$object(3)

idd$object("Building")
}

Method objects()

Extract multiple IddObject objects using class indices or names.

Usage

Idd$objects(class)

Arguments

Details

⁠$objects()⁠ returns a named list of IddObject objects using class indices or names. The returned list is named using class names.

Note that case-sensitive matching is performed, which means that "Version" is a valid class name but "version" is not.

For convenience, underscore-style names are allowed, e.g. Site_Location is equivalent to Site:Location.

Returns

A named list of IddObject objects.

Examples

\dontrun{
idd$objects(c(3,10))

idd$objects(c("Version", "Material"))
}

Method object_relation()

Extract the relationship between class fields.

Usage

Idd$object_relation(
  which,
  direction = c("all", "ref_to", "ref_by"),
  class = NULL,
  group = NULL,
  depth = 0L
)

Arguments

Details

Many fields in Idd can be referred by others. For example, the ⁠Outside Layer⁠ and other fields in Construction class refer to the Name field in Material class and other material related classes. Here it means that the ⁠Outside Layer⁠ field refers to the Name field and the Name field is referred by the ⁠Outside Layer⁠.

⁠$object_relation()⁠ provides a simple interface to get this kind of relation. It takes a single class index or name and also a relation direction, and returns an IddRelation object which contains data presenting such relation above. For instance, if idd$object_relation("Construction", "ref_to") gives results below:

-- Refer to Others ---------------------------
  Class: <Construction>
  |- Field: <02: Outside Layer>
  |  v~~~~~~~~~~~~~~~~~~~~~~~~~
  |  |- Class: <Material>
  |  |  \- Field: <1: Name>
  |  |
  |  |- Class: <Material:NoMass>
  |  |  \- Field: <1: Name>
  |  |
  |  |- Class: <Material:InfraredTransparent>
  |  |  \- Field: <1: Name>
  |  |
  ......

This means that the value of field ⁠Outside Layer⁠ in class Construction can be one of values from field Name in class Material, field Name in class Material:NoMass, field Name in class Material:InfraredTransparent and etc. All those classes can be further easily extracted using ⁠$objects_in_relation()⁠ method described below.

Returns

An IddRelation object, which is a list of 3 data.table::data.table()s named ref_to and ref_by. Each data.table::data.table() contains 12 columns.

Examples

\dontrun{
# check each construction layer's possible references
idd$object_relation("Construction", "ref_to")

# check where construction being used
idd$object_relation("Construction", "ref_by")
}

Method objects_in_relation()

Extract multiple IddObject objects referencing each others.

Usage

Idd$objects_in_relation(
  which,
  direction = c("ref_to", "ref_by"),
  class = NULL,
  group = NULL,
  depth = 0L
)

Arguments

Details

⁠$objects_in_relation()⁠ returns a named list of IddObject objects that have specified relationship with given class. The first element of returned list is always the specified class itself. If that class does not have specified relationship with other classes, a list that only contains specified class itself is returned.

For instance, idd$objects_in_relation("Construction", "ref_by") will return a named list of an IddObject object named Construction and also all other IddObject objects that can refer to field values in class Construction. Similarly, idd$objects_in_relation("Construction", "ref_to") will return a named list of an IddObject object named Construction and also all other IddObject objects that Construction can refer to.

Returns

An named list of IddObject objects.

Examples

\dontrun{
# get class Construction and all classes that it can refer to
idd$objects_in_relation("Construction", "ref_to")

# get class Construction and all classes that refer to it
idd$objects_in_relation("Construction", "ref_by")
}

Method objects_in_group()

Extract all IddObject objects in one group.

Usage

Idd$objects_in_group(group)

Arguments

Details

⁠$objects_in_group()⁠ returns a named list of all IddObject objects in specified group. The returned list is named using class names.

Returns

A named list of IddObject objects.

Examples

\dontrun{
# get all classes in Schedules group
idd$objects_in_group("Schedules")
}

Method to_table()

Format Idd classes as a data.frame

Usage

Idd$to_table(class, all = FALSE)

Arguments

Details

⁠$to_table()⁠ returns a data.table that contains basic data of specified classes. The returned data.table has 3 columns:

• class: Character type. Current class name.

• index: Integer type. Field indexes.

• field: Character type. Field names.

Returns

A data.table with 3 columns.

Examples

\dontrun{
# extract data of class Material
idd$to_table(class = "Material")

# extract multiple class data
idd$to_table(c("Construction", "Material"))
}

Method to_string()

Format Idf classes as a character vector

Usage

Idd$to_string(class, leading = 4L, sep_at = 29L, sep_each = 0L, all = FALSE)

Arguments

Details

⁠$to_string()⁠ returns the text format of specified classes. The returned character vector can be pasted into an IDF file as empty objects of specified classes.

Returns

A character vector.

Examples

\dontrun{
# get text format of class Material
head(idd$to_string(class = "Material"))

# get text format of multiple class
idd$to_string(c("Material", "Construction"))

# tweak output formatting
idd$to_string(c("Material", "Construction"), leading = 0, sep_at = 0, sep_each = 5)
}

Method print()

Print Idd object

Usage

Idd$print()

Details

⁠$print()⁠ prints the Idd object giving the information of version, build tag and total class numbers.

Returns

The Idd object itself, invisibly.

Examples

\dontrun{
idd$print()
}

Author(s)

Hongyuan Jia

References

IDFEditor, OpenStudio utilities library

See Also

IddObject class which provides detailed information of curtain class

Examples

## ------------------------------------------------
## Method `Idd$new`
## ------------------------------------------------

## Not run: Idd$new(file.path(eplus_config(8.8)$dir, "Energy+.idd"))

# Preferable way
idd <- use_idd(8.8, download = "auto")

## End(Not run)


## ------------------------------------------------
## Method `Idd$version`
## ------------------------------------------------

## Not run: 
# get version
idd$version()

## End(Not run)


## ------------------------------------------------
## Method `Idd$build`
## ------------------------------------------------

## Not run: 
# get build tag
idd$build()

## End(Not run)


## ------------------------------------------------
## Method `Idd$path`
## ------------------------------------------------

## Not run: 
# get path
idd$path()

## End(Not run)


## ------------------------------------------------
## Method `Idd$group_name`
## ------------------------------------------------

## Not run: 
# get names of all groups Idf contains
idd$group_name()

## End(Not run)


## ------------------------------------------------
## Method `Idd$from_group`
## ------------------------------------------------

## Not run: 
idd$from_group(c("Version", "Schedule:Compact"))

## End(Not run)


## ------------------------------------------------
## Method `Idd$class_name`
## ------------------------------------------------

## Not run: 
# get names of the 10th to 20th class
idd$class_name(10:20)

# get names of all classes in Idf
idd$class_name()

# get names of all classes grouped by group names in Idf
idd$class_name(by_group = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Idd$required_class_name`
## ------------------------------------------------

## Not run: 
idd$required_class_name()

## End(Not run)


## ------------------------------------------------
## Method `Idd$unique_class_name`
## ------------------------------------------------

## Not run: 
idd$unique_class_name()

## End(Not run)


## ------------------------------------------------
## Method `Idd$extensible_class_name`
## ------------------------------------------------

## Not run: 
idd$extensible_class_name()

## End(Not run)


## ------------------------------------------------
## Method `Idd$group_index`
## ------------------------------------------------

## Not run: 
idd$group_index()

## End(Not run)


## ------------------------------------------------
## Method `Idd$class_index`
## ------------------------------------------------

## Not run: 
idd$class_index()

## End(Not run)


## ------------------------------------------------
## Method `Idd$is_valid_group`
## ------------------------------------------------

## Not run: 
idd$is_valid_group(c("Schedules", "Compliance Objects"))

## End(Not run)


## ------------------------------------------------
## Method `Idd$is_valid_class`
## ------------------------------------------------

## Not run: 
idd$is_valid_class(c("Building", "ShadowCalculation"))

## End(Not run)


## ------------------------------------------------
## Method `Idd$object`
## ------------------------------------------------

## Not run: 
idd$object(3)

idd$object("Building")

## End(Not run)


## ------------------------------------------------
## Method `Idd$objects`
## ------------------------------------------------

## Not run: 
idd$objects(c(3,10))

idd$objects(c("Version", "Material"))

## End(Not run)


## ------------------------------------------------
## Method `Idd$object_relation`
## ------------------------------------------------

## Not run: 
# check each construction layer's possible references
idd$object_relation("Construction", "ref_to")

# check where construction being used
idd$object_relation("Construction", "ref_by")

## End(Not run)


## ------------------------------------------------
## Method `Idd$objects_in_relation`
## ------------------------------------------------

## Not run: 
# get class Construction and all classes that it can refer to
idd$objects_in_relation("Construction", "ref_to")

# get class Construction and all classes that refer to it
idd$objects_in_relation("Construction", "ref_by")

## End(Not run)


## ------------------------------------------------
## Method `Idd$objects_in_group`
## ------------------------------------------------

## Not run: 
# get all classes in Schedules group
idd$objects_in_group("Schedules")

## End(Not run)


## ------------------------------------------------
## Method `Idd$to_table`
## ------------------------------------------------

## Not run: 
# extract data of class Material
idd$to_table(class = "Material")

# extract multiple class data
idd$to_table(c("Construction", "Material"))

## End(Not run)


## ------------------------------------------------
## Method `Idd$to_string`
## ------------------------------------------------

## Not run: 
# get text format of class Material
head(idd$to_string(class = "Material"))

# get text format of multiple class
idd$to_string(c("Material", "Construction"))

# tweak output formatting
idd$to_string(c("Material", "Construction"), leading = 0, sep_at = 0, sep_each = 5)

## End(Not run)


## ------------------------------------------------
## Method `Idd$print`
## ------------------------------------------------

## Not run: 
idd$print()

## End(Not run)

EnergyPlus IDD object

Description

IddObject is an abstraction of a single object in an Idd object. It provides more detail methods to query field properties. IddObject can only be created from the parent Idd object, using ⁠$object()⁠, ⁠$object_in_group()⁠ and other equivalent. This is because that initialization of an IddObject needs some shared data from parent Idd object.

Details

There are lots of properties for every class and field. For details on the meaning of each property, please see the heading comments in the Energy+.idd file in the EnergyPlus installation path.

Methods

Public methods

• IddObject$new()

• IddObject$version()

• IddObject$parent()

• IddObject$group_name()

• IddObject$group_index()

• IddObject$class_name()

• IddObject$class_index()

• IddObject$class_format()

• IddObject$min_fields()

• IddObject$num_fields()

• IddObject$memo()

• IddObject$num_extensible()

• IddObject$first_extensible_index()

• IddObject$extensible_group_num()

• IddObject$add_extensible_group()

• IddObject$del_extensible_group()

• IddObject$has_name()

• IddObject$is_required()

• IddObject$is_unique()

• IddObject$is_extensible()

• IddObject$field_name()

• IddObject$field_index()

• IddObject$field_type()

• IddObject$field_note()

• IddObject$field_unit()

• IddObject$field_default()

• IddObject$field_choice()

• IddObject$field_range()

• IddObject$field_relation()

• IddObject$field_possible()

• IddObject$is_valid_field_num()

• IddObject$is_extensible_index()

• IddObject$is_valid_field_name()

• IddObject$is_valid_field_index()

• IddObject$is_autosizable_field()

• IddObject$is_autocalculatable_field()

• IddObject$is_numeric_field()

• IddObject$is_real_field()

• IddObject$is_integer_field()

• IddObject$is_required_field()

• IddObject$has_ref()

• IddObject$has_ref_to()

• IddObject$has_ref_by()

• IddObject$outputs()

• IddObject$to_table()

• IddObject$to_string()

• IddObject$print()

Method new()

Create an IddObject object

Usage

IddObject$new(class, parent)

Arguments

Details

Note that an IddObject can be created from the parent Idd object, using ⁠$object()⁠, idd_object and other equivalent.

Returns

An IddObject object.

Examples

\dontrun{
surf <- IddObject$new("BuildingSurface:Detailed", use_idd(8.8, download = "auto"))
}

Method version()

Get the version of parent Idd

Usage

IddObject$version()

Details

⁠$version()⁠ returns the version of parent Idd in a base::numeric_version() format. This makes it easy to direction compare versions of different IddObjects, e.g. iddobj$version() > 8.6 or iddobj1$version() > iddobj2$version().

Returns

A base::numeric_version() object.

Examples

\dontrun{
# get version
surf$version()
}

Method parent()

Get parent Idd

Usage

IddObject$parent()

Details

⁠$parent()⁠ returns parent Idd object.

Returns

A Idd object.

Examples

\dontrun{
surf$parent()
}

Method group_name()

Get the group name

Usage

IddObject$group_name()

Details

⁠$group_name()⁠ returns the group name of current IddObject.

Returns

A single string.

Examples

\dontrun{
surf$group_name()
}

Method group_index()

Get the group index

Usage

IddObject$group_index()

Details

⁠$group_index()⁠ returns the group index of current IddObject. A group index is just an integer indicating its appearance order in the Idd.

Returns

A single integer.

Examples

\dontrun{
surf$group_index()
}

Method class_name()

Get the class name of current IddObject

Usage

IddObject$class_name()

Details

⁠$class_name()⁠ returns the class name of current IddObject.

Returns

A single string.

Examples

\dontrun{
surf$class_name()
}

Method class_index()

Get the class index

Usage

IddObject$class_index()

Details

⁠$class_index()⁠ returns the class index of current IddObject. A class index is just an integer indicating its appearance order in the Idd.

Returns

A single integer.

Examples

\dontrun{
surf$class_index()
}

Method class_format()

Get the class format

Usage

IddObject$class_format()

Details

⁠$class_format()⁠ returns the format of this IDD class. This format indicator is currently not used by eplusr.

Returns

A single character.

Examples

\dontrun{
surf$class_format()
}

Method min_fields()

Get the minimum field number of current class

Usage

IddObject$min_fields()

Details

⁠$min_fields()⁠ returns the minimum fields required for current class. If no required, 0 is returned.

Returns

A single integer.

Examples

\dontrun{
surf$min_fields()
}

Method num_fields()

Get the total field number of current class

Usage

IddObject$num_fields()

Details

⁠$num_fields()⁠ returns current total number of fields in current class.

Returns

A single integer.

Examples

\dontrun{
surf$num_fields()
}

Method memo()

Get the memo string of current class

Usage

IddObject$memo()

Details

⁠$memo()⁠ returns memo of current class, usually a brief description of this class.

Returns

A character vector.

Examples

\dontrun{
surf$memo()
}

Method num_extensible()

Get the field number of the extensible group in current class

Usage

IddObject$num_extensible()

Details

⁠$num_extensible()⁠ returns the field number of the extensible group in current class.

An extensible group is a set of fields that should be treated as a whole, such like the X, Y and Z vertices of a building surfaces. An extensible group should be added or deleted together.

If there is no extensible group in current class, 0 is returned.

Returns

A single integer.

Examples

\dontrun{
surf$num_extensible()
}

Method first_extensible_index()

Get the minimum field number of current class

Usage

IddObject$first_extensible_index()

Details

⁠$first_extensible_index()⁠ returns the field index of first extensible field in current class.

An extensible group is a set of fields that should be treated as a whole, such like the X, Y and Z vertices of a building surfaces. An extensible group should be added or deleted together.

If there is no extensible group in current class, 0 is returned.

Returns

A single integer.

Examples

\dontrun{
surf$first_extensible_index()
}

Method extensible_group_num()

Get the number of extensible groups in current class

Usage

IddObject$extensible_group_num()

Details

⁠$extensible_group_num()⁠ returns the number of extensible groups in current class.

An extensible group is a set of fields that should be treated as a whole, such like the X, Y and Z vertices of a building surfaces. An extensible group should be added or deleted together.

If there is no extensible group in current class, 0 is returned.

Returns

A single integer.

Examples

\dontrun{
surf$extensible_group_num()
}

Method add_extensible_group()

Add extensible groups in current class

Usage

IddObject$add_extensible_group(num = 1L)

Arguments

Details

⁠$add_extensible_groups()⁠ adds extensible groups in this class.

An extensible group is a set of fields that should be treated as a whole, such like the X, Y and Z vertices of a building surfaces. An extensible group should be added or deleted together.

An error will be issued if current class contains no extensible group.

Returns

The modified IddObject itself.

Examples

\dontrun{
# field number before adding
surf$num_fields()
# extensible group number before adding
surf$extensible_group_num()

# add 2 more extensible groups
surf$add_extensible_group(2)

# field number after adding
surf$num_fields()
# extensible group number after adding
surf$extensible_group_num()
}

Method del_extensible_group()

Delete extensible groups in current class

Usage

IddObject$del_extensible_group(num = 1L)

Arguments

Details

⁠$del_extensible_groups()⁠ deletes extensible groups in this class.

An extensible group is a set of fields that should be treated as a whole, such like the X, Y and Z vertices of a building surfaces. An extensible group should be added or deleted together.

An error will be issued if current class contains no extensible group.

Returns

The modified IddObject itself.

Examples

\dontrun{
# field number before deleting
surf$num_fields()
# extensible group number before deleting
surf$extensible_group_num()

# delete 2 more extensible groups
surf$del_extensible_group(2)

# field number after deleting
surf$num_fields()
# extensible group number after deleting
surf$extensible_group_num()
}

Method has_name()

Check if current class has name attribute

Usage

IddObject$has_name()

Details

⁠$has_name()⁠ return TRUE if current class has name attribute, and FALSE otherwise.

A class with name attribute means that objects in this class can have names.

Returns

A single logical value (TRUE or FALSE).

Examples

\dontrun{
surf$has_name()
}

Method is_required()

Check if current class is required

Usage

IddObject$is_required()

Details

⁠$is_required()⁠ returns TRUE if current class is required and FALSE otherwise.

A required class means that for any model, there should be at least one object in this class. One example is Building class.

Returns

A single logical value (TRUE or FALSE).

Examples

\dontrun{
surf$is_required()
}

Method is_unique()

Check if current class is unique

Usage

IddObject$is_unique()

Details

⁠$is_unique()⁠ returns TRUE if current class is unique and FALSE otherwise.

A unique class means that for any model, there should be at most one object in this class. One example is Building class.

Returns

A single logical value (TRUE or FALSE).

Examples

\dontrun{
surf$is_unique()
}

Method is_extensible()

Check if current class is extensible

Usage

IddObject$is_extensible()

Details

⁠$is_extensible()⁠ returns TRUE if current class is extensible and FALSE otherwise.

A extensible class means that for there are curtain number of fields in this class that can be dynamically added or deleted, such like the X, Y and Z vertices of a building surface.

Returns

A single logical value (TRUE or FALSE).

Examples

\dontrun{
surf$is_extensible()
}

Method field_name()

Get field names

Usage

IddObject$field_name(
  index = NULL,
  unit = FALSE,
  in_ip = eplusr_option("view_in_ip")
)

Arguments

Details

⁠$field_name()⁠ returns a character vector of names of fields specified by field indices in current class.

Returns

A character vector.

Examples

\dontrun{
# get all field names
surf$field_name()

# get field units also
surf$field_name(unit = TRUE)

# get field units in IP
surf$field_name(unit = TRUE)

# change field name to lower-style
surf$field_name(unit = TRUE, in_ip = TRUE)
}

Method field_index()

Get field indices

Usage

IddObject$field_index(name = NULL)

Arguments

Details

⁠$field_index()⁠ returns an integer vector of names of fields specified by field names in current class.

Returns

An integer vector.

Examples

\dontrun{
# get all field indices
surf$field_index()

# get field indices for specific fields
surf$field_index(c("number of vertices", "vertex 10 z-coordinate"))
}

Method field_type()

Get field types

Usage

IddObject$field_type(which = NULL)

Arguments

Details

⁠$field_type()⁠ returns a character vector of field types of specified fields in current class. All possible values are:

• "integer"

• "real"

• "alpha" (arbitrary string)

• "choice" (alpha with specific list of choices)

• "object-list" (link to a list of objects defined elsewhere)

• "external-list" (uses a special list from an external source)

• "node" (name used in connecting HVAC components).

Returns

A character vector.

Examples

\dontrun{
# get all field types
surf$field_type()

# get field types for specific fields
surf$field_type(c("name", "zone name", "vertex 10 z-coordinate"))
}

Method field_note()

Get field notes

Usage

IddObject$field_note(which = NULL)

Arguments

Details

⁠$field_note()⁠ returns a list of character vectors that contains field notes of specified fields in current class, usually serving as field descriptions. If no notes are found for current fields, NULL is returned.

Returns

A list of character vectors.

Examples

\dontrun{
# get all field notes
surf$field_note()

# get field types for specific fields
surf$field_note(c("name", "zone name", "vertex 10 z-coordinate"))
}

Method field_unit()

Get field units

Usage

IddObject$field_unit(which = NULL, in_ip = eplusr_option("view_in_ip"))

Arguments

Details

⁠$field_unit()⁠ returns a character vector that contains units of specified fields in current class. If there is no unit found for current field, NA is returned.

Returns

A character vector.

Examples

\dontrun{
# get all field units
surf$field_unit()

# get field units for specific fields
surf$field_unit(c("name", "zone name", "vertex 10 z-coordinate"))
}

Method field_default()

Get field default value

Usage

IddObject$field_default(which = NULL, in_ip = eplusr_option("view_in_ip"))

Arguments

Details

⁠$field_default()⁠ returns a list that contains default values of specified fields in current class. If there is no default value found for current field, NA is returned.

Returns

A character vector.

Examples

\dontrun{
# get all field default values
surf$field_default()

# get default values for specific fields
surf$field_default(c("name", "zone name", "vertex 10 z-coordinate"))
}

Method field_choice()

Get choices of field values

Usage

IddObject$field_choice(which = NULL)

Arguments

Details

⁠$field_value()⁠ returns a list of character vectors that contains choices of specified field values in current class. If there is no choice found for current field, NULL is returned.

Returns

A list of character vectors.

Examples

\dontrun{
# get all field value choices
surf$field_choice()

# get field value choices for specific fields
surf$field_choice(c("name", "sun exposure", "wind exposure"))
}

Method field_range()

Get field value ranges

Usage

IddObject$field_range(which = NULL)

Arguments

Details

⁠$field_range()⁠ returns a list of value ranges of specified fields in current class.

Every range has four components:

• minimum: lower limit

• lower_incbounds: TRUE if the lower limit should be included

• maximum: upper limit

• upper_incbounds: TRUE if the upper limit should be included

For fields of character type,

• minimum and maximum are always set to NA

• lower_incbounds and upper_incbounds are always set to FALSE

For fields of numeric types with no specified ranges,

• minimum is set to -Inf

• lower_incbounds is set to FALSE

• upper is set to Inf

• upper_incbounds is set to FALSE

The field range is printed in number interval denotation.

Returns

A list of ranges.

Examples

\dontrun{
# get all field value ranges
surf$field_range()

# get value ranges for specific fields
surf$field_range(c("name", "number of vertices", "vertex 10 z-coordinate"))
}

Method field_relation()

Extract the relationship among fields

Usage

IddObject$field_relation(
  which = NULL,
  direction = c("all", "ref_by", "ref_to"),
  class = NULL,
  group = NULL,
  depth = 0L,
  keep = FALSE
)

Arguments

Details

Many fields in Idd can be referred by others. For example, the ⁠Outside Layer⁠ and other fields in Construction class refer to the Name field in Material class and other material related classes. Here it means that the ⁠Outside Layer⁠ field refers to the Name field and the Name field is referred by the ⁠Outside Layer⁠.

⁠$field_relation()⁠ provides a simple interface to get this kind of relation. It takes a field specification and a relation direction, and returns an IddRelation object which contains data presenting such relation above.

⁠$field_relation()⁠ returns a list of references for those fields that have the object-list and/or reference and reference-class-name attribute. Basically, it is a list of two elements ref_to and ref_by. Underneath, ref_to and ref_by are data.tables which contain source field data and reference field data with custom printing method. For instance, if iddobj$field_relation(c(1, 2), "ref_to") gives results below:

-- Refer to Others ---------------------
  +- Field: <1: Field 1>
  |  v~~~~~~~~~~~~~~~~~~
  |  \- Class: <Class 2>
  |     \- Field: <2: Field 2>
  |
  \- Field: <2: Field 2>

This means that ⁠Field 2⁠ in current class does not refer to any other fields. But ⁠Field 1⁠ in current class refers to ⁠Field 2⁠ in class named ⁠Class 2⁠.

Returns

An IddRelation object.

Examples

\dontrun{
# get field relation for specific fields
surf$field_relation(c("name", "zone name", "vertex 10 z-coordinate"))
}

Method field_possible()

Get field possible values

Usage

IddObject$field_possible(which = NULL)

Arguments

Details

⁠$field_possible()⁠ returns all possible values for specified fields, including auto-value (Autosize, Autocalculate, and NA if not applicable), and results from ⁠$field_default()⁠, ⁠$field_range()⁠, ⁠$field_choice()⁠. Underneath, it returns a data.table with custom printing method. For instance, if iddobj$field_possible(c(4, 2)) gives results below:

-- 4: Field 4 ----------
* Auto value: <NA>
* Default: <NA>
* Choice:
  - "Key1"
  - "Key2"

-- 2: Field 2 ----------
* Auto value: "Autosize"
* Default: 2
* Choice: <NA>

This means that ⁠Field 4⁠ in current class cannot be "autosized" or "autocalculated", and it does not have any default value. Its value should be a choice from "Key1" or "Key2". For ⁠Field 2⁠ in current class, it has a default value of 2 but can also be filled with value "Autosize".

Returns

A IddFieldPossible object which is a data.table::data.table() with 9 columns.

Examples

\dontrun{
# get field possible values for specific fields
surf$field_possible(6:10)
}

Method is_valid_field_num()

Check if input is a valid field number

Usage

IddObject$is_valid_field_num(num)

Arguments

Details

⁠$is_valid_field_num()⁠ returns TRUE if input num is acceptable as a total number of fields in this class. Extensible property is considered.

For instance, the total number of fields defined in IDD for class BuildingSurfaces:Detailed is 390. However, 396 is still a valid field number for this class as the number of field in the extensible group is 3.

Returns

A logical vector.

Examples

\dontrun{
surf$is_valid_field_num(c(10, 14, 100))
}

Method is_extensible_index()

Check if input field index indicates an extensible field

Usage

IddObject$is_extensible_index(index)

Arguments

Details

⁠$is_extensible_index()⁠ returns TRUE if input index indicates an index of extensible field in current class.

Extensible fields mean that these fields can be dynamically added or deleted, such like the X, Y and Z vertices of a building surface.

Returns

A logical vector.

Examples

\dontrun{
surf$is_extensible_index(c(10, 14, 100))
}

Method is_valid_field_name()

Check if input character is a valid field name

Usage

IddObject$is_valid_field_name(name, strict = FALSE)

Arguments

Details

⁠$is_valid_field_name()⁠ returns TRUE if name is a valid field name WITHOUT unit. Note name can be given in underscore style, e.g. "outside_layer" is equivalent to "Outside Layer".

Returns

A logical vector.

Examples

\dontrun{
surf$is_valid_field_name(c("name", "sun_exposure"))

# exact match
surf$is_valid_field_name(c("Name", "Sun_Exposure"), strict = TRUE)
}

Method is_valid_field_index()

Check if input integer is a valid field index

Usage

IddObject$is_valid_field_index(index)

Arguments

Details

⁠$is_valid_field_index()⁠ returns TRUE if index is a valid field index. For extensible class, TRUE is always returned.

Returns

A logical vector.

Examples

\dontrun{
surf$is_valid_field_index(1:10)
}

Method is_autosizable_field()

Check if input field can be autosized

Usage

IddObject$is_autosizable_field(which = NULL)

Arguments

Details

⁠$is_autosizable_field()⁠ returns TRUE if input field can be assigned to autosize.

Returns

A logical vector.

Examples

\dontrun{
surf$is_autosizable_field()

surf$is_autosizable_field(c("name", "sun_exposure"))
}

Method is_autocalculatable_field()

Check if input field can be autocalculated

Usage

IddObject$is_autocalculatable_field(which = NULL)

Arguments

Details

⁠$is_autocalculatable_field()⁠ returns TRUE if input field can be assigned to autocalculate.

Returns

A logical vector.

Examples

\dontrun{
surf$is_autocalculatable_field()

surf$is_autocalculatable_field(c("name", "sun_exposure"))
}

Method is_numeric_field()

Check if input field value should be numeric

Usage

IddObject$is_numeric_field(which = NULL)

Arguments

Details

⁠$is_numeric_field()⁠ returns TRUE if the value of input field should be numeric ( an integer or a real number).

Returns

A logical vector.

Examples

\dontrun{
surf$is_numeric_field()

surf$is_numeric_field(c("name", "sun_exposure"))
}

Method is_real_field()

Check if input field value should be a real number

Usage

IddObject$is_real_field(which = NULL)

Arguments

Details

⁠$is_real_field()⁠ returns TRUE if the field value should be a real number but not an integer.

Returns

A logical vector.

Examples

\dontrun{
surf$is_real_field()

surf$is_real_field(c("name", "number of vertices"))
}

Method is_integer_field()

Check if input field value should be an integer

Usage

IddObject$is_integer_field(which = NULL)

Arguments

Details

⁠$is_real_field()⁠ returns TRUE if the field value should be an integer.

Returns

A logical vector.

Examples

\dontrun{
surf$is_integer_field()

surf$is_integer_field(c("name", "number of vertices"))
}

Method is_required_field()

Check if input field is required

Usage

IddObject$is_required_field(which = NULL)

Arguments

Details

⁠$is_required_field()⁠ returns TRUE if the field is required.

Returns

A logical vector.

Examples

\dontrun{
surf$is_required_field()

surf$is_required_field(c("name", "number of vertices"))
}

Method has_ref()

Check if input field can refer to or can be referred by other fields

Usage

IddObject$has_ref(which = NULL, class = NULL, group = NULL, depth = 0L)

Arguments

Details

⁠$has_ref()⁠ returns TRUE if input field refers to or can be referred by other fields.

Returns

A logical vector.

Examples

\dontrun{
surf$has_ref()

surf$has_ref(c("name", "zone name"))
}

Method has_ref_to()

Check if input field can refer to other fields

Usage

IddObject$has_ref_to(which = NULL, class = NULL, group = NULL, depth = 0L)

Arguments

Details

⁠$has_ref_to()⁠ returns TRUE if input field can refer to other fields.

Returns

A logical vector.

Examples

\dontrun{
surf$has_ref_to()

surf$has_ref_to(c("name", "zone name"))
}

Method has_ref_by()

Check if input field can be referred by other fields

Usage

IddObject$has_ref_by(which = NULL, class = NULL, group = NULL, depth = 0L)

Arguments

Details

⁠$has_ref_by()⁠ returns TRUE if input field can be referred by other fields.

Returns

A logical vector.

Examples

\dontrun{
surf$has_ref_by()

surf$has_ref_by(c("name", "zone name"))
}

Method outputs()

Get possible output variables for current class

Usage

IddObject$outputs()

Details

⁠$outputs()⁠ returns a data.table that gives all possible outputs for current class. The returned data.table has 6 columns:

*index: Integer. Index of each variable. *class: Character. Name of current class.

• reported_time_step: Character. Reported time step for the variables. Possible value: Zone and HVAC.

• report_type: Character. Report types. Possible value: Average, Sum.

• variable: Character. Report variable names.

• units: Character. Units of reported values. NA if report values do not have units.

Returns

A data.table with 6 columns.

Examples

\dontrun{
surf$outputs()
}

Method to_table()

Format an IddObject as a data.frame

Usage

IddObject$to_table(all = FALSE)

Arguments

Details

⁠$to_table()⁠ returns a data.table that contains basic data of current class. The returned data.table has 3 columns:

• class: Character type. Current class name.

• index: Integer type. Field indexes.

• field: Character type. Field names.

Returns

A data.table with 3 columns.

Examples

\dontrun{
surf$to_table()

surf$to_table(TRUE)
}

Method to_string()

Format an IdfObject as a character vector

Usage

IddObject$to_string(comment = NULL, leading = 4L, sep_at = 29L, all = FALSE)

Arguments

Details

⁠$to_string()⁠ returns the text format of current class. The returned character vector can be pasted into an IDF file as an empty object of specified class.

Returns

A character vector.

Examples

\dontrun{
# get text format of class BuildingSurface:Detailed
surf$to_string()

# tweak output formatting
surf$to_string(leading = 0, sep_at = 0)

# add comments
surf$to_string(c("This", "will", "be", "comments"))
}

Method print()

Print IddObject object

Usage

IddObject$print(brief = FALSE)

Arguments

Details

⁠$print()⁠ prints the IddObject object giving the information of class name, class properties, field indices and field names.

⁠$print()⁠ prints the IddObject. Basically, the print output can be divided into 4 parts:

• CLASS: IDD class name of current object in format ⁠<IddObject: CLASS>⁠.

• MEMO: brief description of the IDD class.

• PROPERTY: properties of the IDD class, including name of group it belongs to, whether it is an unique or required class and current total fields. The fields may increase if the IDD class is extensible, such as Branch, ZoneList and etc.

• FIELDS: fields of current IDD class. Required fields are marked with stars (*). If the class is extensible, only the first extensible group will be printed and two ellipses will be shown at the bottom. Fields in the extensible group will be marked with an arrow down surrounded by angle brackets (⁠<v>⁠).

Returns

The IddObject object itself, invisibly.

Examples

\dontrun{
surf

surf$print(brief = TRUE)
}

Note

Some classes have special format when saved in the IDFEditor with the special format option enabled. Those special format includes "singleLine", "vertices", "compactSchedule", "fluidProperties", "viewFactors" and "spectral". eplusr can handle all those format when parsing IDF files. However, when saved, all classes are formatted in standard way.

This number may change if the class is extensible and after ⁠$add_extensible_group()⁠ or ⁠$del_extensible_group()⁠.

The type of each default value will be consistent with field definition. However, for numeric fields with default values being "autosize" or "autocalculate", the type of returned values will be character.

All outputs are extracted from the LaTeX source file of "Input Output Reference" for EnergyPlus v9.5.0 and later. So empty result will always be returned for Idd version lower than v9.5.

It is possible that there are some mistakes introduced when extracting the output variables. Also, some outputs are only available if certain fields are set. Even they are listed in the results, it does not mean that the Idf can report all of them. It is strongly suggested to check the RDD and MDD file for correctness.

Author(s)

Hongyuan Jia

See Also

Idd Class

Examples

## ------------------------------------------------
## Method `IddObject$new`
## ------------------------------------------------

## Not run: 
surf <- IddObject$new("BuildingSurface:Detailed", use_idd(8.8, download = "auto"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$version`
## ------------------------------------------------

## Not run: 
# get version
surf$version()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$parent`
## ------------------------------------------------

## Not run: 
surf$parent()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$group_name`
## ------------------------------------------------

## Not run: 
surf$group_name()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$group_index`
## ------------------------------------------------

## Not run: 
surf$group_index()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$class_name`
## ------------------------------------------------

## Not run: 
surf$class_name()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$class_index`
## ------------------------------------------------

## Not run: 
surf$class_index()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$class_format`
## ------------------------------------------------

## Not run: 
surf$class_format()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$min_fields`
## ------------------------------------------------

## Not run: 
surf$min_fields()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$num_fields`
## ------------------------------------------------

## Not run: 
surf$num_fields()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$memo`
## ------------------------------------------------

## Not run: 
surf$memo()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$num_extensible`
## ------------------------------------------------

## Not run: 
surf$num_extensible()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$first_extensible_index`
## ------------------------------------------------

## Not run: 
surf$first_extensible_index()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$extensible_group_num`
## ------------------------------------------------

## Not run: 
surf$extensible_group_num()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$add_extensible_group`
## ------------------------------------------------

## Not run: 
# field number before adding
surf$num_fields()
# extensible group number before adding
surf$extensible_group_num()

# add 2 more extensible groups
surf$add_extensible_group(2)

# field number after adding
surf$num_fields()
# extensible group number after adding
surf$extensible_group_num()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$del_extensible_group`
## ------------------------------------------------

## Not run: 
# field number before deleting
surf$num_fields()
# extensible group number before deleting
surf$extensible_group_num()

# delete 2 more extensible groups
surf$del_extensible_group(2)

# field number after deleting
surf$num_fields()
# extensible group number after deleting
surf$extensible_group_num()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$has_name`
## ------------------------------------------------

## Not run: 
surf$has_name()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_required`
## ------------------------------------------------

## Not run: 
surf$is_required()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_unique`
## ------------------------------------------------

## Not run: 
surf$is_unique()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_extensible`
## ------------------------------------------------

## Not run: 
surf$is_extensible()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_name`
## ------------------------------------------------

## Not run: 
# get all field names
surf$field_name()

# get field units also
surf$field_name(unit = TRUE)

# get field units in IP
surf$field_name(unit = TRUE)

# change field name to lower-style
surf$field_name(unit = TRUE, in_ip = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_index`
## ------------------------------------------------

## Not run: 
# get all field indices
surf$field_index()

# get field indices for specific fields
surf$field_index(c("number of vertices", "vertex 10 z-coordinate"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_type`
## ------------------------------------------------

## Not run: 
# get all field types
surf$field_type()

# get field types for specific fields
surf$field_type(c("name", "zone name", "vertex 10 z-coordinate"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_note`
## ------------------------------------------------

## Not run: 
# get all field notes
surf$field_note()

# get field types for specific fields
surf$field_note(c("name", "zone name", "vertex 10 z-coordinate"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_unit`
## ------------------------------------------------

## Not run: 
# get all field units
surf$field_unit()

# get field units for specific fields
surf$field_unit(c("name", "zone name", "vertex 10 z-coordinate"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_default`
## ------------------------------------------------

## Not run: 
# get all field default values
surf$field_default()

# get default values for specific fields
surf$field_default(c("name", "zone name", "vertex 10 z-coordinate"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_choice`
## ------------------------------------------------

## Not run: 
# get all field value choices
surf$field_choice()

# get field value choices for specific fields
surf$field_choice(c("name", "sun exposure", "wind exposure"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_range`
## ------------------------------------------------

## Not run: 
# get all field value ranges
surf$field_range()

# get value ranges for specific fields
surf$field_range(c("name", "number of vertices", "vertex 10 z-coordinate"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_relation`
## ------------------------------------------------

## Not run: 
# get field relation for specific fields
surf$field_relation(c("name", "zone name", "vertex 10 z-coordinate"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$field_possible`
## ------------------------------------------------

## Not run: 
# get field possible values for specific fields
surf$field_possible(6:10)

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_valid_field_num`
## ------------------------------------------------

## Not run: 
surf$is_valid_field_num(c(10, 14, 100))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_extensible_index`
## ------------------------------------------------

## Not run: 
surf$is_extensible_index(c(10, 14, 100))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_valid_field_name`
## ------------------------------------------------

## Not run: 
surf$is_valid_field_name(c("name", "sun_exposure"))

# exact match
surf$is_valid_field_name(c("Name", "Sun_Exposure"), strict = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_valid_field_index`
## ------------------------------------------------

## Not run: 
surf$is_valid_field_index(1:10)

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_autosizable_field`
## ------------------------------------------------

## Not run: 
surf$is_autosizable_field()

surf$is_autosizable_field(c("name", "sun_exposure"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_autocalculatable_field`
## ------------------------------------------------

## Not run: 
surf$is_autocalculatable_field()

surf$is_autocalculatable_field(c("name", "sun_exposure"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_numeric_field`
## ------------------------------------------------

## Not run: 
surf$is_numeric_field()

surf$is_numeric_field(c("name", "sun_exposure"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_real_field`
## ------------------------------------------------

## Not run: 
surf$is_real_field()

surf$is_real_field(c("name", "number of vertices"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_integer_field`
## ------------------------------------------------

## Not run: 
surf$is_integer_field()

surf$is_integer_field(c("name", "number of vertices"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$is_required_field`
## ------------------------------------------------

## Not run: 
surf$is_required_field()

surf$is_required_field(c("name", "number of vertices"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$has_ref`
## ------------------------------------------------

## Not run: 
surf$has_ref()

surf$has_ref(c("name", "zone name"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$has_ref_to`
## ------------------------------------------------

## Not run: 
surf$has_ref_to()

surf$has_ref_to(c("name", "zone name"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$has_ref_by`
## ------------------------------------------------

## Not run: 
surf$has_ref_by()

surf$has_ref_by(c("name", "zone name"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$outputs`
## ------------------------------------------------

## Not run: 
surf$outputs()

## End(Not run)


## ------------------------------------------------
## Method `IddObject$to_table`
## ------------------------------------------------

## Not run: 
surf$to_table()

surf$to_table(TRUE)

## End(Not run)


## ------------------------------------------------
## Method `IddObject$to_string`
## ------------------------------------------------

## Not run: 
# get text format of class BuildingSurface:Detailed
surf$to_string()

# tweak output formatting
surf$to_string(leading = 0, sep_at = 0)

# add comments
surf$to_string(c("This", "will", "be", "comments"))

## End(Not run)


## ------------------------------------------------
## Method `IddObject$print`
## ------------------------------------------------

## Not run: 
surf

surf$print(brief = TRUE)

## End(Not run)

Read, Modify, and Run an EnergyPlus Model

Description

eplusr provides parsing EnergyPlus Input Data File (IDF) files and strings in a hierarchical structure, which was extremely inspired by OpenStudio utilities library, but with total different data structure under the hook.

Details

eplusr uses Idf class to present the whole IDF file and use IdfObject to present a single object in IDF. Both Idf and IdfObject contain member functions for helping modify the data in IDF so it complies with the underlying IDD (EnergyPlus Input Data Dictionary).

Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD data in different data.table::data.tables. So to modify an EnergyPlus model in eplusr is equal to change the data in those IDF tables accordingly, in the context of specific IDD data. This means that a corresponding Idd object is needed whenever creating an Idf object. eplusr provides several helpers to easily download IDD files and create Idd objects.

All IDF reading process starts with function read_idf() which returns an Idf object. Idf class provides lots of methods to programmatically query and modify EnergyPlus models.

Internally, the powerful data.table package is used to speed up the whole IDF parsing process and store the results. Under the hook, eplusr uses a SQL-like structure to store both IDF and IDD data in data.table::data.table format. Every IDF will be parsed and stored in three tables:

• object: contains object IDs, names and comments.

• value: contains field values

• reference: contains cross-reference data of field values.

Methods

Public methods

• Idf$new()

• Idf$version()

• Idf$path()

• Idf$group_name()

• Idf$class_name()

• Idf$is_valid_group()

• Idf$is_valid_class()

• Idf$definition()

• Idf$object_id()

• Idf$object_name()

• Idf$object_num()

• Idf$is_valid_id()

• Idf$is_valid_name()

• Idf$object()

• Idf$objects()

• Idf$object_unique()

• Idf$objects_in_class()

• Idf$objects_in_group()

• Idf$object_relation()

• Idf$objects_in_relation()

• Idf$search_object()

• Idf$dup()

• Idf$add()

• Idf$set()

• Idf$del()

• Idf$purge()

• Idf$duplicated()

• Idf$unique()

• Idf$rename()

• Idf$insert()

• Idf$load()

• Idf$update()

• Idf$paste()

• Idf$search_value()

• Idf$replace_value()

• Idf$validate()

• Idf$is_valid()

• Idf$to_string()

• Idf$to_table()

• Idf$external_deps()

• Idf$is_unsaved()

• Idf$save()

• Idf$run()

• Idf$last_job()

• Idf$geometry()

• Idf$view()

• Idf$print()

• Idf$clone()

Method new()

Create an Idf object

Usage

Idf$new(path, idd = NULL, encoding = "unknown")

Arguments

Details

It takes an EnergyPlus Input Data File (IDF) as input and returns an Idf object.

Currently, Imf file is not fully supported. All EpMacro lines will be treated as normal comments of the nearest downwards object. If input is an Imf file, a warning will be given during parsing. It is recommended to convert the Imf file to an Idf file and use ParametricJob class to conduct parametric analysis.

Returns

An Idf object.

Examples

\dontrun{
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8

# If neither EnergyPlus v8.8 nor Idd v8.8 was found, error will
# occur. If Idd v8.8 is found, it will be used automatically.
idf <- Idf$new(path_idf)

# argument `idd` can be specified explicitly using `use_idd()`
idf <- Idf$new(path_idf, idd = use_idd(8.8))

# you can set `download` arugment to "auto" in `use_idd()` if you
# want to automatically download corresponding IDD file when
# necessary
idf <- Idf$new(path_idf, use_idd(8.8, download = "auto"))

# Besides use a path to an IDF file, you can also provide IDF in literal
# string format
string_idf <-
    "
    Version, 8.8;
    Building,
        Building;                !- Name
    "

Idf$new(string_idf, use_idd(8.8, download = "auto"))
}

Method version()

Get the version of current Idf

Usage

Idf$version()

Details

⁠$version()⁠ returns the version of current Idf in a base::numeric_version() format. This makes it easy to direction compare versions of different Idfs, e.g. idf$version() > 8.6 or idf1$version() > idf2$version().

Returns

A base::numeric_version() object.

Examples

\dontrun{
# get version
idf$version()
}

Method path()

Get the file path of current Idf

Usage

Idf$path()

Details

⁠$path()⁠ returns the full path of current Idf or NULL if the Idf object is created using a character vector and not saved locally.