Merge branch 'main' into angus-g/pypi-upload

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
@@ -52,23 +54,23 @@ Check out the [documentation](https://regional-mom6.readthedocs.io/en/latest/) a
 
 ## Installation
 
-#### Easy, clean, one liner
+We encourage creating a new or using an existing conda environment.
 
-The easiest way is to install `regional-mom6` via [`conda`](https://anaconda.org/conda-forge/regional-mom6).
-We encourage creating a new or using an existing conda environment and then simply
+#### Easy, clean, one liner via conda
+
+The easiest way to install `regional-mom6` is via [`conda`](https://anaconda.org/conda-forge/regional-mom6).
 
 ```bash
 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*?"
 
-We can install via `pip` but it's a bit more cumbersome.
-Again, we encourage creating a new or using an existing conda environment.
+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
@@ -88,17 +90,16 @@ pip install regional-mom6
 
 The above installs the version of `regional-mom6` (plus any required dependencies) that corresponds to the latest tagged release of the package.
 
-#### "*I'd like to be on the cutting edge of the development*?"
+#### "*I want to live on the edge! I want the latest developments*"
 
-Alternatively, we can install directly `regional-mom6` directly via GitHub using `pip`.
-First install `esmpy` as described above and then:
+To install `regional-mom6` directly via GitHub using `pip`, first install `esmpy` as described above. Then:
 
 ```bash
 pip install git+https://github.com/COSIMA/regional-mom6.git
 ```
 
 to get the version that corresponds to the latest commit in GitHub.
-Or, 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
@@ -123,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).

demos/access_om2-forced.ipynb

@@ -22,26 +22,17 @@
     "Additionally, you'll need access to `/g/data/x77/` if you want to use the same executable using the latest FMS build (a good idea for troubleshooting)."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "To use your own version of regional_mom6 package, clone the entire github repository\n",
-    "on your machine and set the regional-mom6 path using the `os` library, like shown below:"
-   ]
-  },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {
     "tags": []
    },
    "outputs": [],
    "source": [
-    "import os\n",
-    "os.chdir(\"/g/data/v45/nc3020/dhruvs-regional-mom6/\")\n",
-    "\n",
     "import regional_mom6 as rmom6\n",
+    "\n",
+    "import os\n",
     "import xarray as xr\n",
     "from pathlib import Path\n",
     "from dask.distributed import Client"
@@ -526,7 +517,7 @@
     "\n",
     "Setting up a regional model in MOM6 can be a pain. The goal of this package is that users should spend their debugging time fixing a model that's running and doing weird things, rather than puzzling over a model that won't even start.\n",
     "\n",
-    "In running this notebook, you'll hopefully have a running MOM6 regional model. There will still be a lot of fiddling to do with the MOM_input file to make sure that the parameters are set up right for your domain, and you might want to manually edit some of the input files. *But*, this package should help you bypass most of the woes of regridding, encoding and understanding the arcane arts of the MOM6 boundary segment files. "
+    "In running this notebook, you'll hopefully have a running MOM6 regional model. There will still be a lot of fiddling to do with the `MOM_input` file to make sure that the parameters are set up right for your domain, and you might want to manually edit some of the input files. *But*, this package should help you bypass most of the woes of regridding, encoding and understanding the arcane arts of the MOM6 boundary segment files. "
    ]
   },
   {
@@ -590,8 +581,8 @@
    "source": [
     "expt_name = \"tassie-glorys\"\n",
     "\n",
-    "latitude_extent = [-48, -38.95]\n",
-    "longitude_extent = [143, 150]\n",
+    "latitude_extent = (-48, -38.95)\n",
+    "longitude_extent = (143, 150)\n",
     "\n",
     "date_range = [\"2003-01-01 00:00:00\", \"2003-01-05 00:00:00\"]\n",
     "\n",
@@ -607,9 +598,10 @@
     "## Directory where ocean model cut-outs go before processing\n",
     "tmp_dir = f\"{gdata}/{expt_name}\"\n",
     "\n",
-    "for i in [run_dir, tmp_dir, input_dir]:\n",
-    "    if not os.path.exists(i):\n",
-    "        os.makedirs(str(i))"
+    "## if directories don't exist, create them\n",
+    "for path in (run_dir, tmp_dir, input_dir):\n",
+    "    if not os.path.exists(path):\n",
+    "        os.makedirs(path)"
    ]
   },
   {
@@ -737,7 +729,7 @@
    "source": [
     "## Step 4: Set up bathymetry\n",
     "\n",
-    "Similarly to ocean forcing, we point our 'bathymetry' method at the location of the file of choice, and pass it a dictionary mapping variable names. This time we don't need to preprocess the topography since it's just a 2D field and easier to deal with. Afterwards you can run `expt.topog` and have a look at your domain. "
+    "Similarly to ocean forcing, we point the `setup_bathymetry` method at the location of the file of choice. In this case, we don't need to preprocess the bathymetry since it's just a 2D field and easier to deal with. Afterwards, the bathymetry is stored in `expt.bathymetry`."
    ]
   },
   {
@@ -812,7 +804,7 @@
     }
    ],
    "source": [
-    "expt.topog.depth.plot()"
+    "expt.bathymetry.depth.plot()"
    ]
   },
   {
@@ -823,7 +815,7 @@
     "\n",
     "This cuts out and interpolates the initial condition as well as all boundaries (unless you don't pass it boundaries).\n",
     "\n",
-    "The dictionary maps the MOM6 variable names to what they're called in your ocean input file. Notice how the horizontal dimensions are `x` and `y` in the GLORYS reanalysis example, vs `xh`, `yh`, `xq`, `yq`. This is because ACCESS-OM2-01 is on a `B` grid, so we need to differentiate between `q` and `t` points. \n",
+    "The dictionary maps the MOM6 variable names to what they're called in your ocean input file. Notice how the horizontal dimensions are `x` and `y` in the GLORYS reanalysis example, vs `xh`, `yh`, `xq`, `yq`. This is because ACCESS-OM2-01 is on a `B` grid, so we need to differentiate between the `q` and `t` points. \n",
     "\n",
     "If one of your segments is land, you can delete its string from the 'boundaries' list. You'll need to update `MOM_input` to reflect this though so it knows how many segments to look for, and their orientations. "
    ]
@@ -870,7 +862,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",
@@ -1055,7 +1047,7 @@
     "\n",
     "Hopefully your model is running. If not, the first thing you should do is reduce the timestep. You can do this by adding `#override DT=XXXX` to your `MOM_override` file. \n",
     "\n",
-    "If there's strange behaviour on your boundaries, you could play around with the `nudging timescale` (an example is already included in the `MOM_override` file). Sometimes, if your boundary has a lot going on (like all of the eddies spinning off the ACC), it can be hard to avoid these edge effects. This is because the chaotic, submesoscale structures developed within the regional domain won't match those at the boundary. "
+    "If there's strange behaviour on your boundaries, you could play around with the `nudging timescale` (an example is already included in the `MOM_override` file). Sometimes, if your boundary has a lot going on (like all of the eddies spinning off the western boundary currents or off the Antarctic Circumpolar current), it can be hard to avoid these edge effects. This is because the chaotic, submesoscale structures developed within the regional domain won't match those at the boundary. "
    ]
   }
  ],

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`.

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

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
 
 

docs/installation.md

@@ -1,23 +1,23 @@
 Installation
 ============
 
-#### Easy, clean, one liner
+We encourage creating a new or using an existing conda environment.
 
-The easiest way is to install `regional-mom6` via [`conda`](https://anaconda.org/conda-forge/regional-mom6).
-We encourage creating a new or using an existing conda environment and then simply
+## Easy, clean, one liner via conda
+
+The easiest way to install `regional-mom6` is via [`conda`](https://anaconda.org/conda-forge/regional-mom6).
 
 ```bash
 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*?"
 
-We can install via `pip` but it's a bit more cumbersome.
-Again, we encourage creating a new or using an existing conda environment.
+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
@@ -37,17 +37,16 @@ pip install regional-mom6
 
 The above installs the version of `regional-mom6` (plus any required dependencies) that corresponds to the latest tagged release of the package.
 
-#### "*I'd like to be on the cutting edge of the development*?"
+## "*I want to live on the edge! I want the latest developments*"
 
-Alternatively, we can install directly `regional-mom6` directly via GitHub using `pip`.
-First install `esmpy` as described above and then:
+To install `regional-mom6` directly via GitHub using `pip`, first install `esmpy` as described above. Then:
 
 ```bash
 pip install git+https://github.com/COSIMA/regional-mom6.git
 ```
 
 to get the version that corresponds to the latest commit in GitHub.
-Or, 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