Skip to main content

A Gymnasium environment based on the purely Python-based OCHRE residential energy building simulator.

Project description

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

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 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.
  2. Clone this repo: git clone git@github.com/NREL/ochre_gym.git
  3. cd ochre_gym
  4. 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():

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ochre_gym-0.1.0a1.tar.gz (12.9 MB view details)

Uploaded Source

Built Distribution

ochre_gym-0.1.0a1-py3-none-any.whl (13.6 MB view details)

Uploaded Python 3

File details

Details for the file ochre_gym-0.1.0a1.tar.gz.

File metadata

  • Download URL: ochre_gym-0.1.0a1.tar.gz
  • Upload date:
  • Size: 12.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.17

File hashes

Hashes for ochre_gym-0.1.0a1.tar.gz
Algorithm Hash digest
SHA256 048a8f58e45e9978526ce46a83b03ff40acff407d4e7741c24daeb6f75884ae5
MD5 4976332751a290553f4fff71e15071f1
BLAKE2b-256 060358b7c6de02c6dc97a99bf6bb4e6eca10c72c37ad261ddb2ec0b7044272b5

See more details on using hashes here.

File details

Details for the file ochre_gym-0.1.0a1-py3-none-any.whl.

File metadata

  • Download URL: ochre_gym-0.1.0a1-py3-none-any.whl
  • Upload date:
  • Size: 13.6 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.17

File hashes

Hashes for ochre_gym-0.1.0a1-py3-none-any.whl
Algorithm Hash digest
SHA256 4e8d7bcb95b2b64cc968d7246aceaf7b74f4344756b8865880935fa7e51e570c
MD5 6c11ee8e9e00379a5c508ec9f9420f8f
BLAKE2b-256 c5ceff2f925a98e100e89f727359af27a7d30305bfbaa9b20b04748770633866

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page