docs: adding docs for mga feature

docs/source/computational_implementation.rst

@@ -464,11 +464,11 @@ The Temoa model code is organized into clear, purpose-driven packages:
 
 * ``temoa.extensions`` - Optional extensions for advanced analysis
 
-  * ``modeling_to_generate_alternatives`` - MGA analysis for exploring near-optimal solutions ([!] untested in v4.0)
+  * ``modeling_to_generate_alternatives`` - :doc:`mga` (MGA analysis for exploring near-optimal solutions)
   * ``method_of_morris`` - Sensitivity analysis ([!] untested in v4.0)
   * ``monte_carlo`` - :doc:`monte_carlo` (Uncertainty quantification)
   * ``myopic`` - :doc:`myopic` (Sequential decision making with limited foresight)
-  * ``single_vector_mga`` - Focused MGA on specific variables ([!] untested in v4.0)
+  * ``single_vector_mga`` - :doc:`mga` (Focused MGA on specific variables)
   * ``stochastics`` - :doc:`stochastics` (Stochastic programming capabilities)
 
 * ``temoa._internal`` - Internal utilities (not part of public API)

docs/source/index.rst

@@ -8,3 +8,4 @@ Temoa Project Documentation
    myopic
    unit_checking
    stochastics
+   mga

docs/source/mga.rst

