honeybee_energy.result.loadbalance module

Module for constructing thermal load balances from energy result data collections.

class honeybee_energy.result.loadbalance.LoadBalance(rooms, cooling_data=None, heating_data=None, lighting_data=None, electric_equip_data=None, gas_equip_data=None, process_data=None, service_hot_water_data=None, people_data=None, solar_data=None, infiltration_data=None, mech_ventilation_data=None, nat_ventilation_data=None, surface_flow_data=None, units='Meters', use_all_solar=False)[source]

Bases: object

Object for constructing thermal load balances from energy results.

Parameters:

  • rooms – An array of honeybee Rooms, which will be matched to the input data collections and used to determine which heat flow values are through outdoor surfaces. The length of these Rooms does not have to match the data collections and this object will only construct a load balance for rooms that are found to be matching.

  • cooling_data – Array of data collections for ‘Zone Ideal Loads Supply Air Total Cooling Energy’ that correspond to the input rooms.

  • heating_data – Array of data collections for ‘Zone Ideal Loads Supply Air Total Heating Energy’ that correspond to the input rooms.

  • lighting_data – Array of data collections for ‘Zone Lights Total Heating Energy’ that correspond to the input rooms.

  • electric_equip_data – Array of data collections for ‘Zone Electric Equipment Total Heating Energy’ that correspond to the input rooms.

  • gas_equip_data – Array of data collections for ‘Zone Gas Equipment Total Heating Energy’ that correspond to the input rooms.

  • process_data – Array of data collections for ‘Zone Other Equipment Total Heating Energy’ that correspond to the input rooms.

  • service_hot_water_data – Array of data collections for ‘Water Use Equipment Zone Heat Gain Energy’ that correspond to the input rooms.

  • people_data – Array of data collections for ‘Zone People Total Heating Energy’ that correspond to the input rooms.

  • solar_data – Array of data collections for ‘Zone Windows Total Transmitted Solar Radiation Energy’ that correspond to the input rooms.

  • infiltration_data – The infiltration heat loss (negative) or heat gain (positive), which can be obtained by subtracting ‘Zone Infiltration Total Heat Loss Energy’ data collections from ‘Zone Infiltration Total Heat Gain Energy’ data collections.

  • mech_ventilation_data – The ventilation heat loss (negative) or heat gain (positive) as a result of meeting minimum outdoor air requirements with the mechanical system. This can be obtained by first subtracting ‘Zone Ideal Loads Zone Total Energy’ from ‘Zone Ideal Loads Supply Air Total Energy’ for both heating and cooling loads. Then the resulting heating load (ventilation loss) should be subtracted from the cooling load (ventilation gain).

  • nat_ventilation_data – The natural ventilation heat loss (negative) or heat gain (positive) which can be obtained by subtracting ‘Zone Ventilation Total Heat Loss Energy’ data collections from ‘Zone Ventilation Total Heat Gain Energy’ data collections.

  • surface_flow_data – The surface heat loss (negative) or heat gain (positive), which can be obtained for opaque surfaces with a ‘Surface Average Face Conduction Heat Transfer Energy’ data collection. For fenestration surfaces, it can be obtained by by subtracting ‘Surface Window Heat Loss Energy’ data collections from ‘Surface Window Heat Gain Energy’ data collections.

  • units –

    Text for the units system in which the room geometry exists. Choose from the following:

    • Meters

    • Millimeters

    • Feet

    • Inches

    • Centimeters

  • use_all_solar – Boolean to note whether all of the solar_data should be used in the resulting load balance, regardless of whether it has been matched to the rooms. This is useful for the case that air boundaries exist in a model and solar data is reported for grouped zones. (Default: False).

Properties:

  • rooms

  • floor_area

  • cooling

  • heating

  • lighting

  • electric_equip

  • gas_equip

  • process

  • service_hot_water

  • people

  • solar

  • infiltration

  • mech_ventilation

  • nat_ventilation

  • conduction

  • window_conduction

  • opaque_conduction

  • wall_conduction

  • roof_conduction

  • floor_conduction

  • storage

  • floor_storage

  • wall_storage

  • window_storage

  • air_storage

  • units

ToString()[source]

Overwrite .NET ToString.

classmethod from_sql_file(model, sql_path)[source]

Create a LoadBalance object from an EnergyPlus SQLite result file.

Parameters:

  • model – A honeybee Model, which will have its rooms matched to the input data collections and used to determine which heat flow values are through outdoor surfaces.

  • sql_path – Full path to an SQLite file that was generated by EnergyPlus. this file should have the relevant load balance outputs in the ReportData table.

classmethod from_sql_file_rooms(rooms, sql_path, units='Meters')[source]

