Improve documentation of share constraints
- Dominant language
- Jupyter Notebook
- Stars
- 150
- Forks
- 178
- Avg merge
- 17h 32m
- Merged PRs (30d)
- 2
Description
### What is this about?
As discovered through #875, [our documentation for share constraints](https://docs.messageix.org/en/latest/model/MESSAGE/model_core.html#share-constraints) is lacking. For starters, `map_shares_commodity_share` and `map_shares_commodity_total` are missing in the documentation. They are mentioned [here](https://docs.messageix.org/en/latest/model/MESSAGE/model_core.html#share-constraints-on-commodities), but not explained: what can you do with them, what do their index sets mean? In particular, what does `node_share` mean and how does it contrast with `node`? And by defining these in the `map_*`s, why does e.g. `share_commodity_lo` need another `node_share` dimension?
In addition, the index dimensions listed for [`share_*` parameters](https://docs.messageix.org/en/latest/model/MESSAGE/parameter_def.html#parameters-of-the-share-constraints-section) are erroneous: they reference `node_share`, `node`, and `node_loc`, while the GAMS codes calls all of them `node_share`. This should be fixed [here](https://github.com/iiasa/message_ix/blob/00241f6fea4c689ee7f7173cd62b07d218f6571b/message_ix/model/MESSAGE/parameter_def.gms#L722C1-L729C89).
Contributor guide
Research direction
Read the share-constraints sections in the MESSAGE model documentation, then compare their parameter descriptions with message_ix/model/MESSAGE/parameter_def.gms around lines 722–729. Document the purposes and index sets of map_shares_commodity_share and map_shares_commodity_total, clarify node_share versus node, and correct the inconsistent share_* dimensions.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100