honeybee_energy.load.equipment module

Complete definition of equipment in a simulation, including schedule and load.

class honeybee_energy.load.equipment.ElectricEquipment(identifier, watts_per_area, schedule, radiant_fraction=0, latent_fraction=0, lost_fraction=0)[source]

Bases: _EquipmentBase

A complete definition of electric equipment, including schedules and load.

Parameters

  • identifier – Text string for a unique ElectricEquipment ID. Must be < 100 characters and not contain any EnergyPlus special characters. This will be used to identify the object across a model and in the exported IDF.

  • watts_per_area – A numerical value for the equipment power density in Watts per square meter of floor area.

  • schedule – A ScheduleRuleset or ScheduleFixedInterval for the use of equipment over the course of the year. The type of this schedule should be Fractional and the fractional values will get multiplied by the watts_per_area to yield a complete equipment profile.

  • radiant_fraction – A number between 0 and 1 for the fraction of the total equipment load given off as long wave radiant heat. (Default: 0).

  • latent_fraction – A number between 0 and 1 for the fraction of the total equipment load that is latent (as opposed to sensible). (Default: 0).

  • lost_fraction – A number between 0 and 1 for the fraction of the total equipment load that is lost outside of the zone and the HVAC system. Typically, this is used to represent heat that is exhausted directly out of a zone (as you would for a stove). (Default: 0).

Properties:

  • identifier

  • display_name

  • watts_per_area

  • schedule

  • radiant_fraction

  • latent_fraction

  • lost_fraction

  • convected_fraction

  • user_data

ToString()

Overwrite .NET ToString.

static average(identifier, equipments, weights=None, timestep_resolution=1)[source]

Get an ElectricEquipment object that’s an average between other objects.

Parameters

  • identifier – Text string for a unique ID for the new averaged ElectricEquipment. Must be < 100 characters and not contain any EnergyPlus special characters. This will be used to identify the object across a model and in the exported IDF.

  • equipments – A list of ElectricEquipment objects that will be averaged together to make a new ElectricEquipment.

  • weights – An optional list of fractional numbers with the same length as the input equipments. These will be used to weight each of the equipment objects in the resulting average. Note that these weights can sum to less than 1 in which case the average watts_per_area will assume 0 for the unaccounted fraction of the weights. If None, the objects will be weighted equally. Default: None.

  • timestep_resolution – An optional integer for the timestep resolution at which the schedules will be averaged. Any schedule details smaller than this timestep will be lost in the averaging process. Default: 1.

diversify(count, watts_stdev=20, schedule_offset=1, timestep=1, schedule_indices=None)

Get an array of diversified Equipment derived from this “average” one.

Approximately 2/3 of the schedules in the output objects will be offset from the mean by the input schedule_offset (1/3 ahead and another 1/3 behind).

Parameters

  • count – An positive integer for the number of diversified objects to generate from this mean object.

  • watts_stdev – A number between 0 and 100 for the percent of the watts_per_area representing one standard deviation of diversification from the mean. (Default 20 percent).

  • schedule_offset – A positive integer for the number of timesteps at which the lighting schedule of the resulting objects will be shifted - roughly 1/3 of the objects ahead and another 1/3 behind. (Default: 1).

  • timestep – An integer for the number of timesteps per hour at which the shifting is occurring. This must be a value between 1 and 60, which is evenly divisible by 60. 1 indicates that each step is an hour while 60 indicates that each step is a minute. (Default: 1).

  • schedule_indices – An optional list of integers from 0 to 2 with a length equal to the input count, which will be used to set whether a given schedule is behind (0), ahead (2), or the same (1). This can be used to coordinate schedules across diversified programs. If None a random list of integers will be genrated. (Default: None).

duplicate()

Get a copy of this object.

classmethod from_dict(data)[source]

Create a ElectricEquipment object from a dictionary.

Note that the dictionary must be a non-abridged version for this classmethod to work.

Parameters

data – A ElectricEquipment dictionary in following the format below.

{
"type": 'ElectricEquipment',
"identifier": 'Open_Office_Equipment_50_03',
"display_name": 'Office Equipment',
"watts_per_area": 5, # equipment watts per square meter of floor area
"schedule": {}, # ScheduleRuleset/ScheduleFixedInterval dictionary
"radiant_fraction": 0.3, # fraction of heat that is long wave radiant
"latent_fraction": 0, # fraction of heat that is latent
"lost_fraction": 0 # fraction of heat that is lost
}
classmethod from_dict_abridged(data, schedule_dict)[source]

Create a ElectricEquipment object from an abridged dictionary.

Parameters

  • data – A ElectricEquipmentAbridged dictionary in following the format below.

  • schedule_dict – A dictionary with schedule identifiers as keys and honeybee schedule objects as values (either ScheduleRuleset or ScheduleFixedInterval). These will be used to assign the schedules to the equipment object.

