honeybee-grasshopper-radiance 1.35.1__py3-none-any.whl

honeybee_grasshopper_radiance/src/HB Annual Daylight Metrics.py

@@ -0,0 +1,209 @@
+# Honeybee: A Plugin for Environmental Analysis (GPL)
+# This file is part of Honeybee.
+#
+# Copyright (c) 2025, Ladybug Tools.
+# You should have received a copy of the GNU Affero General Public License
+# along with Honeybee; If not, see <http://www.gnu.org/licenses/>.
+# 
+# @license AGPL-3.0-or-later <https://spdx.org/licenses/AGPL-3.0-or-later>
+
+"""
+Calculate Annual Daylight Metrics from a result (.ill) files.
+
+-
+    Args:
+        _results: An list of annual Radiance result files from the "HB Annual Daylight"
+            component (containing the .ill files and the sun-up-hours.txt).
+            This can also be just the path to the folder containing these
+            result files.
+        dyn_sch_: Optional dynamic Aperture Group Schedules from the "HB Aperture Group
+            Schedule" component, which will be used to customize the behavior
+            of any dyanmic aperture geometry in the output metrics. If unsupplied,
+            all dynamic aperture groups will be in their default state in for
+            the output metrics.
+        _occ_sch_: An annual occupancy schedule as a Ladybug Data Collection or a HB-Energy
+            schedule object. This can also be the identifier of a schedule in
+            your HB-Energy schedule library. Any value in this schedule that is
+            0.1 or above will be considered occupied. If None, a schedule from
+            8AM to 6PM on all days will be used.
+        _threshold_: Threshhold for daylight autonomy (DA) in lux (default: 300).
+        _min_max_: A list for min, max illuminacne thresholds for useful daylight illuminance
+            in lux. (Default: (100, 3000)).
+        grid_filter_: The name of a grid or a pattern to filter the grids. For instance,
+            first_floor_* will simulate only the sensor grids that have an
+            identifier that starts with first_floor_. By default all the grids
+            will be processed.
+
+    Returns:
+        report: Reports, errors, warnings, etc.
+        DA: Daylight autonomy results in percent. DA is the percentage of occupied hours
+            that each sensor recieves equal or more than the illuminance threshold.
+            Each value is for a different sensor of the grid. These can be plugged
+            into the "LB Spatial Heatmap" component along with meshes of the sensor
+            grids to visualize results. These can also be connected to the "HB
+            Spatial Daylight Autonomy" component to compute spatial daylight
+            autonomy for each grid.
+        cDA: Continuous daylight autonomy results in percent. cDA is similar to DA except
+            that values below the illuminance threshold can still count partially
+            towards the final percentage. Each value is for a different
+            sensor of the grid. These can be plugged into the "LB Spatial Heatmap"
+            component along with meshes of the sensor grids to visualize results.
+        UDI: Useful daylight illuminance results in percent. UDI is the percentage of time
+            that illuminace falls between minimum and maximum thresholds. Each value
+            is for a different sensor of the grid. These can be plugged into the
+            "LB Spatial Heatmap" component along with meshes of the sensor grids
+            to visualize results.
+        UDI_low: Results for the percent of time that is below the lower threshold
+            of useful daylight illuminance in percent. Each value is for a different
+            sensor of the grid. These can be plugged into the "LB Spatial Heatmap"
+            component along with meshes of the sensor grids to visualize results.
+        UDI_up: Results for the percent of time that is above the upper threshold
+            of useful daylight illuminance in percent. Each value is for a different
+            sensor of the grid. These can be plugged into the "LB Spatial Heatmap"
+            component along with meshes of the sensor grids to visualize results.
+"""
+
+ghenv.Component.Name = "HB Annual Daylight Metrics"
+ghenv.Component.NickName = 'DaylightMetrics'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '4 :: Results'
+ghenv.Component.AdditionalHelpFromDocStrings = '1'
+
+import os
+import subprocess
+
+try:
+    from ladybug.datacollection import BaseCollection
+    from ladybug.futil import write_to_file
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug:\n\t{}'.format(e))
+
+try:
+    from honeybee.config import folders
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee:\n\t{}'.format(e))
+
+try:
+    from honeybee_radiance.postprocess.annualdaylight import metrics_from_folder
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee_radiance:\n\t{}'.format(e))
+
+try:
+    from honeybee_radiance_postprocess.dynamic import DynamicSchedule
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee_radiance:\n\t{}'.format(e))
+
+try:
+    from honeybee_energy.lib.schedules import schedule_by_identifier
+except ImportError as e:  # honeybee schedule library is not available
+    schedule_by_identifier = None
+
+try:
+    from pollination_handlers.outputs.daylight import read_da_from_folder, \
+        read_cda_from_folder, read_udi_from_folder
+except ImportError as e:
+    raise ImportError('\nFailed to import pollination_handlers:\n\t{}'.format(e))
+
+try:
+    from ladybug_rhino.grasshopper import all_required_inputs, list_to_data_tree,   \
+        give_warning
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component):
+    # set default values for the thresholds and the grid filter
+    grid_filter_ = '*' if grid_filter_ is None else grid_filter_
+    _threshold_ = _threshold_ if _threshold_ else 300
+    if len(_min_max_) != 0:
+        assert len(_min_max_), 'Expected two values for _min_max_.'
+        min_t = _min_max_[0]
+        max_t = _min_max_[1]
+    else:
+        min_t = 100
+        max_t = 3000
+
+    # process the schedule
+    if _occ_sch_ is None:
+        schedule = None
+    elif isinstance(_occ_sch_, BaseCollection):
+        schedule = _occ_sch_.values
+    elif isinstance(_occ_sch_, str):
+        if schedule_by_identifier is not None:
+            try:
+                schedule = schedule_by_identifier(_occ_sch_).values()
+            except TypeError:  # it's probably a ScheduleFixedInterval
+                schedule = schedule_by_identifier(_occ_sch_).values
+        else:
+            raise ValueError('honeybee-energy must be installed to reference '
+                             'occupancy schedules by identifier.')
+    else:  # assume that it is a honeybee schedule object
+        try:
+            schedule = _occ_sch_.values()
+        except TypeError:  # it's probably a ScheduleFixedInterval
+            schedule = _occ_sch_.values
+    if schedule is not None:
+        bin_schedule = []
+        for val in schedule:
+            bin_val = 1 if val >= 0.1 else 0
+            bin_schedule.append(bin_val)
+        schedule = bin_schedule
+
+    # compute the annual metrics
+    res_folder = os.path.dirname(_results[0]) if os.path.isfile(_results[0]) \
+        else _results[0]
+    if os.path.isdir(os.path.join(res_folder, '__static_apertures__')) or \
+            os.path.isfile(os.path.join(res_folder, 'grid_states.json')):
+        cmds = [
+            folders.python_exe_path, '-m', 'honeybee_radiance_postprocess',
+            'post-process', 'annual-daylight', res_folder, '-sf', 'metrics',
+            '-t', str(_threshold_), '-lt', str(min_t), '-ut', str(max_t)
+        ]
+        if grid_filter_ != '*':
+            cmds.extend(['--grids-filter', grid_filter_])
+        if len(dyn_sch_) != 0:
+            if os.path.isfile(os.path.join(res_folder, 'grid_states.json')):
+                dyn_sch = dyn_sch_[0] if isinstance(dyn_sch_[0], DynamicSchedule) else \
+                    DynamicSchedule.from_group_schedules(dyn_sch_)
+                dyn_sch_file = dyn_sch.to_json(folder=res_folder)
+                cmds.extend(['--states', dyn_sch_file])
+            else:
+                msg = 'No dynamic aperture groups were found in the Model.\n' \
+                    'The input dynamic schedules will be ignored.'
+                print(msg)
+                give_warning(ghenv.Component, msg)
+        if schedule is not None:
+            sch_str = '\n'.join(str(h) for h in schedule)
+            sch_file = os.path.join(res_folder, 'schedule.txt')
+            write_to_file(sch_file, sch_str)
+            cmds.extend(['--schedule', sch_file])
+        use_shell = True if os.name == 'nt' else False
+        custom_env = os.environ.copy()
+        custom_env['PYTHONHOME'] = ''
+        process = subprocess.Popen(
+            cmds, cwd=res_folder, shell=use_shell, env=custom_env,
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        stdout = process.communicate()  # wait for the process to finish
+        if stdout[-1] != '':
+            print(stdout[-1])
+            raise ValueError('Failed to compute annual daylight metrics.')
+        metric_dir = os.path.join(res_folder, 'metrics')
+        DA = list_to_data_tree(read_da_from_folder(os.path.join(metric_dir, 'da')))
+        cDA = list_to_data_tree(read_cda_from_folder(os.path.join(metric_dir, 'cda')))
+        UDI = list_to_data_tree(read_udi_from_folder(os.path.join(metric_dir, 'udi')))
+        UDI_low = list_to_data_tree(read_udi_from_folder(os.path.join(metric_dir, 'udi_lower')))
+        UDI_up = list_to_data_tree(read_udi_from_folder(os.path.join(metric_dir, 'udi_upper')))
+    else:
+        if len(dyn_sch_) != 0:
+            msg = 'Dynamic Schedules are currently only supported for Annual Daylight ' \
+                'simulations.\nThe input schedules will be ignored.'
+            print(msg)
+            give_warning(ghenv.Component, msg)
+        DA, cDA, UDI_low, UDI, UDI_up = metrics_from_folder(
+            res_folder, schedule, _threshold_, min_t, max_t, grid_filter_)
+        DA = list_to_data_tree(DA)
+        cDA = list_to_data_tree(cDA)
+        UDI = list_to_data_tree(UDI)
+        UDI_low = list_to_data_tree(UDI_low)
+        UDI_up = list_to_data_tree(UDI_up)

honeybee_grasshopper_radiance/src/HB Annual Daylight.py

@@ -0,0 +1,153 @@
+# Honeybee: A Plugin for Environmental Analysis (GPL)
+# This file is part of Honeybee.
+#
+# Copyright (c) 2025, Ladybug Tools.
+# You should have received a copy of the GNU Affero General Public License
+# along with Honeybee; If not, see <http://www.gnu.org/licenses/>.
+# 
+# @license AGPL-3.0-or-later <https://spdx.org/licenses/AGPL-3.0-or-later>
+
+"""
+Run an annual daylight study for a Honeybee model to compute hourly illuminance
+for each sensor in a model's sensor grids.
+_
+By default, this recipe uses an enhanced 2-phase method, which accurately models
+direct sun by tracing rays from each sensor to the solar position at each hour
+of the calculation. This makes the result suitable for computing Annual Sun
+Exposure (ASE) and for modeling the effects of dynamic shades and apertures.
+_
+When the enhanced_ option is set to False, a standard 2-phase method for simulation,
+which is much faster because it simply determines the relationship between each
+sensor and sky patch and then multiplies the value of each sky patch at each
+hour by the relationship coefficient. However, this means that the direct sun
+is spread out across a few sky patches, making it unsuitable for ASE.
+_
+The resulting illuminance is used to compute the following metrics:
+_
+* Daylight Autonomy (DA) - The percentage of occupied hours that each sensor
+        recieves more than the illuminance threshold.
+* Continuous Daylight Autonomy (cDA) - Similar to DA except that values below the
+        illuminance threshold can still count partially towards the final percentage.
+* Useful Daylight Illuminance (UDI) - The percentage of occupied hours that
+        illuminace falls between minimum and maximum thresholds
+
+-
+    Args:
+        _model: A Honeybee Model for which Annual Daylight will be simulated.
+            Note that this model must have grids assigned to it.
+        _wea: A Wea object produced from the Wea components that are under the Light
+            Sources tab. This can also be the path to a .wea or a .epw file.
+            Note that the Wea must have a timestep of 1 to be used with this
+            recipe.
+        north_: A number between -360 and 360 for the counterclockwise difference
+            between the North and the positive Y-axis in degrees. This can
+            also be Vector for the direction to North. (Default: 0).
+        _thresholds_: A string to change the threshold for daylight autonomy and useful
+            daylight illuminance. Valid keys are -t for daylight autonomy threshold,
+            -lt for the lower threshold for useful daylight illuminance and
+            -ut for the upper threshold. The order of the keys is not important
+            and you can include one or all of them. For instance if you only want
+            to change the upper threshold to 2000 lux you should use -ut 2000
+            as the input. (Default: -t 300 -lt 100 -ut 3000).
+        _schedule_: An annual occupancy schedule, either as a Ladybug Hourly Continuous
+            Data Collection or a HB-Energy schedule object. This can also be the
+            path to a CSV file with 8760 rows or the identifier of a schedule in
+            the honeybee-energy schedule library. Any value in this schedule
+            that is 0.1 or above will be considered occupied. If not provided,
+            a default schedule that runs from 8 AM to 6 PM on all days will be used.
+        grid_filter_: Text for a grid identifer or a pattern to filter the sensor grids of
+            the model that are simulated. For instance, first_floor_* will simulate
+            only the sensor grids that have an identifier that starts with
+            first_floor_. By default, all grids in the model will be simulated.
+        radiance_par_: Text for the radiance parameters to be used for ray
+            tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).
+        enhanced_: Boolean to note whether an enhanced version of the 2-phase ray tracing
+            simulation should be used, which will more accurately account for
+            direct sun at each time step. If False, only a 2-phase daylight
+            coefficient calculation with sky patches will be used, which is
+            much faster but spreads the direct sun out across a few sky
+            patches, making it unsuitable for ASE. (Default: True).
+        run_settings_: Settings from the "HB Recipe Settings" component that specify
+            how the recipe should be run. This can also be a text string of
+            recipe settings.
+        _run: Set to True to run the recipe and get results. This input can also be
+            the integer "2" to run the recipe silently.
+
+    Returns:
+        report: Reports, errors, warnings, etc.
+        results: Raw result files (.ill) that contain illuminance matrices for each sensor
+            at each hour of the simulation. These can be postprocessed using
+            various components under the 4::Results sub-tab.
+        DA: Daylight autonomy results in percent. DA is the percentage of occupied hours
+            that each sensor recieves equal or more than the illuminance threshold.
+            Each value is for a different sensor of the grid. These can be plugged
+            into the "LB Spatial Heatmap" component along with meshes of the sensor
+            grids to visualize results. These can also be connected to the "HB
+            Spatial Daylight Autonomy" component to compute spatial daylight
+            autonomy for each grid. Note that the resulting sDA is only compliant
+            with LEED if dynamic blinds have been simulated using the methods
+            in IES-LM-83-12.
+        cDA: Continuous daylight autonomy results in percent. cDA is similar to DA except
+            that values below the illuminance threshold can still count partially
+            towards the final percentage. Each value is for a different
+            sensor of the grid. These can be plugged into the "LB Spatial Heatmap"
+            component along with meshes of the sensor grids to visualize results.
+        UDI: Useful daylight illuminance results in percent. UDI is the percentage of
+            occupied hours that illuminace falls between minimum and maximum
+            thresholds. Each value is for a different sensor of the grid. These
+            can be plugged into the "LB Spatial Heatmap" component along with
+            meshes of the sensor grids to visualize results.
+        UDI_low: Results for the percent of time that is below the lower threshold
+            of useful daylight illuminance in percent. Each value is for a different
+            sensor of the grid. These can be plugged into the "LB Spatial Heatmap"
+            component along with meshes of the sensor grids to visualize results.
+        UDI_up: Results for the percent of time that is above the upper threshold
+            of useful daylight illuminance in percent. Each value is for a different
+            sensor of the grid. These can be plugged into the "LB Spatial Heatmap"
+            component along with meshes of the sensor grids to visualize results.
+"""
+
+ghenv.Component.Name = 'HB Annual Daylight'
+ghenv.Component.NickName = 'AnnualDaylight'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '3 :: Recipes'
+ghenv.Component.AdditionalHelpFromDocStrings = '1'
+
+try:
+    from lbt_recipes.recipe import Recipe
+except ImportError as e:
+    raise ImportError('\nFailed to import lbt_recipes:\n\t{}'.format(e))
+
+try:
+    from ladybug_rhino.grasshopper import all_required_inputs, recipe_result
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component) and _run:
+    # create the recipe and set the input arguments
+    recipe = Recipe('annual-daylight') if enhanced_ is False else \
+        Recipe('annual-daylight-enhanced')
+    recipe.input_value_by_name('model', _model)
+    recipe.input_value_by_name('wea', _wea)
+    recipe.input_value_by_name('north', north_)
+    recipe.input_value_by_name('thresholds', _thresholds_)
+    recipe.input_value_by_name('schedule', _schedule_)
+    recipe.input_value_by_name('grid-filter', grid_filter_)
+    recipe.input_value_by_name('radiance-parameters', radiance_par_)
+
+    # run the recipe
+    silent = True if _run > 1 else False
+    project_folder = recipe.run(run_settings_, radiance_check=True, silent=silent)
+
+    # load the results
+    try:
+        results = recipe_result(recipe.output_value_by_name('results', project_folder))
+        DA = recipe_result(recipe.output_value_by_name('da', project_folder))
+        cDA = recipe_result(recipe.output_value_by_name('cda', project_folder))
+        UDI = recipe_result(recipe.output_value_by_name('udi', project_folder))
+        UDI_low = recipe_result(recipe.output_value_by_name('udi-lower', project_folder))
+        UDI_up = recipe_result(recipe.output_value_by_name('udi-upper', project_folder))
+    except Exception:
+        raise Exception(recipe.failure_message(project_folder))

