Requesting v0.7 documentation improvements/fixes

[irm-codebase]

Description

This is a list of things I found on the documentation of the new release that could be improved. Most are minor things.

1. YAML schema: description is missing tabs beyond the second level for some items, making it hard to read. Examples: time_subset, parameters, tech_groups.
2. Model configuration: it would be good to specify if the dates in time_subset are inclusive (does ['2005-01-01', '2005-01-05'] run up to or include May?)
3. Tab 2 or tab 4 usage is a bit inconsistent. There is a statement advocating for tab 2, but a good amount of examples use tab 4.
4. Specify checks for techs. For cost_ parameters, the documentation mentions they must define a cost class, but it's unclear what that means or what the code will check for. Is it an index or a dims? Will the library return an error if the user sets this incorrectly? nodes has something similar for dims: if the users specifies nodes, will the code catch it?
5. nodes deactivation: move the nodes deactivation comment from the techs section to the nodes section, to make it easier to find.
6. nodes using constraints to modify techs: in the nodes section it's mentioned that you overwrite techs settings by using constraints. I think this term is a bit confusing (it's not used anywhere else before, and it's seldom mentioned in the documentation). Is it really necessary? Otherwise, I'd just remove it since it's clear that anything below a techs will be a parameter, and costs_ already have standardised naming.
7. Tabular data: I recommend showing the tabular data as tables instead of comma text, to make it easier to read.
8. Inbuilt math vs custom-math: I think the activation of Inter-cluster storage via custom math is a bit confusing and hard to find. Maybe moving it to a "pre-defined custom math" section would solve this. As it stands, the inbuilt math section mostly talks about custom math.
9. Math readability: most equations are quite hard to follow because they get "cut" due to the long names. Defining the conditions above the constraints would help with this:

Initial conditions (for all timestep in timesteps... etc):

• Equation_1... if condition_1...
• Equation_2... if condition_2...

Or (for an even more readable alternative):

Initial conditions:

• if condition_1: Equation_1

10. foreach, where math syntax examples: when reading the section, it's a bit difficult to see how these are used since there is no complete example. Adding one at the start would solve this. Or moving the equation section to the top, since it's where most of these terms are used.
11. Math components and Math syntax: the custom math section says to read syntax, then components, but the order and the way the text is written seems to suggest the opposite.

Related links

1. https://calliope.readthedocs.io/en/v0.7.0.dev2/reference/config_schema/#model-configuration-schema
2. https://calliope.readthedocs.io/en/v0.7.0.dev2/creating/config/
3. https://calliope.readthedocs.io/en/v0.7.0.dev2/creating/techs/ (example of tab 4 usage)
4. https://calliope.readthedocs.io/en/v0.7.0.dev2/creating/techs/ (unclear if there are checks for cost_)
5. https://calliope.readthedocs.io/en/v0.7.0.dev2/creating/techs/ (nodes comment that is hard to find)
6. https://calliope.readthedocs.io/en/v0.7.0.dev2/creating/nodes/ (constraints to modify techs)
7. https://calliope.readthedocs.io/en/v0.7.0.dev2/creating/data_sources/#__tabbed_3_1 (showing tabular data as tables)
8. https://calliope.readthedocs.io/en/v0.7.0.dev2/math/ (inbuilt math vs custom math).
9. https://calliope.readthedocs.io/en/v0.7.0.dev2/math/base/ (making math more readable).
10. https://calliope.readthedocs.io/en/v0.7.0.dev2/custom_math/syntax/ (where, foreach usage is unclear)
11. https://calliope.readthedocs.io/en/v0.7.0.dev2/custom_math/ (reverse suggestion to read Math syntax then components)

Version

v0.7.0

Proposed change

Some suggested updates to the documentation.

[sjpfenninger]

Thanks, this is very useful feedback!

[brynpickering]

@irm-codebase thanks for the feedback.

Some responses / requests for additional thoughts:

8. How about "pre-defined" math for everything we have already built into calliope and "user-defined" math instead of "custom" math?
9. This is somewhat intentional. We're trying to strictly match convention for defining math. It isn't pretty because of all the "cases" but we're not really trying to make it pretty. If you can provide LaTeX examples of how to structure math with cases as you've suggested then I'm open to changing the implementation to increase readability.

10/11. @sjpfenninger and I went back and forth on this a few times, hence why there's some confusion between different pages! We opted for "components" to come first so that you get some context via more complex examples before going into detail on the "syntax". Would it have been sufficiently clear if you had read the "components" page first?

[irm-codebase]

8. That would make sense! I'd sub-divide into core math and then additional features (time aggregation, operational mode, pathways, etc.).
9. I suppose that makes sense, but it's still very hard to read. IMO documentation is only read if it's accessible... Here's a suggested version using \quad and \qquad:

$\forall tech \in techs, node \in nodes, step \in steps, year \in years \quad \text{if} \quad \exists (\mathbf{param}_{tech,node}):$ $\quad \text{if some condition}:$

$\qquad var{tech,node,step,year} = othervar{tech,node,step,year}\cdot \mathbf{param}_{tech,node}$

10. (and 11): I think so! I'd just change the suggested order in the linked page.

---

Math code, in case GitHub does not allow you to see it:

$\forall tech \in  techs, node \in nodes, step \in steps, year \in years \quad \text{if} \quad  \exists (\mathbf{param}_{tech,node}):$
$\quad  \text{if some condition}:$

$\qquad var_{tech,node,step,year} = othervar_{tech,node,step,year}\cdot \mathbf{param}_{tech,node}$