Fix LaTeX math delimiters in model explanation and ER calculation accordions for proper rendering in Gradio

dashboard/app.py

@@ -209,19 +209,96 @@ with gr.Blocks() as demo:
     </div>
     """, elem_id="sequestr-header")
     gr.Markdown(r"""
-# Declining Increment Model
+# Mangrove Emissions Reduction (ER) Model & Dashboard
 
-**Growth Model:** Annual increment declines linearly to zero; total size is the sum of non-negative increments. No negative growth: DBH and height never decrease. Mortality is compounded annually according to the schedule in the config.
+Welcome to the Mangrove ER Model Dashboard, a tool designed by [Sequestr](https://www.sequestr.io/) for simulating and analyzing carbon sequestration in mangrove restoration projects. This dashboard allows users to explore the "Declining Increment" growth model, adjust key project parameters, and visualize the resulting carbon and emission reduction outcomes over time.
+""")
+    with gr.Accordion("How the Model Works", open=False):
+        gr.Markdown(r"""
+## How the Model Works
+
+The core of this dashboard is an emissions reduction (ER) model that projects mangrove growth, biomass accumulation, and carbon sequestration based on user-defined parameters and a chosen growth model. Currently, the active model is the **Declining Increment** model.
 
-**Continuous mode uses the analytical formula:**
+### Declining Increment Growth Model
 
+This model assumes that the annual growth increment (for both Diameter at Breast Height - DBH, and Height) declines linearly over time, eventually reaching zero. The total size at any given age is the sum of all non-negative annual increments up to that age. This ensures that tree size never decreases.
+
+**1. Discrete Declining Increment:**
+The size at a given age $t$ (in years) is calculated by summing annual increments:
+$$
+\text{size}(t) = \text{initial\_size} + \sum_{i=1}^{t} \text{increment}(i)
 $$
-\text{size}(t) = \text{initial} + r_0 \cdot \left(t - \frac{t^2}{2T_m}\right)
+Where the increment for year $i$ is:
 $$
+\text{increment}(i) = \max\left(0, r_0 \cdot \left(1 - \frac{i - 0.5}{T_m}\right)\right)
+$$
+-   $\text{initial\_size}$: The initial DBH (cm) or Height (m) at planting (age 0).
+-   $r_0$: The initial annual growth increment (cm/year for DBH, m/year for Height).
+-   $T_m$: The time (in years) at which the annual growth increment becomes zero.
 
-This version is smoother and may yield slightly different results than the discrete sum, especially for short time periods or small Tm.
+**2. Continuous Declining Increment (Analytical Formula):**
+For a smoother representation, the continuous version uses an analytical formula:
+$$
+\text{size}(t) = \text{initial\_size} + r_0 \cdot \left(t - \frac{t^2}{2T_m}\right), \quad \text{for } 0 \le t \le T_m
+$$
+If $t > T_m$, then $\text{size}(t) = \text{size}(T_m)$.
+This version may yield slightly different results from the discrete sum, especially for short time periods or small $T_m$ values. The dashboard configuration specifies which version is active.
 
-*Species are displayed as "Rhizophora spp." and "Avicennia germinans" throughout the dashboard for clarity.*
+### Survival and Mortality
+The number of surviving trees in a cohort is calculated annually. Mortality can be specified using either:
+1.  **Annual Mortality Rates**: A percentage mortality rate applied each year, potentially varying for the first few years and then stabilizing.
+2.  **DBH-Dependent Mortality (Optional, if configured)**: Mortality rate $m$ is a function of tree DBH:
+$$
+m = m_{\text{ref}} \cdot \left(\frac{\text{DBH}_{\text{ref}}}{\text{DBH}}\right)^p
+$$
+-   $m_{\text{ref}}$: Reference mortality rate at $\text{DBH}_{\text{ref}}$.
+-   $\text{DBH}_{\text{ref}}$: Reference DBH.
+-   $p$: Exponent controlling the sensitivity of mortality to DBH.
+The calculated $m$ is capped (e.g., between 0 and 0.99).
+""")
+    with gr.Accordion("How Emission Reductions (ERs) are Calculated", open=False):
+        gr.Markdown(r"""
+## How Emission Reductions (ERs) are Calculated
+
+The model follows these steps to estimate net CO2 emission reductions:
+
+**1. Biomass Calculation:**
+Total above-ground and below-ground biomass per tree is calculated using allometric equations, which typically relate DBH and Height to biomass. For example, using equations from Zanvo et al. (2023):
+-   For *Rhizophora spp.* (Species A): $\text{Biomass}_{\text{total}} = 1.938 \times (\text{DBH}^2 \cdot H)^{0.67628}$ (kg)
+-   For *Avicennia germinans* (Species B): $\text{Biomass}_{\text{total}} = 1.486 \times (\text{DBH}^2 \cdot H)^{0.55864}$ (kg)
+    *(Note: The specific equations are defined in the model configuration.)*
+
+**2. Carbon Stock Calculation:**
+The total carbon stock in living biomass per hectare is calculated:
+$$
+\text{Carbon Stock (tC/ha)} = \frac{\text{Biomass per tree (kg)} \times \text{Surviving Trees per ha} \times \text{Biomass to Carbon ratio}}{1000}
+$$
+-   The Biomass to Carbon ratio (e.g., 0.47) converts biomass to carbon mass.
+
+**3. Gross CO2 Sequestration:**
+The carbon stock is then converted to tons of CO2 equivalent:
+$$
+\text{Gross CO2eq (tCO2/ha)} = \text{Carbon Stock (tC/ha)} \times \text{Carbon to CO2 ratio}
+$$
+-   The Carbon to CO2 ratio (typically 3.67) is based on molecular weights.
+
+**4. Soil Carbon (Optional):**
+If configured, annual soil carbon sequestration is added:
+$$
+\text{Soil Carbon CO2eq (tCO2/ha/yr)} = \text{User Defined Value (e.g. 1.0 tCO2/ha/yr)}
+$$
+This is added to the gross CO2 sequestration from biomass.
+
+**5. Net Emission Reductions (ERs):**
+Adjustments are made to the gross CO2 sequestration (including soil carbon, if applicable) to determine net ERs eligible for crediting:
+$$
+\text{Net ERs} = (\text{Gross CO2eq}_{\text{biomass + soil}}) \times (1 - \text{Buffer \%}) - (\text{Gross CO2eq}_{\text{biomass + soil}} \times \text{Leakage \%}) - (\text{Baseline Emissions per ha} \times \text{Area})
+$$
+-   **Buffer Pool**: A percentage deduction to account for risks like project failure or natural disturbances.
+-   **Leakage**: Emissions occurring outside the project boundary due to project activities (often assumed to be 0% for mangrove projects if activities are self-contained).
+-   **Baseline Emissions**: Emissions that would have occurred in the absence of the project (e.g., from degrading land).
+
+This dashboard visualizes these values annually over the project duration, providing insights into the project's carbon sequestration potential.
 """)
     # --- Key Input Params Card ---
     config = yaml.safe_load(open(MODEL_CONFIGS["Declining Increment"]))
@@ -254,10 +331,7 @@ This version is smoother and may yield slightly different results than the discr
     )
     gr.Markdown("""
 ### Key Model Inputs
-""" + species_md + "\n" + project_md)
-    gr.Markdown("""
-### Annual Mortality Rate
-""" + mortality_md)
+""" + species_md)
     gr.Markdown("""
 ### Carbon Details
 """ + carbon_md)
