honeybee-radiance 1.66.190__py3-none-any.whl

honeybee_radiance/postprocess/annualglare.py

@@ -0,0 +1,201 @@
+"""Functions for post-processing imageless annual glare outputs.
+
+Note: These functions will most likely be moved to a separate package in the near future.
+"""
+import json
+import os
+
+from .annual import filter_schedule_by_hours, _process_input_folder
+
+
+def glare_autonomy_to_file(dgp_file, occ_pattern, output_folder, glare_threshold=0.4,
+                           grid_name=None, total_hours=None):
+    """Compute glare autonomy for an dgp file and write the results to a folder.
+
+    This function generates 1 file for glare autonomy.
+
+    Args:
+        dgp_file: Path to an dgp file generated by Radiance. The dgp file should be
+            tab separated and shot NOT have a header. The results for each sensor point
+            should be available in a row and and each column should be the daylight
+            glare probability value for a sun_up_hour. The number of columns should
+            match the number of sun up hours.
+        occ_pattern: A list of 0 and 1 values for hours of occupancy.
+        output_folder: An output folder where the results will be written to. The folder
+            will be created if not exist.
+        glare_threshold: A fractional number for the threshold of DGP above which
+            conditions are considered to induce glare. Default: 0.4.
+        grid_name: An optional name for grid name which will be used to name the output
+            files. If None the name of the input file will be used.
+        total_hours: An integer for the total number of occupied hours in the
+            occupancy schedule. If None, it will be assumed that all of the
+            occupied hours are sun-up hours and are already accounted for
+            in the the occ_pattern.
+
+    Returns:
+        file.ga
+
+    """
+    if not os.path.isdir(output_folder):
+        os.makedirs(output_folder)
+
+    grid_name = grid_name or os.path.split(dgp_file)[-1][-4:]
+    ga = os.path.join(output_folder, 'ga', '%s.ga' % grid_name).replace('\\', '/')
+
+    folder = os.path.dirname(ga)
+    if not os.path.isdir(folder):
+        os.makedirs(folder)
+
+    with open(dgp_file) as results, open(ga, 'w') as gaf:
+        for pt_res in results:
+            values = (float(res) for res in pt_res.split())
+            gar = _glare_autonomy(values, occ_pattern, glare_threshold, total_hours)
+            gaf.write(str(gar) + '\n')
+
+    return ga
+
+
+def glare_autonomy(dgp_file, occ_pattern, glare_threshold=0.4, total_hours=None):
+    """Compute glare autonomy for a given result file.
+
+    Args:
+        dgp_file: Path to a dgp file generated by Radiance. The dgp file should be
+            tab separated and shot NOT have a header. The results for each sensor point
+            should be available in a row and and each column should be the DGP value for
+            a sun_up_hour. The number of columns should match the number of sun up hours.
+        occ_pattern: A list of 0 and 1 values for hours of occupancy.
+        glare_threshold: Threshold DGP level for glare autonomy. Default: 0.4.
+        total_hours: An integer for the total number of occupied hours in the
+            occupancy schedule. If None, it will be assumed that all of the
+            occupied hours are sun-up hours and are already accounted for
+            in the the occ_pattern.
+
+    Returns:
+        A list of glare autonomy values. Number of results in each list matches the
+        number of lines in dgp input file.
+
+    """
+    ga = []
+    total_occupied_hours = sum(occ_pattern) if total_hours is None else total_hours
+    with open(dgp_file) as results:
+        for pt_res in results:
+            values = (float(res) for res in pt_res.split())
+            ga_v = _glare_autonomy(
+                values, occ_pattern, glare_threshold, total_occupied_hours
+            )
+            ga.append(ga_v)
+
+    return ga
+
+
+# TODO - support a list of schedules/schedule folder to match the input grids
+def glare_autonomy_from_folder(results_folder, schedule=None, glare_threshold=0.4, 
+                               grids_filter='*'):
+    """Compute glare autonomy for a folder.
+
+    This folder is an output folder of imageless annual glare recipe. Folder should
+    include grids_info.json and sun-up-hours.txt - the script uses the list in
+    grids_info.json to find the result files for each sensor grid.
+
+    Args:
+        results_folder: Results folder.
+        schedule: An annual schedule for 8760 hours of the year as a list of values.
+        glare_threshold: Threshold DGP level for glare autonomy. Default: 0.4.
+        grids_filter: A pattern to filter the grids. By default all the grids will be
+            processed.
+
+    Returns:
+        Tuple[List] - There will be a list for each input sensor grid. Number of results
+        in each list matches the number of lines in ill input file.
+
+    """
+    ga = []
+
+    grids, sun_up_hours = _process_input_folder(results_folder, grids_filter)
+    occ_pattern, total_occ, sun_down_occ_hours = \
+        filter_schedule_by_hours(sun_up_hours=sun_up_hours, schedule=schedule)
+
+    for grid in grids:
+        dgp_file = os.path.join(results_folder, '%s.dgp' % grid['full_id'])
+        ga_r = glare_autonomy(dgp_file, occ_pattern, glare_threshold, total_occ)
+        ga.append(ga_r)
+
+    return ga
+
+
+def glare_autonomy_to_folder(
+    results_folder, schedule=None, glare_threshold=0.4, grids_filter='*',
+    sub_folder='metrics'
+        ):
+    """Compute annual glare autonomy in a folder and write them in a subfolder.
+
+    This folder is an output folder of imageless annual glare recipe. Folder should
+    include grids_info.json and sun-up-hours.txt - the script uses the list in
+    grids_info.json to find the result files for each sensor grid.
+
+    Args:
+        results_folder: Results folder.
+        schedule: An annual schedule for 8760 hours of the year as a list of values.
+        glare_threshold: A fractional number for the threshold of DGP above which
+            conditions are considered to induce glare. Default: 0.4.
+        grids_filter: A pattern to filter the grids. By default all the grids will be
+            processed.
+        sub_folder: An optional relative path for subfolder to copy results files.
+            Default: metrics
+
+    Returns:
+        str -- Path to results folder.
+
+    """
+    grids, sun_up_hours = _process_input_folder(results_folder, grids_filter)
+    occ_pattern, total_occ, sun_down_occ_hours = \
+        filter_schedule_by_hours(sun_up_hours=sun_up_hours, schedule=schedule)
+
+    metrics_folder = os.path.join(results_folder, sub_folder)
+    if not os.path.isdir(metrics_folder):
+        os.makedirs(metrics_folder)
+
+    for grid in grids:
+        dgp_file = os.path.join(results_folder, '%s.dgp' % grid['full_id'])
+        glare_autonomy_to_file(
+            dgp_file, occ_pattern, metrics_folder, glare_threshold,
+            grid['full_id'], total_occ
+        )
+
+    # copy info.json to all results folders
+    grid_info = os.path.join(metrics_folder, 'ga', 'grids_info.json')
+    with open(grid_info, 'w') as outf:
+        json.dump(grids, outf)
+
+    return metrics_folder
+
+
+def _glare_autonomy(values, occ_pattern, glare_threshold, total_hours):
+    """Calculate annual glare autonomy for a sensor.
+
+    Args:
+        values: Hourly illuminance values as numbers.
+        occ_pattern: A list of 0 and 1 values for hours of occupancy.
+        glare_threshold: A fractional number for the threshold of DGP above which
+            conditions are considered to induce glare. Default: 0.4.
+        total_hours: An integer for the total number of occupied hours, which can be used
+            to avoid having to sum occ pattern each time.
+
+    Returns:
+        glare autonomy
+    """
+    def _percentage(in_v, occ_hours):
+        return round(100.0 * in_v / occ_hours, 2)
+
+    ga_above = 0
+    # count hours above glare threshold
+    for is_occ, value in zip(occ_pattern, values):
+        if is_occ == 0:
+            continue
+        if value > glare_threshold:
+            ga_above += 1
+
+    # get the number of glare free hours
+    ga = total_hours - ga_above
+
+    return _percentage(ga, total_hours)

