honeybee_plus.radiance.analysisgrid module

Honeybee PointGroup and TestPointGroup.

class honeybee_plus.radiance.analysisgrid.AnalysisGrid(analysis_points, name=None, window_groups=None)[source]

Bases: object

A grid of analysis points.

analysis_points

A collection of analysis points.

ToString()[source]

Overwrite ToString .NET method.

add_result_files(file_path, hoys, start_line=None, is_direct=False, header=True, mode=0)[source]

Add new result files to grid.

Use this methods if you want to get annual metrics without loading the values for each point. This method is only useful for cases with no window groups and dynamic blind states. After adding the files you can call ‘annualMetrics’ method.

property analysis_points

Return a list of analysis points.

annual_metrics(da_threshhold=None, udi_min_max=None, blinds_state_ids=None, occ_schedule=None)[source]

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, 3000)).

  • 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, Continious 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, target_area=None)[source]

Annual Solar Exposure (ASE)

As per IES-LM-83-12 ase is the percent of sensors that are found to be exposed to more than 1000lux of direct sunlight for more than 250hrs per year. For LEED credits No more than 10% of the points in the grid should fail this measure.

Parameters

  • threshhold – Threshhold for for solar exposure 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 – Minimum targe hours for each point (default: 250).

  • target_area – Minimum target area percentage for this grid (default: 10).

Returns

Success as a Boolean, ase values for each point, Percentage area, Problematic points, Problematic hours for each point

combined_value_by_id(hoy=None, blinds_state_ids=None)[source]

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

Get combined value from all sources based on state_ids.

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.

property digit_sign
duplicate()[source]

Duplicate AnalysisGrid.

classmethod from_file(file_path, start_line=None, end_line=None)[source]

Create an analysis grid from a pts file.

Parameters

  • file_path – Full path to points file

  • start_line – Start line (default: 0)

  • end_line – End line as an integer (default: last line in file)

classmethod from_json(ag_json)[source]

Create an analysis grid from json objects.

classmethod from_points_and_vectors(points, vectors=None, name=None, window_groups=None)[source]

Create an analysis grid from points and vectors.

Parameters

  • points – A flatten list of (x, y ,z) points.

  • vectors – An optional list of (x, y, z) for direction of test points. If not provided a (0, 0, 1) vector will be assigned.

property has_direct_values

Check if direct values are available for this point.

In point-in-time and 3phase recipes only total values are available.

property has_values

Check if this analysis grid has result values.

property hoys

Return hours of the year for results if any.

property isAnalysisGrid

Return True for AnalysisGrid.

property is_results_point_in_time

Return True if the grid has the results only for an hour.

load_values_from_files()[source]

Load grid values from self.result_files.

max_values_by_id(hoys=None, blinds_state_ids=None)[source]

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 name

AnalysisGrid name.

parse_blind_states(blinds_state_ids)[source]

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.

parse_header(inf, start_line, hoys, check_point_count=False)[source]

Parse radiance matrix header.

property points

A generator of points as x, y, z.

property result_files

Return result files as a list [[total files], [direct files]].

set_coupled_values_from_file(total_file_path, direct_file_path, hoys=None, source=None, state=None, start_line=None, header=True, check_point_count=True, mode=0)[source]

Load direct and total values for test points from two files.

Parameters

  • file_path – Full file path to the result file.

  • hoys – A collection of hours of the year for the results. If None the default will be range(0, len(results)).

  • source – Name of the source.

  • state – Name of the state.

  • start_line – Number of start lines after the header from 0 (default: 0).

  • header – A Boolean to declare if the file has header (default: True).

  • mode – 0 > load the values 1 > load values as binary. Any non-zero value will be 1. This is useful for studies such as sunlight hours. 2 > load the values divided by mode number. Use this mode for daylight factor or radiation analysis.

set_values(hoys, values, source=None, state=None, is_direct=False)[source]
set_values_from_file(file_path, hoys=None, source=None, state=None, start_line=None, is_direct=False, header=True, check_point_count=True, mode=0)[source]

Load values for test points from a file.

Parameters

  • file_path – Full file path to the result file.

  • hoys – A collection of hours of the year for the results. If None the default will be range(0, len(results)).

  • source – Name of the source.

  • state – Name of the state.

  • start_line – Number of start lines after the header from 0 (default: 0).

  • is_direct – A Boolean to declare if the results is direct illuminance (default: False).

  • header – A Boolean to declare if the file has header (default: True).

  • mode –

    0 > load the values 1 > load values as binary. Any non-zero value

    will be 1. This is useful for studies such as sunlight hours.

    2 or Greater > Load results divided by mode value, which can be 2 or

    any other value larger than 2. Use this mode for daylight factor or radiation analysis. e.g. For daylight factor that you run an illuminance study under an overcast sky with total horizontal illuminance of 10000 lux. Now to get daylight factor you should divide the values by 100 ( 10000 / 100). In that case you can use mode = 100 to get the correct values.

property sources

Get sorted list fo sources.

spatial_daylight_autonomy(da_threshhold=None, target_da=None, blinds_state_ids=None, occ_schedule=None)[source]

Calculate Spatial Daylight Autonomy (sDA).

Parameters

  • da_threshhold – Minimum illuminance threshhold for daylight (default: 300).

  • target_da – Minimum threshhold for daylight autonomy in percentage (default: 50%).

  • 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

Spatial daylight autonomy as percentage of analysis points. DA: Daylight autonomy for each analysis point. Problematic points: List of problematic points.

Return type

sDA

sum_values_by_id(hoys=None, blinds_state_ids=None)[source]

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 collection of sum values as (total, direct) values.

to_json()[source]

Create json object from analysisGrid.

to_rad_string()[source]

Return analysis points group as a Radiance string.

unload()[source]

Remove all the sources and values from analysis_points.

property vectors

Get generator of vectors as x, y , z.

property window_groups

A list of window group names that are related to this analysis grid.

write(folder, filename=None, mkdir=False)[source]

write analysis grid to file.