Update mapping tables in documentation #250
Conversation
WalkthroughDocumentation restructures two files to align model comparison and mathematical notation. The db_model_comparison.rst shifts from descriptive to code-centric representation with updated identifiers and flag-based qualifiers. The mathematical_formulation.rst removes notation definitions and adds Sets introduction explaining relationships between mathematical notation and code/database names. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Fix all issues with AI agents
In @docs/source/db_model_comparison.rst:
- Line 26: The Notes column contains a "NEED HELP" placeholder for the
time_season_sequential entry; replace it with a short, accurate description by
locating where time_season_sequential is defined/used (search for the symbol
time_season_sequential in the codebase and inspect related functions
time_season_to_sequential and ordered_season_sequential), summarize its purpose
and behavior (input expected, transformation it performs, any ordering or season
handling details), and update the RST line to include that description instead
of "NEED HELP".
- Line 79: Replace the misspelled word "defing" with "defining" in the sentence
fragment "necessary, defing these operators as a set allows modelers to express
constraints" within the docs/source/db_model_comparison.rst file so the text
reads "necessary, defining these operators as a set allows modelers to express
constraints".
- Line 12: Fix the typo "dtabase" → "database" in the documentation sentence
that reads "elements, the first element refers to the name of the dtabase table
and the second" in db_model_comparison.rst; update that instance to "database"
so the sentence correctly reads "elements, the first element refers to the name
of the database table and the second".
- Line 83: Update the table header string so it matches other tables by
replacing "Model Element" with "Model Code" in the :header: line; specifically
edit the line currently reading :header: "Set", "Database Table", "Model
Element", "Notes" and change it to :header: "Set", "Database Table", "Model
Code", "Notes" so the header is consistent.
- Line 66: Replace the table header entry that currently reads :header: "Set",
"Database Table", "Model Element", "Notes" so it matches other tables by using
"Model Code" instead of "Model Element"; locate the :header: line in
docs/source/db_model_comparison.rst and change the third quoted header token to
"Model Code" to ensure consistency.
- Line 31: Update the table header string that currently reads ':header: "Set",
"Database Table", "Model Element", "Notes"' to use "Model Code" instead of
"Model Element"; locate the header declaration (the :header: line) and replace
"Model Element" with "Model Code" so the table header matches the other tables.
- Line 72: Update the flags list literal ":code:`commodity, flag = w, wa , wp`"
to remove the stray space before "wa" so it reads ":code:`commodity, flag = w,
wa, wp`"; edit the RST line containing that string (the flags list) to correct
the spacing and ensure consistent comma separation.
- Line 43: Update the table header to use "Model Code" instead of "Model
Element": locate the table header declaration that currently reads :header:
"Set", "Database Table", "Model Element", "Notes" and change the third header
string to "Model Code" so it becomes :header: "Set", "Database Table", "Model
Code", "Notes".
- Line 36: Update the documentation entry for the set regional_global_indices:
replace the placeholder "NEED HELP - is this set required? It appears to be
deprecated?" with the precise description: "set of all regions and regional
groups (regions and groups can be used interchangeably in constraints)". Ensure
the new text is used wherever regional_global_indices is documented so it
clearly states it is required and describes its purpose in 11+ constraints and
parameters for capacity, activity, emissions, and share limits.
- Line 56: Replace the incorrect code identifier `tech_unlim_cap` with the
actual implementation name `tech_uncap` in the mathematical formulation
documentation: locate every occurrence of `:code:\`tech_unlim_cap\`` in the
mathematical_formulation.rst content and change it to `:code:\`tech_uncap\`` so
the docs match the Python implementation (the codebase uses `tech_uncap` in
core/model.py, components/capacity.py, components/reserves.py, etc.).
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
docs/source/db_model_comparison.rstdocs/source/mathematical_formulation.rst
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: setup and test (macos-latest, 3.13)
- GitHub Check: setup and test (windows-latest, 3.13)
- GitHub Check: setup and test (macos-latest, 3.12)
- GitHub Check: setup and test (windows-latest, 3.12)
🔇 Additional comments (2)
docs/source/mathematical_formulation.rst (1)
127-131: LGTM! Helpful introductory context added.This new paragraph effectively sets up the reader for the detailed set definitions that follow and aligns well with the updated mapping tables in
db_model_comparison.rst.docs/source/db_model_comparison.rst (1)
89-257: Parameter mapping tables look good overall.The parameter mapping tables are well-structured and provide clear correspondences between database tables, model elements, and their purposes. The consistent use of "Model Element" in these table headers (vs "Model Code" in the sets tables) appears to be an intentional distinction.
| the model's time horizon for optimization. | ||
|
|
||
| Note: In instances where the "Database Table" column contains two comma-separated | ||
| elements, the first element refers to the name of the dtabase table and the second |
There was a problem hiding this comment.
Fix typo: "dtabase" → "database".
📝 Proposed fix
-elements, the first element refers to the name of the dtabase table and the second
+elements, the first element refers to the name of the database table and the second📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| elements, the first element refers to the name of the dtabase table and the second | |
| elements, the first element refers to the name of the database table and the second |
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 12, Fix the typo "dtabase" →
"database" in the documentation sentence that reads "elements, the first element
refers to the name of the dtabase table and the second" in
db_model_comparison.rst; update that instance to "database" so the sentence
correctly reads "elements, the first element refers to the name of the database
table and the second".
| ":math:`\text{D}`", ":code:`time_of_day`", ":code:`time_of_day`", "intraday time divisions" | ||
| ":math:`\text{S}`", ":code:`season_label`", ":code:`time_season`", "intra-annual divisions, e.g., different seasons or different representative days" | ||
| "", ":code:`time_season`", ":code:`time_season`", "ordered tuple of seasons by time period" | ||
| "", ":code:`time_season_sequential`", ":code:`time_season_to_sequential, ordered_season_sequential`", "NEED HELP" |
There was a problem hiding this comment.
Complete the "NEED HELP" placeholder before release.
The entry for time_season_sequential needs a proper description in the Notes column.
Would you like me to help research the purpose of this set by examining the codebase?
#!/bin/bash
# Search for usage of time_season_sequential in the codebase
rg -nC3 'time_season_sequential' --type=py🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 26, The Notes column contains a
"NEED HELP" placeholder for the time_season_sequential entry; replace it with a
short, accurate description by locating where time_season_sequential is
defined/used (search for the symbol time_season_sequential in the codebase and
inspect related functions time_season_to_sequential and
ordered_season_sequential), summarize its purpose and behavior (input expected,
transformation it performs, any ordering or season handling details), and update
the RST line to include that description instead of "NEED HELP".
| The sets in the table below define Temoa's representation of regions. | ||
|
|
||
| .. csv-table:: | ||
| :header: "Set", "Database Table", "Model Element", "Notes" |
There was a problem hiding this comment.
Update header to match other tables.
The header should be "Model Code" instead of "Model Element" for consistency with the other tables in this file.
📝 Proposed fix
- :header: "Set", "Database Table", "Model Element", "Notes"
+ :header: "Set", "Database Table", "Model Code", "Notes"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| :header: "Set", "Database Table", "Model Element", "Notes" | |
| :header: "Set", "Database Table", "Model Code", "Notes" |
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 31, Update the table header
string that currently reads ':header: "Set", "Database Table", "Model Element",
"Notes"' to use "Model Code" instead of "Model Element"; locate the header
declaration (the :header: line) and replace "Model Element" with "Model Code" so
the table header matches the other tables.
| "", "region", "regional_global_indices", "regional groups" | ||
| ":math:`\text{R}`", ":code:`region`", ":code:`regions`", "distinct geographical regions; direct mapping" | ||
| "", ":code:`region`", ":code:`regional_indices`", "set of all the possible combinations of interregional exchanges plus original region indices" | ||
| "", ":code:`region`", ":code:`regional_global_indices`", "NEED HELP - is this set required? It appears to be deprecated?" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for all occurrences of regional_global_indices
echo "=== Searching for regional_global_indices usage ==="
rg -n 'regional_global_indices' --type=py -C 2
echo -e "\n=== Checking for deprecation mentions ==="
rg -n 'regional_global_indices' -i deprecated
echo -e "\n=== Searching in all file types ==="
rg -n 'regional_global_indices' -C 1
echo -e "\n=== Checking documentation mentions ==="
rg -n 'regional_global_indices' --type=rst --type=md -C 2Repository: TemoaProject/temoa
Length of output: 13045
Update documentation description for regional_global_indices.
The set is not deprecated and is actively required. It represents the combined set of regions and regional groups, used in 11+ constraints and parameters for capacity, activity, emissions, and share limits. Replace the placeholder text with: "set of all regions and regional groups (regions and groups can be used interchangeably in constraints)"
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 36, Update the documentation
entry for the set regional_global_indices: replace the placeholder "NEED HELP -
is this set required? It appears to be deprecated?" with the precise
description: "set of all regions and regional groups (regions and groups can be
used interchangeably in constraints)". Ensure the new text is used wherever
regional_global_indices is documented so it clearly states it is required and
describes its purpose in 11+ constraints and parameters for capacity, activity,
emissions, and share limits.
| number of technology subsets. | ||
|
|
||
| .. csv-table:: | ||
| :header: "Set", "Database Table", "Model Element", "Notes" |
There was a problem hiding this comment.
Update header to match other tables.
The header should be "Model Code" instead of "Model Element" for consistency.
📝 Proposed fix
- :header: "Set", "Database Table", "Model Element", "Notes"
+ :header: "Set", "Database Table", "Model Code", "Notes"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| :header: "Set", "Database Table", "Model Element", "Notes" | |
| :header: "Set", "Database Table", "Model Code", "Notes" |
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 43, Update the table header to
use "Model Code" instead of "Model Element": locate the table header declaration
that currently reads :header: "Set", "Database Table", "Model Element", "Notes"
and change the third header string to "Model Code" so it becomes :header: "Set",
"Database Table", "Model Code", "Notes".
| ":math:`\text{T}^f`", ":code:`technology, flex = 1`", ":code:`tech_flex`", "technologies producing excess commodity flows, (:math:`{T}^f \subset T`)" | ||
| ":math:`\text{T}^x`", ":code:`technology, exchange = 1`", ":code:`tech_exchange`", "technologies used for interregional commodity flows, (:math:`{T}^x \subset T`)" | ||
| ":math:`\text{T}^{ret}`", ":code:`technology, retire = 1`", ":code:`tech_retirement`", "technologies allowed to retire before end of life, (:math:`{T}^{ret} \subset (T - T^{u})`)" | ||
| ":math:`\text{T}^u`", ":code:`technology, unlim_cap = 1`", ":code:`tech_uncap`", "technologies that have no bound on capacity, (:math:`{T}^u \subset (T - T^{res})`)" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for both naming variants in the codebase
echo "=== Searching for tech_uncap ==="
rg -nC2 '\btech_uncap\b' --type=py
echo "=== Searching for tech_unlim_cap ==="
rg -nC2 '\btech_unlim_cap\b' --type=pyRepository: TemoaProject/temoa
Length of output: 9774
🏁 Script executed:
#!/bin/bash
# Check both documentation files for the naming variants
echo "=== Checking db_model_comparison.rst around line 56 ==="
sed -n '50,60p' docs/source/db_model_comparison.rst
echo ""
echo "=== Checking mathematical_formulation.rst around line 162 ==="
sed -n '155,170p' docs/source/mathematical_formulation.rstRepository: TemoaProject/temoa
Length of output: 4007
Update mathematical_formulation.rst to match actual code name.
The Python implementation uses tech_uncap (confirmed throughout the codebase in core/model.py, components/capacity.py, components/reserves.py, and elsewhere). However, mathematical_formulation.rst at line 162 documents this set as :code:tech_unlim_cap, while `db_model_comparison.rst` at line 56 correctly uses `:code:`tech_uncap. Update mathematical_formulation.rst to use tech_uncap for consistency with the actual implementation.
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 56, Replace the incorrect code
identifier `tech_unlim_cap` with the actual implementation name `tech_uncap` in
the mathematical formulation documentation: locate every occurrence of
`:code:\`tech_unlim_cap\`` in the mathematical_formulation.rst content and
change it to `:code:\`tech_uncap\`` so the docs match the Python implementation
(the codebase uses `tech_uncap` in core/model.py, components/capacity.py,
components/reserves.py, etc.).
| technologies. | ||
|
|
||
| .. csv-table:: | ||
| :header: "Set", "Database Table", "Model Element", "Notes" |
There was a problem hiding this comment.
Update header to match other tables.
The header should be "Model Code" instead of "Model Element" for consistency.
📝 Proposed fix
- :header: "Set", "Database Table", "Model Element", "Notes"
+ :header: "Set", "Database Table", "Model Code", "Notes"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| :header: "Set", "Database Table", "Model Element", "Notes" | |
| :header: "Set", "Database Table", "Model Code", "Notes" |
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 66, Replace the table header
entry that currently reads :header: "Set", "Database Table", "Model Element",
"Notes" so it matches other tables by using "Model Code" instead of "Model
Element"; locate the :header: line in docs/source/db_model_comparison.rst and
change the third quoted header token to "Model Code" to ensure consistency.
| ":math:`\text{C}^d`", ":code:`commodity, flag = d`", ":code:`commodity_demand`", "end-use demand commodities, representing the final consumer demands" | ||
| ":math:`\text{C}^e`", ":code:`commodity, flag = e`", ":code:`commodity_emissions`", "emission commodities (e.g. :math:`\text{CO}_\text{2}` :math:`\text{NO}_\text{x}`); filtered by flag" | ||
| ":math:`\text{C}^p`", ":code:`commodity, flag = p`", ":code:`commodity_physical`", "physical energy commodities (e.g. electricity, coal, uranium, oil) produced and consumed across the energy system" | ||
| ":math:`\text{C}^w`", ":code:`commodity, flag = w, wa , wp`", ":code:`commodity_waste`", "production can be greater than consumption; can be physical, annual, or neither (not balanced)" |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Minor formatting: Remove extra space in flag list.
There's an extra space before "wa" in the flags list.
📝 Proposed fix
- ":math:`\text{C}^w`", ":code:`commodity, flag = w, wa , wp`", ":code:`commodity_waste`", "production can be greater than consumption; can be physical, annual, or neither (not balanced)"
+ ":math:`\text{C}^w`", ":code:`commodity, flag = w, wa, wp`", ":code:`commodity_waste`", "production can be greater than consumption; can be physical, annual, or neither (not balanced)"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ":math:`\text{C}^w`", ":code:`commodity, flag = w, wa , wp`", ":code:`commodity_waste`", "production can be greater than consumption; can be physical, annual, or neither (not balanced)" | |
| ":math:`\text{C}^w`", ":code:`commodity, flag = w, wa, wp`", ":code:`commodity_waste`", "production can be greater than consumption; can be physical, annual, or neither (not balanced)" |
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 72, Update the flags list
literal ":code:`commodity, flag = w, wa , wp`" to remove the stray space before
"wa" so it reads ":code:`commodity, flag = w, wa, wp`"; edit the RST line
containing that string (the flags list) to correct the spacing and ensure
consistent comma separation.
| Other Sets | ||
| ^^^^^^^^^^ | ||
| There is one additional set that defines operators (=, <, >). While not strictly | ||
| necessary, defing these operators as a set allows modelers to express constraints |
There was a problem hiding this comment.
Fix typo: "defing" → "defining".
📝 Proposed fix
-necessary, defing these operators as a set allows modelers to express constraints
+necessary, defining these operators as a set allows modelers to express constraints📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| necessary, defing these operators as a set allows modelers to express constraints | |
| necessary, defining these operators as a set allows modelers to express constraints |
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 79, Replace the misspelled word
"defing" with "defining" in the sentence fragment "necessary, defing these
operators as a set allows modelers to express constraints" within the
docs/source/db_model_comparison.rst file so the text reads "necessary, defining
these operators as a set allows modelers to express constraints".
| more efficiently. | ||
|
|
||
| .. csv-table:: | ||
| :header: "Set", "Database Table", "Model Element", "Notes" |
There was a problem hiding this comment.
Update header to match other tables.
The header should be "Model Code" instead of "Model Element" for consistency.
📝 Proposed fix
- :header: "Set", "Database Table", "Model Element", "Notes"
+ :header: "Set", "Database Table", "Model Code", "Notes"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| :header: "Set", "Database Table", "Model Element", "Notes" | |
| :header: "Set", "Database Table", "Model Code", "Notes" |
🤖 Prompt for AI Agents
In @docs/source/db_model_comparison.rst at line 83, Update the table header
string so it matches other tables by replacing "Model Element" with "Model Code"
in the :header: line; specifically edit the line currently reading :header:
"Set", "Database Table", "Model Element", "Notes" and change it to :header:
"Set", "Database Table", "Model Code", "Notes" so the header is consistent.
This PR updates the tables and descriptions associated with Temoa sets and parameters, which include the mapping between database tables and code elements.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.