Merge branch 'main' into ncc/fixes-in-demos

COSIMA · Apr 22, 2024 · 1b3d840 · 1b3d840
2 parents 274b9e6 + 264e4cd
commit 1b3d840
Show file tree

Hide file tree

Showing 12 changed files with 211 additions and 161 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # regional-mom6
 
-*Python package for automatic generation of regional configurations for the [Modular Ocean Model 6](https://github.com/mom-ocean/MOM6).*
+*Python package for automatic generation of regional configurations for the [Modular Ocean Model version 6](https://github.com/mom-ocean/MOM6) (MOM6).*
 
 [![Repo status](https://www.repostatus.org/badges/latest/active.svg?style=flat-square)](https://www.repostatus.org/#active)
 [![conda forge](https://img.shields.io/conda/vn/conda-forge/regional-mom6.svg)](https://anaconda.org/conda-forge/regional-mom6)
@@ -27,10 +27,12 @@ The idea behind this package is that it should let the user sidestep some of the
 
 ## 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](https://github.com/COSIMA/regional-mom6/pulls) 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.
+- Only generates regional horizontal grids with uniform spacing in longitude and latitude.
+  However, users can provide their own non-uniform grid, or ideally
+  [open a pull request](https://github.com/COSIMA/regional-mom6/pulls) with a method that
+  generates other types of horizontal grids.
+- Only supports boundary segments that are parallel to either lines of constant longitude or
+  lines of constant latitude.
 
 
 ## We want to hear from you
@@ -64,11 +66,11 @@ conda install conda-forge::regional-mom6
 
 That's it -- now enjoy!
 
-#### "*But I want `pip`, can't I install with `pip`*?"
+#### "*But I want pip, can't I install with pip*?"
 
 To install via `pip` is a bit more cumbersome.
 
-A prerequisite is the binary `esmpy` dependency, which provides regridding capabilities.
+A prerequisite is the binary `esmpy` dependency, which provides re-gridding capabilities.
 The easiest way to install `esmpy` is via conda:
 
 ```bash
@@ -97,7 +99,7 @@ pip install git+https://github.com/COSIMA/regional-mom6.git
 ```
 
 to get the version that corresponds to the latest commit in GitHub.
-Alternatively, install the version that corresponds to a particular git commit using
+Alternatively, install the version that corresponds to a particular git commit using, for example,
 
 ```bash
 pip install git+https://github.com/COSIMA/regional-mom6.git@061b0ef80c7cbc04de0566df329c4ea472002f7e
@@ -122,7 +124,6 @@ necessarily those used by the GFDL's [`MOM6_examples`](https://github.com/NOAA-G
 
 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).
+Please ensure that you can get at least one of these working on your setup with your MOM6 executable before trying to modify the example to suit your domain with your bathymetry, forcing, and boundary conditions.
 
+You can download the notebooks [from Github](https://github.com/COSIMA/regional-mom6/tree/main/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).
diff --git a/demos/access_om2-forced.ipynb b/demos/access_om2-forced.ipynb
@@ -870,7 +870,7 @@
     "expt.initial_condition(\n",
     "    tmp_dir + '/ic_unprocessed.nc', # directory where the unprocessed initial condition is stored, as defined earlier\n",
     "    ocean_varnames,\n",
-    "    gridtype=\"B\"\n",
+    "    arakawa_grid=\"B\"\n",
     "    )\n",
     "\n",
     "# Now iterate through our four boundaries \n",

diff --git a/demos/premade_run_directories/README.md b/demos/premade_run_directories/README.md
@@ -0,0 +1,5 @@
+## Premade Run Directories
+
+These directories are used for the demo notebooks, and can be used as templates for setting up a new experiment. The [documentation](https://regional-mom6.readthedocs.io/en/latest/mom6-file-structure-primer.html) explains what all the files are for.
+
+The `common_files` folder contains all of the required files for a regional MOM6 run, including a `data_table` with constant surface forcing as a placeholder. The other two directories offer different choices for the surface forcing, affecting the `data_table`.
diff --git a/demos/premade_run_directories/readme_premade_rundirs.md b/demos/premade_run_directories/readme_premade_rundirs.md
diff --git a/demos/reanalysis-forced.ipynb b/demos/reanalysis-forced.ipynb
@@ -257,7 +257,7 @@
     "expt.initial_condition(\n",
     "    glorys_path / \"ic_unprocessed.nc\", # directory where the unprocessed initial condition is stored, as defined earlier\n",
     "    ocean_varnames,\n",
-    "    gridtype=\"A\"\n",
+    "    arakawa_grid=\"A\"\n",
     "    )\n",
     "\n",
     "# Now iterate through our four boundaries \n",

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -10,20 +10,21 @@ how new docstrings or any new bits of documentation that you may have added look
 ## Testing
 
 To run the tests from a local clone of the repository we first need to create a conda
-environment with all the dependencies required. From the repositories local clone main
-directory do
+environment with all the required dependencies.
+
+We create the environment by calling
 
 ```{code-block} bash
 conda env create --prefix ./env --file environment-ci.yml
 ```
 
-and then activate it
+from the repository's local clone main directory. Then we activate it via
 
 ```{code-block} bash
 conda activate ./env
 ```
 
-Now we need to install the package in this environment as well as `pytest`
+We then install both the package in this environment as well as the `pytest` package:
 
 ```{code-block} bash
 python -m pip install .
@@ -36,8 +37,8 @@ Now we can run the tests with
 python -m pytest tests/
 ```
 
-If we also want to run the doctests (tests that appear as examples in various docstrings), we
-can use
+If we also want to run the doctests (that is, the tests that appear as examples in
+various docstrings), we can use
 
 ```{code-block} bash
 python -m pytest --doctest-modules tests/ regional_mom6/
@@ -46,30 +47,31 @@ python -m pytest --doctest-modules tests/ regional_mom6/
 ## Documentation
 
 To build the docs from a local clone of the repository we first need to create a conda
-environment. Navigate to the `docs` directory of your local repository clone (e.g., `cd docs`)
-and then 
+environment after we first navigate to the `docs` directory of our local repository clone.
 
 ```{code-block} bash
 cd docs
 conda create --name docs-env --file requirements.txt
 ```
 
-Then activate this environment and install the package itself as an editable install (`pip install -e`).
+We activate this environment and install the package itself as an editable install (`pip install -e`).
 
 ```{code-block} bash
 conda activate docs-env
 pip install -e ..
 ```
 
-Now we can make the docs
+Now we can build the docs via `make`:
 
 ```{code-block} bash
 make html
 ```
 
-and open `_build/html/index.html` in your favorite browser.
+and upon successful build, we preview the documentation by opening `_build/html/index.html`
+in our favorite browser.
 
-Alternatively, we can install the dependencies needed for the docs via `pip`; the rest is same, that is
+Alternatively, instead of creating a conda environment, we can install the required
+dependencies for the docs via `pip`; the rest is same, that is
 
 ```{code-block} bash
 cd docs

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,7 +1,7 @@
 Regional MOM6 Documentation
 ===========================
 
-*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 version 6`_ (MOM6).
 
 
 In brief...
@@ -35,11 +35,11 @@ Features
 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.
+- Only generates regional horizontal grids with uniform spacing in longitude and latitude.
+  However, users can provide their own non-uniform grid, or ideally `open a pull request`_
+  with a method that generates other types of horizontal grids.
+- Only supports boundary segments that are parallel to either lines of constant longitude or lines of
+  constant latitude.
 
 
 What you need to get started
@@ -50,12 +50,12 @@ What you need to get started
 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.
+6. `GFDL's FRE tools <https://github.com/NOAA-GFDL/FRE-NCtools>`_ 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
+.. _Modular Ocean Model version 6: https://github.com/mom-ocean/MOM6
 .. _open a pull request: https://github.com/COSIMA/regional-mom6/pulls
 
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,4 +1,5 @@
-# Installation
+Installation
+============
 
 We encourage creating a new or using an existing conda environment.
 
@@ -16,7 +17,7 @@ That's it -- now enjoy!
 
 To install via `pip` is a bit more cumbersome.
 
-A prerequisite is the binary `esmpy` dependency, which provides regridding capabilities.
+A prerequisite is the binary `esmpy` dependency, which provides re-gridding capabilities.
 The easiest way to install `esmpy` is via conda:
 
 ```bash
@@ -45,7 +46,7 @@ pip install git+https://github.com/COSIMA/regional-mom6.git
 ```
 
 to get the version that corresponds to the latest commit in GitHub.
-Alternatively, install the version that corresponds to a particular git commit using
+Alternatively, install the version that corresponds to a particular git commit using, for example,
 
 ```bash
 pip install git+https://github.com/COSIMA/regional-mom6.git@061b0ef80c7cbc04de0566df329c4ea472002f7e