honeybee-radiance-postprocess 0.4.555__py3-none-any.whl

honeybee_radiance_postprocess/en17037.py

@@ -0,0 +1,304 @@
+"""Functions for EN 17037 post-processing."""
+from typing import Union
+from pathlib import Path
+import json
+try:
+    import cupy as np
+    is_gpu = True
+except ImportError:
+    is_gpu = False
+    import numpy as np
+
+from ladybug.color import Colorset
+from ladybug.datatype.fraction import Fraction
+from ladybug.legend import LegendParameters
+
+from .results.annual_daylight import AnnualDaylight
+from .dynamic import DynamicSchedule
+from .metrics import da_array2d
+from .util import filter_array
+
+
+def en17037_to_files(
+        array: np.ndarray, metrics_folder: Path, grid_info: dict) -> list:
+    """Compute annual EN 17037 metrics for a NumPy array and write the results
+    to a folder.
+
+    This function generates 6 different files for daylight autonomy based on
+    the varying level of recommendation in EN 17037.
+
+    Args:
+        array: A 2D NumPy array.
+        metrics_folder: An output folder where the results will be written to.
+            The folder will be created if it does not exist.
+        grid_info: A grid information dictionary.
+
+    Returns:
+        tuple -- Tuple of lists of paths for da, sda, and compliance folders.
+    """
+    recommendations = {
+        'minimum_illuminance': {
+            'minimum': 100,
+            'medium': 300,
+            'high': 500
+        },
+        'target_illuminance': {
+            'minimum': 300,
+            'medium': 500,
+            'high': 750
+        }
+    }
+    compliance_value = {
+        'minimum': 1,
+        'medium': 2,
+        'high': 3
+    }
+
+    grid_id = grid_info['full_id']
+    grid_count = grid_info['count']
+
+    da_folders = []
+    sda_folders = []
+    compliance_folders = []
+    da_folder = metrics_folder.joinpath('da')
+    sda_folder = metrics_folder.joinpath('sda')
+    compliance_folder = metrics_folder.joinpath('compliance_level')
+
+    for target_type, thresholds in recommendations.items():
+        compliance_level = None
+        for level, threshold in thresholds.items():
+            # da
+            da_level_folder = \
+                da_folder.joinpath('_'.join([target_type, str(threshold)]))
+            da_file = da_level_folder.joinpath(f'{grid_id}.da')
+            if not da_file.parent.is_dir():
+                da_file.parent.mkdir(parents=True)
+            da = da_array2d(array, total_occ=4380, threshold=threshold)
+            np.savetxt(da_file, da, fmt='%.2f')
+
+            # sda
+            sda_level_folder = \
+                sda_folder.joinpath('_'.join([target_type, str(threshold)]))
+            sda_file = sda_level_folder.joinpath(f'{grid_id}.sda')
+            if not sda_file.parent.is_dir():
+                sda_file.parent.mkdir(parents=True)
+            sda = (da >= 50).mean() * 100
+            with open(sda_file, 'w') as sdaf:
+                sdaf.write(str(round(sda, 2)))
+
+            space_target = 50 if target_type == 'target_illuminance' else 95
+            if sda >= space_target:
+                compliance_level = np.full((grid_count), compliance_value[level], dtype=int)
+
+            da_folders.append(da_file.parent)
+            sda_folders.append(sda_file.parent)
+
+        if compliance_level is None:
+            compliance_level = np.zeros(grid_count, dtype=int)
+        compliance_level_folder = compliance_folder.joinpath(target_type)
+        compliance_level_file = compliance_level_folder.joinpath(f'{grid_id}.pf')
+        if not compliance_level_file.parent.is_dir():
+            compliance_level_file.parent.mkdir(parents=True)
+        np.savetxt(compliance_level_file, compliance_level, fmt='%i')
+        compliance_folders.append(compliance_level_file.parent)
+
+    return da_folders, sda_folders, compliance_folders
+
+
+def en17037_to_folder(
+        results: Union[str, AnnualDaylight], schedule: list,
+        states: DynamicSchedule = None, grids_filter: str = '*',
+        sub_folder: str = 'en17037') -> Path:
+    """Compute annual EN 17037 metrics in a folder and write them in a subfolder.
+
+    The results is an output folder of annual daylight recipe.
+
+    Args:
+        results: Results folder.
+        schedule: An annual schedule for 8760 hours of the year as a list of
+            values. This should be a daylight hours schedule.
+        grids_filter: A pattern to filter the grids. By default all the grids
+            will be processed.
+        states: A dictionary of states. Defaults to None.
+        sub_folder: An optional relative path for subfolder to copy results
+            files. Default: en17037.
+
+    Returns:
+        str -- Path to results folder.
+    """
+    if not isinstance(results, AnnualDaylight):
+        results = AnnualDaylight(results, schedule=schedule)
+    else:
+        results.schedule = schedule
+
+    total_occ = results.total_occ
+    occ_mask = results.occ_mask
+
+    grids_info = results._filter_grids(grids_filter=grids_filter)
+
+    sub_folder = Path(sub_folder)
+
+    if total_occ != 4380:
+        raise ValueError(
+            f'There are {total_occ} occupied hours in the schedule. According '
+            'to EN 17037 the schedule must consist of the daylight hours '
+            'which is defined as the half of the year with the largest '
+            'quantity of daylight')
+
+    for grid_info in grids_info:
+        array = results._array_from_states(
+            grid_info, states=states, res_type='total', zero_array=True)
+        if np.any(array):
+            array = np.apply_along_axis(
+                filter_array, 1, array, occ_mask)
+        da_folders, sda_folders, compliance_folders = en17037_to_files(
+            array, sub_folder, grid_info)
+
+    # copy grids_info.json to all results folders
+    for folder in da_folders + sda_folders + compliance_folders:
+        grids_info_file = Path(folder, 'grids_info.json')
+        with open(grids_info_file, 'w') as outf:
+            json.dump(grids_info, outf, indent=2)
+
+    metric_info_dict = _annual_daylight_en17037_vis_metadata()
+    da_folder = sub_folder.joinpath('da')
+    for metric, data in metric_info_dict.items():
+        file_path = da_folder.joinpath(metric, 'vis_metadata.json')
+        with open(file_path, 'w') as fp:
+            json.dump(data, fp, indent=4)
+
+    return sub_folder
+
+
+def _annual_daylight_en17037_vis_metadata():
+    """Return visualization metadata for annual daylight."""
+    da_lpar = LegendParameters(min=0, max=100, colors=Colorset.annual_comfort())
+
+    metric_info_dict = {
+        'minimum_illuminance_100': {
+            'type': 'VisualizationMetaData',
+            'data_type': Fraction('Daylight Autonomy - minimum 100 lux').to_dict(),
+            'unit': '%',
+            'legend_parameters': da_lpar.to_dict()
+        },
+        'minimum_illuminance_300': {
+            'type': 'VisualizationMetaData',
+            'data_type': Fraction('Daylight Autonomy - minimum 300 lux').to_dict(),
+            'unit': '%',
+            'legend_parameters': da_lpar.to_dict()
+        },
+        'minimum_illuminance_500': {
+            'type': 'VisualizationMetaData',
+            'data_type': Fraction('Daylight Autonomy - minimum 500 lux').to_dict(),
+            'unit': '%',
+            'legend_parameters': da_lpar.to_dict()
+        },
+        'target_illuminance_300': {
+            'type': 'VisualizationMetaData',
+            'data_type': Fraction('Daylight Autonomy - target 300 lux').to_dict(),
+            'unit': '%',
+            'legend_parameters': da_lpar.to_dict()
+        },
+        'target_illuminance_500': {
+            'type': 'VisualizationMetaData',
+            'data_type': Fraction('Daylight Autonomy - target 500 lux').to_dict(),
+            'unit': '%',
+            'legend_parameters': da_lpar.to_dict()
+        },
+        'target_illuminance_750': {
+            'type': 'VisualizationMetaData',
+            'data_type': Fraction('Daylight Autonomy - target 750 lux').to_dict(),
+            'unit': '%',
+            'legend_parameters': da_lpar.to_dict()
+        }
+    }
+
+    return metric_info_dict
+
+
+def _annual_daylight_en17037_config():
+    """Return vtk-config for annual daylight EN 17037. """
+    cfg = {
+        "data": [
+            {
+                "identifier": "Daylight Autonomy - target 300 lux",
+                "object_type": "grid",
+                "unit": "Percentage",
+                "path": "target_illuminance/minimum/da",
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "min": 0,
+                    "max": 100,
+                    "color_set": "nuanced",
+                },
+            },
+            {
+                "identifier": "Daylight Autonomy - target 500 lux",
+                "object_type": "grid",
+                "unit": "Percentage",
+                "path": "target_illuminance/medium/da",
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "min": 0,
+                    "max": 100,
+                    "color_set": "nuanced",
+                },
+            },
+            {
+                "identifier": "Daylight Autonomy - target 750 lux",
+                "object_type": "grid",
+                "unit": "Percentage",
+                "path": "target_illuminance/high/da",
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "min": 0,
+                    "max": 100,
+                    "color_set": "nuanced",
+                },
+            },
+            {
+                "identifier": "Daylight Autonomy - minimum 100 lux",
+                "object_type": "grid",
+                "unit": "Percentage",
+                "path": "minimum_illuminance/minimum/da",
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "min": 0,
+                    "max": 100,
+                    "color_set": "nuanced",
+                },
+            },
+            {
+                "identifier": "Daylight Autonomy - minimum 300 lux",
+                "object_type": "grid",
+                "unit": "Percentage",
+                "path": "minimum_illuminance/medium/da",
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "min": 0,
+                    "max": 100,
+                    "color_set": "nuanced",
+                },
+            },
+            {
+                "identifier": "Daylight Autonomy - minimum 500 lux",
+                "object_type": "grid",
+                "unit": "Percentage",
+                "path": "minimum_illuminance/high/da",
+                "hide": False,
+                "legend_parameters": {
+                    "hide_legend": False,
+                    "min": 0,
+                    "max": 100,
+                    "color_set": "nuanced",
+                },
+            },
+        ]
+    }
+
+    return cfg

