A general purpose enduse object is provided that incorporate a simple translation of a schedule to a loadshape to an enduse load. The enduse is linked to a circuit (which may be either line-to-line or line-to-neutral).

The residential_enduse class is defined as
```
```

class residential_enduse {
loadshape shape;
complex demand[kVA]; // the peak power consumption since the last meter reading
complex energy[kVAh]; // the total energy consumed since the last meter reading
complex total_power[kVA]; // the total power consumption of the load
double heatgain[Btu/h]; // the heat transferred from the enduse to the parent
double heatgain_fraction; // the fraction of the heat that goes to the parent
double current_fraction; // the fraction of total power that is constant current
double impedance_fraction; // the fraction of total power that is constant impedance
double power_fraction; // the fraction of the total power that is constant power
double power_factor; // the power factor of the load
complex constant_power[kVA]; // the constant power portion of the total load
complex constant_current[kVA]; // the constant current portion of the total load
complex constant_admittance[kVA]; // the constant admittance portion of the total load
double voltage_factor[pu]; // the voltage change factor
set {IS220=1} configuration; // the load configuration options
complex total[kVA]; // (DEPRECATED) the constant power portion of the total load
complex power[kVA]; // (DEPRECATED) the constant power portion of the total load
complex current[kVA]; // (DEPRECATED) the constant current portion of the total load
complex admittance[kVA]; // (DEPRECATED) the constant admittance portion of the total load
}

```
The various end use appliances within the residential module have a common
```

`enduse`

member. The four component values of this structure are published consistently by the house as the enduse load name (e.g., *lights*, *plugs*) The individual properties should be used for internal reference for a given appliance and aggregated to the "enduse_load" property, which may be used for load calculations by the house or by other objects.

The central importance of the enduse structure is that these four principle properties (power, demand, energy, and heatgain) must be updated by the object using a call to *gl_sync_enduse* so that when the enduse is attached to a house circuit panel the load accumulate correctly. If the properties are not published and updated, the house will halt the simulator.

** Implicit enduses **

A number of enduses can be implicitly defined by listing them in the residential module's global parameter *implicit_enduses*. If the parameter is not specified in the module directive, all implicit enduses are activated as shown in Table 1. Implicit enduses that may be specified are:
```
```

module residential {
implicit_enduses LIGHTS|CLOTHESWASHER|WATERHEATER|REFRIGERATOR|DRYER|FREEZER|DISHWASHER;
}

```
```

but others are expected any time, so please consult the *--modhelp residential* output for what is currently supported.

End use | Type | Schedule | Parameters |
---|---|---|---|

Lights | analog | residential-lights-default | power: 760 W |

Plugs | analog | residential-plugs-default | power: 360 W |

Clotheswasher | pulsed | residential-clotheswasher-default | energy: 750 Wh count: 0.25 power: 1 kW stdev: 150 W |

Waterheater | frequency modulated | residential-waterheater-default | energy: 1 kWh count: 1 power: 5 kW stdev: 500 W |

Refrigerator | frequency modulated | residential-refrigerator-default | energy: 1 kWh count: 25 power: 750 W stdev: 100 W |

Dryer | pulsed | residential-dryer-default | energy: 2.5 kWh count: 0.25 power: 5 kW tdev: 0.5 kW |

Freezer | frequency modulated | residential-freezer-default | energy: 750 Wh count: 25 power: 500 W stdev: 50 W |

Dishwasher | pulsed | residential-dishwasher-default | energy: 1.0 kWh power: 1.0 kW count: 1.0 stdev: 150 W |

Range | pulsed | residential-range-default | energy: 1.0 kWh power: 500 W count: 1.0 stdev: 95 W |

Microwave | pulsed | residential-microwave-default | energy: 1.0 kWh power: 200 W count: 1.0 stdev: 40 W |

** Using the House **

The house object is a dual purpose class. It first operates to aggregate and contain the effects of the various appliance loads, but also contains an appliance, the HVAC system, which it uses to control the thermal effects of the solar input and the electrical load heat of the building.

**Default House**

PLEASE NOTE: This section on the default house parameters will be deprecated or updated in the near future. Please go to http://sourceforge.net/apps/mediawiki/gridlab-d/index.php?title=Residential_module_user%27s_guide for a further, more complete description of the house model. All other information on this page should be up-to-date.

**House Properties**

Property Name | Type | Unit | Default Value | Description |
---|---|---|---|---|

floor_area | double | sq ft | normal distribution, m = 2500, r = 300) | The area of the house's ground floor. |

ceiling_height[ft] | double | ft | 8.0 | The height of the interior ceiling. Used to calculate air volume and exterior surface area. |

aspect_ratio | - | - | 1.0 | The ratio of the floor width to the floor length ~ a measure of how rectangular the house is. |

gross_wall_area | double | sq ft | 8 * ceiling height * (aspect_ratio + 1.0) * sqrt(floor_area / aspect_ratio) | Exterior wall surface area. |

envelope_UA | double | BTU/degF | - | Product of the house insulation quality (BTU / degF*ft^2) and the wall area (ft^2) |

window_wall_ratio | double | - | 15% | Ratio of the exterior wall area occupied by windows. |

glazing_shgc | double | - | 0.65 | "glazing SHGC" |

airchange_per_hour | double | ft^3 / hour | 4.0 - 6.0 | Rate at which air passes into or out of the house, through open windows, doors, leaky seals, anything. |

internal_gain | double | BTU / hour | - | Read-only. Internal gains for the house, based on occupants and appliances. |

solar_gain | double | BTU / hour | - | Read-only. Internal gains from solar input. |

heat_cool_gain | double | BTU / hour | - | Read-only. Internal gains from the HVAC system. |

thermostat_deadband | double | degF | 2.0 | 'Slack' for the thermostat setpoints, the temperature to heat or cool the house when the HVAC system activates. |

heating_setpoint | double | degF | 68.0 - 72.0 | Set temperature for the HVAC heater to start. |

