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

honeybee_grasshopper_radiance/src/HB Daylight Control Schedule.py

@@ -0,0 +1,211 @@
+# 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>
+
+"""
+Generate electric lighting schedules from annual daylight results, which can be
+used to account for daylight controls in energy simulations.
+_
+Such controls will dim the lights in the energy simulation according to whether
+the illuminance values at the sensor locations are at a target illuminance setpoint.
+_
+In addition to benefiting from the accuracy of Radiance, using this component has
+several advantages over the "HB Apply Daylight Control" component under HB-Energy.
+Notably, it can account for setups with multiple illuminance sensors.
+_
+This component 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.
+-
+
+    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.
+        _base_schedule_: A 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.
+            The format of this schedule can be a Ladybug Data Collection, a HB-Energy
+            schedule object, or the identifier of a schedule in the HB-Energy
+            schedule library. If None, a schedule from 8AM to 6PM on all days
+            will be used.
+        _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_ output 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:
+        report: Reports, errors, warnings, etc.
+        rooms: The input Rooms with simple daylight controls assigned to them.
+"""
+
+ghenv.Component.Name = 'HB Daylight Control Schedule'
+ghenv.Component.NickName = 'DaylightSchedule'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '4 :: Results'
+ghenv.Component.AdditionalHelpFromDocStrings = '1'
+
+import os
+import json
+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.electriclight import daylight_control_schedules
+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
+    from honeybee_energy.lib.scheduletypelimits import schedule_type_limit_by_identifier
+    from honeybee_energy.schedule.fixedinterval import ScheduleFixedInterval
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee_energy:\n\t{}'.format(e))
+
+try:
+    from ladybug_rhino.grasshopper import all_required_inputs, give_warning
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+def load_schedules_from_folder(folder):
+    """Load schedule values from a folder."""
+    info = os.path.join(folder, 'grids_info.json')
+    with open(info) as data_f:
+        data = json.load(data_f)
+    sch_vals, sch_ids = [], []
+    for grid in data:
+        res_file = os.path.join(folder, '{}.txt'.format(grid['full_id']))
+        with open(res_file) as res_f:
+            sch_vals.append([float(v) for v in res_f])
+            sch_ids.append('{} Daylight Control'.format(grid['full_id']))
+    return sch_vals, sch_ids
+
+
+if all_required_inputs(ghenv.Component):
+    # set default values for all controls
+    _ill_setpoint_ = 300 if _ill_setpoint_ is None else _ill_setpoint_
+    _min_power_in_ = 0.3 if _min_power_in_ is None else _min_power_in_
+    _min_light_out_ = 0.2 if _min_light_out_ is None else _min_light_out_
+    off_at_min_ = False if off_at_min_ is None else off_at_min_
+
+    # process the base schedule input into a list of values
+    if _base_schedule_ is None:
+        schedule = _base_schedule_
+    elif isinstance(_base_schedule_, BaseCollection):
+        schedule = _base_schedule_.values
+    elif isinstance(_base_schedule_, str):
+        schedule = schedule_by_identifier(_base_schedule_).values()
+    else:  # assume that it is a honeybee schedule object
+        try:
+            schedule = _base_schedule_.values()
+        except TypeError:  # it's probably a ScheduleFixedInterval
+            schedule = _base_schedule_.values
+    # get the relevant .ill files
+    res_folder = os.path.dirname(_results[0]) if os.path.isfile(_results[0]) \
+        else _results[0]
+
+    # check to see if results use the newer numpy arrays
+    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',
+            'schedule', 'control-schedules', res_folder,
+            '--ill-setpoint', str(_ill_setpoint_),
+            '--min-power-in', str(_min_power_in_),
+            '--min-light-out', str(_min_light_out_),
+            '--sub-folder', 'schedules'
+        ]
+        if _base_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(['--base-schedule-file', sch_file])
+        if off_at_min_:
+            cmds.append('--off-at-min')
+        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)
+        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 control schedule.')
+        cntrl_dir = os.path.join(res_folder, 'schedules', 'control_schedules')
+        if os.path.isdir(cntrl_dir):
+            sch_vals, sch_ids = load_schedules_from_folder(cntrl_dir)
+
+    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)
+        sch_vals, sch_ids = daylight_control_schedules(
+            res_folder, schedule, _ill_setpoint_, _min_power_in_, _min_light_out_, off_at_min_)
+
+    # create the schedule by combining the base schedule with the dimming fraction
+    type_limit = schedule_type_limit_by_identifier('Fractional')
+    schedules = []
+    for shc_val, sch_id in zip(sch_vals, sch_ids):
+        schedules.append(ScheduleFixedInterval(sch_id, shc_val, type_limit))

