honeybee_energy.load.lighting module

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

class honeybee_energy.load.lighting.Lighting(identifier, watts_per_area, schedule, return_air_fraction=0.0, radiant_fraction=0.32, visible_fraction=0.25)[source]

Bases: _LoadBase

A complete definition of lighting, including schedules and load.

Parameters

  • identifier – Text string for a unique Lighting 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 lighting power density in Watts per square meter of floor area.

  • schedule – A ScheduleRuleset or ScheduleFixedInterval for the use of lights 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 lighting profile.

  • return_air_fraction – A number between 0 and 1 for the fraction of the total lighting load that goes into the zone return air (into the zone outlet node). (Default: 0.0). (representative of pendant lighting).

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

  • visible_fraction – A number between 0 and 1 for the fraction of the total lighting load given off as short wave visible light. (Default: 0.25). (representative of pendant lighting).

Properties:

  • identifier

  • display_name

  • watts_per_area

  • schedule

  • return_air_fraction

  • radiant_fraction

  • visible_fraction

  • convected_fraction

  • baseline_watts_per_area

  • user_data

ToString()

Overwrite .NET ToString.

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

Get a Lighting object that’s a weighted average between other Lighting objects.

Parameters

  • identifier – Text string for a unique ID for the new averaged Lighting. 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.

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

  • weights – An optional list of fractional numbers with the same length as the input lightings. These will be used to weight each of the Lighting 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)[source]

Get an array of diversified Lighting 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 generated. (Default: None).

duplicate()

Get a copy of this object.

classmethod from_dict(data)[source]

Create a Lighting object from a dictionary.

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

Parameters

data – A Lighting dictionary in following the format below.

{
"type": 'Lighting',
"identifier": 'Open_Office_Lighting_100_0_032_025',
"display_name": 'Office Lighting',
"watts_per_area": 10, # lighting watts per square meter of floor area
"schedule": {}, # ScheduleRuleset/ScheduleFixedInterval dictionary
"return_air_fraction": 0, # fraction of heat going to return air
"radiant_fraction": 0.32, # fraction of heat that is long wave radiant
"visible_fraction": 0.25 # fraction of heat that is short wave visible
}
classmethod from_dict_abridged(data, schedule_dict)[source]

Create a Lighting object from an abridged dictionary.

Parameters

  • data – A LightingAbridged 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 Lighting object.

{
"type": 'LightingAbridged',
"identifier": 'Open_Office_Lighting_100_0_032_025',
"display_name": 'Office Lighting',
"watts_per_area": 10, # lighting watts per square meter of floor area
"schedule": "Office Lighting Schedule", # Schedule identifier
"return_air_fraction": 0, # fraction of heat going to return air
"radiant_fraction": 0.32, # fraction of heat that is long wave radiant
"visible_fraction": 0.25 # fraction of heat that is short wave visible
}
classmethod from_idf(idf_string, schedule_dict)[source]

Create a Lighting object from an EnergyPlus IDF text string.

Note that the Lighting 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 lighting 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 Lighting object.

Returns

A tuple with two elements

  • lighting: A Lighting object loaded from the idf_string.

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

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

Lighting 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 Lighting object.

Note that this method only outputs a single string for the Lights object and, to write everything needed to describe the object into an IDF, this object’s schedule must also be written. This is done to give more control over the export process since you typically want to check whether these schedules are used by multiple Lighting objects and write the schedule into the IDF only once.

Parameters

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

unlock()
property baseline_watts_per_area

Get or set the baseline lighting power density in W/m2 of floor area.

This baseline is useful to track how much better the installed lights are in comparison to a standard like ASHRAE 90.1. If set to None, it will default to 11.84029 W/m2, which is that ASHRAE 90.1-2004 baseline for an office.

property convected_fraction

Get the fraction of lighting 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 properties

Get properties for extensions.

property radiant_fraction

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

property return_air_fraction

Get or set the fraction of lighting heat that goes into the return air.

property schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for lighting 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 visible_fraction

Get or set the fraction of lighting heat given off as visible light.

property watts_per_area

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