ECM Definition Reference

In some parts of the definition of an ECM, specific values must be entered for the ECM to be valid and successfully included in an analysis. In particular, the installed cost and energy efficiency units used must match exactly with the expected units for a given building sector, end use, and technology type. These units are defined by the EIA Annual Energy Outlook data used to define the baseline technology cost, efficiency, and lifetime.

Applicable baseline market options

For each of the keys in the applicable baseline market definition, only specific entries are expected and allowable. This section outlines those acceptable entries for each of the keys.

For some keys, there are shorthand summary values that can be used when all or a large group of more specific values for that key apply. For example, if all of the climate zones should be included in the applicable baseline market, the value “all” can be specified instead of typing out each climate zone name in a list. These shorthand values are provided after the semi-colon in the lists below. Additional notes might also be provided to further clarify the different summary values available for a given key. More information regarding the use of these shorthand values is in the Baseline market shorthand values section.

Climate zone (default regions)

AIA_CZ1 AIA Climate Zone 1 , AIA_CZ2 AIA Climate Zone 2 , AIA_CZ3 AIA Climate Zone 3 , AIA_CZ4 AIA Climate Zone 4 , AIA_CZ5 AIA Climate Zone 5 ; all

_images/climatezone-lg.jpg

Fig. 11 Map of American Institute of Architects (AIA) climate zones for the contiguous U.S., Alaska, and Hawaii.

Alternate regions

Note

These alternate regions are only permitted when ecm_prep.py is executed with the --alt_regions option, as described in Additional preparation options.

EIA Electricity Market Module (EMM) regions

TRE, FRCC, MISW, MISC, MISE, MISS, ISNE, NYCW, NYUP, PJME, PJMW, PJMC, PJMD, SRCA, SRSE, SRCE, SPPS, SPPC, SPPN, SRSG, CANO, CASO, NWPP, RMRG, BASN; all

_images/eia_emm.jpg

Fig. 12 Map of U.S. EIA Electricity Market Module (EMM) regions.

Contiguous U.S. states

AL, AZ, AR, CA, CO, CT, DE, DC, FL, GA, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY; all

_images/state_map.jpg

Fig. 13 Map of contiguous United States.

Building type

Residential: single family home, multi family home, mobile home; all residential

Commercial: assembly, education, food sales, food service, health care, lodging, large office, small office, mercantile/service, warehouse, other, unspecified; all commercial

Note

“all” can be used instead of specifying both “all residential” and “all commercial” if all residential and commercial building types apply.

Structure type

new, existing; all

Fuel type

Residential: electricity, natural gas, distillate, other fuel; all

Commercial: electricity, natural gas, distillate; all

End use

The end use names appear verbatim in the first column of the tables for residential and commercial buildings.

Note

While “all” is available for specifying all of the end uses in residential and/or commercial buildings (depending on the building types selected), its use should be limited to ECMs where a single technology can credibly affect all energy use in the building. Using the “all” option for end uses also significantly increases computational expense, and that expense will scale exponentially if uncertainty is present on any of the ECMs in the analysis.

Residential

End Use

Fuel Type

electricity

natural gas

distillate

other fuel

heating

X

X

X

X

secondary heating

X

X

X

X

cooling

X

X

water heating

X

X

X

X

cooking

X

X

X

drying

X

X

X

lighting

X

refrigeration

X

ceiling fan *

X

fans and pumps *

X

computers *

X

TVs *

X

other **

X

X

X

X

all

X

X

X

X

* These end uses and all associated technologies may currently only be specified for the add-on measure type due to the lack of available baseline cost, performance, and lifetime data for associated technologies.

** For the “other” end use, all associated technologies aside from “dishwasher,” “clothes washing,” and “freezers” may currently only be specified for the add-on measure type due to the lack of available baseline cost, performance, and lifetime data for associated technologies.

Commercial

End Use

Fuel Type

electricity

natural gas

distillate

heating

X

X

X

cooling

X

X

ventilation

X

water heating

X

X

X

lighting

X

refrigeration

X

cooking

X

X

PCs *

X

non-PC office equipment *

X

MELs *

X

other *

X

X

unspecified *

X

X

X

all

X

X

X

* These end uses and all associated technologies may currently only be specified for the add-on measure type due to the lack of available baseline cost, performance, and lifetime data for the associated technologies.

Technology

Technology names appear verbatim. For residential building types, the lighting technology names are in the body of the table, categorized by illumination technology (e.g., incandescent, fluorescent) and application or fixture type. For commercial building types, the lighting technology names are categorized generally by bulb type or application. In both cases, these categories are provided for convenience and are not used anywhere in an ECM definition.

Tip

If the technology name for a given end use and fuel type is indicated as null, the ECM definition should have the unquoted text “null” written into the technology field.

Note

“all” is available as an option to specify all of the technology names that apply to all of the building types, fuel types, and end uses specified for the applicable baseline market. In addition, “all” can be made specific to a particular end use by specifying “all” followed by the end use name – “all heating” or “all water heating,” for example. This shorthand will capture all of the technologies in the named end use that apply to the building types and fuel types included in the applicable baseline market. For example, if the building type is “single family homes” and the fuel type is specified as [“electricity”, “natural gas”] then “all heating” will include all of the heating technologies for residential buildings that use electricity or natural gas.

