JOSS paper edits/comments by Chris

[ashjbarnes]

Replicating Chris's PR to point to joss-paper

Hi @ashjbarnes @navidcy
Following @aekiss and making my comments through a PR on a separate branch.

I've made a few mostly minor modifications to the paper.md file. I've included a referece to Mike Herzfeld's work developing the original implementation of the radiation boundary conditions in MOM4, which includes a number of rules-of-thumb regarding regional domain parameters (grid resolution, time step, etc..). I also agree with @aekiss that there was a lot of useful information in the commented out sections of the paper, that, if space isn't an issue, I think could be included.

A few brief comments

1. Worth noting that MOM6, while improving some aspects of the regional modelling, has also lost some capabilities. Noteably, a number of radiative schemes are yet to be implemented on the C-grid. Not sure if we need this level of detail in the paper.
2. The major advantage of using MOM6 in regional modelling is to access the advantages of the new ocean model (ALE, better tracer advection schemes enabling larger time-steps, etc...);
3. Do we need step-by-step guide to what inputs are required, and what the expected outputs are? Or is this best handled within the code itself?
4. How removed from the NCI/Gadi environment do we need to be to make this work open for a general audience?

Great work so far. I don't think you are far from having something ready to submit.

[navidcy]

1. Worth noting that MOM6, while improving some aspects of the regional modelling, has also lost some capabilities. Noteably, a number of radiative schemes are yet to be implemented on the C-grid. Not sure if we need this level of detail in the paper.

True. But let's not start comparing MOM5 and MOM6 in this paper. It's beyond the scope. We should only mention what is relevant for the package.

2. The major advantage of using MOM6 in regional modelling is to access the advantages of the new ocean model (ALE, better tracer advection schemes enabling larger time-steps, etc...);

Good point!

3. Do we need step-by-step guide to what inputs are required, and what the expected outputs are? Or is this best handled within the code itself?

It can go either way. At the moment we mention briefly and point to the documented examples.

4. How removed from the NCI/Gadi environment do we need to be to make this work open for a general audience?

We need to be totally removed! A package cannot be only applicable to particular machine. Imagine the Nature paper titled "Array programming with NumPy on Australia's Gadi HPC". I doubt it would have the same audience...

Why you ask @ChrisC28 -- did you have anything in mind? As it stands now the package is completely removed from NCI-specifics. Only one of the two examples is NCI-specific, the one that uses ACCESS-OM2 output as forcing. But our plan is to remove this example from the package's documentation and move it to the cosima-recipes (see COSIMA/cosima-recipes#326) and then add a link to the cosima-recipes in this package's docs.

[ashjbarnes]

Thanks Chris! I suggest we have a discussion here and resolve Chris's dot points one by one.

Regarding the commented out sections, given the feedback of @aekiss and @ChrisC28, I'll put them back in in this PR and then @navidcy perhaps we could then re-trim them with any information you think is excessive?

1. I tend to agree that these details might be beyond what we need to include
2. This is a good point though and helps to contextualise why it's worth investing in MOM6 tools|
3. Inputs should be clear from the README of the package itself, but I hadn't thought about the outputs. I think the output files themselves ought to be expanded on in the documentation, if not the paper. Do you think it's sufficient that we say the package generates everything that's needed to run MOM6 except the executable itself without listing and explaining all of the components?
4. At this stage it's pretty devoid of NCI specific stuff (except for the access om2 example which we're still trying to migrate to cosima examples). One payu-centric thing is still present ( Surface forcing file paths contain are setup for payu users #93 )

[navidcy]

Let's merge this and then bring back the commented txt after we first ensure that appropriate modifications occur so that the text flows?

[ashjbarnes]

Let's merge this and then bring back the commented txt after we first ensure that appropriate modifications occur so that the text flows?

Sure sounds good! I'm happy with Chris's changes but can't approve now that it's my PR of course. I'll take your lead on bringing back the text since I'm sure I'll make a big git mess...

[navidcy]

lgtm!
a few edits!
let's add citation to the ALE paper, https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2019MS001954

[navidcy]

Suggested change

	The learning curve for setting up a regional ocean model can be quite steep, and it it not obvious for a new user what inputs are required, nor the appropriate format.
	The learning curve for setting up a regional ocean model can be quite steep, and it is not obvious for a new user what inputs are required, nor the appropriate format of them.

[navidcy]

@ashjbarnes I approved the PR but I also made some suggestions. Could you have a look and commit them if you agree or modify wherever you feel?

[navidcy]

Let's merge this and then bring back the commented txt after we first ensure that appropriate modifications occur so that the text flows?

Sure sounds good! I'm happy with Chris's changes but can't approve now that it's my PR of course. I'll take your lead on bringing back the text since I'm sure I'll make a big git mess...

I can also do the resurrection of the commented text ;)

[ashjbarnes]

I've merged so we can do the un-commenting of text separately as a next step, but @ChrisC28 let us know what you think about our responses to your 4 points above. Navid has already addressed 2, there's an issue associated with 4 but we can continue discussing 1 & 3