honeybee_radiance_postprocess/helper.py

@@ -0,0 +1,266 @@
+"""Helper functions."""
+import json
+from pathlib import Path
+try:
+    import cupy as np
+    is_gpu = True
+except ImportError:
+    is_gpu = False
+    import numpy as np
+
+from honeybee.model import Model
+
+
+def model_grid_areas(model, grids_info):
+    if isinstance(model, Model):
+        hb_model = model
+    else:
+        hb_model = Model.from_file(model)
+
+    full_ids = [grid_info['full_id'] for grid_info in grids_info]
+    sensor_grids = hb_model.properties.radiance.sensor_grids
+    grid_areas = []
+    for s_grid in sensor_grids:
+        if s_grid.identifier in full_ids:
+            if s_grid.mesh is not None:
+                grid_areas.append(s_grid.mesh.face_areas)
+    grid_areas = [np.array(grid) for grid in grid_areas]
+    if not grid_areas:
+        grid_areas = [None] * len(full_ids)
+
+    return grid_areas
+
+
+def grid_summary(
+        folder: Path, grid_areas: list = None,
+        grids_info: list = None, name: str = 'grid_summary',
+        grid_metrics: list = None, sub_folder: bool = True
+    ):
+    """Calculate a grid summary for a single metric.
+
+    Args:
+        folder: A folder with results.
+        grid_areas: A list of area of each sensor.
+        grids_info: Grid information as a dictionary.
+        name: Optional filename of grid summary.
+        grid_metrics: Additional customized metrics to calculate.
+        sub_folder: If set to True it will look for results in all sub-folders
+            in the folder input. Else it look for results directly in the folder
+            input.
+    """
+    if sub_folder:
+        sub_folders = [sf for sf in folder.iterdir() if sf.is_dir()]
+    else:
+        sub_folders = [folder]
+
+    # set up the default data types
+    dtype_sensor_grid = ('Sensor Grid', 'O')
+    dtype_sensor_grid_id = ('Sensor Grid ID', 'O')
+    dtype_base = [
+        ('Mean', np.float32),
+        ('Minimum', np.float32),
+        ('Maximum', np.float32),
+        ('Uniformity Ratio', np.float32)
+    ]
+    dtype = []
+
+    # set up default format (for first two columns: str)
+    fmt = ['%s', '%s']
+
+    if grids_info is None:
+        for sf in sub_folders:
+            gi_file = sf.joinpath('grids_info.json')
+            if gi_file.exists():
+                with open(gi_file) as gi:
+                    grids_info = json.load(gi)
+                break
+        if grids_info is None:
+            # if it did not find grids_info.json in any folder
+            raise FileNotFoundError(
+                f'The file grids_info.json was not found in any folder.')
+
+    if grid_areas is None:
+        grid_areas = [None] * len(grids_info)
+
+
+    dtype.append(dtype_sensor_grid)
+    dtype.append(dtype_sensor_grid_id)
+    for sf in sub_folders:
+        _dtype = []
+        _fmt = []
+        for dt_b in dtype_base:
+            col_name = dt_b[0]
+            if sub_folder:
+                col_name = '-'.join([sf.stem.upper(), col_name])
+            _dtype.append((col_name, np.float32))
+            _fmt.append('%.2f')
+        dtype.extend(_dtype)
+        fmt.extend(_fmt)
+
+        if grid_metrics is not None:
+            for grid_metric in grid_metrics:
+                if len(grid_metric) == 1:
+                    if 'allOf' in grid_metric:
+                        _mname = []
+                        for gr_m in grid_metric['allOf']:
+                            _mname.append(_get_grid_metric_name(gr_m))
+                        mname = ' and '.join(_mname)
+                    elif 'anyOf' in grid_metric:
+                        _mname = []
+                        for gr_m in grid_metric['anyOf']:
+                            _mname.append(_get_grid_metric_name(gr_m))
+                        mname = ' or '.join(_mname)
+                    else:
+                        mname = _get_grid_metric_name(grid_metric)
+                elif len(grid_metric) == 2:
+                    _mname = []
+                    for k, v in grid_metric.items():
+                        _mname.append(_get_grid_metric_name({k: v}))
+                    mname = ' and '.join(_mname)
+                col_name = mname
+                if sub_folder:
+                    col_name = '-'.join([sf.stem.upper(), col_name])
+                dtype.append((col_name, np.float32))
+                fmt.append('%.2f')
+
+    arrays = []
+    for grid_info, grid_area in zip(grids_info, grid_areas):
+        full_id = grid_info['full_id']
+        grid_name = grid_info['name']
+        data = [grid_name, full_id]
+        for sf in sub_folders:
+            grid_files = list(sf.glob(f'{full_id}.*'))
+            assert len(grid_files) == 1
+
+            array = np.loadtxt(grid_files[0])
+            _mean = array.mean()
+            _min = array.min()
+            _max = array.max()
+            _uniformity_ratio = _min / _mean * 100
+
+            data.extend([_mean, _min, _max, _uniformity_ratio])
+
+            if grid_metrics is not None:
+                # get grid metrics
+                grid_metrics_data = \
+                    _get_grid_metrics(array, grid_metrics, grid_info, grid_area)
+                data.extend(grid_metrics_data)
+
+        arrays.append(tuple(data))
+
+    # create structured array
+    if is_gpu:
+        struct_array = None
+    else:
+        struct_array = np.array(arrays, dtype=dtype)
+
+    header = [dt[0] for dt in dtype]
+    # write header to file
+    with open(folder.joinpath(f'{name}.csv'), 'w') as grid_summary_file:
+        grid_summary_file.write(','.join(header))
+    # write structured array to grid_summary_file
+    with open(folder.joinpath(f'{name}.csv'), 'a') as grid_summary_file:
+        grid_summary_file.write('\n')
+        if is_gpu:
+            # CuPy doesn't support structured arrays; manually format rows
+            for row in arrays:
+                row_str = ','.join(fmt_val % val for fmt_val, val in zip(fmt, row))
+                grid_summary_file.write(row_str + '\n')
+        else:
+            np.savetxt(grid_summary_file, struct_array, delimiter=',', fmt=fmt)
+
+    return grid_summary_file
+
+
+def _calculate_percentage(gr_metric_bool, grid_info, grid_area=None):
+    """Calculate percentage of floor area where True.
+
+    Args:
+        gr_metric_bool: A NumPy array of booleans.
+        grid_info: Grid information.
+        grid_area: A NumPy array of area for each sensor. (Default: None).
+    
+    Returns:
+        The percentage of floor area where gr_metric_bool is True.
+    """
+    if grid_area is not None:
+        gr_metric_pct = \
+            grid_area[gr_metric_bool].sum() / grid_area.sum() * 100
+    else:
+        gr_metric_pct = \
+            gr_metric_bool.sum() / grid_info['count'] * 100
+    return gr_metric_pct
+
+
+def _logical_operator(keyword):
+    lg = {
+        'minimum': '>',
+        'exclusiveMinimum': '>=',
+        'maximum': '<',
+        'exclusiveMaximum': '<='
+    }
+    return lg[keyword]
+
+
+def _get_grid_metric_name(grid_metric):
+    if 'minimum' in grid_metric:
+        return f'{_logical_operator("minimum")}{grid_metric["minimum"]}'
+    elif 'exclusiveMinimum' in grid_metric:
+        return f'{_logical_operator("exclusiveMinimum")}{grid_metric["exclusiveMinimum"]}'
+    elif 'maximum' in grid_metric:
+        return f'{_logical_operator("maximum")}{grid_metric["maximum"]}'
+    elif 'exclusiveMaximum' in grid_metric:
+        return f'{_logical_operator("exclusiveMaximum")}{grid_metric["exclusiveMaximum"]}'
+
+
+def _numeric_type(array, gr_metric):
+    if 'minimum' in gr_metric:
+        gr_metric_bool = array > gr_metric['minimum']
+    elif 'exclusiveMinimum' in gr_metric:
+        gr_metric_bool = array >= gr_metric['minimum']
+    elif 'maximum' in gr_metric:
+        gr_metric_bool = array < gr_metric['maximum']
+    elif 'exclusiveMaximum' in gr_metric:
+        gr_metric_bool = array <= gr_metric['exclusiveMaximum']
+    return gr_metric_bool
+
+
+def _grid_summary_all_any(array, gr_metric, grid_info, grid_area, keyword):
+    gr_metric_arrays = []
+    for gr_m in gr_metric[keyword]:
+        assert len(gr_m) == 1
+        gr_metric_arrays.append(_numeric_type(array, gr_m))
+    if keyword == 'allOf':
+        gr_metric_bool = np.all(gr_metric_arrays, axis=0)
+    else:
+        gr_metric_bool = np.any(gr_metric_arrays, axis=0)
+    gr_metric_pct = \
+        _calculate_percentage(gr_metric_bool, grid_info, grid_area)
+    return gr_metric_pct
+
+
+def _get_grid_metrics(array, grid_metrics, grid_info, grid_area):
+    grid_metrics_data = []
+    for gr_metric in grid_metrics:
+        if len(gr_metric) == 1:
+            if 'allOf' in gr_metric:
+                gr_metric_pct = \
+                    _grid_summary_all_any(
+                        array, gr_metric, grid_info, grid_area, 'allOf')
+            elif 'anyOf' in gr_metric:
+                gr_metric_pct = \
+                    _grid_summary_all_any(
+                        array, gr_metric, grid_info, grid_area, 'anyOf')
+            else:
+                gr_metric_bool = _numeric_type(array, gr_metric)
+                gr_metric_pct = \
+                    _calculate_percentage(gr_metric_bool, grid_info, grid_area)
+        elif len(gr_metric) == 2:
+            gr_metric_arrays = []
+            for k, threshold in gr_metric.items():
+                gr_metric_arrays.append(_numeric_type(array, {k: threshold}))
+            gr_metric_bool = np.all(gr_metric_arrays, axis=0)
+            gr_metric_pct = \
+                _calculate_percentage(gr_metric_bool, grid_info, grid_area)
+        grid_metrics_data.append(gr_metric_pct)
+    return grid_metrics_data

honeybee_radiance_postprocess/ies/__init__.py

@@ -0,0 +1 @@
+"""honeybee-radiance-postprocess library."""