Add intro in Docs + include a "MOM6 file structure primer" section

README.md

@@ -1,4 +1,4 @@
-# regional_mom6
+# regional-mom6
 
 *Python package for automatic generation of regional configurations for the [Modular Ocean Model 6](https://github.com/mom-ocean/MOM6).*
 
@@ -14,11 +14,27 @@ Users just need to provide some information about where, when, and how big their
 
 The idea behind this package is that it should let the user sidestep some of the tricky issues with getting the model to run in the first place. This removes some of the steep learning curve for people new to working with MOM6. Note that the resultant model configuration might still need some tweaking (e.g., fiddling with timestep to avoid CFL-related numerical stability issues or fiddling with bathymetry to deal with very narrow fjords or channels that may exist).
 
-Limitations: Currently the package supports only one horizontal grid type (that is equally spaced in longitude); there are plans to add more grid options. We have designed the package in a way that it is modular so, for example, one needs to implement just another method for a different type of grid and the rest should be good to go.
 
-If you find this package useful and have any suggestions please feel free to open an [issue](https://github.com/COSIMA/regional-mom6/issues) or a [discussion](https://github.com/COSIMA/regional-mom6/discussions). We'd love to have [new contributors](https://regional-mom6.readthedocs.io/en/latest/contributing.html) and we are very keen to help you out along the way!
+## Features
+
+- Automatic grid generation at chosen vertical and horizontal grid spacing.
+- Automatic removal of non-advective cells from the bathymetry that cause the model to crash.
+- Handle slicing across 'seams' in of the forcing input datasets (e.g., when the regional configuration spans the longitude 180 of a global dataset that spans [-180, 180]).
+- Handles metadata encoding.
+- Creates directory structure with the configuration files as expected by MOM6.
+- Handles interpolation and interpretation of input data. No pre-processing of forcing datasets is required. (In some cases, slicing the forcing dataset before helps with hitting limitations related to the machine's available memory.)
+
+## Limitations
+
+Currently the package only supports one type of regional horizontal grid, namely one that's equally spaced in longitude and latitude. Users can provide their own grid, or ideally [open a PR](https://github.com/COSIMA/regional-mom6/pulls) with a method that implements another type of horizontal grid! Furthermore, currently only boundary segments that are parallel to either lines of constant longitude or constant latitude lines are supported. 
+
+## We want to hear from you
+
+If you have any suggestions please feel free to open an [issue](https://github.com/COSIMA/regional-mom6/issues) or start a [discussion](https://github.com/COSIMA/regional-mom6/discussions). We welcome any [new contributors](https://regional-mom6.readthedocs.io/en/latest/contributing.html) and we are very keen to help you out along the way!
+
 
 ## What you need to get started:
+
 1. a cool idea for a new regional MOM6 domain,
 2. a working MOM6 executable on a machine of your choice, 
 3. a bathymetry file that at least covers your domain,
@@ -28,6 +44,7 @@ If you find this package useful and have any suggestions please feel free to ope
 
 Check out the [documentation](https://regional-mom6.readthedocs.io/en/latest/) and browse through the [demos](https://regional-mom6.readthedocs.io/en/latest/demos.html).
 
+
 ## Installation
 
 #### Easy, clean, one liner
@@ -55,7 +72,7 @@ conda install -c conda-forge esmpy
 
 Alternatively, to install `esmpy` in a Conda-free way, follow the instructions for [installing ESMPy from
 source](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/install.html#installing-esmpy-from-source).
-With `esmpy` available, we can then install `regional_mom6` via pip. (If we don't have have pip, then
+With `esmpy` available, we can then install `regional-mom6` via pip. (If we don't have have pip, then
 `conda install pip` should do the job.)
 
 With `esmpy` installed we can now install `regional-mom6` via [`pip`](https://pypi.org/project/regional-mom6/):
@@ -84,8 +101,9 @@ pip install git+https://github.com/COSIMA/regional-mom6.git@061b0ef80c7cbc04de05
 
 ## MOM6 Configuration and Version Requirements
 
-The package and demos assume a coupled SIS2-MOM6 configuration.
-The examples could work for an ocean-only MOM6 run but this has not been tested. 
+The package and demos assume a coupled MOM6-SIS2 configuration, but also work for MOM6 ocean-only configuration after appropriate changes in the `input.nml` and `MOM_input` files.
+
+Additionally, regional configurations require that the MOM6 executable _must_ be compiled with **symmetric memory**.
 
 The current release of this package assumes the latest source code of all components needed to run MOM6 as of
 January 2024. A forked version of the [`setup-mom6-nci`](https://github.com/ashjbarnes/setup-mom6-nci) repository
@@ -95,18 +113,12 @@ directory lists the particular commits that were used to compile MOM6 and its su
 Note that the commits used for MOM6 submodules (e.g., Flexible Modelling System (FMS), coupler, SIS2) are _not_
 necessarily those used by the GFDL's [`MOM6_examples`](https://github.com/NOAA-GFDL/MOM6-examples) repository.
 
-## Getting started
 
+## Getting started
 
 The [example notebooks](https://regional-mom6.readthedocs.io/en/latest/demos.html) walk you through how to use
 the package using two different sets of input datasets.
 Please ensure that you can get at least one of these working on your setup with your MOM6 executable before trying modify the example to suit your domain with your bathymethry, forcing, and boundary conditions.
 
 You can download the notebooks [from Github](https://github.com/COSIMA/regional-mom6/tree/ncc/installation/demos) or by clicking on the download <img width="22" alt="download" src="https://github.com/COSIMA/regional-mom6/assets/7112768/2c1ae149-c6a8-4395-ab09-2f77588008d9"> button, e.g., at the top-right of the [regional tasmania forced by ERA5 example](https://regional-mom6.readthedocs.io/en/latest/demo_notebooks/reanalysis-forced.html).
 
-**Note**
-
-The `xesmf` the package attempts to regrid in parallel, and if it's not able to do so, it throws a warning and
-runs in serial. You also get a print out of the relevant `mpirun` command which you could use as a backup.
-Depending on your setup of your machine, you may need to write scripts that implement the package to access more
-computational resources than might be available, e.g., on the HPC machine of you are working on.

docs/index.rst

@@ -1,17 +1,71 @@
 Regional MOM6 Documentation
 ===========================
 
-``regional_mom6`` is a Python package for automatic generation of regional
-configurations for the `Modular Ocean Model 6`_.
+*Python package for automatic generation of regional configurations for the `Modular Ocean Model 6`_.*
+
+
+In brief...
+-----------
+
+Users just need to provide some information about where, when, and how big their domain
+is and also where raw input forcing files are. The package sorts out all the boring details
+and creates a set of MOM6-friendly input files along with setup directories ready to go! 
+
+The idea behind this package is that it should let the user sidestep some of the tricky
+issues with getting the model to run in the first place. This removes some of the steep
+learning curve for people new to working with MOM6. Note that the resultant model configuration
+might still need some tweaking (e.g., fiddling with timestep to avoid CFL-related numerical
+stability issues or fiddling with bathymetry to deal with very narrow fjords or channels that may exist).
+
+
+Features
+--------
+
+- Automatic grid generation at chosen vertical and horizontal grid spacing.
+- Automatic removal of non-advective cells from the bathymetry that cause the model to crash.
+- Handle slicing across 'seams' in of the forcing input datasets (e.g., when the regional
+  configuration spans the longitude 180 of a global dataset that spans [-180, 180]).
+- Handles metadata encoding.
+- Creates directory structure with the configuration files as expected by MOM6.
+- Handles interpolation and interpretation of input data. No pre-processing of forcing datasets
+  is required. (In some cases, slicing the forcing dataset before helps with hitting limitations
+  related to the machine's available memory.)
+
+
+Limitations
+------------
+
+- Only supports one type of regional horizontal grid, namely one that's equally spaced in longitude
+  and latitude. Users can provide their own grid, or ideally `open a pull request`_ with a method
+  that implements another type of horizontal grid!
+- Only boundary segments that are parallel to either lines of constant longitude or constant latitude
+  lines are supported.
+
+
+What you need to get started
+----------------------------
+
+1. a cool idea for a new regional MOM6 domain,
+2. a working MOM6 executable on a machine of your choice, 
+3. a bathymetry file that at least covers your domain,
+4. 3D ocean forcing files *of any resolution* on your choice of A, B, or C Arakawa grid,
+5. surface forcing files (e.g., from ERA or JRA reanalysis), and
+6. `GFDL's FRE tools <https://github.com/NOAA-GFDL/FRE-NCtools>`_ be downloaded and compiled on the machine you are using.
+
+Browse through the `demos <demos.html>`_.
+
 
 .. _Modular Ocean Model 6: https://github.com/mom-ocean/MOM6
+.. _open a pull request: https://github.com/COSIMA/regional-mom6/pulls
+
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
    installation
    demos
+   mom6-file-structure-primer
    api
    contributing
 

docs/mom6-file-structure-primer.md

@@ -0,0 +1,98 @@
+A primer on MOM6 file structure
+===============================
+
+Here we describe the various directories and files that `regional-mom6` package produces alongside with
+userful insights that, hopefully, will help users deal with troubleshooting and more advanced customisations.
+
+## `run` directory
+
+The directory, specified by the `mom_run_dir` path keyword argument in the `experiment` class, contains only text files that configure MOM6 and are used at model initialisation.
+You can see examples of these files in the `premade_run_directories`.
+These files are:
+
+* `input.nml`:
+  High-level information that is passed directly to each component of your MOM6 setup.
+  The paths of to the `SIS` and `MOM` input directories and outputs are included.
+  The `coupler` section turns on or off different model components, and specifies how long to run the experiment for. 
+
+* `diag_table`:
+  The diagnostics to save from your model run.
+  Choose wisely the quantities that are relevant to your experiment and the analysis you plan to do otherwise you can fill up disk space very fast.
+  Different lines in the `diag_table` either specify a new output *file* and its associated characteristics, or a new output *variable* and the matching file that it should go in (which needs to already have been specified).
+  If uncertain regarding which diagnostics to pick, try running the model for a short period (e.g., 1 hour) and look in the output folder.
+  There, we find a file `available_diags` that lists every available diagnostic for your model configuration also mentioning  which grids the quantity can be output on.
+  Aside from the native model grid, we can create our own custom vertical coordinates to output on.
+  To output on a custom vertical coordinate, create a netCDF that contains all of the vertical points (in the coordinate of your choice) and then edit the `MOM_input` file to specify additional diagnostic coordinates.
+  After that, we are able to select the custom vertical coordinate in the `diag_table`.
+
+  Instructions for how to format the `diag_table` are included in the [MOM6 documentation](https://mom6.readthedocs.io/en/dev-gfdl/api/generated/pages/Diagnostics.html).
+
+* `data_table`
+  The data table is read by the coupler to provide different model components with inputs.
+  With more model components we need more inputs.
+
+  Instructions for how to format the `data_table` are included in the [MOM6 documentation](https://mom6.readthedocs.io/en/dev-gfdl/forcing.html). 
+
+* `MOM_input / SIS_input`
+  Basic settings for the core MOM and SIS code with reasonably-well documentation.
+  After running the experiment for a short amount of time, you can find a `MOM_parameter_doc.all` file which lists every possible setting your can modify for your experiment.
+  The `regional-mom6` package can copy and modify a default set of input files to work with your experiment.
+  There's too much in these files to explain here.
+  The aforementioned vertical diagnostic coordinates are specified here, as are all of the different parameterisation schemes and hyperparameters used by the model.
+  Some of these parameters are important, e.g., the timesteps, which will likely need to be fiddled with to get your model running quickly but stably.
+  However, it can be more helpful to specify these in the `MOM_override` file instead. 
+
+  Another important part section for regional modelling is the specification of open boundary segments.
+  A separate line for each boundary in our domain is included and also any additional tracers need to be specified here.
+
+* `MOM_override`
+  This file serves to override settings chosen in other input files. This is helpful for making a distinction between the thing you're fiddling with and 95% of the settings that you'll always be leaving alone. For instance, you might need to temporarily change your baroclinic (`DT`), thermal (`DT_THERM`) or baroclinic (`DT_BT`) timesteps, or are doing perturbation experiments that requires you to switch between different bathymetry files.
+
+* `config file`
+  This file is machine dependent and environment dependent. For instance, if you're using Australia's National Computational Infrastructure (NCI), then you're likely using the `payu` framework, and you'll have a `config.yml` file. Regardless of what it looks like, this file should contain information that points to the executable, your input directory (aka the `mom_input_dir` you specified), the computational resources you'd like to request and other various settings. 
+
+  The package does come with a premade `config.yml` file for payu users which is automatically copied and modified when the appropriate flag is passed to the `setup_rundir` method. If you find this package useful and you use a different machine, I'd encourage you to provide an example config file for your institution! Then this could be copied into.
+
+
+## `input` directory
+
+The directory referred to by as `mom_input_dir` path that hosts mostly netCDF files that are read by MOM6 at runtime.
+These files can be big, so it is usually helpful to store them somewhere without any disk limitations. 
+
+* `hgrid.nc`
+  The horizontal grid that the model runs on. Known as the 'supergrid', it contains twice as many points in each
+  horizontal dimension as one would expect from the domain extent and the chosen resolution. This is because *all*
+  points on the Arakawa C grid are included: both velocity and tracer points live in the 'supergrid'. For a regional
+  configuration, we need to use the 'symmetric memory' configuration of the MOM6 executable. This implies that the
+  horizontal grids boundary must be entirely composed of cell edge points (like those used by velocities). Therefore,
+  for example, a model configuration that is 20-degrees wide in longitude and has 0.5 degrees longitudinal resolution,would imply that it has 40 cells in the `x` dimension and thus a supergrid with `nx = 41`. 
+
+  The `nx` and `ny` points are where data is stored, whereas `nxp` and `nyp` here define the spaces between points
+  used to compute area. The `x` and `y` variables in `hgrid` refer to the longitude and latitude. Importantly, `x`
+  and `y` are both two-dimensional (they both depend on both `nyx` and `nyp`) meaning that the grid does not have
+  to follow lines of constant latitude or longitude. Users that create their own own custom horizontal and vertical
+  grids can `read_existing_grid` to `True` when creating an experiment.
+
+* `vcoord.nc`
+  The values of the vertical coordinate. By default, `regional-mom6` sets up a `z*` vertical coordinate but other
+  coordinates may be provided after appropriate adjustments in the `MOM_input` file. Users that would like to
+  customise the vertical coordinate can initialise an `experiment` object to begin with, then modify and the `vcoord.nc`
+  file and save. Users can provide additional vertical coordinates (under different names) for diagnostic purposes.
+  These additional vertical coordinates allow diagnostics to be remapped and output during runtime. 
+
+* `bathymetry.nc`
+  Fairly self explanatory, but can be the source of some difficulty. The package automatically attempts to remove "non advective cells". These are small enclosed lakes at the boundary that can cause numerical problems whereby water might flow in but have no way to flow out. Likewise, there can be issues with very shallow (only 1 or 2 layers) or very narrow (1 cell wide) channels. If your model runs for a while but then gets extreme sea surface height values, it could be caused by an unlucky combination of boundary and bathymetry.
+
+  Another thing to note is that the bathymetry interpolation can be computationally intensive. For a high-resolution
+  dataset like GEBCO and a large domain, one might not be able to execute the `.setup_bathymetry` method within
+  a Jupyter notebook. In that case, instructions for running the interpolation via `mpirun` will be printed upon
+  executing the `setup_bathymetry` method.
+
+* `forcing/init_*.nc`
+  The initial conditions bunched into velocities, tracers, and the free surface height. 
+
+* `forcing/forcing_segment*`
+  The boundary forcing segments, numbered the same way as in `MOM_input`. The dimensions and coordinates are fairly
+  confusing, and getting them wrong can likewise cause some cryptic error messages! These boundaries do not have to
+  follow lines of constant longitude and latitude, but it is much easier to set things up if they do. For an example
+  of a curved boundary, see this [Northwest Atlantic experiment](https://github.com/jsimkins2/nwa25/tree/main).