Further formatting fixes to the PC2 and boundary-layer scheme docs ported from the UMDPs.

[MichaelWhitall]

PR Summary

Sci/Tech Reviewer: Paul Barrett (@paul-barrett)
Code Reviewer: Yaswant Pradhan (@yaswant)

#450 and #465 made an initial port of the UM Documentation Papers describing the PC2 cloud-scheme and the Boundary-Layer scheme into the lfric_apps science guide. This involved fixing many formatting errors when converting the source from latex to Sphinx / ReStructureText. Subsequent to those PRs being lodged, further formatting problems have been found. This PR attempts to fix these problems:

• The two docs merged together expose an equation label clash (both try to use the same label "dz_param" for one of their equations). So we just change the name of the label in the PC2 doc.
• Non-ASCII characters are removed / converted to ASCII in the PC2 doc (already done in the BL doc in Port boundary-layer scheme documentation into lfric_apps #465). Most common change is unicode fancy apostrophes and quotation marks changed to basic ones.
• Stray trailing white-spaces and blank lines removed.
• Various aligned math regions reinstated in the PC2 doc. I had previously split these up into multiple separate math blocks as ReST doesn't allow labeling individual equations within a single aligned math block. But my scripting to do this was overzealous and had split-up aligned blocks that were already meant to be labeled and referenced as a group. I've now regrouped various instances into single aligned math regions and moved the label to apply to the whole region.
• Fix in-line math inside emphasis. ReST doesn't render equations placed inside italic (* *) or bold (** **); to get these equations to display I needed to close the enclosing ** or * before the math, then open it again afterwards. Where math was inside a bold (** **) region, I've used latex \boldsymbol to make it render bold as intended.
• Replaced latex math \rm, \cal, \bf with \mathrm{}, \mathcal{}, \mathbf. This was requested by code reviewer for the BL doc in Port boundary-layer scheme documentation into lfric_apps #465 but ought to be done consistently in the PC2 doc too. I also found my script had missed a number of instances in the BL doc due to failing to process in-line math split over multiple lines, and math on the declaration line of display math blocks.
• Reinstate closing brackets following equation cross-references (accidentally deleted by my scripts due to a parsing error).
• Corrected citations of papers with authors whose names contained codes for special characters in the latex source. These were parsed incorrectly in my script to import the references from the bibtex file. e.g. \\"u (for a u with double-dots above) fooled my script as the " was interpreted as the end of the field string, so author names containing this character were spuriously truncated.
• Stray curly brackets removed from the references sections (these had been accidentally imported from the latex bibtex file).
• Changed paragraph underline style to """""", as per the style guide (accidentally missed this previously!)
• Footnotes giving author affiliations are reinstated (converting from latex to ReST using pandoc lost these).
• Placeholders for inter-doc cross-referencing added (where there had been inter-UMDP references in the latex). To be changed to proper cross-references using a script once more of the docs have been ported.
• The PC2 cloud-scheme doc contained a diagram of the UM code-structure with different cloud-scheme subroutines colour-coded according to which cloud-scheme uses them. This was broken by the port from latex to ReST (diagram structure didn't display correctly, text colours were lost). I have now attempted to fix these formatting issues (changing it to reflect the LFRic code structure and subroutine names instead of the UM ones still needs to be done in a later PR).

Copy of the built docs: science_guide/index.html#science-guide-index

closes #405
closes #451

Code Quality Checklist

• I have performed a self-review of my own code
• My code follows the project's style guidelines
• Comments have been included that aid understanding and enhance the readability of the code *
• My changes generate no new warnings
• All automated checks in the CI pipeline have completed successfully **

* Only documentation is edited; the doc source should speak for itself without needing explanatory comments, but feel free to suggest if you'd like any clarifying comments in the source?

** check_cr_approved won't pass until code review is approved.

Testing

• I have tested this change locally, using the LFRic Apps rose-stem suite *
• If any tests fail (rose-stem or CI) the reason is understood and acceptable (e.g. kgo changes) *
• I have added tests to cover new functionality as appropriate (e.g. system tests, unit tests, etc.) *
• Any new tests have been assigned an appropriate amount of compute resource and have been allocated to an appropriate testing group (i.e. the developer tests are for jobs which use a small amount of compute resource and complete in a matter of minutes) *

* Only modified documentation; rose-stem not applicable.

To test the changes, I have built the lfric_apps docs from the branch source. The build now gives no errors or warnings.

trac.log

Security Considerations

• I have reviewed my changes for potential security issues *
• Sensitive data is properly handled (if applicable)
• Authentication and authorisation are properly implemented (if applicable)

* I'm not aware of any security issues with the docs. Does anyone know if there are license implications though? The latex UMDPs that I'm porting from are private, whereas the lfric_apps docs that I'm porting to are open-access?

Performance Impact

• Performance of the code has been considered and, if applicable, suitable performance measurements have been conducted

NA

AI Assistance and Attribution

• Some of the content of this change has been produced with the assistance of Generative AI tool name (e.g., Met Office Github Copilot Enterprise, Github Copilot Personal, ChatGPT GPT-4, etc) and I have followed the Simulation Systems AI policy (including attribution labels)

I got M365 copilot to help update the python scripts which I'm using to automate the format corrections applied to the doc ReST source after running pandoc (and the scripts were largely written by copilot in the first place).

Documentation

• Where appropriate I have updated documentation related to this change and confirmed that it builds correctly

This is a documentation-only PR

PSyclone Approval

• If you have edited any PSyclone-related code (e.g. PSyKAl-lite, Kernel interface, optimisation scripts, LFRic data structure code) then please contact the TCD Team

NA

Sci/Tech Review

• I understand this area of code and the changes being added
• The proposed changes correspond to the pull request description
• Documentation is sufficient (do documentation papers need updating)
• Sufficient testing has been completed

(Please alert the code reviewer via a tag when you have approved the SR)

Code Review

• All dependencies have been resolved
• Related Issues have been properly linked and addressed
• CLA compliance has been confirmed
• Code quality standards have been met
• Tests are adequate and have passed
• Documentation is complete and accurate
• Security considerations have been addressed
• Performance impact is acceptable

[Adrian Lock (Adrian-Lock)]

Further improvements to some of the formatting . Well spotted and thinks Mike

[Paul Barrett (paul-barrett)]

The links to equations tends to fall just below the equation in the page, meaning I need to scroll up to see the equations. A minor point, and I suspect it's a "feature" rather than a bug.

[Paul Barrett (paul-barrett)]

There is a section missing 3.3.1 Numerical Application, plus a few lines previous, and Eqn 45 (would become LFRic_Apps docs Eqn 44) and the final sentence in LFRic_Apps docs doesn't seem to appear in UMDocs section 3.3?

[Paul Barrett (paul-barrett)]

more equations not numbered:

after LFRic_Apps #86, UM_Docs 91, 92, 93, (all 3 are factors/constants) 94 (refers to nothing?), 95

LFRic_Apps 102-107, 108-111, (after UM_docs 92)

LFRic_Apps 177, 184, 186, 189, 192, 193, 212, 214, 215, 217-220, 221-224, 226-227, 231, 234-235, 237-239,

just wondering if this is indicative of a bug somewhere?

[Paul Barrett (paul-barrett)]

4.3 PC2 Erosion - differences,
4.3.1 Note: on dbsdtdb1 is NEW in LRFic-Apps
Numerical application of the original width-narrowing method is NEW in LFRic-Apps
Cloud-surface-area hybrid erosion method (new note in LFRic_Apps

[MichaelWhitall]

There is a section missing 3.3.1 Numerical Application, plus a few lines previous, and Eqn 45 (would become LFRic_Apps docs Eqn 44) and the final sentence in LFRic_Apps docs doesn't seem to appear in UMDocs section 3.3?

Thanks lots for spotting this Paul! I just checked and that section is actually missing on the trunk in the github copy of the um_doc repo! i.e. its there on trac:
https://code.metoffice.gov.uk/doc/um/latest/papers/umdp_030.pdf
But mysteriously not there in the exact same UM doc ported to github:
https://upgraded-adventure-jznrmqp.pages.github.io/papers/umdp_030.pdf

The missing section was introduced by my trac ticket:
https://code.metoffice.gov.uk/trac/um/ticket/7403
(which you and Frankie sci/tech reviewed last summer I think!)
This was lodged between UM vn13.9 and vn14.0 (i.e. just before git migration). When the UMDPs were ported to github, they must've taken a copy of them just before ticket 7403 got lodged :P

I could just fix this myself, but should probably first check whether any other changes to the UMDPs between vn13.9 and vn14.0 got left out by mistake!

[MichaelWhitall]

The links to equations tends to fall just below the equation in the page, meaning I need to scroll up to see the equations. A minor point, and I suspect it's a "feature" rather than a bug.

Thanks for testing the equation links! I'm currently finding that if I click an eqn link when viewing the doc in Firefox, the browser lines up with the equation nicely at the top of the window. Whereas currently if I view the same doc using Edge, the equations aren't displaying correctly at all :( Which browser are you using?

[MichaelWhitall]

more equations not numbered:

after LFRic_Apps #86, UM_Docs 91, 92, 93, (all 3 are factors/constants) 94 (refers to nothing?), 95

LFRic_Apps 102-107, 108-111, (after UM_docs 92)

LFRic_Apps 177, 184, 186, 189, 192, 193, 212, 214, 215, 217-220, 221-224, 226-227, 231, 234-235, 237-239,

just wondering if this is indicative of a bug somewhere?

The equations which are numbered in the UMDP latex doc but unnumbered in the lfric_apps ReST doc are ones which were not labeled in the UMDP (and therefore not cross-referenced anywhere). There are various latex math environments which number equations by default, even if you do not label or cross-reference them. But I think in ReST it only generates an equation number if you label the equation. So if we want to keep all the eqn numbers the same as they were in the latex doc, we'll have to add new labels to the currently unlabeled equations in the ReST source. I don't think its worth doing this universally, but shout if there are any particular equations you reckon should be labeled and numbered :)

That's a good spot that in the latex UMDP 030 eq 94 labels a blank line! Looking at the latex source (https://github.com/MetOffice/um_doc/blob/main/source/030/UMDP30_PC2CloudScheme.tex, L1795), this is in an eqnarray environment (which numbers all lines by default unless you add \nonumber to the end of the line). Crucially the intended last line of the block has been ended with \\, which in this latex math environment triggers a new line afterwards. So there is an accidental extra blank line in the eqnarray, and it doesn't have \nonumber, so it gets a number!

[Paul Barrett (paul-barrett)]

The links to equations tends to fall just below the equation in the page, meaning I need to scroll up to see the equations. A minor point, and I suspect it's a "feature" rather than a bug.

Thanks for testing the equation links! I'm currently finding that if I click an eqn link when viewing the doc in Firefox, the browser lines up with the equation nicely at the top of the window. Whereas currently if I view the same doc using Edge, the equations aren't displaying correctly at all :( Which browser are you using?

This was in Chrome, with the window about 40% of the screen size, and so I think it's just a consequence of that (or possibly zoom level), I can't replicate now. So working in Firefox and Chrome seems fine to me. I didn't test every link, but hopefully if someone spots a broken link later they can report it

[Paul Barrett (paul-barrett)]

more equations not numbered:
after LFRic_Apps #86, UM_Docs 91, 92, 93, (all 3 are factors/constants) 94 (refers to nothing?), 95
LFRic_Apps 102-107, 108-111, (after UM_docs 92)
LFRic_Apps 177, 184, 186, 189, 192, 193, 212, 214, 215, 217-220, 221-224, 226-227, 231, 234-235, 237-239,
just wondering if this is indicative of a bug somewhere?

The equations which are numbered in the UMDP latex doc but unnumbered in the lfric_apps ReST doc are ones which were not labeled in the UMDP (and therefore not cross-referenced anywhere). There are various latex math environments which number equations by default, even if you do not label or cross-reference them. But I think in ReST it only generates an equation number if you label the equation. So if we want to keep all the eqn numbers the same as they were in the latex doc, we'll have to add new labels to the currently unlabeled equations in the ReST source. I don't think its worth doing this universally, but shout if there are any particular equations you reckon should be labeled and numbered :)

That's a good spot that in the latex UMDP 030 eq 94 labels a blank line! Looking at the latex source (https://github.com/MetOffice/um_doc/blob/main/source/030/UMDP30_PC2CloudScheme.tex, L1795), this is in an eqnarray environment (which numbers all lines by default unless you add \nonumber to the end of the line). Crucially the intended last line of the block has been ended with \\, which in this latex math environment triggers a new line afterwards. So there is an accidental extra blank line in the eqnarray, and it doesn't have \nonumber, so it gets a number!

I agree - it isn't worth keeping exact correspondence to the latex eqn numbers. I think it makes sense that if they are referred to in text then they need a reference, otherwise it's just there to show working. I didn't really go through to see if I thought others needed a number. We can pick this up in a future PR, once the additional new features are documented.

[Paul Barrett (paul-barrett)]

There is a section missing 3.3.1 Numerical Application, plus a few lines previous, and Eqn 45 (would become LFRic_Apps docs Eqn 44) and the final sentence in LFRic_Apps docs doesn't seem to appear in UMDocs section 3.3?

Thanks lots for spotting this Paul! I just checked and that section is actually missing on the trunk in the github copy of the um_doc repo! i.e. its there on trac: https://code.metoffice.gov.uk/doc/um/latest/papers/umdp_030.pdf But mysteriously not there in the exact same UM doc ported to github: https://upgraded-adventure-jznrmqp.pages.github.io/papers/umdp_030.pdf

The missing section was introduced by my trac ticket: https://code.metoffice.gov.uk/trac/um/ticket/7403 (which you and Frankie sci/tech reviewed last summer I think!) This was lodged between UM vn13.9 and vn14.0 (i.e. just before git migration). When the UMDPs were ported to github, they must've taken a copy of them just before ticket 7403 got lodged :P

I could just fix this myself, but should probably first check whether any other changes to the UMDPs between vn13.9 and vn14.0 got left out by mistake!

That makes sense, I couldn't work out why it felt like it was the first time I was seeing this in the LFRic_Apps docs! Good plan, worth checking for other changes first.

[MichaelWhitall]

That makes sense, I couldn't work out why it felt like it was the first time I was seeing this in the LFRic_Apps docs! Good plan, worth checking for other changes first.

I've posted a question about the UMDP content missing from the port to github here:
MetOffice/simulation-systems#673
Still waiting to see if anyone from SSD team can advise...

[MichaelWhitall]

Re the missing section of the PC2 doc (when comparing the UMDP on github versus the UMDP on trac), Yash helped me get to the bottom of this here:
MetOffice/simulation-systems#673

Section 3.3.1 was actually deleted by my trac ticket 4703, which replaced it with new sections further down the doc. The key thing is, the docs hosted on trac at
https://code.metoffice.gov.uk/doc/um/latest/papers/umdp_030.pdf
are frozen at vn13.9; they do not include any changes after vn13.9, hence my changes from 4703 don't appear there. But the docs hosted on github at
https://upgraded-adventure-jznrmqp.pages.github.io/papers/umdp_030.pdf
do include changes after vn13.9. That's why the two appear different, with sections added or removed.

i.e. the trunk of the um_doc github repo is the up-to-date one and all is well afterall :) (that's the one I copied to make the new lfric_apps doc).

[MichaelWhitall]

Following some feedback offline from Yaswant Pradhan (@yaswant), I've added the latest commit which fixes the UM code-structure diagram in the PC2 cloud-scheme doc (just formatting corrections; changing the content to reflect LFRic rather than UM is tbd in another PR). In particular, the original latex version of this colour-coded the subroutine names according to whether they're used by the Smith, PC2 or bimodal cloud-schemes, but the text colours hadn't ported into ReST. Text colour has now been re-implemented.

[github-actions]

⚠️ Hello MichaelWhitall!

Your CLA signature was found on the base branch, but you appear to have modified the CONTRIBUTORS.md file in this PR.

Please do not edit the CONTRIBUTORS.md file. If you have already signed the CLA, revert changes to the file and your signature will be picked up.