honeybee_plus.radiance.analysispoint module

class honeybee_plus.radiance.analysispoint.AnalysisPoint(location, direction)

Bases: object

A radiance analysis point.

location

Location of analysis points as (x, y, z).

direction

Direction of analysis point as (x, y, z).

This class is developed to enable honeybee for running daylight control studies with dynamic shadings without going back to several files.

Each AnalysisPoint can load annual total and direct results for every state of each source assigned to it. As a result once can end up with a lot of data for a single point (8760 * sources * states for each source). The data are sorted as integers and in different lists for each source. There are several methods to set or get the data but if you’re interested in more details read the comments under __init__ to know how the data is stored.

In this class:

• Id stands for ‘the id of a blind state’. Each state has a name and an ID will be assigned to it based on the order of loading.

• coupledValue stands for a tuple of (total, direct) values. If one the values is not available it will be set to None.

ToString()

Overwrite .NET ToString.

annual_metrics(da_threshhold=None, udi_min_max=None, blinds_state_ids=None, occ_schedule=None)

Calculate annual metrics.

Daylight autonomy, continious daylight autonomy and useful daylight illuminance.

Parameters

• da_threshhold – Threshhold for daylight autonomy in lux (default: 300).

• udi_min_max – A tuple of min, max value for useful daylight illuminance (default: (100, 2000)).

• blinds_state_ids – List of state ids for all the sources for input hoys. If you want a source to be removed set the state to -1.

• occ_schedule – An annual occupancy schedule (default: Office Schedule).

Returns

Daylight autonomy, Continuous daylight autonomy, Useful daylight illuminance, Less than UDI, More than UDI

annual_sunlight_exposure(threshhold=None, blinds_state_ids=None, occ_schedule=None, target_hours=None)

Annual Solar Exposure (ASE).

Calculate number of hours that this point is exposed to more than 1000lux of direct sunlight. The point meets the target in the number of hours is less than 250 hours per year.

Parameters

• threshhold – Threshhold for daylight autonomy in lux (default: 1000).

• blinds_state_ids – List of state ids for all the sources for input hoys. If you want a source to be removed set the state to -1. ase must be calculated without dynamic blinds but you can use this option to study the effect of different blind states.

• occ_schedule – An annual occupancy schedule.

• target_hours – Target minimum hours (default: 250).

Returns

Success as a Boolean, Number of hours, Problematic hours

blind_state_id(source, state)

Get state id if available.

blinds_state(hoys=None, blinds_state_ids=None, *args, **kwargs)

Calculte blinds state based on a control logic.

Overwrite self.logic to overwrite the logic for this point.

Parameters

• hoys – List of hours of year. If None default is self.hoys.

• blinds_state_ids – List of state ids for all the sources for an hour. If you want a source to be removed set the state to -1. If not provided a longest combination of states from sources (window groups) will be used. Length of each item in states should be equal to number of sources.

• args – Additional inputs for self.logic. args will be passed to self.logic

• kwargs – Additional inputs for self.logic. kwargs will be passed to self.logic

combined_value_by_id(hoy, blinds_state_ids=None)

Get combined value from all sources based on state_id.

Parameters

• hoy – hour of the year.

• blinds_state_ids – List of state ids for all the sources for an hour. If you want a source to be removed set the state to -1.

Returns

total, direct values.

combined_values_by_id(hoys=None, blinds_state_ids=None)

Get combined value from all sources based on state_id.

Parameters

• hoys – A collection of hours of the year.

• blinds_state_ids – List of state ids for all the sources for input hoys. If you want a source to be removed set the state to -1.

Returns

Return a generator for (total, direct) values.

coupled_value(hoy, source=None, state=None)

Get total and direct values for an hoy.

coupled_value_by_id(hoy, source_id=None, state_id=None)

Get total and direct values for an hoy.

coupled_values(hoys=None, source=None, state=None)

Get total and direct values for several hours of year.

coupled_values_by_id(hoys=None, source_id=None, state_id=None)

Get total and direct values for several hours of year by source id.

Use this method to load the values if you have the ids for source and state.

Parameters

• hoys – A collection of hoys.

• source_id – Id of source as an integer (default: 0).

• state_id – Id of state as an integer (default: 0).

daylight_autonomy(da_threshhold=None, blinds_state_ids=None, occ_schedule=None)

Calculate daylight autonomy and continuous daylight autonomy.

Parameters

• da_threshhold – Threshhold for daylight autonomy in lux (default: 300).

• blinds_state_ids – List of state ids for all the sources for input hoys. If you want a source to be removed set the state to -1.

