honeybee_radiance_postprocess.results.annual_daylight module

class honeybee_radiance_postprocess.results.annual_daylight.AnnualDaylight(folder, schedule: Optional[list] = None, load_arrays: bool = False)[source]

Bases: Results

Annual Daylight Results class.

Parameters

  • folder – Path to results folder.

  • schedule – 8760 values as a list. Values must be either 0 or 1. Values of 1 indicates occupied hours. If no schedule is provided a default schedule will be used. (Default: None).

  • load_arrays – Set to True to load all NumPy arrays. If False the arrays will be loaded only once they are needed. In both cases the loaded array(s) will be stored in a dictionary under the arrays property. (Default: False).

Properties:

  • schedule

  • occ_pattern

  • total_occ

  • sun_down_occ_hours

  • occ_mask

  • arrays

  • valid_states

  • datatype

annual_data(states: Optional[DynamicSchedule] = None, grids_filter: str = '*', sensor_index: Optional[dict] = None, res_type: str = 'total') → Tuple[List[List[HourlyContinuousCollection]], List[dict], dict]

Get annual data for one or multiple sensors.

Parameters

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • sensor_index – A dictionary with grids as keys and a list of sensor indices as values. Defaults to None.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with Data Collections for each sensor, grid information,

and a dictionary of the sensors.

Return type

Tuple

annual_data_to_folder(target_folder: str, states: Optional[DynamicSchedule] = None, grids_filter: str = '*', sensor_index: Optional[dict] = None, res_type: str = 'total')

Get annual data for one or multiple sensors and write the data to a folder as Data Collections.

Parameters

  • target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • sensor_index – A dictionary with grids as keys and a list of sensor indices as values. Defaults to None.

  • res_type – Type of results to load. Defaults to ‘total’.

annual_metrics(threshold: float = 300, min_t: float = 100, max_t: float = 3000, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[ndarray], List[ndarray], List[ndarray], List[ndarray], List[ndarray], List[dict]][source]

Calculate multiple annual daylight metrics.

This method will calculate the following metrics:

  • Daylight autonomy

  • Continuous daylight autonomy

  • Useful daylight illuminance

  • Lower than useful daylight illuminance

  • Higher than useful daylight illuminance

Parameters

  • threshold – Threshold value for daylight autonomy. Defaults to 300.

  • min_t – Minimum threshold for useful daylight illuminance. Defaults to 100.

  • max_t – Maximum threshold for useful daylight illuminance. Defaults to 3000.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the five annual daylight metrics and grid information.

Return type

Tuple

annual_metrics_to_folder(target_folder: str, threshold: float = 300, min_t: float = 100, max_t: float = 3000, states: Optional[DynamicSchedule] = None, grids_filter: str = '*')[source]

Calculate and write multiple annual daylight metrics to a folder.

This method will calculate the following metrics:

  • Daylight autonomy

  • Continuous daylight autonomy

  • Useful daylight illuminance

  • Lower than useful daylight illuminance

  • Higher than useful daylight illuminance

Parameters

  • target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

  • threshold – Threshold value for daylight autonomy. Defaults to 300.

  • min_t – Minimum threshold for useful daylight illuminance. Defaults to 100.

  • max_t – Maximum threshold for useful daylight illuminance. Defaults to 3000.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

annual_sunlight_exposure(direct_threshold: float = 1000, occ_hours: int = 250, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[float64], List[ndarray], List[dict]][source]

Calculate annual sunlight exposure.

Parameters

  • direct_threshold – The threshold that determines if a sensor is overlit. Defaults to 1000.

  • occ_hours – The number of occupied hours that cannot receive more than the direct_threshold. Defaults to 250.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the annual sunlight exposure, the number of

hours that exceeds the direct threshold for each sensor, and grid information.

Return type

Tuple

annual_sunlight_exposure_to_folder(target_folder: str, direct_threshold: float = 1000, occ_hours: int = 250, states: Optional[DynamicSchedule] = None, grids_filter: str = '*')[source]

