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

honeybee_radiance_postprocess/leed/leed_schedule.py

@@ -0,0 +1,256 @@
+"""Module for dynamic LEED schedules."""
+from typing import Tuple
+try:
+    import cupy as np
+    is_gpu = True
+except ImportError:
+    is_gpu = False
+    import numpy as np
+
+from ..results.annual_daylight import AnnualDaylight
+from ..util import filter_array2d
+
+
+def shd_trans_schedule_descending(
+        results: AnnualDaylight, grid_info, light_paths, shade_transmittances, occ_mask,
+        states_schedule, fail_to_comply
+        ) -> Tuple[dict, dict]:
+    grid_count = grid_info['count']
+    full_direct = []
+    full_thresh = []
+    full_shd_trans_array = []
+    for light_path in light_paths:
+        array = results._get_array(grid_info, light_path, res_type="direct")
+        array = filter_array2d(array, occ_mask)
+        full_direct.append(array)
+        full_thresh.append((array >= 1000).sum(axis=0))
+        full_shd_trans_array.append(shade_transmittances[light_path][1])
+
+    # Sum the array element-wise.
+    # This array is the sum of all direct illuminance without shade
+    # transmittance.
+    full_direct_sum = sum(full_direct)
+
+    # Create base list of shading combinations (all set to 1).
+    # We will replace the 1s later.
+    combinations = [
+        {light_path: 1 for light_path in light_paths}
+        for i in range(full_direct_sum.shape[1])
+    ]
+
+    # Find the percentage of floor area >= 1000 lux.
+    # This array is the percentage for each hour (axis=0).
+    direct_pct_above = (full_direct_sum >= 1000).sum(axis=0) / grid_count
+
+    # Find the indices where the percentage of floor area is > 2%.
+    # This array is the problematic hours.
+    above_2_indices = np.where(direct_pct_above > 0.02)[0]
+
+    # Use the indices to get the relevant hours.
+    direct_sum = np.take(full_direct_sum, above_2_indices, axis=1)
+
+    # Use the indices to get the relevant hours.
+    direct = np.take(full_direct, above_2_indices, axis=2)
+
+    # Use the indices to get the relevant hours.
+    thresh = np.take(full_thresh, above_2_indices, axis=1)
+
+    del full_direct, full_thresh
+    # Sort and get indices. Negate the array to get descending order.
+    # Descending order puts the "highest offender" light path first.
+    sort_thresh = np.argsort(-thresh, axis=0).transpose()
+
+    _combinations = []
+    _combinations.insert(
+        0, (np.arange(full_direct_sum.shape[1]), combinations)
+    )
+
+    del full_direct_sum
+
+    if np.any(above_2_indices):
+        # There are hours where the percentage of floor area is > 2%.
+        for idx, lp in enumerate(light_paths):
+            # Take column. For each iteration it will take the next column
+            # in descending order, i.e., the "highest offender" is the first
+            # column.
+            sort_indices = np.take(sort_thresh, idx, axis=1)
+
+            # Map light path identifiers to indices.
+            light_path_ids = np.take(light_paths, sort_indices)
+
+            # Map shade transmittance to indices.
+            shd_trans_array = np.take(full_shd_trans_array, sort_indices)
+
+            # Create combination for the subset.
+            _subset_combination = [
+                {light_path: _shd_trans} for light_path, _shd_trans in
+                zip(light_path_ids, shd_trans_array)
+            ]
+            _combinations.insert(0, (above_2_indices, _subset_combination))
+
+            # Take the values from each array by indexing.
+            direct_array = \
+                direct[sort_indices, :, range(len(sort_indices))].transpose()
+
+            # Subtract the illuminance values.
+            direct_sum = direct_sum - (direct_array * (1 - shd_trans_array))
+
+            # Find the percentage of floor area >= 1000 lux.
+            direct_pct_above = (direct_sum >= 1000).sum(axis=0) / grid_count
+
+            # Find the indices where the percentage of floor area is > 2%.
+            above_2_indices = np.where(direct_pct_above > 0.02)[0]
+
+            # Break if there are no hours above 2%.
+            if not np.any(above_2_indices):
+                break
+
+            # Update variables for the next iteration.
+            direct_sum = np.take(direct_sum, above_2_indices, axis=1)
+            direct = np.take(direct, above_2_indices, axis=2)
+            thresh = np.take(thresh, above_2_indices, axis=1)
+            sort_thresh = np.take(sort_thresh, above_2_indices, axis=0)
+
+        if np.any(above_2_indices):
+            # There are hours not complying with the 2% rule.
+            previous_indices = []
+            previous_combination = []
+            grid_comply = []
+            # Merge the combinations from the iterations of the subsets.
+            for i, subset in enumerate(_combinations):
+                if i == 0:
+                    previous_indices = subset[0]
+                else:
+                    _indices = subset[0]
+                    grid_comply = []
+                    for _pr_idx in previous_indices:
+                        grid_comply.append(_indices[_pr_idx])
+                    previous_indices = grid_comply
+            # Convert indices to sun up hours indices.
+            filter_indices = np.where(occ_mask.astype(bool))[0]
+            grid_comply = [filter_indices[_gc] for _gc in grid_comply]
+            grid_comply = np.array(results.sun_up_hours)[grid_comply]
+            fail_to_comply[grid_info['name']] = \
+                [int(hoy) for hoy in grid_comply]
+
+        previous_indices = None
+        previous_combination = None
+        # Merge the combinations from the iterations of the subsets.
+        for i, subset in enumerate(_combinations):
+            if i == 0:
+                previous_indices, previous_combination = subset
+            else:
+                _indices, _combination = subset
+                for _pr_idx, _pr_comb in \
+                        zip(previous_indices, previous_combination):
+                    for light_path, _shd_trans in _pr_comb.items():
+                        _combination[_pr_idx][light_path] = _shd_trans
+                previous_indices = _indices
+                previous_combination = _combination
+
+        combinations = _combination
+
+    del full_shd_trans_array, direct_sum, direct, thresh, sort_thresh
+
+    # Merge the combinations of dicts.
+    for combination in combinations:
+        for light_path, shd_trans in combination.items():
+            if light_path != "__static_apertures__":
+                states_schedule[light_path].append(shd_trans)
+
+    return states_schedule, fail_to_comply
+
+
+def states_schedule_descending(
+        results: AnnualDaylight, grid_info, light_paths, occ_mask,
+        states_schedule, fail_to_comply
+        ) -> Tuple[dict, dict]:
+    grid_count = grid_info['count']
+    full_direct = []
+    full_thresh = []
+    full_direct_blinds = []
+    for light_path in light_paths:
+        array = results._get_array(
+            grid_info, light_path, state=0, res_type="direct")
+        array = filter_array2d(array, occ_mask)
+        full_direct.append(array)
+        full_thresh.append((array >= 1000).sum(axis=0))
+
+        array = results._get_array(
+            grid_info, light_path, state=1, res_type="direct")
+        array = filter_array2d(array, occ_mask)
+        full_direct_blinds.append(array)
+
+    full_direct = np.array(full_direct)
+    full_direct_blinds = np.array(full_direct_blinds)
+    full_direct_sum = full_direct.sum(axis=0)
+
+    percentage_sensors = (full_direct_sum >= 1000).sum(axis=0) / grid_count
+    if not np.any(percentage_sensors > 0.02):
+        combinations = [
+            {light_path: 0 for light_path in light_paths}
+            for i in range(full_direct_sum.shape[1])]
+    else:
+        new_array = full_direct.copy()
+        tracking_array = np.zeros(
+            (new_array.shape[0], new_array.shape[2]), dtype=int)
+
+        percentage_sensors = (full_direct >= 1000).sum(axis=1) / grid_count
+
+        ranking_indices = np.argsort(-percentage_sensors, axis=0)
+
+        for rank in range(ranking_indices.shape[0]):
+            # Calculate the percentage of sensors with values >= 1000 for the current new_array
+            summed_array = np.sum(new_array, axis=0)
+            percentage_sensors_summed = np.sum(
+                summed_array >= 1000, axis=0) / grid_count
+            indices_above_2_percent = np.where(
+                percentage_sensors_summed > 0.02)[0]
+
+            # Exit if there are no more hours exceeding the threshold
+            if len(indices_above_2_percent) == 0:
+                break
+
+            # Array indices to use for replacement for these hours
+            replace_indices = indices_above_2_percent
+            array_indices = ranking_indices[rank, replace_indices]
+
+            # Use advanced indexing to replace values in new_array for these hours
+            for hour_idx, array_idx in zip(replace_indices, array_indices):
+                new_array[array_idx, :, hour_idx] = full_direct_blinds[
+                    array_idx, :, hour_idx
+                ]
+
+            # Update the tracking array
+            tracking_array[array_indices, replace_indices] = 1
+
+        combinations = []
+        for hour in range(new_array.shape[2]):
+            hour_dict = {
+                light_paths[i]: tracking_array[i, hour]
+                for i in range(tracking_array.shape[0])}
+            combinations.append(hour_dict)
+
+        final_summed_array = np.sum(new_array, axis=0)
+        final_percentage_sensors_summed = (
+            final_summed_array >= 1000).sum(
+            axis=0) / grid_count
+        final_indices_above_2_percent = np.where(
+            final_percentage_sensors_summed > 0.02)[0]
+        if np.any(final_indices_above_2_percent):
+            sun_up_hours_indices = np.where(occ_mask == 1)[0][
+                final_indices_above_2_percent]
+            grid_comply = np.array(results.sun_up_hours)[sun_up_hours_indices]
+            fail_to_comply[grid_info['name']] = [
+                int(hoy) for hoy in grid_comply]
+
+        del new_array, tracking_array, percentage_sensors, ranking_indices, final_summed_array
+
+    del full_direct, full_thresh, full_direct_blinds, full_direct_sum
+
+    for combination in combinations:
+        for light_path, value in combination.items():
+            if light_path != '__static_apertures__':
+                states_schedule[light_path].append(value)
+
+    return states_schedule, fail_to_comply