cooling_setpoint | double | degF | 76.0 - 80.0 | Set temperature for the HVAC air conditioner to start. |

design_heating_capacity | double | BTU / hour | 18.0 - 24.0 | Average heating capacity per square foot of a house. |

design_cooling_capacity | double | BTU / hour | 18.0 - 24.0 | Average cooling capacity per square foot of a house. |

heating_COP | double | - | 3.0 | ... |

cooling_COP | double | - | 3.0 | ... |

COP_coeff | double | - | 0.9 - 1.1 | Equipment performance scalar, providing basic variation |

air_temperature | double | degF | 72.0 - 76.0 | Temperature of the air within the house |

outside_temp | double | degF | 74.0 | Temperature of the air outside the house |

mass_temperature | double | degF | 72.0 - 76.0 | Temperature of the solid and liquid objects within the house |

mass_heat_coeff | double | BTU / (hr * degF) | [0.5 - 1.0] * floor_area | The UA of the solid objects within the house |

heat_mode | enumeration | ELECTRIC, GASHEAT | ELECTRIC | The heating mode of the HVAC system |

hc_mode | enumeration | OFF, HEAT, COOL | OFF | Read-only. The current mode of the HVAC thermostat. |

total_load | complex | kW | - | Read-only. The total complex power flowing through the circuit panel |

enduse_load | complex | kW | - | Read-only. The total complex power load from the HVAC system. |

power | complex | kW | - | Read-only. The constant power part of the enduse_load. |

current | complex | A | - | Read-only. The constant current part of the enduse_load. |

admittance | complex | 1/Ohm | - | Read-only. The constant resistance part of the enduse_load. |

** Using the Refrigerator**

The Refrigerator copies the behaviors and the properties from the Freezer

**Default Refrigerator**

**Refrigerator Properties**

** Using the Freezer **

The freezer is modeled by determining the thermal capacity of the hypothetical contents of the freezer and estimating the thermal gains of the freezer cavity through its insulation. Heat gain through intermittent door opening is not factored in at this point.

From a simulation view, the freezer gradually absorbs heat from the house, and will activate its cooling system motor when the temperature exceeds a certain point.

**Default Freezer**

A default freezer will be defined with
```
```

object freezer {
}

```
will be initialized with the values of
```

```
```

object freezer {
size random.uniform(20,40);
thermostat_deadband random.uniform(2,3);
setpoint random.uniform(10,20);
UA 6.5;
power_factor 0.95;
rated_capacity (size * 34.0);
}

```
```

**Freezer Properties**

Property Name | Type | Unit | Default Value | Description |
---|---|---|---|---|

size | double | cu ft | 20 - 40 cu ft | Storage volume of the freezer |

rated_capacity | double | BTU / hr | 10 BTU/h per cu ft | Cooling capacity of the freezer under optimum conditions. |

power_factor | double | ratio | 0.95 | ... |

temperature | double | degF | 10.0 - setpoint | Read-only. Air temperature inside the freezer. |

setpoint | double | degF | 10.0 - 20.0 | The temperature the thermostat is set at to stay colder than |

deadband | double | degF | 2.0 - 3.0 | The 'slack' in the thermostat, and the temperature to cool the freezer by when the thermostat starts the cooling cycle. |

next_time | timestamp | sec | - | The next time that the internal state of the freezer will change due to thermal conditions. |

output | double | ??? | - | Read-only. Heat rate from the cooling system. |

UA | double | BTU*hr/degF | 6.5 | The relative heat loss of the freezer across the surface of its housing. Smaller values indicate better insulation. |

state | enumeration | OFF, ON | OFF | Read-only. Current state of the freezer cooling motor. |

enduse_load | complex | kW | - | Read-only. Current power consumption by the freezer. |

constant_power | complex | kW | - | Read-only. Constant power part of the current power draw. |

constant_current | complex | A | - | Read-only. Constant current part of the current power draw. |

constant_admittance | complex | 1/Ohm | - | Read-only. Constant resistance part of the current power draw. |

internal_gains | double | kW | - | Read-only. The heat created and released into the air by this appliance. |

energy_meter | double | kWh | - | The energy consumed during the running life of the appliance. |

** Using the Waterheater **

The waterheater is modeled as either a one-node or a two-node body of heat with thermal resistance between the interior and the exterior of the model.

**Default Waterheater**

An empty waterheater object, along the lines of
```
```

object waterheater { }

```
will be constructed into a semi-consistant state. The "default waterheater" ends up being similar to
```

```
```

object waterheater {
tank_volume 50.0 gal;
tank_diameter 1.5 ft;
inlet_water_temperature 60.0 degF;
location GARAGE;
heat_mode ELECTRIC;
tank_setpoint random.normal(130,10); // bound [100, 160]
thermostat_deadband (1 + random.normal(2,1)); // bound [1, 10]
tank_UA random.normal(2.0, 0.2); // bound (1, inf)
heating_element_capacity 4500 W;
}

```
Any properties that are not set explicitly will carry these default values.
```

**Waterheater Properties**

Property Name | Type | Unit | Description |
---|---|---|---|

tank_volume | double | gallons | The water volume of the water tank. |

tank_UA | double | BTU/hour | The product of the U-value of the tank's insulation and the surface area of the tank, assuming R values of about 13. |

tank_diameter | double | feet | The diameter of the water tank, influences heat loss calculations. |

water_demand | double | gallons/minute | Hot water consumption. Constant unless controlled by a Player object. |

heating_element_capacity | double | Watts | The rate at which the waterheater heating element will dump thermal energy into the water tank. |

inlet_water_temperature | double | degF | The temperature of the cold water entering the bottom of the waterheater to replace any hot water drawn out the top of the tank. |

heat_mode | enumeration | "ELECTRIC" or "GASHEAT". Determines the method that heat is added to the water tank. | |

location | enumeration | "INSIDE" or "GARAGE". Placement determines if thermal losses from the water heater wind up heating up the house, and if the outside temperature influences the effective temperature for heat loss. | |