Residential – Supply

  • heating

    • electricity: ASHP air-source heat pump , GSHP ground-source heat pump , resistance heat

    • natural gas: NGHP air-source natural gas heat pump , boiler (NG), furnace (NG)

    • distillate: boiler (distillate), furnace (distillate)

    • other fuel: furnace (LPG), furnace (kerosene), stove (wood)

  • secondary heating

    • electricity: secondary heater

    • natural gas: secondary heater

    • distillate: secondary heater

    • other fuel: secondary heater (wood), secondary heater (coal), secondary heater (kerosene), secondary heater (LPG)

  • cooling

    • electricity: room AC, ASHP air-source heat pump , GSHP ground-source heat pump , central AC

    • natural gas: NGHP air-source natural gas heat pump

  • water heating

    • electricity: electric WH, solar WH

    • natural gas: null

    • distillate: null

    • other fuel: null

  • cooking

    • all fuel types: null

  • drying

    • all fuel types: null

  • lighting

Fixture Type

Bulb Type

incandescent/halogen

fluorescent

LED

general service

general service (incandescent)

general service (CFL)

general service (LED)

reflector

reflector (incandescent)
reflector (halogen)

reflector (CFL)

reflector (LED)

linear fixture

linear fluorescent (T-8)
linear fluorescent (T-12)

linear fluorescent (LED)

exterior

external (incandescent)
external (high pressure sodium)

external (CFL)

external (LED)

  • refrigeration: null

  • ceiling fan: null

  • fans and pumps: null

  • computers: desktop PC, laptop PC, network equipment, monitors

  • TVs: home theater and audio, set top box, video game consoles, OTT streaming devices, TV

  • other

    • electricity: dishwasher, clothes washing, freezers, rechargeables, coffee maker, dehumidifier, electric other, small kitchen appliances, microwave, smartphones, pool heaters, pool pumps, security system, portable electric spas, smart speakers, tablets, wine coolers

    • natural gas: other appliances

    • distillate: other appliances

    • other fuel: other appliances

Residential – Demand

roof, wall, infiltration, ground, windows solar, windows conduction, equipment gain, people gain

Commercial – Supply

  • heating

    • electricity: electric_res-heat electric resistance heat , comm_GSHP-heat commercial ground-source heat pump , rooftop_ASHP-heat rooftop air-source heat pump , elec_boiler electric boiler

    • natural gas: gas_eng-driven_RTHP-heat natural gas engine-driven rooftop heat pump , res_type_gasHP-heat residential-style natural gas heat pump , gas_boiler, gas_furnace

    • distillate: oil_boiler, oil_furnace

  • cooling

    • electricity: rooftop_AC, scroll_chiller, res_type_central_AC, reciprocating_chiller, comm_GSHP-cool commercial ground-source heat pump , centrifugal_chiller, rooftop_ASHP-cool rooftop air-source heat pump , wall-window_room_AC, screw_chiller

    • natural gas: gas_eng-driven_RTAC natural gas engine-driven rooftop AC , gas_chiller, res_type_gasHP-cool residential-style natural gas heat pump , gas_eng-driven_RTHP-cool natural gas engine-driven rooftop heat pump

  • ventilation: CAV_Vent constant air volume ventilation system , VAV_Vent variable air volume ventilation system

  • water heating

    • electricity: Solar water heater, HP water heater, elec_booster_water_heater, elec_water_heater

    • natural gas: gas_water_heater, gas_instantaneous_WH, gas_booster_WH

    • distillate: oil_water_heater

  • lighting

    • general service: 100W A19 Incandescent, 100W Equivalent A19 Halogen, 100W Equivalent CFL Bare Spiral, 100W Equivalent LED A Lamp,

    • PAR-38: Halogen Infrared Reflector (HIR) PAR38, Halogen PAR38, LED PAR38

    • linear fluorescent: T5 F28, T8 F28, T8 F32, T8 F59, T8 F96

    • low/high bay: T5 4xF54 HO High Bay, Mercury Vapor, Metal Halide, Sodium Vapor

    • other: LED Integrated Luminaire

  • refrigeration: Commercial Beverage Merchandisers, Commercial Ice Machines, Commercial Reach-In Freezers, Commercial Reach-In Refrigerators, Commercial Refrigerated Vending Machines, Commercial Supermarket Display Cases, Commercial Walk-In Freezers, Commercial Walk-In Refrigerators

  • cooking

    • electricity: electric_range_oven_24x24_griddle

    • natural gas: gas_range_oven_24x24_griddle

  • PCs: null

  • non-PC office equipment: null

  • MELs: distribution transformers, kitchen ventilation, security systems, lab fridges and freezers, medical imaging, large video boards, coffee brewers, non-road electric vehicles, fume hoods, laundry, elevators, escalators, IT equipment, office UPS, data center UPS, shredders, private branch exchanges, voice-over-IP telecom, point-of-sale systems, warehouse robots, televisions, water services, telecom systems, other

  • other: null

  • unspecified: null

Commercial – Demand

roof, wall, ground, floor, infiltration, ventilation, windows conduction, windows solar, lighting gain, equipment gain, people gain, other heat gain

Energy efficiency units

