From b2f1501d14e17ef632f7264e889579fa5f655345 Mon Sep 17 00:00:00 2001 From: ParticularlyPythonicBS Date: Mon, 19 Jan 2026 09:11:50 -0500 Subject: [PATCH 1/2] docs: adding docs for mga feature --- docs/source/computational_implementation.rst | 4 +- docs/source/index.rst | 1 + docs/source/mga.rst | 151 +++++++++++++++++++ 3 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 docs/source/mga.rst 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'; From c464790596f0ac7713a22525989984c3948c4723 Mon Sep 17 00:00:00 2001 From: Joe DeCarolis Date: Fri, 6 Feb 2026 13:10:06 -0500 Subject: [PATCH 2/2] Update and clarify MGA documentation --- docs/source/mga.rst | 78 +++++++++++++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 21 deletions(-) diff --git a/docs/source/mga.rst b/docs/source/mga.rst index d8877024..5ad0a8c5 100644 --- a/docs/source/mga.rst +++ b/docs/source/mga.rst @@ -3,17 +3,24 @@ 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). +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. -Standard MGA ------------- +Hull Expansion +-------------- -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. +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) `_ Configuration ~~~~~~~~~~~~~ -To enable standard MGA, set the ``scenario_mode`` to ``"mga"`` in your configuration TOML file and provide an ``[MGA]`` section: +To enable hull expansion, set the ``scenario_mode`` to ``"mga"`` in your +configuration TOML file and provide an ``[MGA]`` section: .. code-block:: toml @@ -29,7 +36,8 @@ To enable standard MGA, set the ``scenario_mode`` to ``"mga"`` in your configura Options ^^^^^^^ -* **cost_epsilon**: The fraction by which the optimal cost is allowed to increase (e.g., ``0.05`` for 5%). +* **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: @@ -37,17 +45,23 @@ Options * ``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. +* **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. +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: +To enable SVMGA, set the ``scenario_mode`` to ``"svmga"`` and provide an +``[SVMGA]`` section: .. code-block:: toml @@ -62,19 +76,32 @@ To enable SVMGA, set the ``scenario_mode`` to ``"svmga"`` and provide an ``[SVMG 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. +* **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.** +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. +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 @@ -87,22 +114,31 @@ The number of worker processes and solver-specific settings are defined in a ``M 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``. + 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. +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: ``-``. +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``. +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 ~~~~~~~~~~~~~~~~~~~