{
"type": 'ElectricEquipmentAbridged',
"identifier": 'Open_Office_Equipment_50_03',
"display_name": 'Office Equipment',
"watts_per_area": 5, # equipment watts per square meter of floor area
"schedule": "Office Equipment Schedule", # Schedule identifier
"radiant_fraction": 0.3, # fraction of heat that is long wave radiant
"latent_fraction": 0, # fraction of heat that is latent
"lost_fraction": 0 # fraction of heat that is lost
}
classmethod from_idf(idf_string, schedule_dict)[source]

Create an ElectricEquipment object from an EnergyPlus IDF text string.

Note that the ElectricEquipment idf_string must use the ‘watts per zone floor area’ method in order to be successfully imported.

Parameters

  • idf_string – A text string fully describing an EnergyPlus ElectricEquipment definition.

  • schedule_dict – A dictionary with schedule identifiers as keys and honeybee schedule objects as values (either ScheduleRuleset or ScheduleFixedInterval). These will be used to assign the schedules to the ElectricEquipment object.

Returns

A tuple with two elements

  • equipment: An ElectricEquipment object loaded from the idf_string.

  • zone_identifier: The identifier of the zone to which the ElectricEquipment object should be assigned.

lock()
to_dict(abridged=False)[source]

ElectricEquipment dictionary representation.

Parameters

abridged – Boolean to note whether the full dictionary describing the object should be returned (False) or just an abridged version (True), which only specifies the identifiers of schedules. Default: False.

to_idf(zone_identifier)[source]

IDF string representation of ElectricEquipment object.

Note that this method only outputs a single string for the ElectricEquipment object and, to write everything needed to describe the object into an IDF, this object’s schedule must also be written.

Parameters

zone_identifier – Text for the zone identifier that the ElectricEquipment object is assigned to.

unlock()
property convected_fraction

Get the fraction of equipment heat that convects to the zone air.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property identifier

Get or set the text string for object identifier.

property latent_fraction

Get or set the fraction of equipment heat that is latent.

property lost_fraction

Get or set the fraction of equipment heat that is lost out of the zone.

property properties

Get properties for extensions.

property radiant_fraction

Get or set the fraction of equipment heat given off as long wave radiation.

property schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for equipment usage.

property user_data

Get or set an optional dictionary for additional meta data for this object.

This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list, dict)

property watts_per_area

Get or set the equipment power density in Watts/square meter of floor area.

class honeybee_energy.load.equipment.GasEquipment(identifier, watts_per_area, schedule, radiant_fraction=0, latent_fraction=0, lost_fraction=0)[source]

Bases: _EquipmentBase

A complete definition of gas equipment, including schedules and load.

Parameters

  • identifier – Text string for a unique GasEquipment ID. Must be < 100 characters and not contain any EnergyPlus special characters. This will be used to identify the object across a model and in the exported IDF.

  • watts_per_area – A numerical value for the equipment power density in Watts per square meter of floor area.

  • schedule – A ScheduleRuleset or ScheduleFixedInterval for the use of equipment over the course of the year. The type of this schedule should be Fractional and the fractional values will get multiplied by the watts_per_area to yield a complete equipment profile.

  • radiant_fraction – A number between 0 and 1 for the fraction of the total equipment load given off as long wave radiant heat. (Default: 0).

  • latent_fraction – A number between 0 and 1 for the fraction of the total equipment load that is latent (as opposed to sensible). (Default: 0).

  • lost_fraction – A number between 0 and 1 for the fraction of the total equipment load that is lost outside of the zone and the HVAC system. Typically, this is used to represent heat that is exhausted directly out of a zone (as you would for a stove). (Default: 0).

Properties:

  • identifier

  • display_name

  • watts_per_area

  • schedule

  • radiant_fraction

  • latent_fraction

  • lost_fraction

  • convected_fraction

  • user_data

ToString()

Overwrite .NET ToString.

static average(identifier, equipments, weights=None, timestep_resolution=1)[source]

Get a GasEquipment object that’s an average between other objects.

Parameters

  • identifier – Text string for a unique ID for the new averaged GasEquipment. Must be < 100 characters and not contain any EnergyPlus special characters. This will be used to identify the object across a model and in the exported IDF.

  • equipments – A list of GasEquipment objects that will be averaged together to make a new GasEquipment.

  • weights – An optional list of fractional numbers with the same length as the input equipments. These will be used to weight each of the equipment objects in the resulting average. Note that these weights can sum to less than 1 in which case the average watts_per_area will assume 0 for the unaccounted fraction of the weights. If None, the objects will be weighted equally. Default: None.

  • timestep_resolution – An optional integer for the timestep resolution at which the schedules will be averaged. Any schedule details smaller than this timestep will be lost in the averaging process. Default: 1.

