diff --git a/docs/source/computational_implementation.rst b/docs/source/computational_implementation.rst index 3893abf5..24aef4ff 100644 --- a/docs/source/computational_implementation.rst +++ b/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) diff --git a/docs/source/index.rst b/docs/source/index.rst index fc84d742..63c3f8f7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,3 +8,4 @@ Temoa Project Documentation myopic unit_checking stochastics + mga diff --git a/docs/source/mga.rst b/docs/source/mga.rst new file mode 100644 index 00000000..d8877024 --- /dev/null +++ b/docs/source/mga.rst @@ -0,0 +1,151 @@ +.. _mga: + +Modeling to Generate Alternatives (MGA) +======================================= + +Temoa provides two extensions for Modeling to Generate Alternatives (MGA): the standard iterative MGA and the Single-Vector MGA (SVMGA). Both methods are designed to explore the "near-optimal" solution space, helping users identify alternative energy system configurations that have similar total costs but different characteristics (e.g., higher utilization of a specific technology or lower emissions). + +Standard MGA +------------ + +The standard MGA extension implements an iterative algorithm to explore the boundaries of the near-optimal solution space. It works by relaxing the total system cost by a user-specified percentage (epsilon) and then iteratively optimizing along different axes to find extreme points. + +Configuration +~~~~~~~~~~~~~ + +To enable standard MGA, 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 optimal cost. Second, it adds a cost relaxation constraint and optimizes a new objective function defined by the user to "push" the model in a specific direction. + +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 standard MGA. +* **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. + +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: ``-``. + +* **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';