Learn R Programming
⚠️There's a newer version (0.16.2) of this package.Take me there.

eplusr

A Toolkit for Using EnergyPlus in R.

eplusr provides a rich toolkit of using whole building energy simulation program EnergyPlus directly in R, which enables programmatic navigation, modification of EnergyPlus models and makes it less painful to do parametric simulations and analysis. More information about EnergyPlus can be found at its website.

A comprehensive introduction to eplusr can be found using vignette("eplusr"). You can learn more about eplusr at https://hongyuanjia.github.io/eplusr, along with full package documentation.

Installation

You can install the latest stable release of eplusr from CRAN.

install.packages("eplusr")

Alternatively, you can install the development version from GitHub.

# install.packages("devtools")
devtools::install_github("hongyuanjia/eplusr")

Since running the IDF files requires EnergyPlus (https://energyplus.net), EnergyPlus has to be installed if you want to run EnergyPlus models in R. There are helper functions in eplusr to download and install it automatically on major operating systems (Windows, macOS and Linux):

# install the latest version (currently v9.0.0)
eplusr::install_eplus("latest")

# OR download the latest version (currently v9.0.0) and run the installer
# manually by yourself
eplusr::download_eplus("latest", dir = tempdir())

Note that the installation process in install_eplus() requires administrative privileges. You have to run R with administrator (or with sudo if you are on macOS or Linux) to make it work if you are not in interactive mode.

Features

  • Read, parse and modify EnergyPlus Weather File (EPW)
  • Read, parse and modify EnergyPlus Input Data File (IDF)
  • Query on models, including classes, objects and fields
  • Directly add, modify, duplicate, insert, and delete objects of IDF
  • Automatically change referenced fields when modifying objects
  • Save changed models into standard formats in the same way as IDFEditor distributed along with EnergyPlus
  • Run your models and collect the simulation output
  • Conduct parametric energy simulations and collect all results in one go

Usage overview

Class structure

Below shows the class structure in eplusr.

Basically, eplusr uses Idf class to present the whole IDF file and IdfObject class to present a single object in an IDF. Both Idf and IdfObject class contain member functions for helping modify the data in IDF so it complies with the underlying EnergyPlus IDD (Input Data Dictionary). Similarly, IDD file is wrapped into two classes, i.e. Idd and IddObject.

Besides, Epw class is used to present EnergyPlus Weather files; EplusJob to run single EnergyPlus simulation and collect outputs, ParametricJob to run parametric EnergyPlus simulations and collect all outputs.

It is highly recommended to read the documentation to get a thorough understanding on each class.

Getting started

library(eplusr)

idd <- use_idd(8.8, download = "auto")
#> Idd v8.8.0 has not been parsed before. Try to locate `Energy+.idd` in EnergyPlus v8.8.0 installation folder `C:/EnergyPlusV8-8-0`.
#> IDD file found: `C:\EnergyPlusV8-8-0\Energy+.idd`.
#> Start parsing...
#> 
  Parsing IDD (Parsing ) [======>---------------------------]  20% in  0s
  Parsing IDD (Parsing ) [=========>------------------------]  30% in  0s
  Parsing IDD (Parsing ) [=============>--------------------]  40% in  0s
  Parsing IDD (Parsing ) [================>-----------------]  50% in  1s
  Parsing IDD (Parsing ) [===================>--------------]  60% in  2s
  Parsing IDD (Parsing ) [==========================>-------]  80% in  3s
  Parsing IDD (Parsing ) [===============================>--]  95% in  3s
  Parsing IDD (Complete) [==================================] 100% in  3s

model <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"))

model
#> == EnergPlus Input Data File ==============================================
#> * Path: `C:\Users\hongy\R\eplusr\extdata\1ZoneUncontrolled.idf`
#> * Version: `8.8`
#> 
#> Group: `Simulation Parameters`
#> ---------------------------------------------------------------------------
#> [01] Version
#> [01] SimulationControl
#> [01] Building
#> [01] SurfaceConvectionAlgorithm:Inside
#> [01] SurfaceConvectionAlgorithm:Outside
#> [01] HeatBalanceAlgorithm
#> [01] Timestep
#> 
#> Group: `Location and Climate`
#> ---------------------------------------------------------------------------
#> [01] Site:Location
#> [02] SizingPeriod:DesignDay
#> [01] RunPeriod
#> 
#> Group: `Schedules`
#> ---------------------------------------------------------------------------
#> [02] ScheduleTypeLimits
#> [01] Schedule:Constant
#> 
#> Group: `Surface Construction Elements`
#> ---------------------------------------------------------------------------
#> [01] Material
#> [02] Material:NoMass
#> [03] Construction
....

model$Material_NoMass$R13LAYER
#> IdfObject <<[ID:12] `R13LAYER`>>`Material:NoMass`
#> -------------------------------- * VALUES * -------------------------------
#> *1: R13LAYER,          !- Name
#> *2: Rough,             !- Roughness
#> *3: 2.290965,          !- Thermal Resistance {m2-K/W}
#>  4: 0.9,               !- Thermal Absorptance
#>  5: 0.75,              !- Solar Absorptance
#>  6: 0.75;              !- Visible Absorptance
#> ---------------------------------------------------------------------------

model$RunPeriod[[1]][c("Begin Month", "End Month")]
#> $Begin_Month
#> [1] 1
#> 
#> $End_Month
#> [1] 12

model$add_object("RunPeriod",
    list(name = "run_period", begin_month = 3, begin_day_of_month = 1,
         end_month = 4, end_day_of_month = 1))
#> $run_period
#> IdfObject <<[ID:54] `run_period`>>`RunPeriod`
#> -------------------------------- * VALUES * -------------------------------
#>   1: run_period,        !- Name
#> * 2: 3,                 !- Begin Month
#> * 3: 1,                 !- Begin Day of Month
#> * 4: 4,                 !- End Month
#> * 5: 1,                 !- End Day of Month
#>   6: UseWeatherFile,    !- Day of Week for Start Day
#>   7: Yes,               !- Use Weather File Holidays and Special Days
#>   8: Yes,               !- Use Weather File Daylight Saving Period
#>   9: No,                !- Apply Weekend Holiday Rule
#>  10: Yes,               !- Use Weather File Rain Indicators
#>  11: Yes;               !- Use Weather File Snow Indicators
#> ---------------------------------------------------------------------------

model$Construction$FLOOR$possible_value("Outside Layer")
#> -- 2: Field `Outside Layer` -----------------------------------------------
#> * References:
#>   - `R13LAYER`
#>   - `R31LAYER`
#>   - `C5 - 4 IN HW CONCRETE`

model$save(file.path(tempdir(), "model.idf"), overwrite = TRUE)

job <- model$run(
    weather = file.path(eplus_config(8.8)$dir, "WeatherData/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"),
    dir = NULL)
#> -- Info -------------------------------------------------------------------
#> Adding object `Output:SQLite` and setting `Option Type` to `SimpleAndTabular`.
#> 
#> -- Info -------------------------------------------------------------------
#> Replace the existing file located  at C:\Users\hongy\AppData\Local\Temp\Rtmp4Ub7Cl\model.idf.
#> 
#> EnergyPlus Starting
#> EnergyPlus, Version 8.8.0-7c3bbe4830, YMD=2018.08.30 19:52
#> Processing Data Dictionary
#> Processing Input File
#> Initializing Simulation
#> Reporting Surfaces
#> Beginning Primary Simulation
#> Initializing New Environment Parameters
#> Warming up {1}
#> Warming up {2}
#> Warming up {3}
#> Warming up {4}
#> Warming up {5}
#> Warming up {6}
#> Warming up {7}
#> Warming up {8}
#> Warming up {9}
#> Warming up {10}
#> Warming up {11}
#> Warming up {12}
#> Warming up {13}
#> Warming up {14}
#> Warming up {15}
#> Warming up {16}
....

job$errors()
#> 
#> +-------------------------------------------------------------------------+
#> |Warning[1/3] Weather file location will be used rather than entered (IDF)|
#> |Location object.                                                         |
#> |..Location object=DENVER CENTENNIAL GOLDEN N_CO_USA DESIGN_CONDITIONS    |
#> |..Weather File Location=San Francisco Intl Ap CA USA TMY3 WMO#=724940    |
#> |..due to location differences, Latitude difference=[2.12] degrees,       |
#> |Longitude difference=[17.22] degrees.                                    |
#> |..Time Zone difference=[1.0] hour(s), Elevation difference=[99.89]       |
#> |percent, [1827.00] meters.                                               |
#> |                                                                         |
#> |Warning[2/3] SetUpDesignDay: Entered DesignDay Barometric Pressure=81198 |
#> |differs by more than 10% from Standard Barometric Pressure=101301.       |
#> |...occurs in DesignDay=DENVER CENTENNIAL GOLDEN N ANN HTG 99% CONDNS DB, |
#> |Standard Pressure (based on elevation) will be used.                     |
#> |                                                                         |
#> |Warning[3/3] SetUpDesignDay: Entered DesignDay Barometric Pressure=81198 |
#> |differs by more than 10% from Standard Barometric Pressure=101301.       |
#> |...occurs in DesignDay=DENVER CENTENNIAL GOLDEN N ANN CLG 1% CONDNS      |
#> |DB=>MWB, Standard Pressure (based on elevation) will be used.            |
#> +-------------------------------------------------------------------------+
#> 
#> EnergyPlus completed successfully with 3 Warning.

job$report_data(name = "EnergyTransfer:Facility", case = "example")
#>          Case            DateTime KeyValue                    Name Units
#>    1: example 2018-01-01 01:00:00          EnergyTransfer:Facility     J
#>    2: example 2018-01-01 02:00:00          EnergyTransfer:Facility     J
#>    3: example 2018-01-01 03:00:00          EnergyTransfer:Facility     J
#>    4: example 2018-01-01 04:00:00          EnergyTransfer:Facility     J
#>    5: example 2018-01-01 05:00:00          EnergyTransfer:Facility     J
#>   ---                                                                   
#> 9572: example 2018-12-31 20:00:00          EnergyTransfer:Facility     J
#> 9573: example 2018-12-31 21:00:00          EnergyTransfer:Facility     J
#> 9574: example 2018-12-31 22:00:00          EnergyTransfer:Facility     J
#> 9575: example 2018-12-31 23:00:00          EnergyTransfer:Facility     J
#> 9576: example 2019-01-01 00:00:00          EnergyTransfer:Facility     J
#>       Value
#>    1:     0
#>    2:     0
#>    3:     0
#>    4:     0
#>    5:     0
#>   ---      
#> 9572:     0
#> 9573:     0
#> 9574:     0
#> 9575:     0
#> 9576:     0

Acknowledgements

I would like to thank many open source projects who have heavily inspired the development of eplusr package, especially these below:

Author

Hongyuan Jia

Faculty of Urban Construction and Environmental Engineering, Chongqing University

License

The project is released under the terms of the GPLv3.

Copyright © 2016-2018 Hongyuan Jia

Copy Link

Version

Install

install.packages('eplusr')

Monthly Downloads

724

Version

0.9.4

License

MIT + file LICENSE

Issues

34

Pull Requests

1

Stars

69

Forks

13

Maintainer

Hongyuan Jia

Last Published

December 5th, 2018

Functions in eplusr (0.9.4)

install_eplus

Download and Install EnergyPlus
read_idf

Read an EnergyPlus Input Data File (IDF)
use_idd

Use a specific EnergyPlus Input Data Dictionary (IDD) file
use_eplus

Configure which version of EnergyPlus to use
run_idf

Run simulations of EnergyPlus models.
Idf

Read, modify, and run an EnergyPlus model
param_job

Create An EnergyPlus Parametric Simulation Job
EplusSql

Retrieve Simulation Outputs Using EnergyPlus SQLite Output File
EplusJob

Run EnergyPlus Simulation and Collect Outputs
eplus_job

Create an EnergyPlus Simulation Job
eplus_sql

Read an Energy SQLite Output File
eplusr-package

eplusr: A Toolkit for Using EnergyPlus in R
eplusr_option

Get and Set eplusr options
clean_wd

Clean working directory of a previous EnergyPlus simulation
download_weather

Download EnergyPlus Weather File (EPW) and Design Day File (DDY)
read_epw

Read and Parse EnergyPlus Weather File (EPW)
IdfObject

EnergyPlus IDF object
IddObject

EnergyPlus IDD object
ParametricJob

Create and Run Parametric Analysis, and Collect Results
Epw

Read, and modify an EnergyPlus Weather File (EPW)
Idd

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