The Pyretechnics Fire Behavior Library
Copyright © 2023-2024 Spatial Informatics Group, LLC

from functools import reduce
import numpy as np

def is_pos_int(x):
    return isinstance(x, int) and x > 0


def divide_evenly(dividend, divisor):
    (quotient, remainder) = divmod(dividend, divisor)
    if remainder == 0:
        return quotient
    else:
        raise ValueError(str(dividend) + " must be an exact multiple of " + str(divisor) + ".")


def to_positive_index_range(index_range, axis_length):
    """
    Translate None and negative indices to positive indices.
    """
    if index_range == None:
        return (0, axis_length)
    else:
        (start, stop) = index_range
        return (
            0 if start == None else axis_length + start if start < 0 else start,
            axis_length if stop == None else axis_length + stop if stop < 0 else stop
        )


def maybe_repeat_array(array, axis_repetitions):
    """
    Return a new array that is created by repeating the elements from the input
    array repetitions times along the specified array axis. Avoid allocating
    new memory if repetitions == 1 or if the repeated array axis has length 1.
    """
    (axis, repetitions) = axis_repetitions
    if repetitions == 1:
        return array
    else:
        array_shape = list(np.shape(array))
        if array_shape[axis] == 1:
            array_shape[axis] = repetitions
            return np.broadcast_to(array, array_shape)
        else:
            return np.repeat(array, repetitions, axis)