honeybee_grasshopper_radiance/src/HB Daylight Factor.py

@@ -0,0 +1,82 @@
+# 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 a daylight factor study for a Honeybee model.
+_
+Daylight Factor (DF) is defined as the ratio of the indoor daylight illuminance
+to outdoor illuminance under an unobstructed overcast sky. It is expressed as a
+percentage between 0 and 100.
+_
+Because daylight factor is computed using an overcast sky, it does not change
+with [North, East, South, West] orientation. As such, it is more suited to
+assessing daylight in climates where cloudy conditions are common. The "HB
+Annual Daylight" recipe yields a much more accurate assessment of daylight
+and is suitable for all climates, though it requires a significantly longer
+calculation time than Daylight Factor.
+
+-
+    Args:
+        _model: A Honeybee Model for which Daylight Factor will be simulated.
+            Note that this model should have grids assigned to it in order
+            to produce meaningfule results.
+        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 -aa 0.1 -ad 2048 -ar 64).
+        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: The daylight factor values from the simulation 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 Daylight Factor'
+ghenv.Component.NickName = 'DaylightFactor'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '3 :: Recipes'
+ghenv.Component.AdditionalHelpFromDocStrings = '3'
+
+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('daylight-factor')
+    recipe.input_value_by_name('model', _model)
+    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))
+    except Exception:
+        raise Exception(recipe.failure_message(project_folder))

honeybee_grasshopper_radiance/src/HB Deconstruct Modifier.py

@@ -0,0 +1,47 @@
+# 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>
+
+
+"""
+Deconstruct a modifier into a radiance string.
+-
+
+    Args:
+        _mod: A modifier to be deconstructed or text for a modifier to be looked
+            up in the modifier library.
+
+    Returns:
+        rad_str: A Radiance string that includes all of the attributes that
+            define the modifier.
+"""
+
+ghenv.Component.Name = 'HB Deconstruct Modifier'
+ghenv.Component.NickName = 'DecnstrMod'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '1 :: Modifiers'
+ghenv.Component.AdditionalHelpFromDocStrings = '0'
+
+
+try:  # import the honeybee-radiance dependencies
+    from honeybee_radiance.lib.modifiers import modifier_by_identifier
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee_radiance:\n\t{}'.format(e))
+
+try:  # import ladybug_rhino dependencies
+    from ladybug_rhino.grasshopper import all_required_inputs
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component):
+    # check the input
+    if isinstance(_mod, str):
+        _mod = modifier_by_identifier(_mod)
+    rad_str = _mod.to_radiance()

honeybee_grasshopper_radiance/src/HB Deconstruct ModifierSet Interior.py

