Introduction
The residential module is designed to comprehensively model a house object and everything that it contains, such as a water heater, appliances, and end use loads. This module contains the following classes:
- house – Single-family home model, called
House_e. - waterheater – Typical residential water heating appliance.
- ZIPload – Generic constant impedance/current/power end use load.
- lights – Typical residential lights.
- occupantload – Residential occupants (sensible and latent heat).
- plugload – Typical residential plug loads.

The thermal performance of a home in the House_e module is based on a simple thermal heat flow circuit, shown in Figure 1. Here, the complexity of much more detailed thermal models, as used in most building simulations, is reduced to an equivalent thermal parameter (ETP) model in which parallel or nearly parallel heat flow paths and series thermal mass elements are lumped into a few parameters and portrayed as a simple DC electric circuit. This reduces the number of details of the building design that must be specified by the user of House_e , greatly reduces memory requirements, and speeds execution (all critical when simulating populations of buildings, especially relevant where the thermal details of the population are somewhat uncertain in any event).

Where in Figure 1, at the time \(t\):
- \(T_A\) is the indoor air temperature, and
- \(T_M\) is the building mass temperature
- \(T_O\) is the outdoor air temperature,
- \(Q_A\) is the heat added to the indoor air,
- \(Q_M\) is the heat added to the building mass,
- \(U_A\) is the building envelop conductivity to the indoor air,
- \(C_A\) is the heat capacity of the indoor air,
- \(H_M\) is the building mass conductivity to the indoor air, and
- \(C_M\) is the heat capacity of the building mass.
In the laws of physics, temperatures, conductances, thermal masses and heat flows are entirely equivalent to voltages, conductances, capacitors and current flows in the electric circuit analog. That is, the differential equations expressing conservation for energy are the same. In practice, when applied to represent heat flow in a building, this circuit is always over-damped. That is, it exhibits exponential decays and approaches toward steady-state (not oscillatory) conditions.
The ETP circuit captures the essence of the response of the home under most circumstances of importance to analysis of a smart grid: heat gains and losses and the effects of thermal mass, as a function of weather (temperature and solar radiation), occupant behavior (thermostat settings and internal heat gains from appliances), and heating/cooling system efficiencies. How these are modeled using this framework is explained in this document.
In its essence, the thermal envelope of the home has a conductance (\(U_A\)) through which heat flows from the room air temperature (\(T_A\)) to the outdoor air temperature (\(T_O\)). The \(U_A\) is the sum of all parallel heat flow paths through the envelope of the building (walls, windows, doors, ceilings, floors, and infiltration air flows). The primary simplifying assumption here is that the masses of these elements of the building envelope are relatively insignificant compared to their conductances, so their masses can be lumped inside the home.
The bulk of the mass in the home is summed to form the lumped mass \(C_M\), which is coupled to the room air through a conductance that represents the sum of the products of the mass surface area and the heat transfer coefficient. The mass of the air in the interior volume of the house is represented by the much smaller mass \(C_A\), which is directly couple to the room air. The primary effect of \(C_A\) is to realistically dampen the effect of heat delivered to the air (\(Q_A\)) from the heating/cooling (HVAC) system turning on and off, which would otherwise result in an instantaneous change in room air temperature.
Heat gains from solar radiation and from appliances are combined with that from the heating/cooling system to form the heat gains to the air, \(Q_A\). The House_e model allows a specified fraction for each of the heat gains from heating/cooling, solar radiation, and internal appliances to allow them to bypass the air node and be delivered directly to the mass to form \(Q_M\). This can be used to represent solid interior objects absorbing heat from solar radiation shining through windows, for example. This is a reasonable approximation for the wood frame construction predominant in U.S. homes. It becomes an increasingly poor assumption for buildings with massive masonry or brick exterior. Future versions of GridLAB-D™ will have the capability to model these effects explicitly with a modified approach.
Finally, a time-series solution of the ETP circuit must be solved, with a thermostat controlling the HVAC system to maintain heating and cooling setpoints specified by the occupants. This requires modeling the output of the HVAC system, and the electric input to it, as a function of the type, capacity, and efficiency of the equipment under varying conditions such as the outdoor temperature.
The solution for the indoor air temperature and mass temperatures of the ETP model shown in Figure 1 is described below.
The heat balance on \(T_A\) is
Rearranging (1) in the form for solving a differential equation:
The heat balance on \(T_M\) is
The details of how these are modeled from user-specified inputs are described in greater detail in the ETP closed form solution, for those interested in the full derivation.
Synopsis
module residential;
module residential {
default_outdoor_temperature 74.0 [degF];
default_humidity 75.0 [%];
default_etp_iterations 100;
implicit_enduses LIGHTS|PLUGS|OCCUPANCY|NONE;
house_low_temperature_warning 55 [degF];
house_high_temperature_warning 95 [degF];
thermostat_control_warning TRUE;
system_dwell_time 1 [s];
aux_cutin_temperature 10 [degF];
}
Variables
Note
The variable list below represent the default variables for the residential module. These are typically set via their respective modules; for example, the climate module controls the outdoor temperature, humidity, and solar input. If the required module is not present, these default values will be used.
| Variable | Type | Description |
|---|---|---|
| default_line_voltage | complex3 | Incoming line voltage to use when no power objects are defined (default is 240V+0j,120V+0j,120V+0j). |
| default_line_current | complex3 | Line current across the outside energy meter (default is 0A+0j,0A+0j,0A+0j). |
| default_outdoor_temperature | double | Used when no climate/weather data is available (default is 74 degF). The outdoor air temperature determine the rate of heat gain/loss through the building envelope and as a result of air exchange. When the climate module is loaded, the temperature is read from climate object. However, when no climate object available, the default temperature is used. |
| default_humidity | double | Used when no climate/weather data is available (default is 75%). The humidity determines some thermal properties of the building envelope and as a result of air exchange. When the climate module is loaded, the humidity is read from climate object. However, when no climate object available, the default humidity is used. |
| default_solar | double9 | Used when no climate/weather data is available (default is 0,0,0,0,0,0,0,0,0). |
| default_etp_iterations | int64 | Limits the number of iterations the ETP solver will perform before stopping (default is 100). The ETP solver sometimes must iterate using Newton's method to determine the time to the next state change. The default_etp_iterations specifies the maximum number of iterations permitted before the method reports a failure to converge. |