Custom Spatial Thermal Metrics Generation

Version 0.21 adds the capability to create custom thermal spatial metrics from existing EnergyPlus output report variable data. Operations that in older releases required several Mr.Comfy components to be strung together, e.g. summing heating and cooling rates, can thus now be performed with just a single component on canvas- and additional computations that were not possible beforehand, such as custom conditional statements.

The component VarExpress (1) handles new variable calculation. If var_expression_mode (2) is set to “calculate”, it parses the custom non-multiline data input string from the Custom Variable Expressions (3) panel and creates new variable name(s) as specified by the user and separated from the calculation statement(s)/expression(s) by the “=” operator (equals in quotes, do not use without them). This is runtime-intensive and can take several minutes for large models, especially if multiple new variables are requested in one go. After calculations, new variables are available alongside existing ones and do not negatively impact performance.

Existing variable names used to compute custom ones are addressed/called by their names as given in Mr.Comfy’s Available Reporting Variables panel, without any [unit] or (timestep) appendages. Input is neither case- nor whitespace-sensitive, however you must spell the called variables properly.

If multiple variables are to be created, separate expressions with a semicolon ; (and no carriage return / enter). There is no limit on how many new variables can be appended.


The general format for making new variables is as follows:
custom user variable name A “=” existing variable name 01 OPERATOR existing variable name 02; custom variable name B “=” existing variable name 03 OPERATOR existing variable name 04; etc.

A very simple sample statement computes the (simplified) operative temperature from Zone Air and Radiant Temperature EnergyPlus outputs created from the simulation run:

Operative Temperature “=” (Zone Mean Air Temperature + Zone Mean Radiant Temperature)/2

Standard operators (+, -, /,*, **, >=, <=, ==, <, >) in their natural precedence, bracketing and Python math.(expression) inputs (documentation) are supported, including the following operators to evaluate conditional statements/list comprehensions:

if, else, elif, and, or, not, is, in, true, false, for

and, or logical operators enable compound conditional statements to be strung together and become true if either both individual conditions are true (condition A and condition b), or in the case of (condition A or condition B) if at least one sub-statement/component is true. Search online for “boolean logic” for more examples.

Using conditional statements allows powerful control over the nature of the new variable(s), which can be created depending on the values of other preexisting variables:

Combined Heating & Cooling Rate (unoccupied hours) “=” (Zone/Sys Sensible Heating Rate + Zone/Sys Sensible Cooling Rate) if Zone People Sensible Heat Gain == 0 else 0

Combined Heating & Cooling Rate (occupied hours only) “=” (Zone/Sys Sensible Heating Rate + Zone/Sys Sensible Cooling Rate) if Zone People Sensible Heat Gain > 0 else 0

CustomVar_noOccYesOccHeatCooolComboCombined annual heating + cooling energy, unoccupied vs. occupied hours only, custom thermal variable

The tool here evaluates the expression after “=”, creates a new memory-resident data field for each zone and fills it up with hourly values created through the statement. It is important to give an “else” clause with a value that should be appended if the condition is not met, because otherwise an empty data field will result and might cause downstream calculation issues. In the above case, the combined hourly cooling and heating rate is stored for each hourly timestep only if heat gain through occupancy is either zero (left) or larger than zero (right), effectively filtering combined conditioning loads according to whether someone is present in a zone or not. One can use this to compare the non-occupied vs. the occupied loads without having to set zone-specific mapping schedules, which especially in designs with complex occupancy patterns can be hard to do.

Statements/expressions can become arbitrarily complex:

Cooling Season Discomfort (tsens > 1.8 or air temp >= 26) Excess Solar Gains “=” Zone Transmitted Solar if ((piercetsens >= 1.8 or Zone Mean Air Temperature >= 26) and Zone People Sensible Heat Gain > 0 and Zone/Sys Sensible Cooling Rate > 0) else 0

CoolingSeasonExcessSolarGainsMonthly performance map of “Zone Discomfort Excess Solar Gains” while space cooling active, custom thermal variable

This sample expression saves all hourly zone transmitted solar gains to a new variable only when cooling is active, people are in a space and the Pierce TSENS thermal discomfort index is either larger/equal to 1.8 or the zone air temperature is larger/equal to 26°C. Solar gains for other hours are discarded / saved as zero. Spatially mapping the result can help identify when existing/proposed shading is insufficient to in combination with space conditioning maintain a comfortable indoor environment; in (sub)tropical climates, such as the above example shows, these conditions can easily be met in the winter months, when there are excess solar gains present in several of the heavily glazed spaces; due to high sun angles, this happens less severly in summer, counter to what one might expect.

In combination with the builtin frequency mapping functions, custom conditional variables allow you to create frequency maps of when arbitrarily complex conditions are met; we can modify the above expression to give:

Cooling Season Discomfort Frequency (tsens > 1.8 or air temp >= 26) “=” 1 if ((piercetsens >= 1.8 or Zone Mean Air Temperature >= 26) and Zone People Sensible Heat Gain > 0 and Zone/Sys Sensible Cooling Rate > 0) else 0

Instead of the actual zone transmitted solar W values, a “1″ integer is written to each hourly field if the condition is met, otherwise “0″. Setting the Mr.Comfy frequency condition mode to frequency_single and looking for nothing but “1″ thus enables you to easily create frequency maps that give the percentage of occupied hours with cooling active and discomfort a danger, represented through two alternative, non-exclusive conditions.

If you end up creating interesting custom report variables in your work, I’d be happy to share them here on the site- just let me know. This functionality is freshly implemented as of 0.21; if something goes awry, please also get in touch with me.