honeybee_radiance_postprocess/metrics.py

@@ -0,0 +1,439 @@
+"""Functions to calculate various metrics for 1D and 2D NumPy arrays."""
+from typing import Tuple, Union
+try:
+    import cupy as np
+    is_gpu = True
+except ImportError:
+    is_gpu = False
+    import numpy as np
+
+from .util import check_array_dim
+
+is_cpu = not is_gpu
+
+
+def da_array2d(
+        array: np.ndarray, total_occ: int = None, threshold: float = 300) -> np.ndarray:
+    """Calculate daylight autonomy for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not
+            given any input the number of occupied hours will be found by the
+            array shape, i.e., it is assumed that the array is filtered by
+            occupied hours.
+        threshold: Threshold value for daylight autonomy. Default: 300.
+
+    Returns:
+        A 1-dimensional NumPy array with the daylight autonomy for each row in
+        the input array.
+    """
+    check_array_dim(array, 2)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.shape[1]
+
+    da = np.sum(array >= threshold, axis=1) / total_occ * 100
+
+    return da
+
+
+def da_array1d(
+        array: np.ndarray, total_occ: int = None,
+        threshold: float = 300) -> np.float64:
+    """Calculate daylight autonomy for a 1D NumPy array.
+
+    Args:
+        array: A 1D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        threshold: Threshold value for daylight autonomy. Default: 300.
+
+    Returns:
+        A NumPy float of the daylight autonomy.
+    """
+    check_array_dim(array, 1)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.size
+
+    return np.float64((array >= threshold).sum() / total_occ * 100)
+
+
+def cda_array2d(
+        array: np.ndarray, total_occ: int = None,
+        threshold: float = 300) -> np.ndarray:
+    """Calculate continuos daylight autonomy for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        threshold: Threshold value for continuos daylight autonomy. Default: 300.
+
+    Returns:
+        A 1-dimensional NumPy array with the continuos daylight autonomy for
+        each row in the input array.
+    """
+    check_array_dim(array, 2)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.shape[1]
+
+    if is_cpu:
+        cda = np.apply_along_axis(
+                cda_array1d, 1, array, total_occ=total_occ, threshold=threshold)
+    else:
+        cda = np.where(array >= threshold, 1, array / threshold).sum(axis=1) / total_occ * 100
+
+    return cda
+
+
+def cda_array1d(
+        array: np.ndarray, total_occ: int = None,
+        threshold: float = 300) -> np.float64:
+    """Calculate continuos daylight autonomy for a 1D NumPy array.
+
+    Args:
+        array: A 1D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        threshold: Threshold value for continuos daylight autonomy. Default: 300.
+
+    Returns:
+        A NumPy float of the continuos daylight autonomy.
+    """
+    check_array_dim(array, 1)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.size
+
+    return np.float64(
+        np.where(array >= threshold, 1, array / threshold).sum() / total_occ * 100)
+
+
+def udi_array2d(
+        array: np.ndarray, total_occ: int = None, min_t: float = 100,
+        max_t: float = 3000) -> np.ndarray:
+    """Calculate useful daylight illuminance for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+        max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+
+    Returns:
+        A 1-dimensional NumPy array with the useful daylight illuminance for
+        each row in the input array.
+    """
+    check_array_dim(array, 2)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.shape[1]
+
+    if is_cpu:
+        udi = np.apply_along_axis(
+                udi_array1d, 1, array, total_occ=total_occ, min_t=min_t, max_t=max_t)
+    else:
+        udi = ((array >= min_t) & (array <= max_t)).sum(axis=1) / total_occ * 100
+
+    return udi
+
+
+def udi_array1d(
+        array: np.ndarray, total_occ: int = None, min_t: float = 100,
+        max_t: float = 3000) -> np.float64:
+    """Calculate useful daylight illuminance for a 1D NumPy array.
+
+    Args:
+        array: A 1D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+        max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+
+    Returns:
+        A NumPy float of the useful daylight illuminance.
+    """
+    check_array_dim(array, 1)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.size
+
+    return np.float64(((array >= min_t) & (array <= max_t)).sum() / total_occ * 100)
+
+
+def udi_lower_array2d(
+        array: np.ndarray, total_occ: int = None, min_t: float = 100,
+        sun_down_occ_hours: int = 0) -> np.ndarray:
+    """Calculate lower than useful daylight illuminance for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+        sun_down_occ_hours: Number of occupied hours where the sun is down.
+
+    Returns:
+        A 1-dimensional NumPy array with the lower than useful daylight
+        illuminance for each row in the input array.
+    """
+    check_array_dim(array, 2)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.shape[1]
+
+    if is_cpu:
+        udi = np.apply_along_axis(
+                udi_lower_array1d, 1, array, total_occ=total_occ, min_t=min_t,
+                sun_down_occ_hours=sun_down_occ_hours)
+    else:
+        if min_t == 0:
+            return np.zeros(array.shape[0], dtype=np.float32)
+
+        udi = ((array < min_t).sum(axis=1) + sun_down_occ_hours) / total_occ * 100
+
+    return udi
+
+
+def udi_lower_array1d(
+        array: np.ndarray, total_occ: int = None, min_t: float = 100,
+        sun_down_occ_hours: int = 0) -> np.float64:
+    """Calculate lower than useful daylight illuminance for a 1D NumPy array.
+
+    Args:
+        array: A 1D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+        sun_down_occ_hours: Number of occupied hours where the sun is down.
+
+    Returns:
+        A NumPy float of the lower than useful daylight illuminance.
+    """
+    check_array_dim(array, 1)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.size
+
+    if min_t == 0:
+        return np.float64(0)
+
+    return np.float64(((array < min_t).sum() + sun_down_occ_hours) / total_occ * 100)
+
+
+def udi_upper_array2d(
+        array: np.ndarray, total_occ: int = None,
+        max_t: float = 3000) -> np.ndarray:
+    """Calculate higher than useful daylight illuminance for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+
+    Returns:
+        A 1-dimensional NumPy array with the higher than useful daylight
+        illuminance for each row in the input array.
+    """
+    check_array_dim(array, 2)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.shape[1]
+
+    if is_cpu:
+        udi = np.apply_along_axis(
+                udi_upper_array1d, 1, array, total_occ=total_occ, max_t=max_t)
+    else:
+        udi = (array > max_t).sum(axis=1) / total_occ * 100
+
+    return udi
+
+
+def udi_upper_array1d(
+        array: np.ndarray, total_occ: int = None,
+        max_t: float = 3000) -> np.float64:
+    """Calculate higher than useful daylight illuminance for a 1D NumPy array.
+
+    Args:
+        array: A 1D NumPy array.
+        total_occ: Integer indicating the number of occupied hours. If not given any
+            input the number of occupied hours will be found by the array shape.
+        max_t: Maximum threshold for higher than useful daylight illuminance.
+            Default: 3000.
+
+    Returns:
+        A NumPy float of the higher than useful daylight illuminance.
+    """
+    check_array_dim(array, 1)
+    if total_occ is None:
+        # set total_occ to number of columns in array
+        total_occ = array.size
+
+    return np.float64((array > max_t).sum() / total_occ * 100)
+
+
+def sda_array2d(
+        array: np.ndarray, target_time: float = 50, threshold: float = 300,
+        total_occ: int = None) -> np.ndarray:
+    """Calculate spatial daylight autonomy for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        target_time: A minimum threshold of occupied time (eg. 50% of the
+            time), above which a given sensor passes and contributes to the
+            spatial daylight autonomy. Defaults to 50.
+        threshold: Threshold value for daylight autonomy. Default: 300.
+        total_occ: Integer indicating the number of occupied hours. If not
+            given any input the number of occupied hours will be found by the
+            array shape, i.e., it is assumed that the array is filtered by
+            occupied hours.
+
+    Returns:
+        A NumPy float of the sDA as a percentage (decimal)
+    """
+    da = np.sum(array >= threshold, axis=1) / total_occ * 100
+    sda = (da >= target_time).mean()
+
+    return sda
+
+
+def ase_array2d(
+        array: np.ndarray, occ_hours: int = 250,
+        direct_threshold: float = 1000) -> Tuple[np.ndarray, np.ndarray]:
+    """Calculate annual sunlight exposure for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        occ_hours: The number of occupied hours that cannot receive more than
+            the direct_threshold. Defaults to 250.
+        direct_threshold: The threshold that determines if a sensor is overlit.
+            Defaults to 1000.
+
+    Returns:
+        A Tuple with two values.
+
+        -   ase: NumPy float of the ASE as a percentage (decimal).
+
+        -   h_above: 1D NumPy array of the number of hours above the direct
+            threshold.
+    """
+    check_array_dim(array, 2)
+    h_above = (array > direct_threshold).sum(axis=1)
+    ase = (h_above >= occ_hours).sum() / array.shape[0] * 100
+
+    return ase, h_above
+
+
+def average_values_array2d(
+        array: np.ndarray, full_length: int = 8760) -> np.ndarray:
+    """Calculate average values for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        full_length: Integer to use as divisor.
+
+    Returns:
+        A 1-dimensional NumPy array with the average value for each row in the
+        input array.
+    """
+    check_array_dim(array, 2)
+
+    avg_values = array.sum(axis=1) / full_length
+
+    return avg_values
+
+
+def average_values_array1d(
+        array: np.ndarray, full_length: int = 8760) -> np.float64:
+    """Calculate average value for a 1D NumPy array.
+
+    Args:
+        array: A 1D NumPy array.
+        full_length: Integer to use as divisor.
+
+    Returns:
+        A NumPy float of the average value.
+    """
+    check_array_dim(array, 1)
+
+    return array.sum() / full_length
+
+
+def cumulative_values_array2d(
+        array: np.ndarray, timestep: int = 1, t_step_multiplier: float = 1
+        ) -> np.ndarray:
+    """Calculate cumulative values for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        timestep: Integer for the timestep of the analysis.
+        t_step_multiplier: A value that will be multiplied with the timestep.
+
+    Returns:
+        A 1-dimensional NumPy array with the cumulative value for each row in
+        the input array.
+    """
+    check_array_dim(array, 2)
+
+    cumulative_values = array.sum(axis=1) / (timestep * t_step_multiplier)
+
+    return cumulative_values
+
+
+def cumulative_values_array1d(
+        array: np.ndarray, timestep: int = 1, t_step_multiplier: float = 1
+        ) -> np.float64:
+    """Calculate daylight autonomy for a 1D NumPy array.
+
+    Args:
+        array: A 1D NumPy array.
+        timestep: Integer for the timestep of the analysis.
+        t_step_multiplier: A value that will be multiplied with the timestep.
+
+    Returns:
+        A NumPy float of the cumulative value.
+    """
+    check_array_dim(array, 1)
+
+    return array.sum() / (timestep * t_step_multiplier)
+
+
+def peak_values_array2d(
+        array: np.ndarray, coincident: bool = False
+        ) -> Tuple[np.ndarray, Union[int, None]]:
+    """Calculate peak values for a 2D NumPy array.
+
+    Args:
+        array: A 2D NumPy array.
+        coincident: Boolean to indicate whether output values represent the
+            peak value for each sensor throughout the entire analysis (False)
+            or they represent the highest overall value across each sensor grid
+            at a particular timestep (True).
+
+    Returns:
+        A 1-dimensional NumPy array with the peak value for each row in the
+        input array, and the index of the maximum value representing the
+        timestep in the array with the largest value.
+    """
+    check_array_dim(array, 2)
+
+    max_i = None
+    if coincident:
+        array_summed = array.sum(axis=0)
+        if np.any(array_summed):
+            max_i = np.argmax(array_summed)
+            peak_values = array[:, max_i]
+        else:
+            peak_values = np.zeros(array.shape[0])
+    else:
+        if np.any(array):
+            peak_values = np.amax(array, axis=1)
+        else:
+            peak_values = np.zeros(array.shape[0])
+
+    return peak_values, max_i