@@ -284,33 +358,14 @@ This version is smoother and may yield slightly different results than the discr
                         year_3 = gr.Number(value=year_3_default, label="Area to be planted in year 3 (ha)", interactive=True)
                         year_4 = gr.Number(value=year_4_default, label="Area to be planted in year 4 (ha)", interactive=True)
                         year_5 = gr.Number(value=year_5_default, label="Area to be planted in year 5 (ha)", interactive=True)
-                # Column 2: Species A Parameters (as gr.Slider)
+                # Column 2: Planting Density (as gr.Slider)
                 with gr.Column(scale=1, min_width=220):
-                    with gr.Accordion("Species A Parameters", open=True):
+                    with gr.Accordion("Planting Density", open=True):
                         pdA = config['species'][0]['planting_density']
-                        r0dA = config['species'][0]['declining_increment']['dbh']['r0']
-                        tmdA = config['species'][0]['declining_increment']['dbh']['T_m']
-                        r0hA = config['species'][0]['declining_increment']['height']['r0']
-                        tmhA = config['species'][0]['declining_increment']['height']['T_m']
-                        planting_density_A = gr.Slider(minimum=pdA*0.75, maximum=pdA*1.25, value=pdA, step=1, label="Initial planting density for Species A")
-                        r0_dbh_A = gr.Slider(minimum=r0dA*0.75, maximum=r0dA*1.25, value=r0dA, step=0.01, label="Initial DBH growth rate for Species A")
-                        tm_dbh_A = gr.Slider(minimum=tmdA*0.75, maximum=tmdA*1.25, value=tmdA, step=1, label="DBH growth duration for Species A")
-                        r0_height_A = gr.Slider(minimum=r0hA*0.75, maximum=r0hA*1.25, value=r0hA, step=0.01, label="Initial height growth rate for Species A")
-                        tm_height_A = gr.Slider(minimum=tmhA*0.75, maximum=tmhA*1.25, value=tmhA, step=1, label="Height growth duration for Species A")
-                # Column 3: Species B Parameters (as gr.Slider)
-                with gr.Column(scale=1, min_width=220):
-                    with gr.Accordion("Species B Parameters", open=True):
                         pdB = config['species'][1]['planting_density']
-                        r0dB = config['species'][1]['declining_increment']['dbh']['r0']
-                        tmdB = config['species'][1]['declining_increment']['dbh']['T_m']
-                        r0hB = config['species'][1]['declining_increment']['height']['r0']
-                        tmhB = config['species'][1]['declining_increment']['height']['T_m']
+                        planting_density_A = gr.Slider(minimum=pdA*0.75, maximum=pdA*1.25, value=pdA, step=1, label="Initial planting density for Species A")
                         planting_density_B = gr.Slider(minimum=pdB*0.75, maximum=pdB*1.25, value=pdB, step=1, label="Initial planting density for Species B")
-                        r0_dbh_B = gr.Slider(minimum=r0dB*0.75, maximum=r0dB*1.25, value=r0dB, step=0.01, label="Initial DBH growth rate for Species B")
-                        tm_dbh_B = gr.Slider(minimum=tmdB*0.75, maximum=tmdB*1.25, value=tmdB, step=1, label="DBH growth duration for Species B")
-                        r0_height_B = gr.Slider(minimum=r0hB*0.75, maximum=r0hB*1.25, value=r0hB, step=0.01, label="Initial height growth rate for Species B")
-                        tm_height_B = gr.Slider(minimum=tmhB*0.75, maximum=tmhB*1.25, value=tmhB, step=1, label="Height growth duration for Species B")
-                # Columns 4-5: Mortality Rates (as gr.Slider, split across two half-width columns in a single row)
+                # Columns 3-4: Mortality Rates (as gr.Slider, split across two half-width columns)
                 with gr.Column(scale=2, min_width=300):
                     with gr.Accordion("Mortality Rates (%)", open=True):
                         mort_defaults = [config['species'][0]['mortality_rates'][f'year_{yr}'] for yr in range(1, 11)]
@@ -323,12 +378,8 @@ This version is smoother and may yield slightly different results than the discr
                                 mort_sub = gr.Slider(minimum=mort_sub_default*0.75, maximum=mort_sub_default*1.25, value=mort_sub_default, step=0.1, label="Annual mortality rate for years 11+")
                         mort_vars = mort_vars_1 + mort_vars_2
             # After the mortality columns, add:
-            project_duration_default = config['project']['duration_years']
-            buffer_pct_default = config['carbon']['buffer_percentage']
             soil_carbon_default = config['carbon']['soil_carbon_per_ha_per_year']
 
-            project_duration = gr.Number(value=project_duration_default, label="Project Duration (years)", interactive=True, info="Total project duration in years")
-            buffer_pct = gr.Number(value=buffer_pct_default, label="Buffer %", interactive=True, info="Buffer pool percentage for risk mitigation")
             soil_carbon = gr.Number(value=soil_carbon_default, label="Soil Carbon per ha per year (tCO2)", interactive=True, info="Annual soil carbon addition per hectare")
 
             # Add a Reset to Defaults button
@@ -338,15 +389,7 @@ This version is smoother and may yield slightly different results than the discr
                 # Reload config and return all default values in widget order
                 config = yaml.safe_load(open(MODEL_CONFIGS["Declining Increment"]))
                 pdA = config['species'][0]['planting_density']
-                r0dA = config['species'][0]['declining_increment']['dbh']['r0']
-                tmdA = config['species'][0]['declining_increment']['dbh']['T_m']
-                r0hA = config['species'][0]['declining_increment']['height']['r0']
-                tmhA = config['species'][0]['declining_increment']['height']['T_m']
                 pdB = config['species'][1]['planting_density']
-                r0dB = config['species'][1]['declining_increment']['dbh']['r0']
-                tmdB = config['species'][1]['declining_increment']['dbh']['T_m']
-                r0hB = config['species'][1]['declining_increment']['height']['r0']
-                tmhB = config['species'][1]['declining_increment']['height']['T_m']
                 mort_defaults = [config['species'][0]['mortality_rates'][f'year_{yr}'] for yr in range(1, 11)]
                 mort_sub_default = config['species'][0]['mortality_rates']['subsequent']
                 return [
@@ -355,20 +398,16 @@ This version is smoother and may yield slightly different results than the discr
                     config['project']['planting_schedule']['year_3'],
                     config['project']['planting_schedule']['year_4'],
                     config['project']['planting_schedule']['year_5'],
-                    pdA, r0dA, tmdA, r0hA, tmhA,
-                    pdB, r0dB, tmdB, r0hB, tmhB,
+                    pdA, pdB,
                     *mort_defaults, mort_sub_default,
-                    config['project']['duration_years'],
-                    config['carbon']['buffer_percentage'],
                     config['carbon']['soil_carbon_per_ha_per_year']
                 ]
             reset_btn.click(
                 reset_to_defaults,
                 inputs=[],
                 outputs=[year_1, year_2, year_3, year_4, year_5,
-                         planting_density_A, r0_dbh_A, tm_dbh_A, r0_height_A, tm_height_A,
-                         planting_density_B, r0_dbh_B, tm_dbh_B, r0_height_B, tm_height_B,
-                         *mort_vars, mort_sub, project_duration, buffer_pct, soil_carbon]
+                         planting_density_A, planting_density_B,
+                         *mort_vars, mort_sub, soil_carbon]
             )
 
             update_btn = gr.Button("Update Results", variant="primary")
@@ -391,32 +430,21 @@ This version is smoother and may yield slightly different results than the discr
             # --- End tabbed tables ---
             # Update the update_declining_increment callback to use these new inputs
             def update_declining_increment(y1, y2, y3, y4, y5,
-                                           planting_density_A, r0_dbh_A, tm_dbh_A, r0_height_A, tm_height_A,
-                                           planting_density_B, r0_dbh_B, tm_dbh_B, r0_height_B, tm_height_B,
-                                           *mortality_inputs_and_project_params):
-                # Unpack the last three from the end
-                *mortality_inputs, project_duration, buffer_pct, soil_carbon = mortality_inputs_and_project_params
+                                           planting_density_A, planting_density_B,
+                                           *mortality_inputs_and_soil_carbon):
+                # Unpack the last one from the end
+                *mortality_inputs, soil_carbon = mortality_inputs_and_soil_carbon
                 config = update_planting_schedule(MODEL_CONFIGS["Declining Increment"], [y1, y2, y3, y4, y5])
                 # Update species_A params
                 config['species'][0]['planting_density'] = planting_density_A
-                config['species'][0]['declining_increment']['dbh']['r0'] = r0_dbh_A
-                config['species'][0]['declining_increment']['dbh']['T_m'] = tm_dbh_A
-                config['species'][0]['declining_increment']['height']['r0'] = r0_height_A
-                config['species'][0]['declining_increment']['height']['T_m'] = tm_height_A
                 # Update species_B params
                 config['species'][1]['planting_density'] = planting_density_B
-                config['species'][1]['declining_increment']['dbh']['r0'] = r0_dbh_B
-                config['species'][1]['declining_increment']['dbh']['T_m'] = tm_dbh_B
-                config['species'][1]['declining_increment']['height']['r0'] = r0_height_B
-                config['species'][1]['declining_increment']['height']['T_m'] = tm_height_B
                 # Update mortality for BOTH species from the same UI values (years 1-10 + subsequent)
                 for i in [0, 1]:
                     for yr_idx, yr in enumerate(range(1, 11)):
                         config['species'][i]['mortality_rates'][f'year_{yr}'] = mortality_inputs[yr_idx]
                     config['species'][i]['mortality_rates']['subsequent'] = mortality_inputs[10]
                 # Update project/carbon params
-                config['project']['duration_years'] = int(project_duration)
-                config['carbon']['buffer_percentage'] = buffer_pct
                 config['carbon']['soil_carbon_per_ha_per_year'] = soil_carbon
                 with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as tmp:
                     yaml.dump(config, tmp)
@@ -445,18 +473,16 @@ This version is smoother and may yield slightly different results than the discr
             update_btn.click(
                 update_declining_increment,
                 inputs=[year_1, year_2, year_3, year_4, year_5,
-                        planting_density_A, r0_dbh_A, tm_dbh_A, r0_height_A, tm_height_A,
-                        planting_density_B, r0_dbh_B, tm_dbh_B, r0_height_B, tm_height_B,
-                        *mort_vars, mort_sub, project_duration, buffer_pct, soil_carbon],
+                        planting_density_A, planting_density_B,
+                        *mort_vars, mort_sub, soil_carbon],
                 outputs=[carbon_plot, biomass_plot, annual_plot, growth_plot, summary_box, results_box, species_box, survival_box, biomass_debug_table]
             )
             # Show initial results
             c, b, a, g, summary, r, s, surv, biomass_debug_df = update_declining_increment(
                 year_1_default, year_2_default, year_3_default, year_4_default, year_5_default,
-                pdA, r0dA, tmdA, r0hA, tmhA,
-                pdB, r0dB, tmdB, r0hB, tmhB,
+                pdA, pdB,
                 *mort_defaults, mort_sub_default,
-                project_duration_default, buffer_pct_default, soil_carbon_default
+                soil_carbon_default
             )
             carbon_plot.value = c
             biomass_plot.value = b