@@ -0,0 +1,67 @@
+# 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>
+
+
+"""
+Deconstruct a modifier set into its constituient interior modifiers.
+-
+
+    Args:
+        _mod_set: A modifier set to be deconstructed. This can also be
+            text for a modifier set to be looked up in the modifier
+            set library.
+
+    Returns:
+        interior_wall: A modifier object for the set's interior walls.
+        ceiling: A modifier object for the set's interior roofs.
+        interior_floor: A modifier object for the set's interior floors.
+        interior_window: A modifier object for all apertures with a Surface
+            boundary condition.
+        interior_door: A modifier object for all opaque doors with a Surface
+            boundary condition.
+        int_glass_door: A modifier object for all glass doors with a Surface
+            boundary condition.
+        interior_shade: A modifier object for all interior shades.
+"""
+
+ghenv.Component.Name = 'HB Deconstruct ModifierSet Interior'
+ghenv.Component.NickName = 'DecnstrConstrSetInt'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '1 :: Modifiers'
+ghenv.Component.AdditionalHelpFromDocStrings = '5'
+
+
+try:  # import the honeybee-radiance dependencies
+    from honeybee_radiance.modifierset import ModifierSet
+    from honeybee_radiance.lib.modifiersets import modifier_set_by_identifier
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee_radiance:\n\t{}'.format(e))
+
+try:  # import ladybug_rhino dependencies
+    from ladybug_rhino.grasshopper import all_required_inputs
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component):
+    # check the input
+    if isinstance(_mod_set, str):
+        _mod_set = modifier_set_by_identifier(_mod_set)
+    else:
+        assert isinstance(_mod_set, ModifierSet), \
+            'Expected ModifierSet. Got {}.'.format(type(_mod_set))
+
+    interior_wall = _mod_set.wall_set.interior_modifier
+    ceiling = _mod_set.roof_ceiling_set.interior_modifier
+    interior_floor = _mod_set.floor_set.interior_modifier
+    interior_window = _mod_set.aperture_set.interior_modifier
+    interior_door = _mod_set.door_set.interior_modifier
+    int_glass_door = _mod_set.door_set.interior_glass_modifier
+    interior_shade = _mod_set.shade_set.interior_modifier

honeybee_grasshopper_radiance/src/HB Deconstruct ModifierSet.py

@@ -0,0 +1,80 @@
+# 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>
+
+
+"""
+Deconstruct a modifier set into its constituient exterior modifiers.
+-
+
+    Args:
+        _mod_set: A modifier set to be deconstructed. This can also be
+            text for a modifier set to be looked up in the modifier
+            set library.
+
+    Returns:
+        exterior_wall: A modifier object for the set's exterior walls.
+        exterior_roof: A modifier object for the set's exterior roofs.
+        exposed_floor: A modifier object for the set's exposed floors.
+        ground_wall: A modifier object for the set's underground walls.
+        ground_roof: A modifier object for the set's underground roofs.
+        ground_floor: A modifier object for the set's ground-contact floors.
+        window: A modifier object for apertures with an Outdoors boundary
+            condition and a Wall face type for their parent face.
+        skylight: A modifier object for apertures with an Outdoors boundary
+            condition and a RoofCeiling or Floor face type for their parent face.
+        operable: A modifier object for apertures with an Outdoors boundary
+            condition and True is_operable property.
+        exterior_door: A modifier object for opaque doors with an Outdoors
+            boundary condition and a Wall face type for their parent face.
+        overhead_door: A modifier object for opaque doors with an Outdoors
+            boundary condition and a RoofCeiling or Floor face type for their
+            parent face.
+        glass_door: A modifier object for all glass doors with an Outdoors
+            boundary condition.
+        exterior_shade: A modifier object for all exterior shades.
+"""
+
+ghenv.Component.Name = 'HB Deconstruct ModifierSet'
+ghenv.Component.NickName = 'DecnstrModSet'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '1 :: Modifiers'
+ghenv.Component.AdditionalHelpFromDocStrings = '5'
+
+
+try:  # import the honeybee-radiance dependencies
+    from honeybee_radiance.modifierset import ModifierSet
+    from honeybee_radiance.lib.modifiersets import modifier_set_by_identifier
+except ImportError as e:
+    raise ImportError('\nFailed to import honeybee_radiance:\n\t{}'.format(e))
+
+try:  # import ladybug_rhino dependencies
+    from ladybug_rhino.grasshopper import all_required_inputs
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component):
+    # check the input
+    if isinstance(_mod_set, str):
+        _mod_set = modifier_set_by_identifier(_mod_set)
+    else:
+        assert isinstance(_mod_set, ModifierSet), \
+            'Expected ModifierSet. Got {}.'.format(type(_mod_set))
+
+    exterior_wall = _mod_set.wall_set.exterior_modifier
+    exterior_roof = _mod_set.roof_ceiling_set.exterior_modifier
+    exposed_floor = _mod_set.floor_set.exterior_modifier
+    window = _mod_set.aperture_set.window_modifier
+    skylight = _mod_set.aperture_set.skylight_modifier
+    operable = _mod_set.aperture_set.operable_modifier
+    exterior_door = _mod_set.door_set.exterior_modifier
+    overhead_door = _mod_set.door_set.overhead_modifier
+    glass_door = _mod_set.door_set.exterior_glass_modifier
+    exterior_shade = _mod_set.shade_set.exterior_modifier

