docs: adding docs for mga feature

[ParticularlyPythonicBS]

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for Modeling to Generate Alternatives (MGA), including configuration options, parameters, TOML examples, parallel execution, outputs, and usage notes.
  • Added an "mga" entry to the docs index for navigation.
  • Updated cross-references to point to the new MGA documentation page.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Documentation updates add a new MGA page, insert it into the docs index, and replace two inline descriptions with cross-references to the new MGA documentation.

Changes

Cohort / File(s)	Summary
Documentation Index and Navigation docs/source/index.rst	Adds a new mga entry to the toctree to include the MGA documentation in site navigation.
New MGA Documentation docs/source/mga.rst	Adds comprehensive MGA documentation covering Standard MGA and Single-Vector MGA (SVMGA), configuration (TOML) examples, parameters, iterative workflow, relaxation epsilon, supported axes/weighting, parallel execution options, solver options, outputs, naming conventions, and relevant SQL examples.
Updated Documentation References docs/source/computational_implementation.rst	Replaces two temoa.extensions bullet descriptions with cross-references to the new mga documentation page.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

docs

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding documentation for the MGA (Modeling to Generate Alternatives) feature, which aligns with all file modifications in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🤖 Fix all issues with AI agents

In `@docs/source/mga.rst`:
- Around line 87-90: Expand the "Outputs" section to include which database
tables store MGA results (mention the output database and specific tables such
as the scenarios table, solutions/iterations table, and any metrics table),
describe how to compare/analyze iterations (query pattern for scenario name
suffixes like "my_scenario-0", "my_scenario-1" and recommended SQL filters/joins
to compare objective values and decision variables across iterations), and list
MGA-specific output columns/metrics to expect (e.g., iteration index, objective
value(s), decision variable snapshots, distance/diversity metrics, and
feasibility flags) so users can find and interpret MGA outputs after a run
completes; reference the existing naming convention example ("my_scenario-0")
when showing query examples and where to look for iteration metadata.
- Line 35: Remove the implementation-file reference by editing the
docs/source/mga.rst line that reads "see ``MgaAxis`` in ``mga_constants.py``":
rephrase to present the user-facing option only (e.g., "Supported values:
MgaAxis = {list the valid values here}" or "See the API reference for MgaAxis"),
or link to the public API docs for MgaAxis instead of mentioning the internal
file name; ensure the term "axis" and symbol "MgaAxis" remain for
discoverability but omit "mga_constants.py".
- Around line 67-69: The descriptions for capacity_labels, emissions_labels, and
activity_labels lack info on how label matching is performed; update each bullet
to state the matching rules (e.g., matching is exact and case-sensitive against
the model's technology/emission identifier strings, not partial or regex
matches) and give a short example of a correct label; reference the symbols
capacity_labels, emissions_labels, and activity_labels when making the
clarification so users know to supply exact identifiers.
- Around line 40-41: Update the documentation for the "weighting" option to
explicitly state that HULL_EXPANSION is the only implemented weighting algorithm
today: modify the description around the weighting enum/name (reference symbol:
HULL_EXPANSION and the parameter "weighting") to read something like "Currently,
only HULL_EXPANSION is supported" or equivalent so users know no other weighting
algorithms are available yet.
- Around line 74-86: Update the docs text in the MGA parallelization section to
(1) explicitly state that parallel execution via num_workers is supported only
by "Standard MGA" and that "SVMGA" runs sequentially and does not honor
num_workers, (2) clarify that num_workers is a top-level/global MGA setting in
the MGA_solver_options.toml (not a solver-specific key) and therefore applies
regardless of which solver block (e.g., [gurobi]) is present, and (3) add a
short recommendation for choosing num_workers (e.g., usually set to available
CPU cores minus one to leave room for the main process and any solver Threads).

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/source/mga.rst`:
- Line 6: Split the long introductory sentence in docs/source/mga.rst into two
sentences to improve readability: keep the first sentence introducing the two
MGA extensions (standard iterative MGA and Single-Vector MGA (SVMGA)) and create
a second sentence describing their shared purpose of exploring the
"near-optimal" solution space and identifying alternative energy system
configurations (e.g., similar total costs but different characteristics like
higher utilization of a specific technology or lower emissions).
- Around line 89-91: Clarify the two levels of parallelism in the tip by
explicitly describing MGA-level parallelism (parallel solves controlled by
num_workers) versus solver-level parallelism (threads per solve controlled by
Threads), and update the wording in the paragraph that currently mentions
num_workers and Threads so it states that total threads = num_workers * Threads
and gives a short example (e.g., num_workers=4 and Threads=8 => 32 threads) plus
a note to reduce Threads if each solver is CPU-heavy; refer to the existing
symbols num_workers and Threads and the solver blocks when making the change.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Consider splitting the long introductory sentence for improved readability.

Line 6 contains a complex sentence that introduces both MGA methods and their purpose. While grammatically correct, splitting it into two sentences would improve readability.

📝 Suggested improvement

-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): the standard iterative MGA and the Single-Vector MGA (SVMGA). Both methods explore the "near-optimal" solution space to help users identify alternative energy system configurations. These alternatives have similar total costs but different characteristics (e.g., higher utilization of a specific technology or lower emissions).

🤖 Prompt for AI Agents

In `@docs/source/mga.rst` at line 6, Split the long introductory sentence in
docs/source/mga.rst into two sentences to improve readability: keep the first
sentence introducing the two MGA extensions (standard iterative MGA and
Single-Vector MGA (SVMGA)) and create a second sentence describing their shared
purpose of exploring the "near-optimal" solution space and identifying
alternative energy system configurations (e.g., similar total costs but
different characteristics like higher utilization of a specific technology or
lower emissions).

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Consider clarifying the two levels of parallelism in the tip.

The tip correctly calculates total threads as num_workers * Threads, but could be clearer about the distinction between MGA-level parallelism (multiple optimization problems solved in parallel) and solver-level parallelism (threads per individual solve).

📝 Suggested enhancement

 .. 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. Note that ``num_workers`` controls how many MGA iterations run in parallel, while ``Threads`` controls parallelism within each individual solver instance. The total thread count will be ``num_workers * Threads``, so adjust both settings to match your available CPU resources.

🤖 Prompt for AI Agents

In `@docs/source/mga.rst` around lines 89 - 91, Clarify the two levels of
parallelism in the tip by explicitly describing MGA-level parallelism (parallel
solves controlled by num_workers) versus solver-level parallelism (threads per
solve controlled by Threads), and update the wording in the paragraph that
currently mentions num_workers and Threads so it states that total threads =
num_workers * Threads and gives a short example (e.g., num_workers=4 and
Threads=8 => 32 threads) plus a note to reduce Threads if each solver is
CPU-heavy; refer to the existing symbols num_workers and Threads and the solver
blocks when making the change.