Various docs improvements from JOSS review

[jagoosw]

This PR addresses several docs problems from the JOSS review

This includes

• [x] Adds model equations for all model components
• [x] Adds parameter variable name lists to each model component
• [x] Speeds up quickstart example by reducing resolution (and makes the example more realistic)
• [x] Adds flow diagrams explaining the bgc model formulations
• [x] Adds contributors guide (closes #128)
• [ ] Adds docs section explaining how to implement new models (closes #129) Dealt with in #131

[jagoosw]

I can't work out how to write a piecewise equation nicely in Documenters latex. In normal latex you can write \left\{ \begin{array}...\end{array}\right but this doesn't work in Documenter

[navidcy]

I can't work out how to write a piecewise equation nicely in Documenters latex. In normal latex you can write \left\{ \begin{array}...\end{array}\right but this doesn't work in Documenter

Try escaping \ chars, eg

\\begin{array}…

[codecov[bot]]

Codecov Report

Patch coverage: 100.00% and project coverage change: -0.04% :warning:

Comparison is base (1bf27ca) 63.85% compared to head (8b2568c) 63.82%.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #126 +/- ## ========================================== - Coverage 63.85% 63.82% -0.04% ========================================== Files 28 28 Lines 1021 1020 -1 ========================================== - Hits 652 651 -1 Misses 369 369 ``` | [Files Changed](https://app.codecov.io/gh/OceanBioME/OceanBioME.jl/pull/126?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=OceanBioME) | Coverage Δ | | |---|---|---| | [...c/Boundaries/Sediments/instant\_remineralization.jl](https://app.codecov.io/gh/OceanBioME/OceanBioME.jl/pull/126?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=OceanBioME#diff-c3JjL0JvdW5kYXJpZXMvU2VkaW1lbnRzL2luc3RhbnRfcmVtaW5lcmFsaXphdGlvbi5qbA==) | `82.35% <100.00%> (ø)` | | | [src/Boundaries/Sediments/simple\_multi\_G.jl](https://app.codecov.io/gh/OceanBioME/OceanBioME.jl/pull/126?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=OceanBioME#diff-c3JjL0JvdW5kYXJpZXMvU2VkaW1lbnRzL3NpbXBsZV9tdWx0aV9HLmps) | `89.58% <100.00%> (-0.22%)` | :arrow_down: | | [src/Models/AdvectedPopulations/NPZD.jl](https://app.codecov.io/gh/OceanBioME/OceanBioME.jl/pull/126?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=OceanBioME#diff-c3JjL01vZGVscy9BZHZlY3RlZFBvcHVsYXRpb25zL05QWkQuamw=) | `92.00% <100.00%> (ø)` | |

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[jagoosw]

I can't work out how to write a piecewise equation nicely in Documenters latex. In normal latex you can write \left\{ \begin{array}...\end{array}\right but this doesn't work in Documenter

Try escaping \ chars, eg

\\begin{array}…

Think I've got this working now

[jagoosw]

There is something wrong w rendering at

https://oceanbiome.github.io/OceanBioME.jl/previews/PR126/model_components/air-sea-gas/

Good spot, thank you

[navidcy]

Can we try size = (160, 32) for the first example? Movie looks bit pixelated now.

[jagoosw]

Can we try size = (160, 32) for the first example? Movie looks bit pixelated now.

Sure, seems reasonable

[jagoosw]

Todo:

• [x] Add lists of parameter variable names to equations listings
• [x] Add flow diagrams

[jagoosw]

I've added tables to each page with equations listing the corresponding variable name for each parameter and added flow diagrams as per the review suggestions (will see how they look).

I also listed the units which we didn't have anywhere before.

[jagoosw]

@navidcy I think I've finished making the changes here now. The README image doesn't appear to be loading from the preview which is a bit odd. I set it to the preview branch to test (intending to change to main once it worked) but it's not working.

[navidcy]

@navidcy I think I've finished making the changes here now. The README image doesn't appear to be loading from the preview which is a bit odd. I set it to the preview branch to test (intending to change to main once it worked) but it's not working.

Revert back to previous way of showing the video and leave this for a future PR? Upload the latest version of the gif in an issue and update the link?

[jagoosw]

I've changed to a SeawaterBuoyancy with constant salinity to reduce the confusion of also having b. It takes longer to run now though as I had to make the timestep smaller, we could reduce the buoyancy gradient which would probably make it so the timestep can be bigger?

It does only take 3 mins ish to run on my computer.

[jagoosw]

Just tried changing the temp gradient and it looks fine still So will change this and reduce the time step again

[navidcy]

Just tried changing the temp gradient and it looks fine still So will change this and reduce the time step again

Let’s not use a divergent colormap for T

[jagoosw]

Happy with this one?

[navidcy]

Happy with this one?

Magnificent

[jagoosw]

Maybe it's less pretty but a much larger domain like this might be a more realistic first example? And it runs in about the same time.

Obviously not really a realistic problem but the phytoplankton growth has a chance to develop and be effected by the mixing here?

[jagoosw]

Or maybe something like this where the cold water is nutrient-rich, kind of in the vein of this paper https://www.math.hkust.edu.hk/~magan/AMCE6082010/paperpool2010/Franks_1992.pdf

[iuryt]

Or maybe something like this where the cold water is nutrient-rich, kind of in the vein of this paper https://www.math.hkust.edu.hk/~magan/AMCE6082010/paperpool2010/Franks_1992.pdf

It is very cool to see the effect of the downwelling at the front bringing phytoplankton to greater depths. I like this version, also because you also show the evolution of the nutrients.

[navidcy]

A thought: This PR has become large. Why not open new PR for contribution guide etc?

[jagoosw]

A thought: This PR has become large. Why not open new PR for contribution guide etc?

I've already done the contribution guide but forgot to push, so think I will add that and then do the other bit in a new PR?

[jagoosw]

Happy for this PR to be merged now?

[navidcy]

Merge!