Custom Building Methodology

The custom building methodology simulates a building that the customer describes. It does not read a meter. The result is modeled energy, hour by hour.

What the methodology states

The methodology starts from one NREL building model. It applies the customer’s edits to that model. Then it runs the model in EnergyPlus under the weather at the building’s own location.

The result is the energy that the edited model uses. It is not a measurement of the building. It shows what the building uses if it matches the edited model. A metered methodology is stronger evidence for what the building did.

How the starting model is chosen

The starting model is a building from NREL’s ResStock (residential building types) or ComStock (commercial building types). The customer can name the building with the NREL Building ID field.

If the customer does not name a building, a selector picks the NREL building that best matches the type, floor area, number of stories, year built, and heating fuel. A building in the same county ranks first. A building in the same state ranks second.

If the customer leaves the heating fuel blank, the model heats with gas when the asset has a gas meter. Otherwise it heats with the most common fuel for the building type in the county.

Building fields

Field	Notes
Commenced Operation Date	Required. On or after January 15, 2018 (weather limit).
Building Type	Required. An NREL building type.
Area (sqft)	Greater than 0.
Number of Stories	1 to 100.
Year Building was Built	1800 or later.
Fuel Used for Space Heating	For example, gas or electricity.
NREL Building ID	Names the starting model. Advanced.

Named settings

A named setting uses the units that the customer knows. A blank (null) setting keeps the NREL value. Each setting has a range, and a value outside the range is refused.

Setting name	Title	Unit	Range	Applies to
heating_setpoint_offset_f	Heating Setpoint Offset (°F)	°F	-10 to 10	Both
cooling_setpoint_offset_f	Cooling Setpoint Offset (°F)	°F	-10 to 10	Both
baseline_furnace_afue	Furnace AFUE	fraction	0.5 to 1.0	Residential
legacy_heating_efficiency	Heating Efficiency	fraction	0.5 to 1.0	Commercial
legacy_cooling_cop	Cooling COP	none	1.5 to 6.0	Commercial
legacy_lighting_power_density_w_per_sqft	Lighting Power Density (W/ft²)	W/ft²	0.05 to 3.0	Commercial
legacy_roof_r_value	Roof Insulation R-Value	ft²·°F·h/Btu	1 to 80	Commercial
legacy_wall_r_value	Wall Insulation R-Value	ft²·°F·h/Btu	1 to 40	Commercial
legacy_window_u_factor	Window U-Factor (Btu/h·ft²·°F)	Btu/h·ft²·°F	0.1 to 1.2	Commercial
legacy_window_shgc	Window Solar Heat Gain Coefficient	none	0.1 to 0.9	Commercial

A setting for the wrong stock is refused. A residential building type cannot take a commercial setting, and a commercial building type cannot take baseline_furnace_afue.

Building-type settings

Some building types offer settings that the others do not. A building-type setting is a count of one kitchen appliance: fryer_count, griddle_count, oven_count, range_count, broiler_count and steamer_count. Each is a number from 0 to 50. A building type offers a count only when NREL’s models of that type have the appliance. A restaurant offers all six. A small office offers none, and a request for one is refused.

A count scales the model’s own appliance loads, so the fuel mix stays as NREL has it. A starting model can have a gas fryer, an electric fryer, or both. A new count of 3 for a model with 1.5 fryers doubles each load. A count of 0 turns the appliance off. A count cannot add an appliance that the starting model lacks. The measurement stops and the log names the setting.

Every residential building type (single-family detached and attached, both multifamily types, and mobile home) offers these settings:

Setting name	Title	Unit	Range	What it changes
occupant_count	Number of Occupants	people	0 to 12	Occupant heat gains only. Appliance and hot-water use come from the schedule file.
<end use>_multiplier	for example Refrigerator Multiplier	×	0 to 5	The size of that end use, so 2 doubles its energy. 1 keeps NREL’s model.
water_heater_tank_gallons	Water Heater Tank Size	gal	10 to 120	The tank volume. The heater’s capacity stays as NREL has it.

The end uses are fridge, freezer, cooking_range, clothes_dryer, clothes_washer, dishwasher, plug_load, tv and interior_lighting. A gas or propane range and dryer scale together with their electric parts. A vacant unit has no occupants, so occupant_count reads null for it. A home without an end use reads null for that multiplier.

Each offer in available_model_settings from get-custom-building-model gives the key, title, unit, range, and the starting model’s own value (current_value). A current_value of null means the model has no such appliance, so do not propose that count. stored_value is the value saved on the methodology.

Building-type settings apply after the named settings and before the field edits. A field edit that sets the same field wins.

Field edits

A field edit changes one field of the EnergyPlus model. Use a field edit when no named setting covers the change. Each edit has four parts:

• object_type: the EnergyPlus object type, for example Lights or Material.
• object_name: the name of one object, or * for every object of the type.
• field: the field name as the model file labels it, for example Thickness.
• value: the new value, as a number or a string.

The rules for field edits are:

