Input Files and Arguments¶
HPXML File¶
OCHRE uses the Home Performance eXtensible Markup Language, or HPXML, file format for defining building properties. HPXML provides a standardized format for all the relevant inputs for a building energy model of a residential building. The full HPXML schema and a validator tool is available here. HPXML is continuously updated to account for additional relevant properties, and in some cases extension elements can be used to store additional information not currently included in the schema.
Standardized data format designed for interoperability between stakeholders
Generated during audits with REM/Rate, but also by other NREL tools like ResStock (or any other OS-HPXML based workflow)
HPXML integration allows us to quickly generate corresponding models suitable for co-simulation based on other workflows
Schedule Input File¶
A schedule input file is optional but highly recommended. OS-HPXML has two different types of occupancy models it supports: “asset” and “operational” (see here for more information). The “asset” occupant model uses the schedules defined in ANSI/RESNET 301 for all occupant driven loads, but note that these schedules represent a smooth average usage for all of the occupant driven loads (hot water usage, dishwasher, clothes washer, clothes dryer, and cooking range) as well as occupancy itself. The “operational” calculation uses a stochastic event generator (described here) to model more realistic events associated with the occupant driven loads. The operational (or stochastic) model is most often used in OCHRE as it more realistically models the on/off usage of these devices and therefore gets a better estimate of the power spikes associated with their usage.
The schedule file (usually named “schedules.csv”) is generated when using ResStock or when using BEopt and selecting stochastic schedules for each end use. The file contains all necessary times series schedule information for load profiles as well as hourly temperature setpoints for both thermostats and water heaters (See the OS-HPXML documentation for more information.
Tip: The load profile values in the schedule input file are normalized. OCHRE can save a schedule file after initialization that contains load profiles for each scheduled equipment in units of kW.
Weather File¶
A weather input file is required for simulating a dwelling. OCHRE accepts EnergyPlus and National Solar Radiation Database (NSRDB) weather file formats.
Generating Input Files¶
A large advantage to using HPXML is the interoperability it provides, particularly with other NREL building energy modeling tools. HPXML files can be generated using the OS-HPXML workflow, which is documented here. This workflow is used in both BEopt (version 3.0 or later) and ResStock (version 3.0 or later). As a result, a user familiar with these other tools generates OCHRE input files as part of their normal workflow. This allows these other tools to be used as a front end and enables quick comparisons between OCHRE and EnergyPlus. OCHRE has been tested with HPXML files from both workflows, but note it does not currently support all of the features of these tools.
HPXML and occupancy schedule input files can be generated from:
BEopt 3.0 or later: best for designing a single building model. Includes a user interface to select building features. Note that the occupancy schedule file is optional; users must specify stochastic occupancy in BEopt. To generate input files from BEopt, run your model as usual. The input files you need for OCHRE (in.hpxml and schedules.csv) will be automatically generated and are located in ‘C:/Users/your_username/Documents/BEopt_3.0.x/TEMP1/1/run’. BEopt generates several xml files as part of the workflow, but the one OCHRE is looking for is always within the run directory.
End-Use Load Profiles Database: best for using pre-existing building models
ResStock: best for existing ResStock users and for users in need of a large sample of building models.
Weather input files can be generated from:
BEopt or EnergyPlus: for TMY weather files in EPW format
NSRDB: for TMY and AMY weather files in NSRDB format
The ResStock dataset: for weather files that align with ResStock-generated HPXML files.
Dwelling Arguments¶
A Dwelling model can be initialized using:
from OCHRE import Dwelling
house = Dwelling(**dwelling_args)
where dwelling_args is a Python dictionary of Dwelling arguments.
The table below lists the required arguments for creating a Dwelling model.
Argument Name |
Argument Type |
Description |
|---|---|---|
|
|
Simulation start time |
|
|
Simulation timestep |
|
|
Simulation duration |
|
string |
Path to hpxml file |
|
string |
Path to weather file |
|
string |
Path to directory of weather files [1] |
The table below lists the optional arguments for creating a Dwelling model.
Argument Name |
Argument Type |
Default Value |
Description |
|---|---|---|---|
|
string |
None |
Name of the simulation |
|
string |
None |
Path to schedule input file |
|
|
None |
Length of “warm up” simulation for initial conditions [2] |
|
string |
None [3] |
Use |
|
int |
1 |
Verbosity of the outputs, from 0-9. See Outputs and Analysis for details. |
|
int |
1 |
Verbosity of metrics, from 0-9. See Dwelling Metrics for details. |
|
string |
Path to saved output files |
|
|
boolean |
False |
Save time series data as parquet (instead of .csv) |
|
|
None [6] |
Time resolution to save results |
|
boolean |
|
Save results, including time series, metrics, status, and schedule outputs |
|
boolean |
|
Save all input arguments to .json file, including user defined arguments. [7] |
|
boolean |
|
Save status file for is simulation completed or failed |
|
list |
Empty list |
List of time series inputs to save to schedule outputs file |
|
pandas.DataFrame |
None |
Schedule with equipment and weather data that overrides the |
|
datetime.timedelta |
None |
Time resolution for external controller. Required for Duty Cycle control. |
|
int or string |
HPXML or schedule file |
Random seed for initial temperatures and EV event data |
|
dict |
empty dict |
Dictionary that directly modifies values from HPXML file |
|
dict |
empty dict |
Includes envelope specific arguments |
|
dict |
empty dict |
Includes equipment specific arguments |
While not required, a warm up period is recommended. The warm up gets more accurate initial conditions
for the simulation by running a few prior days. Warm up is particularly helpful for simulation with a
shorter duration
None means no time zone is modeled or considered.
Can also accept any time zone in pyzt.all_timezones
Default location is same as HPXML file
Default is time step for time series data
If False and verbosity > 3, .json will only include HPXML properties
If verbosity > 0, else FALSE
Envelope arguments can be included to modify the default envelope model
that is based on the HPXML file. The table below lists optional arguments for
the Envelope dictionary.
Argument Name |
Argument Type |
Default Value |
Description |
|---|---|---|---|
|
number |
Random temperature within HVAC deadband |
Initial temperature for Indoor zone. It is set before the initialization time |
|
boolean |
FALSE |
Linearizes infiltration heat pathways and incorporates in state space matrices |
|
string |
“full” |
Option to use detailed radiation method (“full”), linearized radiation (“linear”), or no radiation (None) |
|
string |
“full” |
Option to use detailed radiation method (“full”), linearized radiation (“linear”), or no radiation (None) |
|
integer |
None |
Number of states for envelope model reduction |
|
number |
None |
Minimum accuracy to determine number of states for envelope model reduction |
|
boolean |
FALSE |
Saves envelope state space matrices to files |
|
|
None |
Time resolution for discretizing saved matrices. If None, saves continuous time matrices |
|
dict of dicts |
Empty dict |
Includes arguments for individual zones |
The zones dictionary keys can be from the list: ['Indoor', 'Attic',
'Garage', 'Foundation']. The table below lists optional arguments for
each zone dictionary.
Argument Name |
Argument Type |
Default Value |
Description |
|---|---|---|---|
|
boolean |
True for Indoor zone, else False |
If True, OCHRE models humidity in the given zone |
|
number |
7 |
Multiplier for zone’s thermal mass (i.e., capacitance) |
|
number |
Taken from HPXML file |
Volume of the given zone |
We note that it is possible, though not recommended, to create an Envelope
object without initializing a Dwelling. This can be done for very simple
Envelope models. As an example, see the run_hvac function in
run_equipment.py.
Equipment-specific Arguments¶
An Equipment model can be initialized in a very similar way to a Dwelling. For example, to initialize a battery:
from OCHRE import Battery
equipment = Battery(**equipment_args)
where equipment_args is a Python dictionary of Equipment arguments. A full set of the equipment classes available are listed in this section, by end use.
The table below lists the required arguments for creating any standalone Equipment model. Some equipment have additional required arguments as described in the sections below.
Argument Name |
Argument Type |
Description |
|---|---|---|
|
|
Simulation start time |
|
|
Simulation time resolution |
|
|
Simulation duration |
The table below lists the optional arguments for creating any standalone Equipment model. Some equipment have additional optional arguments as described in the sections below.
Argument Name |
Argument Type |
Default Value |
Description |
|---|---|---|---|
|
string |
OCHRE |
Name of the simulation |
|
|
None (no initialization) |
Runs a “warm up” simulation to improve initial temperature values |
|
string |
None |
Name of Envelope zone if envelope model exists |
|
|
None |
Envelope model for measuring temperature impacts (required for HVAC equipment) |
|
int |
1 |
Verbosity of the outputs, from 0-9. See Outputs and Analysis for details |
|
string |
HPXML or equipment schedule file directory |
Path to saved output files |
|
boolean |
FALSE |
Save time series files as parquet files (False saves as csv files) |
|
|
None (no intermediate data export) |
Time resolution to save results to files |
|
boolean |
True if verbosity > 0 |
Save results files, including time series files, metrics file, schedule output file, and status file |
|
boolean |
FALSE |
Save all input arguments to json file, including user defined arguments. If False and verbosity >= 3, the json file will only include HPXML properties. |
|
boolean |
True if save_results is True |
Save status file to indicate whether the simulation is complete or failed |
|
boolean |
FALSE |
Include equivalent battery model data in results |
|
list |
Empty list |
List of time series inputs to save to schedule output file |
|
string |
None |
File with equipment time series data. Optional for most equipment |
|
dict |
None |
Dictionary of {file_column_name: ochre_schedule_name} to rename columns in equipment_schedule_file. Sometimes used for PV |
|
number |
1 |
Scaling factor to normalize data in equipment_schedule_file. Sometimes used for PV to convert units |
|
|
None |
Schedule with equipment or weather data that overrides the schedule_input_file and the equipment_schedule_file. Not required for Dwelling and some equipment |
|
|
None |
Time resolution for external controller. Required if using Duty Cycle control |
|
int or string |
HPXML or equipment schedule file |
Random seed for setting initial temperatures and EV event data |
The following sections list the names and arguments for all OCHRE
equipment by end use. Many equipment types have all of their required
arguments included in the HPXML properties. These properties can be
overwritten by specifying the arguments in the equipment_args
dictionary.
HVAC Heating and Cooling¶
OCHRE includes models for the following HVAC equipment:
End Use |
Equipment Class |
Equipment Name |
Description |
|---|---|---|---|
HVAC Heating |
|
Electric Furnace |
|
HVAC Heating |
|
Electric Baseboard |
|
HVAC Heating |
|
Electric Boiler |
|
HVAC Heating |
|
Gas Furnace |
|
HVAC Heating |
|
Gas Boiler |
|
HVAC Heating |
|
Heat Pump Heater |
Air Source Heat Pump with no electric resistance backup |
HVAC Heating |
|
ASHP Heater |
Air Source Heat Pump, heating only |
HVAC Heating |
|
MSHP Heater |
Minisplit Heat Pump, heating only |
HVAC Cooling |
|
Air Conditioner |
Central air conditioner |
HVAC Cooling |
|
Room AC |
Room air conditioner |
HVAC Cooling |
|
ASHP Cooler |
Air Source Heat Pump, cooling only |
HVAC Cooling |
|
MSHP Cooler |
Minisplit Heat Pump, cooling only |
The table below shows the required and optional equipment-specific arguments for HVAC equipment.
Argument Name |
Argument Type |
Required? |
Default Value |
Description |
|---|---|---|---|---|
|
|
Yes |
Envelope model for measuring temperature impacts |
|
|
boolean |
No |
True if time_res >= 5 minutes or for variable-speed equipment |
If True, OCHRE sets HVAC capacity to meet the setpoint. If False, OCHRE uses thermostat deadband control |
|
number or list of numbers |
Yes |
Taken from HPXML |
Rated capacity of equipment. If a list, it is the rated capacity by speed |
|
number |
No |
0 |
Minimum equipment capacity for ideal capacity equipment models |
|
number |
No |
Taken from HPXML file, or 1 |
Conditioned space fraction, e.g., for Room Air Conditioners |
|
number or list of numbers |
Yes |
Taken from HPXML file, or from Rated Efficiency |
Energy input ratio (i.e., the inverse of the COP). If a list, it is the EIR by speed |
|
number or list of numbers |
No |
Taken from HPXML file, or from Rated Efficiency, or 1 |
Sensible heat ratio. If a list, it is the SHR by speed. Only for HVAC Cooling equipment |
|
number |
Yes |
Taken from HPXML file |
Rated auxiliary power, including fan or pump power |
|
dict |
Yes |
Taken from first row of schedule |
Dictionary of initial values in schedule |
|
dict |
No |
Taken from HPXML file, or sets distribution system efficiency to 1 |
Dictionary of inputs to determine HVAC distribution system efficiency |
|
number |
No |
0.2 for heaters if there is a conditioned basement, otherwise 0 |
Ratio of airflow and HVAC capacity to send to conditioned basement. For heaters only |
|
number |
No |
Taken from HPXML file or schedule file |
Constant setpoint temperature |
|
list of 24 numbers |
No |
Taken from HPXML file or schedule file |
Hourly weekday setpoint temperatures by hour |
|
list of 24 numbers |
No |
Taken from HPXML file or schedule file |
Hourly weekend setpoint temperatures by hour. Defaults to weekday temperatures if they are included. |
|
number |
No |
Taken from HPXML file, or 1 |
Size of temperature deadband in degC. Can also be specified in the schedule |
|
number |
No |
0.2 for ASHP Heater, otherwise None |
Maximum ramp rate of thermostat setpoint, in degC/min |
|
boolean |
No |
FALSE |
If True, show EIR and SHR in results for all time steps. If False, they will be set to 0 when the equipment is off |
|
int |
No |
Taken from HPXML file, or 1 |
Number of speeds. Options are 1 (single speed), 2 (double speed), 4 (variable speed), or 10 (mini-split HP only) |
|
string |
Only if Number of Speeds > 1 |
Taken from HPXML file, or None |
Rated SEER or HSPF. Used to determine the capacity, EIR, and SHR ratios of each speed |
|
number |
Only for ASHP Heater |
ASHP Heater supplemental heater capacity |
|
|
number |
No |
1 |
ASHP Heater supplemental heater energy input ratio |
|
number |
No |
None |
Temperature to shut off heat pump for ASHP Heater |
Water Heating¶
OCHRE includes models for the following Water Heating equipment:
End Use |
Equipment Class |
Equipment Name |
|---|---|---|
Water Heating |
|
Electric Tank Water Heater |
Water Heating |
|
Gas Tank Water Heater |
Water Heating |
|
Heat Pump Water Heater |
Water Heating |
|
Tankless Water Heater |
Water Heating |
|
Gas Tankless Water Heater |
The table below shows the required and optional equipment-specific arguments for Water Heating equipment.
Argument Name |
Argument Type |
Required? |
Default Value |
Description |
|---|---|---|---|---|
|
boolean |
No |
True if time_res >= 5 minutes |
If True, OCHRE sets water heater capacity to meet the setpoint. If False, OCHRE uses thermostat deadband control |
|
int |
No |
12 if Heat Pump Water Heater, 1 if Tankless Water Heater, otherwise 2 |
Number of nodes in water tank model |
|
number |
No |
4500 |
Water heater capacity |
|
number |
No |
1 |
Water heater efficiency (or supplemental heater efficiency for HPWH) |
|
number |
Yes |
Taken from HPXML file, or 51.67 |
Water heater setpoint temperature. Can also be set in schedule |
|
number |
No |
8.17 for Heat Pump Water Heater, otherwise 5.56 |
Water heater deadband size. Can also be set in schedule |
|
number |
No |
60 |
Maximum water tank temperature |
|
number |
No |
40.56 |
Hot water temperature for tempered water draws (sinks, showers, and baths) |
|
number |
No |
Setpoint temperature - 10% of deadband temperature |
Initial temperature of the entire tank (before initialization routine) |
|
number |
No |
None |
Maximum rate of change for setpoint temperature |
|
number |
Yes |
Taken from HPXML file |
Size of water tank, in L |
|
number |
Yes |
Taken from HPXML file |
Height of water tank, used to determine surface area |
|
number |
Yes |
Taken from HPXML file |
Heat transfer coefficient of water tank |
|
boolean |
No |
FALSE |
Disable supplemental heater for HPWH |
|
number |
Only for Heat Pump Water Heater |
Coefficient of Performance for HPWH |
|
|
number |
No |
500 (for HPWH Power) |
Capacity or rated power for HPWH |
|
number |
No |
1 |
Parasitic power for HPWH |
|
number |
No |
35 |
Fan power for HPWH |
|
number |
No |
0.88 |
Sensible heat ratio for HPWH |
|
number |
No |
0.75 if in Indoor Zone else 1 |
Fraction of HPWH sensible gains to envelope |
|
number |
No |
0.5 |
Fraction of HPWH sensible gains to wall boundary, remainder goes to zone |
|
number |
Only for Gas Water Heater |
Taken from HPXML file |
Water heater energy factor (EF) for getting skin loss fraction |
|
number |
Only for Gas Tankless Water Heater |
Taken from HPXML file |
Parasitic power for Gas Tankless Water Heater |
Electric Vehicle¶
OCHRE includes an electric vehicle (EV) model. The equipment name can be “EV” or “Electric Vehicle”. The table below shows the required and optional equipment-specific arguments for EVs.
Argument Name |
Argument Type |
Required? |
Default Value |
Description |
|---|---|---|---|---|
|
string |
Yes |
BEV, if taken from HPXML file |
EV vehicle type, options are “PHEV” or “BEV” |
|
string |
Yes |
Level 2, if taken from HPXML file |
EV charging type, options are “Level 1” or “Level 2” |
|
number |
Yes |
100 miles if HPXML Annual EV Energy < 1500 kWh, otherwise 250 miles |
EV battery capacity in kWh or mileage in miles |
|
boolean |
No |
True if charging_level = Level 2 |
Allows EV to charge at partial load |
|
number |
No |
Taken from schedule, or 20 C |
Ambient temperature used to estimate EV usage per day |
|
string |
No |
Default file based on |
File for EV event scenarios |
Battery¶
OCHRE includes a battery model. The table below shows the required and optional equipment-specific arguments for batteries.
Argument Name |
Argument Type |
Required? |
Default Value |
Description |
|---|---|---|---|---|
|
number |
No |
10 |
Nominal energy capacity of battery, in kWh |
|
number |
No |
5 |
Max power of battery, in kW |
|
number |
No |
0.98 |
Battery Discharging Efficiency, unitless |
|
number |
No |
0.98 |
Battery Charging Efficiency, unitless |
|
number |
No |
0.97 |
Inverter Efficiency, unitless |
|
string |
No |
“advanced” |
Efficiency calculation option. Options are “advanced”, “constant”, “curve”, and “quadratic” |
|
number |
No |
0.5 |
Initial State of Charge, unitless |
|
number |
No |
0.95 |
Maximum SOC, unitless |
|
number |
No |
0.15 |
Minimum SOC, unitless |
|
boolean |
No |
TRUE |
If True, runs an energy capacity degradation model daily |
|
number |
No |
50.4 |
Initial open circuit voltage, in V. Used for advanced efficiency and degradation models. |
|
number |
No |
3.6 |
Cell voltage, in V. Used for advanced efficiency and degradation models. |
|
number |
No |
70 |
Cell capacity, in Ah. Used for advanced efficiency and degradation models. |
|
number |
No |
0 |
Cell resistance, in ohm. Used for advanced efficiency and degradation models. |
|
number |
No |
9 |
Schedule: Charge Start Time, in hour of day |
|
number |
No |
16 |
Schedule: Discharge Start Time, in hour of day |
|
number |
No |
1 |
Schedule: Charge Power, in kW |
|
number |
No |
1 |
Schedule: Discharge Power, in kW |
|
number |
No |
0 |
Self-Consumption: Force Charge from Solar, in boolean |
|
number |
No |
0 |
Self-Consumption: Grid Import Limit, in kW |
|
number |
No |
0 |
Self-Consumption: Grid Export Limit, in kW |
|
boolean |
No |
True only if zone_name or envelope is specified |
If True, creates 1R-1C thermal model for battery temperature. Temperature is used in degradation model |
|
number |
No |
0.5 |
Thermal Resistance, in K/W |
|
number |
No |
90000 |
Thermal Mass, in J/K |
|
number |
No |
zone temperature |
Solar PV¶
OCHRE includes a solar PV model. The table below shows the required and optional equipment-specific arguments for PV.
Argument Name |
Argument Type |
Required? |
Default Value |
Description |
|---|---|---|---|---|
|
number |
Only when running SAM |
PV panel capacity, in kW |
|
|
number |
No |
Taken from HPXML roof pitch |
Tilt angle from horizontal, in degrees. Used for SAM |
|
number |
No |
Taken from HPXML, south-most facing roof |
Azimuth angle from south, in degrees. Used for SAM |
|
number |
No |
PV.capacity |
Inverter apparent power capacity, in kVA. Used for SAM |
|
number |
No |
Use default from SAM |
Efficiency of the inverter, unitless. Used for SAM |
|
string |
No |
“Var” |
PV inverter priority. Options are “Var”, “Watt”, or “CPF” (constant power factor) |
|
number |
No |
0.8 |
Inverter minimum power factor, unitless |
Gas Generator¶
OCHRE includes models for the following gas generator equipment:
End Use |
Equipment Class |
Equipment Name |
|---|---|---|
Gas Generator |
|
Gas Generator |
Gas Generator |
|
Gas Fuel Cell |
The table below shows the required and optional equipment-specific arguments for gas generators.
Argument Name |
Argument Type |
Required? |
Default Value |
Description |
|---|---|---|---|---|
|
number |
No |
6 |
Maximum power, in kW |
|
number |
No |
0.95 |
Discharging Efficiency, unitless |
|
string |
No |
“curve” if GasFuelCell, otherwise “constant” |
Efficiency calculation option. Options are “constant”, “curve”, and “quadratic” |
|
string |
No |
“Off” |
Control option. Options are “Off”, “Schedule”, and “Self-Consumption” |
|
number |
No |
0.1 |
Max ramp rate, in kW/min |
|
number |
No |
9 |
Schedule: Charge Start Hour |
|
number |
No |
16 |
Schedule: Discharge Start Hour |
|
number |
No |
1 |
Schedule: Charge Power, in kW |
|
number |
No |
1 |
Schedule: Discharge Power, in kW |
|
number |
No |
0 |
Self-Consumption: Grid Import Limit, in kW |
|
number |
No |
0 |
Self-Consumption: Grid Export Limit, in kW |
Other Equipment¶
OCHRE includes basic models for other loads, including appliances, lighting, and miscellaneous electric and gas loads:
End Use |
Equipment Class |
Equipment Name |
|---|---|---|
Lighting |
|
Lighting |
Lighting |
|
Exterior Lighting |
Lighting |
|
Basement Lighting |
Lighting |
|
Garage Lighting |
Other |
|
Clothes Washer |
Other |
|
Clothes Dryer |
Other |
|
Dishwasher |
Other |
|
Refrigerator |
Other |
|
Cooking Range |
Other |
|
MELs |
Other |
|
TV |
Other |
|
Well Pump |
Other |
|
Gas Grill |
Other |
|
Gas Fireplace |
Other |
|
Gas Lighting |
Other |
|
Pool Pump |
Other |
|
Pool Heater |
Other |
|
Hot Tub Pump |
Other |
|
Hot Tub Heater |
Other |
|
Ceiling Fan |
Other |
|
Ventilation Fan |
EV |
|
Scheduled EV |
The table below shows the required and optional equipment-specific arguments for other equipment.
Argument Name |
Argument Type |
Required? |
Default Value |
Description |
|---|---|---|---|---|
|
number |
No |
Taken from HPXML file, or 0 |
Fraction of power consumption that is dissipated through convection into zone |
|
number |
No |
Taken from HPXML file, or 0 |
Fraction of power consumption that is dissipated through radiation into zone |
|
number |
No |
Taken from HPXML file, or 0 |
Fraction of power consumption that is dissipated as latent heat into zone |