Residential – Equipment (Supply)

  • Heating

    • Boilers and furnaces (AFUE)

    • Wood stoves (HHV)

    • All other equipment types (COP)

  • Secondary heating

    • Electricity (COP)

    • All other fuel types (AFUE)

  • Cooling

    • Geothermal heat pumps (EER)

    • All other equipment types (COP)

  • Water heating

    • Solar water heaters (SEF)

    • All other water heaters (UEF)

  • Refrigeration (kWh/yr)

  • Cooking

    • Electricity (kWh/yr)

    • Natural gas (TEff)

    • LPG (TEff)

  • Drying (CEF)

  • Lighting (lm/W)

  • Fans and pumps (kWh/yr)

  • Ceiling fan (kWh/yr)

  • TVs (kWh/yr)

  • Computers (kWh/yr)

  • Other

    • Clothes washing (kWh/cycle)

    • Dishwasher (kWh/cycle)

    • Freezers (kWh/yr)

    • Dehumidifier (kWh/yr)

    • Microwave (kWh/yr)

    • Pool heaters and pumps (kWh/yr)

    • Portable electric spas (kWh/yr)

    • Wine coolers (kWh/yr)

  • All other end uses/equipment types (relative savings (constant) with add-on measure type designation)

Commercial – Equipment (Supply)

  • Heating (BTU out/BTU in)

  • Cooling (BTU out/BTU in)

  • Water heating (BTU out/BTU in)

  • Ventilation (cfm-hr/BTU in)

  • Cooking (BTU out/BTU in)

  • Lighting (lm/W)

  • Refrigeration (BTU out/BTU in)

  • PCs (kWh/yr)

  • All other end uses/equipment types (relative savings (constant) with add-on measure type designation)

Residential and Commercial – Sensors and Controls (Supply)

  • All sensors and controls ECMs (relative savings (constant) or relative savings (dynamic))

Residential and Commercial – Envelope Components (Demand)

  • Windows conduction (R value)

  • Windows solar (SHGC)

  • Wall, roof, and ground (R value)

  • Infiltration

    • Residential (ACH)

    • Commercial (CFM/ft^2 @ 0.3 in. w.c.)

Installed cost units

Residential – Equipment (Supply)

  • All equipment ($/unit)

Commercial – Equipment (Supply)

  • Ventilation ($/1000 CFM)

  • Lighting ($/1000 lm)

  • Heating, cooling, water heating, cooking, and refrigeration ($/kBtu/h service, e.g., $/kBtu/h heating)

  • All other equipment ($/ft^2 floor)

Residential and Commercial – Sensors and Controls (Supply)

  • All sensors and controls ECMs ($/ft^2 floor)

Residential and Commercial – Envelope Components (Demand)

  • Windows ($/ft^2 glazing)

  • Walls ($/ft^2 wall)

  • Roof ($/ft^2 roof)

  • Floor/ground ($/ft^2 footprint)

ECM JSON schema

This section outlines the elements of a JSON file that defines an energy conservation measure (ECM) – a technology included for analysis with Scout. More details about ECMs can be found in the Analysis Approach and Tutorial 1 sections.

Each sub-section corresponds to a single key in the JSON. The details provided for each key include the parent and child fields, valid data types, a brief description of the field, and one or more illustrative examples. Parent keys are above and child keys are below the current key in the hierarchy of a JSON file.

{"parent key": {
   "current key": {
      "child key": "value"}}}

The data type “none” indicates that null is a valid value for that key. The parent “root” indicates that it is at the top of the hierarchy, that is, there are no parents for that key.

name

  • Parents: root

  • Children: none

  • Type: string

A descriptive name of the technology defined in the ECM. If possible, the name length should be kept to under 55 characters including spaces. The name should not be shared with any other ECM.

{...
 "name": "Residential Natural Gas HPWH",
 ...}

climate_zone

  • Parents: root

  • Children: none

  • Type: string, list

Either a single climate zone or list of climate zones to which the ECM applies. The climate zone strings must come from the list of valid entries in the ECM Definition Reference.