Calculate and write annual sunlight exposure to a folder.

Parameters

  • direct_threshold – The threshold that determines if a sensor is overlit. Defaults to 1000.

  • occ_hours – The number of occupied hours that cannot receive more than the direct_threshold. Defaults to 250.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

annual_uniformity_ratio(threshold: float = 0.5, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[float], List[HourlyContinuousCollection], List[dict]][source]

Calculate annual uniformity ratio.

Parameters

  • threshold – A threshold for the uniformity ratio. Defaults to 0.5.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the annual uniformity ratio, annual

data collections, and grid information.

Return type

Tuple

annual_uniformity_ratio_to_folder(target_folder: str, threshold: float = 0.5, states: Optional[DynamicSchedule] = None, grids_filter: str = '*')[source]

Calculate annual uniformity ratio and write it to a folder.

Parameters

  • target_folder – Folder path to write annual uniformity ratio in.

  • threshold – A threshold for the uniformity ratio. Defaults to 0.5.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the daylight autonomy and grid information.

Return type

Tuple

average_values(hoys: list = [], states: Optional[DynamicSchedule] = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get average values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period.

Parameters

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with the average value for each sensor and grid information.

Return type

Tuple

average_values_to_folder(target_folder: str, hoys: list = [], states: Optional[DynamicSchedule] = None, grids_filter: str = '*', res_type: str = 'total')

Get average values for each sensor over a given period and write the values to a folder.

Parameters

  • target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

continuous_daylight_autonomy(threshold: float = 300, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[ndarray], List[dict]][source]

Calculate continuous daylight autonomy.

Parameters

  • threshold – Threshold value for daylight autonomy. Defaults to 300.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the continuous daylight autonomy and grid

information.

Return type

Tuple

cumulative_values(hoys: list = [], states: Optional[DynamicSchedule] = None, t_step_multiplier: float = 1, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get cumulative values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period.

Parameters

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • t_step_multiplier – A value that will be multiplied with the timestep.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with the cumulative value for each sensor and grid

information.

Return type

Tuple

cumulative_values_to_folder(target_folder: str, hoys: list = [], states: Optional[DynamicSchedule] = None, t_step_multiplier: float = 1, grids_filter: str = '*', res_type: str = 'total')

Get cumulative values for each sensor over a given period and write the values to a folder.

Parameters

  • target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • t_step_multiplier – A value that will be multiplied with the timestep.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

daylight_autonomy(threshold: float = 300, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[ndarray], List[dict]][source]

Calculate daylight autonomy.

Parameters

  • threshold – Threshold value for daylight autonomy. Defaults to 300.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the daylight autonomy and grid information.

Return type

Tuple

daylight_control_schedules(states: Optional[DynamicSchedule] = None, grids_filter: str = '*', base_schedule: Optional[list] = None, ill_setpoint: float = 300, min_power_in: float = 0.3, min_light_out: float = 0.2, off_at_min: bool = False) → Tuple[List[ndarray], List[dict]][source]

Generate electric lighting schedules from annual daylight results.

Such controls will dim the lights according to whether the illuminance values at the sensor locations are at a target illuminance setpoint. The results can be used to account for daylight controls in energy simulations.

This function will generate one schedule per sensor grid in the simulation. Each grid should have sensors at the locations in space where daylight dimming sensors are located. Grids with one, two, or more sensors can be used to model setups where fractions of each room are controlled by different sensors. If the sensor grids are distributed over the entire floor of the rooms, the resulting schedules will be idealized, where light dimming has been optimized to supply the minimum illuminance setpoint everywhere in the room.

Parameters

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • base_schedule – A list of 8760 fractional values for the lighting schedule representing the usage of lights without any daylight controls. The values of this schedule will be multiplied by the hourly dimming fraction to yield the output lighting schedules. If None, a schedule from 9AM to 5PM on weekdays will be used. (Default: None).

  • ill_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 that need illumination).

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

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

  • min_power_in – 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_out – 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. Note that setting this to 1 means lights aren’t dimmed at all until the illuminance setpoint is reached. This can be used to approximate manual light-switching behavior when used in conjunction with the off_at_min input below. (Default: 0.2).

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

Returns

A tuple with two values.

  • schedules: A list of lists where each sub-list represents an electric lighting dimming schedule for a sensor grid.

  • grids_info: A list of grid information.

daylight_control_schedules_to_folder(target_folder: str, states: Optional[DynamicSchedule] = None, grids_filter: str = '*', base_schedule: Optional[list] = None, ill_setpoint: float = 300, min_power_in: float = 0.3, min_light_out: float = 0.2, off_at_min: bool = False)[source]

Generate electric lighting schedules from annual daylight results and write the schedules to a folder.

Such controls will dim the lights according to whether the illuminance values at the sensor locations are at a target illuminance setpoint. The results can be used to account for daylight controls in energy simulations.

This function will generate one schedule per sensor grid in the simulation. Each grid should have sensors at the locations in space where daylight dimming sensors are located. Grids with one, two, or more sensors can be used to model setups where fractions of each room are controlled by different sensors. If the sensor grids are distributed over the entire floor of the rooms, the resulting schedules will be idealized, where light dimming has been optimized to supply the minimum illuminance setpoint everywhere in the room.

Parameters

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • base_schedule – A list of 8760 fractional values for the lighting schedule representing the usage of lights without any daylight controls. The values of this schedule will be multiplied by the hourly dimming fraction to yield the output lighting schedules. If None, a schedule from 9AM to 5PM on weekdays will be used. (Default: None).

  • ill_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 that need illumination).

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

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

  • min_power_in – 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_out – 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. Note that setting this to 1 means lights aren’t dimmed at all until the illuminance setpoint is reached. This can be used to approximate manual light-switching behavior when used in conjunction with the off_at_min input below. (Default: 0.2).

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

