Document mathematical notation

[khaeru]

Following on the 2024-03-28 MESSAGE meeting (#388 (comment)), this PR proposes a style of mathematical notation to be used in the docs.

This style is:

• Intended to be more explicit and easier to read and edit than the existing style.
• Documented on a new page.
  The previous/extant style was not documented fully or in any user-visible location.

This PR is not intended to include revision of all equations to match the style, only to establish it. That revision would be accomplished in 1 or more follow-up PRs by a team of contributors.

How to review

• Look at the ‘Notation’ page in the preview build of the docs.
• Comment below.

PR checklist

• Discuss and implement feedback.
• Complete the section on LaTeX source.
• Maybe expand the Sphinx LaTex/MathJax config.
  In particular, we could define LaTeX commands like \output to expand to \text{output}_{c h h^D l m n^D n^L t y^A y^V}, since these are almost always written the same way. This would make the LaTeX source of the equations much easier to read and edit.
• Continuous integration checks all ✅
• Add or expand tests; coverage checks both ✅
• Add, expand, or update documentation.
• Update release notes.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.6%. Comparing base (ef66e37) to head (d7d963f).

Additional details and impacted files

@@          Coverage Diff          @@
##            main    #811   +/-   ##
=====================================
  Coverage   95.6%   95.6%           
=====================================
  Files         46      46           
  Lines       4344    4344           
=====================================
  Hits        4154    4154           
  Misses       190     190           

[Jihoon]

Thanks, Paul, for putting this together. I tried to go through it but then find it still quite hard to follow the details.

Some observations:

1. If you sum over h on LHS, RHS shouldn't have subscript h.
2. Using y and y^A interchangeably is confusing. The summation mark has y, while there is no y inside the parentheses.
3. I don't quite get the 'alignment' part and the meaning of this. . 'Aligned' means identical?
4. In this sense, indexing was a bit better to follow in the old setting.
5. For the math equation, why don't we use parenthesis within brackets instead of nesting parentheses in parenthesis? (differently from usual coding style)
6. I would assume there is a separate table or something to explain what each index means (like c/h/l). All in one place.
7. Putting =,>, or < on a separate line makes it look also very hidden. What about keeping it the old way: what's being defined goes to LHS, and the elaborative or the specification go RHS. For the given example, putting COMMODITY_BALANCE on LHS and the rest aligned to the right of the equality sign, and at each +/- sign, line changes.
8. n^L is not defined in the end?

Thanks again. This is a VERY helpful effort for readers but a very challenging task for the documentor..

[khaeru]

Thanks @Jihoon for the close read! These are all important points to consider.

1. If you sum over h on LHS, RHS shouldn't have subscript h.
2. Using y and y^A interchangeably is confusing. The summation mark has y, while there is no y inside the parentheses.

These are both errors I think. For (2) I guess it should be y^A on the summation mark for consistency. I'm not sure about (1).

3. I don't quite get the 'alignment' part and the meaning of this. . 'Aligned' means identical?

Yes. This is supposed to reflect that some parameters have dimension n^D, others n^O, others n. If one is e.g. "R12_AFR", then the others are the same.

This is for instance not the case for n^L: n^L can have one value while n^D, n^O, and n have a different one (the same value for all three).

IMHO this is a tricky concept per se, and hard to convey it concisely and clearly through notation.

5. For the math equation, why don't we use parenthesis within brackets instead of nesting parentheses in parenthesis? (differently from usual coding style)

In LaTeX it is possible to write \left( \left( \right) \right) and the LaTeX compiler will make progressively smaller or larger parentheses, which makes it easy to visually match them. MathJAX doesn't seem to support this.

I would be fine for describing an order (e.g. () innermost, followed by [], then alternate…or something like that) but it would be a bit harder to apply consistently. Will consider this further.

6. I would assume there is a separate table or something to explain what each index means (like c/h/l). All in one place.

Yes, these are already given on the page for Sets and mappings. I think this could be improved, but didn't want to get into that yet.

7. Putting =,>, or < on a separate line makes it look also very hidden. What about keeping it the old way: what's being defined goes to LHS, and the elaborative or the specification go RHS. For the given example, putting COMMODITY_BALANCE on LHS and the rest aligned to the right of the equality sign, and at each +/- sign, line changes.

This would produce more line wraps and possibly longer lines that overflow.
I would be okay with always starting with the side that is more brief or a single symbol and keeping the (in)equality on the same line:

COMMODITY_BALANCE =
\sum{
- …
+ …

My one worry with this is that it may reverse the way some equations are named and actually implemented in the code. For example, if a equation is called BLAH_GT or BLAH_LT but then we end up with respectively the symbol ≤ ("less than or equal") or ≥ ("greater than or equal"), the mismatch is potentially confusing. But I will try and see how it looks.

8. n^L is not defined in the end?

It should be defined at (6), maybe isn't.