{...
 "climate_zone": ["AIA_CZ2", "AIA_CZ3", ...],
 ...}
{...
 "climate_zone": ["ERCT", "CAMX", "RMPA", "AZNM", "NEWE", "NWPP", ...],
 ...}
{...
 "climate_zone": ["AL", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", ...],
 ...}

bldg_type

  • Parents: root

  • Children: none

  • Type: string, list

A single building type or a list of residential and/or commercial building types in which the ECM could be installed. The building types specified must be from the list of valid entries in the ECM Definition Reference.

{...
 "bldg_type": "all residential",
 ...}

structure_type

  • Parents: root

  • Children: none

  • Type: string, list

The structure type indicates whether the technology described by the ECM is suitable for application in new construction, completed/existing buildings, or both. Valid structure types are new, existing, or all, respectively.

{...
 "structure_type": "new",
 ...}

Tip

If the ECM technology can be applied to both new construction and existing buildings but with differing energy efficiency, installed costs, and/or service life, those differing values should be specified explicitly in the energy_efficiency, installed_cost, and/or product_lifetime fields. This specification method is explained in the Detailed input specification section.

fuel_type

  • Parents: root

  • Children: none

  • Type: string, list

The fuel type(s) should correspond to the energy source(s) used by the technology described in the ECM, and can be specified as a string for a single fuel type or as a list to include multiple fuel types. The fuel type(s) should be drawn from the list of valid fuel types.

{...
 "fuel_type": "electricity",
 ...}

Tip

If the ECM describes a technology that does not use energy directly but affects the energy use of the building, i.e., windows and building envelope, the fuel type should be specified as all.

Tip

If fuel switching is included in the ECM definition, then the fuel types listed should include all fuel types corresponding to equipment or technologies that can be supplanted by the technology described in the ECM. Further information about using the fuel_switch_to field is in the Technology and/or fuel switching section.

end_use

  • Parents: root

  • Children: none

  • Type: string, list

The end use corresponds to the type of building function that is served by the technology described in the ECM. The end use can be specified as a single string or, if multiple end uses apply, as a list. The valid end uses depend on the building type(s) and fuel type(s) specified, as indicated in the end use tables in the ECM Definition Reference.

{...
 "end_use": ["heating", "cooling"],
 ...}

Tip

If the ECM is describing a technology that affects the heating and cooling load of a building, such as insulation, windows, or an air barrier, the end uses should be given as ["heating", "cooling"].

technology

  • Parents: root

  • Children: none

  • Type: string, list

The technology field lists the specific technologies or device types that can be replaced by the technology described by the ECM. A complete listing of valid technology names is provided in the ECM Definition Reference.

{...
 "technology": ["HP water heater", "elec_water_heater", "electric WH"],
 ...}

market_entry_year

  • Parents: root

  • Children: none

  • Type: int, none

The market entry year specifies the year that the ECM entered or is expected to enter the market. The year should be given as an integer in the format YYYY. null is also an acceptable value for the market entry year, and is interpreted to mean that the ECM is available in the first year simulated in Scout.

{...
 "market_entry_year": 2019,
 ...}

market_entry_year_source

The market entry year source indicates the reference from which the market entry year for the ECM was derived. If the market entry year is null, the source can also be given as null without the dict (see market_exit_year_source).

{...
 "market_entry_year_source": {
   "notes": "",
   "source_data": [{
      "title": "High Efficiency Troffer Performance Specification, Version 5.0",
      "author": "",
      "organization": "U.S. Department of Energy",
      "year": 2015,
      "pages": null,
      "URL": "https://betterbuildingssolutioncenter.energy.gov/sites/default/files/attachments/High%20Efficiency%20Troffer%20Performance%20Specification.pdf"}]},
 ...}

market_exit_year

  • Parents: root

  • Children: none

  • Type: int, none

The market exit year indicates the final year that the technology described in the ECM is available for purchase. The year should be formatted as YYYY. null is also an acceptable market exit year value, and is interpreted as the technology remaining available through the final year simulated in Scout.

{...
 "market_exit_year": null,
 ...}

market_exit_year_source

The market exit year source indicates the original source for the exit year specified for the ECM. The field is formatted identically to the market_entry_year_source field. If the market exit year is null, the source can also be given as null without the dict.

{...
 "market_exit_year_source": null,
 ...}

energy_efficiency

The energy efficiency value(s) define the energy performance of the technology being described by the ECM. The numeric values should be given such that they correspond to the required units given in the energy_efficiency_units field.

{...
 "energy_efficiency": 2.8,
 ...}

If it is appropriate for the technology described by the ECM, the energy efficiency can be specified more precisely using one or more of the optional child fields. The values should then be reported in a dict where the keys correspond to the applicable child fields. If multiple levels of specificity are desired, the hierarchy of the nested keys must use the following order: climate_zone, bldg_type, end_use and structure_type. Additional information regarding this specification method can be found in the Detailed input specification section.

{...
 "energy_efficiency": {
   "AIA_CZ1": {
      "heating": 1.05,
      "cooling": 1.3,
      "water heating": 1.25},
   "AIA_CZ2": {
      "heating": 1.15,
      "cooling": 1.26,
      "water heating": 1.31},
   "AIA_CZ3": {
      "heating": 1.3,
      "cooling": 1.21,
      "water heating": 1.4},
   "AIA_CZ4": {
      "heating": 1.4,
      "cooling": 1.16,
      "water heating": 1.57},
   "AIA_CZ5": {
      "heating": 1.4,
      "cooling": 1.07,
      "water heating": 1.7}},
 ...}

energy_efficiency_units

This field specifies the units of the reported energy efficiency values for the ECM. The correct energy efficiency units depend on the building type, end use, and in some cases, equipment type of the technology described by the ECM. The units can be determined using the list of energy efficiency units in the ECM Definition Reference.

{...
 "energy_efficiency_units": "COP",
 ...}

In cases where the energy efficiency is specified with one or more of the optional keys, if the units are the same for all values, the units can still be reported with a single string. If the units are different for some of the keys used, a dict with a structure parallel to the energy efficiency data should be used to report the units. (Energy efficiency units are not a function of climate zone and do not have to be specified with a climate zone breakdown even if the efficiency varies by climate zone.)

{...
 "energy_efficiency_units": {
   "heating": {
      "all residential": "COP",
      "small office": "BTU out/BTU in"},
   "cooling": {
      "all residential": "COP",
      "small office": "BTU out/BTU in"}},
 ...}

Energy efficiency can also be specified with relative units, as described in the Relative energy efficiency units section, or with probability distributions on some or all values, detailed in the Probability distributions section.

energy_efficiency_source

This key is used to specify the source of the ECM’s energy efficiency (i.e., energy performance) values. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source(s) and the values in the ECM definition should be supplied in the notes field.

{...
 "energy_efficiency_source": {
   "notes": "Minimum Luminaire Efficiency value reported in section 1.4, sub-section II.a.2.a.",
   "source_data": [{
      "title": "High Efficiency Troffer Performance Specification, Version 5.0",
      "author": "",
      "organization": "U.S. Department of Energy",
      "year": 2015,
      "pages": 5,
      "URL": "https://betterbuildingssolutioncenter.energy.gov/sites/default/files/attachments/High%20Efficiency%20Troffer%20Performance%20Specification.pdf"}]},
 ...}

installed_cost

The installed cost field represents the typical total cost of the technology and installation of the technology into a building. Costs should be specified such that they are consistent with the required units for the type of technology described by the ECM.

{...
 "installed cost": 14,
 ...}

Since installation costs can vary by building type (implicitly by building square footage) and whether the technology is being installed as part of new construction or as a replacement of existing equipment or renovation of an existing building, the costs can be specified in a dict using the indicated optional child fields. The keys should match exactly with the allowable values for each of those fields.

{...
 "installed_cost": {
   "all residential": 8,
   "all commercial": 10},
 ...}

The installed costs can be specified with detail beyond what is shown using the additional optional child field types, as illustrated for the energy_efficiency field. The order of the hierarchy is: bldg_type, structure_type. Further information about detailed structures for specifying the installed cost is in the Detailed input specification section.

cost_units

  • Parents: root

  • Children: (optional) matching installed_cost

  • Type: string, dict

Cost units correspond to the installed cost given for the ECM. The cost units should match the required units based the type of technology described by the ECM.

{...
 "cost_units": "$/1000 lm",
 }

If there is only a single cost value, a single units value should be given; if the installed cost is specified by one or more of the optional keys and the various installed costs have different units, the cost units should be specified with the same dict structure as the costs. (Cost units are not a function of climate zone and do not have to be specified with a climate zone breakdown even if the costs vary by climate zone.)

{...
 "cost_units": {
   "all residential": "$/unit",
   "all commercial": "$/1000 lm"},
 ...}

installed_cost_source

This key is used to specify the source of the ECM’s installed cost values. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source(s) and the values in the ECM definition should be supplied in the notes field.

{...
 "installed_cost_source": {
   "notes": "Table 6.3, average of values reported in Total Installed Cost column for the Gas Storage water heater equipment type.",
   "source_data": [{
      "title": "Energy Savings Potential and RD&D Opportunities for Commercial Building Appliances (2015 Update)",
      "author": "Navigant Consulting; William Goetzler, Matt Guernsey, Kevin Foley, Jim Young, Greg Chung",
      "organization": "U.S. Department of Energy",
      "year": 2016,
      "pages": 80,
      "URL": "http://energy.gov/sites/prod/files/2016/06/f32/DOE-BTO%20Comml%20Appl%20Report%20-%20Full%20Report_0.pdf"}]},
 ...}

product_lifetime

  • Parents: root

  • Children: (optional) values from bldg_type

  • Type: int, dict

The product lifetime is the expected usable life of the technology described by the ECM in years. The lifetime value should be an integer greater than 0.

{...
 "product_lifetime": 3,
 ...}

The product lifetime can be specified by building type, if appropriate for the ECM. The building types are the keys in the lifetime dict and should match the types listed in the bldg_type field. Additional information regarding this specification method can be found in the Detailed input specification section.

{...
 "product_lifetime": {
   "single family home": 10,
   "small office": 7,
   "mercantile/service": 6},
 ...}

product_lifetime_units

  • Parents: root

  • Children: none

  • Type: string

The product lifetime units are years. This field is included largely to ensure that the correct units were used when specifying the product lifetime.

{...
 "product_lifetime_units": "years",
 ...}

product_lifetime_source

This key is used to specify the source of the ECM’s product lifetime values. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source and the values in the ECM definition should be supplied in the notes field.

{...
 "product_lifetime_source": {
   "notes": "Table C-2, Lamp Life column, average of A-Type, Track Lighting, and Downlights Incandescent Omni rows; converted to years assuming an average use of 8 hours/day.",
   "source_data": [{
      "title": "Energy Savings Forecast for Solid-State Lighting in General Illumination Applications",
      "author": "Navigant Consulting; Julie Penning, Kelsey Stober, Victor Taylor, Mary Yamada",
      "organization": "U.S. Department of Energy",
      "year": 2016,
      "pages": 65,
      "URL": "http://energy.gov/sites/prod/files/2016/09/f33/energysavingsforecast16_2.pdf"}]},
 ...}

tsv_features

This key specifies the time-sensitive (e.g., hourly or sub-annual) impacts of the technology being described by the ECM. One or more time sensitive ECM features may be described, including shed, shift, and/or shape. Each feature is indicated as a dict key as follows.

{...
 "tsv_features": {
   "shed": {...}},
 ...}

If an ECM has multiple time sensitive features, they may be specified as follows.

{...
 "tsv_features": {
   "shed": {...},
   ...,
   "shape": {...}},
 ...}

Optionally, a user may break out time sensitive features by region, building type, and/or end use by setting these variables as the first levels in the dict key hierarchy, followed by the time sensitive feature type key.

{...
 "tsv_features": {
   <region 1> : {
     <building type 1> : {
       <end use 1>: {
         <time sensitive feature>: {<feature details>}}}}, ...
   <region N> : {
     <building type N> : {
       <end use N>: {
         <time sensitive feature>: {<feature details>}}}}},
 ...}

Note that if a region, building type, and/or end use breakout is used, keys for all the ECM’s applicable regions, building types, and/or end uses must be included. For example, if the time sensitive features dict is broken out by end use, and the ECM applies to both heating and cooling, both the heating and cooling keys must be reflected in the time sensitive features dict.

tsv_source

This key is used to specify the source of the ECM’s time sensitive valuation data. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source(s) and the values in the ECM definition should be supplied in the notes field.

{...
 "tsv_source": {
   "notes": "Study provides estimate of commercial load curtailment magnitude.",
   "source_data": [{
      "title": "Characterization of demand response in the commercial, industrial, and residential sectors in the United States",
      "author": "Sila Kiliccote, Daniel Olsen, Michael D. Sohn, Mary Ann Piette",
      "organization": "Lawrence Berkeley National Laboratory",
      "year": 2015,
      "pages": 17,
      "URL": "https://onlinelibrary.wiley.com/doi/abs/10.1002/wene.176"}]},
 ...}

Optionally, a user may break out time sensitive source data by region, building type, and/or end use by setting these variables as the first levels in the dict key hierarchy, followed by the time sensitive feature type key.

{...
 "tsv_source": {
   <region 1> : {
       <building type 1> : {
         <end use 1>: {
           <time sensitive feature>: {
             "notes": <notes>,
             "source_data": [{
               "title": <title>,
               "author": <author>,
               "organization": <organization>,
               "year": <year>,
               "pages":[<start page>, <end page>],
               "URL": <URL>}]}}}}, ...
   <region N> : {
       <building type N> : {
         <end use N>: {
           <time sensitive feature>: {
             "notes": <notes>,
             "source_data": [{
               "title": <title>,
               "author": <author>,
               "organization": <organization>,
               "year": <year>,
               "pages":[<start page>, <end page>],
               "URL": <URL>}]}}}},
 ...}

Note that if a region, building type, and/or end use breakout is used, keys for all the ECM’s applicable regions, building types, and/or end uses must be included. For example, if the time sensitive features dict is broken out by end use, and the ECM applies to both heating and cooling, both the heating and cooling keys must be reflected in the time sensitive features dict.

measure_type

  • Parents: root

  • Children: none

  • Type: string

This field is used to specify whether the technology described by the ECM could be substituted for a component already installed in buildings, such as an electric cold-climate heat pump being substituted for an electric furnace and central AC system, or enhance the efficiency of an existing component, such as a window film applied to an existing window or an HVAC controls system that improves the efficiency of existing HVAC equipment. The measure type is then either "full service" or "add-on", respectively. Supplementary information and illustrative examples of the use of this field are available in the Add-on type ECMs section.

{...
 "measure_type": "full service",
 ...}

fuel_switch_to

  • Parents: root

  • Children: none

  • Type: string

If the ECM replaces a comparable baseline technology or technologies that are served by a different fuel type, this field should identify the fuel type that the ECM switches to. The switched to fuel type name should match exactly with one of the fuel types listed in the ECM Definition Reference. If the ECM fuel type matches that of the comparable baseline technology, this field can be given as null. Additional information regarding the use of this field is available in the Technology and/or fuel switching section.

{...
 "fuel_switch_to": "natural gas",
 ...}

tech_switch_to

  • Parents: root

  • Children: none

  • Type: string

If the ECM technology differs from that of the comparable baseline technology it replaces, this field should identify the technology that the ECM switches to. The switched to technology name should match one of those shown in the table in Table 1. If the ECM technology is a like-for-like replacement of the baseline technology, this field can be given as null. Additional information regarding the use of this field is available in the Technology and/or fuel switching section.

{...
 "tech_switch_to": "ASHP",
 ...}

market_scaling_fractions

The market scaling fraction is used to further reduce the energy use of the applicable baseline market [1] specified for an ECM whose technology corresponds to only a fraction of that market. The market scaling fraction value should be between 0 and 1, representing the desired fraction of the baseline market. If the ECM does not need a market scaling fraction, the field should be given the value null.

{...
 "market_scaling_fractions": 0.18,
 ...}

Market scaling fractions can be separately specified using the optional child fields if relevant to the technology described by the ECM, if the fields are part of the applicable baseline market, and if appropriate source information is provided.

{...
 "market_scaling_fractions": {
   "new": 1,
   "existing": 0.43},
 ...}

Further information regarding the use of market scaling fractions is in the Market scaling fractions section.

market_scaling_fractions_source

The market scaling fractions source identifies the sources that were used to determine the market scaling fraction, including the exact method for deriving the fraction. If the market_scaling_fractions field is null, the source should also be specified as null.

{...
 "market_scaling_fractions_source": {
   "title": "Energy Savings Forecast for Solid-State Lighting in General Illumination Applications",
   "author": "Navigant Consulting; Julie Penning, Kelsey Stober, Victor Taylor, Mary Yamada",
   "organization": "U.S. Department of Energy",
   "year": 2016,
   "pages": 23,
   "URL": "http://energy.gov/sites/prod/files/2016/09/f33/energysavingsforecast16_2.pdf"},
   "fraction_derivation": "In Figure 4.4, sum of 2015 data for LED - Connected Lighting, LED - Controls, and shed Lighting - Controls."},
 ...}

Multiple scaling fraction values can share the same source so long as the calculation procedure for all of the values is provided in the fraction_derivation field, however, no more than one source is allowed for each scaling fraction value. If scaling fractions correspond to different sources, the source information can be given in a nested dict with the same top level structure as the scaling fractions themselves. If the market scaling fraction is set to 1 for one of the keys in the nested structure, the source information can be given as a string explaining any assumptions.

{...
 "market_scaling_fractions_source": {
   "new": "Assumes that all new commercial buildings are constructed with BAS",
   "existing": {
      "title": "CBECS 2012 - Table B1. Summary table: total and means of floorspace, number of workers, and hours of operation, 2012",
      "author": "U.S. Energy Information Administration (EIA)",
      "organization": "U.S. Energy Information Administration (EIA)",
      "year": "2012",
      "URL": "http://www.eia.gov/consumption/commercial/data/2012/bc/cfm/b1.cfm",
      "fraction_derivation": "37051 ft^2 floor of commercial buildings with BAS / 87093 ft^2 floor total commercial buildings"}},
 ...}

retro_rate

  • Parents: root

  • Children: none

  • Type: float, none

This field assigns an ECM-specific retrofit rate to use in stock-and-flow calculations. The retrofit rate value should be specified as a fraction between 0 and 1. For example, 0.1 corresponds to 10% of the existing technology stock being retrofitted annually.

{...
 "retro_rate": 0.1,
 ...}

retro_rate_source

This field is used to specify the source of the ECM’s retrofit rate data. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source and the values in the ECM definition should be supplied in the notes field.

{...
 "retro_rate_source": {
   "notes": "Increased commercial building retrofit rate to represent the potential impacts of the DEEP database in accelerating energy savings from commercial retrofits.",
   "source_data": [{
      "title": "Accelerating the energy retrofit of commercial buildings using a database of energy efficiency performance",
      "author": "Sang Hoon Lee, Tianzhen Hong, Mary Ann Piette, Geof Sawaya, Yixing Chen, Sarah C. Taylor-Lange",
      "organization": "Lawrence Berkeley National Laboratory",
      "year": 2015,
      "pages": 10,
      "URL": "https://eta.lbl.gov/sites/all/files/publications/tianzhen_hong_-_accelerating_the_energy_retrofit_of_commercial_buildings_using_a_database_of_energy_efficiency_performance.pdf"}]},
 ...}

_description

  • Parents: root

  • Children: none

  • Type: string

A one to two sentence description of the ECM. If the ECM is prospective, i.e., describing a technology still being researched, the description should include URLs or other identifying information for additional references that contain further details about the technology.

{...
 "_description": "LED troffers for commercial modular dropped ceiling grids that are a replacement for the entire troffer luminaire for linear fluorescent bulbs, not a retrofit kit or linear LED bulbs that slot into existing troffers.",
 ...}

_notes

  • Parents: root

  • Children: none

  • Type: string

A text field that can be used for explanatory notes regarding the technologies that can be replaced by the ECM, any notable assumptions made in the specification of the ECM, or any other relevant information about the ECM that is not captured by any other field.

{...
 "_notes": "Energy efficiency is specified for the luminaire, not the base lamp.",
 ...}

_added_by

A dict containing basic information about the user that originally created the ECM.

{...
 "_added_by": {
   "name": "Maureen Baruch Kilda",
   "organization": "U.S. Department of Energy",
   "email": "maureen.b.kilda@hq.doe.gov",
   "timestamp": "2016-01-28 21:17:35 UTC"}
 ...}

_updated_by

A dict containing basic information that identifies the user that last updated the ECM, identical in structure to the dict in the _added_by field. null if the ECM has never been modified.

{...
 "_updated_by": ``null``
 ...}

shed

This field sheds (reduces) a certain percentage of baseline electricity demand (defined by the parameter relative energy change fraction) during certain days of the reference year (defined by the parameters start_day and stop_day) and hours of the day (defined by the parameters start_hour and stop_hour.)

{...
 "shed": {
   "relative energy change fraction": 0.1,
   "start_day": 152, "stop_day": 174,
   "start_hour": 12, "stop_hour": 20}
 ...}

shift

This field shifts baseline energy loads from one time of day to another by redistributing loads reduced during a certain hour range to earlier times of day. The start_day and stop_day and start_hour and stop_hour parameters are used to determine the day and hour ranges from which to shift the load reductions, respectively. The magnitude of the load reduction is defined by the relative energy change fraction parameter. The offset_hrs_earlier parameter is then used to determine which hour range to redistribute the load reductions to.

{...
 "shift": {
   "offset_hrs_earlier": 12,
   "relative energy change fraction": 0.1,
   "start_day": 152, "stop_day": 174,
   "start_hour": 12, "stop_hour": 20}
 ...}

shape

The final type of time sensitive ECM feature applies hourly savings fractions to baseline loads in accordance with a custom savings shape that represents either a typical day or all 8760 hours of the year.

In the first case, custom hourly savings for a typical day are defined in the custom_daily_savings parameter; the hourly savings are specified as a list with 24 elements, with each element representing the fraction of hourly baseline load that an ECM saves. These hourly savings are applied for each day of the year in the range defined by the start_day and stop_day parameters, as for the shed and shift features.

In the second case, the custom savings shape represents hourly load impacts for all 8760 hours in the reference year. Here, the measure definition links to a supporting CSV file via the custom_annual_savings parameter that is expected to be present in the ./ecm_definitions/energyplus_data/savings_shapes folder, with one CSV per measure JSON in ./ecm_definitions that uses this feature.

{...
 "shape": {
   "start_day": 152, "stop_day": 174,
   "custom_daily_savings": [
     0.5, 0.5, 0.5, 0.5, 0.5, 0.6, 1, 1.3, 1.4, 1.5, 1.6, 1.8,
     1.9, 2, 1, 0.5, 0.75, 0.75, 0.75, 0.75, 0.5, 0.5, 0.5, 0.5]}
 ...}

{...
 "shape": {
   "start_day": 152, "stop_day": 174,
   "custom_annual_savings": "sample_8760.csv"}
 ...}

start_hour

This field indicates the hour of the day (from 1 to 24) that application of a time sensitive ECM feature begins.

{...
 "start": 12
 ...}

stop_hour

This field indicates the hour of the day (from 1 to 24) that application of a time sensitive ECM feature ends.

{...
 "stop": 20
 ...}

start_day

This field indicates the day of the year (from 1 to 365) that application of a time sensitive ECM feature begins.

{...
 "start_day": 12
 ...}

The field may alternatively be specified in list format to yield two start day values, which are paired with two stop_day values to yield two distinct day ranges of time senstive feature application.

{...
 "start_day": [1, 335]
 ...}

stop_day

This field indicates the day of the year (from 1 to 365) that application of a time sensitive ECM feature ends.

{...
 "stop_day": 20
 ...}

The field may alternatively be specified in list format to yield two end day values, which are paired with two start_day values to yield two distinct day ranges of time senstive feature application.

{...
 "stop_day": [91, 365]
 ...}

relative energy change fraction

  • Parents: shed, shift

  • Children: None,

  • Type: float

This field indicates fraction of baseline hourly loads that a measure sheds and/or shifts to another time period.

{...
 "relative energy change fraction": 0.1
 ...}

offset_hrs_earlier

  • Parents: shift

  • Children: None,

  • Type: int

This field indicates the number of hours earlier to shift baseline load reductions.

{...
 "offset_hrs_earlier": 12
 ...}

custom_daily_savings

  • Parents: shape

  • Children: None,

  • Type: list

This field provides a list of 24 fractions that represent the percentage of baseline load saved in each hour of a typical day.

{...
 "custom_daily_savings": [
   0.5, 0.5, 0.5, 0.5, 0.5, 0.6, 1, 1.3, 1.4, 1.5, 1.6, 1.8,
   1.9, 2, 1, 0.5, 0.75, 0.75, 0.75, 0.75, 0.5, 0.5, 0.5, 0.5]
 ...}

custom_annual_savings

  • Parents: shape

  • Children: None,

  • Type: string

This field points to a CSV file containing measure savings fractions for all 8760 hours of the year.

{...
 "custom_annual_savings": "sample_8760.csv"
 ...}

notes

The notes field should include the exact location of the specific information used from the source(s) identified. The location information should include the table or figure number, and if the value is drawn from tabular data, the applicable row and column heading(s). The notes should also outline any calculations performed to convert from the values found in the source(s) to the value used in the ECM definition, including unit conversions and methods for combining multiple values (e.g., averaging, market share-weighted averaging). Any other assumptions regarding the derivation of the related value in the ECM definition should also be included.

{...
 "notes": "Value drawn from Table 1 for the Ventless or Vented Electric, Standard product type. For clothes drying, the expected units of EF (Energy Factor) are equivalent to lbs/kWh.",
 ...}

fraction_derivation

For the market scaling fractions, this field should provide a description of how the values were calculated. The description should have enough detail for another user to be able to easily repeat the calculations.

{...
 "fraction_derivation": "Sum of 2015 data for LED - Connected Lighting, LED - Controls, and shed Lighting - Controls.",
 ...}

source_data

A list that encloses one or more dicts, where each dict corresponds to a single source and includes all of the child fields listed.

{...
 "source_data": [{
   "title": "ENERGY STAR Program Requirements: Product Specification for Clothes Dryers",
   "author": null,
   "organization": "U.S. Environmental Protection Agency",
   "year": 2014,
   "pages": "2-3",
   "URL": "https://www.energystar.gov/sites/default/files/specs//ENERGY%20STAR%20Final%20Version%201%200%20Clothes%20Dryers%20Program%20Requirements.pdf"}],
...}

title

The title of the source document.

{...
 "title": "ENERGY STAR Program Requirements: Product Specification for Clothes Dryers",
 ...}

author

The names of the author(s) of the publication, if any are identified. If no authors are listed, null or an empty string are acceptable values for this field if no authors are identified by name in the source.

{...
 "author": null,
 ...}

organization

The journal publication, organization, or other entity that released the source article, report, specification, test result, or other reference.

{...
 "organization": "U.S. Environmental Protection Agency",
 ...}

year

The year that the source was published or last updated.

{...
 "year": 2014,
 ...}

pages

The page number(s) of the information in the source document, if applicable. If the source is not divided into pages, this entry can have the value null. If the relevant information can be found on a single page, the page number should be given as an integer. If the information is divided across several pages or a range of pages, the page numbers should be given as a string.

{...
 "pages": "24, 26-29, 37",
 ...}

URL

The URL where the source can be found on the internet. The URL should point directly to the original source file, if possible.

{...
 "URL": "https://www.energystar.gov/sites/default/files/specs//ENERGY%20STAR%20Final%20Version%201%200%20Clothes%20Dryers%20Program%20Requirements.pdf",
 ...}

name

The name of the author of the initial definition or latest changes to the ECM.

{...
 "name": "Maureen Adams",
 ...}

organization

The organization or employer with which the named author is affiliated.

{...
 "organization": "U.S. Department of Energy",
 ....}

email

The email address of the named author.

{...
 "email": "james.clipper@ee.doe.gov",
 ...}

timestamp

The date and time at which the relevant changes were completed. The entry should be formatted as YYYY-MM-DD HH:MM:SS, with the time reported in 24-hour Universal Coordinated Time (UTC) if possible.

{...
 "timestamp": "2014-03-27 14:36:18 UTC",
 ...}

Footnotes