honeybee_radiance/postprocess/annualirradiance.py

@@ -0,0 +1,187 @@
+"""Functions for post-processing annual irradiance outputs.
+
+Note: These functions will most likely be moved to a separate package in the near future.
+"""
+import os
+import shutil
+import json
+
+from ladybug.wea import Wea
+from ladybug.datatype.energyflux import EnergyFlux
+from ladybug.datatype.energyintensity import EnergyIntensity
+from ladybug.legend import LegendParameters
+
+from .annual import remove_header
+
+
+def annual_irradiance_to_folder(folder, wea, timestep=1, sub_folder='metrics'):
+    """Compute irradiance metrics in a folder and write them in a subfolder.
+
+    This command generates 3 files for each input grid.
+
+        * average_irradiance/{grid-name}.res -- Average Irradiance (W/m2)
+        * peak_irradiance/{grid-name}.res -- Peak Irradiance (W/m2)
+        * cumulative_radiation/{grid-name}.res -- Cumulative Radiation (kWh/m2)
+
+    Args:
+        folder: Results folder from an annual irradiance recipe.
+        wea: The .wea file that was used in the annual irradiance simulation. This
+            will be used to determine the duration of the analysis for computing
+            cumulative radiation.
+        timestep: The timestep of the Wea file, which is used to ensure the summed
+            row of irradiance yields cumulative radiation over the time period
+            of the Wea. (Default: 1).
+        sub_folder: An optional relative path for subfolder to copy results
+            files. (Default: metrics).
+
+    Returns:
+        str -- Path to results folder.
+    """
+    # get the time length of the Wea and the list of grids
+    wea_len = Wea.count_timesteps(wea) * timestep
+    grids = [g.replace('.ill', '') for g in os.listdir(folder) if g.endswith('.ill')]
+    grid_info = os.path.join(folder, 'grids_info.json')
+
+    # write a record of the timestep into the result folder for result processing
+    t_step_f = os.path.join(folder, 'timestep.txt')
+    with open(t_step_f, 'w') as t_f:
+        t_f.write(str(timestep))
+
+    # setup the folder into which the metrics will be written
+    metrics_folder = os.path.join(folder, sub_folder)
+    metrics_folders = []
+    for sub_f in ('average_irradiance', 'peak_irradiance', 'cumulative_radiation'):
+        m_path = os.path.join(metrics_folder, sub_f)
+        metrics_folders.append(m_path)
+        if not os.path.isdir(m_path):
+            os.makedirs(m_path)
+        grid_info_copy = os.path.join(m_path, 'grids_info.json')
+        shutil.copyfile(grid_info, grid_info_copy)
+
+    # loop through the grids and compute metrics
+    for grid in grids:
+        input_matrix = os.path.join(folder, '{}.ill'.format(grid))
+        first_line, input_file = remove_header(input_matrix)
+        avg = os.path.join(metrics_folders[0], '{}.res'.format(grid))
+        pk = os.path.join(metrics_folders[1], '{}.res'.format(grid))
+        cml = os.path.join(metrics_folders[2], '{}.res'.format(grid))
+        with open(avg, 'w') as avg_i, open(pk, 'w') as pk_i, open(cml, 'w') as cml_r:
+            # calculate the values for the first line
+            values = [float(v) for v in first_line.split()]
+            total_val = sum(values)
+            avg_i.write('{}\n'.format(total_val / wea_len))
+            pk_i.write('{}\n'.format(max(values)))
+            cml_r.write('{}\n'.format(total_val / (timestep * 1000)))
+
+            # write rest of the lines
+            for line in input_file:
+                try:
+                    values = [float(v) for v in line.split()]
+                    total_val = sum(values)
+                    pk_i.write('{}\n'.format(max(values)))
+                    avg_i.write('{}\n'.format(total_val / wea_len))
+                    cml_r.write('{}\n'.format(total_val / (timestep * 1000)))
+                except ValueError:
+                    pass  # last line of the file
+
+    metric_info_dict = _annual_irradiance_vis_metadata()
+    for metric, data in metric_info_dict.items():
+        file_path = os.path.join(metrics_folder, metric, 'vis_metadata.json')
+        with open(file_path, 'w') as fp:
+            json.dump(data, fp, indent=4)
+
+    return metrics_folder
+
+
+def _annual_irradiance_vis_metadata():
+    """Return visualization metadata for annual irradiance."""
+    cumulative_radiation_lpar = LegendParameters(min=0)
+    peak_irradiance_lpar = LegendParameters(min=0)
+    average_irradiance_lpar = LegendParameters(min=0)
+
+    metric_info_dict = {
+        'cumulative_radiation': {
+            'type': 'VisualizationMetaData',
+            'data_type': EnergyIntensity('Cumulative Radiance').to_dict(),
+            'unit': 'kWh/m2',
+            'legend_parameters': cumulative_radiation_lpar.to_dict()
+        },
+        'peak_irradiance': {
+            'type': 'VisualizationMetaData',
+            'data_type': EnergyFlux('Peak Irradiance').to_dict(),
+            'unit': 'W/m2',
+            'legend_parameters': peak_irradiance_lpar.to_dict()
+        },
+        'average_irradiance': {
+            'type': 'VisualizationMetaData',
+            'data_type': EnergyFlux('Average Irradiance').to_dict(),
+            'unit': 'W/m2',
+            'legend_parameters': average_irradiance_lpar.to_dict()
+        }
+    }
+
+    return metric_info_dict
+
+
+def _annual_irradiance_config():
+    """Return vtk-config for annual irradiance. """
+    cfg = {
+        "data": [
+            {
+                "identifier": "Cumulative Radiation",
+                "object_type": "grid",
+                "unit": "kW/m2",
+                "path": 'cumulative_radiation',
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "color_set": "original",
+                    "min": 0,
+                    "max": 1400,
+                    "label_parameters": {
+                        "color": [34, 247, 10],
+                        "size": 0,
+                        "bold": True
+                    }
+                }
+            },
+            {
+                "identifier": "Peak Irradiance",
+                "object_type": "grid",
+                "unit": "W/m2",
+                "path": 'peak_irradiance',
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "color_set": "original",
+                    "min": 0,
+                    "max": 200,
+                    "label_parameters": {
+                        "size": 0,
+                        "color": [34, 247, 10],
+                        "bold": True
+                    }
+                }
+            },
+            {
+                "identifier": "Average Irradiance",
+                "object_type": "grid",
+                "unit": "W/m2",
+                "path": 'average_irradiance',
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "color_set": "original",
+                    "min": 0,
+                    "max": 200,
+                    "label_parameters": {
+                        "color": [34, 247, 10],
+                        "size": 0,
+                        "bold": True
+                    }
+                }
+            }
+        ]
+    }
+
+    return cfg

