Merge pull request #39 from switchbox-data/30-modify-ratebase-growth-calc

30 modify ratebase growth calc

Author: alxsmith

src/npa_howtopay/capex_project.py

@@ -35,10 +35,27 @@ def to_df(self) -> pl.DataFrame:
         })
 
 
-# functions for generating dataframe rows for capex projects
 def get_synthetic_initial_capex_projects(
     start_year: int, initial_ratebase: float, depreciation_lifetime: int
 ) -> pl.DataFrame:
+    """
+    Generate synthetic capex projects to represent the projects that make up the initial ratebase.
+
+    Creates a series of historical capex projects that would result in the given initial ratebase value, assuming straight-line depreciation. Uses the triangular number formula to create a uniform distribution of projects over the depreciation lifetime, where each project has the same original cost. Projects are distributed evenly over depreciation_lifetime years leading up to start_year.
+
+    Args:
+        start_year: The first year of the model
+        initial_ratebase: The target ratebase value at start_year
+        depreciation_lifetime: The blended depreciation lifetime for the synthetic projects
+
+    Returns:
+        pl.DataFrame with columns:
+            - project_year: Year the project was initiated
+            - project_type: "synthetic_initial"
+            - original_cost: Cost of the project
+            - depreciation_lifetime: Depreciation lifetime in years
+            - retirement_year: Year the project is fully depreciated
+    """
     total_weight = (depreciation_lifetime * (depreciation_lifetime + 1) / 2) / depreciation_lifetime
     est_original_cost_per_year = initial_ratebase / total_weight
     project_years = range(start_year - depreciation_lifetime + 1, start_year + 1)
@@ -56,11 +73,34 @@ def get_non_lpp_gas_capex_projects(
     current_ratebase: float,
     baseline_non_lpp_gas_ratebase_growth: float,
     depreciation_lifetime: int,
+    construction_inflation_rate: float,
 ) -> pl.DataFrame:
+    """
+    Generate capex projects for non-LPP (non-leak prone pipe) gas infrastructure.
+
+    These represent routine gas infrastructure investments not related to pipe replacement or npas,
+    such as meter replacements, regulator stations, etc. The cost is calculated as a
+    percentage of current ratebase, adjusted for construction cost inflation.
+
+    Args:
+        year: The year to generate projects for
+        current_ratebase: Current value of the gas utility's ratebase
+        baseline_non_lpp_gas_ratebase_growth: Annual growth rate for non-LPP capex as fraction of ratebase
+        depreciation_lifetime: Blended depreciation lifetime in years for these projects
+        construction_inflation_rate: Annual inflation rate for construction costs
+
+    Returns:
+        pl.DataFrame with columns:
+            - project_year: Year the project was initiated
+            - project_type: "misc" for miscellaneous gas infrastructure
+            - original_cost: Cost of the project
+            - depreciation_lifetime: Depreciation lifetime in years
+            - retirement_year: Year the project is fully depreciated
+    """
     return CapexProject(
         project_year=year,
         project_type="misc",
-        original_cost=current_ratebase * baseline_non_lpp_gas_ratebase_growth,
+        original_cost=current_ratebase * baseline_non_lpp_gas_ratebase_growth * (1 + construction_inflation_rate),
         depreciation_lifetime=depreciation_lifetime,
     ).to_df()
 
@@ -72,18 +112,29 @@ def get_lpp_gas_capex_projects(
     depreciation_lifetime: int,
 ) -> pl.DataFrame:
     """
-    Inputs:
-    - year: int
-    - gas_bau_lpp_costs_per_year: pl.DataFrame
-      - columns: year, cost
-      - year is not required to be unique
-    - npa_projects: pl.DataFrame
-      - npa columns
-    - depreciation_lifetime: int
-
-    Outputs:
-    - pl.DataFrame
-      - capex project columns
+    Generate capex projects for leak-prone pipe (LPP) replacement in the gas system.
+
+    This function calculates the remaining pipe replacement costs after accounting for pipe
+    replacements avoided by NPA projects. If NPAs avoid all planned pipe replacements in a given
+    year, returns an empty dataframe.
+
+    Args:
+        year: The year to generate projects for
+        gas_bau_lpp_costs_per_year: DataFrame containing business-as-usual pipe replacement costs
+            with columns:
+            - year: Year of planned replacement
+            - cost: Cost of planned replacement
+            Note: Multiple entries may exist per year
+        npa_projects: DataFrame containing NPA project details, used to calculate avoided pipe costs
+        depreciation_lifetime: Depreciation lifetime in years for pipe replacement projects
+
+    Returns:
+        pl.DataFrame with columns:
+            - project_year: Year the project was initiated
+            - project_type: "pipeline" for pipe replacement projects
+            - original_cost: Cost of the project after subtracting avoided costs
+            - depreciation_lifetime: Depreciation lifetime in years
+            - retirement_year: Year the project is fully depreciated
     """
     npas_this_year = npa_projects.filter(pl.col("project_year") == year)
     npa_pipe_costs_avoided = compute_npa_pipe_cost_avoided_from_df(year, npas_this_year)
@@ -107,11 +158,33 @@ def get_non_npa_electric_capex_projects(
     current_ratebase: float,
     baseline_electric_ratebase_growth: float,
     depreciation_lifetime: int,
+    construction_inflation_rate: float,
 ) -> pl.DataFrame:
+    """
+    Generate capex projects for non-NPA non-grid upgrade electric system upgrades.
+
+    This function calculates the baseline capital expenditures for the electric system,
+    excluding NPA-related projects. The expenditure grows with both the baseline growth rate
+    and construction inflation.
+
+    Args:
+        year: The year to generate projects for
+        current_ratebase: Current value of the electric utility's ratebase
+        baseline_electric_ratebase_growth: Annual growth rate of non-NPA electric capex as fraction of ratebase
+        depreciation_lifetime: Blended depreciation lifetime in years for electric system projects
+        construction_inflation_rate: Annual inflation rate for construction costs
+
+    Returns:
+        pl.DataFrame with columns:
+            - project_year: Year the project was initiated
+            - project_type: "misc" for miscellaneous electric system upgrades
+            - original_cost: Cost of the project including construction inflation
+            - depreciation_lifetime: Depreciation lifetime in years
+    """
     return CapexProject(
         project_year=year,
         project_type="misc",
-        original_cost=current_ratebase * baseline_electric_ratebase_growth,
+        original_cost=current_ratebase * baseline_electric_ratebase_growth * (1 + construction_inflation_rate),
         depreciation_lifetime=depreciation_lifetime,
     ).to_df()
 
@@ -124,6 +197,28 @@ def get_grid_upgrade_capex_projects(
     distribution_cost_per_peak_kw_increase: float,
     grid_upgrade_depreciation_lifetime: int,
 ) -> pl.DataFrame:
+    """
+    Generate capex projects for grid upgrades needed to support NPA installations.
+
+    This function calculates the required grid upgrades based on the peak power increase
+    from heat pumps and air conditioners installed as part of NPA projects. The cost
+    scales linearly with the total peak power increase.
+
+    Args:
+        year: The year to generate projects for
+        npa_projects: DataFrame containing NPA project details
+        peak_hp_kw: Peak power draw in kW for a heat pump
+        peak_aircon_kw: Peak power draw in kW for an air conditioner
+        distribution_cost_per_peak_kw_increase: Cost per kW of increasing grid capacity in year of project
+        grid_upgrade_depreciation_lifetime: Depreciation lifetime in years for grid upgrades
+
+    Returns:
+        pl.DataFrame with columns:
+            - project_year: Year the project was initiated
+            - project_type: "grid_upgrade" for grid capacity upgrades
+            - original_cost: Total cost of grid upgrades
+            - depreciation_lifetime: Depreciation lifetime in years
+    """
     npas_this_year = npa_projects.filter(pl.col("project_year") == year)
     peak_kw_increase = compute_peak_kw_increase_from_df(year, npas_this_year, peak_hp_kw, peak_aircon_kw)
     if peak_kw_increase > 0:
@@ -140,6 +235,25 @@ def get_grid_upgrade_capex_projects(
 def get_npa_capex_projects(
     year: int, npa_projects: pl.DataFrame, npa_install_cost: float, npa_lifetime: int
 ) -> pl.DataFrame:
+    """
+    Generate capex projects for NPA (non-pipe alternative) installations.
+
+    This function calculates the capital costs associated with installing NPAs in a given year.
+    The total cost is based on the number of heat pump conversions and the per-unit installation cost.
+
+    Args:
+        year: The year to generate projects for
+        npa_projects: DataFrame containing NPA project details
+        npa_install_cost: Cost per household of installing an NPA
+        npa_lifetime: Expected lifetime in years of an NPA installation
+
+    Returns:
+        pl.DataFrame with columns:
+            - project_year: Year the project was initiated
+            - project_type: "npa" for NPA installations
+            - original_cost: Total cost of NPA installations
+            - depreciation_lifetime: Depreciation lifetime in years
+    """
     npas_this_year = npa_projects.filter(pl.col("project_year") == year)
     npa_total_cost = npa_install_cost * compute_hp_converts_from_df(
         year, npas_this_year, cumulative=False, npa_only=True
@@ -152,8 +266,24 @@ def get_npa_capex_projects(
         return return_empty_capex_df()
 
 
-# functions for computing things given a dataframe of capex projects
 def compute_ratebase_from_capex_projects(year: int, df: pl.DataFrame) -> float:
+    """Compute the ratebase value for a given year from capital projects.
+
+    For each project, the ratebase value declines linearly from the original cost to zero over the depreciation lifetime.
+    Projects that haven't started yet (year < project_year) have zero ratebase value.
+    Projects that are fully depreciated have zero ratebase value.
+    Projects that are in the year of the project have the full original cost added to the ratebase.
+
+    Args:
+        year: The year to compute ratebase for
+        df: DataFrame containing capital projects with columns:
+            - project_year: int - Year project was initiated
+            - original_cost: float - Original cost of the project
+            - depreciation_lifetime: int - Number of years to depreciate over
+
+    Returns:
+        float: Total ratebase value for the year across all projects
+    """
     df = df.with_columns(
         pl.when(pl.lit(year) < pl.col("project_year"))
         .then(pl.lit(0))
@@ -164,6 +294,21 @@ def compute_ratebase_from_capex_projects(year: int, df: pl.DataFrame) -> float:
 
 
 def compute_depreciation_expense_from_capex_projects(year: int, df: pl.DataFrame) -> float:
+    """Compute annual depreciation expense for capital projects.
+
+    For each project, depreciation expense is the original cost divided evenly over the depreciation lifetime.
+    Depreciation starts the year after the project year and continues for the depreciation lifetime.
+
+    Args:
+        year: The year to compute depreciation expense for
+        df: DataFrame containing capital projects with columns:
+            - project_year: int - Year project was initiated
+            - original_cost: float - Original cost of the project
+            - depreciation_lifetime: int - Number of years to depreciate over
+
+    Returns:
+        float: Total depreciation expense for the year across all projects
+    """
     return float(
         df.select(
             pl.when(

src/npa_howtopay/model.py

@@ -548,6 +548,7 @@ def run_model(scenario_params: ScenarioParams, input_params: InputParams, ts_par
                     current_ratebase=gas_ratebase,
                     baseline_non_lpp_gas_ratebase_growth=input_params.gas.baseline_non_lpp_ratebase_growth,
                     depreciation_lifetime=input_params.gas.non_lpp_depreciation_lifetime,
+                    construction_inflation_rate=input_params.shared.construction_inflation_rate,
                 ),
                 cp.get_lpp_gas_capex_projects(
                     year=year,
@@ -568,6 +569,7 @@ def run_model(scenario_params: ScenarioParams, input_params: InputParams, ts_par
                     current_ratebase=electric_ratebase,
                     baseline_electric_ratebase_growth=input_params.electric.baseline_non_npa_ratebase_growth,
                     depreciation_lifetime=input_params.electric.default_depreciation_lifetime,
+                    construction_inflation_rate=input_params.shared.construction_inflation_rate,
                 ),
                 cp.get_grid_upgrade_capex_projects(
                     year=year,

tests/test_capex_project.py

@@ -1,5 +1,5 @@
-## Switchbox
-## 2025-08-25
+# Switchbox
+# 2025-08-25
 
 import numpy as np
 import polars as pl
@@ -39,12 +39,16 @@ def test_get_synthetic_initial_capex_projects():
 
 def test_get_non_lpp_gas_capex_projects():
     df = get_non_lpp_gas_capex_projects(
-        year=2025, current_ratebase=1000, baseline_non_lpp_gas_ratebase_growth=0.015, depreciation_lifetime=60
+        year=2025,
+        current_ratebase=1000,
+        baseline_non_lpp_gas_ratebase_growth=0.015,
+        depreciation_lifetime=60,
+        construction_inflation_rate=0.02,
     )
     ref_df = pl.DataFrame({
         "project_year": [2025],
         "project_type": ["misc"],
-        "original_cost": [15],
+        "original_cost": [15.3],
         "depreciation_lifetime": [60],
         "retirement_year": [2085],
     })
@@ -53,19 +57,23 @@ def test_get_non_lpp_gas_capex_projects():
 
 def test_get_non_npa_electric_capex_projects():
     df = get_non_npa_electric_capex_projects(
-        year=2025, current_ratebase=1000, baseline_electric_ratebase_growth=0.03, depreciation_lifetime=60
+        year=2025,
+        current_ratebase=1000,
+        baseline_electric_ratebase_growth=0.03,
+        depreciation_lifetime=60,
+        construction_inflation_rate=0.02,
     )
     ref_df = pl.DataFrame({
         "project_year": [2025],
         "project_type": ["misc"],
-        "original_cost": [30],
+        "original_cost": [30.6],
         "depreciation_lifetime": [60],
         "retirement_year": [2085],
     })
     assert_frame_equal(ref_df, df, check_dtypes=False)
 
 
-## NPA TESTS
+# NPA TESTS
 @pytest.fixture
 def npa_projects():
     return pl.concat(
@@ -148,7 +156,8 @@ def test_get_grid_upgrade_capex_projects(npa_projects):
     ref_df = pl.DataFrame({
         "project_year": [2025],
         "project_type": ["grid_upgrade"],
-        "original_cost": [34000],  # three projects increase peak_kw by 14, 11, 9
+        # three projects increase peak_kw by 14, 11, 9
+        "original_cost": [34000],
         "depreciation_lifetime": [30],
         "retirement_year": [2055],
     })
@@ -167,7 +176,7 @@ def test_get_npa_capex_projects(npa_projects):
     assert_frame_equal(ref_df, df, check_dtypes=False)
 
 
-## COMPUTE TESTS
+# COMPUTE TESTS
 capex_df = pl.DataFrame({
     "project_year": [2025, 2026, 2027],
     "original_cost": [1000, 1000, 1000],