# OCHRE: The Object-oriented Controllable High-resolution Residential Energy Model
OCHRE™ is a Python-based energy modeling tool designed to model end-use
loads and distributed energy resources in residential buildings. It can model
flexible devices---including HVAC equipment, water heaters, electric vehicles,
solar PV, and batteries---and the thermal and electrical interactions between
them. OCHRE has been used to generate diverse and high-resolution load
profiles, examine the impacts of advanced control strategies on energy costs
and occupant comfort, and assess grid reliability and resilience through
building-to-grid co-simulation.
More information about OCHRE can be found in [our
documentation](https://ochre-nrel.readthedocs.io/), on [NREL's
website](https://www.nrel.gov/grid/ochre.html), and from the [Powered By
OCHRE](https://www.youtube.com/watch?v=B5elLVtYDbI) webinar recording.
If you use OCHRE for your research or other projects, please fill out our [user survey](https://forms.office.com/g/U4xYhaWEvs).
## 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
```
Note that OCHRE requires Python version >=3.9 and <3.13.
## 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/or input files must be defined.
Below is a simple example of simulating a dwelling:
```
import os
import datetime as dt
from ochre import Dwelling
from ochre.utils import default_input_path # for using sample files
house = Dwelling(
simulation_name,
start_time=dt.datetime(2018, 1, 1, 0, 0),
time_res=dt.timedelta(minutes=10),
duration=dt.timedelta(days=3),
hpxml_file=os.path.join(default_input_path, "Input Files", "bldg0112631-up11.xml"),
hpxml_schedule_file=os.path.join(default_input_path, "Input Files", "bldg0112631_schedule.csv"),
weather_file=os.path.join(default_input_path, "Weather", "USA_CO_Denver.Intl.AP.725650_TMY3.epw"),
)
df, metrics, hourly = dwelling.simulate()
```
This will return 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 [OCHRE User
Tutorial](https://colab.research.google.com/github/NREL/OCHRE/blob/main/notebook/user_tutorial.ipynb)
Jupyter notebook
* Python example scripts to:
* Run a [single dwelling](https://github.com/NREL/OCHRE/blob/main/bin/run_dwelling.py)
* Run a [single piece of equipment](https://github.com/NREL/OCHRE/blob/main/bin/run_equipment.py)
* Run a [fleet of equipment](https://github.com/NREL/OCHRE/blob/main/bin/run_fleet.py)
* Run [multiple dwellings](https://github.com/NREL/OCHRE/blob/main/bin/run_multiple.py)
* Run a [OCHRE with an external controller](https://github.com/NREL/OCHRE/blob/main/bin/run_external_control.py)
* Run a [OCHRE in co-simulation using HELICS](https://github.com/NREL/OCHRE/blob/main/bin/run_cosimulation.py)
Raw data
{
"_id": null,
"home_page": null,
"name": "ochre-nrel",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=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/6c/82/60f8842058e4a3b1de7cb43a2f9608cd4197bc58ec0345651ca639efb56c/ochre_nrel-0.9.1.tar.gz",
"platform": null,
"description": "\n\n# OCHRE: The Object-oriented Controllable High-resolution Residential Energy Model\n\nOCHRE™ is a Python-based energy modeling tool designed to model end-use\nloads and distributed energy resources in residential buildings. It can model\nflexible devices---including HVAC equipment, water heaters, electric vehicles,\nsolar PV, and batteries---and the thermal and electrical interactions between\nthem. OCHRE has been used to generate diverse and high-resolution load\nprofiles, examine the impacts of advanced control strategies on energy costs\nand occupant comfort, and assess grid reliability and resilience through\nbuilding-to-grid co-simulation.\n\nMore information about OCHRE can be found in [our\ndocumentation](https://ochre-nrel.readthedocs.io/), on [NREL's\nwebsite](https://www.nrel.gov/grid/ochre.html), and from the [Powered By\nOCHRE](https://www.youtube.com/watch?v=B5elLVtYDbI) webinar recording.\n\nIf you use OCHRE for your research or other projects, please fill out our [user survey](https://forms.office.com/g/U4xYhaWEvs).\n\n## Installation\n\nOCHRE 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\nNote that OCHRE requires Python version >=3.9 and <3.13.\n\n## Usage\n\nOCHRE can be used to simulate a residential dwelling or an individual piece of\nequipment. In either case, a python object is instantiated and then simulated.\nA set of input parameters and/or input files must be defined. \n\nBelow is a simple example of simulating a dwelling:\n```\nimport os\nimport datetime as dt\nfrom ochre import Dwelling\nfrom ochre.utils import default_input_path # for using sample files\nhouse = Dwelling(\n 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 hpxml_file=os.path.join(default_input_path, \"Input Files\", \"bldg0112631-up11.xml\"),\n hpxml_schedule_file=os.path.join(default_input_path, \"Input Files\", \"bldg0112631_schedule.csv\"),\n weather_file=os.path.join(default_input_path, \"Weather\", \"USA_CO_Denver.Intl.AP.725650_TMY3.epw\"),\n)\n\ndf, metrics, hourly = dwelling.simulate()\n```\n\nThis will return 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:\n* The [OCHRE User\n Tutorial](https://colab.research.google.com/github/NREL/OCHRE/blob/main/notebook/user_tutorial.ipynb)\n Jupyter notebook \n* Python example scripts to:\n * Run a [single dwelling](https://github.com/NREL/OCHRE/blob/main/bin/run_dwelling.py)\n * Run a [single piece of equipment](https://github.com/NREL/OCHRE/blob/main/bin/run_equipment.py)\n * Run a [fleet of equipment](https://github.com/NREL/OCHRE/blob/main/bin/run_fleet.py)\n * Run [multiple dwellings](https://github.com/NREL/OCHRE/blob/main/bin/run_multiple.py)\n * Run a [OCHRE with an external controller](https://github.com/NREL/OCHRE/blob/main/bin/run_external_control.py)\n * Run a [OCHRE in co-simulation using HELICS](https://github.com/NREL/OCHRE/blob/main/bin/run_cosimulation.py)\n",
"bugtrack_url": null,
"license": null,
"summary": "An energy modeling tool designed to model residential end-use loads and DERs",
"version": "0.9.1",
"project_urls": {
"Changelog": "https://github.com/NREL/OCHRE/blob/main/changelog.md",
"Documentation": "https://ochre-nrel.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",
"Tutorial": "https://colab.research.google.com/github/NREL/OCHRE/blob/main/notebook/user_tutorial.ipynb"
},
"split_keywords": [
"building energy modeling",
" demand flexibility",
" grid-interactive buildings",
" residential buildings"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6ef9882220c195e88e9d94c2cd7666bdae5d0cc857022ad6181dba3a81cde95d",
"md5": "2c763d520bbec401bbc89384b6d2cd81",
"sha256": "c274abcbe4bb88b6ce814a6ead2eec5502f9cd65ee123b252357fc98189ef36c"
},
"downloads": -1,
"filename": "ochre_nrel-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c763d520bbec401bbc89384b6d2cd81",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 44772372,
"upload_time": "2025-02-14T17:14:20",
"upload_time_iso_8601": "2025-02-14T17:14:20.294918Z",
"url": "https://files.pythonhosted.org/packages/6e/f9/882220c195e88e9d94c2cd7666bdae5d0cc857022ad6181dba3a81cde95d/ochre_nrel-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6c8260f8842058e4a3b1de7cb43a2f9608cd4197bc58ec0345651ca639efb56c",
"md5": "5ac0e3de563eaac9c056e293991085cf",
"sha256": "71423fd7564fd3912837fdc0538b8b1343d53906e5cbe89b567eb0c8c96f7c27"
},
"downloads": -1,
"filename": "ochre_nrel-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "5ac0e3de563eaac9c056e293991085cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 45741115,
"upload_time": "2025-02-14T17:16:00",
"upload_time_iso_8601": "2025-02-14T17:16:00.905461Z",
"url": "https://files.pythonhosted.org/packages/6c/82/60f8842058e4a3b1de7cb43a2f9608cd4197bc58ec0345651ca639efb56c/ochre_nrel-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-14 17:16:00",
"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
