# OCHRE Gym
All authors are with the National Renewable Energy Laboratory (NREL).
## Overview
OCHRE (pronounced "Oh-ker") Gym is a Gymnasium environment based on the purely Python-based [OCHRE](https://github.com/NREL/OCHRE) residential energy building simulator. OCHRE is a high-fidelity, high-resolution residential building model developed by NREL with behind-the-meter DERs and flexible load models that integrates with controllers and distribution models in building-to-grid co-simulation platforms. It has been benchmarked against EnergyPlus to quantify the tradeoff between fidelity and speed. Read more about OCHRE [here](https://www.sciencedirect.com/science/article/pii/S0306261921002464).
OCHRE Gym features:
- No EnergyPlus; each Dwelling consists of multiple RC circuits implemented in pure Python
- Works with any building that OCHRE supports: get building models from NREL End-Use Load Profiles, ResStock, BEopt, etc.
- Flexible control of building equipment (HVAC, Water Heater)--support coming for DERs (PV, Battery, EV)
- Customizable observation space with equipment-level, building-level, and building metadata
- Simple reward: minimize cost of energy use while maintaining comfort
- 3 different demand response (DR) cost functions: Real-Time Pricing (RTP), Time-of-Use (TOU), and Power Constraints (PC)
[Read our docs](https://nrel.github.io/ochre_gym) to get started quickly.
## Installation
Install from PyPI `pip install ochre_gym`.
Or,
Install in editable mode with `pip install -e .` from the root of this repo.
1. Using `conda` or `venv`, create an environment with `python >= 3.9`: `conda create -n ochre_gym python=3.9`.
1. Clone this repo: `git clone git@github.com/NREL/ochre_gym.git`
2. `cd ochre_gym`
2. `pip install -e .`
Test your installation with `unittest` by running `python3 -m unittest` from the root of this repo.
## Quick Start
Init one of the provided buildings (e.g., `basic-v0`) with `ochre_gym.load()`:
```python
import ochre_gym
env = ochre_gym.load(
env_name="basic-v0",
)
for step in range(1000):
# Sample an action from the action space
action = env.action_space.sample()
# Step the environment with the sampled action
obs, rew, terminated, truncated, info = env.step(action)
# Check if the episode is done
if terminated:
print("Episode finished after {} timesteps".format(step+1))
break
```
The `ochre_gym.load()` function will handle creating the OCHRE building simulator instance using the properties, schedule, and weather files located in `ochre_gym/buildings/basic-v0`.
Keyword arguments passed to `load` can be used to override the defaults in the `ochre_gym/buildings/defaults.toml` config file.
## Funding Acknowledgement
This work was authored by the National Renewable Energy Laboratory (NREL), operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE) under Contract No. DE-AC36-08GO28308. This work was supported by the Laboratory Directed Research and Development (LDRD) Program at NREL. The views expressed in the article do not necessarily represent the views of the DOE or the U.S. Government. The U.S. Government retains and the publisher, by accepting the article for publication, acknowledges that the U.S. Government retains a nonexclusive, paid-up, irrevocable, worldwide license to publish or reproduce the published form of this work, or allow others to do so, for U.S. Government purposes.
Raw data
{
"_id": null,
"home_page": "https://github.nrel.gov/NREL/ochre_gym",
"name": "ochre-gym",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "reinforcement learning,hvac,building,building energy simulation",
"author": "Patrick Emami, Xiangyu Zhang, Peter Graf",
"author_email": "pemami@nrel.gov, Xiangyu.Zhang@nrel.gov, Peter.Graf@nrel.gov",
"download_url": "https://files.pythonhosted.org/packages/06/03/58b7c6de02c6dc97a99bf6bb4e6eca10c72c37ad261ddb2ec0b7044272b5/ochre_gym-0.1.0a1.tar.gz",
"platform": null,
"description": "# OCHRE Gym\n\nAll authors are with the National Renewable Energy Laboratory (NREL).\n\n## Overview\n\nOCHRE (pronounced \"Oh-ker\") Gym is a Gymnasium environment based on the purely Python-based [OCHRE](https://github.com/NREL/OCHRE) residential energy building simulator. OCHRE is a high-fidelity, high-resolution residential building model developed by NREL with behind-the-meter DERs and flexible load models that integrates with controllers and distribution models in building-to-grid co-simulation platforms. It has been benchmarked against EnergyPlus to quantify the tradeoff between fidelity and speed. Read more about OCHRE [here](https://www.sciencedirect.com/science/article/pii/S0306261921002464).\n\nOCHRE Gym features:\n\n- No EnergyPlus; each Dwelling consists of multiple RC circuits implemented in pure Python\n- Works with any building that OCHRE supports: get building models from NREL End-Use Load Profiles, ResStock, BEopt, etc.\n- Flexible control of building equipment (HVAC, Water Heater)--support coming for DERs (PV, Battery, EV)\n- Customizable observation space with equipment-level, building-level, and building metadata\n- Simple reward: minimize cost of energy use while maintaining comfort\n- 3 different demand response (DR) cost functions: Real-Time Pricing (RTP), Time-of-Use (TOU), and Power Constraints (PC)\n\n[Read our docs](https://nrel.github.io/ochre_gym) to get started quickly.\n\n## Installation\n\nInstall from PyPI `pip install ochre_gym`.\n\nOr,\n\nInstall in editable mode with `pip install -e .` from the root of this repo.\n\n1. Using `conda` or `venv`, create an environment with `python >= 3.9`: `conda create -n ochre_gym python=3.9`.\n1. Clone this repo: `git clone git@github.com/NREL/ochre_gym.git`\n2. `cd ochre_gym`\n2. `pip install -e .`\n\nTest your installation with `unittest` by running `python3 -m unittest` from the root of this repo.\n\n## Quick Start\n\nInit one of the provided buildings (e.g., `basic-v0`) with `ochre_gym.load()`:\n\n```python\nimport ochre_gym\n\nenv = ochre_gym.load(\n env_name=\"basic-v0\",\n)\n\nfor step in range(1000):\n\n # Sample an action from the action space\n action = env.action_space.sample()\n\n # Step the environment with the sampled action\n obs, rew, terminated, truncated, info = env.step(action)\n \n # Check if the episode is done \n if terminated:\n print(\"Episode finished after {} timesteps\".format(step+1))\n break\n```\n\nThe `ochre_gym.load()` function will handle creating the OCHRE building simulator instance using the properties, schedule, and weather files located in `ochre_gym/buildings/basic-v0`. \nKeyword arguments passed to `load` can be used to override the defaults in the `ochre_gym/buildings/defaults.toml` config file. \n\n## Funding Acknowledgement\n\nThis work was authored by the National Renewable Energy Laboratory (NREL), operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE) under Contract No. DE-AC36-08GO28308. This work was supported by the Laboratory Directed Research and Development (LDRD) Program at NREL. The views expressed in the article do not necessarily represent the views of the DOE or the U.S. Government. The U.S. Government retains and the publisher, by accepting the article for publication, acknowledges that the U.S. Government retains a nonexclusive, paid-up, irrevocable, worldwide license to publish or reproduce the published form of this work, or allow others to do so, for U.S. Government purposes.\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "A Gymnasium environment based on the purely Python-based OCHRE residential energy building simulator.",
"version": "0.1.0a1",
"project_urls": {
"Homepage": "https://github.nrel.gov/NREL/ochre_gym"
},
"split_keywords": [
"reinforcement learning",
"hvac",
"building",
"building energy simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c5ceff2f925a98e100e89f727359af27a7d30305bfbaa9b20b04748770633866",
"md5": "6c11ee8e9e00379a5c508ec9f9420f8f",
"sha256": "4e8d7bcb95b2b64cc968d7246aceaf7b74f4344756b8865880935fa7e51e570c"
},
"downloads": -1,
"filename": "ochre_gym-0.1.0a1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c11ee8e9e00379a5c508ec9f9420f8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13648572,
"upload_time": "2023-10-09T15:55:26",
"upload_time_iso_8601": "2023-10-09T15:55:26.897512Z",
"url": "https://files.pythonhosted.org/packages/c5/ce/ff2f925a98e100e89f727359af27a7d30305bfbaa9b20b04748770633866/ochre_gym-0.1.0a1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "060358b7c6de02c6dc97a99bf6bb4e6eca10c72c37ad261ddb2ec0b7044272b5",
"md5": "4976332751a290553f4fff71e15071f1",
"sha256": "048a8f58e45e9978526ce46a83b03ff40acff407d4e7741c24daeb6f75884ae5"
},
"downloads": -1,
"filename": "ochre_gym-0.1.0a1.tar.gz",
"has_sig": false,
"md5_digest": "4976332751a290553f4fff71e15071f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12865229,
"upload_time": "2023-10-09T15:55:37",
"upload_time_iso_8601": "2023-10-09T15:55:37.798045Z",
"url": "https://files.pythonhosted.org/packages/06/03/58b7c6de02c6dc97a99bf6bb4e6eca10c72c37ad261ddb2ec0b7044272b5/ochre_gym-0.1.0a1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-09 15:55:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ochre-gym"
}
JSON