Create a LoadBalance object from a SQLite result file and Rooms.

This method will perform a check such that, if the rooms do not have properties that can be matched to certain data in the SQL, no exception will be raised. Note that, if the input rooms contain AirBoundaries, the solar term of the resulting balance will not be correct.

Parameters:

  • rooms – An array of honeybee Rooms, which will be matched to the input data collections and used to determine which heat flow values are through outdoor surfaces. The length of these Rooms does not have to match the data collections and this object will only construct a load balance for rooms that are found to be matching.

  • sql_path – Full path to an SQLite file that was generated by EnergyPlus. this file should have the relevant load balance outputs in the ReportData table.

  • units –

    Text for the units system in which the room geometry exists. Choose from the following:

    • Meters

    • Millimeters

    • Feet

    • Inches

    • Centimeters

load_balance_terms(floor_normalized=False, include_storage=False, detailed_faces=False)[source]

Get a list of data collections with one for each term in the load balance.

Terms of the load balance that are None will be excluded from this list. Conduction terms will only appear as opaque and window conduction terms.

Parameters:

  • floor_normalized – Boolean to note whether all of the output data collections should have values that are normalized by the Room floor area.

  • include_storage – Boolean to note whether the storage term should be included in the list.

  • detailed_faces – Boolean to note whether the opaque conduction losses should be broken down into walls, roofs, and floors. Setting this to True will also cause storage to be broken down into storage in walls, floors, windows, and air. (Default: False).

static load_data_from_sql(sql_path)[source]

Load all data collections relevant to load balances from a SQL file.

Parameters:

sql_path – Full path to an SQLite file that was generated by EnergyPlus. this file should have the relevant load balance outputs in the ReportData table.

Returns:

A tuple where each item is a list of data collections relevant to load balances.

static mech_vent_loss_gain(zone_cooling, zone_heating, cooling, heating)[source]

Compute mechanical ventilation loss/gain from lists of data collections.

Parameters:

  • zone_cooling – A list of data collections for zone-level cooling.

  • zone_heating – A list of data collections for zone-level heating.

  • cooling – A list of data collections for supply air cooling.

  • heating – A list of data collections for supply air heating.

static subtract_loss_from_gain(load_gain, load_loss)[source]

Subtract an array of load loss data collections from load gain collections.

This is what is needed for certain LoadBalance inputs like infiltration and natural ventilation.

Parameters:

  • load_gain – A list of data collections with load gains.

  • load_loss – A list of data collections with load losses.

COOLING = ('Zone Ideal Loads Supply Air Total Cooling Energy', 'Zone Ideal Loads Supply Air Sensible Cooling Energy', 'Zone Ideal Loads Supply Air Latent Cooling Energy')
ELECTRIC_EQUIP = ('Zone Electric Equipment Electricity Energy', 'Zone Electric Equipment Total Heating Energy', 'Zone Electric Equipment Radiant Heating Energy', 'Zone Electric Equipment Convective Heating Energy', 'Zone Electric Equipment Latent Gain Energy')
EXTERIOR_BCS = (<class 'honeybee.boundarycondition.Outdoors'>, <class 'honeybee.boundarycondition.Ground'>, <class 'honeybee_energy.boundarycondition.OtherSideTemperature'>)
GAS_EQUIP = ('Zone Gas Equipment NaturalGas Energy', 'Zone Gas Equipment Total Heating Energy', 'Zone Gas Equipment Radiant Heating Energy', 'Zone Gas Equipment Convective Heating Energy', 'Zone Gas Equipment Latent Gain Energy')
HEATING = ('Zone Ideal Loads Supply Air Total Heating Energy', 'Zone Ideal Loads Supply Air Sensible Heating Energy', 'Zone Ideal Loads Supply Air Latent Heating Energy')
HOT_WATER = ('Water Use Equipment Zone Sensible Heat Gain Energy', 'Water Use Equipment Zone Latent Gain Energy')
INFIL_GAIN = ('Zone Infiltration Total Heat Gain Energy', 'Zone Infiltration Sensible Heat Gain Energy', 'Zone Infiltration Latent Heat Gain Energy', 'AFN Zone Infiltration Sensible Heat Gain Energy', 'AFN Zone Infiltration Latent Heat Gain Energy')
INFIL_LOSS = ('Zone Infiltration Total Heat Loss Energy', 'Zone Infiltration Sensible Heat Loss Energy', 'Zone Infiltration Latent Heat Loss Energy', 'AFN Zone Infiltration Sensible Heat Loss Energy', 'AFN Zone Infiltration Latent Heat Loss Energy')
INTERIOR_BCS = (<class 'honeybee.boundarycondition.Surface'>, <class 'honeybee_energy.boundarycondition.Adiabatic'>)
LIGHTING = ('Zone Lights Electricity Energy', 'Zone Lights Total Heating Energy')
NAT_VENT_GAIN = ('Zone Ventilation Sensible Heat Gain Energy', 'Zone Ventilation Latent Heat Gain Energy', 'AFN Zone Ventilation Sensible Heat Gain Energy', 'AFN Zone Ventilation Latent Heat Gain Energy')
NAT_VENT_LOSS = ('Zone Ventilation Sensible Heat Loss Energy', 'Zone Ventilation Latent Heat Loss Energy', 'AFN Zone Ventilation Sensible Heat Loss Energy', 'AFN Zone Ventilation Latent Heat Loss Energy')
OPAQUE_ENERGY_FLOW = 'Surface Inside Face Conduction Heat Transfer Energy'
PEOPLE_GAIN = ('Zone People Total Heating Energy', 'Zone People Sensible Heating Energy', 'Zone People Latent Gain Energy')
PROCESS = ('Zone Other Equipment Total Heating Energy', 'Zone Other Equipment Convective Heating Energy', 'Zone Other Equipment Radiant Heating Energy', 'Zone Other Equipment Latent Heating Energy')
SOLAR_GAIN = ('Zone Windows Total Transmitted Solar Radiation Energy', 'Enclosure Windows Total Transmitted Solar Radiation Energy')
UNITS = ('Meters', 'Millimeters', 'Feet', 'Inches', 'Centimeters')
VENT_GAIN = ('Zone Ideal Loads Zone Total Cooling Energy', 'Zone Ideal Loads Zone Sensible Cooling Energy', 'Zone Ideal Loads Zone Latent Cooling Energy')
VENT_LOSS = ('Zone Ideal Loads Zone Total Heating Energy', 'Zone Ideal Loads Zone Sensible Heating Energy', 'Zone Ideal Loads Zone Latent Heating Energy')
WINDOW_GAIN = 'Surface Window Heat Gain Energy'
WINDOW_LOSS = 'Surface Window Heat Loss Energy'
property air_storage

