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.
https://github.com/hongyuanjia/eplusr

Category: Consumption
Sub Category: Buildings and Heating

Keywords

energy-simulation energyplus energyplus-models eplus epw idd idf parametric-simulation r r6 simulation

Last synced: about 2 hours ago
JSON representation

Repository metadata

A Toolkit for Using EnergyPlus in R.

README.Rmd

          ---
output:
  github_document
---



```{r setup, include = FALSE}
library(knitr)

# the default output hook
hook_output <- knitr::knit_hooks$get("output")
knitr::knit_hooks$set(output = function(x, options) {
    if (!is.null(n <- options$out.lines)) {
        x <- unlist(strsplit(x, "\n", fixed = TRUE))
        if (length(x) > n) {
            # truncate the output
            x <- c(head(x, n), "....", "")
        } else {
            x <- c(x, "")
        }
        x <- paste(x, collapse = "\n") # paste first n lines together
    }
    hook_output(x, options)
})

knitr::opts_knit$set(root.dir = tempdir())
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    fig.path = "README-"
)

# Make sure the date is shown in English format not Chinese.
invisible(Sys.setlocale(category = "LC_TIME", locale = "en_US.UTF-8"))
```

# eplusr 


[![R build status](https://github.com/hongyuanjia/eplusr/workflows/R-CMD-check/badge.svg)](https://github.com/hongyuanjia/eplusr/actions)
[![codecov](https://codecov.io/gh/hongyuanjia/eplusr/branch/master/graph/badge.svg?token=HoBA0Qm6k2)](https://app.codecov.io/gh/hongyuanjia/eplusr)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/eplusr)](https://cran.r-project.org/package=eplusr)
[![CRAN Checks](https://badges.cranchecks.info/worst/eplusr.svg)](https://badges.cranchecks.info/worst/eplusr.svg)
[![CRAN Download Badge](https://cranlogs.r-pkg.org/badges/eplusr)](https://cran.r-project.org/package=eplusr)


> A Toolkit for Using EnergyPlus in R.

eplusr provides a rich toolkit of using whole building energy simulation program
[EnergyPlus](https://energyplus.net) 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](https://energyplus.net).

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

## How to cite

```{r}
citation("eplusr")
```

## Installation

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

```{r cran-install, eval = FALSE}
install.packages("eplusr")
```

Alternatively, you can install the development version from GitHub.

```{r gh-installation, eval = FALSE}
install.packages("eplusr",
    repos = c(
        hongyuanjia = "https://hongyuanjia.r-universe.dev",
        cran = "https://cran.r-project.org"
    )
)
```

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):

```{r eplus-install, eval = FALSE}
# install the latest version (currently v23.1.0)
eplusr::install_eplus("latest")

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

## Features

* Download, 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 which is more than
  [20X](https://hongyuanjia.github.io/eplusr/articles/transition.html)
  faster than VersionUpdater distributed with EnergyPlus
* Fast 3D geometry visualization

**View IDF geometry in 3D**\
```{r, echo = FALSE, out.width = "60%"}
knitr::include_graphics("https://github.com/hongyuanjia/eplusr/blob/master/tools/figures/view_geometry.gif?raw=true")
```

**Turn RStudio into a model editor via autocompletion**\
```{r, echo = FALSE, out.width = "60%"}
knitr::include_graphics("https://github.com/hongyuanjia/eplusr/blob/master/tools/figures/autocomplete.gif?raw=true")
```

**Query and modify weather file**\
```{r, echo = FALSE, out.width = "60%"}
knitr::include_graphics("https://github.com/hongyuanjia/eplusr/blob/master/tools/figures/epw.gif?raw=true")
```

**Query output via SQL in Tidy format which is much better for data analysis**\
```{r, echo = FALSE, out.width = "60%"}
knitr::include_graphics("https://github.com/hongyuanjia/eplusr/blob/master/tools/figures/job.gif?raw=true")
```

## Resources

### Articles

* Hongyuan Jia, Adrian Chong (2020). eplusr: A framework for integrating
  building energy simulation and data-driven analytics. doi:
  10.13140/RG.2.2.34326.16966
  - [Source code and data to reproduce figures in the article](https://github.com/ideas-lab-nus/eplusr-paper)

### Vignettes

Please see these vignettes and articles about {eplusr}

* [Introduction to eplusr](https://hongyuanjia.github.io/eplusr/articles/eplusr.html)
* [Run simulation and data exploration](https://hongyuanjia.github.io/eplusr/articles/job.html)
* [Parametric simulations](https://hongyuanjia.github.io/eplusr/articles/param.html)
* [Update IDF version](https://hongyuanjia.github.io/eplusr/articles/transition.html)
* [Work with weather files](https://hongyuanjia.github.io/eplusr/articles/epw.html)
* [Work with `Schedule:Compact` objects](https://hongyuanjia.github.io/eplusr/articles/schedule.html)
* [Work with geometries](https://hongyuanjia.github.io/eplusr/articles/geom.html)
* [Frequently asked questions](https://hongyuanjia.github.io/eplusr/articles/faq.html)

### Slides

* [Slides: Interfacing EnergyPlus using R](https://hongyuanjia.github.io/eplusrIntro/)

## Additional resources

* eplusr manual: https://hongyuanjia.github.io/eplusr/
* eplusr Docker image: https://github.com/hongyuanjia/eplusr-docker
* [epwshiftr](https://CRAN.R-project.org/package=epwshiftr) for creating future
  EnergyPlus weather files using CMIP6 data
* [epluspar](https://github.com/hongyuanjia/epluspar) for conducting parametric
  analysis on EnergyPlus models, including sensitivity analysis, Bayesian
  calibration and optimization.

## Acknowledgment

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

* [EnergyPlus](https://energyplus.net): A whole building energy simulation
  program.
* [OpenStudio](https://openstudio.net): A cross-platform collection of
  software tools to support whole building energy modeling using EnergyPlus and
  advanced daylight analysis using Radiance.
* [eppy](https://github.com/santoshphilip/eppy): Scripting language for E+,
  EnergyPlus.
* [JEplus](http://www.jeplus.org): An EnergyPlus simulation manager for
  parametrics.

## Author

Hongyuan Jia and Adrian Chong

## License

The project is released under the terms of MIT License.

Copyright © 2016-2025 Hongyuan Jia and Adrian Chong

---

Please note that the 'eplusr' project is released with a
[Contributor Code of Conduct](https://github.com/hongyuanjia/eplusr/blob/master/.github/CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.

        

Owner metadata


GitHub Events

Total
Last Year

Committers metadata

Last synced: 1 day ago

Total Commits: 1,783
Total Committers: 3
Avg Commits per committer: 594.333
Development Distribution Score (DDS): 0.338

Commits in past year: 15
Committers in past year: 1
Avg Commits per committer in past year: 15.0
Development Distribution Score (DDS) in past year: 0.0

Name Email Commits
Hongyuan Jia h****a@c****n 1180
Hongyuan Jia h****a@b****g 602
dmurdoch m****n@g****m 1

Committer domains:


Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 335
Total pull requests: 262
Average time to close issues: about 1 month
Average time to close pull requests: 5 days
Total issue authors: 19
Total pull request authors: 2
Average comments per issue: 0.51
Average comments per pull request: 0.27
Merged pull request: 253
Bot issues: 0
Bot pull requests: 0

Past year issues: 11
Past year pull requests: 9
Past year average time to close issues: 8 days
Past year average time to close pull requests: about 1 hour
Past year issue authors: 1
Past year pull request authors: 1
Past year average comments per issue: 0.09
Past year average comments per pull request: 0.0
Past year merged pull request: 9
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/hongyuanjia/eplusr

Top Issue Authors

  • hongyuanjia (299)
  • yatingchen (9)
  • bdcoelho (5)
  • yidan1214 (4)
  • Enchufa2 (2)
  • wch (2)
  • jywang2016 (2)
  • chenwei2017 (1)
  • evelynsoong (1)
  • divyanshusood (1)
  • sckott (1)
  • lukas-rokka (1)
  • bjurban (1)
  • JChyi98 (1)
  • corymosiman12 (1)

Top Pull Request Authors

  • hongyuanjia (261)
  • dmurdoch (1)

Top Issue Labels

  • bug (138)
  • feature (66)
  • enhancement (41)
  • idf (28)
  • CRAN (21)
  • documentation (20)
  • EPW (19)
  • EnergyPlus (14)
  • SQL (13)
  • parametric (13)
  • geometry (10)
  • compatibility (8)
  • run (8)
  • CI (8)
  • question (7)
  • refactor (7)
  • idd (4)
  • release (4)
  • duplicate (4)
  • performance (3)
  • transition (3)
  • validate (3)
  • GUI (2)
  • schedule (2)
  • dependency (2)
  • viewer (1)
  • autocomplete (1)
  • deprecate (1)
  • help wanted (1)
  • invalid (1)

Top Pull Request Labels

  • bug (119)
  • feature (53)
  • enhancement (32)
  • idf (19)
  • EnergyPlus (19)
  • EPW (18)
  • CI (16)
  • documentation (15)
  • SQL (12)
  • CRAN (11)
  • parametric (10)
  • compatibility (8)
  • refactor (8)
  • run (8)
  • geometry (7)
  • transition (3)
  • dependency (2)
  • performance (2)
  • idd (2)
  • schedule (2)
  • viewer (1)
  • autocomplete (1)
  • release (1)
  • GUI (1)

Package metadata

cran.r-project.org: eplusr

A Toolkit for Using Whole Building Simulation Program 'EnergyPlus'

  • Homepage: https://hongyuanjia.github.io/eplusr/
  • Documentation: http://cran.r-project.org/web/packages/eplusr/eplusr.pdf
  • Licenses: MIT + file LICENSE
  • Latest release: 0.16.3 (published 9 days ago)
  • Last Synced: 2025-04-29T15:03:27.179Z (1 day ago)
  • Versions: 26
  • Dependent Packages: 1
  • Dependent Repositories: 2
  • Downloads: 583 Last month
  • Rankings:
    • Stargazers count: 5.623%
    • Forks count: 5.825%
    • Average: 12.588%
    • Downloads: 14.374%
    • Dependent packages count: 17.575%
    • Dependent repos count: 19.546%
  • Maintainers (1)

Dependencies

DESCRIPTION cran
  • R >= 3.2.0 depends
  • R6 * imports
  • RSQLite * imports
  • callr >= 2.0.4 imports
  • checkmate * imports
  • cli >= 1.1.0 imports
  • crayon * imports
  • data.table >= 1.12.4 imports
  • hms * imports
  • lubridate * imports
  • methods * imports
  • processx >= 3.2.0 imports
  • progress >= 1.2.0 imports
  • stringi * imports
  • units * imports
  • decido * suggests
  • rgl >= 0.105.13 suggests
  • testthat >= 2.1.0 suggests
.github/workflows/R-CMD-check.yaml actions
  • actions/checkout v2 composite
  • r-lib/actions/check-r-package v2 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/pkgdown.yml actions
  • actions/checkout v2 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/pr-commands.yaml actions
  • actions/checkout v2 composite
  • r-lib/actions/pr-fetch v2 composite
  • r-lib/actions/pr-push v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/test-coverage.yaml actions
  • actions/checkout v2 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.devcontainer/Dockerfile docker
  • rocker/r-ver 4.1.0 build
tools/meta.json cpan

Score: 12.174117474288623