diversify(count, watts_stdev=20, schedule_offset=1, timestep=1, schedule_indices=None)

Get an array of diversified Equipment derived from this “average” one.

Approximately 2/3 of the schedules in the output objects will be offset from the mean by the input schedule_offset (1/3 ahead and another 1/3 behind).

Parameters

  • count – An positive integer for the number of diversified objects to generate from this mean object.

  • watts_stdev – A number between 0 and 100 for the percent of the watts_per_area representing one standard deviation of diversification from the mean. (Default 20 percent).

  • schedule_offset – A positive integer for the number of timesteps at which the lighting schedule of the resulting objects will be shifted - roughly 1/3 of the objects ahead and another 1/3 behind. (Default: 1).

  • timestep – An integer for the number of timesteps per hour at which the shifting is occurring. This must be a value between 1 and 60, which is evenly divisible by 60. 1 indicates that each step is an hour while 60 indicates that each step is a minute. (Default: 1).

  • schedule_indices – An optional list of integers from 0 to 2 with a length equal to the input count, which will be used to set whether a given schedule is behind (0), ahead (2), or the same (1). This can be used to coordinate schedules across diversified programs. If None a random list of integers will be genrated. (Default: None).

duplicate()

Get a copy of this object.

classmethod from_dict(data)[source]

Create a GasEquipment object from a dictionary.

Note that the dictionary must be a non-abridged version for this classmethod to work.

Parameters

data – A GasEquipment dictionary in following the format below.

{
"type": 'GasEquipment',
"identifier": 'Kitchen_Equipment_200_03_02_0',
"display_name": 'Kitchen Equipment',
"watts_per_area": 20, # equipment watts per square meter of floor area
"schedule": {}, # ScheduleRuleset/ScheduleFixedInterval dictionary
"radiant_fraction": 0.3, # fraction of heat that is long wave radiant
"latent_fraction": 0.2, # fraction of heat that is latent
"lost_fraction": 0 # fraction of heat that is lost
}
classmethod from_dict_abridged(data, schedule_dict)[source]

Create a GasEquipment object from an abridged dictionary.

Parameters

  • data – A GasEquipmentAbridged dictionary in following the format below.

  • schedule_dict – A dictionary with schedule identifiers as keys and honeybee schedule objects as values (either ScheduleRuleset or ScheduleFixedInterval). These will be used to assign the schedules to the equipment object.

{
"type": 'GasEquipmentAbridged',
"identifier": 'Kitchen_Equipment_200_03_02_0',
"display_name": 'Kitchen Equipment',
"watts_per_area": 20, # equipment watts per square meter of floor area
"schedule": "Kitchen Equipment Schedule", # Schedule identifier
"radiant_fraction": 0.3, # fraction of heat that is long wave radiant
"latent_fraction": 0,  fraction of heat that is latent
"lost_fraction": 0  fraction of heat that is lost
}
classmethod from_idf(idf_string, schedule_dict)[source]

Create an GasEquipment object from an EnergyPlus IDF text string.

Note that the GasEquipment idf_string must use the ‘watts per zone floor area’ method in order to be successfully imported.

Parameters

  • idf_string – A text string fully describing an EnergyPlus GasEquipment definition.

  • schedule_dict – A dictionary with schedule identifiers as keys and honeybee schedule objects as values (either ScheduleRuleset or ScheduleFixedInterval). These will be used to assign the schedules to the GasEquipment object.

Returns

A tuple with two elements

  • equipment: An GasEquipment object loaded from the idf_string.

  • zone_identifier: The identifier of the zone to which the GasEquipment object should be assigned.

lock()
to_dict(abridged=False)[source]

GasEquipment dictionary representation.

Parameters

abridged – Boolean to note whether the full dictionary describing the object should be returned (False) or just an abridged version (True), which only specifies the identifiers of schedules. Default: False.

to_idf(zone_identifier)[source]

IDF string representation of GasEquipment object.

Note that this method only outputs a single string for the GasEquipment object and, to write everything needed to describe the object into an IDF, this object’s schedule must also be written.

Parameters

zone_identifier – Text for the zone identifier that the GasEquipment object is assigned to.

unlock()
property convected_fraction

Get the fraction of equipment heat that convects to the zone air.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property identifier

Get or set the text string for object identifier.

property latent_fraction

Get or set the fraction of equipment heat that is latent.

property lost_fraction

Get or set the fraction of equipment heat that is lost out of the zone.

property properties

Get properties for extensions.

property radiant_fraction

Get or set the fraction of equipment heat given off as long wave radiation.

property schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for equipment usage.

property user_data

Get or set an optional dictionary for additional meta data for this object.

This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list, dict)

property watts_per_area

Get or set the equipment power density in Watts/square meter of floor area.