R build status codecov CRAN_Status_Badge CRAN Checks CRAN Download Badge

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, conducts parametric simulations and retrieves outputs. More information about EnergyPlus can be found at its website.

A comprehensive introduction to eplusr can be found using vignette("eplusr"). There is also an online slides here (Interfacing EnergyPlus Using R). You can learn more about eplusr at https://hongyuanjia.github.io/eplusr/, along with full package documentation.

How to cite

#> To cite eplusr in publications use:
#>   Hongyuan Jia, Adrian Chong (2021). eplusr: A framework for
#>   integrating building energy simulation and data-driven analytics.
#>   Energy and Buildings 237: 110757.
#>   https://doi.org/10.1016/j.enbuild.2021.110757
#> A BibTeX entry for LaTeX users is
#>   @Article{,
#>     title = {eplusr: A framework for integrating building energy simulation and data-driven analytics},
#>     author = {Hongyuan Jia and Adrian Chong},
#>     year = {2020},
#>     journal = {Energy and Buildings},
#>     volume = {237},
#>     url = {https://CRAN.R-project.org/package=eplusr},
#>     doi = {10.1016/j.enbuild.2021.110757},
#>   }


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


Alternatively, you can install the development version from GitHub.

install.packages("eplusr", repos = "https://hongyuanjia.r-universe.dev")

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 v23.1.0)

# OR download the latest version (currently v23.1.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.


View IDF geometry in 3D

Turn RStudio into a model editor via autocompletion

Query and modify weather file

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




Please see these vignettes and articles about {eplusr}


Additional resources


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


Hongyuan Jia and Adrian Chong


The project is released under the terms of MIT License.

Copyright © 2016-2023 Hongyuan Jia and Adrian Chong

Please note that the ‘eplusr’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.