• The model uses SI units. Write each value in the unit that the field shows, for example W/m² or °C.
• Matching of the type, name, and field ignores case.
• An object type that has no name field, such as Version, matches only *.
• A number is written with four decimals.
• A request holds at most 200 edits.
• A field edit sets an absolute value. It cannot scale a value by a percentage. To scale values, read each current value and propose the new value.
• Edits apply in order, after the named settings. A later edit wins over an earlier edit. An edit wins over a named setting that sets the same field.
• If an edit finds no object type, object, or field, the measurement stops and the log names the edit. The measurement never skips an edit.

Read the model with get-custom-building-model

The get-custom-building-model tool reads the model. It never changes anything. Pass asset_id. Pass ordinal only if the asset has more than one custom building methodology.

Call it with no object_type first. The response gives the starting model (stock, release, building ID, and whether the customer named it or the selector matched it), the stored named settings, the building-type settings that the asset’s building type offers, the stored field edits, and the count of each object type.

Call it again with an object_type, for example Lights, to see the objects of that type. Each object lists its fields with the value and the SI unit. Use name_contains to find an object by name. Use limit (1 to 100, default 25) to set how many objects return. A call with an object_type always returns total_matched. The truncated field is true when more objects match than return. An object lists at most 200 fields. If fields_truncated is true, the object has more fields than the response shows.

The first call for a ComStock building can take minutes, because the model must translate. Later calls are fast.

Propose changes with propose_custom_building_edits

The propose_custom_building_edits tool proposes a change. It does not save the change. The user confirms the proposal on a card, and the confirmation saves it.

Always read the model first. Use the exact object type, object name, and field name that get-custom-building-model returns. Do not guess a field name.

The tool takes these inputs:

• asset_id and summary are required. The summary is one sentence that names the change for the confirm card.
• ordinal is required when the asset has more than one custom building methodology. Otherwise it is null.
• settings is an object of named settings. Each value is a number or null. A setting that is not in the object keeps its stored value. A null value clears the setting.
• model_settings is an object of building-type settings, by key. Each value is a number or null, and the rules for settings apply. A key the asset’s building type does not offer is refused.
• field_edits is a list of edits. The tool adds them after the stored edits.
• replace_field_edits set to true drops the stored edits and keeps only the edits in this request.

The server checks the merged result and returns a proposal_id. Put [[custom_building_edit_proposal:<proposal_id>]] on its own line in the final answer, where the confirm card belongs. Tell the user to review the proposal and click Confirm.

Aristotle cannot save the edits. Never tell the user that the edits are applied before the user confirms. Say that the proposal waits for the Confirm click. If the tool returns an error, tell the user the problem and propose again with corrected inputs.

Worked example: lower the lighting power density of a commercial asset

The user asks Aristotle to set the lighting power density of a commercial custom building to 0.8 W/ft². A named setting covers this change, so no field edit is necessary.

1. Call get-custom-building-model with the asset_id. The response shows the stored settings and edits.
2. Call propose_custom_building_edits with the setting below.

{
  "asset_id": 1234,
  "summary": "Set the lighting power density to 0.8 W/ft².",
  "settings": { "legacy_lighting_power_density_w_per_sqft": 0.8 }
}

3. Put the returned [[custom_building_edit_proposal:<proposal_id>]] on its own line in the final answer. Tell the user to click Confirm.

Worked example: set the number of fryers in a restaurant

The user says that a quick-service restaurant has two fryers. A building-type setting covers this change, so no field edit is necessary.

1. Call get-custom-building-model with the asset_id. In available_model_settings, fryer_count shows current_value 1. That is the count in NREL’s model.
2. Call propose_custom_building_edits with the setting below.

{
  "asset_id": 1234,
  "summary": "Set the number of fryers to 2.",
  "model_settings": { "fryer_count": 2 }
}

3. Put the returned [[custom_building_edit_proposal:<proposal_id>]] on its own line in the final answer. Tell the user to click Confirm.

If current_value is null for the appliance, the model has none and the count cannot be set. Tell the user, and do not propose it.

Worked example: change one field of one object

A field edit changes a field that no named setting covers. This example sets the thickness of one roof insulation layer to 0.15 m.

1. Call get-custom-building-model with no object_type. The response lists Material in the object counts.
2. Call it again with object_type set to Material and name_contains set to insulation. The response lists each matching object by name, with its Thickness field in m.
3. Choose one object name from the response. Call propose_custom_building_edits with that exact name.

{
  "asset_id": 1234,
  "summary": "Set the thickness of the roof insulation layer to 0.15 m.",
  "field_edits": [
    {
      "object_type": "Material",
      "object_name": "<name from the read response>",
      "field": "Thickness",
      "value": 0.15
    }
  ]
}

Use * as the object name only when every object of the type must hold the same absolute value.

Limits to tell the user

• The result is modeled. No meter on the asset feeds it.
• The result states electricity, gas, fuel oil, district hot water and district steam. A home that burns propane, or a building with district cooling, has that energy left out, and the measurement log warns with the amount in kWh.
• An edit can make the model less like the building. Edits that come from drawings or audit reports lower the error. Guesses add to it.
• If the starting model is much larger or smaller than the building, the log shows a floor-area scaling outside 0.5 to 2.0. Name an NREL building closer in size.