honeybee_grasshopper_radiance/src/HB Deconstruct Wea.py

@@ -0,0 +1,44 @@
+# 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>
+
+"""
+Deconstruct a Wea object into data collections of direct, diffuse, and golbal
+irradiance at each timestep of the file.
+
+-
+    Args:
+        _wea: A Honeybee WEA object.
+
+    Returns:
+        readMe!: Reports, errors, warnings, etc.
+        dir: A data collection of direct normal irradiance values at each timestep
+            of the Wea.
+        diff: A data collection of diffuse sky solar irradiance values at each
+            timestep of the Wea.
+        glob: A data collection of global horizontal irradiance values at each
+            timestep of the Wea.
+"""
+
+ghenv.Component.Name = 'HB Deconstruct Wea'
+ghenv.Component.NickName = 'DecnstrWea'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '2 :: Light Sources'
+ghenv.Component.AdditionalHelpFromDocStrings = '3'
+
+try:
+    from ladybug_rhino.grasshopper import all_required_inputs
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+
+if all_required_inputs(ghenv.Component):
+    dir = _wea.direct_normal_irradiance
+    diff = _wea.diffuse_horizontal_irradiance
+    glob = _wea.global_horizontal_irradiance

honeybee_grasshopper_radiance/src/HB Direct Sun Hours.py

@@ -0,0 +1,88 @@
+# 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 the number of hours of direct sun received by grids of sensors in a
+Honeybee model.
+_
+The fundamental calculation of this recipe is the same as that of the "LB Direct
+Sun Hours" component except that this recipe uses Radiance, which allows the
+simulation to scale better for large numbers of sensors.
+
+-
+    Args:
+        _model: A Honeybee Model for which Direct Sun Hours will be simulated.
+            Note that this model should have grids assigned to it in order
+            to produce meaningfule results.
+        _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 will
+            be used to ensure the units of the results are in hours. (Default: 1)
+        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.
+        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 zero/one values
+            indicating whether each sensor is exposed to the sun at a given
+            time step of the input Wea.
+        hours: The cumulative number of hours that each sensor can see the sun.
+            Each value is always in hours provided that the input _timestep_
+            is the same as the input Wea.
+"""
+
+ghenv.Component.Name = 'HB Direct Sun Hours'
+ghenv.Component.NickName = 'DirectSunHours'
+ghenv.Component.Message = '1.9.0'
+ghenv.Component.Category = 'HB-Radiance'
+ghenv.Component.SubCategory = '3 :: Recipes'
+ghenv.Component.AdditionalHelpFromDocStrings = '3'
+
+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('direct-sun-hours')
+    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('north', north_)
+    recipe.input_value_by_name('grid-filter', grid_filter_)
+
+    # 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(
+            'direct-sun-hours', project_folder))
+        hours = recipe_result(recipe.output_value_by_name(
+            'cumulative-sun-hours', project_folder))
+    except Exception:
+        raise Exception(recipe.failure_message(project_folder))