[JOSS review] Example usage

In a nutshell

This issue is the response to the item on the checklist regarding example usage. I can run all demo cases described in this page. And I think the content in Running Ocellaris and Demos is good enough to serve this purpose. One thing I think that can be added into the documentation is about the parallel use case. See the following.

No explicit statement about how to run cases with MPI

Parallel simulations with MPI is a feature of this software. But I can't find anywhere in the document that clearly describes how to run a case with MPI. End-users may not have enough knowledge to figure out by themselves how to run an MPI program. So I believe it's better to add one or two sentences to show users an example command to launch Ocellaris with MPI.

Especially that the recommended way of using Ocellaris is through Singularity, and running a Singularity application on a cluster with MPI is not that straightforward (unlike running MPI on a single node). For example, users may have to make sure the MPI versions are the same on the host and in the container.

Actually, based on the page of orun.py, it looks like the implied way to run Ocellaris on a cluster is through a direct installation of Ocellaris, instead of through Singularity. If this is indeed the design, then it's better to clarify this in the documentation. Otherwise, users may go down the rabbit hole trying to make Singularity stuff work with clusters (because the installation instruction recommends users to use Singularity at the beginning).

In a nutshell

No explicit statement about how to run cases with MPI

Comments (5)