median_values(hoys: list = [], states: Optional[dict] = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get median values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period. If hoys is left empty the median values will likely be 0 since there are likely more sun down hours than sun up hours.

Parameters

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with the median value for each sensor and grid information.

Return type

Tuple

median_values_to_folder(target_folder: str, hoys: list = [], states: Optional[dict] = None, grids_filter: str = '*', res_type: str = 'total')

Get median values for each sensor over a given period and write the values to a folder.

Parameters

  • target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

peak_values(hoys: list = [], states: Optional[DynamicSchedule] = None, grids_filter: str = '*', coincident: bool = False, res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get peak values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period.

Parameters

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • coincident – Boolean to indicate whether output values represent the peak value for each sensor throughout the entire analysis (False) or they represent the highest overall value across each sensor grid at a particular timestep (True). Defaults to False.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with the peak value for each sensor and grid information.

Return type

Tuple

peak_values_to_folder(target_folder: str, hoys: list = [], states: Optional[DynamicSchedule] = None, grids_filter: str = '*', coincident: bool = False, res_type='total')

Get peak values for each sensor over a given period and write the values to a folder.

Parameters

  • target_folder – Folder path to write peak values in. Usually this folder is called ‘metrics’.

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids.

  • coincident – Boolean to indicate whether output values represent the peak value for each sensor throughout the entire analysis (False) or they represent the highest overall value across each sensor grid at a particular timestep (True). Defaults to False.

  • res_type – Type of results to load. Defaults to ‘total’.

point_in_time(datetime: Union[float, DateTime], states: Optional[DynamicSchedule] = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get point in time values.

Parameters

  • datetime – Hour of the year as a float or DateTime object.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with point in time values and grid information.

Return type

Tuple

point_in_time_to_folder(target_folder: str, datetime: Union[float, DateTime], states: Optional[DynamicSchedule] = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get point in time values and write the values to a folder.

Parameters

  • target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

  • datetime – Hour of the year as a float or DateTime object.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with point in time values and grid information.

Return type

Tuple

spatial_daylight_autonomy(threshold: float = 300, target_time: float = 50, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[float64], List[dict]][source]

Calculate spatial daylight autonomy.

Note: This component will only output a LEED compliant sDA if you’ve run the simulation with blinds and blinds schedules as per the IES-LM-83-12. Use the states option to calculate a LEED compliant sDA.

Parameters

  • threshold – Threshold value for daylight autonomy. Defaults to 300.

  • target_time – A minimum threshold of occupied time (eg. 50% of the time), above which a given sensor passes and contributes to the spatial daylight autonomy. Defaults to 50.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the spatial daylight autonomy and grid

information.

Return type

Tuple

total(hoys: list = [], states: Optional[DynamicSchedule] = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get summed values for each sensor.

Parameters

  • hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

  • res_type – Type of results to load. Defaults to ‘total’.

Returns

A tuple with total values and grid information.

Return type

Tuple

useful_daylight_illuminance(min_t: float = 100, max_t: float = 3000, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[ndarray], List[dict]][source]

Calculate useful daylight illuminance.

Parameters

  • min_t – Minimum threshold for useful daylight illuminance. Defaults to 100.

  • max_t – Maximum threshold for useful daylight illuminance. Defaults to 3000.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the useful daylight illuminance and grid information.

Return type

Tuple

useful_daylight_illuminance_lower(min_t: float = 100, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[ndarray], List[dict]][source]

Calculate lower than useful daylight illuminance.

Parameters

  • min_t – Minimum threshold for useful daylight illuminance. Defaults to 100.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the lower than useful daylight illuminance and

grid information.

Return type

Tuple

useful_daylight_illuminance_upper(max_t: float = 3000, states: Optional[DynamicSchedule] = None, grids_filter: str = '*') → Tuple[List[ndarray], List[dict]][source]

Calculate higher than useful daylight illuminance.

Parameters

  • max_t – Maximum threshold for useful daylight illuminance. Defaults to 3000.

  • states – A dictionary of states. Defaults to None.

  • grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns

A tuple with the higher than useful daylight illuminance and

grid information.

Return type

Tuple

static values_to_annual(hours: Union[List[float], ndarray], values: Union[List[float], ndarray], timestep: int, study_hours: list, base_value: int = 0) → ndarray

Map a 1D NumPy array based on a set of hours to an annual array.

This method creates an array with a base value of length 8760 and replaces the base value with the input ‘values’ at the indices of the input ‘hours’.

Parameters

  • hours – A list of hours. This can be a regular list or a 1D NumPy array.

  • values – A list of values to map to an annual array. This can be a regular list or a 1D NumPy array.

  • timestep – Time step of the simulation.

  • study_hours – Study hours of the simulation.

  • base_value – A value that will be applied for all the base array.

Returns

A 1D NumPy array.

property arrays

Return a dictionary of all the NumPy arrays that have been loaded.

property datatype

Return a Ladybug DataType object.

property datetimes

Return DateTimes for sun up hours.

property default_states

Return default states as a dictionary.

property folder

Return full path to results folder as a string.

property grid_states

Return grid states as a dictionary.

property grids_info

Return grids information as list of dictionaries for each grid.

property light_paths

Return the identifiers of the light paths.

property occ_mask

Return an occupancy mask as a NumPy array that can be used to mask the results.

property occ_pattern

Return a filtered version of the annual schedule that only includes the sun-up-hours.

property schedule

Return schedule.

property study_hours

Return study hours as a list.

property sun_down_hours

Return sun down hours.

property sun_down_hours_mask

Return sun down hours masking array.

property sun_down_occ_hours

Return an integer for the number of occupied hours where the sun is down and there’s no possibility of being daylit or experiencing glare.

property sun_up_hours

Return sun up hours.

property sun_up_hours_mask

Return sun up hours masking array.

property timestep

Return timestep as an integer.

property total_occ

Return an integer for the total occupied hours of the schedule.

property unit

Return unit of hourly values.

property valid_states

Return a dictionary with valid states. Each light path is represented by a key-value pair where the light path identifier is the key and the value is a list of valid states, e.g., [0, 1, 2, …].