honeybee_radiance/postprocess/electriclight.py

@@ -0,0 +1,119 @@
+"""Functions for post-processing daylight outputs into electric lighting schedules."""
+import os
+
+from .annual import generate_default_schedule, _process_input_folder
+
+
+def daylight_control_schedules(
+    results_folder, base_schedule=None, ill_setpoint=300,
+    min_power_in=0.3, min_light_out=0.2, off_at_min=False
+):
+    """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.
+
+    Args:
+        results_folder: The path to the folder containing the annual daylight
+            result files.
+        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.
+
+        -   schedule_ids: A list of text strings for the recommended names of the
+            electric lighting schedules.
+    """
+    # process the base schedule input into a list of values
+    if base_schedule is None:
+        base_schedule = generate_default_schedule()
+
+    # get the relevant .ill files
+    grids, sun_up_hours = _process_input_folder(results_folder, '*')
+    sun_up_hours = [int(h) for h in sun_up_hours]
+
+    # get the dimming fractions for each sensor grid from the .ill files
+    dim_fracts = []
+    for grid_info in grids:
+        ill_file = os.path.join(results_folder, '%s.ill' % grid_info['full_id'])
+        fract_list = _file_to_dimming_fraction(
+            ill_file, sun_up_hours, ill_setpoint, min_power_in,
+            min_light_out, off_at_min
+        )
+        dim_fracts.append(fract_list)
+
+    # create the schedule by combining the base schedule with the dimming fraction
+    schedules, schedule_ids = [], []
+    for grid_info, dim_fract in zip(grids, dim_fracts):
+        sch_vals = [b_val * d_val for b_val, d_val in zip(base_schedule, dim_fract)]
+        sch_id = '{} Daylight Control'.format(grid_info['full_id'])
+        schedules.append(sch_vals)
+        schedule_ids.append(sch_id)
+    return schedules, schedule_ids
+
+
+def _file_to_dimming_fraction(ill_file, su_pattern, setpt, m_pow, m_lgt, off_m):
+    """Compute hourly dimming fractions for a given result file."""
+    # get a base schedule of dimming fractions for the sun-up hours
+    su_values = [0] * len(su_pattern)
+    sensor_count = 0
+    with open(ill_file) as results:
+        for pt_res in results:
+            sensor_count += 1
+            for i, val in enumerate(pt_res.split()):
+                su_values[i] += _dimming_from_ill(float(val), setpt, m_pow, m_lgt, off_m)
+    su_values = [val / sensor_count for val in su_values]
+
+    # account for the hours where the sun is not up
+    dim_fract = [1] * 8760
+    for val, hr in zip(su_values, su_pattern):
+        dim_fract[hr] = float(val)
+    return dim_fract
+
+
+def _dimming_from_ill(ill_val, ill_setpt, min_pow, min_light, off_at_min):
+    """Compute the dimming fraction from an illuminance value."""
+    if ill_val > ill_setpt:  # dimmed all of the way
+        return 0 if off_at_min else min_pow
+    elif ill_val <= min_light:  # not dimmed at all
+        return 1
+    else:  # partially dimmed
+        fract_dim = (ill_setpt - ill_val) / (ill_setpt - min_light)
+        return fract_dim + ((1 - fract_dim) * min_pow)