honeybee_grasshopper_radiance/src/HB Annual Glare Metrics.py

@@ -0,0 +1,137 @@
+# Honeybee: A Plugin for Environmental Analysis (GPL)
+# This file is part of Honeybee.
+#
+# Copyright (c) 2025, Ladybug Tools.
+# You should have received a copy of the GNU Affero General Public License
+# along with Honeybee; If not, see <http://www.gnu.org/licenses/>.
+# 
+# @license AGPL-3.0-or-later <https://spdx.org/licenses/AGPL-3.0-or-later>
+
+"""
+Calculate Annual Glare Metrics from result (.dgp) files.
+_
+Glare Autonmy is a metric describing the percentage of occupied
+hours that each sensor is below the glare threshold.
+_
+Spatial Glare Autonomy is a metric describing the percentage of the sensor grid
+that is free glare according to the glare threshold and the target time. The sGA
+value is expressed as a percentage of the sensors in the analysis grid.
+
+-
+    Args:
+        _results: An list of annual Radiance result files from the "HB Imageless Annual
+            Glare" component (containing the .dgp files and the sun-up-hours.txt).
+            This can also be just the path to the folder containing these result
+            files.
+        _occ_sch_: An annual occupancy schedule as a Ladybug Data Collection or a HB-Energy
+            schedule object. This can also be the identifier of a schedule in
+            your HB-Energy schedule library. Any value in this schedule that is
+            0.1 or above will be considered occupied. If None, a schedule from
+            8AM to 6PM on all days will be used.
+        _glare_thresh_: Threshold for glare autonomy (GA) in DGP (default: 0.4).
+        grid_filter_: The name of a grid or a pattern to filter the grids. For instance,
+            first_floor_* will simulate only the sensor grids that have an
+            identifier that starts with first_floor_. By default all the grids
+            will be processed.
+        _target_time_: A minimum threshold of occupied time (eg. 95% of the time), above
+            which a given sensor passes and contributes to the spatial glare
+            autonomy. (Default: 95%).
+
+    Returns:
+        report: Reports, errors, warnings, etc.
+        GA: Glare autonomy results in percent. GA is the percentage of occupied hours
+            that each sensor is free of glare according to the glare threshold.
+            Each value is for a different sensor of the grid. These can be plugged
+            into the "LB Spatial Heatmap" component along with meshes of the sensor
+            grids to visualize results.
+        sGA: Spatial glare autonomy as a percentage of the sensors for each analysis grid
+            that does not exceed the glare threshold for a specified fraction of
+            occupied hours, ie. the target time.
+        pass_fail: A data tree of zeros and ones, which indicate whether a given sensor
+            passes the criteria for being free of glare (1) or fails the criteria (0).
+            Being free of glare does not necessarily mean that the sensor is glare-free
+            for all hours, but that it is glare-free for a minimum percentage of
+            occupied hours defined by the target time. Each value is for a different
+            sensor of the grid. These can be plugged into the "LB Spatial Heatmap"
+            component along with meshes of the sensor grids to visualize results.
+"""
+
+ghenv.Component.Name = "HB Annual Glare Metrics"
+ghenv.Component.NickName = 'GlareMetrics'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '4 :: Results'
+ghenv.Component.AdditionalHelpFromDocStrings = '1'
+
+import os
+
+try:
+    from ladybug.datacollection import BaseCollection
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug:\n\t{}'.format(e))
+
+try:
+    from honeybee_radiance.postprocess.annualglare import glare_autonomy_from_folder
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee_radiance:\n\t{}'.format(e))
+
+try:
+    from honeybee_energy.lib.schedules import schedule_by_identifier
+except ImportError as e:  # honeybee schedule library is not available
+    schedule_by_identifier = None
+
+try:
+    from ladybug_rhino.grasshopper import all_required_inputs, list_to_data_tree, \
+        data_tree_to_list
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component):
+    # set default values for the thresholds and the grid filter
+    grid_filter_ = '*' if grid_filter_ is None else grid_filter_
+    _glare_thresh_ = _glare_thresh_ if _glare_thresh_ else 0.4
+
+    # process the schedule
+    if _occ_sch_ is None:
+        schedule = None
+    elif isinstance(_occ_sch_, BaseCollection):
+        schedule = _occ_sch_.values
+    elif isinstance(_occ_sch_, str):
+        if schedule_by_identifier is not None:
+            try:
+                schedule = schedule_by_identifier(_occ_sch_).values()
+            except TypeError:  # it's probably a ScheduleFixedInterval
+                schedule = schedule_by_identifier(_occ_sch_).values
+        else:
+            raise ValueError('honeybee-energy must be installed to reference '
+                             'occupancy schedules by identifier.')
+    else:  # assume that it is a honeybee schedule object
+        try:
+            schedule = _occ_sch_.values()
+        except TypeError:  # it's probably a ScheduleFixedInterval
+            schedule = _occ_sch_.values
+    if schedule is not None:
+        bin_schedule = []
+        for val in schedule:
+            bin_val = 1 if val >= 0.1 else 0
+            bin_schedule.append(bin_val)
+        schedule = bin_schedule
+
+    # compute the annual metrics
+    res_folder = os.path.dirname(_results[0]) if os.path.isfile(_results[0]) \
+        else _results[0]
+    GA = glare_autonomy_from_folder(
+        res_folder, schedule, _glare_thresh_, grid_filter_)
+    GA = list_to_data_tree(GA)
+
+    # process the input values into a readable format
+    ga_mtx = [item[-1] for item in data_tree_to_list(GA)]
+    _target_time_ = 95 if _target_time_ is None else _target_time_
+
+    # determine whether each point passes or fails
+    pass_fail = [[int(val > _target_time_) for val in grid] for grid in ga_mtx]
+
+    # compute spatial glare autonomy from the pass/fail results
+    sGA = [sum(pf_list) / len(pf_list) for pf_list in pass_fail]
+    pass_fail = list_to_data_tree(pass_fail)  # convert matrix to data tree

