Merge branch 'main' into ncc/clean-hgrid

.gitignore

@@ -5,4 +5,4 @@ _build
 regional_mom6/_version.py
 regional_mom6.egg-info
 .pytest_cache
-env
+.env

README.md

@@ -1,7 +1,46 @@
-# regional_mom6: Python package for automatic generation of regional configurations for the Modular Ocean Model 6
+# regional_mom6
 
-[![codecov](https://codecov.io/gh/COSIMA/regional-mom6/branch/master/graph/badge.svg?token=7OEZ1UZRY4)](https://codecov.io/gh/COSIMA/regional-mom6) [![Documentation Status](https://readthedocs.org/projects/regional-mom6/badge/?version=latest)](https://regional-mom6.readthedocs.io/en/latest/?badge=latest) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+*Python package for automatic generation of regional configurations for the [Modular Ocean Model 6](https://github.com/mom-ocean/MOM6).*
 
-Just provide some information about where, when and how big, and also where raw input forcing files live. The package will sort out all the boring details to create MOM6-friendly input files.
+[![Repo status](https://www.repostatus.org/badges/latest/active.svg?style=flat-square)](https://www.repostatus.org/#active) [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://mit-license.org) [![codecov](https://codecov.io/gh/COSIMA/regional-mom6/branch/master/graph/badge.svg?token=7OEZ1UZRY4)](https://codecov.io/gh/COSIMA/regional-mom6) [![Documentation Status](https://readthedocs.org/projects/regional-mom6/badge/?version=latest)](https://regional-mom6.readthedocs.io/en/latest/?badge=latest) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-Check out the [demo notebook](https://nbviewer.org/github/COSIMA/regional-mom6/blob/main/demo.ipynb) and also the [documentation](https://readthedocs.org/projects/regional-mom6/badge/?version=latest)!
+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!
+
+Check out the the [documentation](https://regional-mom6.readthedocs.io/en/latest/) and browse through the [demos](https://regional-mom6.readthedocs.io/en/latest/demos.html).
+
+## Installation
+
+At the moment you can install the package via `pip` from
+GitHub. Before this, the binary `esmpy` dependency is required. This
+is easiest to install using Conda. To do so, first create a custom
+Conda environment, or activate an existing environment into which you
+want to install `esmpy` and `regional_mom6`. Then install `emspy`:
+
+```bash
+conda install -c conda-forge esmpy
+```
+
+Alternatively, it's possible to follow the [Installing ESMPy from
+Source](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/install.html#installing-esmpy-from-source)
+instructions to do this in a Conda-free way. With `esmpy` available, you can then install
+`regional_mom6` via pip. If your environment doesn't yet have pip, then `conda install pip` should do the job.
+
+```bash
+pip install git+https://github.com/COSIMA/regional-mom6.git
+```
+
+This will install the latest version of `regional_mom6` plus any required dependencies.
+`esmpy` won't be installed as a dependency and that's why need to install it separately.
+
+Alternatively, you can also install a particular tag or git commit using, e.g.,
+
+```bash
+pip install git+https://github.com/COSIMA/[email protected]
+```
+
+or
+
+```bash
+pip install git+https://github.com/COSIMA/regional-mom6.git@061b0ef80c7cbc04de0566df329c4ea472002f7e
+```

demos/model-forced.ipynb

@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Forcing with model output"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 19,
@@ -463,25 +470,23 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# What does this package do?\n",
+    "## What does this package do?\n",
     "\n",
     "Setting up a regional model in MOM6 is 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. \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. \n"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## What does this notebook do?\n",
     "\n",
-    "This notebook demonstrates how to set up a regional domain using the package. By the end you should have a running mom6 experiment on the domain of your choice. To make a stable test case:\n",
+    "This notebook demonstrates how to set up a regional domain using the package. By the end you should have a running MOM6 experiment on the domain of your choice. To make a stable test case:\n",
     "\n",
     "* Avoid any regions with ice\n",
     "* Avoid regions near the north pole\n",
@@ -496,11 +501,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 0: Your personal environment variables"
+    "## Step 0: Your personal environment variables"
    ]
   },
   {
@@ -514,11 +518,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 1: Choose our domain, define workspace paths\n",
+    "## Step 1: Choose our domain, define workspace paths\n",
     "\n",
     "To make sure that things are working I'd recommend starting with the default example defined below. If this runs ok, then change to a domain of your choice and hopefully it runs ok too! There's some troubleshooting you can do if not (check readme / readthedocs)\n",
     "\n",
@@ -559,17 +562,15 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 2: Prepare ocean forcing data\n",
+    "## Step 2: Prepare ocean forcing data\n",
     "\n",
-    "We need to cut out our ocean forcing. The pipeline expects an initial condition and one time-dependent segment per non-land boundary. Naming convention is \"east_unprocessed\" and \"ic_unprocessed\" for initial condition. The following provides an example for cutting out the necessary forcing files from an ocean model. It's hardcoded to pull data from a Repeat Year Forced ACCESS-OM2-01 database, but you should be able to recycle parts of the code to cut out data from a datase of your choice"
+    "We need to cut out our ocean forcing. The pipeline expects an initial condition and one time-dependent segment per non-land boundary. Naming convention is \"east_unprocessed\" and \"ic_unprocessed\" for initial condition. The following provides an example for cutting out the necessary forcing files from an ocean model. It's hardcoded to pull data from a Repeat Year Forced ACCESS-OM2-01 database, but you should be able to recycle parts of the code to cut out data from a dataset of your choice"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -890,11 +891,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 3: Make experiment object\n",
+    "## Step 3: Make experiment object\n",
     "This object keeps track of your domain basics, as well as generating the hgrid, vgrid and setting up the folder structures. \n",
     "\n",
     "After running you can have a look at your grids by calling `expt.hgrid` and `expt.vgrid`\n",
@@ -905,7 +905,7 @@
     "```\n",
     " shows you the vertical spacing profile.\n",
     "\n",
-    "## Modular workflow!\n",
+    "### Modular workflow!\n",
     "\n",
     "After constructing your expt object, if you don't like my lazy default hgrid and vgrid you can simply modify and overwrite them. However, you'll also need to save them to disk again as I've not automated this just yet. For example:\n",
     "\n",
@@ -950,11 +950,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 4: Set up bathymetry\n",
+    "## 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. After running this cell, your input directory will contain other topography - adjacent things like the ocean mosaic and mask table too. This defaults to a 10x10 layout which can be updated later."
    ]
@@ -1089,7 +1088,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -1127,15 +1125,14 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#  Step 5: Handle the ocean forcing - where the magic happens\n",
+    "##  Step 5: Handle the ocean forcing - where the magic happens\n",
     "\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, 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, 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",
     "\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. \n"
    ]
@@ -1183,11 +1180,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 6 (optional) Select number of processors \n",
+    "## Step 6 (optional): Select number of processors \n",
     "\n",
     "This is just a wrapper for check_mask FRE tool. Choose the number of processors in the X and Y directions respectively. Having run `.bathymetry()`, you already have one set up for 10x10 by default."
    ]
@@ -1202,11 +1198,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 7: Modify the default input directory to make a (hopefully) runnable configuration out of the box\n",
+    "## Step 7: Modify the default input directory to make a (hopefully) runnable configuration out of the box\n",
     "\n",
     "This cell just copies a default run directory and modifies it to match your configuration.\n",
     "\n"
@@ -1324,7 +1319,6 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -1343,11 +1337,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 9 and beyond: Fiddling, troubleshooting an fine tuning\n",
+    "## Step 9 and beyond: Fiddling, troubleshooting and fine tuning\n",
     "\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",