@@ -0,0 +1,187 @@
+.. _mga:
+
+Modeling to Generate Alternatives (MGA)
+=======================================
+
+Temoa provides two extensions for Modeling to Generate Alternatives (MGA), an
+algorithm to explore the near-optimal solution space: hull expansion and
+single-vector MGA. Both are described in more detail below. 
+
+Hull Expansion
+--------------
+
+Hull expansion creates the convex hull containing all near-optimal solutions
+bound by the extreme points along a particular solution axis and then samples
+the continuum of solutions. The size of the convex hull is determined by the
+degree of cost relaxation (``cost_epsilon``). The method is described in
+`Pedersen et al. (2021) <https://www.sciencedirect.com/science/article/pii/S0360544221015425>`_
+
+Configuration
+~~~~~~~~~~~~~
+
+To enable hull expansion, set the ``scenario_mode`` to ``"mga"`` in your
+configuration TOML file and provide an ``[MGA]`` section:
+
+.. code-block:: toml
+
+   scenario_mode = "mga"
+
+   [MGA]
+   cost_epsilon = 0.05        # Relax cost by 5%
+   iteration_limit = 20       # Maximum number of MGA iterations
+   time_limit_hrs = 12        # Stop after 12 hours
+   axis = "TECH_CATEGORY_ACTIVITY"
+   weighting = "HULL_EXPANSION"
+
+Options
+^^^^^^^
+
+* **cost_epsilon**: The fraction by which the optimal cost is allowed to increase
+  (e.g., ``0.05`` for 5%).
+* **iteration_limit**: The maximum number of alternative solutions to generate.
+* **time_limit_hrs**: The maximum wall-clock time for the entire MGA run.
+* **axis**: The dimension along which to optimize. Supported values:
+    * ``TECH_CAPACITY``
+    * ``TECH_CATEGORY_CAPACITY``
+    * ``TECH_CATEGORY_ACTIVITY`` (Default)
+    * ``EMISSION_ACTIVITY``
+* **weighting**: The algorithm used to select the next optimization vector.
+  Currently, only ``HULL_EXPANSION`` is supported.
+
+Single-Vector MGA (SVMGA)
+-------------------------
+
+Single-Vector MGA is a simplified, two-stage process. First, it solves the base
+model to find the minimum cost. Second, it adds a cost relaxation constraint and
+creates a new objective function that minimizes user-specified quantities, such
+as technology-specific installed capacity or total carbon dioxide emissions.
+
+
+Configuration
+~~~~~~~~~~~~~
+
+To enable SVMGA, set the ``scenario_mode`` to ``"svmga"`` and provide an
+``[SVMGA]`` section:
+
+.. code-block:: toml
+
+   scenario_mode = "svmga"
+
+   [SVMGA]
+   cost_epsilon = 0.05
+   capacity_labels = ["solar_pv", "wind_onshore"]
+   # emissions_labels = ["CO2"]
+   # activity_labels = ["coal_power"]
+
+Options
+^^^^^^^
+
+* **cost_epsilon**: Same as in hull expansion.
+* **capacity_labels**: A list of technology names whose total capacity should be
+  maximized in the second stage. Matching is **exact and case-sensitive** against
+  the identifiers in the ``tech_all`` set. Example: ``["solar_pv", "wind_onshore"]``.
+* **emissions_labels**: A list of emission commodities whose total emissions
+  should be minimized. Matching is **exact and case-sensitive** against
+  identifiers in the ``commodity_emissions`` set. Example: ``["CO2"]``.
+* **activity_labels**: A list of technology names whose total activity
+  (energy flow out) should be maximized. Matching is **exact and case-sensitive**.
+  Example: ``["coal_power"]``.
+
+Note: SVMGA will construct an unweighted sum of all variables matching these
+labels as the new objective function. Be careful not to mix different units. In
+addition, note that the MGA objective function is set to minimize regardless of
+the label choice.
+
+Parallel Execution and Solver Options
+-------------------------------------
+
+Standard MGA supports parallel execution of iterative solves to maximize
+performance. **Note: SVMGA executes sequentially and does not utilize parallel
+workers.**
+
+The number of worker processes and solver-specific settings are defined in a
+``MGA_solver_options.toml`` file. By default, Temoa looks for this file in the
+same directory as your main configuration file.
+
+.. code-block:: toml
+
+   # Global setting at the top level of the file
+   num_workers = 4
+
+   [gurobi]
+   Method = 2
+   Threads = 4  # Threads per solver instance
+   BarConvTol = 0.01
+
+.. tip::
+   When choosing ``num_workers``, a good rule of thumb is to set it to the
+   number of available CPU cores minus one. This leaves room for the main
+   orchestration process and ensures that the system remains responsive. Also,
+   be mindful of the ``Threads`` setting within solver blocks, as the total
+   thread count will be ``num_workers * Threads``.
+
+Outputs
+-------
+
+MGA results are stored in the same output database specified in your
+configuration. Each iteration is saved as a unique scenario to allow for easy
+comparison and analysis.
+
+Scenario Naming Convention
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each run is saved under a unique scenario name in the output tables, following
+the format: ``<base_scenario>-<iteration_index>``.
+
+*   **Iteration 0**: The original baseline solve (optimal solution).
+*   **Iterations 1-N**: The alternative solutions generated by the MGA algorithm.
+
+For example, if your base scenario is ``utopia_mga``, the results for the base
+case will be found under scenario ``utopia_mga-0``, and the first alternative
+will be under ``utopia_mga-1``.
+
+Key Database Tables
+~~~~~~~~~~~~~~~~~~~
+
+The results are spread across several tables, consistent with standard Temoa runs:
+
+*   **output_objective**: Stores the total system cost and MGA optimization objective for each iteration.
+*   **output_net_capacity**: Stores the installed capacity for each technology, period, and iteration.
+*   **output_flow_out** / **output_flow_out_summary**: Stores energy flows between technologies.
+*   **output_emission**: Stores emission results per commodity and technology.
+*   **output_cost**: Stores detailed cost breakdowns (investment, fixed, variable).
+
+Comparing Iterations
+~~~~~~~~~~~~~~~~~~~~
+
+You can use SQL queries to compare results across different MGA iterations.
+
+**Comparing Total System Cost:**
+
+.. code-block:: sql
+
+   SELECT scenario, total_system_cost
+   FROM output_objective
+   WHERE scenario LIKE 'utopia_mga-%'
+   ORDER BY scenario;
+
+**Comparing Capacity for a Specific Technology:**
+
+.. code-block:: sql
+
+   SELECT scenario, tech, period, capacity, units
+   FROM output_net_capacity
+   WHERE scenario LIKE 'utopia_mga-%'
+     AND tech = 'solar_pv'
+   ORDER BY scenario, period;
+
+**Analyzing Diversity (SQL Join Example):**
+
+.. code-block:: sql
+
+   SELECT a.scenario, a.tech, a.capacity as cap_a, b.capacity as cap_b, (a.capacity - b.capacity) as diff
+   FROM output_net_capacity a
+   JOIN output_net_capacity b ON a.tech = b.tech AND a.period = b.period
+   WHERE a.scenario = 'utopia_mga-1'
+     AND b.scenario = 'utopia_mga-0'
+     AND a.tech = 'solar_pv';