Get a data collection for heat loss/gain from storage within Room air.

This term is computed as the remainder of the load balance after storage within walls, floors and windows is removed.

property conduction

Get a data collection for all conduction loss/gain of the load balance.

property cooling

Get a data collection for the cooling of the load balance.

property electric_equip

Get a data collection for the electric equipment gain of the load balance.

property floor_area

Get or set a number for the total floor area in square meters or square feet.

By default, this is the floor area of only the successfully-matched rooms.

This floor area accounts for Room multipliers and will always be in either square meters or square feet depending on whether this object’s units are either SI or IP.

property floor_conduction

Get a data collection for floor conduction loss/gain of the load balance.

property floor_storage

Get a data collection for heat loss/gain from storage within interior floors.

When the model is for a single room or subset of a whole building, this term will indicate heat loss to adjacent Rooms through interior Floors. It also includes all heat exchange that happens across Ceilings.

property gas_equip

Get a data collection for the gas equipment gain of the load balance.

property heating

Get a data collection for the heating of the load balance.

property infiltration

Get a data collection for the infiltration gain/loss of the load balance.

property lighting

Get a data collection for the lighting gain of the load balance.

property mech_ventilation

Get a data collection for the mechanical ventilation of the load balance.

property nat_ventilation

Get a data collection for the natural ventilation of the load balance.

property opaque_conduction

Get a data collection for opaque conduction loss/gain of the load balance.

property people

Get a data collection for the people gain of the load balance.

property process

Get a data collection for the process load gain of the load balance.

property roof_conduction

Get a data collection for roof conduction loss/gain of the load balance.

property rooms

Get the Rooms that have been successfully matched to the input data.

property service_hot_water

Get a data collection for the service hot water gain of the load balance.

property solar

Get a data collection for the solar gain of the load balance.

property storage

Get a data collection for the remainder of the load balance, indicating storage.

property units

Get or set text for the units system in which the room geometry exists.

property wall_conduction

Get a data collection for wall conduction loss/gain of the load balance.

property wall_storage

Get a data collection for heat loss/gain from storage within interior walls.

When the model is for a single room or subset of a whole building, this term will indicate heat loss to adjacent Rooms through interior Walls. It also includes all heat exchange that happens across AirBoundaries.

property window_conduction

Get a data collection for window conduction loss/gain of the load balance.

property window_storage

Get a data collection for heat loss/gain from storage within interior windows.

This will also include any heat transfer from doors. For full building models, this term should typically be very close to zero given that EnergyPlus Fenestration surfaces don’t typically have thermal mass. However, when the model is for a single room or subset of a whole building, this term will indicate heat loss to adjacent Rooms through interior windows.