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
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, warm climates, cold climates
The bolded EMM regions are categorized as “warm climates;” the remainder are “cold climates.”

Fig. 11 Map of U.S. EIA Electricity Market Module (EMM) regions.
AIA climate zones
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, warm climates, cold climates
The bolded climate zones are categorized as “warm climates;” the remainder are “cold climates.”

Fig. 12 Map of American Institute of Architects (AIA) climate zones for the contiguous U.S., Alaska, and Hawaii.
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, warm climates, cold climates
The bolded states are categorized as “warm climates;” the remainder are “cold climates.”

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 (CFL) |
reflector (LED) |
linear fixture |
linear fluorescent (T-8) |
linear fluorescent (LED) |
|
exterior |
external (incandescent) |
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
Parents: root
Children: notes, source_data
Type: dict, none
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
Parents: root
Children: notes, source_data
Type: dict, none
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
Parents: root
Children: (optional) values of climate_zone, bldg_type, end_use, structure_type
Type: float, dict
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
Parents: root
Children: (optional) matching energy_efficiency
Type: string, dict
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
Parents: root
Children: notes, source_data
Type: dict
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
Parents: root
Children: (optional) values from bldg_type, structure_type
Type: int, dict
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
Parents: root
Children: notes, source_data
Type: dict
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
Parents: root
Children: notes, source_data
Type: dict
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
Parents: root
Children: shed, shift, shape, (optional) values of climate_zone, bldg_type, and end_use
Type: dict
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
Parents: root
Children: notes, source_data, (optional) climate_zone, bldg_type, end_use, shed, shift, shape
Type: dict
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
Parents: root
Children: (optional) values from climate_zone, bldg_type, end_use
Type: int, dict, none
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
Parents: root
Children: title, author, organization, year, pages, URL, fraction_derivation; none
Type: dict, string, none
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
Parents: root
Children: notes, source_data
Type: dict
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
Parents: root
Children: name, organization, email, timestamp
Type: dict
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
Parents: root
Children: name, organization, email, timestamp
Type: dict
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
Parents: tsv_features
Children: relative energy change fraction, start_hour, stop_hour, (optional) start_day, stop_day
Type: dict
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
Parents: tsv_features
Children: relative energy change fraction, offset_hrs_earlier, start_hour, stop_hour, (optional) start_day, stop_day
Type: dict
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
Parents: tsv_features
Children: custom_daily_savings, json-custom-save-ann, (optional) start_day, stop_day,
Type: dict
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
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
Parents: market_entry_year_source, market_exit_year_source, energy_efficiency_source, installed_cost_source, product_lifetime_source, tsv_source, retro_rate_source
Children: none
Type: string
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
Parents: market_scaling_fractions_source
Children: none
Type: string
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
Parents: market_entry_year_source, market_exit_year_source, energy_efficiency_source, installed_cost_source, product_lifetime_source, tsv_source, retro_rate_source
Type: list
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
Parents: source_data, market_scaling_fractions_source
Children: none
Type: string
The title of the source document.
{...
"title": "ENERGY STAR Program Requirements: Product Specification for Clothes Dryers",
...}
organization
Parents: source_data, market_scaling_fractions_source
Children: none
Type: string
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
Parents: source_data, market_scaling_fractions_source
Children: none
Type: int
The year that the source was published or last updated.
{...
"year": 2014,
...}
pages
Parents: source_data, market_scaling_fractions_source
Children: none
Type: int, string, none
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
Parents: source_data, market_scaling_fractions_source
Children: none
Type: string
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",
...}
email
Parents: _updated_by, _added_by,
Children: none
Type: string
The email address of the named author.
{...
"email": "james.clipper@ee.doe.gov",
...}
timestamp
Parents: _updated_by, _added_by,
Children: none
Type: string
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