• occ_schedule – An annual occupancy schedule.

Returns

Daylight autonomy, Continuos daylight autonomy

property details

Human readable details.

direct_value(hoy, source=None, state=None)

Get direct value for an hour of the year.

direct_values(hoys=None, source=None, state=None)

Get direct values for several hours of the year.

property direction

Direction of analysis points as Point3.

duplicate()

Duplicate the analysis point.

classmethod from_json(ap_json)

Create an analysis point from json object. {“location”: [x, y, z], “direction”: [x, y, z]}

classmethod from_raw_values(x, y, z, x1, y1, z1)

Create an analysis point from 6 values.

x, y, z are the location of the point and x1, y1 and z1 is the direction.

property has_direct_values

Check if direct values are loaded for this point.

In some cases and based on the recipe only total values are available.

property has_values

Check if this point has results values.

property hoys

Return hours of the year for results if any.

property location

Location of analysis points as Point3.

logic

property longest_state_ids

Get longest combination between blind states as blinds_state_ids.

max_values_by_id(hoys=None, blinds_state_ids=None)

Get maximum value for all the hours.

Parameters

• hoys – A collection of hours of the year.

• blinds_state_ids – List of state ids for all the sources for input hoys. If you want a source to be removed set the state to -1.

Returns

Return a tuple for sum of (total, direct) values.

property moys

Return minutes of the year for results if any.

static parse_blind_states(blinds_state_ids)

Parse input blind states.

The method tries to convert each state to a tuple of a list. Use this method to parse the input from plugins.

Parameters

blinds_state_ids – List of state ids for all the sources for an hour. If you want a source to be removed set the state to -1. If not provided a longest combination of states from sources (window groups) will be used. Length of each item in states should be equal to number of sources.

set_coupled_value(value, hoy, source=None, state=None)

Set both total and direct values for a specific hour of the year.

Parameters

• value – Value as as tuples (total, direct).

• hoy – The hour of the year that corresponds to this value.

• source – Name of the source of light. Only needed in case of multiple sources / window groups (default: None).

• state – State of the source if any (default: None).

set_coupled_values(values, hoys, source=None, state=None)

Set total and direct values for several hours of the year.

Parameters

• values – List of values as tuples (total, direct).

• hoys – List of hours of the year that corresponds to input values.

• source – Name of the source of light. Only needed in case of multiple sources / window groups (default: None).

• state – State of the source if any (default: None).

set_value(value, hoy, source=None, state=None, is_direct=False)

Set value for a specific hour of the year.

Parameters

• value – Value as a number.

• hoy – The hour of the year that corresponds to this value.

• source – Name of the source of light. Only needed in case of multiple sources / window groups (default: None).

• state – State of the source if any (default: None).

• is_direct – Set to True if the value is direct contribution of sunlight.

set_values(values, hoys, source=None, state=None, is_direct=False)

Set values for several hours of the year.

Parameters

• values – List of values as numbers.

• hoys – List of hours of the year that corresponds to input values.

• source – Name of the source of light. Only needed in case of multiple sources / window groups (default: None).

• state – State of the source if any (default: None).

• is_direct – Set to True if the value is direct contribution of sunlight.

source_id(source)

Get source id from source name.

property sources

Get sorted list of light sources.

In most of the cases light sources are window groups.

property states

Get list of states names for each source.

sum_values_by_id(hoys=None, blinds_state_ids=None)

Get sum of value for all the hours.

This method is mostly useful for radiation and solar access analysis.

Parameters

• hoys – A collection of hours of the year.

• blinds_state_ids – List of state ids for all the sources for input hoys. If you want a source to be removed set the state to -1.

Returns

Return a tuple for sum of (total, direct) values.

to_json()

Create an analysis point from json object. {“location”: [x, y, z], “direction”: [x, y, z]}

to_rad_string()

Return Radiance string for a test point.

unload()

Unload values and sources.

useful_daylight_illuminance(udi_min_max=None, blinds_state_ids=None, occ_schedule=None)

Calculate useful daylight illuminance.

Parameters

• udi_min_max – A tuple of min, max value for useful daylight illuminance (default: (100, 2000)).

• blinds_state_ids – List of state ids for all the sources for input hoys. If you want a source to be removed set the state to -1.

• occ_schedule – An annual occupancy schedule.

Returns

Useful daylight illuminance, Less than UDI, More than UDI

value(hoy, source=None, state=None)

Get total value for an hour of the year.

values(hoys=None, source=None, state=None)

Get values for several hours of the year.