tank_setpoint | double | degF | The target temperature at which the heating elements will click on and off in the waterheater. |

thermostat_deadband | double | degF | The number of degrees to heat the water when needed. Influences when the water heating element will turn on and turn off. |

meter | double | kilowatt-hours | The total power consumed by the water heater during the simulation. |

temperature | double | degF | The temperature of the hot water in the tank. |

height | double | feet | The height of the hot water tank. |

enduse_load | complex | kilowatts | The current power draw of the water heater. Required by the house to attach the water heater to the circuit panel. |

constant_power | complex | kilowatts | The constant power draw of the water heater. No effect ~ modify the heating_element_capacity. |

constant_current | complex | amps | The constant current draw of the water heater. No effect. |

constant_admittance | complex | 1/Ohm | The constant admittance of power across the water heater. No effect. |

internal_gains | double | kilowatts | The heat loss for the current timestep from the water heater to the water tank's location. |

|- |}

EDITING IN PROGRESS (--Dchassin 05:55, 7 January 2009 (UTC))

*NOTE: This document needs to be returned to the building engineers to fix some important gaps, as noted below.*

# Single-Family House

Estimating end-use consumption that accurately reflects the magnitude, average hourly shape, and probability and variance of the load is critical for the GridWise simulation and analysis work. Although there are several existing end-use modeling tools, they are not suitable they require large amounts of detailed characteristics data as inputs to estimate heating/cooling/ventilation end-uses (EnergyPlus, HVACSim, and TRANSYS), while others are not suitable because they do not support sub-hourly time steps (DOE 2.1, BLAST, and ASEAM). In addition, such detailed simulation models require significant amount of CPU time to estimate end-uses and, therefore, cannot be scaled to meet the requirement of simulating 1,000 or more residences in real-time using today’s desktop computers.

The thermal loads in a residential and small commercial building can be estimated using simplified first principles models. In this approach, the cooling and heating loads are modeled as function of few lumped parameters (effective envelop conductance, effective thermal mass and effective solar apertures, ventilation/infiltration rates, and equipment efficiencies), weather, internal gains from equipment and occupants, and thermostat set points. Although this approach is not as detailed and accurate as the detailed simulation models, it does overcome some of the limitation and provides reasonably accurate results.

## House Parameters

A house include a circuit panel and one or more loads that consume electricity. The required house parameters are defined in the house class.

### Internal Gains

Residential models must include internal gains from one of two sources. The gains may be specified using a load shape, which can be constructed in a `.shape`

file and attached to the house using a `shaper`

object from the `tape`

module. If you do this, be sure to also apply the corresponding power draw to the circuit on which the load would be attached.

If a more detailed model of an internal gain or load is needed, you may use any of the following objects for each house

- clotheswasher class
- dishwasher class
- dryer class
- dishwasher class
- microwave class
- occupantload class
- plugload class
- range class
- refrigerator
- waterheater

## Load Calculation Methodology

### House A (ASHRAE CLTD Method)

In this section, we describe the residential and small commercial building thermal load calculation, the modeling approach, major assumption and model testing and validation.

The major heat gains and losses that contribute to the building cooling or heating load consist of the following:

- Conduction through exterior walls, roof, and glass
- Heat gain/loss from infiltration of outside air through opening
- Solar radiation through glass
- Internal gains from lighting, people, equipment

Items 1, 2, and 3 are considered driven by the external source, while item 4 is consider internally generated. The thermal load can be either sensible or latent. Sensible load results in increase/decrease in the air temperature; latent load results in increase/decrease of water vapor, which increases/decreases the humidity. Items 1 and 3 are solely sensible, items 2 can be both sensible and latent, internal gains from lights are sensible and internal gains from people and equipment can be both sensible and latent.

In general, the amount of heat that must be removed (cooling load) or added (heating load) is not always equal to the amount of heat received or lost at a given time. The difference is a result of the heat storage and time lag effects [**citation?**]. Only a portion of the heat entering or leaving building actually heats/cools the room air immediately; the rest heats the building mass – the roof, walls, floors and building mass and air mass. The heat that is stored in the mass will result in heating/cooling load at a later time. So, the modeling approach will have to account for the storage effect.

To account for the storage effects when estimating the conduction gains from the exterior walls, roofs, and glass cooling load temperature difference method (CLTD) can be used:

where

- [math]Q[/math] is the cooling load for roof, wall or glass (Btu/hr)
- [math]U[/math] is the overall heat transfer coefficient for roof, wall, or glass (Btu/hr.ft
^{2}.^{o}F) - [math]A[/math] is the area of roof, wall or glass (ft
^{2}) - [math]CLTD_c[/math] is the corrected cooling load temperature difference (
^{o}F)

The CLTD is not the actual temperature difference between the outdoor and indoor air. It is modified value that accounts of storage effects (Pita 2002). The CLTD values for selected roofs and wall constructions are published in the literature (Pita 2002, ASHRAE 2001).

The published CTLD values are based on following conditions:

- Indoor temperature of 78
^{o}F. - Outdoor average temperature on the design day is 85
^{o}F. - Date July 21
^{st}. - Location in 40
^{o}N.

Since the actual conditions differ from any of the above, the CLTD must be corrected:

where

- [math]CLTD_c[/math] is the corrected value of
*CLTD*in^{o}F - [math]CLTD[/math] is the temperature difference from tables
- [math]LM[/math] is the correction for latitude and month from tables
- [math]T_{air}[/math] is the room temperature in
^{o}F - [math]T_{out}[/math] is the average outside temperature on a design day in
^{o}F

### House E (ETP method)

Thermal loads are implemented using the ETP model, which determines the heat flow between an inner and outer air mass and one solid mass embedded within the inner air mass.

The basic etp parameters are

- [math]Ua[/math]: the conductance between the inner and outer air mass
- [math]Ca[/math]: the heat capacity of the internal air mass
- [math]Cm[/math]: the heat capacity of the internal solid mass
- [math]Um[/math]: the conductance between the inner air mass and the inner solid mass
- [math]To[/math]: the outer air temperature
- [math]Ti[/math]: the inner air temperature
- [math]Tm[/math]: the inner mass temperature
- [math]Qa[/math]: the heat flux to the interior air mass
- [math]Qm[/math]: the heat flux to the interior solid mass (this is not supported yet)