class SpaceTimeCube:
    """
    Create an object that represents a 3D array with dimensions (T,Y,X) given by cube_shape.
    Internally, data is stored as a 3D Numpy array at the resolution of the provided base data.
    Whenever a point value or contiguous space-time region of values is requested, translate
    the given cube_shape coordinates into base coordinates, look up the values from the base data,
    expand them (if necessary) back into the cube_shape resolution, and return the resulting scalar
    value or array to the caller.
    """
    def __init__(self, cube_shape, base):
        """
        NOTE: The resolutions in cube_shape must be exact multiples of any existing dimensions
              in the base data.
        """
        # Ensure that cube_shape contains 3 values or throw an error
        (cube_bands, cube_rows, cube_cols) = cube_shape

        # Ensure that cube_shape only contains positive integers or throw an error
        if not(all(map(is_pos_int, cube_shape))):
            raise ValueError("The cube_shape must only contain positive integers.")

        # Store the cube metadata for later
        self.ndim  = 3
        self.size  = cube_bands * cube_rows * cube_cols
        self.shape = cube_shape
        self.base  = base

        match np.ndim(base):
            # 0D: Constant Input
            case 0:
                self.t_repetitions = cube_bands
                self.y_repetitions = cube_rows
                self.x_repetitions = cube_cols
                self.data = np.asarray([[[base]]])

            # 1D: Time-Series Input
            case 1:
                base_bands = len(base)
                self.t_repetitions = divide_evenly(cube_bands, base_bands)
                self.y_repetitions = cube_rows
                self.x_repetitions = cube_cols
                # Expand (base_bands) -> (base_bands,1,1)
                self.data = np.expand_dims(base, axis=(1,2))

            # 2D: Spatial Input
            case 2:
                (base_rows, base_cols) = np.shape(base)
                self.t_repetitions = cube_bands
                self.y_repetitions = divide_evenly(cube_rows, base_rows)
                self.x_repetitions = divide_evenly(cube_cols, base_cols)
                # Expand (base_rows,base_cols) -> (1,base_rows,base_cols)
                self.data = np.expand_dims(base, axis=0)

            # 3D: Spatio-Temporal Input
            case 3:
                (base_bands, base_rows, base_cols) = np.shape(base)
                self.t_repetitions = divide_evenly(cube_bands, base_bands)
                self.y_repetitions = divide_evenly(cube_rows, base_rows)
                self.x_repetitions = divide_evenly(cube_cols, base_cols)
                self.data = np.asarray(base)

            # 4D+: Invalid Input
            case _:
                raise ValueError("Invalid input: base must have 0-3 dimensions.")


    def get(self, t, y, x):
        """
        Return the scalar value at index (t,y,x) by translating these cube coordinates
        to base coordinates and looking up the value within the base data.

        NOTE: Indices may be negative.
        """
        # Select value by spatio-temporal coordinate
        return self.data[t // self.t_repetitions,
                         y // self.y_repetitions,
                         x // self.x_repetitions]


    def getTimeSeries(self, t_range, y, x):
        """
        Return the 1D array given by the slice (t_range,y,x) by translating these cube
        coordinates to base coordinates, looking up the array slice within the base data,
        and expanding it back to the cube_shape resolution.

        NOTE: Indices may be negative.
        NOTE: Range indices may include one or more None values and
              provide (inclusion, exclusion) semantics like Python array slice notation.
        """
        # Destructure the argument range
        (t_start, t_stop_exclusive) = to_positive_index_range(t_range, self.shape[0])
        t_stop = t_stop_exclusive - 1
        # Translate high-res coordinates to low-res coordinates
        t_start_chunk = t_start // self.t_repetitions
        t_stop_chunk  = t_stop  // self.t_repetitions
        y_chunk       = y       // self.y_repetitions
        x_chunk       = x       // self.x_repetitions
        # Select the array slice that completely contains all low-res coordinates
        low_res_time = self.data[t_start_chunk:(t_stop_chunk + 1),
                                 y_chunk,
                                 x_chunk]
        # Expand the low-res slice into a high-res slice
        high_res_time = maybe_repeat_array(low_res_time, (0, self.t_repetitions))
        # Translate high-res global coordinates to high-res slice coordinates
        t_chunk_origin = t_start_chunk * self.t_repetitions
        t_start_idx    = t_start - t_chunk_origin
        t_stop_idx     = t_stop  - t_chunk_origin
        # Select the array slice that matches the high-res slice coordinates
        return high_res_time[t_start_idx:(t_stop_idx + 1)]


    def getSpatialPlane(self, t, y_range, x_range):
        """
        Return the 2D array given by the slice (t,y_range,x_range) by translating these
        cube coordinates to base coordinates, looking up the array slice within the base
        data, and expanding it back to the cube_shape resolution.

        NOTE: Indices may be negative.
        NOTE: Range indices may include one or more None values and
              provide (inclusion, exclusion) semantics like Python array slice notation.
        """
        # Destructure the argument ranges
        (y_start, y_stop_exclusive) = to_positive_index_range(y_range, self.shape[1])
        (x_start, x_stop_exclusive) = to_positive_index_range(x_range, self.shape[2])
        y_stop = y_stop_exclusive - 1
        x_stop = x_stop_exclusive - 1
        # Translate high-res coordinates to low-res coordinates
        t_chunk       = t       // self.t_repetitions
        y_start_chunk = y_start // self.y_repetitions
        y_stop_chunk  = y_stop  // self.y_repetitions
        x_start_chunk = x_start // self.x_repetitions
        x_stop_chunk  = x_stop  // self.x_repetitions
        # Select the array slice that completely contains all low-res coordinates
        low_res_space = self.data[t_chunk,
                                  y_start_chunk:(y_stop_chunk + 1),
                                  x_start_chunk:(x_stop_chunk + 1)]
        # Expand the low-res slice into a high-res slice
        high_res_space = reduce(maybe_repeat_array,
                                ((0, self.y_repetitions),
                                 (1, self.x_repetitions)),
                                low_res_space)
        # Translate high-res global coordinates to high-res slice coordinates
        y_chunk_origin = y_start_chunk * self.y_repetitions
        x_chunk_origin = x_start_chunk * self.x_repetitions
        y_start_idx    = y_start - y_chunk_origin
        y_stop_idx     = y_stop  - y_chunk_origin
        x_start_idx    = x_start - x_chunk_origin
        x_stop_idx     = x_stop  - x_chunk_origin
        # Select the array slice that matches the high-res slice coordinates
        return high_res_space[y_start_idx:(y_stop_idx + 1),
                              x_start_idx:(x_stop_idx + 1)]


    def getSubcube(self, t_range, y_range, x_range):
        """
        Return the 3D array given by the slice (t_range,y_range,x_range) by translating
        these cube coordinates to base coordinates, looking up the array slice within the
        base data, and expanding it back to the cube_shape resolution.

        NOTE: Indices may be negative.
        NOTE: Range indices may include one or more None values and
              provide (inclusion, exclusion) semantics like Python array slice notation.
        """
        # Destructure the argument ranges
        (t_start, t_stop_exclusive) = to_positive_index_range(t_range, self.shape[0])
        (y_start, y_stop_exclusive) = to_positive_index_range(y_range, self.shape[1])
        (x_start, x_stop_exclusive) = to_positive_index_range(x_range, self.shape[2])
        t_stop = t_stop_exclusive - 1
        y_stop = y_stop_exclusive - 1
        x_stop = x_stop_exclusive - 1
        # Translate high-res coordinates to low-res coordinates
        t_start_chunk = t_start // self.t_repetitions
        t_stop_chunk  = t_stop  // self.t_repetitions
        y_start_chunk = y_start // self.y_repetitions
        y_stop_chunk  = y_stop  // self.y_repetitions
        x_start_chunk = x_start // self.x_repetitions
        x_stop_chunk  = x_stop  // self.x_repetitions
        # Select the array slice that completely contains all low-res coordinates
        low_res_cube = self.data[t_start_chunk:(t_stop_chunk + 1),
                                 y_start_chunk:(y_stop_chunk + 1),
                                 x_start_chunk:(x_stop_chunk + 1)]
        # Expand the low-res slice into a high-res slice
        high_res_cube = reduce(maybe_repeat_array,
                               ((0, self.t_repetitions),
                                (1, self.y_repetitions),
                                (2, self.x_repetitions)),
                               low_res_cube)
        # Translate high-res global coordinates to high-res slice coordinates
        t_chunk_origin = t_start_chunk * self.t_repetitions
        y_chunk_origin = y_start_chunk * self.y_repetitions
        x_chunk_origin = x_start_chunk * self.x_repetitions
        t_start_idx    = t_start - t_chunk_origin
        t_stop_idx     = t_stop  - t_chunk_origin
        y_start_idx    = y_start - y_chunk_origin
        y_stop_idx     = y_stop  - y_chunk_origin
        x_start_idx    = x_start - x_chunk_origin
        x_stop_idx     = x_stop  - x_chunk_origin
        # Select the array slice that matches the high-res slice coordinates
        return high_res_cube[t_start_idx:(t_stop_idx + 1),
                             y_start_idx:(y_stop_idx + 1),
                             x_start_idx:(x_stop_idx + 1)]


    def __getFullyRealizedCube(self):
        """
        Return the 3D array created by expanding the base data to the cube_shape resolution.
        Wherever possible, Numpy broadcasting is used to avoid memory allocation along
        constant array dimensions.
        """
        match np.ndim(self.base):
            # 0D: Constant Input
            case 0:
                # Broadcast (0,0,0) -> (t,y,x)
                return np.broadcast_to(self.data, self.shape)

            # 1D: Time-Series Input
            case 1:
                # Repeat (t0,1,1) -> (t,1,1)
                repeated_array = maybe_repeat_array(self.data, (0, self.t_repetitions))
                # Broadcast (t,1,1) -> (t,y,x)
                return np.broadcast_to(repeated_array, self.shape)

            # 2D: Spatial Input
            case 2:
                # Repeat (1,y0,x0) -> (1,y,x)
                repeated_array = reduce(maybe_repeat_array,
                                        ((1, self.y_repetitions),
                                         (2, self.x_repetitions)),
                                        self.data)
                # Broadcast (1,y,x) -> (t,y,x)
                return np.broadcast_to(repeated_array, self.shape)

            # 3D: Spatio-Temporal Input
            case 3:
                # Repeat (t0,y0,x0) -> (t,y,x)
                return reduce(maybe_repeat_array,
                              ((0, self.t_repetitions),
                               (1, self.y_repetitions),
                               (2, self.x_repetitions)),
                              self.data)


    def getFullyRealizedCube(self, cache=False):
        """
        Return the 3D array created by expanding the base data to the cube_shape resolution.
        Wherever possible, Numpy broadcasting is used to avoid memory allocation along
        constant array dimensions. When cache == True, this expanded 3D array is cached
        within the SpaceTimeCube object for future immediate retrieval.
        """
        if hasattr(self, "cube"):
            return self.cube
        else:
            cube = self.__getFullyRealizedCube()
            if cache is True:
                self.cube = cube
            return cube


    def releaseFullyRealizedCube(self):
        """
        Deletes the cached fully realized cube if it exists.
        """
        if hasattr(self, "cube"):
            delattr(self, "cube")

class LazySpaceTimeCube:
    """
    Create an object that represents a 3D array with dimensions (T,Y,X) given by cube_shape.
    Internally, data is stored as an initially empty 3D array of SpaceTimeCube objects.
    Whenever a point value or contiguous space-time region of values is requested, identify
    which SpaceTimeCubes contain the requested coordinates, load them into the cache array
    by calling load_subcube for any that are not already present, request the values from
    these SpaceTimeCubes, combine them together if necessary, and return the resulting scalar
    value or array to the caller.
    """
    def __init__(self, cube_shape, subcube_shape, load_subcube):
        """
        NOTE: The resolutions in cube_shape must be exact multiples of those in subcube_shape.
        """
        # Ensure that cube_shape and subcube_shape both contain 3 values or throw an error
        (cube_bands, cube_rows, cube_cols) = cube_shape
        (subcube_bands, subcube_rows, subcube_cols) = subcube_shape

        # Ensure that cube_shape and subcube_shape only contain positive integers or throw an error
        if not(all(map(is_pos_int, cube_shape + subcube_shape))):
            raise ValueError("The cube_shape and subcube_shape must only contain positive integers.")

        # Ensure that cube_shape is divided evenly by subcube_shape or throw an error
        cache_bands = divide_evenly(cube_bands, subcube_bands)
        cache_rows  = divide_evenly(cube_rows, subcube_rows)
        cache_cols  = divide_evenly(cube_cols, subcube_cols)

        # Store the cube metadata, subcube_shape, cache_shape, cache, and load_subcube functions for later
        self.ndim          = 3
        self.size          = cube_bands * cube_rows * cube_cols
        self.shape         = cube_shape
        self.subcube_shape = subcube_shape
        self.cache_shape   = (cache_bands, cache_rows, cache_cols)
        self.cache         = np.empty(self.cache_shape, dtype=object)
        self.load_subcube  = load_subcube


    def __getOrLoadSubcube(self, cache_t, cache_y, cache_x):
        """
        Return the SpaceTimeCube stored at self.cache[cache_t, cache_y, cache_x] if it
        has already been loaded. Otherwise, call self.load_subcube to load it, store
        it in self.cache, and return it.
        """
        subcube = self.cache[cache_t, cache_y, cache_x]
        if subcube:
            return subcube
        else:
            subcube = self.load_subcube((cache_t, cache_y, cache_x), self.subcube_shape)
            self.cache[cache_t, cache_y, cache_x] = subcube
            return subcube


    def get(self, t, y, x):
        """
        Return the scalar value at index (t,y,x) by translating these cube coordinates
        to cache and subcube coordinates, loading the matching subcube into the cache grid
        if not already present, and looking up the value within this subcube.

        NOTE: Indices may be negative provided that your load_subcube function can handle
              negative indices in its cache_index argument.
        """
        (subcube_bands, subcube_rows, subcube_cols) = self.subcube_shape
        (cache_t, subcube_t) = divmod(t, subcube_bands)
        (cache_y, subcube_y) = divmod(y, subcube_rows)
        (cache_x, subcube_x) = divmod(x, subcube_cols)
        subcube = self.__getOrLoadSubcube(cache_t, cache_y, cache_x)
        return subcube.get(subcube_t, subcube_y, subcube_x)


    def getTimeSeries(self, t_range, y, x):
        """
        Return the 1D array given by the slice (t_range,y,x) by translating these cube
        coordinates to cache and subcube coordinates, loading the matching subcubes into
        the cache grid if not already present, looking up the array slices within each
        subcube, and merging them together into a single 1D array.

        NOTE: Indices may be negative provided that your load_subcube function can handle
              negative indices in its cache_index argument.
        NOTE: Range indices may include one or more None values and
              provide (inclusion, exclusion) semantics like Python array slice notation.
        """
        # Destructure the argument range
        (t_start, t_stop_exclusive) = to_positive_index_range(t_range, self.shape[0])
        t_stop = t_stop_exclusive - 1
        # Translate high-res coordinates to cache and subcube coordinates
        (subcube_bands, subcube_rows, subcube_cols) = self.subcube_shape
        (cache_t_start, subcube_t_start) = divmod(t_start, subcube_bands)
        (cache_t_stop,  subcube_t_stop)  = divmod(t_stop,  subcube_bands)
        (cache_y,       subcube_y)       = divmod(y,       subcube_rows)
        (cache_x,       subcube_x)       = divmod(x,       subcube_cols)
        # Load, expand, and combine subcubes
        return np.concatenate(
            [self.__getOrLoadSubcube(cache_t,
                                     cache_y,
                                     cache_x
                                    ).getTimeSeries(
                                        (subcube_t_start    if cache_t == cache_t_start else 0,
                                         subcube_t_stop + 1 if cache_t == cache_t_stop  else subcube_bands),
                                        subcube_y,
                                        subcube_x
                                    )
             for cache_t in range(cache_t_start, cache_t_stop + 1)]
        )


    def getSpatialPlane(self, t, y_range, x_range):
        """
        Return the 2D array given by the slice (t,y_range,x_range) by translating these
        cube coordinates to cache and subcube coordinates, loading the matching subcubes
        into the cache grid if not already present, looking up the array slices within each
        subcube, and merging them together into a single 2D array.

        NOTE: Indices may be negative provided that your load_subcube function can handle
              negative indices in its cache_index argument.
        NOTE: Range indices may include one or more None values and
              provide (inclusion, exclusion) semantics like Python array slice notation.
        """
        # Destructure the argument ranges
        (y_start, y_stop_exclusive) = to_positive_index_range(y_range, self.shape[1])
        (x_start, x_stop_exclusive) = to_positive_index_range(x_range, self.shape[2])
        y_stop = y_stop_exclusive - 1
        x_stop = x_stop_exclusive - 1
        # Translate high-res coordinates to cache and subcube coordinates
        (subcube_bands, subcube_rows, subcube_cols) = self.subcube_shape
        (cache_t,       subcube_t)       = divmod(t,       subcube_bands)
        (cache_y_start, subcube_y_start) = divmod(y_start, subcube_rows)
        (cache_y_stop,  subcube_y_stop)  = divmod(y_stop,  subcube_rows)
        (cache_x_start, subcube_x_start) = divmod(x_start, subcube_cols)
        (cache_x_stop,  subcube_x_stop)  = divmod(x_stop,  subcube_cols)
        # Load, expand, and combine subcubes
        return np.block(
            [[self.__getOrLoadSubcube(cache_t,
                                      cache_y,
                                      cache_x
                                      ).getSpatialPlane(
                                          subcube_t,
                                          (subcube_y_start    if cache_y == cache_y_start else 0,
                                           subcube_y_stop + 1 if cache_y == cache_y_stop  else subcube_rows),
                                          (subcube_x_start    if cache_x == cache_x_start else 0,
                                           subcube_x_stop + 1 if cache_x == cache_x_stop  else subcube_cols)
                                      )
              for cache_x in range(cache_x_start, cache_x_stop + 1)]
             for cache_y in range(cache_y_start, cache_y_stop + 1)]
        )


    def getSubcube(self, t_range, y_range, x_range):
        """
        Return the 3D array given by the slice (t_range,y_range,x_range) by translating
        these cube coordinates to cache and subcube coordinates, loading the matching
        subcubes into the cache grid if not already present, looking up the array slices
        within each subcube, and merging them together into a single 3D array.

        NOTE: Indices may be negative provided that your load_subcube function can handle
              negative indices in its cache_index argument.
        NOTE: Range indices may include one or more None values and
              provide (inclusion, exclusion) semantics like Python array slice notation.
        """
        # Destructure the argument ranges
        (t_start, t_stop_exclusive) = to_positive_index_range(t_range, self.shape[0])
        (y_start, y_stop_exclusive) = to_positive_index_range(y_range, self.shape[1])
        (x_start, x_stop_exclusive) = to_positive_index_range(x_range, self.shape[2])
        t_stop = t_stop_exclusive - 1
        y_stop = y_stop_exclusive - 1
        x_stop = x_stop_exclusive - 1
        # Translate high-res coordinates to cache and subcube coordinates
        (subcube_bands, subcube_rows, subcube_cols) = self.subcube_shape
        (cache_t_start, subcube_t_start) = divmod(t_start, subcube_bands)
        (cache_t_stop,  subcube_t_stop)  = divmod(t_stop,  subcube_bands)
        (cache_y_start, subcube_y_start) = divmod(y_start, subcube_rows)
        (cache_y_stop,  subcube_y_stop)  = divmod(y_stop,  subcube_rows)
        (cache_x_start, subcube_x_start) = divmod(x_start, subcube_cols)
        (cache_x_stop,  subcube_x_stop)  = divmod(x_stop,  subcube_cols)
        # Load, expand, and combine subcubes
        return np.block(
            [[[self.__getOrLoadSubcube(cache_t,
                                       cache_y,
                                       cache_x
                                       ).getSubcube(
                                           (subcube_t_start    if cache_t == cache_t_start else 0,
                                            subcube_t_stop + 1 if cache_t == cache_t_stop  else subcube_bands),
                                           (subcube_y_start    if cache_y == cache_y_start else 0,
                                            subcube_y_stop + 1 if cache_y == cache_y_stop  else subcube_rows),
                                           (subcube_x_start    if cache_x == cache_x_start else 0,
                                            subcube_x_stop + 1 if cache_x == cache_x_stop  else subcube_cols)
                                       )
               for cache_x in range(cache_x_start, cache_x_stop + 1)]
              for cache_y in range(cache_y_start, cache_y_stop + 1)]
             for cache_t in range(cache_t_start, cache_t_stop + 1)]
        )


    def getFullyRealizedCube(self, cache=False):
        raise ValueError("getFullyRealizedCube is not implemented for LazySpaceTimeCube.\n"
                         + "You probably don't want to do this anyway.")


    def releaseFullyRealizedCube(self):
        raise ValueError("releaseFullyRealizedCube is not implemented for LazySpaceTimeCube.\n"
                         + "You probably don't want to do this anyway.")

# Lookup table including entries for each of the Anderson 13 and Scott & Burgan 40 fuel models.
#
# The fields have the following meanings:
#   {fuel-model-number : [name, delta, M_x-dead, h, w_o, sigma]}
#
# where:
#   w_o   = [  w_o-dead-1hr,   w_o-dead-10hr,   w_o-dead-100hr,   w_o-live-herbaceous,   w_o-live-woody]
#   sigma = [sigma-dead-1hr, sigma-dead-10hr, sigma-dead-100hr, sigma-live-herbaceous, sigma-live-woody]
fuel_model_compact_table = {
    # Anderson 13:
    # Grass and Grass-dominated (short-grass,timber-grass-and-understory,tall-grass)
    1   : ["R01", 1.0, 12, 8, [0.0340, 0.0000, 0.0000, 0.0000, 0.0000], [3500.0,   0.0,  0.0,    0.0,    0.0]],
    2   : ["R02", 1.0, 15, 8, [0.0920, 0.0460, 0.0230, 0.0230, 0.0000], [3000.0, 109.0, 30.0, 1500.0,    0.0]],
    3   : ["R03", 2.5, 25, 8, [0.1380, 0.0000, 0.0000, 0.0000, 0.0000], [1500.0,   0.0,  0.0,    0.0,    0.0]],
    # Chaparral and Shrubfields (chaparral,brush,dormant-brush-hardwood-slash,southern-rough)
    4   : ["R04", 6.0, 20, 8, [0.2300, 0.1840, 0.0920, 0.2300, 0.0000], [2000.0, 109.0, 30.0, 1500.0,    0.0]],
    5   : ["R05", 2.0, 20, 8, [0.0460, 0.0230, 0.0000, 0.0920, 0.0000], [2000.0, 109.0,  0.0, 1500.0,    0.0]],
    6   : ["R06", 2.5, 25, 8, [0.0690, 0.1150, 0.0920, 0.0000, 0.0000], [1750.0, 109.0, 30.0,    0.0,    0.0]],
    7   : ["R07", 2.5, 40, 8, [0.0520, 0.0860, 0.0690, 0.0170, 0.0000], [1750.0, 109.0, 30.0, 1550.0,    0.0]],
    # Timber Litter (closed-timber-litter,hardwood-litter,timber-litter-and-understory)
    8   : ["R08", 0.2, 30, 8, [0.0690, 0.0460, 0.1150, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    9   : ["R09", 0.2, 25, 8, [0.1340, 0.0190, 0.0070, 0.0000, 0.0000], [2500.0, 109.0, 30.0,    0.0,    0.0]],
    10  : ["R10", 1.0, 25, 8, [0.1380, 0.0920, 0.2300, 0.0920, 0.0000], [2000.0, 109.0, 30.0, 1500.0,    0.0]],
    # Logging Slash (light-logging-slash,medium-logging-slash,heavy-logging-slash)
    11  : ["R11", 1.0, 15, 8, [0.0690, 0.2070, 0.2530, 0.0000, 0.0000], [1500.0, 109.0, 30.0,    0.0,    0.0]],
    12  : ["R12", 2.3, 20, 8, [0.1840, 0.6440, 0.7590, 0.0000, 0.0000], [1500.0, 109.0, 30.0,    0.0,    0.0]],
    13  : ["R13", 3.0, 25, 8, [0.3220, 1.0580, 1.2880, 0.0000, 0.0000], [1500.0, 109.0, 30.0,    0.0,    0.0]],
    # Nonburnable (NB)
    91  : ["NB1", 0.0,  0, 0, [0.0000, 0.0000, 0.0000, 0.0000, 0.0000], [   0.0,   0.0,  0.0,    0.0,    0.0]],
    92  : ["NB2", 0.0,  0, 0, [0.0000, 0.0000, 0.0000, 0.0000, 0.0000], [   0.0,   0.0,  0.0,    0.0,    0.0]],
    93  : ["NB3", 0.0,  0, 0, [0.0000, 0.0000, 0.0000, 0.0000, 0.0000], [   0.0,   0.0,  0.0,    0.0,    0.0]],
    98  : ["NB4", 0.0,  0, 0, [0.0000, 0.0000, 0.0000, 0.0000, 0.0000], [   0.0,   0.0,  0.0,    0.0,    0.0]],
    99  : ["NB5", 0.0,  0, 0, [0.0000, 0.0000, 0.0000, 0.0000, 0.0000], [   0.0,   0.0,  0.0,    0.0,    0.0]],
    # Scott & Burgan 40:
    # Grass (GR)
    101 : ["GR1", 0.4, 15, 8, [0.0046, 0.0000, 0.0000, 0.0138, 0.0000], [2200.0, 109.0, 30.0, 2000.0,    0.0]],
    102 : ["GR2", 1.0, 15, 8, [0.0046, 0.0000, 0.0000, 0.0459, 0.0000], [2000.0, 109.0, 30.0, 1800.0,    0.0]],
    103 : ["GR3", 2.0, 30, 8, [0.0046, 0.0184, 0.0000, 0.0689, 0.0000], [1500.0, 109.0, 30.0, 1300.0,    0.0]],
    104 : ["GR4", 2.0, 15, 8, [0.0115, 0.0000, 0.0000, 0.0872, 0.0000], [2000.0, 109.0, 30.0, 1800.0,    0.0]],
    105 : ["GR5", 1.5, 40, 8, [0.0184, 0.0000, 0.0000, 0.1148, 0.0000], [1800.0, 109.0, 30.0, 1600.0,    0.0]],
    106 : ["GR6", 1.5, 40, 9, [0.0046, 0.0000, 0.0000, 0.1561, 0.0000], [2200.0, 109.0, 30.0, 2000.0,    0.0]],
    107 : ["GR7", 3.0, 15, 8, [0.0459, 0.0000, 0.0000, 0.2479, 0.0000], [2000.0, 109.0, 30.0, 1800.0,    0.0]],
    108 : ["GR8", 4.0, 30, 8, [0.0230, 0.0459, 0.0000, 0.3352, 0.0000], [1500.0, 109.0, 30.0, 1300.0,    0.0]],
    109 : ["GR9", 5.0, 40, 8, [0.0459, 0.0459, 0.0000, 0.4132, 0.0000], [1800.0, 109.0, 30.0, 1600.0,    0.0]],
    # Grass-Shrub (GS)
    121 : ["GS1", 0.9, 15, 8, [0.0092, 0.0000, 0.0000, 0.0230, 0.0298], [2000.0, 109.0, 30.0, 1800.0, 1800.0]],
    122 : ["GS2", 1.5, 15, 8, [0.0230, 0.0230, 0.0000, 0.0275, 0.0459], [2000.0, 109.0, 30.0, 1800.0, 1800.0]],
    123 : ["GS3", 1.8, 40, 8, [0.0138, 0.0115, 0.0000, 0.0666, 0.0574], [1800.0, 109.0, 30.0, 1600.0, 1600.0]],
    124 : ["GS4", 2.1, 40, 8, [0.0872, 0.0138, 0.0046, 0.1561, 0.3260], [1800.0, 109.0, 30.0, 1600.0, 1600.0]],
    # Shrub (SH)
    141 : ["SH1", 1.0, 15, 8, [0.0115, 0.0115, 0.0000, 0.0069, 0.0597], [2000.0, 109.0, 30.0, 1800.0, 1600.0]],
    142 : ["SH2", 1.0, 15, 8, [0.0620, 0.1102, 0.0344, 0.0000, 0.1768], [2000.0, 109.0, 30.0,    0.0, 1600.0]],
    143 : ["SH3", 2.4, 40, 8, [0.0207, 0.1377, 0.0000, 0.0000, 0.2847], [1600.0, 109.0, 30.0,    0.0, 1400.0]],
    144 : ["SH4", 3.0, 30, 8, [0.0390, 0.0528, 0.0092, 0.0000, 0.1171], [2000.0, 109.0, 30.0, 1800.0, 1600.0]],
    145 : ["SH5", 6.0, 15, 8, [0.1653, 0.0964, 0.0000, 0.0000, 0.1331], [ 750.0, 109.0, 30.0,    0.0, 1600.0]],
    146 : ["SH6", 2.0, 30, 8, [0.1331, 0.0666, 0.0000, 0.0000, 0.0643], [ 750.0, 109.0, 30.0,    0.0, 1600.0]],
    147 : ["SH7", 6.0, 15, 8, [0.1607, 0.2433, 0.1010, 0.0000, 0.1561], [ 750.0, 109.0, 30.0,    0.0, 1600.0]],
    148 : ["SH8", 3.0, 40, 8, [0.0941, 0.1561, 0.0390, 0.0000, 0.1997], [ 750.0, 109.0, 30.0,    0.0, 1600.0]],
    149 : ["SH9", 4.4, 40, 8, [0.2066, 0.1125, 0.0000, 0.0712, 0.3214], [ 750.0, 109.0, 30.0, 1800.0, 1500.0]],
    # Timber-Understory (TU)
    161 : ["TU1", 0.6, 20, 8, [0.0092, 0.0413, 0.0689, 0.0092, 0.0413], [2000.0, 109.0, 30.0, 1800.0, 1600.0]],
    162 : ["TU2", 1.0, 30, 8, [0.0436, 0.0826, 0.0574, 0.0000, 0.0092], [2000.0, 109.0, 30.0,    0.0, 1600.0]],
    163 : ["TU3", 1.3, 30, 8, [0.0505, 0.0069, 0.0115, 0.0298, 0.0505], [1800.0, 109.0, 30.0, 1600.0, 1400.0]],
    164 : ["TU4", 0.5, 12, 8, [0.2066, 0.0000, 0.0000, 0.0000, 0.0918], [2300.0, 109.0, 30.0,    0.0, 2000.0]],
    165 : ["TU5", 1.0, 25, 8, [0.1837, 0.1837, 0.1377, 0.0000, 0.1377], [1500.0, 109.0, 30.0,    0.0,  750.0]],
    # Timber Litter (TL)
    181 : ["TL1", 0.2, 30, 8, [0.0459, 0.1010, 0.1653, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    182 : ["TL2", 0.2, 25, 8, [0.0643, 0.1056, 0.1010, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    183 : ["TL3", 0.3, 20, 8, [0.0230, 0.1010, 0.1286, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    184 : ["TL4", 0.4, 25, 8, [0.0230, 0.0689, 0.1928, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    185 : ["TL5", 0.6, 25, 8, [0.0528, 0.1148, 0.2020, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0, 1600.0]],
    186 : ["TL6", 0.3, 25, 8, [0.1102, 0.0551, 0.0551, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    187 : ["TL7", 0.4, 25, 8, [0.0138, 0.0643, 0.3719, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    188 : ["TL8", 0.3, 35, 8, [0.2663, 0.0643, 0.0505, 0.0000, 0.0000], [1800.0, 109.0, 30.0,    0.0,    0.0]],
    189 : ["TL9", 0.6, 35, 8, [0.3053, 0.1515, 0.1905, 0.0000, 0.0000], [1800.0, 109.0, 30.0,    0.0, 1600.0]],
    # Slash-Blowdown (SB)
    201 : ["SB1", 1.0, 25, 8, [0.0689, 0.1377, 0.5051, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    202 : ["SB2", 1.0, 25, 8, [0.2066, 0.1951, 0.1837, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    203 : ["SB3", 1.2, 25, 8, [0.2525, 0.1263, 0.1377, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
    204 : ["SB4", 2.7, 25, 8, [0.2410, 0.1607, 0.2410, 0.0000, 0.0000], [2000.0, 109.0, 30.0,    0.0,    0.0]],
}

def expand_compact_fuel_model(fuel_model_number):
    [name, delta, M_x_dead, h, w_o, sigma] = fuel_model_compact_table[fuel_model_number]
    [w_o_dead_1hr, w_o_dead_10hr, w_o_dead_100hr, w_o_live_herbaceous, w_o_live_woody] = w_o
    [sigma_dead_1hr, sigma_dead_10hr, sigma_dead_100hr, sigma_live_herbaceous, sigma_live_woody] = sigma
    M_x_dead = M_x_dead * 0.01
    h        = h * 1000.0
    # Conditionally set dead_herbaceous values
    dynamic               = fuel_model_number > 100 and w_o_live_herbaceous > 0.0
    M_x_dead_herbaceous   = M_x_dead              if dynamic else 0.0
    sigma_dead_herbaceous = sigma_live_herbaceous if dynamic else 0.0
    return {
        "name"    : name,
        "number"  : fuel_model_number,
        "delta"   : delta,
        "M_x"     : [M_x_dead, M_x_dead, M_x_dead, M_x_dead_herbaceous, 0.0, 0.0],
        "w_o"     : [w_o_dead_1hr, w_o_dead_10hr, w_o_dead_100hr, 0.0, w_o_live_herbaceous, w_o_live_woody],
        "sigma"   : [sigma_dead_1hr, sigma_dead_10hr, sigma_dead_100hr, sigma_dead_herbaceous, sigma_live_herbaceous, sigma_live_woody],
        "h"       : 6 * [h],
        "rho_p"   : 6 * [32.0],
        "S_T"     : 6 * [0.0555],
        "S_e"     : 6 * [0.01],
        "dynamic" : dynamic,
        "burnable": not (91 <= fuel_model_number <= 99),
    }


fuel_model_table = {k: expand_compact_fuel_model(k) for k in fuel_model_compact_table.keys()}

def map_category(f):
    return [f(0), f(1)]


def map_size_class(f):
    return [f(0), f(1), f(2), f(3), f(4), f(5)]


def category_sum(f):
    return f(0) + f(1)


def size_class_sum(f):
    return [f(0) + f(1) + f(2) + f(3), f(4) + f(5)]

def add_dynamic_fuel_loading(fuel_model, M_f):
    if fuel_model["dynamic"]:
        # dynamic fuel model
        w_o                       = fuel_model["w_o"]
        live_herbaceous_load      = w_o[4]
        live_herbaceous_moisture  = M_f[4]
        fraction_green            = max(0.0, min(1.0, (live_herbaceous_moisture / 0.9) - 0.3333333333333333))
        fraction_cured            = 1.0 - fraction_green
        dynamic_fuel_model        = fuel_model.copy() # shallow copy
        dynamic_fuel_model["M_f"] = [
            M_f[0],
            M_f[1],
            M_f[2],
            M_f[0], # set dead_herbaceous to dead_1hr
            M_f[4],
            M_f[5],
        ]
        dynamic_fuel_model["w_o"] = [
            w_o[0],
            w_o[1],
            w_o[2],
            live_herbaceous_load * fraction_cured, # dead_herbaceous
            live_herbaceous_load * fraction_green, # live_herbaceous
            w_o[5],
        ]
        return dynamic_fuel_model
    else:
        # static fuel model
        static_fuel_model = fuel_model.copy() # shallow copy
        static_fuel_model["M_f"] = M_f
        return static_fuel_model

def add_weighting_factors(fuel_model):
    w_o                         = fuel_model["w_o"]
    sigma                       = fuel_model["sigma"]
    rho_p                       = fuel_model["rho_p"]
    A_ij                        = map_size_class(lambda i: (sigma[i] * w_o[i]) / rho_p[i])
    A_i                         = size_class_sum(lambda i: A_ij[i])
    A_T                         = category_sum(lambda i: A_i[i])
    f_ij                        = map_size_class(lambda i: (lambda A: (A_ij[i] / A) if A > 0.0 else 0.0)(A_i[i//4]))
    f_i                         = map_category(lambda i: (A_i[i] / A_T) if A_T > 0.0 else 0.0)
    firemod_size_classes        = map_size_class(lambda i: (lambda s:
                                                            1 if (s >= 1200.0)
                                                            else 2 if (s >= 192.0)
                                                            else 3 if (s >= 96.0)
                                                            else 4 if (s >= 48.0)
                                                            else 5 if (s >= 16.0)
                                                            else 6
                                                            )(sigma[i]))
    g_ij                        = map_size_class(lambda i: (lambda c:
                                                            ((f_ij[0] if (c == firemod_size_classes[0]) else 0.0)
                                                             + (f_ij[1] if (c == firemod_size_classes[1]) else 0.0)
                                                             + (f_ij[2] if (c == firemod_size_classes[2]) else 0.0)
                                                             + (f_ij[3] if (c == firemod_size_classes[3]) else 0.0))
                                                            if (i < 4) else
                                                            ((f_ij[4] if (c == firemod_size_classes[4]) else 0.0)
                                                             + (f_ij[5] if (c == firemod_size_classes[5]) else 0.0))
                                                            )(firemod_size_classes[i]))
    weighted_fuel_model         = fuel_model.copy() # shallow copy
    weighted_fuel_model["f_ij"] = f_ij
    weighted_fuel_model["f_i"]  = f_i
    weighted_fuel_model["g_ij"] = g_ij
    return weighted_fuel_model

from math import exp

def add_live_moisture_of_extinction(fuel_model):
    """
    Equation 88 from Rothermel 1972 adjusted by Albini 1976 Appendix III.
    """
    w_o                       = fuel_model["w_o"]
    sigma                     = fuel_model["sigma"]
    M_f                       = fuel_model["M_f"]
    M_x                       = fuel_model["M_x"]
    loading_factors           = map_size_class(lambda i:
                                               (lambda sigma_ij, A:
                                                w_o[i] * exp(A / sigma_ij) if (sigma_ij > 0.0) else 0.0
                                                )(sigma[i], -138.0 if (i < 4) else -500.0))
    [dead_loading_factor,
     live_loading_factor]     = size_class_sum(lambda i: loading_factors[i])
    [dead_moisture_factor, _] = size_class_sum(lambda i: M_f[i] * loading_factors[i])
    dead_to_live_ratio        = (dead_loading_factor / live_loading_factor) if (live_loading_factor > 0.0) else None
    dead_fuel_moisture        = (dead_moisture_factor / dead_loading_factor) if (dead_loading_factor > 0.0) else 0.0
    M_x_dead                  = M_x[0]
    M_x_live                  = max(M_x_dead,
                                    (2.9 * dead_to_live_ratio * (1.0 - (dead_fuel_moisture / M_x_dead))) - 0.226
                                    ) if (live_loading_factor > 0.0) else M_x_dead
    moisturized_fuel_model    = fuel_model.copy() # shallow copy
    moisturized_fuel_model["M_x"] = [
        M_x[0],
        M_x[1],
        M_x[2],
        M_x[3],
        M_x_live,
        M_x_live,
    ]
    return moisturized_fuel_model

# TODO: If these functions aren't called anywhere else, create a copy
#       of the fuel model here and mutate it in the called functions.
def moisturize(fuel_model, fuel_moisture):
    dynamic_fuel_model     = add_dynamic_fuel_loading(fuel_model, fuel_moisture)
    weighted_fuel_model    = add_weighting_factors(dynamic_fuel_model)
    moisturized_fuel_model = add_live_moisture_of_extinction(weighted_fuel_model)
    return moisturized_fuel_model

from pprint import pprint
from pyretechnics.fuel_models import fuel_model_table

static_fuel_model_number  = 1   # R01
dynamic_fuel_model_number = 101 # GR1

static_fuel_model  = fuel_model_table.get(static_fuel_model_number)
dynamic_fuel_model = fuel_model_table.get(dynamic_fuel_model_number)

print("Static Fuel Model: R01")
pprint(static_fuel_model)

print("\nDynamic Fuel Model: GR1")
pprint(dynamic_fuel_model)

from pprint import pprint
from pyretechnics.fuel_models import fuel_model_table, moisturize

static_fuel_model_number  = 1   # R01
dynamic_fuel_model_number = 101 # GR1

static_fuel_model  = fuel_model_table.get(static_fuel_model_number)
dynamic_fuel_model = fuel_model_table.get(dynamic_fuel_model_number)

fuel_moisture = [
    0.05, # dead_1hr
    0.10, # dead_10hr
    0.15, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    0.30, # live_herbaceous
    0.50, # live_woody
]

print("Moisturized Static Fuel Model: R01")
pprint(moisturize(static_fuel_model, fuel_moisture))

print("\nMoisturized Dynamic Fuel Model: GR1")
pprint(moisturize(dynamic_fuel_model, fuel_moisture))

def calc_residence_time(sigma_prime):
    """
    Returns the residence time (total burning time) of fuel (min) given:
    - sigma_prime :: ft^2/ft^3 (surface area to volume ratio)
    """
    return 384.0 / sigma_prime if (sigma_prime > 0.0) else 0.0


def calc_flame_depth(spread_rate, residence_time):
    """
    Returns the depth, or front-to-back distance, of the actively flaming zone
    of a free-spreading fire (ft) given:
    - spread_rate    :: ft/min (orthogonal to the fireline)
    - residence_time :: min
    """
    return spread_rate * residence_time


def calc_fireline_intensity(reaction_intensity, flame_depth):
    """
    Returns the rate of heat release per unit of fire edge (Btu/ft/s) given:
    - reaction_intensity :: Btu/ft^2/min
    - flame_depth        :: ft
    """
    return (reaction_intensity * flame_depth) / 60.0


def calc_flame_length(fireline_intensity):
    """
    Returns the average flame length (m) given:
    - fireline_intensity :: kW/m
    """
    return 0.07747042253266703 * (fireline_intensity ** 0.46)


def calc_areal_heat_output(spread_rate, fireline_intensity):
    """
    Returns the heat per unit area (kJ/m^2) given:
    - spread_rate        :: m/min
    - fireline_intensity :: kW/m
    """
    return 60.0 * fireline_intensity / spread_rate if spread_rate > 0.0 else 0.0

import pyretechnics.conversion as conv


def calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model, spread_rate_adjustment=1.0):
    """
    Given these inputs:
    - moisturized_fuel_model :: dictionary of fuel model and fuel moisture properties
      - delta :: ft                                        (fuel depth)
      - w_o   :: lb/ft^2                                   (ovendry fuel loading)
      - rho_p :: lb/ft^3                                   (ovendry particle density)
      - sigma :: ft^2/ft^3                                 (fuel particle surface-area-to-volume ratio)
      - h     :: Btu/lb                                    (fuel particle low heat content)
      - S_T   :: lb minerals/lb ovendry weight             (fuel particle total mineral content)
      - S_e   :: lb silica-free minerals/lb ovendry weight (fuel particle effective mineral content)
      - M_x   :: lb moisture/lb ovendry weight             (fuel particle moisture of extinction)
      - M_f   :: lb moisture/lb ovendry weight             (fuel particle moisture content)
      - f_ij  :: %                                         (percent load per size class)
      - f_i   :: %                                         (percent load per category)
      - g_ij  :: %                                         (percent load per size class - Albini_1976_FIREMOD, page 20)
    - spread_rate_adjustment :: unitless float (1.0 for no adjustment)

    return a dictionary containing these keys:
    - base_spread_rate         :: m/min
    - base_fireline_intensity  :: kW/m
    - max_effective_wind_speed :: m/min
    - get_phi_S                :: lambda: slope (rise/run) => phi_S (unitless)
    - get_phi_W                :: lambda: midflame_wind_speed (m/min) => phi_W (unitless)
    - get_wind_speed           :: lambda: phi_W (unitless) => midflame_wind_speed (m/min)
    """
    # Unpack fuel model values
    delta          = moisturized_fuel_model["delta"]
    w_o            = moisturized_fuel_model["w_o"]
    rho_p          = moisturized_fuel_model["rho_p"]
    sigma          = moisturized_fuel_model["sigma"]
    M_f            = moisturized_fuel_model["M_f"]
    f_ij           = moisturized_fuel_model["f_ij"]
    f_i            = moisturized_fuel_model["f_i"]
    # Calculate base spread rate (no wind, no slope)
    sigma_prime    = calc_surface_area_to_volume_ratio(f_i, f_ij, sigma)
    beta           = calc_packing_ratio(w_o, rho_p, delta)
    beta_op        = calc_optimum_packing_ratio(sigma_prime)
    I_R            = calc_reaction_intensity(moisturized_fuel_model, sigma_prime, beta, beta_op) # Btu/ft^2/min
    xi             = calc_propagating_flux_ratio(sigma_prime, beta)
    heat_source    = calc_heat_source(I_R, xi)                                  # Btu/ft^2/min
    rho_b          = calc_ovendry_bulk_density(w_o, delta)                      # lb/ft^3
    epsilon_ij     = calc_effective_heating_number_distribution(sigma)
    Q_ig_ij        = calc_heat_of_preignition_distribution(M_f)                 # Btu/lb
    heat_sink      = calc_heat_sink(f_i, f_ij, rho_b, epsilon_ij, Q_ig_ij)      # Btu/ft^3
    R0             = calc_spread_rate(heat_source, heat_sink)                   # ft/min
    # Calculate base fireline intensity (no wind, no slope)
    t_res          = calc_residence_time(sigma_prime)                           # min
    D_A            = calc_flame_depth(R0, t_res)                                # ft
    I_s            = calc_fireline_intensity(I_R, D_A)                          # Btu/ft/s
    # Pre-compute values related to wind and slope
    U_eff_max      = calc_max_effective_wind_speed(I_R)                         # ft/min
    B              = 0.02526 * (sigma_prime ** 0.54)
    C              = 7.47 * exp(-0.133 * (sigma_prime ** 0.55))
    E              = 0.715 * exp(-3.59 * (sigma_prime / 10000.0))
    F              = (beta / beta_op) ** E
    get_phi_S      = get_phi_S_fn(beta)
    get_phi_W      = get_phi_W_fn(B, C, F)
    get_wind_speed = get_wind_speed_fn(B, C, F)
    # Return no-wind-no-slope surface fire behavior values
    return {
        "base_spread_rate"        : conv.ft_to_m(R0 * spread_rate_adjustment),
        "base_fireline_intensity" : conv.Btu_ft_s_to_kW_m(I_s * spread_rate_adjustment),
        "max_effective_wind_speed": conv.ft_to_m(U_eff_max),
        "get_phi_S"               : get_phi_S,
        "get_phi_W"               : get_phi_W,
        "get_wind_speed"          : get_wind_speed,
    }

from math import log, sqrt


def calc_wind_adjustment_factor(fuel_bed_depth, canopy_height, canopy_cover):
    """
    Return the wind adjustment factor (unitless) given these inputs:
    - fuel_bed_depth :: ft
    - canopy_height  :: ft
    - canopy_cover   :: 0-1
    """
    if (canopy_cover > 0.0) and (canopy_height > 0.0):
        # sheltered: equation 2 based on CC and CH, CR=1 (Andrews 2012)
        A = sqrt((canopy_cover / 3.0) * canopy_height)
        B = log((20.0 + 0.36 * canopy_height) / (0.13 * canopy_height))
        return 0.555 / (A * B)
    elif (fuel_bed_depth > 0.0):
        # unsheltered: equation 6 H_F = H (Andrews 2012)
        A = log((20.0 + 0.36 * fuel_bed_depth) / (0.13 * fuel_bed_depth))
        return 1.83 / A # 1.83 truncated from 1.8328795184533409
    else:
        # non-burnable fuel model
        return 0.0


def calc_midflame_wind_speed(wind_speed_20ft, fuel_bed_depth, canopy_height, canopy_cover):
    """
    Return the midflame wind speed (S) given these inputs:
    - wind_speed_20ft :: S
    - fuel_bed_depth  :: ft
    - canopy_height   :: ft
    - canopy_cover    :: 0-1
    """
    wind_adj_factor = calc_wind_adjustment_factor(fuel_bed_depth, canopy_height, canopy_cover)
    return wind_speed_20ft * wind_adj_factor

import numpy as np
from pyretechnics.conversion import azimuthal_to_cartesian
from pyretechnics.vector_utils import vector_magnitude, as_unit_vector, to_slope_plane


def project_wind_and_slope_vectors_3d(wind_speed, downwind_direction, slope, upslope_direction):
    """
    Given these inputs:
    - wind_speed         :: S
    - downwind_direction :: degrees clockwise from North
    - slope              :: rise/run
    - upslope_direction  :: degrees clockwise from North

    return a dictionary containing these keys:
    - wind_vector_3d  :: (x: S, y: S, z: S)
    - slope_vector_3d :: (x, y, z)
    """
    # Convert wind and slope vectors from azimuthal to cartesian coordinates
    wind_vector_2d  = azimuthal_to_cartesian(wind_speed, downwind_direction)
    slope_vector_2d = azimuthal_to_cartesian(slope, upslope_direction)
    # Project wind and slope vectors onto the slope-tangential plane
    wind_vector_3d  = to_slope_plane(wind_vector_2d, slope_vector_2d)
    slope_vector_3d = to_slope_plane(slope_vector_2d, slope_vector_2d)
    return {
        "wind_vector_3d" : wind_vector_3d,
        "slope_vector_3d": slope_vector_3d,
    }


def get_phi_E(wind_vector_3d, slope_vector_3d, phi_W, phi_S):
    # Convert wind and slope vectors to unit vectors on the slope-tangential plane
    w_S = as_unit_vector(wind_vector_3d)  if phi_W > 0.0 else wind_vector_3d
    u_S = as_unit_vector(slope_vector_3d) if phi_S > 0.0 else slope_vector_3d
    # Create the 3D slope-tangential phi_W, phi_S, and phi_E vectors
    phi_W_3d = phi_W * w_S
    phi_S_3d = phi_S * u_S
    phi_E_3d = phi_W_3d + phi_S_3d
    # Calculate phi_E
    phi_E = vector_magnitude(phi_E_3d)
    # Determine max spread direction and return results
    if phi_E > 0.0:
        return {
            "phi_E"               : phi_E,
            "max_spread_direction": phi_E_3d / phi_E,
        }
    elif phi_S > 0.0:
        return {
            "phi_E"               : phi_E,
            "max_spread_direction": u_S,
        }
    else:
        return {
            "phi_E"               : phi_E,
            "max_spread_direction": np.asarray((0,1,0)), # default: North
        }

from math import exp, sqrt
from pyretechnics.conversion import m_min_to_mph


def surface_length_to_width_ratio(effective_wind_speed, model="rothermel"):
    """
    Calculate the length_to_width_ratio of the surface fire front given:
    - effective_wind_speed :: m/min (aligned with the slope-tangential plane)
    - model                :: "rothermel" or "behave" (Optional)
    """
    effective_wind_speed_mph = m_min_to_mph(effective_wind_speed)
    match model:
        case "rothermel":
            return 1.0 + 0.25 * effective_wind_speed_mph

        case "behave":
            return min(8.0,
                       0.936 * exp(0.1147 * effective_wind_speed_mph)
                       +
                       0.461 * exp(-0.0692 * effective_wind_speed_mph)
                       -
                       0.397)

        case _:
            raise ValueError("Invalid input: model must be 'rothermel' or 'behave'.")


def surface_fire_eccentricity(length_to_width_ratio):
    """
    Calculate the eccentricity (E) of the surface fire front using eq. 8 from
    Albini and Chase 1980 given:
    - L/W :: (1: circular spread, > 1: elliptical spread)
    """
    return sqrt(length_to_width_ratio ** 2.0 - 1.0) / length_to_width_ratio

from pyretechnics.conversion import opposite_direction
from pyretechnics.vector_utils import vector_magnitude


def maybe_limit_wind_speed(use_wind_limit, max_wind_speed, get_phi_W, get_wind_speed, phi_E_magnitude):
    """
    Given these inputs:
    - use_wind_limit  :: boolean
    - max_wind_speed  :: m/min
    - get_phi_W       :: lambda: midflame_wind_speed (m/min) => phi_W (unitless)
    - get_wind_speed  :: lambda: phi_W (unitless) => midflame_wind_speed (m/min)
    - phi_E_magnitude :: unitless

    return a tuple with these fields:
    - limited_wind_speed :: m/min
    - limited_phi_E      :: unitless
    """
    effective_wind_speed = get_wind_speed(phi_E_magnitude)
    if (use_wind_limit and effective_wind_speed > max_wind_speed):
        return (
            max_wind_speed,
            get_phi_W(max_wind_speed),
        )
    else:
        return (
            effective_wind_speed,
            phi_E_magnitude,
        )


# NOTE: No longer takes ellipse_adjustment_factor parameter
def calc_surface_fire_behavior_max(surface_fire_min, midflame_wind_speed, upwind_direction,
                                   slope, aspect, use_wind_limit=True, surface_lw_ratio_model="rothermel"):
    """
    Given these inputs:
    - surface_fire_min            :: dictionary of no-wind-no-slope surface fire behavior values
      - base_spread_rate             :: m/min
      - base_fireline_intensity      :: kW/m
      - max_effective_wind_speed     :: m/min
      - get_phi_S                    :: lambda: slope (rise/run) => phi_S (unitless)
      - get_phi_W                    :: lambda: midflame_wind_speed (m/min) => phi_W (unitless)
      - get_wind_speed               :: lambda: phi_W (unitless) => midflame_wind_speed (m/min)
    - midflame_wind_speed         :: m/min
    - upwind_direction            :: degrees clockwise from North
    - slope                       :: rise/run
    - aspect                      :: degrees clockwise from North
    - use_wind_limit              :: boolean (Optional)
    - surface_lw_ratio_model      :: "rothermel" or "behave" (Optional)

    return a dictionary containing these keys:
    - max_spread_rate        :: m/min
    - max_spread_direction   :: (x, y, z) unit vector
    - max_fireline_intensity :: kW/m
    - max_flame_length       :: m
    - length_to_width_ratio  :: unitless (1: circular spread, > 1: elliptical spread)
    - eccentricity           :: unitless (0: circular spread, > 0: elliptical spread)
    """
    # Unpack no-wind-no-slope surface fire behavior values
    spread_rate        = surface_fire_min["base_spread_rate"]
    fireline_intensity = surface_fire_min["base_fireline_intensity"]
    max_wind_speed     = surface_fire_min["max_effective_wind_speed"]
    get_phi_W          = surface_fire_min["get_phi_W"]
    get_phi_S          = surface_fire_min["get_phi_S"]
    get_wind_speed     = surface_fire_min["get_wind_speed"]
    # Reverse the provided wind and slope directions
    downwind_direction = opposite_direction(upwind_direction)
    upslope_direction  = opposite_direction(aspect)
    # Project wind and slope vectors onto the slope-tangential plane
    vectors = project_wind_and_slope_vectors_3d(midflame_wind_speed, downwind_direction, slope, upslope_direction)
    wind_vector_3d  = vectors["wind_vector_3d"]  # m/min
    slope_vector_3d = vectors["slope_vector_3d"] # rise/run
    # Calculate phi_W and phi_S
    phi_W = get_phi_W(vector_magnitude(wind_vector_3d)) # |wind_vector_3d| = slope-aligned midflame wind speed
    phi_S = get_phi_S(slope)
    # Calculate phi_E and the max_spread_direction
    result               = get_phi_E(wind_vector_3d, slope_vector_3d, phi_W, phi_S)
    phi_E                = result["phi_E"]
    max_spread_direction = result["max_spread_direction"]
    # Limit effective wind speed to max wind speed if use_wind_limit == True
    (limited_wind_speed, limited_phi_E) = maybe_limit_wind_speed(use_wind_limit, max_wind_speed,
                                                                 get_phi_W, get_wind_speed, phi_E)
    # Calculate and return max surface fire behavior values
    max_spread_rate        = spread_rate * (1.0 + limited_phi_E)
    max_fireline_intensity = fireline_intensity * (1.0 + limited_phi_E)
    length_to_width_ratio  = surface_length_to_width_ratio(limited_wind_speed, surface_lw_ratio_model)
    return {
        "max_spread_rate"       : max_spread_rate,
        "max_spread_direction"  : max_spread_direction, # unit vector
        "max_fireline_intensity": max_fireline_intensity,
        "max_flame_length"      : calc_flame_length(max_fireline_intensity),
        "length_to_width_ratio" : length_to_width_ratio,
        "eccentricity"          : surface_fire_eccentricity(length_to_width_ratio),
    }

import numpy as np


def calc_surface_fire_behavior_in_direction(surface_fire_max, spread_direction):
    """
    Given these inputs:
    - surface_fire_max     :: dictionary of max surface fire behavior values
      - max_spread_rate        :: m/min
      - max_spread_direction   :: (x, y, z) unit vector
      - max_fireline_intensity :: kW/m
      - max_flame_length       :: m
      - length_to_width_ratio  :: unitless (1: circular spread, > 1: elliptical spread)
      - eccentricity           :: unitless (0: circular spread, > 0: elliptical spread)
    - spread_direction     :: 3D unit vector on the slope-tangential plane

    return a dictionary containing these keys:
    - fire_type          :: "surface"
    - spread_rate        :: m/min
    - spread_direction   :: (x, y, z) unit vector
    - fireline_intensity :: kW/m
    - flame_length       :: m
    """
    # Unpack max surface fire behavior values
    max_spread_rate        = surface_fire_max["max_spread_rate"]
    max_spread_direction   = surface_fire_max["max_spread_direction"]
    max_fireline_intensity = surface_fire_max["max_fireline_intensity"]
    eccentricity           = surface_fire_max["eccentricity"]
    # Calculate cos(w), where w is the offset angle between these unit vectors on the slope-tangential plane
    cos_w = np.dot(max_spread_direction, np.asarray(spread_direction))
    # Calculate adjustment due to the offset angle from the max spread direction
    adjustment = (1.0 - eccentricity) / (1.0 - eccentricity * cos_w)
    # Update surface fire behavior values by the adjustment value
    fireline_intensity = max_fireline_intensity * adjustment
    return {
        "fire_type"         : "surface",
        "spread_rate"       : max_spread_rate * adjustment,
        "spread_direction"  : spread_direction,
        "fireline_intensity": fireline_intensity,
        "flame_length"      : calc_flame_length(fireline_intensity),
    }

from pprint import pprint
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf

# Set input parameters
fuel_model    = fm.fuel_model_table[101] # GR1
fuel_moisture = [
    0.05, # dead_1hr
    0.10, # dead_10hr
    0.15, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    0.90, # live_herbaceous
    0.60, # live_woody
]

# Apply fuel moisture to fuel model
moisturized_fuel_model = fm.moisturize(fuel_model, fuel_moisture)

# Calculate no-wind-no-slope surface fire behavior
surface_fire_min = sf.calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model)

# View results
print("No-Wind-No-Slope Surface Fire Behavior for Fuel Model GR1 with Fuel Moisture = "
      + str(moisturized_fuel_model["M_f"]))
pprint({k: surface_fire_min[k] for k in ["base_spread_rate", "base_fireline_intensity", "max_effective_wind_speed"]})

import pyretechnics.conversion as conv
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf

# Set input parameters
fuel_model       = fm.fuel_model_table[101] # GR1
canopy_height    = 20                       # meters
canopy_cover     = 0.6                      # 0-1
wind_speed_10m   = 20                       # km/hr
upwind_direction = 45.0                     # degrees clockwise from North

# Convert from 10m wind speed to 20ft wind speed
wind_speed_20ft = conv.wind_speed_10m_to_wind_speed_20ft(wind_speed_10m) # km/hr

# Convert from 20ft wind speed to midflame wind speed in m/min
midflame_wind_speed = sf.calc_midflame_wind_speed(conv.km_hr_to_m_min(wind_speed_20ft), # m/min
                                                  fuel_model["delta"],                  # ft
                                                  conv.m_to_ft(canopy_height),          # ft
                                                  canopy_cover)                         # 0-1

# View results
print("Midflame Wind Speed and Direction for 10m Wind Speed = 20 km/hr, Upwind Direction = 45.0\n"
      + " with Fuel Model GR1, Canopy Height = 20m, and Canopy Cover = 60%\n"
      + "- Speed: " + str(midflame_wind_speed) + " (m/min)\n"
      + "- Downwind Direction: " + str(conv.opposite_direction(upwind_direction)) + " (degrees clockwise from North)")

from pprint import pprint
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf

# Set input parameters
fuel_model    = fm.fuel_model_table[101] # GR1
fuel_moisture = [
    0.05, # dead_1hr
    0.10, # dead_10hr
    0.15, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    0.90, # live_herbaceous
    0.60, # live_woody
]
midflame_wind_speed = 500.0 # m/min
upwind_direction    = 215.0 # degrees clockwise from North
slope               = 0.2   # rise/run
aspect              = 270.0 # degrees clockwise from North

# Apply fuel moisture to fuel model
moisturized_fuel_model = fm.moisturize(fuel_model, fuel_moisture)

# Calculate no-wind-no-slope surface fire behavior
surface_fire_min = sf.calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model)

# Calculate surface fire behavior in the direction of maximum spread with effective wind speed limit
surface_fire_max = sf.calc_surface_fire_behavior_max(surface_fire_min,
                                                     midflame_wind_speed,
                                                     upwind_direction,
                                                     slope,
                                                     aspect)

# View results
print("Surface Fire Behavior Max (Limited) for Fuel Model GR1 with Fuel Moisture = "
      + str(moisturized_fuel_model["M_f"]))
pprint(surface_fire_max)

# Calculate surface fire behavior in the direction of maximum spread without effective wind speed limit
surface_fire_max_unlimited = sf.calc_surface_fire_behavior_max(surface_fire_min,
                                                               midflame_wind_speed,
                                                               upwind_direction,
                                                               slope,
                                                               aspect,
                                                               use_wind_limit=False)

# View results
print("\nSurface Fire Behavior Max (Unlimited) for Fuel Model GR1 with Fuel Moisture = "
      + str(moisturized_fuel_model["M_f"]))
pprint(surface_fire_max_unlimited)

from pprint import pprint
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf
import pyretechnics.vector_utils as vu

# Set input parameters
fuel_model    = fm.fuel_model_table[101] # GR1
fuel_moisture = [
    0.05, # dead_1hr
    0.10, # dead_10hr
    0.15, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    0.90, # live_herbaceous
    0.60, # live_woody
]
midflame_wind_speed = 500.0 # m/min
upwind_direction    = 215.0 # degrees clockwise from North
slope               = 0.2   # rise/run
aspect              = 270.0 # degrees clockwise from North

# Apply fuel moisture to fuel model
moisturized_fuel_model = fm.moisturize(fuel_model, fuel_moisture)

# Calculate no-wind-no-slope surface fire behavior
surface_fire_min = sf.calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model)

# Calculate surface fire behavior in the direction of maximum spread with effective wind speed limit
surface_fire_max = sf.calc_surface_fire_behavior_max(surface_fire_min,
                                                     midflame_wind_speed,
                                                     upwind_direction,
                                                     slope,
                                                     aspect)

# Calculate surface fire behavior for the heading, flanking, and backing fires
heading_fire_direction  = surface_fire_max["max_spread_direction"]
flanking_fire_direction = vu.rotate_on_sloped_plane(heading_fire_direction, 90, slope, aspect)
backing_fire_direction  = -heading_fire_direction

heading_fire_behavior  = sf.calc_surface_fire_behavior_in_direction(surface_fire_max, heading_fire_direction)
flanking_fire_behavior = sf.calc_surface_fire_behavior_in_direction(surface_fire_max, flanking_fire_direction)
backing_fire_behavior  = sf.calc_surface_fire_behavior_in_direction(surface_fire_max, backing_fire_direction)

# View heading fire results
print("Heading Fire Behavior for Fuel Model GR1 with Fuel Moisture = "
      + str(moisturized_fuel_model["M_f"]))
pprint(heading_fire_behavior)

# View flanking fire results
print("\nFlanking Fire Behavior for Fuel Model GR1 with Fuel Moisture = "
      + str(moisturized_fuel_model["M_f"]))
pprint(flanking_fire_behavior)

# View backing fire results
print("\nBacking Fire Behavior for Fuel Model GR1 with Fuel Moisture = "
      + str(moisturized_fuel_model["M_f"]))
pprint(backing_fire_behavior)

def van_wagner_critical_fireline_intensity(canopy_base_height, foliar_moisture):
    """
    Returns the critical fireline intensity (kW/m) given:
    - canopy_base_height :: m
    - foliar_moisture    :: kg moisture/kg ovendry weight

    Constants used:
    460.0 = heat-of-ignition :: kJ/kg
    0.01 = empirical estimate for C in Van Wagner 1977 (eq. 4)
    """
    H = 460.0 + 2600.0 * foliar_moisture
    return (0.01 * canopy_base_height * H) ** 1.5

def van_wagner_crown_fire_initiation(surface_fireline_intensity, canopy_cover, canopy_base_height, foliar_moisture):
    """
    Returns True if the surface fire transitions to a crown fire or False otherwise given:
    - surface_fireline_intensity :: kW/m
    - canopy_cover               :: 0-1
    - canopy_base_height         :: m
    - foliar_moisture            :: kg moisture/kg ovendry weight
    """
    return (
        surface_fireline_intensity > 0.0
        and
        canopy_cover > 0.4
        and
        surface_fireline_intensity >= van_wagner_critical_fireline_intensity(canopy_base_height, foliar_moisture)
    )

from math import exp


def cruz_active_crown_fire_spread_rate(wind_speed_10m, canopy_bulk_density, estimated_fine_fuel_moisture):
    """
    Returns the active crown fire spread rate (m/min) given:
    - wind_speed_10m                                   :: km/hr
    - canopy_bulk_density                              :: kg/m^3
    - estimated_fine_fuel_moisture (M_f[0] "dead-1hr") :: kg moisture/kg ovendry weight
    """
    return (11.02
            * wind_speed_10m ** 0.90
            * canopy_bulk_density ** 0.19
            * exp(-17.0 * estimated_fine_fuel_moisture))

def van_wagner_critical_spread_rate(canopy_bulk_density):
    """
    Returns the critical spread rate (m/min) given:
    - canopy_bulk_density :: kg/m^3
    """
    return 3.0 / canopy_bulk_density

from math import exp


def cruz_passive_crown_fire_spread_rate(active_spread_rate, critical_spread_rate):
    """
    Returns the passive crown fire spread rate (m/min) given:
    - active_spread_rate   :: m/min
    - critical_spread_rate :: m/min
    """
    return active_spread_rate * exp(-active_spread_rate / critical_spread_rate)

def cruz_crown_fire_spread_info(wind_speed_10m, canopy_bulk_density, estimated_fine_fuel_moisture):
    """
    Given these inputs:
    - wind_speed_10m                                   :: km/hr
    - canopy_bulk_density                              :: kg/m^3
    - estimated_fine_fuel_moisture (M_f[0] "dead-1hr") :: kg moisture/kg ovendry weight

    return a dictionary containing these keys:
    - fire_type            :: "passive_crown" or "active_crown"
    - spread_rate          :: m/min
    - critical_spread_rate :: m/min
    """
    active_spread_rate   = cruz_active_crown_fire_spread_rate(wind_speed_10m,
                                                              canopy_bulk_density,
                                                              estimated_fine_fuel_moisture) # m/min
    critical_spread_rate = van_wagner_critical_spread_rate(canopy_bulk_density) # m/min
    if (active_spread_rate > critical_spread_rate):
        return {
            "fire_type"           : "active_crown",
            "spread_rate"         : active_spread_rate,
            "critical_spread_rate": critical_spread_rate,
        }
    else:
        return {
            "fire_type"           : "passive_crown",
            "spread_rate"         : cruz_passive_crown_fire_spread_rate(active_spread_rate, critical_spread_rate),
            "critical_spread_rate": critical_spread_rate,
        }

# NOTE: heat_of_combustion is h from the fuel models (generally 8000 Btu/lb)
# NOTE: ELMFIRE hard-codes heat_of_combustion to 18000 kJ/kg = 7738.6 Btu/lb
def calc_crown_fireline_intensity(crown_spread_rate, canopy_bulk_density, canopy_height,
                                  canopy_base_height, heat_of_combustion):
    """
    Returns the crown fireline intensity (Btu/ft/s OR kW/m) given:
    - crown_spread_rate                                             :: ft/min  OR m/min
    - canopy_bulk_density                                           :: lb/ft^3 OR kg/m^3
    - canopy_height                                                 :: ft      OR m
    - canopy_base_height                                            :: ft      OR m
    - heat_of_combustion                                            :: Btu/lb  OR kJ/kg

    (ft/min * lb/ft^3 * ft * Btu/lb)/60 = (Btu/ft/min)/60 = Btu/ft/s
    OR
    (m/min * kg/m^3 * m * kJ/kg)/60 = (kJ/m*min)/60 = kJ/m*s = kW/m
    """
    canopy_height_difference = canopy_height - canopy_base_height
    return (crown_spread_rate * canopy_bulk_density * canopy_height_difference * heat_of_combustion) / 60.0

from math import sqrt
import pyretechnics.conversion as conv


def crown_length_to_width_ratio(wind_speed_10m, max_length_to_width_ratio=None):
    """
    Calculate the length_to_width_ratio of the crown fire front using eq. 9 from
    Rothermel 1991 given:
    - wind_speed_10m            :: km/hr (aligned with the slope-tangential plane)
    - max_length_to_width_ratio :: float > 0.0 (Optional)
    """
    wind_speed_20ft_mph   = conv.km_hr_to_mph(conv.wind_speed_10m_to_wind_speed_20ft(wind_speed_10m)) # mph
    length_to_width_ratio = 1.0 + 0.125 * wind_speed_20ft_mph
    if max_length_to_width_ratio:
        return min(length_to_width_ratio, max_length_to_width_ratio)
    else:
        return length_to_width_ratio


def crown_fire_eccentricity(length_to_width_ratio):
    """
    Calculate the eccentricity (E) of the crown fire front using eq. 8 from
    Albini and Chase 1980 given:
    - L/W :: (1: circular spread, > 1: elliptical spread)
    """
    return sqrt(length_to_width_ratio ** 2.0 - 1.0) / length_to_width_ratio

import numpy as np
import pyretechnics.conversion as conv
import pyretechnics.surface_fire as sf
import pyretechnics.vector_utils as vu


def calc_crown_fire_behavior_max(canopy_height, canopy_base_height, canopy_bulk_density, heat_of_combustion,
                                 estimated_fine_fuel_moisture, wind_speed_10m, upwind_direction,
                                 slope, aspect, crown_max_lw_ratio=None):
    """
    Given these inputs:
    - canopy_height                                    :: m
    - canopy_base_height                               :: m
    - canopy_bulk_density                              :: kg/m^3
    - heat_of_combustion                               :: kJ/kg
    - estimated_fine_fuel_moisture (M_f[0] "dead-1hr") :: kg moisture/kg ovendry weight
    - wind_speed_10m                                   :: km/hr
    - upwind_direction                                 :: degrees clockwise from North
    - slope                                            :: rise/run
    - aspect                                           :: degrees clockwise from North
    - crown_max_lw_ratio                               :: float > 0.0 (Optional)

    return a dictionary containing these keys:
    - max_fire_type          :: "passive_crown" or "active_crown"
    - max_spread_rate        :: m/min
    - max_spread_direction   :: (x, y, z) unit vector
    - max_fireline_intensity :: kW/m
    - length_to_width_ratio  :: unitless (1: circular spread, > 1: elliptical spread)
    - eccentricity           :: unitless (0: circular spread, > 0: elliptical spread)
    - critical_spread_rate   :: m/min
    """
    # Reverse the provided wind and slope directions
    downwind_direction = conv.opposite_direction(upwind_direction)
    upslope_direction  = conv.opposite_direction(aspect)
    # Project wind and slope vectors onto the slope-tangential plane
    vectors = sf.project_wind_and_slope_vectors_3d(wind_speed_10m, downwind_direction, slope, upslope_direction)
    wind_vector_3d  = vectors["wind_vector_3d"]  # km/hr
    slope_vector_3d = vectors["slope_vector_3d"] # rise/run
    # Determine the max spread direction
    wind_speed_10m_3d    = vu.vector_magnitude(wind_vector_3d)      # km/hr
    max_spread_direction = (wind_vector_3d / wind_speed_10m_3d      # unit vector in the 3D downwind direction
                            if wind_speed_10m_3d > 0.0
                            else vu.as_unit_vector(slope_vector_3d) # unit vector in the 3D upslope direction
                            if slope > 0.0
                            else np.asarray((0,1,0)))               # default: North
    # Calculate the crown fire behavior in the max spread direction
    spread_info           = cruz_crown_fire_spread_info(wind_speed_10m_3d, canopy_bulk_density,
                                                        estimated_fine_fuel_moisture)
    spread_rate           = spread_info["spread_rate"] # m/min
    fireline_intensity    = calc_crown_fireline_intensity(spread_rate, canopy_bulk_density, canopy_height,
                                                          canopy_base_height, heat_of_combustion) # kW/m
    length_to_width_ratio = crown_length_to_width_ratio(wind_speed_10m_3d, crown_max_lw_ratio) # unitless
    eccentricity          = crown_fire_eccentricity(length_to_width_ratio) # unitless
    return {
        "max_fire_type"         : spread_info["fire_type"],
        "max_spread_rate"       : spread_rate,
        "max_spread_direction"  : max_spread_direction, # unit vector
        "max_fireline_intensity": fireline_intensity,
        "length_to_width_ratio" : length_to_width_ratio,
        "eccentricity"          : eccentricity,
        "critical_spread_rate"  : spread_info["critical_spread_rate"],
    }

import numpy as np


def calc_crown_fire_behavior_in_direction(crown_fire_max, spread_direction):
    """
    Given these inputs:
    - crown_fire_max     :: dictionary of max crown fire behavior values
      - max_fire_type          :: "passive_crown" or "active_crown"
      - max_spread_rate        :: m/min
      - max_spread_direction   :: (x, y, z) unit vector
      - max_fireline_intensity :: kW/m
      - length_to_width_ratio  :: unitless (1: circular spread, > 1: elliptical spread)
      - eccentricity           :: unitless (0: circular spread, > 0: elliptical spread)
      - critical_spread_rate   :: m/min
    - spread_direction   :: 3D unit vector on the slope-tangential plane

    return a dictionary containing these keys:
    - fire_type          :: "passive_crown" or "active_crown"
    - spread_rate        :: m/min
    - spread_direction   :: (x, y, z) unit vector
    - fireline_intensity :: kW/m
    """
    # Unpack max crown fire behavior values
    max_fire_type          = crown_fire_max["max_fire_type"]
    max_spread_rate        = crown_fire_max["max_spread_rate"]
    max_spread_direction   = crown_fire_max["max_spread_direction"]
    max_fireline_intensity = crown_fire_max["max_fireline_intensity"]
    eccentricity           = crown_fire_max["eccentricity"]
    critical_spread_rate   = crown_fire_max["critical_spread_rate"]
    # Calculate cos(w), where w is the offset angle between these unit vectors on the slope-tangential plane
    cos_w = np.dot(max_spread_direction, np.asarray(spread_direction))
    # Calculate adjustment due to the offset angle from the max spread direction
    adjustment = (1.0 - eccentricity) / (1.0 - eccentricity * cos_w)
    # Adjust the spread rate (possibly switching from an active to passive crown fire)
    spread_rate = max_spread_rate * adjustment
    if spread_rate > critical_spread_rate:
        # Max spread rate was active and directional spread rate remains active
        return {
            "fire_type"         : "active_crown",
            "spread_rate"       : spread_rate,
            "spread_direction"  : spread_direction,
            "fireline_intensity": max_fireline_intensity * adjustment,
        }
    elif max_fire_type == "passive_crown":
        # Max spread rate was passive and directional spread rate remains passive
        return {
            "fire_type"         : "passive_crown",
            "spread_rate"       : spread_rate,
            "spread_direction"  : spread_direction,
            "fireline_intensity": max_fireline_intensity * adjustment,
        }
    else:
        # Max spread rate was active and directional spread rate has become passive
        return {
            "fire_type"         : "passive_crown",
            "spread_rate"       : cruz_passive_crown_fire_spread_rate(spread_rate, critical_spread_rate),
            "spread_direction"  : spread_direction,
            "fireline_intensity": max_fireline_intensity * adjustment,
        }

from pprint import pprint
import pyretechnics.crown_fire as cf

# Set tree canopy characteristics
canopy_cover_low   = 0.3 # 0-1
canopy_cover_high  = 0.8 # 0-1
canopy_base_height = 3.0 # m
foliar_moisture    = 1.0 # kg moisture/kg ovendry weight

# Specify some surface fireline intensity values to check
# These would normally be calculated by the functions in pyretechnics.surface_fire
surface_fireline_intensity_low  = 500.0  # kW/m
surface_fireline_intensity_high = 5000.0 # kW/m

#=================================================================================
# Check for crown fire with canopy_cover_low and surface_fireline_intensity_low
#=================================================================================

print("Low Canopy Cover and Low Surface Fireline Intensity\n" + "=" * 60)

if cf.van_wagner_crown_fire_initiation(surface_fireline_intensity_low,
                                       canopy_cover_low,
                                       canopy_base_height,
                                       foliar_moisture):
    # Crown Fire
    print("\nA crown fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_low,
        "canopy_cover"              : canopy_cover_low,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })
else:
    # Surface Fire
    print("\nA surface fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_low,
        "canopy_cover"              : canopy_cover_low,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })

#=================================================================================
# Check for crown fire with canopy_cover_low and surface_fireline_intensity_high
#=================================================================================

print("\nLow Canopy Cover and High Surface Fireline Intensity\n" + "=" * 60)

if cf.van_wagner_crown_fire_initiation(surface_fireline_intensity_high,
                                       canopy_cover_low,
                                       canopy_base_height,
                                       foliar_moisture):
    # Crown Fire
    print("\nA crown fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_high,
        "canopy_cover"              : canopy_cover_low,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })
else:
    # Surface Fire
    print("\nA surface fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_high,
        "canopy_cover"              : canopy_cover_low,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })

#=================================================================================
# Check for crown fire with canopy_cover_high and surface_fireline_intensity_low
#=================================================================================

print("\nHigh Canopy Cover and Low Surface Fireline Intensity\n" + "=" * 60)

if cf.van_wagner_crown_fire_initiation(surface_fireline_intensity_low,
                                       canopy_cover_high,
                                       canopy_base_height,
                                       foliar_moisture):
    # Crown Fire
    print("\nA crown fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_low,
        "canopy_cover"              : canopy_cover_high,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })
else:
    # Surface Fire
    print("\nA surface fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_low,
        "canopy_cover"              : canopy_cover_high,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })

#=================================================================================
# Check for crown fire with canopy_cover_high and surface_fireline_intensity_high
#=================================================================================

print("\nHigh Canopy Cover and High Surface Fireline Intensity\n" + "=" * 60)

if cf.van_wagner_crown_fire_initiation(surface_fireline_intensity_high,
                                       canopy_cover_high,
                                       canopy_base_height,
                                       foliar_moisture):
    # Crown Fire
    print("\nA crown fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_high,
        "canopy_cover"              : canopy_cover_high,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })
else:
    # Surface Fire
    print("\nA surface fire occurs with these input parameters:")
    pprint({
        "surface_fireline_intensity": surface_fireline_intensity_high,
        "canopy_cover"              : canopy_cover_high,
        "canopy_base_height"        : canopy_base_height,
        "foliar_moisture"           : foliar_moisture,
    })

from pprint import pprint
import pyretechnics.crown_fire as cf

# Set input parameters
canopy_height                = 30.0    # m
canopy_base_height           = 3.0     # m
canopy_bulk_density          = 0.3     # kg/m^3
heat_of_combustion           = 18608.0 # kJ/kg
estimated_fine_fuel_moisture = 0.05    # kg moisture/kg ovendry weight
wind_speed_10m               = 10.0    # km/hr
upwind_direction             = 180.0   # degrees clockwise from North
slope                        = 0.5     # rise/run
aspect_parallel_to_wind      = 180.0   # degrees clockwise from North
aspect_perpendicular_to_wind = 270.0   # degrees clockwise from North

#====================================================================================================
# Calculate crown fire behavior in the direction of maximum spread with slope and wind aligned
#====================================================================================================

crown_fire_max_aligned = cf.calc_crown_fire_behavior_max(canopy_height, canopy_base_height,
                                                         canopy_bulk_density, heat_of_combustion,
                                                         estimated_fine_fuel_moisture,
                                                         wind_speed_10m, upwind_direction,
                                                         slope, aspect_parallel_to_wind)

# View results
print("Crown Fire Behavior Max with Wind and Slope Aligned\n" + "=" * 60)

print("\nInputs:")
pprint({
    "canopy_height"               : canopy_height,
    "canopy_base_height"          : canopy_base_height,
    "canopy_bulk_density"         : canopy_bulk_density,
    "heat_of_combustion"          : heat_of_combustion,
    "estimated_fine_fuel_moisture": estimated_fine_fuel_moisture,
    "wind_speed_10m"              : wind_speed_10m,
    "upwind_direction"            : upwind_direction,
    "slope"                       : slope,
    "aspect"                      : aspect_parallel_to_wind,
})

print("\nOutputs:")
pprint(crown_fire_max_aligned)

#====================================================================================================
# Calculate crown fire behavior in the direction of maximum spread with slope and wind perpendicular
#====================================================================================================

crown_fire_max_perpendicular = cf.calc_crown_fire_behavior_max(canopy_height, canopy_base_height,
                                                               canopy_bulk_density, heat_of_combustion,
                                                               estimated_fine_fuel_moisture,
                                                               wind_speed_10m, upwind_direction,
                                                               slope, aspect_perpendicular_to_wind)

# View results
print("\nCrown Fire Behavior Max with Wind and Slope Perpendicular\n" + "=" * 60)

print("\nInputs:")
pprint({
    "canopy_height"               : canopy_height,
    "canopy_base_height"          : canopy_base_height,
    "canopy_bulk_density"         : canopy_bulk_density,
    "heat_of_combustion"          : heat_of_combustion,
    "estimated_fine_fuel_moisture": estimated_fine_fuel_moisture,
    "wind_speed_10m"              : wind_speed_10m,
    "upwind_direction"            : upwind_direction,
    "slope"                       : slope,
    "aspect"                      : aspect_perpendicular_to_wind,
})

print("\nOutputs:")
pprint(crown_fire_max_perpendicular)

from pprint import pprint
import pyretechnics.crown_fire as cf
import pyretechnics.vector_utils as vu

# Set input parameters
canopy_height                = 30.0    # m
canopy_base_height           = 3.0     # m
canopy_bulk_density          = 0.3     # kg/m^3
heat_of_combustion           = 18608.0 # kJ/kg
estimated_fine_fuel_moisture = 0.05    # kg moisture/kg ovendry weight
wind_speed_10m               = 10.0    # km/hr
upwind_direction             = 180.0   # degrees clockwise from North
slope                        = 0.5     # rise/run
aspect                       = 225.0   # degrees clockwise from North

#================================================================================================
# Calculate crown fire behavior in the direction of maximum spread
#================================================================================================

crown_fire_max = cf.calc_crown_fire_behavior_max(canopy_height, canopy_base_height,
                                                 canopy_bulk_density, heat_of_combustion,
                                                 estimated_fine_fuel_moisture,
                                                 wind_speed_10m, upwind_direction,
                                                 slope, aspect)

#================================================================================================
# Calculate crown fire behavior for the heading, flanking, and backing fires
#================================================================================================

heading_fire_direction  = crown_fire_max["max_spread_direction"]
flanking_fire_direction = vu.rotate_on_sloped_plane(heading_fire_direction, 90, slope, aspect)
backing_fire_direction  = -heading_fire_direction

heading_fire_behavior  = cf.calc_crown_fire_behavior_in_direction(crown_fire_max, heading_fire_direction)
flanking_fire_behavior = cf.calc_crown_fire_behavior_in_direction(crown_fire_max, flanking_fire_direction)
backing_fire_behavior  = cf.calc_crown_fire_behavior_in_direction(crown_fire_max, backing_fire_direction)

# View heading fire results
print("Heading Fire Behavior\n" + "=" * 60)
pprint(heading_fire_behavior)

# View flanking fire results
print("\nFlanking Fire Behavior\n" + "=" * 60)
pprint(flanking_fire_behavior)

# View backing fire results
print("\nBacking Fire Behavior\n" + "=" * 60)
pprint(backing_fire_behavior)

from pprint import pprint
import pyretechnics.conversion as conv
import pyretechnics.crown_fire as cf
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf
import pyretechnics.vector_utils as vu

#================================================================================================
# Set input parameters
#================================================================================================

# Landscape
fuel_model          = fm.fuel_model_table[101] # GR1
canopy_cover        = 0.6                      # 0-1
canopy_height       = 30.0                     # m
canopy_base_height  = 3.0                      # m
canopy_bulk_density = 0.3                      # kg/m^3
slope               = 0.8                      # rise/run
aspect              = 225.0                    # degrees clockwise from North

# Weather
fuel_moisture    = [
    0.05, # dead_1hr
    0.10, # dead_10hr
    0.15, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    0.90, # live_herbaceous
    0.60, # live_woody
]                        # kg moisture/kg ovendry weight
foliar_moisture  = 0.9   # kg moisture/kg ovendry weight
wind_speed_10m   = 30.0  # km/hr
upwind_direction = 180.0 # degrees clockwise from North

# Derived Parameters
fuel_bed_depth               = fuel_model["delta"]                      # ft
heat_of_combustion           = conv.Btu_lb_to_kJ_kg(fuel_model["h"][0]) # kJ/kg
estimated_fine_fuel_moisture = fuel_moisture[0]                         # kg moisture/kg ovendry weight

# Fire Perimeter Normal Vector
fire_perimeter_normal_vector_2d = (1.0, 0.0) # (x,y) unit vector pointing East

#================================================================================================
# Project the 2D fire perimeter normal vector onto the slope-tangential plane
#================================================================================================

upslope_direction               = conv.opposite_direction(aspect)
slope_vector_2d                 = conv.azimuthal_to_cartesian(slope, upslope_direction)
fire_perimeter_normal_vector_3d = vu.as_unit_vector(vu.to_slope_plane(fire_perimeter_normal_vector_2d, slope_vector_2d))

#================================================================================================
# Calculate midflame wind speed
#================================================================================================

# Convert from 10m wind speed to 20ft wind speed
wind_speed_20ft = conv.wind_speed_10m_to_wind_speed_20ft(wind_speed_10m) # km/hr

# Convert 20ft wind speed from km/hr to m/min
wind_speed_20ft_m_min = conv.km_hr_to_m_min(wind_speed_20ft) # m/min

# Convert from 20ft wind speed to midflame wind speed in m/min
midflame_wind_speed = sf.calc_midflame_wind_speed(wind_speed_20ft_m_min,       # m/min
                                                  fuel_bed_depth,              # ft
                                                  conv.m_to_ft(canopy_height), # ft
                                                  canopy_cover)                # 0-1

#================================================================================================
# Calculate surface fire behavior in the direction of maximum spread
#================================================================================================

# Apply fuel moisture to fuel model
moisturized_fuel_model = fm.moisturize(fuel_model, fuel_moisture)

# Calculate no-wind-no-slope surface fire behavior
surface_fire_min = sf.calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model)

# Calculate surface fire behavior in the direction of maximum spread with effective wind speed limit
surface_fire_max = sf.calc_surface_fire_behavior_max(surface_fire_min,
                                                     midflame_wind_speed,
                                                     upwind_direction,
                                                     slope,
                                                     aspect)

#================================================================================================
# Calculate surface fire behavior in the direction normal to the fire perimeter
#================================================================================================

surface_fire_normal = sf.calc_surface_fire_behavior_in_direction(surface_fire_max, fire_perimeter_normal_vector_3d)

#================================================================================================
# Determine whether the surface fire transitions to a crown fire
#================================================================================================

if cf.van_wagner_crown_fire_initiation(surface_fire_normal["fireline_intensity"],
                                       canopy_cover,
                                       canopy_base_height,
                                       foliar_moisture):

    #============================================================================================
    # Calculate crown fire behavior in the direction of maximum spread
    #============================================================================================

    crown_fire_max = cf.calc_crown_fire_behavior_max(canopy_height, canopy_base_height,
                                                     canopy_bulk_density, heat_of_combustion,
                                                     estimated_fine_fuel_moisture,
                                                     wind_speed_10m, upwind_direction,
                                                     slope, aspect)

    #============================================================================================
    # Calculate crown fire behavior in the direction normal to the fire perimeter
    #============================================================================================

    crown_fire_normal = cf.calc_crown_fire_behavior_in_direction(crown_fire_max, fire_perimeter_normal_vector_3d)

    #============================================================================================
    # Calculate combined fire behavior in the direction normal to the fire perimeter
    #============================================================================================

    combined_fire_normal = cf.calc_combined_fire_behavior(surface_fire_normal, crown_fire_normal)

    #============================================================================================
    # Display the combined fire behavior normal to the fire perimeter
    #============================================================================================

    print("Fire Behavior from Combined Surface and Crown Fire\n" + "=" * 60)
    pprint(combined_fire_normal)

else:

    #============================================================================================
    # Display the surface fire behavior normal to the fire perimeter
    #============================================================================================

    print("Fire Behavior from Surface Fire (No Crown Fire Occurred)\n" + "=" * 60)
    pprint(surface_fire_normal)

from math import sqrt
import pyretechnics.surface_fire as sf


def expected_firebrand_production(fire_behavior, elevation_gradient, cube_resolution, firebrands_per_unit_heat=1e-6):
    """
    Return the expected number of firebrands produced by an entire cell when it burns given:
    - fire_behavior            :: dictionary of surface or crown fire behavior values
      - fire_type                 :: "unburned", "surface", "passive_crown", or "active_crown"
      - spread_rate               :: m/min
      - spread_direction          :: (x, y, z) unit vector on the slope-tangential plane
      - fireline_intensity        :: kW/m
      - flame_length              :: m
    - elevation_gradient       :: tuple with these fields
      - dz_dx                     :: rise/run
      - dz_dy                     :: rise/run
    - cube_resolution          :: tuple with these fields
      - band_duration             :: minutes
      - cell_height               :: meters
      - cell_width                :: meters
    - firebrands_per_unit_heat :: firebrands/kJ
    """
    if fire_behavior["spread_rate"] == 0.0:
        return 0.0
    else:
        #================================================================================================
        # Calculate the heat output per unit area
        #================================================================================================

        spread_rate          = fire_behavior["spread_rate"]                               # m/min
        fireline_intensity   = fire_behavior["fireline_intensity"]                        # kW/m
        heat_output_per_area = sf.calc_areal_heat_output(spread_rate, fireline_intensity) # kJ/m^2

        #================================================================================================
        # Calculate the slope-adjusted cell area
        #================================================================================================

        (dz_dx, dz_dy) = elevation_gradient                      # (rise/run, rise/run)
        slope_factor   = sqrt(1.0 + dz_dx ** 2.0 + dz_dy ** 2.0) # unitless
        cell_height    = cube_resolution[1]                      # meters
        cell_width     = cube_resolution[2]                      # meters
        cell_area      = cell_height * cell_width * slope_factor # m^2

        #================================================================================================
        # Calculate the expected number of firebrands produced in this cell
        #================================================================================================

        cell_heat_output = heat_output_per_area * cell_area            # kJ
        firebrand_count  = firebrands_per_unit_heat * cell_heat_output # number of firebrands
        return firebrand_count

def delta_to_grid_dx(cos_wdir, sin_wdir, delta_x, delta_y):
    """
    Computes the grid-aligned x coordinate of the delta vector, given the wind-aligned [ΔX ΔY] coordinates.
    Returns a signed distance (same unit as ΔX and ΔY).
    """
    wdir_x      = sin_wdir
    wdir_perp_x = cos_wdir
    return delta_x * wdir_x + delta_y * wdir_perp_x


def delta_to_grid_dy(cos_wdir, sin_wdir, delta_x, delta_y):
    """
    Computes the grid-aligned y coordinate of the delta vector, given the wind-aligned [ΔX ΔY] coordinates.
    Returns a signed distance (same unit as ΔX and ΔY).
    """
    wdir_y      = cos_wdir  # FIXME: Should this be negative or positive?
    wdir_perp_y = sin_wdir
    return delta_x * wdir_y + delta_y * wdir_perp_y


def distance_to_n_cells(distance, cell_size):
    """
    Converts a delta expressed as a signed distance to one expressed as a number of grid cells.
    """
    return round(distance / cell_size)

from math import log, sqrt


def resolve_exp_delta_x(spot_config, fireline_intensity, wind_speed_20ft):
    """
    Computes the expected value E[ΔX] (in meters) of the downwind spotting distance ΔX given:
    - spot_config        :: a map of spotting parameters
    - fireline_intensity :: kW/m
    - wind_speed_20ft    :: m/s
    """
    downwind_distance_mean      = spot_config["downwind_distance_mean"]
    fireline_intensity_exponent = spot_config["fireline_intensity_exponent"]
    wind_speed_exponent         = spot_config["wind_speed_exponent"]
    return (downwind_distance_mean
            * (fireline_intensity ** fireline_intensity_exponent)
            * (wind_speed_20ft ** wind_speed_exponent))


def resolve_var_delta_x(spot_config, exp_delta_x):
    """
    Computes the variance Var[ΔX] (in m^2) of the downwind spotting distance ΔX given:
    - spot_config :: a map of spotting parameters
    - exp_delta_x :: meters (E[ΔX])
    """
    return spot_config["downwind_variance_mean_ratio"] * exp_delta_x


def lognormal_mu_from_moments(mean, variance):
    """
    TODO: Add docstring
    """
    m2 = mean ** 2.0
    return log(m2 / sqrt(m2 + variance))


def lognormal_sigma_from_moments(mean, variance):
    """
    TODO: Add docstring
    """
    return sqrt(log(1.0 + variance / (mean ** 2.0)))


def resolve_lognormal_params(spot_config, fireline_intensity, wind_speed_20ft):
    """
    TODO: Add docstring
    """
    exp_delta_x = resolve_exp_delta_x(spot_config, fireline_intensity, wind_speed_20ft)
    var_delta_x = resolve_var_delta_x(spot_config, exp_delta_x)
    return {
        "prob.lognormal.mu"   : lognormal_mu_from_moments(exp_delta_x, var_delta_x),
        "prob.lognormal.sigma": lognormal_sigma_from_moments(exp_delta_x, var_delta_x),
    }

from math import exp, sqrt, log
import pyretechnics.conversion as conv


def sample_normal(random_generator, mu, sd):
    """
    Returns sample from normal/gaussian distribution given mu and sd.
    """
    return random_generator.normal(mu, sd)


def sample_lognormal(random_generator, mu, sd):
    """
    Returns sample from log-normal distribution given mu and sd.
    """
    return random_generator.lognormal(mu, sd)


# FIXME: unused
def deltax_expected_value(mu_x, sigma_x):
    return conv.m_to_ft(exp(mu_x + (sigma_x ** 2.0) / 2.0))


# FIXME: unused
def deltax_coefficient_of_variation(sigma_x):
    return sqrt(exp(sigma_x ** 2.0) - 1.0)


def delta_x_sampler(spot_config, fireline_intensity, wind_speed_20ft):
    """
    Returns a function for randomly sampling ΔX, the spotting jump along the wind direction (in meters).
    """
    ln_params = resolve_lognormal_params(spot_config, fireline_intensity, wind_speed_20ft)
    mu_x      = ln_params["prob.lognormal.mu"]    # meters
    sigma_x   = ln_params["prob.lognormal.sigma"] # meters
    return lambda random_generator: sample_lognormal(random_generator, mu_x, sigma_x) # meters


# When will we have the default sigma_Y > E[ΔX]?
# It can be seen that this nonsensical situation
# happens iff sigma_X exceeds the following number:
#
# sqrt(log(1.0 + (0.88 ** 2.0) / (0.92 * 0.47))
#
# => 1.0131023746492023
sigma_y_scalar_m = 0.92 * 0.47 / (0.88 ** 2.0)


def himoto_resolve_default_sigma_y_from_lognormal_params(mu_x, sigma_x):
    es2h       = exp((sigma_x ** 2.0) / 2.0)
    avg_deltax = exp(mu_x) * es2h
    return sigma_y_scalar_m * avg_deltax * (es2h + 1.0) * (es2h - 1.0) # meters


def himoto_resolve_default_sigma_y(spot_config, fireline_intensity, wind_speed_20ft):
    ln_params = resolve_lognormal_params(spot_config, fireline_intensity, wind_speed_20ft)
    mu_x      = ln_params["prob.lognormal.mu"]    # meters
    sigma_x   = ln_params["prob.lognormal.sigma"] # meters
    return himoto_resolve_default_sigma_y_from_lognormal_params(mu_x, sigma_x) # meters


def resolve_crosswind_distance_stdev(spot_config, fireline_intensity, wind_speed_20ft):
    crosswind_distance_stdev = spot_config.get("crosswind_distance_stdev")
    if crosswind_distance_stdev != None:
        return crosswind_distance_stdev # meters
    else:
        return himoto_resolve_default_sigma_y(spot_config, fireline_intensity, wind_speed_20ft) # meters


def delta_y_sampler(spot_config, fireline_intensity, wind_speed_20ft):
    """
    Returns a function for randomly sampling ΔY, the spotting jump perpendicular to the wind direction (in meters).
    """
    sigma_y = resolve_crosswind_distance_stdev(spot_config, fireline_intensity, wind_speed_20ft) # meters
    return lambda random_generator: sample_normal(random_generator, 0.0, sigma_y) # meters

def sample_poisson(random_generator, mu):
    """
    Returns sample from poisson distribution given mu.
    """
    return random_generator.poisson(mu)


def sample_number_of_firebrands(random_generator, expected_firebrand_count):
    return sample_poisson(random_generator, expected_firebrand_count)

from math import exp


def firebrand_flight_survival_probability(spotting_distance, decay_distance):
    """
    Returns the probability that a firebrand will survive its flight (Perryman 2012) given:
    - spotting_distance :: meters (d)
    - decay_distance    :: meters (1/lambda)

    P(Survival) = exp(-d * lambda)
    """
    return exp(-spotting_distance / decay_distance)


def heat_of_preignition(temperature, fine_fuel_moisture):
    """
    Returns heat of preignition given:
    - temperature        :: degrees Celsius
    - fine_fuel_moisture :: 0-1

    Q_ig = 144.512 - 0.266 * T_o - 0.00058 * (T_o)^2 - T_o * M + 18.54 * (1 - exp(-15.1 * M)) + 640 * M (eq. 10)
    """
    T_o = temperature
    M   = fine_fuel_moisture
    # Heat required to reach ignition temperature
    Q_a = 144.512 - 0.266 * T_o - 0.00058 * (T_o ** 2.0)
    # Heat required to raise moisture to the boiling point
    Q_b = -T_o * M
    # Heat of desorption
    Q_c = 18.54 * (1.0 - exp(-15.1 * M))
    # Heat required to vaporize moisture
    Q_d = 640.0 * M
    return Q_a + Q_b + Q_c + Q_d


def schroeder_ignition_probability(temperature, fine_fuel_moisture):
    """
    Returns the probability of spot fire ignition (Schroeder 1969) given:
    - temperature        :: degrees Celsius
    - fine_fuel_moisture :: 0-1

    X           = (400 - Q_ig) / 10
    P(Ignition) = (0.000048 * X^4.3) / 50 (pg. 15)
    """
    Q_ig        = heat_of_preignition(temperature, fine_fuel_moisture)
    X           = max(0.0, 400.0 - Q_ig) / 10.0
    P_Ignition  = 0.000048 * (X ** 4.3) / 50.0
    return min(P_Ignition, 1.0)

from math import sqrt
import pyretechnics.conversion as conv


def albini_firebrand_maximum_height(firebrand_diameter):
    return 0.39e5 * firebrand_diameter


def albini_t_max(flame_length):
    """
    Returns the time of spot ignition using Albini1979spot in minutes given:
    - flame_length :: meters [z_F]

    a           = 5.963                                                             (D33)
    b           = a - 1.4                                                           (D34)
    D           = 0.003
    z           = 0.39 * D * 10^5
    w_F         = 2.3 * z_F^0.5                                                     (A58)
    t_c         = 1
    t_o         = t_c / (2 * z_F / w_F)
    travel_time = t_1 + t_2 + t_3 = 1.2 + (a / 3) * (((b + (z/z_F)) / a)^3/2 - 1)   (D43)
    """
    a           = 5.963  # dimensionless constant from (D33)
    b           = 4.563  # dimensionless constant from (D34)
    z           = 117.0  # maximum altitude of firebrands in meters [derived for (D44) in (Albini1979spot)]
    z_F         = flame_length                      # m
    w_F         = 2.3 * sqrt(flame_length)          # m/s
    charact_t   = conv.sec_to_min(2.0 * z_F / w_F)  # min
    # The following dimensionless factor is equal to t_T - t_o, with t_T defined by (D43) in Albini1979spot.
    travel_time = 1.2 + (a / 3.0) * (((b + z / z_F) / a) ** 1.5 - 1.0)
    return charact_t * travel_time


def spot_ignition_time(time_of_arrival, flame_length):
    """
    Returns the time of spot ignition using Albini 1979 and Perryman 2012 in minutes given:
    - time_of_arrival :: minutes
    - flame_length    :: meters

    t_spot = time_of_arrival + (2 * t_max) + t_ss
    """
    t_max          = albini_t_max(flame_length)
    t_steady_state = 20.0 # period of building up to steady state from ignition (min)
    return time_of_arrival + 2.0 * t_max + t_steady_state

from math import sin, cos, hypot, radians
import numpy as np
import pyretechnics.conversion as conv
import pyretechnics.fuel_models as fm


def is_in_bounds(y, x, rows, cols):
    """
    Returns True if the grid coordinate (y,x) lies within the bounds [0,rows) by [0,cols).
    """
    return (y >= 0) and (x >= 0) and (y < rows) and (x < cols)


def is_burnable_cell(fuel_model_cube, t, y, x):
    """
    Returns True if the space-time coordinate (t,y,x) contains a burnable fuel model.
    """
    fuel_model_number = fuel_model_cube.get(t,y,x)
    fuel_model        = fm.fuel_model_table.get(fuel_model_number)
    return fuel_model and fuel_model["burnable"]


def cast_firebrand(random_generator,
                   fuel_model_cube,
                   temperature_cube,
                   fuel_moisture_dead_1hr_cube,
                   fire_type_matrix,
                   firebrand_count_matrix, # NOTE: May be None
                   rows,
                   cols,
                   cell_height,
                   cell_width,
                   source_t,
                   source_y,
                   source_x,
                   decay_distance,
                   cos_wdir,
                   sin_wdir,
                   sample_delta_y_fn,
                   sample_delta_x_fn):
    """
    TODO: Add docstring
    Draws a random [ΔX, ΔY] pair of signed distances (in meters) from
    the supplied cell, representing the coordinates of the spotting jump in the directions
    parallel and perpendicular to the wind. ΔX will typically be positive (downwind),
    and positive ΔY means to the right of the downwind direction.
    """
    #=======================================================================================
    # Determine where the firebrand will land
    #=======================================================================================

    delta_y  = sample_delta_y_fn(random_generator)                    # meters
    delta_x  = sample_delta_x_fn(random_generator)                    # meters
    grid_dy  = delta_to_grid_dy(cos_wdir, sin_wdir, delta_x, delta_y) # meters
    grid_dx  = delta_to_grid_dx(cos_wdir, sin_wdir, delta_x, delta_y) # meters
    target_y = source_y + distance_to_n_cells(grid_dy, cell_height)
    target_x = source_x + distance_to_n_cells(grid_dx, cell_width)

    #=======================================================================================
    # Determine whether the firebrand will start a fire or fizzle out
    #=======================================================================================

    if is_in_bounds(target_y, target_x, rows, cols) and fire_type_matrix[target_y,target_x] == 0:
        # Firebrand landed on the grid in an unburned cell, so record it in firebrand_count_matrix (if provided)
        if isinstance(firebrand_count_matrix, np.ndarray):
            firebrand_count_matrix[target_y,target_x] += 1

        # Calculate the probability that the firebrand survived its flight and landed while still burning
        spotting_distance           = hypot(grid_dx, grid_dy) # meters
        flight_survival_probability = firebrand_flight_survival_probability(spotting_distance, decay_distance)

        # Roll the dice
        uniform_sample = random_generator.uniform(0.0, 1.0)

        if (uniform_sample <= flight_survival_probability
            and is_burnable_cell(fuel_model_cube, source_t, target_y, target_x)):
            # Firebrand landed in a cell with a burnable fuel model, so calculate its ignition probability
            temperature          = temperature_cube.get(source_t, target_y, target_x)            # degrees Celsius
            fine_fuel_moisture   = fuel_moisture_dead_1hr_cube.get(source_t, target_y, target_x) # kg/kg
            ignition_probability = schroeder_ignition_probability(temperature, fine_fuel_moisture)

            if uniform_sample <= flight_survival_probability * ignition_probability:
                # Firebrand ignited the target cell, so return its coordinates for later processing
                return (target_y, target_x)


def spread_firebrands(space_time_cubes, output_matrices, cube_resolution, space_time_coordinate,
                      random_generator, expected_firebrand_count, spot_config):
    """
    Given these inputs:
    - space_time_cubes          :: dictionary of (Lazy)SpaceTimeCube objects with these cell types
      - fuel_model                    :: integer index in fm.fuel_model_table
      - temperature                   :: degrees Celsius
      - wind_speed_10m                :: km/hr
      - upwind_direction              :: degrees clockwise from North
      - fuel_moisture_dead_1hr        :: kg moisture/kg ovendry weight
    - output_matrices           :: dictionary of 2D Numpy arrays whose spatial dimensions match the space_time_cubes
      - fire_type                     :: 2D byte array (0=unburned, 1=surface, 2=passive_crown, 3=active_crown)
      - fireline_intensity            :: 2D float array (kW/m)
      - flame_length                  :: 2D float array (m)
      - time_of_arrival               :: 2D float array (min)
      - firebrand_count               :: 2D integer array (number of firebrands) (Optional)
    - cube_resolution           :: tuple with these fields
      - band_duration                 :: minutes
      - cell_height                   :: meters
      - cell_width                    :: meters
    - space_time_coordinate     :: (t,y,x) coordinate in which the source cell burns
    - random_generator          :: numpy.random.Generator
    - expected_firebrand_count  :: expected number of firebrands to cast
    - spot_config               :: dictionary of spotting parameters
      - downwind_distance_mean        :: meters
      - fireline_intensity_exponent   :: downwind_distance_mean multiplier [I^fireline_intensity_exponent]
      - wind_speed_exponent           :: downwind_distance_mean multiplier [U^wind_speed_exponent]
      - downwind_variance_mean_ratio  :: meters^2 / meter [downwind_variance_mean_ratio = Var(X) / E(X)]
      - crosswind_distance_stdev      :: meters
      - decay_distance                :: meters

    samples a number of firebrands from a Poisson distribution parameterized by expected_firebrand_count,
    casts these from the space_time_coordinate into grid cells in the space-time cube, records their landing
    locations in output_matrices["firebrand_count"] (if provided), filters out all of the firebrands that
    fizzle out in either burnable or non-burnable fuels, and returns any that ignite new spot fires in
    a tuple with these fields:

    - ignition_time :: minutes
    - ignited_cells :: set of (y,x) grid coordinates
    """
    #=======================================================================================
    # Sample the number of firebrands to cast from the source cell
    #=======================================================================================

    num_firebrands = sample_number_of_firebrands(random_generator, expected_firebrand_count)

    if num_firebrands > 0:

        #=======================================================================================
        # Ensure that there is wind to transport the firebrands
        #=======================================================================================

        (t, y, x)      = space_time_coordinate
        wind_speed_10m = space_time_cubes["wind_speed_10m"].get(t,y,x) # km/hr

        if wind_speed_10m > 0.0:

            #=======================================================================================
            # Unpack all firebrand-related features of the source cell
            #=======================================================================================

            fuel_model_cube              = space_time_cubes["fuel_model"]
            temperature_cube             = space_time_cubes["temperature"]
            fuel_moisture_dead_1hr_cube  = space_time_cubes["fuel_moisture_dead_1hr"]
            fire_type_matrix             = output_matrices["fire_type"]
            firebrand_count_matrix       = output_matrices.get("firebrand_count")
            (_, rows, cols)              = fuel_model_cube.shape
            (_, cell_height, cell_width) = cube_resolution
            decay_distance               = spot_config["decay_distance"]
            upwind_direction             = space_time_cubes["upwind_direction"].get(t,y,x)
            downwind_direction           = radians(conv.opposite_direction(upwind_direction))
            cos_wdir                     = cos(downwind_direction)
            sin_wdir                     = sin(downwind_direction)
            fireline_intensity           = output_matrices["fireline_intensity"][y,x]             # m
            wind_speed_20ft              = conv.wind_speed_10m_to_wind_speed_20ft(wind_speed_10m) # km/hr
            wind_speed_20ft_mps          = conv.km_hr_to_mps(wind_speed_20ft)                     # m/s
            sample_delta_y_fn            = delta_y_sampler(spot_config, fireline_intensity, wind_speed_20ft_mps)
            sample_delta_x_fn            = delta_x_sampler(spot_config, fireline_intensity, wind_speed_20ft_mps)

            #=======================================================================================
            # Cast each firebrand, update firebrand_count_matrix, and accumulate any ignited cells
            #=======================================================================================

            ignited_cells = {ignited_cell for _i in range(num_firebrands)
                             if (ignited_cell := cast_firebrand(random_generator,
                                                                fuel_model_cube,
                                                                temperature_cube,
                                                                fuel_moisture_dead_1hr_cube,
                                                                fire_type_matrix,
                                                                firebrand_count_matrix,
                                                                rows,
                                                                cols,
                                                                cell_height,
                                                                cell_width,
                                                                t,
                                                                y,
                                                                x,
                                                                decay_distance,
                                                                cos_wdir,
                                                                sin_wdir,
                                                                sample_delta_y_fn,
                                                                sample_delta_x_fn))
                             is not None}

            #=======================================================================================
            # Return any cells ignited by firebrands along with their time of ignition
            #=======================================================================================

            if len(ignited_cells) > 0:
                time_of_arrival = output_matrices["time_of_arrival"][y,x]           # minutes
                flame_length    = output_matrices["flame_length"][y,x]              # meters
                ignition_time   = spot_ignition_time(time_of_arrival, flame_length) # minutes

                return (ignition_time, ignited_cells)

import matplotlib.pyplot as plt
import numpy as np
from pprint import pprint
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf

def calc_areal_heat_output_from_fuel_model(moisturized_fuel_model):
    fire_behavior      = sf.calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model)
    spread_rate        = fire_behavior["base_spread_rate"]            # m/min
    fireline_intensity = fire_behavior["base_fireline_intensity"]     # kW/m
    return sf.calc_areal_heat_output(spread_rate, fireline_intensity) # kJ/m^2

def save_areal_heat_output_as_histogram(areal_heat_output, moisture_category):
    plt.hist(areal_heat_output[moisture_category],
             range=(0, 60000),
             bins=12,
             density=True,
             histtype="bar",
             color="darkred",
             edgecolor="black")
    plt.title("Areal Heat Output for All Surface Fuel Models - " + str.capitalize(moisture_category) + " Conditions")
    plt.xlabel("Areal Heat Output (kJ/m^2)")
    plt.ylabel("Probability Density")
    plt.savefig("pics/fm_areal_heat_output_" + moisture_category + ".png")
    plt.close("all")

fuel_moisture_dry = [
    0.025, # dead_1hr
    0.050, # dead_10hr
    0.075, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    0.45, # live_herbaceous
    0.30, # live_woody
]

fuel_moisture_mod = [
    0.05, # dead_1hr
    0.10, # dead_10hr
    0.15, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    0.90, # live_herbaceous
    0.60, # live_woody
]

fuel_moisture_wet = [
    0.10, # dead_1hr
    0.20, # dead_10hr
    0.30, # dead_100hr
    0.00, # dead_herbaceous (will be set by moisturize for dynamic fuel models)
    1.80, # live_herbaceous
    1.20, # live_woody
]

areal_heat_output = {
    "dry": [calc_areal_heat_output_from_fuel_model(fm.moisturize(v, fuel_moisture_dry))
            for v in fm.fuel_model_table.values()],
    "mod": [calc_areal_heat_output_from_fuel_model(fm.moisturize(v, fuel_moisture_mod))
            for v in fm.fuel_model_table.values()],
    "wet": [calc_areal_heat_output_from_fuel_model(fm.moisturize(v, fuel_moisture_wet))
            for v in fm.fuel_model_table.values()],
}

for moisture_category in ["dry", "mod", "wet"]:
    save_areal_heat_output_as_histogram(areal_heat_output, moisture_category)

print("Median Areal Heat Output (kJ/m^2) for All Surface Fuel Models\n" + "=" * 80)
pprint({
    "dry": np.median(areal_heat_output["dry"]),
    "mod": np.median(areal_heat_output["mod"]),
    "wet": np.median(areal_heat_output["wet"]),
})

print("\nMean Areal Heat Output (kJ/m^2) for All Surface Fuel Models\n" + "=" * 80)
pprint({
    "dry": np.mean(areal_heat_output["dry"]),
    "mod": np.mean(areal_heat_output["mod"]),
    "wet": np.mean(areal_heat_output["wet"]),
})

print("\nMax Areal Heat Output (kJ/m^2) for All Surface Fuel Models\n" + "=" * 80)
pprint({
    "dry": np.max(areal_heat_output["dry"]),
    "mod": np.max(areal_heat_output["mod"]),
    "wet": np.max(areal_heat_output["wet"]),
})

from pprint import pprint
import pyretechnics.spot_fire as spot


cell_area = 900 # m^2


firebrand_counts = sorted([heat_output_per_area * cell_area * firebrands_per_unit_heat
                           for heat_output_per_area in range(0, 45001, 5000)
                           for firebrands_per_unit_heat in map(lambda x: 1/x, range(int(5e5), int(2e6)+1, int(5e5)))])


distance_penalties = sorted([spot.firebrand_flight_survival_probability(spotting_distance, decay_distance)
                             for spotting_distance in range(30, 901, 30)
                             for decay_distance in range(30, 901, 30)])


schroeder_probs = sorted([spot.schroeder_ignition_probability(temperature, moisture / 100)
                          for temperature in range(20, 41, 5)
                          for moisture in range(5, 21, 5)])


ignition_probs = sorted([dp * sp
                         for dp in distance_penalties
                         for sp in schroeder_probs])


spot_fire_counts = sorted([fb * ip
                           for fb in firebrand_counts
                           for ip in ignition_probs])


def percentile_indices(coll):
    """
    Return the 0th, 25th, 50th, 75th, and 100th percentile indices for coll.
    """
    max_index = len(coll) - 1
    return map(lambda p: (p, int(p * max_index)),
               [0.0, 0.25, 0.5, 0.75, 1.0])


firebrand_count_percs = {int(100 * p_v[0]): firebrand_counts[p_v[1]]
                         for p_v in percentile_indices(firebrand_counts)}


distance_penalty_percs = {int(100 * p_v[0]): distance_penalties[p_v[1]]
                          for p_v in percentile_indices(distance_penalties)}


schroeder_prob_percs = {int(100 * p_v[0]): schroeder_probs[p_v[1]]
                        for p_v in percentile_indices(schroeder_probs)}


ignition_prob_percs = {int(100 * p_v[0]): ignition_probs[p_v[1]]
                       for p_v in percentile_indices(ignition_probs)}


spot_fire_count_percs = {int(100 * p_v[0]): spot_fire_counts[p_v[1]]
                         for p_v in percentile_indices(spot_fire_counts)}


pprint({
    "firebrand_count_percentiles"               : firebrand_count_percs,
    "flight_distance_penalty_percentiles"       : distance_penalty_percs,
    "schroeder_ignition_probability_percentiles": schroeder_prob_percs,
    "spot_ignition_probability_percentiles"     : ignition_prob_percs,
    "spot_fire_count_percentiles"               : spot_fire_count_percs,
}, sort_dicts=False)

from math import sqrt, log

def himoto_eq_28_values(B_star):
    # NOTE: The following value for D seems absurdly low, and so does
    # the predicted E[ΔX]. I suspect a typo in the Himoto2005 paper.
    D                  = 0.08
    std_delta_x_over_D = 0.88 * (B_star ** (1.0 / 3.0))
    exp_delta_x_over_D = 0.47 * (B_star ** (2.0 / 3.0))
    cv_delta_x         = std_delta_x_over_D / exp_delta_x_over_D
    sigma_x            = sqrt(log(1.0 + cv_delta_x))
    exp_delta_x        = exp_delta_x_over_D * D
    mu_x               = log(exp_delta_x) - (sigma_x ** 2.0) / 2.0
    sigma_y            = D * 0.92
    return {
        "$B^*$"                             : B_star,
        "$\\text{CV}[\\Delta_X]$"           : "{:.0f}%".format(100.0 * cv_delta_x),
        "$\\sigma_X$"                       : "{:.2f}".format(sigma_x),
        "$\\sigma_Y/\\mathbb{E}[\\Delta_X]$": "{:.2f}".format(sigma_y / exp_delta_x),
        # NOTE the following ended up being nonsensical:
        # "E[ΔX] (m)" exp_delta_x
        # "μ_X"       mu_x
    }

himoto_typical_ranges = [himoto_eq_28_values(B_star) for B_star in [20, 50, 100, 150, 200]]
table_header          = list(himoto_typical_ranges[0].keys())
table_rows            = [list(d.values()) for d in himoto_typical_ranges]

print([table_header, *table_rows])

import numpy as np
import pyretechnics.conversion as conv
import pyretechnics.crown_fire as cf
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf
import pyretechnics.vector_utils as vu


# TODO: Create a version of this function that runs efficiently over a space_time_region
def burn_cell_as_head_fire(space_time_cubes, space_time_coordinate, use_wind_limit=True,
                           surface_lw_ratio_model="rothermel", crown_max_lw_ratio=None):
    """
    Given these inputs:
    - space_time_cubes             :: dictionary of (Lazy)SpaceTimeCube objects with these cell types
      - slope                         :: rise/run
      - aspect                        :: degrees clockwise from North
      - fuel_model                    :: integer index in fm.fuel_model_table
      - canopy_cover                  :: 0-1
      - canopy_height                 :: m
      - canopy_base_height            :: m
      - canopy_bulk_density           :: kg/m^3
      - wind_speed_10m                :: km/hr
      - upwind_direction              :: degrees clockwise from North
      - fuel_moisture_dead_1hr        :: kg moisture/kg ovendry weight
      - fuel_moisture_dead_10hr       :: kg moisture/kg ovendry weight
      - fuel_moisture_dead_100hr      :: kg moisture/kg ovendry weight
      - fuel_moisture_live_herbaceous :: kg moisture/kg ovendry weight
      - fuel_moisture_live_woody      :: kg moisture/kg ovendry weight
      - foliar_moisture               :: kg moisture/kg ovendry weight
      - fuel_spread_adjustment        :: float >= 0.0 (Optional: defaults to 1.0)
      - weather_spread_adjustment     :: float >= 0.0 (Optional: defaults to 1.0)
    - space_time_coordinate        :: (t,y,x)
    - use_wind_limit               :: boolean (Optional)
    - surface_lw_ratio_model       :: "rothermel" or "behave" (Optional)
    - crown_max_lw_ratio           :: float > 0.0 (Optional)

    return a dictionary with these fire behavior values for the space-time coordinate (t,y,x):
    - fire_type          :: "unburned", "surface", "passive_crown", or "active_crown"
    - spread_rate        :: m/min
    - spread_direction   :: (x, y, z) unit vector on the slope-tangential plane
    - fireline_intensity :: kW/m
    - flame_length       :: m
    """
    #================================================================================================
    # Destructure the space_time_coordinate
    #================================================================================================

    (t, y, x) = space_time_coordinate

    #================================================================================================
    # Unpack the space_time_cubes dictionary
    #================================================================================================

    # Topography, Fuel Model, and Vegetation
    slope               = space_time_cubes["slope"].get(t,y,x)               # rise/run
    aspect              = space_time_cubes["aspect"].get(t,y,x)              # degrees clockwise from North
    fuel_model_number   = space_time_cubes["fuel_model"].get(t,y,x)          # integer index in fm.fuel_model_table
    canopy_cover        = space_time_cubes["canopy_cover"].get(t,y,x)        # 0-1
    canopy_height       = space_time_cubes["canopy_height"].get(t,y,x)       # m
    canopy_base_height  = space_time_cubes["canopy_base_height"].get(t,y,x)  # m
    canopy_bulk_density = space_time_cubes["canopy_bulk_density"].get(t,y,x) # kg/m^3

    # Wind, Surface Moisture, and Foliar Moisture
    wind_speed_10m                = space_time_cubes["wind_speed_10m"].get(t,y,x)                # km/hr
    upwind_direction              = space_time_cubes["upwind_direction"].get(t,y,x)              # degrees clockwise from North
    fuel_moisture_dead_1hr        = space_time_cubes["fuel_moisture_dead_1hr"].get(t,y,x)        # kg moisture/kg ovendry weight
    fuel_moisture_dead_10hr       = space_time_cubes["fuel_moisture_dead_10hr"].get(t,y,x)       # kg moisture/kg ovendry weight
    fuel_moisture_dead_100hr      = space_time_cubes["fuel_moisture_dead_100hr"].get(t,y,x)      # kg moisture/kg ovendry weight
    fuel_moisture_live_herbaceous = space_time_cubes["fuel_moisture_live_herbaceous"].get(t,y,x) # kg moisture/kg ovendry weight
    fuel_moisture_live_woody      = space_time_cubes["fuel_moisture_live_woody"].get(t,y,x)      # kg moisture/kg ovendry weight
    foliar_moisture               = space_time_cubes["foliar_moisture"].get(t,y,x)               # kg moisture/kg ovendry weight

    # Spread Rate Adjustments (Optional)
    fuel_spread_adjustment    = (space_time_cubes["fuel_spread_adjustment"].get(t,y,x)
                                 if "fuel_spread_adjustment" in space_time_cubes
                                 else 1.0)                                         # float >= 0.0
    weather_spread_adjustment = (space_time_cubes["weather_spread_adjustment"].get(t,y,x)
                                 if "weather_spread_adjustment" in space_time_cubes
                                 else 1.0)                                         # float >= 0.0
    spread_rate_adjustment    = fuel_spread_adjustment * weather_spread_adjustment # float >= 0.0

    #================================================================================================
    # Check whether cell is burnable
    #================================================================================================

    fuel_model = fm.fuel_model_table.get(fuel_model_number)

    if not (fuel_model and fuel_model["burnable"]):
        # Encountered unknown or non-burnable fuel model

        #================================================================================================
        # Create a 3D unit vector pointing upslope on the slope-tangential plane
        #================================================================================================

        upslope_direction = conv.opposite_direction(aspect)
        slope_vector_2d   = conv.azimuthal_to_cartesian(slope, upslope_direction)
        slope_vector_3d   = vu.to_slope_plane(slope_vector_2d, slope_vector_2d)
        spread_direction  = vu.as_unit_vector(slope_vector_3d) if slope > 0.0 else np.asarray((0,1,0)) # default: North

        #============================================================================================
        # Return zero surface fire behavior
        #============================================================================================

        return {
            "fire_type"         : "unburned",
            "spread_rate"       : 0.0,
            "spread_direction"  : spread_direction,
            "fireline_intensity": 0.0,
            "flame_length"      : 0.0,
        }

    else:
        # Encountered burnable fuel model

        #============================================================================================
        # Compute derived parameters
        #============================================================================================

        fuel_moisture                = [fuel_moisture_dead_1hr,
                                        fuel_moisture_dead_10hr,
                                        fuel_moisture_dead_100hr,
                                        0.0, # fuel_moisture_dead_herbaceous
                                        fuel_moisture_live_herbaceous,
                                        fuel_moisture_live_woody]               # kg moisture/kg ovendry weight
        fuel_bed_depth               = fuel_model["delta"]                      # ft
        heat_of_combustion           = conv.Btu_lb_to_kJ_kg(fuel_model["h"][0]) # kJ/kg
        estimated_fine_fuel_moisture = fuel_moisture_dead_1hr                   # kg moisture/kg ovendry weight

        #============================================================================================
        # Calculate midflame wind speed
        #============================================================================================

        # Convert from 10m wind speed to 20ft wind speed
        wind_speed_20ft = conv.wind_speed_10m_to_wind_speed_20ft(wind_speed_10m) # km/hr

        # Convert 20ft wind speed from km/hr to m/min
        wind_speed_20ft_m_min = conv.km_hr_to_m_min(wind_speed_20ft) # m/min

        # Convert from 20ft wind speed to midflame wind speed in m/min
        midflame_wind_speed = sf.calc_midflame_wind_speed(wind_speed_20ft_m_min,       # m/min
                                                          fuel_bed_depth,              # ft
                                                          conv.m_to_ft(canopy_height), # ft
                                                          canopy_cover)                # 0-1

        #============================================================================================
        # Calculate surface fire behavior in the direction of maximum spread
        #============================================================================================

        # Apply fuel moisture to fuel model
        moisturized_fuel_model = fm.moisturize(fuel_model, fuel_moisture)

        # TODO: Memoize calc_surface_fire_behavior_no_wind_no_slope
        # Calculate no-wind-no-slope surface fire behavior
        surface_fire_min = sf.calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model,
                                                                          spread_rate_adjustment)

        # Calculate surface fire behavior in the direction of maximum spread
        surface_fire_max = sf.calc_surface_fire_behavior_max(surface_fire_min,
                                                             midflame_wind_speed,
                                                             upwind_direction,
                                                             slope,
                                                             aspect,
                                                             use_wind_limit,
                                                             surface_lw_ratio_model)

        # Simplify the surface fire behavior fields for future comparison/combination with the crown fire behavior values
        surface_fire_max_simple = sf.calc_surface_fire_behavior_in_direction(surface_fire_max,
                                                                             surface_fire_max["max_spread_direction"])

        #============================================================================================
        # Determine whether the surface fire transitions to a crown fire
        #============================================================================================

        if cf.van_wagner_crown_fire_initiation(surface_fire_max_simple["fireline_intensity"],
                                               canopy_cover,
                                               canopy_base_height,
                                               foliar_moisture):

            #========================================================================================
            # Calculate crown fire behavior in the direction of maximum spread
            #========================================================================================

            # Calculate crown fire behavior in the direction of maximum spread
            crown_fire_max = cf.calc_crown_fire_behavior_max(canopy_height, canopy_base_height,
                                                             canopy_bulk_density, heat_of_combustion,
                                                             estimated_fine_fuel_moisture,
                                                             wind_speed_10m, upwind_direction,
                                                             slope, aspect, crown_max_lw_ratio)

            # Simplify the crown fire behavior fields for future comparison/combination with the surface fire behavior values
            crown_fire_max_simple = cf.calc_crown_fire_behavior_in_direction(crown_fire_max,
                                                                             crown_fire_max["max_spread_direction"])

            #========================================================================================
            # Calculate combined fire behavior in the direction of maximum spread
            #========================================================================================

            combined_fire_max = cf.calc_combined_fire_behavior(surface_fire_max_simple, crown_fire_max_simple)

            #========================================================================================
            # Return the combined fire behavior in the direction of maximum spread
            #========================================================================================

            return combined_fire_max

        else:

            #========================================================================================
            # Return the surface fire behavior in the direction of maximum spread
            #========================================================================================

            return surface_fire_max_simple

import pyretechnics.conversion as conv
import pyretechnics.crown_fire as cf
import pyretechnics.fuel_models as fm
import pyretechnics.surface_fire as sf
import pyretechnics.vector_utils as vu


# TODO: Create a version of this function that runs efficiently over a space_time_region
def burn_cell_toward_azimuth(space_time_cubes, space_time_coordinate, azimuth, use_wind_limit=True,
                             surface_lw_ratio_model="rothermel", crown_max_lw_ratio=None):
    """
    Given these inputs:
    - space_time_cubes             :: dictionary of (Lazy)SpaceTimeCube objects with these cell types
      - slope                         :: rise/run
      - aspect                        :: degrees clockwise from North
      - fuel_model                    :: integer index in fm.fuel_model_table
      - canopy_cover                  :: 0-1
      - canopy_height                 :: m
      - canopy_base_height            :: m
      - canopy_bulk_density           :: kg/m^3
      - wind_speed_10m                :: km/hr
      - upwind_direction              :: degrees clockwise from North
      - fuel_moisture_dead_1hr        :: kg moisture/kg ovendry weight
      - fuel_moisture_dead_10hr       :: kg moisture/kg ovendry weight
      - fuel_moisture_dead_100hr      :: kg moisture/kg ovendry weight
      - fuel_moisture_live_herbaceous :: kg moisture/kg ovendry weight
      - fuel_moisture_live_woody      :: kg moisture/kg ovendry weight
      - foliar_moisture               :: kg moisture/kg ovendry weight
      - fuel_spread_adjustment        :: float >= 0.0 (Optional: defaults to 1.0)
      - weather_spread_adjustment     :: float >= 0.0 (Optional: defaults to 1.0)
    - space_time_coordinate        :: (t,y,x)
    - azimuth                      :: degrees clockwise from North on the horizontal plane
    - use_wind_limit               :: boolean (Optional)
    - surface_lw_ratio_model       :: "rothermel" or "behave" (Optional)
    - crown_max_lw_ratio           :: float > 0.0 (Optional)

    return a dictionary with these fire behavior values for the space-time coordinate (t,y,x):
    - fire_type          :: "unburned", "surface", "passive_crown", or "active_crown"
    - spread_rate        :: m/min
    - spread_direction   :: (x, y, z) unit vector on the slope-tangential plane
    - fireline_intensity :: kW/m
    - flame_length       :: m
    """
    #================================================================================================
    # Destructure the space_time_coordinate
    #================================================================================================

    (t, y, x) = space_time_coordinate

    #================================================================================================
    # Unpack the space_time_cubes dictionary
    #================================================================================================

    # Topography, Fuel Model, and Vegetation
    slope               = space_time_cubes["slope"].get(t,y,x)               # rise/run
    aspect              = space_time_cubes["aspect"].get(t,y,x)              # degrees clockwise from North
    fuel_model_number   = space_time_cubes["fuel_model"].get(t,y,x)          # integer index in fm.fuel_model_table
    canopy_cover        = space_time_cubes["canopy_cover"].get(t,y,x)        # 0-1
    canopy_height       = space_time_cubes["canopy_height"].get(t,y,x)       # m
    canopy_base_height  = space_time_cubes["canopy_base_height"].get(t,y,x)  # m
    canopy_bulk_density = space_time_cubes["canopy_bulk_density"].get(t,y,x) # kg/m^3

    # Wind, Surface Moisture, and Foliar Moisture
    wind_speed_10m                = space_time_cubes["wind_speed_10m"].get(t,y,x)                # km/hr
    upwind_direction              = space_time_cubes["upwind_direction"].get(t,y,x)              # degrees clockwise from North
    fuel_moisture_dead_1hr        = space_time_cubes["fuel_moisture_dead_1hr"].get(t,y,x)        # kg moisture/kg ovendry weight
    fuel_moisture_dead_10hr       = space_time_cubes["fuel_moisture_dead_10hr"].get(t,y,x)       # kg moisture/kg ovendry weight
    fuel_moisture_dead_100hr      = space_time_cubes["fuel_moisture_dead_100hr"].get(t,y,x)      # kg moisture/kg ovendry weight
    fuel_moisture_live_herbaceous = space_time_cubes["fuel_moisture_live_herbaceous"].get(t,y,x) # kg moisture/kg ovendry weight
    fuel_moisture_live_woody      = space_time_cubes["fuel_moisture_live_woody"].get(t,y,x)      # kg moisture/kg ovendry weight
    foliar_moisture               = space_time_cubes["foliar_moisture"].get(t,y,x)               # kg moisture/kg ovendry weight

    # Spread Rate Adjustments (Optional)
    fuel_spread_adjustment    = (space_time_cubes["fuel_spread_adjustment"].get(t,y,x)
                                 if "fuel_spread_adjustment" in space_time_cubes
                                 else 1.0)                                         # float >= 0.0
    weather_spread_adjustment = (space_time_cubes["weather_spread_adjustment"].get(t,y,x)
                                 if "weather_spread_adjustment" in space_time_cubes
                                 else 1.0)                                         # float >= 0.0
    spread_rate_adjustment    = fuel_spread_adjustment * weather_spread_adjustment # float >= 0.0

    #================================================================================================
    # Project a 2D unit vector pointing toward the azimuth onto the slope-tangential plane
    #================================================================================================

    upslope_direction = conv.opposite_direction(aspect)
    slope_vector_2d   = conv.azimuthal_to_cartesian(slope, upslope_direction)
    azimuth_vector_2d = conv.azimuthal_to_cartesian(1.0, azimuth)
    spread_direction  = vu.as_unit_vector(vu.to_slope_plane(azimuth_vector_2d, slope_vector_2d))

    #================================================================================================
    # Check whether cell is burnable
    #================================================================================================

    fuel_model = fm.fuel_model_table.get(fuel_model_number)

    if not (fuel_model and fuel_model["burnable"]):
        # Encountered unknown or non-burnable fuel model

        #============================================================================================
        # Return zero surface fire behavior in the direction of the azimuth vector
        #============================================================================================

        return {
            "fire_type"         : "unburned",
            "spread_rate"       : 0.0,
            "spread_direction"  : spread_direction,
            "fireline_intensity": 0.0,
            "flame_length"      : 0.0,
        }

    else:
        # Encountered burnable fuel model

        #============================================================================================
        # Compute derived parameters
        #============================================================================================

        fuel_moisture                = [fuel_moisture_dead_1hr,
                                        fuel_moisture_dead_10hr,
                                        fuel_moisture_dead_100hr,
                                        0.0, # fuel_moisture_dead_herbaceous
                                        fuel_moisture_live_herbaceous,
                                        fuel_moisture_live_woody]               # kg moisture/kg ovendry weight
        fuel_bed_depth               = fuel_model["delta"]                      # ft
        heat_of_combustion           = conv.Btu_lb_to_kJ_kg(fuel_model["h"][0]) # kJ/kg
        estimated_fine_fuel_moisture = fuel_moisture_dead_1hr                   # kg moisture/kg ovendry weight

        #============================================================================================
        # Calculate midflame wind speed
        #============================================================================================

        # Convert from 10m wind speed to 20ft wind speed
        wind_speed_20ft = conv.wind_speed_10m_to_wind_speed_20ft(wind_speed_10m) # km/hr

        # Convert 20ft wind speed from km/hr to m/min
        wind_speed_20ft_m_min = conv.km_hr_to_m_min(wind_speed_20ft) # m/min

        # Convert from 20ft wind speed to midflame wind speed in m/min
        midflame_wind_speed = sf.calc_midflame_wind_speed(wind_speed_20ft_m_min,       # m/min
                                                          fuel_bed_depth,              # ft
                                                          conv.m_to_ft(canopy_height), # ft
                                                          canopy_cover)                # 0-1

        #============================================================================================
        # Calculate surface fire behavior in the direction of maximum spread
        #============================================================================================

        # Apply fuel moisture to fuel model
        moisturized_fuel_model = fm.moisturize(fuel_model, fuel_moisture)

        # TODO: Memoize calc_surface_fire_behavior_no_wind_no_slope
        # Calculate no-wind-no-slope surface fire behavior
        surface_fire_min = sf.calc_surface_fire_behavior_no_wind_no_slope(moisturized_fuel_model,
                                                                          spread_rate_adjustment)

        # Calculate surface fire behavior in the direction of maximum spread
        surface_fire_max = sf.calc_surface_fire_behavior_max(surface_fire_min,
                                                             midflame_wind_speed,
                                                             upwind_direction,
                                                             slope,
                                                             aspect,
                                                             use_wind_limit,
                                                             surface_lw_ratio_model)

        #============================================================================================
        # Calculate surface fire behavior in the direction of the azimuth vector
        #============================================================================================

        surface_fire_azimuth = sf.calc_surface_fire_behavior_in_direction(surface_fire_max, spread_direction)

        #============================================================================================
        # Determine whether the surface fire transitions to a crown fire
        #============================================================================================

        if cf.van_wagner_crown_fire_initiation(surface_fire_azimuth["fireline_intensity"],
                                               canopy_cover,
                                               canopy_base_height,
                                               foliar_moisture):

            #========================================================================================
            # Calculate crown fire behavior in the direction of maximum spread
            #========================================================================================

            crown_fire_max = cf.calc_crown_fire_behavior_max(canopy_height, canopy_base_height,
                                                             canopy_bulk_density, heat_of_combustion,
                                                             estimated_fine_fuel_moisture,
                                                             wind_speed_10m, upwind_direction,
                                                             slope, aspect, crown_max_lw_ratio)

            #========================================================================================
            # Calculate crown fire behavior in the direction of the azimuth vector
            #========================================================================================

            crown_fire_azimuth = cf.calc_crown_fire_behavior_in_direction(crown_fire_max, spread_direction)

            #========================================================================================
            # Calculate combined fire behavior in the direction of the azimuth vector
            #========================================================================================

            combined_fire_azimuth = cf.calc_combined_fire_behavior(surface_fire_azimuth, crown_fire_azimuth)

            #========================================================================================
            # Return the combined fire behavior in the direction of the azimuth vector
            #========================================================================================

            return combined_fire_azimuth

        else:

            #========================================================================================
            # Return the surface fire behavior in the direction of the azimuth vector
            #========================================================================================

            return surface_fire_azimuth

from pprint import pprint
import pyretechnics.burn_cells as bc
from pyretechnics.space_time_cube import SpaceTimeCube

#============================================================================================
# Specify the SpaceTimeCube dimensions
#============================================================================================

cube_shape = (
    240,  # bands: 10 days @ 1 hour/band
    1000, # rows:  30 km @ 30 meters/row
    1000, # cols:  30 km @ 30 meters/col
)

#============================================================================================
# Create an input dictionary of SpaceTimeCubes (using constant data for this example)
#============================================================================================

space_time_cubes = {
    "slope"                        : SpaceTimeCube(cube_shape, 0.8),   # rise/run
    "aspect"                       : SpaceTimeCube(cube_shape, 225.0), # degrees clockwise from North
    "fuel_model"                   : SpaceTimeCube(cube_shape, 101),   # integer index in fm.fuel_model_table
    "canopy_cover"                 : SpaceTimeCube(cube_shape, 0.6),   # 0-1
    "canopy_height"                : SpaceTimeCube(cube_shape, 30.0),  # m
    "canopy_base_height"           : SpaceTimeCube(cube_shape, 3.0),   # m
    "canopy_bulk_density"          : SpaceTimeCube(cube_shape, 0.3),   # kg/m^3
    "wind_speed_10m"               : SpaceTimeCube(cube_shape, 30.0),  # km/hr
    "upwind_direction"             : SpaceTimeCube(cube_shape, 180.0), # degrees clockwise from North
    "fuel_moisture_dead_1hr"       : SpaceTimeCube(cube_shape, 0.05),  # kg moisture/kg ovendry weight
    "fuel_moisture_dead_10hr"      : SpaceTimeCube(cube_shape, 0.10),  # kg moisture/kg ovendry weight
    "fuel_moisture_dead_100hr"     : SpaceTimeCube(cube_shape, 0.15),  # kg moisture/kg ovendry weight
    "fuel_moisture_live_herbaceous": SpaceTimeCube(cube_shape, 0.90),  # kg moisture/kg ovendry weight
    "fuel_moisture_live_woody"     : SpaceTimeCube(cube_shape, 0.60),  # kg moisture/kg ovendry weight
    "foliar_moisture"              : SpaceTimeCube(cube_shape, 0.90),  # kg moisture/kg ovendry weight
    "fuel_spread_adjustment"       : SpaceTimeCube(cube_shape, 1.0),   # float >= 0.0 (Optional: defaults to 1.0)
    "weather_spread_adjustment"    : SpaceTimeCube(cube_shape, 1.0),   # float >= 0.0 (Optional: defaults to 1.0)
}

#============================================================================================
# Specify a space-time coordinate (t,y,x) within the extent of the SpaceTimeCube dimensions
#============================================================================================

space_time_coordinate = (24, 100, 100)

#============================================================================================
# Calculate combined fire behavior in the direction of maximum spread (with wind limit)
#============================================================================================

combined_behavior_limited = bc.burn_cell_as_head_fire(space_time_cubes, space_time_coordinate)

#============================================================================================
# Calculate combined fire behavior in the direction of maximum spread (without wind limit)
#============================================================================================

combined_behavior_unlimited = bc.burn_cell_as_head_fire(space_time_cubes, space_time_coordinate,
                                                        use_wind_limit=False)

#============================================================================================
# Display combined fire behavior in the direction of maximum spread (with wind limit)
#============================================================================================

print("Fire Behavior from Combined Surface and Crown Fire (with Wind Limit) at Coordinate "
      + str(space_time_coordinate) + "\n" + "=" * 100)
pprint(combined_behavior_limited)

#============================================================================================
# Display combined fire behavior in the direction of maximum spread (without wind limit)
#============================================================================================

print("\nFire Behavior from Combined Surface and Crown Fire (without Wind Limit) at Coordinate "
      + str(space_time_coordinate) + "\n" + "=" * 100)
pprint(combined_behavior_unlimited)

from pprint import pprint
import pyretechnics.burn_cells as bc
from pyretechnics.space_time_cube import SpaceTimeCube

#============================================================================================
# Specify the SpaceTimeCube dimensions
#============================================================================================

cube_shape = (
    240,  # bands: 10 days @ 1 hour/band
    1000, # rows:  30 km @ 30 meters/row
    1000, # cols:  30 km @ 30 meters/col
)

#============================================================================================
# Create an input dictionary of SpaceTimeCubes (using constant data for this example)
#============================================================================================

space_time_cubes = {
    "slope"                        : SpaceTimeCube(cube_shape, 0.8),   # rise/run
    "aspect"                       : SpaceTimeCube(cube_shape, 225.0), # degrees clockwise from North
    "fuel_model"                   : SpaceTimeCube(cube_shape, 101),   # integer index in fm.fuel_model_table
    "canopy_cover"                 : SpaceTimeCube(cube_shape, 0.6),   # 0-1
    "canopy_height"                : SpaceTimeCube(cube_shape, 30.0),  # m
    "canopy_base_height"           : SpaceTimeCube(cube_shape, 3.0),   # m
    "canopy_bulk_density"          : SpaceTimeCube(cube_shape, 0.3),   # kg/m^3
    "wind_speed_10m"               : SpaceTimeCube(cube_shape, 30.0),  # km/hr
    "upwind_direction"             : SpaceTimeCube(cube_shape, 180.0), # degrees clockwise from North
    "fuel_moisture_dead_1hr"       : SpaceTimeCube(cube_shape, 0.05),  # kg moisture/kg ovendry weight
    "fuel_moisture_dead_10hr"      : SpaceTimeCube(cube_shape, 0.10),  # kg moisture/kg ovendry weight
    "fuel_moisture_dead_100hr"     : SpaceTimeCube(cube_shape, 0.15),  # kg moisture/kg ovendry weight
    "fuel_moisture_live_herbaceous": SpaceTimeCube(cube_shape, 0.90),  # kg moisture/kg ovendry weight
    "fuel_moisture_live_woody"     : SpaceTimeCube(cube_shape, 0.60),  # kg moisture/kg ovendry weight
    "foliar_moisture"              : SpaceTimeCube(cube_shape, 0.90),  # kg moisture/kg ovendry weight
    "fuel_spread_adjustment"       : SpaceTimeCube(cube_shape, 1.0),   # float >= 0.0 (Optional: defaults to 1.0)
    "weather_spread_adjustment"    : SpaceTimeCube(cube_shape, 1.0),   # float >= 0.0 (Optional: defaults to 1.0)
}

#============================================================================================
# Specify a space-time coordinate (t,y,x) within the extent of the SpaceTimeCube dimensions
#============================================================================================

space_time_coordinate = (24, 100, 100)

#============================================================================================
# Specify an azimuth to spread the fire towards
#============================================================================================

spread_azimuth = 90.0 # degrees clockwise from North on the horizontal plane

#============================================================================================
# Calculate combined fire behavior in the direction of the azimuth (with wind limit)
#============================================================================================

combined_behavior_limited = bc.burn_cell_toward_azimuth(space_time_cubes, space_time_coordinate, spread_azimuth)

#============================================================================================
# Calculate combined fire behavior in the direction of the azimuth (without wind limit)
#============================================================================================

combined_behavior_unlimited = bc.burn_cell_toward_azimuth(space_time_cubes, space_time_coordinate, spread_azimuth,
                                                          use_wind_limit=False)

#============================================================================================
# Display combined fire behavior in the direction of the azimuth (with wind limit)
#============================================================================================

print("Fire Behavior from Combined Surface and Crown Fire (with Wind Limit) at Coordinate "
      + str(space_time_coordinate) + "\n" + "=" * 100)
pprint(combined_behavior_limited)

#============================================================================================
# Display combined fire behavior in the direction of the azimuth (without wind limit)
#============================================================================================

print("\nFire Behavior from Combined Surface and Crown Fire (without Wind Limit) at Coordinate "
      + str(space_time_coordinate) + "\n" + "=" * 100)
pprint(combined_behavior_unlimited)

import numpy as np


def calc_dphi_dx_approx(phi, dx, x, y, cols):
    """
    Calculate the spatial gradient of the phi raster in the x (west->east)
    direction at grid cell (x,y) given the cell width dx.
    """
    east_x = x + 1
    west_x = x - 1
    if east_x < cols:
        if west_x >= 0:
            return (phi[y][east_x] - phi[y][west_x]) / (2.0 * dx)
        else:
            return (phi[y][east_x] - phi[y][x]) / dx
    else:
        if west_x >= 0:
            return (phi[y][x] - phi[y][west_x]) / dx
        else:
            return 0.0


def calc_dphi_dy_approx(phi, dy, x, y, rows):
    """
    Calculate the spatial gradient of the phi raster in the y (south->north)
    direction at grid cell (x,y) given the cell height dy.
    """
    north_y = y + 1
    south_y = y - 1
    if north_y < rows:
        if south_y >= 0:
            return (phi[north_y][x] - phi[south_y][x]) / (2.0 * dy)
        else:
            return (phi[north_y][x] - phi[y][x]) / dy
    else:
        if south_y >= 0:
            return (phi[y][x] - phi[south_y][x]) / dy
        else:
            return 0.0


def calc_phi_gradient_approx(phi, dx, dy, x, y):
    """
    Calculate the spatial gradient of the phi raster at grid cell (x,y)
    given the cell width dx and the cell height dy.
    """
    (rows, cols) = phi.shape
    dphi_dx      = calc_dphi_dx_approx(phi, dx, x, y, cols)
    dphi_dy      = calc_dphi_dy_approx(phi, dy, x, y, rows)
    return np.asarray((dphi_dx, dphi_dy))