nrel / ochre

A Python-based building energy modeling (BEM) tool designed to model flexible loads in residential buildings

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: [email protected], [email protected], [email protected]

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:

• df: a Pandas DataFrame with 10 minute resolution
• metrics: a dictionary of energy metrics
• hourly: a Pandas DataFrame with 1 hour resolution (verbosity >= 3 only)

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

• Run a single dwelling: bin/run_dwelling.py
• Run a single piece of equipment: bin/run_equipment.py
• Run a dwelling with an external controller: bin/run_external_control.py
• Run multiple dwellings: bin/run_multiple.py
• Run a fleet of equipment: bin/run_fleet.py

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

Required Dwelling Parameters

• name: Name of the simulation
• start_time: Simulation start time as a datetime.datetime
• time_res: Simulation time resolution as a datetime.timedelta
• duration: Simulation duration as a datetime.timedelta
• properties_file: Path to building properties file (HPXML, yaml, or BEopt properties file)
• schedule_file: Path to building schedule file (csv)
• weather_file or weather_path: Path to weather file (epw or NSRDB file). weather_path can be used if the Weather Station name is specified in the properties file.

Optional Dwelling Parameters

• input_path: Path with additional input files (defaults to a built-in directory)
• output_path: Path to output files
• save_results: if True, saves results to output files (default is True if output_path is specified)
• initialization_time: Duration to initialize the building temperatures as a datetime.timedelta (default is no initialization)
• water_draw_file: File name for water draw schedule file. For BEopt inputs only (default is no water draw)
• verbosity: Verbosity of the output files as integer from 1 to 9 (default is 1)
• metrics_verbosity: Verbosity of the metrics output file as integer from 1 to 9 (default is 6)

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:

• HVAC Heating:
  • Electric Furnace
  • Electric Baseboard
  • Electric Boiler
  • Gas Furnace
  • Gas Boiler
  • Heat Pump Heater
  • Air Source Heat Pump (ASHP Heater)
  • Minisplit Heat Pump (MSHP Heater)
  • Ideal Heater
• HVAC Cooling:
  • Air Conditioner
  • Room AC
  • Air Source Heat Pump (ASHP Cooler)
  • Minisplit Heat Pump (MSHP Cooler)
  • Ideal Cooler
• Water Heating:
  • Electric Resistance Water Heater
  • Heat Pump Water Heater
  • Gas Water Heater
  • Modulating Water Heater
  • Tankless Water Heater
  • Gas Tankless Water Heater
• DERs and Controllable Loads:
  • PV
  • Battery
  • Electric Vehicle (EV)
• Scheduled Loads:
  • Lighting
  • Exterior Lighting
  • Range
  • Dishwasher
  • Refrigerator
  • Clothes Washer
  • Clothes Dryer
  • MELs
  • Scheduled EV

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:

• High-fidelity, high-resolution residential building simulation
• Controllable equipment via external controllers
• Simple integration with co-simulation using object-oriented principles
• Voltage-dependent electric power and reactive power using an equipment-level ZIP model
• Large variety of equipment types including HVAC, water heating, PV, batteries, and EVs
• Envelope, HVAC, and water heating validation with EnergyPlus (in progress)

OCHRE integrates with the following models and tools:

• ResStock (for generating input files)
• BEopt (for generating input files)
• HELICS (for co-simulation)
• Foresee (for HEMS control)
• SAM (for PV modeling)
• EVIpro (for EV modeling)
• Distribution models, e.g. OpenDSS, through co-simulation

ochre's Issues

Prototype building models?

