Skip to content

docs: adding docs for mga feature #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ParticularlyPythonicBS wants to merge 1 commit into
base: unstable
Choose a base branch
from
+154 −2
Open

docs: adding docs for mga feature #255

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/source/computational_implementation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
1 change: 1 addition & 0 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,4 @@ Temoa Project Documentation
myopic
unit_checking
stochastics
mga
151 changes: 151 additions & 0 deletions docs/source/mga.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: ``<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';