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.
• Fixed the formatting of citations where the latex used the form \cite[<some text>][]{<key>}, which is meant to put the citation in square brackets and optionally insert some note text. The existing instances of these were broken and didn't render at all.
• 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

[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.

[Paul Barrett (paul-barrett)]

Happy with the state of this for now - but as noted - this is simple port + fix problems rather than a full edit of the docs to make them suitable and relevant for LFRic. This should be done as a future PR

[Paul Barrett (paul-barrett)]

happy that this is a useful and sensible stage to pass this. As noted a future PR should be opened that re-writes the Docs for LFRic and checks new links and references, etc.

Yaswant Pradhan (@yaswant)

[MichaelWhitall]

happy that this is a useful and sensible stage to pass this. As noted a future PR should be opened that re-writes the Docs for LFRic and checks new links and references, etc.

Yaswant Pradhan (Yaswant Pradhan (@yaswant))

Awesome thanks for this Paul,

Looking at the approvals, its still down as awaiting an approval from Steve; mo-sabel, do you have any comments on this PR / changes you'd like to request?

Cheers!
Mike

[mo-sabel]

The quality/resolution of Fig 1 is poor in my browser compared to the UMDP030 pdf. Probably related, but the cartoon cloud in the "Convection Model" box in Fig 1 appears white, compared to the grey gradient colour in UMDP030

[MichaelWhitall]

The quality/resolution of Fig 1 is poor in my browser compared to the UMDP030 pdf. Probably related, but the cartoon cloud in the "Convection Model" box in Fig 1 appears white, compared to the grey gradient colour in UMDP030

Hi thanks Steve,
Yes... the images have to be converted from .eps to .svg to be imported into ReST. The image in figure 1 is actually already quite grainy in the UMDPs, see: https://upgraded-adventure-jznrmqp.pages.github.io/papers/umdp_030.pdf (zoom in at p73). I found that if I converted it to black-and-white (which loses that one grey-scale bit as you noted), it was less grainy, since the grey graininess surrounding the text in the original image gets rendered as plain white. See an example where I've rendered it in "colour" to preserve the original grey-scale here:
https://wwwspice/~michael.whitall/vn3.1_port_pc2_doc_html/science_guide/cloud_schemes/UMDP30_PC2CloudScheme.html#fig-schematic
Zooming in on this one, the grey cloud is restored, but the graininess is worse (inherited from the original image so nothing I can do to fix it). Which do you prefer?

[mo-sabel]

Thanks for explaining Mike. I don't have a strong preference. Maybe the original is better as it is portrait rather than landscape. Note that the new one doesn't have the grey cloud in my browser even when zooming in, but I don't think that is important. Can consider recreating the figure in a future revision (looks like it was mostly done in PowerPoint!)

[MichaelWhitall]

Thanks for explaining Mike. I don't have a strong preference. Maybe the original is better as it is portrait rather than landscape. Note that the new one doesn't have the grey cloud in my browser even when zooming in, but I don't think that is important. Can consider recreating the figure in a future revision (looks like it was mostly done in PowerPoint!)

Sorry about the grey-cloud; I've updated the files to include this in my public_html directory in linux:
file:///home/users/michael.whitall/public_html/vn3.1_port_pc2_doc_html/science_guide/cloud_schemes/UMDP30_PC2CloudScheme.html#fig-schematic
But for some reason that directory viewed from windows hasn't synced with it:
https://wwwspice/~michael.whitall/vn3.1_port_pc2_doc_html/science_guide/cloud_schemes/UMDP30_PC2CloudScheme.html#fig-schematic
so you can't actually see the updated image!

I'll try deleting it and remaking it...

[mo-sabel]

Thanks for explaining Mike. I don't have a strong preference. Maybe the original is better as it is portrait rather than landscape. Note that the new one doesn't have the grey cloud in my browser even when zooming in, but I don't think that is important. Can consider recreating the figure in a future revision (looks like it was mostly done in PowerPoint!)

Sorry about the grey-cloud; I've updated the files to include this in my public_html directory in linux: file:///home/users/michael.whitall/public_html/vn3.1_port_pc2_doc_html/science_guide/cloud_schemes/UMDP30_PC2CloudScheme.html#fig-schematic But for some reason that directory viewed from windows hasn't synced with it: https://wwwspice/~michael.whitall/vn3.1_port_pc2_doc_html/science_guide/cloud_schemes/UMDP30_PC2CloudScheme.html#fig-schematic so you can't actually see the updated image!

I'll try deleting it and remaking it...

That looks like it is working now. I personally think the new version looks better. In particular, the pdf diagrams are much better

[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.

[MichaelWhitall]

Thanks to Steve and Adrian for spotting a few more issues; see the latest commit which fixes them:

1. PC2 process figure now restored to grey-scale like the original in the UMDP (accepting making it slightly grainier).
2. Equations eqn:meltf and eqn:freezell now fixed (error was caused by a stray latex \mbox, which ReST can't handle, so I've replaced that with \mathrm consistent with elsewhere.
3. Reference to subroutine ls_acf_brooks just above figure 1 format now fixed (this one is actually broken in the original latex UMDP; for some reason its put in math mode so the underscores in the text render as subscripts which was clearly not intended!)

The built docs linked here are updated with these changes: https://wwwspice/~michael.whitall/umdp_format_fixes/science_guide/cloud_schemes/UMDP30_PC2CloudScheme.html

[mo-sabel]

Thanks to Steve and Adrian for spotting a few more issues; see the latest commit which fixes them:

1. PC2 process figure now restored to grey-scale like the original in the UMDP (accepting making it slightly grainier).
2. Equations eqn:meltf and eqn:freezell now fixed (error was caused by a stray latex \mbox, which ReST can't handle, so I've replaced that with \mathrm consistent with elsewhere.
3. Reference to subroutine ls_acf_brooks just above figure 1 format now fixed (this one is actually broken in the original latex UMDP; for some reason its put in math mode so the underscores in the text render as subscripts which was clearly not intended!)

The built docs linked here are updated with these changes: https://wwwspice/~michael.whitall/umdp_format_fixes/science_guide/cloud_schemes/UMDP30_PC2CloudScheme.html

Thanks Mike. No more changes from me. I am happy that this is a faithful reproduction of the original document.

[mo-sabel]

I am happy that this is now a faithful reproduction of the original document

[MichaelWhitall]

Yaswant Pradhan (@yaswant), just a heads-up this PR is now ready for code review :)

Cheers!
Mike