EPPT-2588: Fire Severity Index: Add a BuildUpIndex class to IMPROVER

improver/api/__init__.py

@@ -28,6 +28,7 @@
     "ApplyRainForestsCalibration": "improver.calibration.rainforest_calibration",
     "ApplyReliabilityCalibration": "improver.calibration.reliability_calibration",
     "BaseNeighbourhoodProcessing": "improver.nbhood.nbhood",
+    "BuildUpIndex": "improver.fire_weather.build_up_index",
     "CalculateForecastBias": "improver.calibration.simple_bias_correction",
     "CalculateWindChill": "improver.temperature.feels_like_temperature",
     "CalibratedForecastDistributionParameters": "improver.calibration.emos_calibration",

improver/fire_weather/__init__.py

@@ -30,7 +30,7 @@ class FireWeatherIndexBase(BasePlugin):
     The Canadian Forest Fire Weather Index System requires specific units
     for all calculations. These are fixed and cannot be overridden:
 
-    - Temperature: degrees Celsius (degC)
+    - Temperature: degrees Celsius (Celsius)
     - Precipitation: millimeters (mm)
     - Relative humidity: dimensionless fraction (1)
     - Wind speed: kilometers per hour (km/h)
@@ -50,7 +50,7 @@ class FireWeatherIndexBase(BasePlugin):
     # Fixed unit conversions for all cube types used in fire weather calculations
     # These units are required by the Canadian FWI System and cannot be changed
     _REQUIRED_UNITS: dict[str, str] = {
-        "temperature": "degC",
+        "temperature": "Celsius",
         "precipitation": "mm",
         "relative_humidity": "1",
         "wind_speed": "km/h",

improver/fire_weather/build_up_index.py

@@ -0,0 +1,78 @@
+# (C) Crown Copyright, Met Office. All rights reserved.
+#
+# This file is part of 'IMPROVER' and is released under the BSD 3-Clause license.
+# See LICENSE in the root of the repository for full licensing details.
+import numpy as np
+from iris.cube import Cube
+
+from improver.fire_weather import FireWeatherIndexBase
+
+
+class BuildUpIndex(FireWeatherIndexBase):
+    """
+    Plugin to calculate the Build Up Index (BUI) following
+    the Canadian Forest Fire Weather Index System.
+
+    The BUI is a numerical rating of the total amount of fuel available
+    for combustion. It combines the Duff Moisture Code (DMC) and the
+    Drought Code (DC) to represent the fuel buildup.
+
+    This process is adapted directly from:
+        Equations and FORTRAN Program for the
+        Canadian Forest Fire Weather Index System
+        (C.E. Van Wagner and T.L. Pickett, 1985).
+        Page 7, Equations 27a-27b.
+
+    Expected input units:
+        - Duff Moisture Code (DMC): dimensionless
+        - Drought Code (DC): dimensionless
+    """
+
+    INPUT_CUBE_NAMES = ["duff_moisture_code", "drought_code"]
+    OUTPUT_CUBE_NAME = "build_up_index"
+    # Map input cube names to internal attribute names for consistency
+    INPUT_ATTRIBUTE_MAPPINGS = {
+        "duff_moisture_code": "input_dmc",
+        "drought_code": "input_dc",
+    }
+
+    input_dmc: Cube
+    input_dc: Cube
+
+    def _calculate(self) -> np.ndarray:
+        """Calculates the Build Up Index (BUI) from DMC and DC.
+
+        From Van Wagner and Pickett (1985), Page 7: Equations 27a-27b.
+
+        Returns:
+            np.ndarray: The calculated BUI values.
+        """
+        dmc_data = self.input_dmc.data
+        dc_data = self.input_dc.data
+
+        # Condition 1: If both DMC and DC are zero, set BUI = 0
+        both_zero = (dmc_data == 0.0) & (dc_data == 0.0)
+
+        # Condition 2: If DMC <= 0.4 * DC use equation 27a
+        use_27a = dmc_data <= 0.4 * dc_data
+
+        # Calculate equations, suppressing divide-by-zero warnings
+        # (the np.where will handle the zero cases correctly)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            bui_27a = (0.8 * dmc_data * dc_data) / (dmc_data + 0.4 * dc_data)
+
+            # Condition 3: If DMC > 0.4 * DC use equation 27b
+            bui_27b = dmc_data - (
+                1.0 - (0.8 * dc_data / (dmc_data + 0.4 * dc_data))
+            ) * (0.92 + (0.0114 * dmc_data) ** 1.7)
+
+        # Apply conditions using np.where:
+        # 1. If both_zero: BUI = 0
+        # 2. Elif use_27a (DMC <= 0.4*DC): BUI = bui_27a
+        # 3. Else (DMC > 0.4*DC): BUI = bui_27b
+        bui = np.where(both_zero, 0.0, np.where(use_27a, bui_27a, bui_27b))
+
+        # Ensure BUI is never negative
+        bui = np.clip(bui, 0.0, None)
+
+        return bui

improver_tests/fire_weather/__init__.py

@@ -73,7 +73,7 @@ def make_input_cubes(
     Example:
         >>> cubes = make_input_cubes(
         ...     [
-        ...         ("air_temperature", 20.0, "degC", False),
+        ...         ("air_temperature", 20.0, "Celsius", False),
         ...         ("lwe_thickness_of_precipitation_amount", 1.0, "mm", True),
         ...     ]
         ... )