iiasa / iiasa/message_ix

Improve documentation of share constraints

Open
#876 0 comments 0 reactions 0 assignees View on GitHub
docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.