Merge unstable into main: extension framework, extensions, and fixes

README.md

@@ -152,29 +152,56 @@ uv run temoa tutorial             # Create tutorial files
 You can use Temoa as a Python library:
 
 ```python
-import temoa
+from logging import getLogger
 from pathlib import Path
-from temoa import TemoaModel, TemoaConfig, TemoaMode
+from temoa._internal.temoa_sequencer import TemoaSequencer
+from temoa.core.config import TemoaConfig
+from temoa.core.modes import TemoaMode
+from temoa.cli import setup_logging
+from pyomo.environ import value, check_optimal_termination
 
-# Create configuration
+output_path = Path('output_files/my_run')
+output_path.mkdir(parents=True, exist_ok=True)
+
+setup_logging(output_path, debug=False, silent=False)
+
+logger = getLogger(__name__)
+
+#  ======================================================================
+#  Choose ONE of the following two options for configuring the model run:
+#  ======================================================================
+
+# OPTION 1: build the config in code
 config = TemoaConfig(
-    scenario='my_scenario',
+    scenario='zulu',
     scenario_mode=TemoaMode.PERFECT_FORESIGHT,
-    input_database=Path('path/to/input.db'),
-    output_database=Path('path/to/output.db'),
-    output_path=Path('path/to/output'),
+    time_sequencing='seasonal_timeslices',
+    input_database='tutorial_database.sqlite',
+    output_database='tutorial_database.sqlite',
     solver_name='appsi_highs',
+    output_path=output_path,
+    silent=False,
+)
+# OPTION 2: load the config from a file
+config = TemoaConfig.build_config(
+    config_file=Path('tutorial_config.toml'),
+    output_path=output_path,
+    silent=False,
 )
 
-# Build and solve model
-model = TemoaModel(config)
-result = model.run()  # Equivalent to: temoa run tutorial_config.toml
+ts = TemoaSequencer(config=config)
+ts.start()  # TemoaSequencer runs the model and handles results
+
+# Results are saved to your output_database but can also be accessed in code, here
+solved_instance = ts.pf_solved_instance  # solved Temoa instance with solution values
+solver_results = ts.pf_results  # information from the solver
 
-# Check if run was successful
-if result:
-    print('Model solved successfully!')
-else:
-    print('Model failed to solve')
+# Example code usage of the solved instance and solver results
+logger.info(f'Solver results: {solver_results["solver"]}')
+if check_optimal_termination(solver_results):
+    logger.info(f'Model solved! Objective value: {value(solved_instance.total_cost):.2f}')
+    built_capacity = value(solved_instance.v_new_capacity['utopia', 'E51', 2010])
+    logger.info(f'Built {built_capacity:.2f} GW of storage in 2010')
 ```
 
 ## Database Setup

docs/source/computational_implementation.rst

@@ -268,7 +268,7 @@ which determines the valid indices from other model components. This second meth
 when the indices of a constraint do not exactly align with the indices of the database
 table. For example, the database table :code:`ramp_up_hourly` is indexed by :code:`region`,
 :code:`tech` in the database but one of its inheriting constraints,
-:code:`ramp_up_day_constraint`, is indexed by :code:`region`, :code:`period`,
+:code:`ramp_up_constraint`, is indexed by :code:`region`, :code:`period`,
 :code:`season`, :code:`time_of_day`, :code:`tech`, :code:`vintage` in the model. In this case,
 an index function is needed to determine the valid indices for the constraint.
 
@@ -277,19 +277,19 @@ an index function is needed to determine the valid indices for the constraint.
    .. code-block:: python
       :linenos:
 
-      self.ramp_up_day_constraint_rpsdtv = Set(
-         dimen=6, initialize=operations.ramp_up_day_constraint_indices
+      self.ramp_up_constraint_rpsdtv = Set(
+         dimen=6, initialize=operations.ramp_up_constraint_indices
       )
-      self.ramp_up_day_constraint = Constraint(
-         self.ramp_up_day_constraint_rpsdtv, rule=operations.ramp_up_day_constraint
+      self.ramp_up_constraint = Constraint(
+         self.ramp_up_constraint_rpsdtv, rule=operations.ramp_up_constraint
       )
 
 .. topic:: in ``temoa/components/operations.py`` (return valid indices)
 
    .. code-block:: python
       :linenos:
 
-      def ramp_up_day_constraint_indices(
+      def ramp_up_constraint_indices(
          model: TemoaModel,
       ) -> set[tuple[Region, Period, Season, TimeOfDay, Technology, Vintage]]:
          indices = {
@@ -302,7 +302,7 @@ an index function is needed to determine the valid indices for the constraint.
 
          return indices
 
-With the sparse set (:code:`demand_constraint_rpc` or :code:`ramp_up_day_constraint_rpsdtv`)
+With the sparse set (:code:`demand_constraint_rpc` or :code:`ramp_up_constraint_rpsdtv`)
 created, we can now can use it in place of the sets specified in the non-sparse
 implementation.  Pyomo will now call the constraint implementation rule the
 minimum number of times.
@@ -320,6 +320,11 @@ dimensionality of 3, and (following the :ref:`naming scheme
 :code:`region`, the second an element of :code:`time_optimize`,
 and third a demand commodity.
 
+.. seealso::
+   The same component pattern (index set, parameter, and constraint declared in a
+   ``model.py`` and implemented in component modules) can be packaged as an
+   optional, self-contained add-on. See :ref:`extensions` for the extension
+   framework and a copy-from template.
 
 
 

docs/source/database_schema.mmd

@@ -275,33 +275,6 @@ limit_capacity_share {
    TEXT notes
    REAL share
 }
-limit_degrowth_capacity {
- TEXT operator PK
-   TEXT region PK
-   TEXT tech_or_group PK
-   TEXT notes
-   REAL rate
-   REAL seed
-   TEXT seed_units
-}
-limit_degrowth_new_capacity {
- TEXT operator PK
-   TEXT region PK
-   TEXT tech_or_group PK
-   TEXT notes
-   REAL rate
-   REAL seed
-   TEXT seed_units
-}
-limit_degrowth_new_capacity_delta {
- TEXT operator PK
-   TEXT region PK
-   TEXT tech_or_group PK
-   TEXT notes
-   REAL rate
-   REAL seed
-   TEXT seed_units
-}
 limit_emission {
  TEXT emis_comm PK
    TEXT operator PK
@@ -311,33 +284,6 @@ limit_emission {
    TEXT units
    REAL value
 }
-limit_growth_capacity {
- TEXT operator PK
-   TEXT region PK
-   TEXT tech_or_group PK
-   TEXT notes
-   REAL rate
-   REAL seed
-   TEXT seed_units
-}
-limit_growth_new_capacity {
- TEXT operator PK
-   TEXT region PK
-   TEXT tech_or_group PK
-   TEXT notes
-   REAL rate
-   REAL seed
-   TEXT seed_units
-}
-limit_growth_new_capacity_delta {
- TEXT operator PK
-   TEXT region PK
-   TEXT tech_or_group PK
-   TEXT notes
-   REAL rate
-   REAL seed
-   TEXT seed_units
-}
 limit_new_capacity {
  TEXT operator PK
    INTEGER period PK