docs: adding docs for mga feature

[ParticularlyPythonicBS]

Summary by CodeRabbit

• Documentation
  • Added a comprehensive MGA guide covering Hull Expansion and Single-Vector MGA, configuration options, parallel execution, outputs, and analysis examples.
  • Added an "mga" entry to the documentation index for easier navigation.
  • Updated cross-references to point to the new MGA documentation page for clearer linking.

[coderabbitai]

Walkthrough

Adds a new MGA documentation page, inserts it into the docs toctree, and replaces two temoa.extensions descriptions with cross-references to the new MGA page. Changes are documentation-only; no code, APIs, or runtime behavior altered.

Changes

Cohort / File(s)	Summary
Documentation Index and Navigation docs/source/index.rst	Adds mga to the toctree to include the new MGA documentation in site navigation.
New MGA Documentation docs/source/mga.rst	Adds comprehensive MGA documentation covering Hull Expansion and Single-Vector MGA (SVMGA), TOML configuration examples and options, two-stage SVMGA workflow, parallel execution and solver option notes, output conventions, scenario naming, and SQL-based comparison examples.
Updated Computational Implementation docs/source/computational_implementation.rst	Replaces inline modeling_to_generate_alternatives and single_vector_mga descriptions with cross-references to the new mga documentation page.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 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 accurately describes the main change: adding documentation for the MGA (Modeling to Generate Alternatives) feature across multiple documentation files.
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.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/mga_docs

---

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]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/source/mga.rst`:
- Around line 10-11: The RST heading "Hull Expansion" has an underline that's
shorter than the title; update the underline beneath the "Hull Expansion"
heading so it is at least as long as the title (e.g., extend the string of "-"
characters to match or exceed the length of "Hull Expansion") to satisfy Sphinx
heading rules and avoid warnings.