The solution to the ETP model is based on the two ordinary differential equations (ODEs)

The general first-order ODEs are found by inspection:

where the constants [math]c_1[/math] through [math]c_6[/math] are

- [math]c_1 = -\frac{U_a + U_m}{C_a}[/math]
- [math]c_2 = \frac{U_m}{C_a}[/math]
- [math]c_3 = \frac{Q_a + U_a T_0}{C_a}[/math]
- [math]c_4 = \frac{U_m}{C_m}[/math]
- [math]c_5 = -\frac{U_m}{C_m}[/math]
- [math]c_6 = \frac{Q_m}{C_m}[/math]

The general form of the second-order ODE is given by

where

- [math]p_1 = \frac{1}{c_2}[/math]
- [math]p_2 = -\frac{c_1+c_5}{c_2}[/math]
- [math]p_3 = \frac{c_1 c_5}{c_2}-c_4[/math]
- [math]p_4 = \frac{c_3 c_5}{c_2}-c_6[/math]

where

- [math]r_1[/math] and [math]r_2[/math] are the roots of [math]p_1 r^2 + p_2 r + p_3 = 0[/math],
- [math]k_1 = \frac{r_2 T_{i,0} + r_2 p_4 / p_3 - \dot T_{i,0}}{r_2-r_1}[/math],
- [math]k_2 = \frac{T_{i,0} -r_1 k_1}{r_2}[/math]
- [math]t[/math] is the elapsed time,
- [math]T_{i,0}[/math] is the initial value of [math]T_i[/math], and
- [math]\dot T_{i,0} = c_1 T_{i,0} + c_2 T_{m,0} + (c_1 + c_2) T_0 + c_7[/math]

with

- [math]c_7 = \frac{Q_a}{C_a}[/math], and
- [math]T_{m,t} = k_1 \frac{r_1-c_1}{c_2} + k_2 \frac{r_2-c_1}{c_2} - \frac{p_4}{p_3} + \frac{c_6}{c_2} [/math]

## Modeling Assumptions

The house model assumes that only envelope characteristics, solar gain through windows and internal gain contribute to the HVAC load. Only air conditioners and heat pumps are modeled in the current implementation.

## Modeling Approach

The model approach that is used to estimate thermal loads is called an equivalent thermal parameter (ETP) modeling approach. Because the ETP approach has been proven to provide reasonably model the residential (and small commercial building) loads and energy consumption and also because it is based on first principles, this modeling approach has been chosen for the current work (Sonderegger 1978; Subbarao 1981; Wilson et al. 1985; Pratt and Taylor 1994). The electric circuit analog of an ETP model used to simulate heating and cooling loads in a typical residence is shown in Figure 3. The heat transfer properties are represented by equivalent electrical components with associated parameters for modeling the thermostatically controlled heating, ventilation, and air-conditioning (HVAC) system.

where,

- [math]C_{air}[/math] – air heat capacity (Btu/
^{o}F or J/^{o}C) *C*– mass (of the building and its content) heat capacity (Btu/_{mass}^{o}F or J/^{o}C)*UA*– the gain/heat loss coefficient (Btu/_{wall}^{o}F.h or W/^{o}C) to the ambient*UA*– the gain/heat loss coefficient (Btu/_{mass}^{o}F.h or W/^{o}C) between air and mass*T*– CLTD_{o}_{c}+ T_{air}(^{o}F or^{o}C)*T*– ambient temperature (_{ambient}^{o}F or^{o}C)*T*– air temperature inside the house (_{air}^{o}F or^{o}C)*T*– mass temperature inside the house (_{mass}^{o}F or^{o}C)*Q*– heat rate for HVAC (Btu/hr or W)_{HVAC}*Q*– heat rate from other appliance, plug loads, lights and people in the residence (Btu/h or W)_{internal}*Q*– heat gain from solar (Btu/h or W)_{solar}

A state space description of the ETP model is:

where (**there's something important missing here: A, B, C, D are not described**)

*R1*= 1/*UA*_{insul}*R2*= 1/*UA*_{mass}*Q*=*Q*+_{HVAC}*Q*+_{solar}*Q*_{internal}

Because there is wide diversity in the thermal parameters (UA, mass, efficiency of equipment, and over sizing factor) used to compute the load across homes, ranges can be provided for these parameters. Because of regional difference in construction practices and wide variation even within a region, a range of values can be assigned for critical parameters based on metering studies (Pratt et al. 1990). While estimating energy consumption of individual homes, the thermal parameters are randomly (from the established range using known distribution, for example, uniform) assigned to each home.

The internal gains in the home are computed external to the house object and are assumed to be inputs to the ETP model. These gains represent heat from other appliances (such as range, microwave), plug loads, lights, and people.

Solving the ETP model (simultaneously for Tair and Tmass), we can obtain the cooling/heating load of an individual home as a function of time. The energy consumption to meet the comfort needs in the home can then be computed by converting the thermal loads by using typical manufacturer-provided air conditioner part load performance data. Using the same simulation model, the energy consumption of a population of homes can also be computed. While simulating a population of homes, the energy consumption for each home is computed simultaneously at each time step. Therefore, we get an accurate representation of distribution feeder load when electric loads are aggregated.

A single ETP model with different thermal parameters can be used to represent all homes in the population for simplicity, or if there is a need, multiple ETP models with different thermal parameters can be used. Therefore, in addition to changing input parameters while simulating a population of homes, the ETP model can also be changed to accurately represent a given building stock. This ensures that it accurately reproduces the effects of load diversity.

## Limitation and Future Improvements

The approach described in the previous section only accounts for sensible loads. This does not lead to a significant error in heating load calculation (because most heating load is sensible); it does lead to some error in the estimation of the cooling load.

# End-uses

Generic enduses can be implemented using the **residential_enduse** object. This object requires a schedule and a loadshape definition (see Built in schedules and loadshapes). All other end-uses are (or will soon be) inheriting the properties and methods of the **residential_enduse** object.

## Enduse Structure

Objects that need to use the *enduse* structure can either inherit the needed properties from an object that already includes one, e.g. *residential_enduse*, or include one of their own.

When the *enduse* structure is inherited, it is strongly recommend that it's name be set during object creation. Usually the name given to the enduse is the same of the class implementing the enduse. The name can be assigned during *create* by using the command

load.name = "lights";

However, when an object implements multiple enduses, then each one is embedded and the name of the property should be given when the end-use is published, i.e.,

... PT_enduse, "lights", PADDR(enduse), ...

In addition, the corresponding shape must be defined and linked. When inheriting the enduse structure, this is already done. However, when defining the enduse structure in an object, it must done explicitly during *create* using the command

lights.shape = lighting_shape;

where *shape* is a property of type *loadshape* and can be published as

... PT_loadshape, "shape", PADDR(lighting_shape), ...

It is recommended that shape for embedded enduses be published with the enduse name as a prefix, e.g.,

... PT_loadshape, "lights.shape", PADDR(lighting_shape), ...

The following updates are made before any *presync* calls are made

- shape->schedule
- the schedule is updated to adjust the schedule value according to the target time of the sync event. The value
*next_t' is updated to give the time of the next expected schedule change.*

- shape
- the shape is updated to make the state of the loadshape correspond to the schedule value. The value t2 is updated to correspond to the expected time of the next change in demand.

- enduse
- this enduse energy is updated to include the power consumed up to the target time of the sync event.

In addition, during *sync* events, objects that use *enduse* properties must explicitly update their enduse structures using the *gl_enduse_sync*.

- Important
- omitting
*gl_enduse_sync*after*enduse*values are updated will result in erroneous output.

## Water Heater

Typical residential electric water heaters range in size from about 30 gallons up to 120 gallons or so, with most tanks falling in the range of about 40 to 80 gallons. Hot water is drawn from the top of the tank to service the home’s water loads, with cold make-up water injected near the bottom of the tank. When a hot water draw is in progress, the tank will tend to have a layer of cold water at the bottom.

Water is typically heated by two elements, one located near the bottom of the tank and one located higher in the tank, usually halfway to two-thirds of the way to the top. The lower element shoulders most of the heating load, with the upper element engaging only when the cold water layer has reached it. The two elements are controlled by independent thermostats, but only one is permitted to be on at a time, the upper element having priority. The design is intended to allow rapid (re)heating of the smaller volume of water above the top element so that full-temperature water is available as soon as possible after a depletion. Water heater elements range in capacity from about 1500 Watts to 6000 Watts, with 4500 Watts being common.

Thermostatic controls have a “dead band” associated with the setpoint, which prevents rapid cycling of power to the elements which would result if the turn-on temperature equaled the turn-off temperature. The dead band is typically a few degrees above and below the nominal setpoint.

Most heaters are shipped with both the upper and lower thermostats set to the same temperature (often 120 degrees-F), but they may be modified at installation or a later time. Some manufacturers recommend that if hotter water is desired, only the lower element be set to a higher temperature. This will maintain the entire tank at the higher temperature but allow for rapid recovery of the upper volume to the lower setting following a depletion. The net effect on energy use is negligible if the upper thermostat is set to a lower setting. However, some homeowners wrongly set the upper element to a higher temperature than the lower one, which results in somewhat different behavior. Because of thermal stratification, the upper volume will be maintained at a higher temperature than the lower volume, resulting in somewhat lower standby losses than when the entire tank is heated to the higher setting.

### Modeling Assumptions

The GridLAB-D approach to modeling electric water heaters is designed to be computationally fast yet reasonably accurate. It accommodates the common two-element design and the possibility for “inverted” thermostat settings, wherein the upper element maintains a higher temperature than the lower element.

To achieve the necessary computational speed, we make the following assumptions:

- Thermal stratification in the tank is not directly modeled. Depending on the situation, the water will be considered to be either of uniform temperature throughout the tank or “lumped” into two temperature regions (hot and cold layers).
- The injection of cold inlet water at the bottom of the tank results in either complete mixing with the hot water in the tank or no mixing at all, depending on the volumetric flow rate.

The water heater simulation uses two very different models depending on the state of the tank at any given moment. The two models are:

- One-Node Model – This is a simple, lumped-parameter electric analogue model that considers the entire tank to be a single “slug” of water at a uniform temperature. This model concerns the temperature of the water at any given time and/or the time required for the temperature to move between two specified points.
- Two-Node Model – This model, which applies when the heater is in a state of partial depletion, considers the heater to consist of two slugs of water, each at a uniform temperature. The upper “hot” node is near the heater’s setpoint temperature, while the lower “cold” node is near the inlet water temperature. This model concerns the location of the boundary between the hot and cold nodes, calculating the movement of that boundary as hot water is drawn from the tank and/or heat is added to the tank.

The water heater simulation keys on two primary “states” of the water heater:

- Tank State – The tank can be in one of three states:
**FULL**– All the water in the tank is at a uniform temperature near the heater’s setpoint. The One-Node model applies.**PARTIAL**– The tank is in a state of partial depletion, where some of the hot water has been (or is being) drawn out, leaving hot and cold layers of water in the tank. The Two-Node model applies.**EMPTY**– The tank has been completely depleted; all the water is at a uniform temperature near the water inlet temperature. The One-Node model applies.

- Load State – This refers to the current water load on the heater; that is, whether and how fast hot water is being drawn from the top of the tank. Formally, this load state applies only when the tank state is
**PARTIAL**, but is useful for the**FULL**and**EMPTY**tank states because it tells whether the tank will begin to move toward a**PARTIAL**state or stay in the current state. There are three possible load states:**DEPLETING**– Hot water is being drawn at a rate sufficient to move the boundary between the hot and cold zones upward. That is, hot water is being drawn out faster than the heating element can warm the incoming cold water, so the upper layer of hot water is getting smaller and the lower layer of cold water is getting larger.**RECOVERING**– Hot water is either not being drawn from the tank or begin drawn at a low enough level that the boundary between the hot and cold layers is moving downward. That is, the hot water is being drawn out at a rate low enough that the heating element can warm the replacement water faster than it is being introduced, causing the upper layer of hot water to get larger and the lower layer of cold water to get smaller.**STABLE**– Simplistically, this state implies that hot water is being drawn at a rate that matches the heating element’s ability to warm the incoming cold water. Actually, the hot water draw does not have to exactly match the warming rate for this state to apply. Because there are other heat flows acting on the water (e.g., jacket losses to surrounding air), in any given situation where the tank state is**PARTIAL**there is a range of hot water flow rates for which the tank will never reach either the**FULL**or the**EMPTY**state.

For example, if the tank begins near the **FULL** state and hot water is drawn from it at a rate slightly higher than the heating element can match, the hot/cold boundary will begin to move upward. However, as the boundary moves up, the size of the hot layer gets smaller, reducing the area of warm tank that is exposed to the surrounding air. The lowered area means lowered heat losses, which may tip the balance so that the heating element eventually can keep up with the hot water draw. Similarly, starting with an almost empty tank, the heating element’s capacity may exceed a small hot water draw and move the hot/cold boundary downward until jacket losses tip the balance. When the load state is **STABLE**, the calculated time to transition is infinite.

This **STABLE** state is illustrated in Figure 1. For an example water heater, the figure shows the time required to deplete an initially full tank (“time to transition”) at various hot water flow rates. Note that flow rates above roughly 0.45 gpm result in positive and finite times to transition. Flow rates below about 0.44 gpm are finite and negative, meaning the tank is not depleting at all, but is actually recovering (i.e., the heating element can more than keep up with the heat removed by the water draw). In between those two points—between the positive and negative spikes to infinity—the tank is in the **STABLE** state that will never reach either the **FULL** or the **EMPTY** state.

These two critical flow rates depend on many factors, including the tank size and shape, tank [math]UA[/math], heating element capacity, and the hot and cold layer temperatures. They are identified in the GridLAB-D water heater model by calculating the rate of change of the hot/cold boundary position [math]h[/math] with respect to time [math](dh/dt)[/math]. Note in the lower graphic of Figure 1 that the time to transition is positive when [math]dh/dt[/math], calculated at the **FULL** starting point [math]h0[/math], is negative (meaning the tank is depleting). Also note that the time to transition is negative (meaning the tank is really recovering and will remain **FULL**) when [math]dh/dt[/math], calculated at the target **EMPTY** state, is positive. The area between the two critical flow rates is identified by differing signs between [math]dh/dt[/math] calculated at **FULL** and [math]dh/dt[/math] calculated at **EMPTY**.

### Modeling Approach

Figure 2 shows a schematic representation of the water heater model in which Tavg is the average water temperature throughout the tank and Tamb is the ambient temperature. The thermal capacitance of the water Cw is a function of the tank volume:

The thermal conductance of the tank shell (or “jacket”) [math]UA[/math] is calculated from the known R-values of the sides and top of the tank divided into their corresponding areas.

#### One-Node Model

Considering Figure 2 and treating the water heater as a single node with thermal capacitance [math]C_w[/math], a conductance [math]UA[/math] to ambient conditions, with mass flow rate and heat input rate of [math]Q_{elec}[/math], a heat balance on the water node is as follows:

or,

The time required to change the tank’s temperature from an initial temperature [math]T_0[/math] to a new temperature [math]T_1[/math] is given by integrating that equation.

That is an integral of the form [math]dx/(a+bx)[/math], which has solution [math]\log(a+bx)/b[/math] . Therefore, the final model of the time required to raise (or lower) the tank’s temperature is

Where

- [math]a = \frac{\dot m C_p T_{inlet} + U A T_{amb} + Q_{elec}}{C_w}[/math]
- [math]b = \frac{ U A + \dot m C_p }{C_w}[/math]

The reverse problem of calculating the new temperature of the tank from a known initial temperature and time difference, [math]t1-t0[/math], follows directly:

#### Two-Node temperature model

**The two-node equations listed are incorrect, even though the repository code is correct. The latter should be parsed for the former.** --Mhauer 20:11, 5 February 2009 (UTC)

This model, which applies when the heater is in a state of partial depletion, considers the heater to consist of two slugs of water, each at a uniform temperature. The upper “hot” node is near the heater’s setpoint temperature, while the lower “cold” node is near the inlet water temperature. The time required to change the tank’s hot water column from an initial height of [math]h_0[/math] to a final height of [math]h_1[/math] is given by the following equation:

Where [math]dh/dt[/math] is the location of temperature boundary along the height of the water column. This is calculated as a function of mass flow rate and the temperature difference across between the upper and lower interface layers of the water column, as given by the following:

where

- [math]a = \frac{Q_{elec}+U A T_{amb}}{C_w T_lower} - \frac{\dot m C_p}{C_w}[/math]
- [math]b = \frac{U A}{C_w}[/math]

In the two-node model, during each synchronization cycle, the height the hot water column is calculated based on the mass flow rate, using the following equation:

### Simulation Sequence

Each time the water heater is sync’d, the simulation follows four steps:

- Calculate the energy consumed since the last iteration. The heater remembers whether it was heating and simply computes the consumption based on the time interval since the last sync.
- Update the tank temperature or the location of the hot/cold boundary, depending on whether the tank was previously
**FULL**,**PARTIAL**, or**EMPTY**. - Discern whether the tank needs heat. If the tank is in (or has reached) a
**FULL**state at the thermostat setting, the power will be turned off. Otherwise the element will be turned on. Note that, for the Single-Node model, the heater state remains unchanged from its previous state when the water temperature is between the heating cut-off and cut-on temperatures (the deadband around the thermostat setpoint). - Calculate and post the time to next transition. For example, if the heater is on, this is either the time for the water to reach the cut-off temperature or for the hot/cold boundary to reach the bottom of the tank, depending on the tank state.

### Complicating Factors

Several factors complicate the simulation. First, switching models between **FULL**, **PARTIAL**, and **EMPTY** states requires careful attention to not only what’s happening now, but what state(s) things were in previously. Second, identifying when the load state is **STABLE** can be difficult. Finally, each of the models (One-Node and Two-Node) has two incarnations—one to calculate time to transition, and a second “inverted” one to calculate temperature/boundary location after a given amount of time. Because of limitations on floating point precision, the inverted model may not show that the water heater has actually reached the state it was anticipating. For example, the time model may show that the tank will reach the cut-off temperature of, say, 135 degreees in 12 minutes. After 12 minutes have elapsed, the core updates the water heater as expected. The temperature model may calculate that the final temperature is in fact 134.95 degrees. In a worst case the simulation could go into an infinite loop and never actually change states.

## Lights

Residential lighting tends to be a mixture of several different types of lighting that is distributed somewhat randomly throughout the house and across the two circuit phases. Very little residential lighting is controlled by timers, although some outdoor lighting may be controlled by daylight sensors.

Depending on its location, the heat produced by a light fixture may go entirely into the conditioned space or may be partly dumped to an unconditioned space such as an attic or directly outdoors.

### Modeling Assumptions

- power_factor
- If the
*power_factor*is not set by the user, then the power factor depends on the lighting type:

- Incandescent: 1.00
- Fluorescent: 0.95
- CFL: 0.92
- SSL: 0.90
- HID: 0.97

- voltage_factor
- If the lights are not connected to a house circuit from which voltage can be determined, then the
*voltage_factor*is 1.0.

- shape.type
- Only
**analog**load shapes are supported. Any of three load shape scales are permitted

- Absolute (neither
*shape.power*nor*shape.energy*are specified) and the schedule value is used as is - Fixed energy (
*shape.energy*is given) and the total energy used by any schedule block is made to made the*shape.energy*value. - Scaled power (
*shape.power*is given or*installed_capacity*is set) and the schedule value is multiplied by the*power*. This value must be provided if no schedule is given, and if missing, the*power_density*is used to compute the*installed_capacity*based on the*floor_area*. If the*floor_area*is not available, a default 2500 sf is used.

- power_density
- The default installed power density of each lights object is based on an assumed power density randomly chosen between 0.75 and 1.25 Watts/sf using a triangle distribution.

- Note
- The default installed power density approximates the lighting in a whole house, so is unlikely to be correct unless there is only one lights object in the model. Because most homes have a mixture of lighting types, and thus need more than one lights object, the default density may need to change in the future to be type-specific (which would imply that several lights objects would have to be specified to get a correct set of defaults).

- heatgain_fraction
- The fraction of lighting consumption that ends up as heat in the house defaults to 1.0.

- curtailment
- The fractional curtailment of the lighting (if any). The default value is 1.0 (i.e., no curtailment).

### Modeling Approach

Each lights object will have a single type (incandescent, fluorescent, CFL, SSL, or HID) but may represent multiple fixtures in the house. It is expected that most models will contain one lights object for each type of lighting present in the house, although nothing constrains that.

Each object will have an installed capacity that represents its total consumption when all fixtures represented by the object are on. The scheduling of the lights object (on/off) is based on a simple demand multiplier (p.u.) that is read in from a tape . Future enhancements may give the lights module the ability to generate demand schedules in an intelligent (yet random) way.

Each object will have a constant power factor and each object will have a constant fraction of heat that enters the conditioned space. Thus, the real energy consumption is calculated as

[math] P[kVA] = installed\_power[W] \times shape.load[pu] \times curtailment[pu] \frac{1[kw]}{1000[W]} [/math]

[math] Q[kVAR] = P[kVA] \sqrt {\frac{1}{power\_factor^2}-1} [/math]

## Validation

## Dishwasher

Dishwashers are fairly complex to control. Many wash cycles are simply timed prescriptions for filling, washing, releasing soaps and softeners, and drying, but most washers have several cycles to choose from. Some cycles in some dishwashers include a water temperature booster, which can be fairly energy intensive.

### Modeling Assumptions

- Energy consumption in dishwashers is split between motors and resistance heaters. Thus the power factor changes depending on whether the wash cycle includes water temperature boost and changes from one part of the cycle to another. At this point, however, power factor modeling is simplified to be a constant value, fixed by default at 0.95.
- The fraction of washer consumption that becomes heat in the space is arbitrarily estimated to be 50%. This presumes that half the heat generated by the motors and/or resistance heater is transferred to the water and flushed down the drain.
- Installed capacity (installed_power) is randomly selected between 1000W and 3000W .

### Modeling Approach

Dishwashers are modeled as a simple stream of energy demand signals taken from a tape. That is,

The heat gains to the space are simply

## Range

Electric ranges are essentially perfectly resistive loads. Each “burner” on a range top may be controlled by cycling the power on and off or by a “triac” device that regulates the on time at very high frequency. The user may reset the knob setting multiple times during a cooking event. Thus, range loads vary with the number of active burners, the user-controlled knob settings, and possibly the cycling behavior.

The GridLAB-D range model greatly simplified. It works in a manner essentially identical to the way plug loads are modeled—a demand (0 to 1) is read from a tape and multiplied by a range object-specific capacity (installed_power).

### Modeling Assumptions

- Power factor is assumed to be fixed at 0.95.
- 100% of the range’s energy consumption is assumed to enter the house as heat (ignoring the heat that goes into the food).
- Installed capacity (installed_power) is randomly selected between 2500 W and 4500 W.

### Modeling Approach

The range model retrieves its demand from a tape as a simple stream of values between 0 and 1 (representing the fraction of time the power is on). The demand is adjusted (scaled) by an “installed_power” value associated with each microwave (W). That is,

The heat gains to the space are simply

## Microwave

In their simplest mode of operation (full power), microwave ovens consume an essentially constant power. Other modes, such as defrost or partial-power, typically consume the same power in cycled on-off bursts. Microwaves are typically rated at 750 to 1100 Watts and operate at an efficiency in the neighborhood of 65%, meaning that 65% of the energy consumed goes toward heating food and the rest is released as heat to the surroundings. However the heat released to the surroundings is complicated. Although roughly 35% of consumed energy goes immediately to the house as heat, the 65% that warms the food is arguably released eventually as heat, either as the food cools on the table or as it is released as body heat from the humans who ate it.

### Modeling Assumptions

- Power factor is assumed to be fixed at 0.95.
- Because microwaves have efficiencies in the range of 65%, approximately 35% of their consumption goes immediately to the space as heat. Because body heat from occupants is theoretically accounted for separately, the microwave model assumes none of the remaining energy consumption becomes heat in the space .
- Installed capacity (
*installed_power*) is randomly selected between 700 W and 2000 W .

### Modeling Approach

The microwave model retrieves its demand from a tape as a simple stream of values between 0 and 1 (representing the fraction of time the power is on). Ordinarily, the values will be either 0 or 1 since most microwaves control cooking by cycling. The demand is adjusted (scaled) by an “installed_power” value associated with each microwave (W). That is,

The heat gains to the space are simply

## Refrigerator

**There are serious unit analysis problems in this section** --Dchassin 00:22, 30 January 2009 (UTC)

The thermal and the electric loads on a refrigerator can be estimated using simplified first principles models. In this approach, the thermal load (primarily heat gain from ambient) is modeled as function of few lumped parameters (effective shell conductance, effective thermal mass, and compressor efficiency), ambient condition, internal gains adding and removing food material, and thermostat setting. Once the thermal load is estimated the power consumption of the compressor and the fan can be calculated. Although this approach is not as detailed and accurate as the detailed physical model, it does provide reasonably accurate estimates of the energy consumption.

### Load Calculation

The major heat gains that contribute to the refrigerator thermal load are:

- Conduction through refrigerator/freezer walls.
- Heat gain from infiltration of ambient air when the refrigerator/freezer door is opened.
- Heat gains from additions of food to the refrigerator/freezer.

In general, the amount of heat that must be removed (cooling load) is not always equal to the amount of heat received at a given time. The difference is a result of the heat storage and time lag effects. Only a portion of the heat entering refrigerator actually cools the air inside the refrigerator immediately; the rest cools the mass – the food material. The heat that is stored in the mass will result in thermal load at a later time. So, the modeling approach will have to account for the storage effect.

### Modeling Assumptions

- Power factor is assumed to be fixed at 0.95.
- The thermal conductance of refrigerator and freezer compartments are assumed to be random normal in the range of 0.9 to 1.1 Btu/h.f 2.°F
- The refrigerator compartment set point is assumed to be between 35 and 39°F.

### Modeling Approach

The refrigerator model is currently implemented in its simplest form to calculate the time to change of state based on the current indoor temperature, refrigerator interior temperature, thermal properties of the casing, and food content and water content of the refrigerator compartment. The original ODE relating these properties is

where

- [math]T_{air}[/math] is the temperature of the air
- [math]T_{out}[/math] is the ambient airtemperature around the refrigerator
- [math]UA_r[/math] is the UA of the refrigerator itself
- [math]UA_f[/math] is the UA of the food-air
- [math]C_f[/math] is the heat capacity of the food
- [math]Q_r[/math] is the heat rate from the cooling system

The general solution is:

where

- [math]t[/math] is the elapsed time
- [math]T_0[/math] is the initial temperature
- [math]T_t[/math] is the temperature at time [math]t[/math]
- [math]C_1 = C_f / ( UA_r + UA_f )[/math]
- [math]C_2 = T_{out} + Q_r / UA_f[/math]

The time solution is:

During each synchronization cycle, the refrigerator model calculates the internal gain based on the rated capacity of the refrigerator and returns the time solution for determining the next synchronization time.

## Internal Gains

Each house modeled in GridLAB-D has two primary sources of internally generated heat. First, is the “waste” heat given off by other devices in the house that are modeled by GridLAB-D. For example, a refrigerator located inside the house is modeled primarily for its thermal behavior regarding cooling and freezing food, with its primary output being the impact (energy and peak) on the grid. However, the refrigerator also gives off heat that must be accounted for in the simulation of the house itself. Second, there are devices in the home that are not explicitly modeled by GridLAB-D, but that have sufficient aggregate impact that their heat contribution to the house and their aggregate impact on the home’s electricity must be accounted for. Examples are TV sets, vacuum cleaners, hand-held hair dryers, and other miscellaneous equipment generally plugged into wall outlets.

### Modeling Assumptions

- All “plug loads” are assumed to be consolidated into a single load. Thus, they are all either on one side of the home’s circuit split or evenly distributed between the two sides; this is determined randomly at object creation.
- The installed capacity of plug loads is randomly selected at a value between 700 and 2000 Watts.
- The fraction of plug load consumption that ends up as heat in the house is fixed at 90%.
- The power factor of the aggregate plug loads is fixed at 0.95.

### Modeling Approach

The internal gains reported by modeled devices are simply collected and summed at the house level, the house object being unaware of any details other than the consumption, circuit, and power factor reported by each device.

Other internal gains (aka plug loads) are modeled as a simple, fixed capacity (installed_power) that is multiplied at each time step by a demand fraction (p.u.) read from a tape. [**Is this right? The code currently sets the demand as a random value between 0 and 0.1. --Dchassin 00:26, 30 January 2009 (UTC)**] That is,

Further, the heat to the surrounding space is given by

# See also

- Residential module
- User's Guide
- Appliances
- house class – Single-family home model.
- residential_enduse class – Abstract residential end-use class.
- occupantload – Residential occupants (sensible and latent heat).
- ZIPload – Generic constant impedance/current/power end-use load.

- Technical Documents