We could make OCHRE models that correspond to the DOE prototype models (see https://www.energycodes.gov/prototype-building-models#Residential), which get used in some studies. The issue is that would probably be quite a lot of work, since only the .idf files are available and they weren't made through OS-HPXML.

Probably won't address unless someone asks for them, and even then it'd be worth a conversation about alternatives.

120 V HPWHs

New 120 V HPWHs are on the market! The upside is for electrifying you don't need to install a new circuit/panel upgrade, which can cost more than the HPWH itself. When this gets added we to OS-HPXML we can look at adding the same functionality here, should just be adding new performance maps and control logics. Hopefully a pretty low lift, but we need to wait on OS-HPXML first.

Option to reset states to initial state

Simulator.reset_time updates the time and schedule, but there isn't an option to reset the state of the dwelling (e.g. temperatures, battery SOC, etc.) to their original values. We should add an option to do that. Initial states should include:

• Envelope states
• Equipment states (water heater temperatures, battery SOC)
• Equipment mode, cycle counts, and other state variables
• Envelope zone temperatures and boundary surface temperatures (and t_prev)
• Envelope humidity

Also make a function that saves the initial_state variables and have that save after the initialization. Then a user can reset it to a different time if they want later.

Note that a deepcopy will produce identical results. The goal should be to produce identical results before and after reset_time is called.

Testing Metrics

We have quite a few metrics for testing, but it's hard to draw a definitive line on what "passes" when we're comparing EnergyPlus to OCHRE. Maybe we should look at ASHRAE 140 for a better idea?

For now, keep all metrics and start with the highest level ones, namely % difference in annual energy consumption.

OCHRE Documentation

Documentation written in word

• OCHRE overview and scope (Jeff)
• Installation (Michael)
• Usage (Michael)
• License, citations, publishing, and contact information (Jeff)
  Modeling Approach:
  • Envelope (Jeff & Michael)
  • HVAC (Jeff and Sugi)
  • Water Heating (Jeff)
  • Batteries (Michael)
  • Electric Vehicles (Michael)
  • PV (Michael)
  • Other Loads (Jeff & Michael)
  • Co-simulation (Michael)
    Input Files and Arguments:
  • HPXML (Jeff)
  • Occupancy Schedule (Jeff)
  • Weather (Jeff & Michael)
  • Generating Input Files (Jeff)
  • Dwelling Arguments (Michael)
  • Equipment Specific Arguments (Michael)
  • Outputs & Analysis (Michael)
    Controller Integration:
  • External Control Singals (Michael)
  • External Model Signals (Michael)
• Example Use Cases (Michael)
• Translated to .rst
• Hosted on readthedocs

Test Suite?

We could consider making a new test suite of "minimal" buildings using BEopt, for debugging purposes. The longer term plan is to use #19 as a better way to try to figure out if differences are due to ceilings, walls, infiltration, etc. But maybe this is worth doing?

Validation

Main validation effort will be simulating a large # of homes in ResStock (~500) and comparing the results between EnergyPlus and OCHRE. As appropriate, we will also create test suite cases to further investigate specific aspects of the model such as multifamily geometries and ducts.

We'll want component loads (#19 )as part of this

• Multifamily geometry test cases created and validated (Jeff & Michael)

• Validation of 500 homes through ResStock

• Documentation of whatever validation results we have? (All)

Standard Effective Temperature

Useful output to calculate for resilliency use cases. On the cold side during an outage dry bulb temperature is the key driver, but on the hot side standard effective temperature (SET) is generally used as a metric.

https://www.buildingenclosureonline.com/blogs/14-the-be-blog/post/85635-standard-effective-temperature-set-and-thermal-comfort

Update OCHRE version in GridAPPS-D

Once OCHRE releases, it'd be nice to update the version of OCHRE that integrates with GridAPPS-D to take advantage of the latest features.

Automatically add Envelope results to Dwelling results like in previous OCHRE versions?

Hi! There used to be a line of code that would automatically add the Envelope results to the Dwelling results Dict, something like out.update(self.envelope.generate_results()). Is this going to get added back eventually in this function?

OCHRE/ochre/Dwelling.py

Line 281 in 7b357be

def generate_results(self):

Right now I can access the Envelope results directly by manually calling self.dwelling.envelope.generate_results(), so this isn't high priority.

Semi conditioned attic

For the IBACOS connected communities project, we have homes with semi conditioned attics. They're basically the same thing as how we model finished basements, with a fixed fraction of heating/cooling making it to the attic but controlled via a thermostat in the living space.

@mnblonsky: how hard would it be to support semi-conditioned attics? There isn't a straightforward input for it in HPXML, which makes it a little complicated, but I'm assuming we can reuse a lot of the conditioned basement code.

Update ZIP parameters

• Compare current parameters with literature
• Check if we have any lab data from SPL to inform PF/ZIP parameters
• Create mode-level zip parameters (i.e., account for the difference between HP and backup electric resistance for an ASHP or HPWH)
• Add option to report house-level ZIP coefficients or exponents to integrate with grid load model

Infiltration updates

There's some updates to infiltration modeling we can do, it looks like OCHRE is low relative to EnergyPlus.

Shared EV charging?

For the AC3 project, we're looking into a central shared EV charger. This would require us to add EV schedules not for residential, but for something much closer to a commercial location. I THINK EVI-pro has the data to do that? If it does, how much effort do you think this would be (and would you have time if I had a task number) @mnblonsky?

Garage doors

We currently don't model garage doors as a surface with different properties as garage walls. Since we always model garage walls as uninsulated this should have a really, really minor impact.

New Fuel Types

We support electricity, natural gas, propane, and fuel oil. There's some other fuels that come up occasionally (wood, coal, etc.) in very small # of homes that would be good to support someday.

Handle Leap Years

Test EPW vs. NSRDB

Would be great to run a couple of buildings under EPW and corresponding NSRDB data to ensure results are identical

Update to work with ResStock 3.1/OS-HPXML 1.6.0

Looks like there's some breaking changes in the most recent release of OS-HPXML. Lighting is the first one we hit, but there's probably several breaking changes. See: https://github.com/NREL/OpenStudio-HPXML/releases/tag/v1.6.0

Detailed Technical Report

NREL technical report on validation efforts. Cover minimal buildings, ResStock E+/OCHRE comparison, validation against real home (GreenBuilt?). ASHRAE 140 if funded, or should that be a separate report?

ASHRAE 140

Can we create all the ASHRAE 140 test cases and run them successfully? Would be a great validation step, and probably a good use of future AOP funding

Other Infiltration Inputs

OS-HPXML allows infiltration inputs to be:

• ACH50
• CFM50
• CFM at house pressure (not 50 Pa)
• ACHnatural
• CFMnatural
• ELA

I think the conversions here are pretty basic, but we'd have to add them into OCHRE.

Duct Model Validation

Some of the cases in ResStock have had the duct models fail. @sugirdhalakshmi is going to look into the failing cases and see what the issue is.

@jmaguire1: would be good to make some "minimal" test cases for extreme scenarios (uninsulated super leaky ducts in attic, crawlspace, etc.)

Add component loads in OCHRE

Add component load outputs into OCHRE. Component loads will use the same approach as is used by OS/HPXML (Andrew Speake is an expert we can tap).

Variable film resistance

For now we're using constant film resistances for convection on surfaces. The resistance varies with orientation and inside/outside, but we could improve this. The algorithms used in EnergyPlus are pretty well documented, it's just a matter of the level of effort and priority.

Hip roofs

Right now we only support gable roofs, and give a not super intuitive error (gable area can't be found) if you draw a hip roof in BEopt. At a minimum we need to change the error, but ideally we'd be able to support it.

Speed & Memory Improvements

How much can we improve the speed and memory usage of OCHRE? Memory is already starting to become an issue at 1 minute, and if we ever want to go to second level it's going to be much worse.

For speed, we should profile OCHRE again and see where the time is being used. Possibly try pyinstrument? We'd been using CProfile for profiling.

Integrate Utility Cost Calculations Into OCHRE

Would be nice if we could load URDB rates (as json) into OCHRE as data files and then allow users to select a rate for postprocessing utility bill calculations. Can get pretty tricky for all combination of rates (tiered, TOU, different PV sellback schemes).

Second Level Phenomena

We could move down to the second level to simulate phenomena that EnergyPlus may currently miss (although SPAWN would be able to capture them). So far no one has asked for or needed this, but it'd be nice to handle things like inrush current and be able to support frequency regulation.

HVAC Oversizing?

We get our HVAC sizes direct from OS-HPXML (which uses ACCA Manual J&S). We might want the ability to oversize (by say x%) in the future to show off things like the impact of short cycling.

Low lift, but let's wait until we have an actual use case.

Remove lookup of material properties

Can we remove the lookup table of material properties and make best guess/directly parse from the HPXML file? R values are there, but not every layer's properties.

Good intern task?

Ideally we'd still use strings in the construction to identify materials like OSB and exterior finishes so we can get mass/R-value correctly distributed through the RC network, but we wouldn't need a strict 1:1 where we've pre run every single material. That really limits the custom constructions people can use, and in some cases might limit us to certain geometries (like our garage roof issue)

Shared Equipment for Multifamily

There's some approximations for modeling shared equipment in multifamily buildings that can be used for this unit by unit approach. These approximations are currently used in OS-HPXML, so we can definitely start there rather than having to combine units and physically model the whole building.

Shared equipment modeling information is in http://www.resnet.us/wp-content/uploads/archive/resblog/2019/01/ANSIRESNETICC301-2019_vf1.23.19.pdf

Heat Pump Cycling Losses

We model explicit on/off cycles, so we should also do a better job on cycling losses. On start up, it generally takes several minutes at full power before you hit full capacity of heating/cooling in the output.

We've actually done something very similar in OS-HPXML: (https://github.com/NREL/OpenStudio-HPXML/blob/0b062a4a2ef9b45307d6577e946c4abe8e2ebff3/HPXMLtoOpenStudio/resources/hvac.rb#L3128 (look at this method and the one below, which has the EMS program).

Directly related to #14, so maybe we'll address both at the same time. This is much more of an issue for single/2 speed equipment than variable speed AFAIK, but maybe we ought to apply to ALL HVAC, not just HPs.

Update Cold Climate HP model

Update the ASHP model in OCHRE to match the updates that are being done to the OpenStudio/HPXML model.

• Allow taking new inputs for cold climate performance (corresponding to NEEP data)
• Update curves based on new inputs
• Cold climate capacity retention
• Start-up capacity degradation
• Lockout temperatures
• Backup supplemental heat staging
• CTA commands (low priority)
• Look at 2-speed staging in OCHRE
• Defrost control

ASHRAE 140

ASHRAE 140 provides a standard way to test building energy modeling software, with a suite of buildings, assumptions, and output criteria. Someday I'd love to run these buildings (we already have hpxml files for it from OS-HPXML) and see if we pass/fail. Obviously with the goal of getting to the point OCHRE can pass.

Resdx Library?

New initiative to create a python library for modeling residential dx systems: https://github.com/bigladder/resdx

At some point we should look to see if there's anything there we can use? Maybe it'll be a quicker way to model cold climate performance.

This could be the path to addressing https://github.nrel.gov/Customer-Modeling/ochre/issues/13, although we need to make sure it works for all equipment speeds not just variable speed.

Floor area check doesn't equal floor area.

In at least one case with a garage I'm hitting this warning for AC3:

WARNING: Indoor floor area calculations do not agree: 178.18803071999997 m^2 and 154.03324031999998 m^2

The first floor area (178 m^2) is the correct one.

Extreme Envelope Temps due to high power equipment

We often get OCHRE errors related to extremely high indoor temperatures when equipment is consuming a lot of power. Usually it's a gas cooking range or gas clothes dryer. This is a known issue in ResStock's stochastic occupancy generator. See issues in ResStock and OS-HPXML.

We could wait for those issues to get resolved, or we could try fixing this ourselves. Might be best to wait for now.

Clean development files

A few files seem unnecessary to be included in the public repo or need to be updated to work with the public repo:

• Remove files used for validation
• Remove old scripts and notebooks
• Replace/remove private file paths
• Replace Github Enterprise paths with public paths
• Run all scripts and notebooks to make sure they run

Docs Improvements

• Fix any broken image links in .rst
• Add changelog
• Step by step BEopt guide (w/ pics)
• ResStock guide? Or better guidance on other resources?
• If I'm feeling crazy ambitious update tables w/ footnotes

Use pvlib for PV Model

Just tried running SAM v4.0 within OCHRE and it failed:

pvsamv1 simulation error
        : precheck input: variable 'subarray1_rear_soiling_loss' (Sub-array 1 rear soiling loss) required but not assigned

reset to 3.0.1 and it works. We should mention this in the documentation and update so it works with the latest PySAM. Or move to pvlib...

2 speed HVAC bug

Hitting an issue where the 2 speed HVAC is hitting "IndexError: list index out of range"

Unit Tests

It'd be great to add a suite of automated unit tests for making sure we don't break anything. These would be things like running the HVAC, WH, envelope model in isolation (or as close as possible). We could even use Github actions to run them automatically with every commit in the future like OS-HPXML does.

Integrate Emissions Data Into OCHRE

Add Cambium data into OCHRE directly and allow for postprocessing calculations that give emissions results as well as energy consumption.

• Pull Cambium data files (by month-hour) for use in postprocessing (Jeff)
• Add emissions factors for fuels (natural gas, propane, fuel oil) (Jeff)
• Integrate emissions calculations into postprocessing at high verbosity (Michael)

Error Out for Unsupported Features

If we see something in the HPXML file that we don't currently support (say a ground source heat pump), we should give an informative warning.

• Go through OS-HPXML sample files and figure out which ones ought to throw an error (Jeff)
• Add informative warnings/errors for each case that ought to error out (Jeff/Michael)

Do we want any documentation of what we do/don't support relative to OS-HPXML.

Pilot Lights

Scott recently added pilot light models into OS-HPXML for water heaters, furnaces, and boilers. Should be a pretty straightforward addition to OCHRE. Low priority though, we can throw a warning for now and ignore.

More Accurate Sensible Gains for Other Equipment

We currently take an weighted average of gain fractions for MELs/MGLs with weights based on annual consumption per load. It would be more accurate to calculate sensible/latent gains at each time step and add that to the schedule for MELs and MGLs. We'd need to save gain fractions for each load to the yaml file, and then use them when creating the schedule.

For appliances, issues with the stochastic occupancy model can cause very high internal gains, especially for the dryer and oven. Need to verify that our methods are accurate, then maybe suggest changes to the stochastic occupancy model, or reduce the heat gain fraction

• Fix gains from MEL/MGLs
• Fix gains from appliances

Unit Tests

Create unit tests to ensure that as development continues we're not breaking anything.

CI Testing

It would be really, really cool if we could have Continuous Integration testing that runs a variety of tests before things are merged in.

Remove lookup of HVAC equipment

Right now we have lookup tables for each piece of HVAC at a given efficiency (SEER/HSPF) that we use to calculate intermediate variables like the EIR at each speed. Would be great if we can remove this by having some things be looked up based on equipment type/# of speeds and the rest be calculated based on rated values directly in OCHRE. That way we won't have to pre run every type of equipment (so user specified equipment from BEopt/ResStock would work).