Models ~ derConsumer - nreca-bts/omf GitHub Wiki

❗ NOTE ❗ omf.models.derConsumer is a new model currently under development. Check back in the coming months for updates!

Introduction

TODO:

  • Describe the purpose of the model and the use cases it was developed to address.

The derConsumer model evaluates the financial cost-benefit for a residential consumer interested in installing or enrolling behind-the-meter distributed energy resources (DERs) with their electric utility or cooperative.

This model uses the National Renewable Energy Laboratory's Renewable Energy Optimization Tool (REopt) and the OMF virtual battery dispatch module (vbatDispatch).

The estimated runtime of the model (for the first time; including building and compiling the REopt Julia system image) is about 8.5 minutes for MacOS running with the Apple M2 architecture. On a Windows machine, building the REopt Julia system image can take about 1.5 hours. Fortunately, after this initial run the model should compile much faster (on the order of 30 seconds for the same MacOS system).

Walkthrough

(Descriptions of required input formats, how to prepare a custom model. Inputs from the default model are used as illustrative examples.)

Inputs

General Model Inputs

  • Demand Curve (.csv file) — Default: residential_PV_load_tenX.csv. The demand curve should be formatted as a .csv file with a length of 8760 values representing the hourly demand (kW) for one entire year beginning on January 1. You may be able to obtain a demand curve from your electric utility or cooperative. 
    8.538
8.7564
8.6784
8.6524
9.11
10.0928
11.2472
10.8624
9.8068
9.0112
...
8.1844
8.1272
8.3768
10.5712
12.3236
12.8072
12.724
12.7188
11.7568
10.5036
10.7324
  • Temperature Curve (.csv file) — Default: open-meteo-denverCO-noheaders.csv. This is assumed to be the outdoor air temperature corresponding to your utility’s service area and year of the provided Demand Curve. The format is the same as the Demand Curve: a .csv file with a length of 8760 values representing the hourly temperature data in degrees Fahrenheit for the entire year. An example of a valid .csv (shortened for brevity): 
    4.6
