Fix tides on angled boundaries, consolidate regridded of velocity and tracers, add proper body tide parameters, add MOM6's angle calculation.

.github/workflows/testing.yml

@@ -18,7 +18,7 @@ jobs:
   testing:
     needs: formatting
     runs-on: ubuntu-latest
-    container: ghcr.io/cosima/regional-test-env:updated
+    container: ghcr.io/crocodile-cesm/crocodile_rm6_test_env:latest
     defaults:
       run:
         shell: bash -el {0}

demos/premade_run_directories/README.md

@@ -1,4 +1,4 @@
-## Premade Run Directories
+# 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.
 

demos/reanalysis-forced.ipynb

@@ -55,6 +55,17 @@
     "from dask.distributed import Client"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Currently, only the regional_mom6 module reports logging information to the info level, for more detailed output\n",
+    "# import logging\n",
+    "# logging.basicConfig(level=logging.INFO) \n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -191,7 +202,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "expt.get_glorys_rectangular(\n",
+    "expt.get_glorys(\n",
     "    raw_boundaries_path=glorys_path\n",
     ")"
    ]

docs/angle_calc.md

@@ -0,0 +1,45 @@
+# Rotation and angle calculation in RM6 using MOM6 Angle Calculation  
+This document explains the implementation of MOM6 angle calculation in RM6, which is the process by which RM6 calculates the angle of curved hgrids. 
+
+**Issue:** MOM6 doesn't actually use the user-provided "angle_dx" field in input hgrids, but internally calculates the angle. 
+
+**Solution:** To accomodate this fact, when we rotate our boundary conditions, we implemented MOM6 angle calculation in a file called "rotation.py", and adjusted functions where we regrid the boundary conditions.
+
+
+## MOM6 process of angle calculation (T-point only)
+1. Calculate pi/4rads / 180 degrees  = Gives a 1/4 conversion of degrees to radians. I.E. multiplying an angle in degrees by this gives the conversion to radians at 1/4 the value. 
+2. Figure out the longitudunal extent of our domain, or periodic range of longitudes. For global cases it is len_lon = 360, for our regional cases it is given by the hgrid.
+3. At each point on our hgrid, we find the q-point to the top left, bottom left, bottom right, top right. We adjust each of these longitudes to be in the range of len_lon around the point itself. (module_around_point)
+4. We then find the lon_scale, which is the "trigonometric scaling factor converting changes in longitude to equivalent distances in latitudes". Whatever that actually means is we add the latitude of all four of these points from part 3 and basically average it and convert to radians. We then take the cosine of it. As I understand it, it's a conversion of longitude to equivalent latitude distance. 
+5. Then we calculate the angle. This is a simple arctan2 so y/x. 
+    1. The "y" component is the addition of the difference between the diagonals in longitude (adjusted by modulo_around_point in step 3) multiplied by the lon_scale, which is our conversion to latitude.
+    2. The "x" component is the same addition of differences in latitude.
+    3. Thus, given the same units, we can call arctan to get the angle in degrees
+
+
+## Problem
+MOM6 only calculates the angle at t-points. For boundary rotation, we need the angle at the boundary, which is q/u/v points. Because we need the points to the left, right, top, and bottom of the point, this method won't work for the boundary.
+
+
+## Convert this method to boundary angles - 3 Options
+1. **GIVEN_ANGLE**: Don't calculate the angle and use the user-provided field in the hgrid called "angle_dx"
+2. **EXPAND_GRID**: Calculate another boundary row/column points around the hgrid using simple difference techniques. Use the new points to calculate the angle at the boundaries. This works because we can now access the four points needed to calculate the angle, where previously at boundaries we would be missing at least two. 
+
+
+## Code Description
+
+Most calculation code is implemented in the rotation.py script, and the functional uses are in regrid_velocity_tracers and regrid_tides functions in the segment class of RM6.
+
+
+### Calculation Code (rotation.py)
+1. **Rotational Method Definition**:  Rotational Methods are defined in the enum class "Rotational Method" in rotation.py.
+2. **MOM6 Angle Calculation**: The method is implemented in "mom6_angle_calculation_method" in rotation.py and the direct t-point angle calculation is "initialize_grid_rotation_angle". 
+3. **Fred's Pseudo Grid Expansion**: The method to add the additional boundary row/columns is referenced in "pseudo_hgrid" functions in rotation.py
+
+### Implementation Code (regional_mom6.py)
+Both regridding functions (regrid_velocity_tracers, regrid_tides) accept a parameter called "rotational_method" which takes the Enum class defining the rotational method.
+
+We then define each method with a bunch of if statements. Here are the processes:
+
+1. Given angle is the default method of accepting the hgrid's angle_dx
+2. Fred's method is the least code, and we simply swap out the hgrid angle with the generated one we calculate right where we do the rotation.

docs/api.rst

@@ -1,22 +1,45 @@
-===============
- API reference
-===============
+regional\_mom6 package
+======================
 
+Submodules
+----------
 
-+++++++++++++++++++
- ``regional_mom6``
-+++++++++++++++++++
+regional\_mom6.regional\_mom6 module
+------------------------------------
 
 .. automodule:: regional_mom6.regional_mom6
    :members:
    :undoc-members:
-   :private-members:
+   :show-inheritance:
 
+regional\_mom6.regridding module
+--------------------------------
 
-+++++++++++
- ``utils``
-+++++++++++
+.. automodule:: regional_mom6.regridding
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+regional\_mom6.rotation module
+------------------------------
+
+.. automodule:: regional_mom6.rotation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+regional\_mom6.utils module
+---------------------------
 
 .. automodule:: regional_mom6.utils
    :members:
    :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: regional_mom6
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/docker_image_dev.md

@@ -0,0 +1,35 @@
+# Docker Image & Github Testing (For contributors)
+
+RM6 uses a docker image in github actions for holding large data. It wasn't directly being used, but for downloading the curvilinear grid for testing, we are using it. This document is a list of helpful commands to work on it.
+
+The link to the image is here: 
+https://github.com/COSIMA/regional-mom6/pkgs/container/regional-test-env
+
+For local development of the image to add data to it for testing, first pull it. 
+```docker pull ghcr.io/cosima/regional-test-env:updated```
+
+Then to do testing of the image, we cd into our cloned version of RM6, and run this command. It mounts our code in the /workspace directory.:
+```docker run -it --rm \ -v $(pwd):/workspace \ -w /workspace \ ghcr.io/cosima/regional-test-env:updated \ /bin/bash```
+
+The -it flag is for shell access, and the workspace stuff is to get our local code in the container.
+You have to download conda, python, pip, and all that business to properly run the tests.
+
+Getting to adding the data, you should create a folder and add both the data you want to add and a file simple called "Dockerfile". In Dockerfile, we'll get the original image, then copy the data we need to the data folder.
+
+```
+# Use the base image
+FROM ghcr.io/cosima/regional-test-env:<tag>
+
+# Copy your local file into the /data directory in the container
+COPY <file> /data/<file>
+```
+
+Then, we need to build the image, tag it, and push it
+
+```
+docker build -t my-custom-image . # IN THE DIRECTORY WITH THE DOCKERFILE
+docker tag my-custom-image ghcr.io/cosima/regional-test-env:<new_tag>
+docker push ghcr.io/cosima/regional-test-env:<new_tag>
+```
+
+

docs/index.rst

@@ -91,8 +91,11 @@ The bibtex entry for the paper is:
    installation
    demos
    mom6-file-structure-primer
+   rm6_workflow
+   angle_calc
    api
    contributing
+   docker_image_dev
 
 
 Indices and tables

docs/mom6-file-structure-primer.md

@@ -106,3 +106,9 @@ These files can be big, so it is usually helpful to store them somewhere without
   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).
+
+* `forcing/{tz/tu}_segment**`
+  The boundary tidal 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).

docs/rm6_workflow.md

@@ -0,0 +1,32 @@
+# Regional MOM6 Workflow
+
+Regional MOM6(RM6) sets up all the data and files for running a basic regional case of MOM6.
+
+It includes:
+
+1. Run Files like MOM_override, MOM_input, diag_table
+2. BC File like velocity, tracers, tides
+3. Basic input files like hgrid & bathymetry.
+4. Initial Condition files
+
+
+To set up a case with all the files, RM6 has its own way of grabbing and organizing files for the user.
+
+RM6 organizes all files into two directories, a "input" directory, and a "run" directory. The input directory includes all of the data we need for our regional case. The run directory includes all of the parameters and outputs (diags) we want for our model. Please see the structure primer document for more information.
+
+The other folders are the data directories. RM6 needs the user to collect the initial condition & boundary condition data and put them into a folder(s). 
+
+Therefore, to start for the user to use RM6, they should have two (empty or not) directories for the input and run files, as well as directories for their input data. 
+
+Depending on the computer used (NCAR-Derecho/Casper doesn't need this), the user may also need to provide a path to FRE_tools. 
+
+To create all these files, RM6 using a class called "Experiment" to hold all of the parameters and functions. Users can follow a few quick steps to setup their cases:
+1. Initalize the experiment object with all the directories and parameters wanted. The initalization can also create the hgrid and vertical coordinate or accept two files called "hgrid.nc" and "vcoord.nc" in the input directory.
+2. Call different "setup..." functions to setup all the data needed for the case (bathymetry, initial condition, velocity, tracers, tides).
+3. Finally, call "setup_run_directory" to setup the run files like MOM_override for their cases.
+4. Based on how MOM6 is setup on the computer, there are follow-up steps unique to each situation. RM6 provides all of what the user needs to run MOM6.
+
+
+There are a few convience functions to help support the process.
+1. Very light read and write config file functions to easily save experiments
+2. A change_MOM_parameter function to easily adjust MOM parameter values from python.

pyproject.toml

@@ -17,6 +17,8 @@ dependencies = [
   "xarray <= 2024.7.0",
   "xesmf >= 0.8.4",
   "f90nml >= 1.4.1",
+  "aiohttp >= 3.9.5,<3.10.0",
+  "copernicusmarine >= 1.2.4,<1.3.0"
 ]
 
 [build-system]