# 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-docs-final.readthedocs.io/en/latest/
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:
* `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
Raw data
{
"_id": null,
"home_page": null,
"name": "ochre-nrel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "building energy modeling, demand flexibility, grid-interactive buildings, residential buildings",
"author": null,
"author_email": "Jeff Maguire <Jeff.Maguire@nrel.gov>, Michael Blonsky <Michael.Blonsky@nrel.gov>",
"download_url": "https://files.pythonhosted.org/packages/ae/4c/3fd4dad009e596a1737dab39699bffc5b6b7d6c800c3794a220b8f618c19/ochre_nrel-0.8.5.tar.gz",
"platform": null,
"description": "\n\n# OCHRE: The Object-oriented Controllable High-resolution Residential Energy Model\n\nOCHRE™ 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.\n\nThe full documentation for OCHRE can be found at https://ochre-docs-final.readthedocs.io/en/latest/\n\nContact: jeff.maguire@nrel.gov, michael.blonsky@nrel.gov, killian.mckenna@nrel.gov\n\n## Installation\n\nNote that OCHRE requires Python version >=3.9 and <3.12\n\n### Stand-alone Installation\n\nFor a stand-alone installation, OCHRE can be installed using `pip` from the command line:\n\n```\npip install ochre-nrel\n```\n\nAlternatively, you can install a specific branch, for example:\n\n```\npip install git+https://github.com/NREL/OCHRE@dev\n```\n\n### In Co-simulation\nTo embed this in a co-simulation and a separate conda environment, create an `environment.yml` file in the co-simulation\nproject and include the following lines:\n```\ndependencies:\n - pip:\n - ochre-nrel\n```\n\n\n## Usage\n\nOCHRE can be used to simulate a residential dwelling or an individual piece of equipment. In either case, a python\nobject is instantiated and then simulated. A set of input parameters and input files must be defined. \n\nBelow is a simple example of simulating a dwelling:\n```\nimport datetime as dt\nfrom ochre import Dwelling\nhouse = Dwelling(simulation_name, \n start_time=dt.datetime(2018, 1, 1, 0, 0),\n time_res=dt.timedelta(minutes=10), \n duration=dt.timedelta(days=3),\n properties_file='sample_resstock_house.xml',\n schedule_file='sample_resstock_schedule.csv',\n weather_file='USA_CO_Denver.Intl.AP.725650_TMY3.epw',\n verbosity=3,\n )\ndf, metrics, hourly = dwelling.simulate()\n```\n\nThis will output 3 variables:\n * `df`: a Pandas DataFrame with 10 minute resolution\n * `metrics`: a dictionary of energy metrics\n * `hourly`: a Pandas DataFrame with 1 hour resolution (verbosity >= 3 only)\n\nFor more examples, see the following python scripts in the `bin` folder:\n* Run a single dwelling: `bin/run_dwelling.py`\n* Run a single piece of equipment: `bin/run_equipment.py`\n* Run a dwelling with an external controller: `bin/run_external_control.py`\n* Run multiple dwellings: `bin/run_multiple.py`\n* Run a fleet of equipment: `bin/run_fleet.py`\n\nRequired and optional input parameters and files are described below for a dwelling.\n\n### Required Dwelling Parameters\n\n* `name`: Name of the simulation\n* `start_time`: Simulation start time as a datetime.datetime\n* `time_res`: Simulation time resolution as a datetime.timedelta\n* `duration`: Simulation duration as a datetime.timedelta\n* `properties_file`: Path to building properties file (HPXML, yaml, or BEopt properties file)\n* `schedule_file`: Path to building schedule file (csv)\n* `weather_file` or `weather_path`: Path to weather file (epw or NSRDB file). `weather_path` can be used if the \nWeather Station name is specified in the properties file.\n\n### Optional Dwelling Parameters\n\n* `input_path`: Path with additional input files (defaults to a built-in directory)\n* `output_path`: Path to output files\n* `save_results`: if True, saves results to output files (default is True if `output_path` is specified)\n* `initialization_time`: Duration to initialize the building temperatures as a datetime.timedelta (default is no \ninitialization)\n* `water_draw_file`: File name for water draw schedule file. For BEopt inputs only (default is no water draw)\n* `verbosity`: Verbosity of the output files as integer from 1 to 9 (default is 1)\n* `metrics_verbosity`: Verbosity of the metrics output file as integer from 1 to 9 (default is 6)\n\n### Equipment-specific Parameters\n\nEquipment arguments can be included to override information from the properties file. See `bin/run_dwelling.py` or\n`bin/run_equipment.py` for examples. Below is a list of all of OCHRE's equipment names:\n* HVAC Heating:\n * Electric Furnace\n * Electric Baseboard\n * Electric Boiler\n * Gas Furnace\n * Gas Boiler\n * Heat Pump Heater\n * Air Source Heat Pump (ASHP Heater)\n * Minisplit Heat Pump (MSHP Heater)\n * Ideal Heater\n* HVAC Cooling:\n * Air Conditioner\n * Room AC\n * Air Source Heat Pump (ASHP Cooler)\n * Minisplit Heat Pump (MSHP Cooler)\n * Ideal Cooler\n* Water Heating:\n * Electric Resistance Water Heater\n * Heat Pump Water Heater\n * Gas Water Heater\n * Modulating Water Heater\n * Tankless Water Heater\n * Gas Tankless Water Heater\n* DERs and Controllable Loads:\n * PV\n * Battery\n * Electric Vehicle (EV)\n* Scheduled Loads:\n * Lighting\n * Exterior Lighting\n * Range\n * Dishwasher\n * Refrigerator\n * Clothes Washer\n * Clothes Dryer\n * MELs\n * Scheduled EV \n\n\n## Overview\n\nOCHRE is an object-oriented residential building model that simulates a variety of behind-the-meter equipment.\nIt simulates dwelling energy consumption (electricity and gas) at a high resolution (up to 1-minute) and is designed \nto integrate in co-simulation with controllers, distribution systems, and other agents.\nMost equipment types are controllable though an external controller to simulate the impact of device\ncontrollers, HEMS, demand response, or other control strategies.\nThe initialization integrates with ResStock and BEopt output files to simplify the building modeling.\n\nThe key features of the code are:\n\n* High-fidelity, high-resolution residential building simulation\n* Controllable equipment via external controllers\n* Simple integration with co-simulation using object-oriented principles\n* Voltage-dependent electric power and reactive power using an equipment-level ZIP model\n* Large variety of equipment types including HVAC, water heating, PV, batteries, and EVs\n* Envelope, HVAC, and water heating validation with EnergyPlus (in progress)\n\nOCHRE integrates with the following models and tools:\n* ResStock (for generating input files)\n* BEopt (for generating input files)\n* HELICS (for co-simulation)\n* Foresee (for HEMS control)\n* SAM (for PV modeling)\n* EVIpro (for EV modeling)\n* Distribution models, e.g. OpenDSS, through co-simulation\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A residential energy modeling tool designed to model flexible loads and DERs",
"version": "0.8.5",
"project_urls": {
"Changelog": "https://github.com/NREL/OCHRE/blob/main/changelog.md",
"Documentation": "https://ochre-docs-final.readthedocs.io/en/latest/",
"Homepage": "https://www.nrel.gov/grid/ochre.html",
"Issues": "https://github.com/NREL/OCHRE/issues",
"Repository": "https://github.com/NREL/OCHRE.git"
},
"split_keywords": [
"building energy modeling",
" demand flexibility",
" grid-interactive buildings",
" residential buildings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f3bcaa92a6b8af0046c9e126c8fd1309941215599a8f8156348a7c47ed7b2d9",
"md5": "7020793640e03f7365c4e2da8b939fa8",
"sha256": "3a182da2e8bd9595ead384d8f570bded7b556ce30e8342b9c7f56f8c49cb04a8"
},
"downloads": -1,
"filename": "ochre_nrel-0.8.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7020793640e03f7365c4e2da8b939fa8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 44281972,
"upload_time": "2024-06-03T22:37:12",
"upload_time_iso_8601": "2024-06-03T22:37:12.919281Z",
"url": "https://files.pythonhosted.org/packages/8f/3b/caa92a6b8af0046c9e126c8fd1309941215599a8f8156348a7c47ed7b2d9/ochre_nrel-0.8.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ae4c3fd4dad009e596a1737dab39699bffc5b6b7d6c800c3794a220b8f618c19",
"md5": "8b7f1151a29c44527499857247a7e838",
"sha256": "401b23c34aa708079a1784c485f5627c088ddd2272c656e17820fde44643cf87"
},
"downloads": -1,
"filename": "ochre_nrel-0.8.5.tar.gz",
"has_sig": false,
"md5_digest": "8b7f1151a29c44527499857247a7e838",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 45123911,
"upload_time": "2024-06-03T22:38:21",
"upload_time_iso_8601": "2024-06-03T22:38:21.170085Z",
"url": "https://files.pythonhosted.org/packages/ae/4c/3fd4dad009e596a1737dab39699bffc5b6b7d6c800c3794a220b8f618c19/ochre_nrel-0.8.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-03 22:38:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NREL",
"github_project": "OCHRE",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ochre-nrel"
}
JSON