3.3
2.7
2.8
3.6
4.4
2.8
5.1
5.2
6
...
17.9
17.9
18.4
17.4
16
11.4
10.8
10.7
10.6
10.6
10.4

    A temperature curve .csv can be obtained using the following steps:

    OpenMeteo Historical Weather Data API

    • Enter the latitude and longitude of the utility or cooperative service area.
    • The timezone should be the local time corresponding to the Demand Curve data.
    • Enter the Start Date (ex. 2018-01-01) and End Date (ex. 2018-12-31).
    • Under the Hourly Weather Variables section, select “Temperature” only.
    • Under Settings, select the Temperature Unit to be Fahrenheit. The other options may be left as the default values.
    • Under API Response, reload the chart by pressing the “Reload Chart” button.
    • Download the .csv file by clicking the “Download CSV” button located under the API Response Chart that was just reloaded.

      • AFTER DOWNLOADING THE .CSV, YOU MUST EDIT THE .CSV FILE BY DOING THE FOLLOWING:
      • Open the .csv file after downloading. It may be in your Downloads folder, or wherever your files go when they are downloaded. You want to be able to make changes and edit the file (e.g. the easiest way would be to open the file in Excel, Google Sheets, CryptPad Spreadsheet, OnlyOffice Spreadsheet, or some other spreadsheet program). The .csv file should look like this:
        • open-meteo-googlesheet-example
      • Delete the header rows and the timestamp column. The .csv file should look like this when you upload it to derUtilityCost:
        • open-meteo-googlesheets-example-edited
      • Be sure that there are 8760 rows total. Save the file (e.g. if you’re using Google Sheets, go to File > Download > Comma Separated Values (.csv). Now you can upload the .csv file to the Temperature Curve input!
  • Latitude (decimal) — Default: 39.969753. The latitude coordinate of the member-consumer’s house or meter. The default case assumes the latitude for Brighton, CO.
  • Longitude (decimal) — Default: -104.812599. The longitude coordinate of the member-consumer’s house or meter. The default case assumes the latitude for Brighton, CO.
  • Year (int) — Default: 2018. The year corresponding to the Demand Curve values.

Financial Inputs

  • Use URDB Label? (checkbox) — Default: Checked. If this input is checked, the model will use the provided URDB Label to obtain energy rate structure information for the analysis. If it is unchecked, the model will instead use the Residential Rate Structure file as the energy rate structure for the analysis.
  • URDB Label (string) — Default: 66a13566e90ecdb7d40581d2. The Utility Rate Database (URDB) is a free Open Energy Information database containing rate structures for utilities and cooperatives across Turtle Island (a.k.a the United States). The default case is a Residential Time of Day rate structure. You can obtain the URDB label by copying the string of letters and numbers found at the end of the Utility Rate Database (URDB) URL. For example,

    https://openei.org/apps/IURDB/rate/view/66a13566e90ecdb7d40581d2

    would yield the URDB label: 66a13566e90ecdb7d40581d2

    NOTE: Remove the suffix “#3__Energy”, “#2__Demand”, or “#1__Basic_Information” in the URDB label, if needed. This can be seen at the end of the website link when retrieving your URDB label: https://apps.openei.org/USURDB/rate/view/66a13566e90ecdb7d40581d2\#3__Energy This happens when you have clicked on one of those pages to view the rate information which changes the URL.)

  • Residential Rate Structure (Optional) (.json file) (%) — Default: TODrate66a13566e90ecdb7d40581d2.json. This is a .json file describing the energy rate structure that a residential customer pays to the utility or cooperative. This input allows a utility to upload a custom rate structure if the URDB Label is not known or is incorrect. An example of a valid .json file: 
    {"energyweekdayschedule":[[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1]],
"energyweekendschedule":[[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1]],
"energyratestructure":[[{"rate":0,"unit":"kWh"}],[{"rate":0.06,"unit":"kWh"}],[{"rate":0.1525,"unit":"kWh"}]],
"demandratestructure":[[{"rate":0,"unit":"kW"}],[{"rate":4.0,"unit":"kW"}]],
"demandweekdayschedule":[[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1]],
"demandweekendschedule":[[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1]]}

    The example above was created using the REopt Web Tool custom electric rate tariff generator following their instructions here: https://github.com/NREL/REopt-Analysis-Scripts/wiki/5.-Custom-Electric-Rates. The rate structure information was based on a Colorado utility's Time of Day residential rate structure found at https://apps.openei.org/USURDB/rate/view/66a13566e90ecdb7d40581d2#3__Energy.

  • Discount Rate (%) — Default: 1. The discount rate is used to devalue future incomes in the financial analysis (e.g. when calculating the Net Present Value). Income received now is generally more valuable than income received later.
  • Financial Projection Length (years) — Default: 25. Number of years to project out the estimated savings. Must be between 1 and 75 years. Note that since the input Demand Curve and Energy Rate Curve are only given for the first year of the analysis, all subsequent years will duplicate the first year’s costs and savings. For example, if the total savings for the first year amount to $100 and the Financial Projection Length is 10 years, then each year will use $100 as the savings.
  • Energy Compensation Rate ($/kWh) — Default: 0.1. The dollar amount paid to you by the utility for each kWh borrowed for each DER technology (e.g. fossil fuel generator, chemical BESS, and all thermal technologies).
  • Home BESS - Upfront Subsidy Amount ($) — Default: 100.0. The total upfront dollars paid to you by the utility for enrolling your home battery (not including any recurring subsidies).
  • Home BESS - Monthly Recurring Subsidy Amount ($) — Default: 55.0. The total monthly recurring dollars paid to you by the utility for keeping your home battery enrolled (not including any upfront subsidies).
  • Home Heat Pump - Upfront Subsidy Amount ($) — Default: 25.0. The total upfront dollars paid to you by the utility for enrolling your heat pump (not including any recurring subsidies).
  • Home Heat Pump - Monthly Recurring Subsidy Amount ($) — Default: 5.0. The total monthly recurring dollars paid to you by the utility for keeping your home heat pump enrolled (not including any upfront subsidies).
  • Home Air Conditioner - Upfront Subsidy Amount ($) — Default: 25.0. The total upfront dollars paid to you by the utility for enrolling your air conditioner (not including any recurring subsidies).
  • Home Air Conditioner - Monthly Recurring Subsidy Amount ($) — Default: 5.0. The total monthly recurring dollars paid to you by the utility for keeping your home air conditioner enrolled (not including any upfront subsidies).
  • Home Water Heater - Upfront Subsidy Amount ($) — Default: 25.0. The total upfront dollars paid to you by the utility for enrolling your water heater (not including any recurring subsidies).
  • Home Water Heater - Monthly Recurring Subsidy Amount ($) — Default: 5.0. The total monthly recurring dollars paid to you by the utility for keeping your home water heater enrolled (not including any upfront subsidies).
  • Home Generator - Upfront Subsidy Amount ($) — Default: 25.0. The total upfront dollars paid to you by the utility for enrolling your home generator (not including any recurring subsidies).
  • Home Generator - Monthly Recurring Subsidy Amount ($) — Default: 5.0. The total monthly recurring dollars paid to you by the utility for keeping your home generator enrolled (not including any upfront subsidies).

Fossil Fuel Generator Device Inputs

The model assumes these default inputs when the specified Fuel Type is selected.

Fuel Type Efficiency Fuel Cost[1] Available Fuel
Natural Gas 30%[4] $0.00386/cu.ft. 1000 cu.ft.
Propane 25%[2][4] $2.70/gallon 1000 gallons
Diesel 35%[3][4] $3.80/gallon 1000 gallons
Gasoline 25%[3][4] $3.17/gallon 1000 gallons
  • Enable Use of Fossil Fuel Generator? (Yes/No) — Default: Yes. If yes, the model will run with a fossil fuel generator. If no, the fossil fuel generator will not be included in the analysis.
  • Fuel Type (Natural Gas|Propane|Diesel|Gasoline) — Default: Diesel. Type of fossil fuel used for the generator.
  • Rated Power Capacity (kW) — Default: 5. Specify the operating power of the fossil fuel generator.
  • Efficiency (\%) — Default: 35. Specify the efficiency of the generator. The default value assumes a diesel fuel generator.
  • Retrofit Cost (\$) — Default: 0.0. Specify the cost to enable the generator for utility control.
  • Available Fuel — Default: 1000. Specify the annual amount of generator fuel available. For natural gas, this input expects units of cubic feet. For all other liquid fuels, the expected units are gallons. The default value assumes a diesel fuel generator with 1000 gallons of fuel available.
  • Fuel Cost — Default: 3.80. Specify the cost of fuel used for the generator. For natural gas, this input expects units of \$/cubic foot. For all other liquid fuels, the expected units are \$/gallon. The default value assumes a diesel fuel generator.
  • Generator Replacement Cost (\$/kWh) — Default: 450. Specify the cost of replacing the generator in the specified year in \$/kW.
  • Generator Lifetime (years) — Default: 15. Specify after how many years in which the generator will be replaced at the cost specified in the Generator Replacement Cost input. Input is an integer less than or equal to the analysis period in years.

Chemical Battery Energy Storage System (BESS)

  • Enable Use of Home Chemical BESS? (Yes/No) — Default: Yes. If Yes, model will run with a home chemical battery. If No, the model will not run with a home chemical battery.
  • Battery Power Capacity (kW) — Default: 5. Specify the home chemical battery power capacity in kW.
  • Battery Energy Capacity (kWh) — Default: 13.5. Specify the home chemical battery energy capacity in kWh.
  • Retrofit Cost ($) — Default: 0.0. Specify the cost to enable the battery for utility control. Typically, the BESS will already be enabled and this cost will be 0.
  • Portion of Charge Shared with Utility (%) — Default: 20. The maximum percentage of full charge that you will allow the utility to use at any time.
  • Battery Replacement Power Cost ($/kW) — Default: 324.0. Specify the cost of replacing the battery inverter at the specified year in $/kW.
  • Battery Replacement Energy Cost ($/kWh) — Default: 351.0. Specify the cost of replacing the battery capacity at the specified year in $/kWh.

    NOTE: The total battery replacement cost is modeled as (BESS Power Capacity in kW) * ($324/kW) + (BESS Energy Capacity in kWh) * ($351/kWh). These values were derived by reducing the 2022 values from Figure 4 in NREL FY23 OSTI to 90%.

  • Battery Lifetime (years) — Default: 10. Specify a year in which the battery cells will be replaced at the cost specified in Battery Replacement Capacity Cost. Input is an integer less than or equal to the analysis period in years.
  • Inverter Replacement Cost ($) — Default: 2400. Specify the cost of replacing the inverter.
  • Inverter Lifetime (years) — Default: 10. Specify a year in which the battery inverter will be replaced at the cost specified in Inverter Replacement Cost. Input is an integer less than or equal to the analysis period in years.

Home Air Conditioner Device Inputs

  • Enable Air Conditioner? (Yes/No) — Default: Yes. If Yes, the model will run with an in-window home air conditioner unit. If No, the model will not run with a home air conditioner.
  • Rated Power (kW) — Default: 0.5. Maximum input power of the unit. Must be a positive rational number between 0.1 and 7.2.
  • Retrofit Cost ($) — Default: 13. Cost to equip air conditioner to respond to utility load control signals. E.g. for a virtual power plant program, this would be the cost of installing a Wi-Fi enabled air conditioner control unit, typically about \$13. 5(#5)
  • Thermal Capacitance (kWh/°C) — Default: 2. Thermal capacitance of the air conditioner unit. Must be between 0.2 and 2.5 with exactly one decimal digit.
  • Thermal Resistance (°C/kW) — Default: 2. Thermal resistance of the air conditioner unit. Must be between 1.5 and 140.
  • Coefficient of Performance — Default: 2.5. Coefficient of performance for the air conditioner unit. Must be between 1 and 3.5.
  • Temperature Setpoint (°C) — Default: 22.5. Target temperature for the unit, set at the thermostat. Must be between 1.7 and 54.
  • Temperature Deadband (°C) — Default: 0.625. Deadband around the setpoint; avoids excessive cycling of heat pump. Must be between 0.125 and 2.

Home Heat Pump Device Inputs

  • Enable Heat Pump? (Yes/No) — Default: Yes. If Yes, the model will run with a home air-source heat pump.
  • Rated Power (kW) — Default: 5.6. Maximum input power of the heat pump. Must be a positive rational number between 0.1 and 7.2.
  • Retrofit Cost ($) — Default: 150. Cost to equip heat pump to respond to utility load control signals.
  • Thermal Capacitance (kWh/°C) — Default: 2. Thermal capacitance of the heat pump. Must be between 0.2 and 2.5 with exactly one decimal digit.
  • Thermal Resistance (°C/kW) — Default: 2. Thermal resistance of the heat pump. Must be between 1.5 and 140.
  • Coefficient of Performance — Default: 3.5. Coefficient of performance for the heat pump. Must be between 1 and 3.5
  • Temperature Setpoint (°C) — Default: 19.5. Target temperature for the tank, set at the thermostat. Must be between 1.7 and 54.
  • Temperature Deadband (°C) — Default: 0.625. Deadband around the setpoint; avoids excessive cycling of heat pump. Must be between 0.125 and 2.

Home Water Heater Device Inputs

  • Enable Water Heater? (Yes/No) — If yes, model will run with a home water heater.
  • Rated Power (kW) — Default: 4.5. Maximum input power of the water heater. Must be a positive rational number between 0.1 and 7.2.
  • Retrofit Cost (\$) — Default: 175. Cost to equip water heater to respond to utility load control signals. E.g. for a virtual power plant program, this would be the cost of installing a Wi-Fi enabled water heater control unit, typically about \$175 (see [Aquanta Smart Electric Water Heater Controller](https://www.nysegsmartsolutions.com/Water-Fixtures/I-AQCAG100E-01-XXXX-XXXX-V1.html?srsltid=AfmBOoo--7Idu156g5c0j01oWowfjP4G50-wJW0ENwo3sZHoE7iQsvuL)).
  • Thermal Capacitance (kWh/°C) — Default: 0.4. Thermal capacitance of the water tank. Must be between 0.2 and 2.5 with exactly one decimal digit.
  • Thermal Resistance (°C/kW) — Default: 120. Thermal resistance of the water tank. Must be between 1.5 and 140.
  • Coefficient of Performance — Default: 1. Coefficient of performance for the water heater. Must be between 1 and 3.5
  • Temperature Setpoint (°C) — Default: 48.5. Target temperature for the tank, set at the thermostat. Must be between 1.7 and 54.
  • Temperature Deadband (°C) — Default: 3. Deadband around the setpoint temperature to alleviate swings in temperature. Must be between 0.125 and 3.

Model Results

(Descriptions of model outputs and how to interpret them in context of the model use case(s).)

The chosen color schemes used for these plots are based on the following guide for color-blind friendly color schemes: 2022 NCEAS Science Communication Resource Corner by Alexandra Phillips

Plot: DER dispatch schedule with new BESS

Plot: DER Serving Load Overview (using REopt)

Table: Monthly Cost Comparison

Plot: Cash Flow Projection

References

[1] These values were based on the reported values from NRECA’s Weekly Fuel Price Watch in March 2025.

[2] Thermal Efficiency of Propane fuel can range from 25-34%. Figure 10 of this research article shows the effective thermal efficiencies for various engine speeds, specifically for propane and gasoline. The efficiency ranges from 25-34% for propane, and 28-33% for gasoline.

[3] The Efficiency of Diesel Generators: A Comprehensive Analysis. This resource claims that the thermal efficiency range is 20-30% for gasoline fuel and 35-45% for diesel fuel.

[4] Thermal Efficiency of Gasoline fuel can range Sustainable Maintenance: How Does Generator Efficiency Vary Across Fuel Types? This resource claims that the thermal efficiencies are 20-30% for gasoline fuel, 25-35% for natural gas fuel, 25-30% for propane fuel, and 30-40% for diesel fuel.

[5] See Enbrighten 125-Volt-1-Outlet Indoor Smart Plug About $13 in April 2025.

⚠️ **GitHub.com Fallback** ⚠️