honeybee_energy.load.daylight module

Room daylight controls, including sensor location and setpoint.

class honeybee_energy.load.daylight.DaylightingControl(sensor_position, illuminance_setpoint=300, control_fraction=1, min_power_input=0.3, min_light_output=0.2, off_at_minimum=False)[source]

Bases: object

Room daylight controls, including sensor location and setpoint.

Parameters:

  • sensor_position – A ladybug_geometry Point3D for the position of the daylight sensor within the parent Room. This point should lie within the Room volume in order for the results to be meaningful. The ladybug_geometry Polyface.is_point_inside method can be used to check whether a given point is inside the room volume.

  • illuminance_setpoint –

    A number for the illuminance setpoint in lux beyond which electric lights are dimmed if there is sufficient daylight. Some common setpoints are listed below. (Default: 300 lux).

    • 50 lux - Corridors and hallways.

    • 150 lux - Computer work spaces (screens provide illumination).

    • 300 lux - Paper work spaces (reading from surfaces needing illumination).

    • 500 lux - Retail spaces or museums illuminating merchandise/artifacts.

    • 1000 lux - Operating rooms and workshops where light is needed for safety.

  • control_fraction – A number between 0 and 1 that represents the fraction of the Room lights that are dimmed when the illuminance at the sensor position is at the specified illuminance. 1 indicates that all lights are dim-able while 0 indicates that no lights are dim-able. Deeper rooms should have lower control fractions to account for the face that the lights in the back of the space do not dim in response to suitable daylight at the front of the room. (Default: 1).

  • min_power_input – A number between 0 and 1 for the the lowest power the lighting system can dim down to, expressed as a fraction of maximum input power. (Default: 0.3).

  • min_light_output – A number between 0 and 1 the lowest lighting output the lighting system can dim down to, expressed as a fraction of maximum light output. (Default: 0.2).

  • off_at_minimum – Boolean to note whether lights should switch off completely when they get to the minimum power input. (Default: False).

Properties:

  • sensor_position

  • illuminance_setpoint

  • control_fraction

  • min_power_input

  • min_light_output

  • off_at_minimum

  • parent

  • has_parent

  • is_sensor_inside_parent

ToString()[source]

Overwrite .NET ToString.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a DaylightingControl object from a dictionary.

Parameters:

data – A DaylightingControl dictionary in following the format below.

{
"type": 'DaylightingControl',
"sensor_position": [5, 5, 0.8]  # array of xyz coordinates for the sensor
"illuminance_setpoint": 300,  # number for illuminance setpoint in lux
"control_fraction": 0.5,  # fraction of the lights that are dim-able
"min_power_input": 0.3,  # minimum fraction of lighting power
"min_light_output": 0.2,  # minimum fraction of lighting output
"off_at_minimum": True  # boolean for whether the lights switch off
}
classmethod from_idf(idf_string, idf_point_string)[source]

Create a DaylightingControl object from an EnergyPlus IDF text string.

Parameters:

  • idf_string – A text string fully describing an EnergyPlus Daylighting:Controls definition.

  • idf_point_string – A text string fully describing an EnergyPlus Daylighting:ReferencePoint definition.

Returns:

A DaylightingControl object loaded from the idf_string.

move(moving_vec)[source]

Move this object along a vector.

Parameters:

moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the sensor.

reflect(plane)[source]

Reflect this object across a plane.

Parameters:

plane – A ladybug_geometry Plane across which the object will be reflected.

rotate(angle, axis, origin)[source]

Rotate this object by a certain angle around an axis and origin.

Parameters:

  • angle – An angle for rotation in degrees.

  • axis – Rotation axis as a Vector3D.

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy(angle, origin)[source]

Rotate this object counterclockwise in the world XY plane by a certain angle.

Parameters:

  • angle – An angle in degrees.

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)[source]

Scale this object by a factor from an origin point.

Parameters:

  • factor – A number representing how much the object should be scaled.

  • origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

to_dict(abridged=False)[source]

DaylightingControl 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()[source]

IDF string representation of DaylightingControl object.

Returns:

A tuple with two values.

  • idf_control – IDF string for the Daylighting:Controls object.

  • idf_point – IDF string for the Daylighting:ReferencePoint object.

Daylighting:Controls,
    West Zone_DaylCtrl,      !- Name
    West Zone,               !- Zone or Space Name
    SplitFlux,               !- Daylighting Method
    ,                        !- Availability Schedule Name
    Continuous,              !- Lighting Control Type
    0.3,                     !- Minimum Input Power Fraction for Continuous or ContinuousOff Dimming Control
    0.2,                     !- Minimum Light Output Fraction for Continuous or ContinuousOff Dimming Control
    ,                        !- Number of Stepped Control Steps
    1.0,                     !- Probability Lighting will be Reset When Needed in Manual Stepped Control
    West Zone_DaylRefPt1,    !- Glare Calculation Daylighting Reference Point Name
    180.0,                   !- Glare Calculation Azimuth Angle of View Direction Clockwise from Zone y-Axis {deg}
    20.0,                    !- Maximum Allowable Discomfort Glare Index
    ,                        !- DElight Gridding Resolution {m2}
    West Zone_DaylRefPt1,    !- Daylighting Reference Point 1 Name
    1.0,                     !- Fraction of Lights Controlled by Reference Point 1
    500.;                    !- Illuminance Setpoint at Reference Point 1 {lux}

Daylighting:ReferencePoint,
    West Zone_DaylRefPt1,    !- Name
    West Zone,               !- Zone or Space Name
    3.048,                   !- X-Coordinate of Reference Point {m}
    3.048,                   !- Y-Coordinate of Reference Point {m}
    0.9;                     !- Z-Coordinate of Reference Point {m}
property control_fraction

Get or set the fraction of the Room lights that are dimmed.

property has_parent

Get a boolean noting whether this object has a parent Room.

property illuminance_setpoint

Get or set a number for the illuminance setpoint in lux.

property is_sensor_inside_parent

Get a boolean for whether the sensor position is inside the parent Room.

This will always be True if no parent is assigned.

property min_light_output

Get or set the lowest lighting output the lighting system can dim down to.

property min_power_input

Get or set the lowest power the lighting system can dim down to.

property off_at_minimum

Get or set a boolean to indicate whether the lights switch off completely.

property parent

Get the parent Room if assigned. None if not assigned.

property sensor_position

Get or set a Point3D for the sensor position for the daylight sensor.