Update mapping tables in documentation #250
Open
+121
−87
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
WalkthroughRewrote documentation to replace descriptive set/parameter names with code-style identifiers and flag qualifiers across mapping and mathematical docs; added/renamed numerous sets and parameters (time, region, tech, commodity, operator, limits, storage, construction/EoL) and updated cross-references to code/DB names. (≈34 words) Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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 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.
Suggested change
| :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.
| 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.
Suggested change
| :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".
| 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.
Suggested change
| :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.
| 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.
Suggested change
| :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.
ParticularlyPythonicBS
force-pushed
the
doc_mapping
branch
from
9204f31 to
3eb54b3
Compare
idelder
reviewed
Feb 2, 2026
docs/source/db_model_comparison.rst
Outdated
| ":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)" | ||
| ":math:`\text{C}^a`", ":code:`commodity, flag = a`", ":code:`commodity_annual`", "same as commodity physical but flows are only balanced over each period (:math:`\text{C}^a \subset \text{C}^p`)" | ||
| ":math:`\text{C}^l`", ":code:`commodity, flag = l`", ":code:`commodity_flex`", "commodities with flexible supply or demand (:math:`\text{C}^l \subset \text{C}^p`)" |
There was a problem hiding this comment.
"(disposable) commodities produced by a flex technology"
idelder
reviewed
Feb 2, 2026
| ":math:`\text{LA}_{r,p,t}`","limit_activity",":math:`\mathbb{R}^+_0`","Limit tech-specific activity by region and period" | ||
| ":math:`\text{LC}_{r,p,t}`","limit_capacity",":math:`\mathbb{R}^+_0`","Limit tech-specific capacity by period" | ||
| ":math:`\text{LNC}_{r,p,t}`","limit_new_capacity",":math:`\mathbb{R}^+_0`","Limit new capacity deployment by period" | ||
| ":math:`\text{LR}_{r,t}`","limit_resource",":math:`\mathbb{R}^+_0`","Limit resource production by tech across time periods" |
There was a problem hiding this comment.
"Cumulative activity limit across time periods (not supported in myopic)"
idelder
reviewed
Feb 2, 2026
| ":math:`\text{TISA}_{r,i,t}`","tech_output_split_annual",":math:`\mathbb{I}`","Average annual technology output fuel ratio" | ||
| ":math:`\text{TOSA}_{r,t,o}`","tech_output_split_annual",":math:`\mathbb{I}`","Average annual technology output fuel ratio" | ||
| ":math:`{}^*\text{LA}_{t,v}`","loan_annualize",":math:`\mathbb{R}^+_0`","Loan amortization by tech and vintage; based on :math:`DR_t`" | ||
| ":math:`{}^*\text{MPL}_{p,t,v}`","model_process_life",":math:`\mathbb{N}`","Smaller of remaining model horizon or process tech life" |
There was a problem hiding this comment.
I think I deprecated MPL when updating the objective function
idelder
reviewed
Feb 2, 2026
docs/source/db_model_comparison.rst
Outdated
| Commodity Sets | ||
| ^^^^^^^^^^^^^^ | ||
| ":math:`{}^*\text{T}`", ":code:`technology`", ":code:`tech_all`", "all technologies to be modeled; (:math:`{T}^r \cup {T}^p`)" | ||
| ":math:`\text{T}^p`", ":code:`technology`", ":code:`tech_production`", "techs producing intermediate commodities, like electricity" |
idelder
reviewed
Feb 2, 2026
docs/source/db_model_comparison.rst
Outdated
| ":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)" |
ParticularlyPythonicBS
force-pushed
the
doc_mapping
branch
from
d0fcd30 to
6e60e71
Compare
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@docs/source/db_model_comparison.rst`:
- Around line 11-13: Remove the duplicate explanatory paragraph about
comma-separated elements in the "Database Table" column (the note currently at
lines 11-13) because it repeats the same explanation already given earlier in
lines 3-9; keep the original occurrence and delete the redundant note so the
section contains only one clear explanation of the first element being the table
name and the second being the column name.
In `@docs/source/mathematical_formulation.rst`:
- Around line 127-131: The documentation uses lowercase "python" in the sentence
that mentions the programming language; update the occurrence of the phrase
"python code" to "Python code" in the mathematical_formulation.rst content so
the proper noun is capitalized, leaving the rest of the sentence unchanged.
- Around line 394-395: The table mixes LaTeX commands: the entries for
\mathrm{LGNC}_{\Delta,r,t} and \mathrm{LDGNC}_{\Delta,r,t} use \mathrm{} while
related non-delta parameters use \text{}; update those two parameter notations
to use \text{} (i.e., \text{LGNC}_{\Delta,r,t} and \text{LDGNC}_{\Delta,r,t}) so
all parameter names in the same table use consistent \text{} formatting.
- Line 388: Update the descriptive text for the parameter named
limit_new_capacity (shown as :math:`\text{LNC}_{r,p,t}`) to refer to "capacity"
instead of "activity"; specifically replace "Cumulative activity limit across
time periods (not supported in myopic)" with "Cumulative capacity limit across
time periods (not supported in myopic)" so the description matches the parameter
name.
6e60e71 to
b8ec219
Compare
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@docs/source/db_model_comparison.rst`:
- Around line 193-194: Replace the \mathrm uses in the math labels with \text
for consistency: change ":math:`\mathrm{LGNC}_{\Delta,r,t}`" to
":math:`\text{LGNC}_{\Delta,r,t}`" and ":math:`\mathrm{LDGNC}_{\Delta,r,t}`" to
":math:`\text{LDGNC}_{\Delta,r,t}`" so the LGNC and LDGNC identifiers match the
other parameters that use \text{} formatting.
- Line 177: The description for the variable/symbol ":math:`\text{LNC}_{r,p,t}`"
(identified by the key "limit_new_capacity") is inconsistent between docs:
change the short phrase "new capacity limits" in db_model_comparison.rst to the
more descriptive wording used in mathematical_formulation.rst ("Limit new
capacity deployment by period") so both files use the same informative
description for limit_new_capacity / :math:`\text{LNC}_{r,p,t}`.
- Around line 13-23: The document's table headers are inconsistent: the first
table uses the header value "Model Code" while many later tables use "Model
Element"; update all table header declarations that currently include "Model
Element" to instead use "Model Code" so all tables use the same header
terminology (search for header lines like :header: "Set", "Database Table",
"Model Element", "Notes" and change "Model Element" to "Model Code", and also
replace any standalone column label occurrences of "Model Element" with "Model
Code" to ensure consistency).
In `@docs/source/mathematical_formulation.rst`:
- Around line 388-395: The parameter descriptions for \text{LR}_{r,t} (LR) and
\text{LNC}_{r,p,t} (LNC) are inconsistent between the two docs; update the
descriptions so they are precise and identical across documentation: for
\text{LR}_{r,t} use a single clarified phrase such as "limit resource
production/extraction by technology across time periods (cumulative across
periods; not supported in myopic)" if the model semantics include both
production and extraction, or pick the correct one if it’s only production or
only extraction, and ensure the parenthetical myopic-support note is included
only if accurate; for \text{LNC}_{r,p,t} use a consistent phrase like "limit new
capacity deployment by period (new capacity limits by period)" or whichever
precise meaning matches the model; apply these exact updated strings in both
mathematical_formulation and db_model_comparison entries so the parameter names
\text{LR}_{r,t} and \text{LNC}_{r,p,t} have identical, unambiguous descriptions.
bb51138 to
1ede199
Compare
ParticularlyPythonicBS
force-pushed
the
doc_mapping
branch
from
1ede199 to
1ce3f7b
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/source/db_model_comparison.rst`:
- Around line 4-6: The phrase "column within the database column" is redundant
and should be changed to "column within the database table"; update the sentence
around the :code:`time_period` example so it reads that the second element
refers to a specific column within the database table (not "database column") to
tighten the wording.
Comment on lines
+4
to
+6
| comma-separated. In those cases, the first element refers to the name of the database | ||
| table, and the second refers to specific column within the database column used to | ||
| identify a specific subset. For example, in the first table below, :code:`time_period` |
There was a problem hiding this comment.
Tighten wording: “database column” → “database table”.
Currently reads “column within the database column,” which is redundant.
📝 Proposed fix
- table, and the second refers to specific column within the database column used to
+ table, and the second refers to a specific column within the database table used to🤖 Prompt for AI Agents
In `@docs/source/db_model_comparison.rst` around lines 4 - 6, The phrase "column
within the database column" is redundant and should be changed to "column within
the database table"; update the sentence around the :code:`time_period` example
so it reads that the second element refers to a specific column within the
database table (not "database column") to tighten the wording.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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