Home

Awesome

OCHRE

OCHRE: The Object-oriented Controllable High-resolution Residential Energy Model

OCHRE™ is a Python-based building energy modeling (BEM) tool designed to model flexible loads in residential buildings. OCHRE includes detailed models and controls for flexible devices including HVAC equipment, water heaters, electric vehicles, solar PV, and batteries. It is designed to run in co-simulation with custom controllers, aggregators, and grid models.

The full documentation for OCHRE can be found at https://ochre-nrel.readthedocs.io/

Contact: jeff.maguire@nrel.gov, michael.blonsky@nrel.gov, killian.mckenna@nrel.gov

Installation

Note that OCHRE requires Python version >=3.9 and <3.12

Stand-alone Installation

For a stand-alone installation, OCHRE can be installed using pip from the command line:

pip install ochre-nrel

Alternatively, you can install a specific branch, for example:

pip install git+https://github.com/NREL/OCHRE@dev

In Co-simulation

To embed this in a co-simulation and a separate conda environment, create an environment.yml file in the co-simulation project and include the following lines:

dependencies:
  - pip:
    - ochre-nrel

Usage

OCHRE can be used to simulate a residential dwelling or an individual piece of equipment. In either case, a python object is instantiated and then simulated. A set of input parameters and input files must be defined.

Below is a simple example of simulating a dwelling:

import datetime as dt
from ochre import Dwelling
house = Dwelling(simulation_name, 
                 start_time=dt.datetime(2018, 1, 1, 0, 0),
                 time_res=dt.timedelta(minutes=10),       
                 duration=dt.timedelta(days=3),
                 properties_file='sample_resstock_house.xml',
                 schedule_file='sample_resstock_schedule.csv',
                 weather_file='USA_CO_Denver.Intl.AP.725650_TMY3.epw',
                 verbosity=3,
                 )
df, metrics, hourly = dwelling.simulate()

This will output 3 variables:

For more examples, see the following python scripts in the bin folder:

Required and optional input parameters and files are described below for a dwelling.

Required Dwelling Parameters

Optional Dwelling Parameters

Equipment-specific Parameters

Equipment arguments can be included to override information from the properties file. See bin/run_dwelling.py or bin/run_equipment.py for examples. Below is a list of all of OCHRE's equipment names:

Overview

OCHRE is an object-oriented residential building model that simulates a variety of behind-the-meter equipment. It simulates dwelling energy consumption (electricity and gas) at a high resolution (up to 1-minute) and is designed to integrate in co-simulation with controllers, distribution systems, and other agents. Most equipment types are controllable though an external controller to simulate the impact of device controllers, HEMS, demand response, or other control strategies. The initialization integrates with ResStock and BEopt output files to simplify the building modeling.

The key features of the code are:

OCHRE integrates with the following models and tools: