Merge pull request #166 from softwareengineerprogrammer/drawdown-parameter-schedule

Drawdown Parameter Schedule [v.3.13.12]

Author: softwareengineerprogrammer

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.13.10
+current_version = 3.13.12
 commit = True
 tag = True
 

.cookiecutterrc

@@ -54,7 +54,7 @@ default_context:
     sphinx_doctest: "no"
     sphinx_theme: "sphinx-py3doc-enhanced-theme"
     test_matrix_separate_coverage: "no"
-    version: 3.13.10
+    version: 3.13.12
     version_manager: "bump2version"
     website: "https://github.com/NREL"
     year_from: "2023"

.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 #   pre-commit install --install-hooks
 # To update the versions:
 #   pre-commit autoupdate
-exclude: '^(\.tox|ci/templates|\.bumpversion\.cfg|src/geophires_x(?!/(GEOPHIRESv3|EconomicsSam|EconomicsSamCashFlow|EconomicsUtils|EconomicsSamPreRevenue|EconomicsSamCalculations|SurfacePlantUtils|NumpyUtils|UPPReservoir)\.py))(/|$)'
+exclude: '^(\.tox|ci/templates|\.bumpversion\.cfg|src/geophires_x(?!/(GEOPHIRESv3|EconomicsSam|EconomicsSamCashFlow|EconomicsUtils|EconomicsSamPreRevenue|EconomicsSamCalculations||ParameterUtils|SurfacePlantUtils|NumpyUtils|UPPReservoir)\.py))(/|$)'
 # Note the order is intentional to avoid multiple passes of the hooks
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit

CHANGELOG.rst

@@ -8,6 +8,8 @@ GEOPHIRES v3 (2023-2026)
 3.13
 ^^^^
 
+3.13.12: `Drawdown Parameter Schedule <https://github.com/softwareengineerprogrammer/GEOPHIRES/pull/166>`__ | `release <https://github.com/NREL/GEOPHIRES-X/releases/tag/v3.13.12>`__
+
 3.13.10: `Well integrity parameterization to trigger redrilling <https://github.com/softwareengineerprogrammer/GEOPHIRES/pull/163>`__ | `release <https://github.com/NREL/GEOPHIRES-X/releases/tag/v3.13.10>`__
 
 3.13.9: `Add hip-ra-x-result.json schema and HipRaXResult <https://github.com/NatLabRockies/GEOPHIRES-X/pull/499>`__ | `release <https://github.com/NREL/GEOPHIRES-X/releases/tag/v3.13.9>`__

README.rst

@@ -58,9 +58,9 @@ Free software: `MIT license <LICENSE>`__
     :alt: Supported implementations
     :target: https://pypi.org/project/geophires-x
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/softwareengineerprogrammer/GEOPHIRES-X/v3.13.10.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/softwareengineerprogrammer/GEOPHIRES-X/v3.13.12.svg
     :alt: Commits since latest release
-    :target: https://github.com/softwareengineerprogrammer/GEOPHIRES-X/compare/v3.13.10...main
+    :target: https://github.com/softwareengineerprogrammer/GEOPHIRES-X/compare/v3.13.12...main
 
 .. |docs| image:: https://readthedocs.org/projects/GEOPHIRES-X/badge/?style=flat
     :target: https://softwareengineerprogrammer.github.io/GEOPHIRES

docs/conf.py

@@ -18,7 +18,7 @@
 year = '2025'
 author = 'NREL'
 copyright = f'{year}, {author}'
-version = release = '3.13.10'
+version = release = '3.13.12'
 
 pygments_style = 'trac'
 templates_path = ['./templates']

setup.py

@@ -13,7 +13,7 @@ def read(*names, **kwargs):
 
 setup(
     name='geophires-x',
-    version='3.13.10',
+    version='3.13.12',
     license='MIT',
     description='GEOPHIRES is a free and open-source geothermal techno-economic simulator.',
     long_description='{}\n{}'.format(

src/geophires_x/Economics.py

@@ -16,8 +16,8 @@
     project_payback_period_parameter, inflation_cost_during_construction_output_parameter, \
     interest_during_construction_output_parameter, total_capex_parameter_output_parameter, \
     overnight_capital_cost_output_parameter, CONSTRUCTION_CAPEX_SCHEDULE_PARAMETER_NAME, \
-    _YEAR_INDEX_VALUE_EXPLANATION_SNIPPET, investment_tax_credit_output_parameter, expand_schedule_dsl, \
-    lcoh_output_parameter, lcoc_output_parameter
+    _YEAR_INDEX_VALUE_EXPLANATION_SNIPPET, investment_tax_credit_output_parameter, lcoh_output_parameter, lcoc_output_parameter
+from geophires_x.ParameterUtils import expand_schedule_dsl
 from geophires_x.GeoPHIRESUtils import quantity
 from geophires_x.OptionList import Configuration, WellDrillingCostCorrelation, EconomicModel, EndUseOptions, PlantType, \
     _WellDrillingCostCorrelationCitation

src/geophires_x/EconomicsUtils.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
-from geophires_x.GeoPHIRESUtils import is_float, is_int
-from geophires_x.Parameter import OutputParameter, SCHEDULE_DSL_MULTIPLIER_SYMBOL
+from geophires_x.Parameter import OutputParameter
 from geophires_x.Units import Units, PercentUnit, TimeUnit, CurrencyUnit, CurrencyFrequencyUnit, EnergyCostUnit
 
 CONSTRUCTION_CAPEX_SCHEDULE_PARAMETER_NAME = 'Construction CAPEX Schedule'
@@ -248,90 +247,9 @@ def investment_tax_credit_output_parameter() -> OutputParameter:
 
 def expand_schedule_dsl(schedule_strings: list[str | float], total_years: int) -> list[float]:
     """
-    Parse a duration-based scheduling DSL and expand it into a fixed-length time-series array.
-
-    Syntax: `[Value] * [Years], [Value] * [Years], ..., [Terminal Value]`
-
-    The terminal (last) value is repeated to fill `total_years`.  A bare scalar
-    (e.g. `['2.5']`) is treated as a terminal value and broadcast across all years.
-
-    Examples::
-
-        expand_schedule_dsl(['1.0 * 3', '0.1'], total_years=6)
-        # => [1.0, 1.0, 1.0, 0.1, 0.1, 0.1]
-
-        expand_schedule_dsl(['2.5'], total_years=4)
-        # => [2.5, 2.5, 2.5, 2.5]
-
-    :param schedule_strings: list of DSL segment strings.  Each element is either
-        `"<value> * <years>"` (a run-length segment) or `"<value>"` (a scalar,
-        which becomes the terminal value when it is the last element, or a 1-year
-        segment otherwise).
-    :param total_years: The total number of years the expanded array must span
-        (typically `construction_years + plant_lifetime`).
-    :returns: A `list[float]` of length `total_years`.
-    :raises ValueError: On malformed DSL strings or when explicit segments exceed
-        `total_years`.
+    Deprecated, call ParameterUtils.expand_schedule_dsl
     """
 
-    if total_years <= 0:
-        return []
-
-    if not schedule_strings:
-        return [0.0] * total_years
-
-    segments: list[tuple[float, int | None]] = []
-    for raw in schedule_strings:
-        raw = str(raw).strip()
-        if SCHEDULE_DSL_MULTIPLIER_SYMBOL in raw:
-            parts = raw.split(SCHEDULE_DSL_MULTIPLIER_SYMBOL)
-            if len(parts) != 2:
-                raise ValueError(f'Invalid schedule segment "{raw}": expected "<value> * <years>".')
-
-            val_raw = parts[0].strip()
-            if not is_float(val_raw):
-                raise ValueError(f'Invalid schedule segment "{raw}": "{val_raw}" is not a float.')
-            value = float(val_raw)
-            if value < 0:
-                raise ValueError(f'Invalid schedule segment "{raw}": {val_raw} is negative.')
-
-            years_raw = parts[1].strip()
-            if not is_int(years_raw):
-                raise ValueError(f'Invalid schedule segment "{raw}": "{years_raw}" is not an int.')
-
-            years = int(years_raw)
-            if years < 0:
-                raise ValueError(f'Invalid schedule segment "{raw}": year count must be non-negative.')
-            segments.append((value, years))
-        else:
-            if not is_float(raw):
-                raise ValueError(f'Invalid schedule segment "{raw}": "{raw}" is not a float.')
-
-            value = float(raw)
-            segments.append((value, None))
-
-    result: list[float] = []
-    terminal_value = 0.0
-
-    for idx, (value, years) in enumerate(segments):
-        is_last = idx == len(segments) - 1
-        if years is not None:
-            result.extend([value] * years)
-            terminal_value = value
-        else:
-            if is_last:
-                terminal_value = value
-            else:
-                result.append(value)
-                terminal_value = value
-
-    if len(result) > total_years:
-        raise ValueError(
-            f'Invalid schedule: Schedule expands to {len(result)} years ' f'which exceeds total_years={total_years}.'
-        )
-
-    remaining = total_years - len(result)
-    if remaining > 0:
-        result.extend([terminal_value] * remaining)
-
-    return result
+    from geophires_x.ParameterUtils import expand_schedule_dsl
+
+    return expand_schedule_dsl(schedule_strings, total_years)

src/geophires_x/ParameterUtils.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import copy
+import logging
+
+from geophires_x.GeoPHIRESUtils import is_float, is_int
+from geophires_x.Parameter import SCHEDULE_DSL_MULTIPLIER_SYMBOL
+
+
+_log = logging.getLogger(__name__)
+
+
+def expand_schedule_dsl(
+    schedule_strings: list[str | float], total_years: int, allow_schedule_length_to_exceed_total_years: bool = False
+) -> list[float]:
+    """
+    Parse a duration-based scheduling DSL and expand it into a fixed-length time-series array.
+
+    Syntax: `[Value] * [Years], [Value] * [Years], ..., [Terminal Value]`
+
+    The terminal (last) value is repeated to fill `total_years`.  A bare scalar
+    (e.g. `['2.5']`) is treated as a terminal value and broadcast across all years.
+
+    Examples::
+
+        expand_schedule_dsl(['1.0 * 3', '0.1'], total_years=6)
+        # => [1.0, 1.0, 1.0, 0.1, 0.1, 0.1]
+
+        expand_schedule_dsl(['2.5'], total_years=4)
+        # => [2.5, 2.5, 2.5, 2.5]
+
+    :param schedule_strings: list of DSL segment strings.  Each element is either
+        `"<value> * <years>"` (a run-length segment) or `"<value>"` (a scalar,
+        which becomes the terminal value when it is the last element, or a 1-year
+        segment otherwise).
+    :param total_years: The total number of years the expanded array must span
+        (typically `construction_years + plant_lifetime`).
+    :returns: A `list[float]` of length `total_years`.
+    :raises ValueError: On malformed DSL strings or when explicit segments exceed
+        `total_years`.
+    """
+
+    if total_years <= 0:
+        return []
+
+    if not schedule_strings:
+        return [0.0] * total_years
+
+    segments: list[tuple[float, int | None]] = []
+    for raw in schedule_strings:
+        raw = str(raw).strip()
+        if SCHEDULE_DSL_MULTIPLIER_SYMBOL in raw:
+            parts = raw.split(SCHEDULE_DSL_MULTIPLIER_SYMBOL)
+            if len(parts) != 2:
+                raise ValueError(f'Invalid schedule segment "{raw}": expected "<value> * <years>".')
+
+            val_raw = parts[0].strip()
+            if not is_float(val_raw):
+                raise ValueError(f'Invalid schedule segment "{raw}": "{val_raw}" is not a float.')
+            value = float(val_raw)
+            if value < 0:
+                raise ValueError(f'Invalid schedule segment "{raw}": {val_raw} is negative.')
+
+            years_raw = parts[1].strip()
+            if not is_int(years_raw):
+                raise ValueError(f'Invalid schedule segment "{raw}": "{years_raw}" is not an int.')
+
+            years = int(years_raw)
+            if years < 0:
+                raise ValueError(f'Invalid schedule segment "{raw}": year count must be non-negative.')
+            segments.append((value, years))
+        else:
+            if not is_float(raw):
+                raise ValueError(f'Invalid schedule segment "{raw}": "{raw}" is not a float.')
+
+            value = float(raw)
+            segments.append((value, None))
+
+    result: list[float] = []
+    terminal_value = 0.0
+
+    for idx, (value, years) in enumerate(segments):
+        is_last = idx == len(segments) - 1
+        if years is not None:
+            result.extend([value] * years)
+            terminal_value = value
+        else:
+            if is_last:
+                terminal_value = value
+            else:
+                result.append(value)
+                terminal_value = value
+
+    remaining = total_years - len(result)
+    if remaining > 0:
+        result.extend([terminal_value] * remaining)
+
+    if len(result) > total_years:
+        if not allow_schedule_length_to_exceed_total_years:
+            raise ValueError(
+                f'Invalid schedule: Schedule expands to {len(result)} years '
+                f'which exceeds total_years={total_years}.'
+            )
+        else:
+            pre_truncation_result = copy.copy(result)
+            result = result[:total_years]
+            _log.warning(
+                f'Schedule expands to {len(pre_truncation_result)} years, which exceeds total_years={total_years}. '
+                f'Schedule has been truncated to {total_years} years ({result}; from {pre_truncation_result}).'
+            )
+
+    return result