honeybee_grasshopper_radiance/src/HB Annual Irradiance.py

@@ -0,0 +1,112 @@
+# Honeybee: A Plugin for Environmental Analysis (GPL)
+# This file is part of Honeybee.
+#
+# Copyright (c) 2025, Ladybug Tools.
+# You should have received a copy of the GNU Affero General Public License
+# along with Honeybee; If not, see <http://www.gnu.org/licenses/>.
+# 
+# @license AGPL-3.0-or-later <https://spdx.org/licenses/AGPL-3.0-or-later>
+
+"""
+Run an annual irradiance study for a Honeybee model to compute hourly solar
+irradiance for each sensor in a model's sensor grids.
+_
+The fundamental calculation of this recipe is the same as that of "HB Annual
+Daylight" in that an enhaced 2-phase method is used to accurately account for
+direct sun at each simulation step. However, this recipe computes broadband
+solar irradiance in W/m2 instead of visible illuminance in lux.
+_
+Consequently, the average irradiance and cumulative radiation values produced from
+this recipe are more accurate than those produced by the "HB Cumulative Radiation"
+recipe. Furthermore, because the hourly irriadiance values are accurate, this
+recipe can be used to evaluate `peak_irradiance` and determine the worst-case
+solar loads over clear sky Weas that represent cooling design days.
+
+-
+    Args:
+        _model: A Honeybee Model for which Annual Irradiance will be simulated.
+            Note that this model must have grids assigned to it.
+        _wea: A Wea object produced from the Wea components that are under the Light
+            Sources tab. This can also be the path to a .wea or a .epw file.
+        _timestep_: An integer for the timestep of the inpput _wea. This value is used
+            to compute average irradiance and cumulative radiation. (Default: 1)
+        visible_: Boolean to indicate the type of irradiance output, which can be solar (False)
+            or visible (True). Note that the output values will still be
+            irradiance (W/m2) when "visible" is selected but these irradiance
+            values will be just for the visible portion of the electromagnetic
+            spectrum. The visible irradiance values can be converted into
+            illuminance by multiplying them by the Radiance luminous efficacy
+            factor of 179. (Default: False).
+        north_: A number between -360 and 360 for the counterclockwise difference
+            between the North and the positive Y-axis in degrees. This can
+            also be Vector for the direction to North. (Default: 0).
+        grid_filter_: Text for a grid identifer or a pattern to filter the sensor grids of
+            the model that are simulated. For instance, first_floor_* will simulate
+            only the sensor grids that have an identifier that starts with
+            first_floor_. By default, all grids in the model will be simulated.
+        radiance_par_: Text for the radiance parameters to be used for ray
+            tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).
+        run_settings_: Settings from the "HB Recipe Settings" component that specify
+            how the recipe should be run. This can also be a text string of
+            recipe settings.
+        _run: Set to True to run the recipe and get results. This input can also be
+            the integer "2" to run the recipe silently.
+
+    Returns:
+        report: Reports, errors, warnings, etc.
+        results: Raw result files (.ill) that contain matrices of irradiance in W/m2
+            for each time step of the wea.
+        res_direct: Raw result files (.ill) that contain irradiance matrices for just the
+            direct sun at each hour of the simulation. These can be postprocessed
+            using various components under the 4::Results sub-tab.
+        avg_irr: The average irradiance in W/m2 for each sensor over the Wea time period.
+        peak_irr: The highest irradiance value in W/m2 during the Wea time period. This
+            is suitable for assessing the worst-case solar load of clear skies on
+            cooling design days. It can also be used to determine the highest
+            radiant temperatures that occupants might experience in over the
+            time period of the Wea.
+        radiation: The cumulative radiation in kWh/m2 over the Wea time period.
+"""
+
+ghenv.Component.Name = 'HB Annual Irradiance'
+ghenv.Component.NickName = 'AnnualIrradiance'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '3 :: Recipes'
+ghenv.Component.AdditionalHelpFromDocStrings = '1'
+
+try:
+    from lbt_recipes.recipe import Recipe
+except ImportError as e:
+    raise ImportError('\nFailed to import lbt_recipes:\n\t{}'.format(e))
+
+try:
+    from ladybug_rhino.grasshopper import all_required_inputs, recipe_result
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component) and _run:
+    # create the recipe and set the input arguments
+    recipe = Recipe('annual-irradiance')
+    recipe.input_value_by_name('model', _model)
+    recipe.input_value_by_name('wea', _wea)
+    recipe.input_value_by_name('timestep', _timestep_)
+    recipe.input_value_by_name('output-type', visible_)
+    recipe.input_value_by_name('north', north_)
+    recipe.input_value_by_name('grid-filter', grid_filter_)
+    recipe.input_value_by_name('radiance-parameters', radiance_par_)
+
+    # run the recipe
+    silent = True if _run > 1 else False
+    project_folder = recipe.run(run_settings_, radiance_check=True, silent=silent)
+
+    # load the results
+    try:
+        results = recipe_result(recipe.output_value_by_name('results', project_folder))
+        res_direct = recipe_result(recipe.output_value_by_name('results-direct', project_folder))
+        avg_irr = recipe_result(recipe.output_value_by_name('average-irradiance', project_folder))
+        peak_irr = recipe_result(recipe.output_value_by_name('peak-irradiance', project_folder))
+        radiation = recipe_result(recipe.output_value_by_name('cumulative-radiation', project_folder))
+    except Exception:
+        raise Exception(recipe.failure_message(project_folder))