Fix tides on angled boundaries, consolidate regridded of velocity and…

… tracers, add proper body tide parameters, add MOM6's angle calculation. (#33)

* Add GFDL Rotation Code and minor tides debugging in setup_run_directory

The GFDL rotation code was commented out🙈

* Black

* Actual Angle Change

* Minor Clean

* Add First Regridding Option

* More tidal changes

* Change default tides to use all constituents in TPXO allowed in MOM6

* Fix Tests

* Start of Angle Calc

* Blacl

* Rand

* Clean up testing  (#37)

* Remove extra directories created

* Black

* Clean up created dirs

* Rand

* Keith Method Step 1, add t-point boundaries to coords()

* Start implementing alternative angles approaches...

* Set up rotational method framework

* Add h, t, and change default mom6_angle_calc to regional

* black

* Fred Angle Calc

* Black

* Black 2

* Keith Method

* Tidal Rotational Methods Completed

* Finish rotational methods for velocity_tracers

* Combine the grid_rotation_calc for fred_pseudo and mom6 general (keiths)

* Move rotation/angle functions to a different file

* Doesn't make sense to use rot method in expt because the regrid methods are in segment right now. Something to discuss and then add

* Clean up the keith method to use the regridding func add_secondary_dimension

* Add angle_calc to docs

* Main Page Link for now...

* Start testing setup

* Change func name for consistency

* Minor Commenting

* Minor Commenting

* Black

* Redo Auto Docs

* Start of testing

* Test until curved grid generation comes in

* Bug

* Test_Rotation Changes

* Adjust Docker Path

* Testing Framework Trial 1

* Docker Docs

* Test Cleaning

* Change name of docker docs

* Adjust docker image to crocodile one

* Step 1: Setup Framework Tidal Regridding Nans/LandMask BugFix

* Finish setting up masking framework

* Clean up process of masking

* Regridding Testing except for the mask functions

* First round testing w/o mask tests

* First Round Testing Completed

* Minor Clean

* MOM6 Angle Calculation (#34)

* Start of Angle Calc

* Blacl

* Rand

* Rand

* Keith Method Step 1, add t-point boundaries to coords()

* Start implementing alternative angles approaches...

* Set up rotational method framework

* Add h, t, and change default mom6_angle_calc to regional

* black

* Fred Angle Calc

* Black

* Black 2

* Keith Method

* Tidal Rotational Methods Completed

* Finish rotational methods for velocity_tracers

* Combine the grid_rotation_calc for fred_pseudo and mom6 general (keiths)

* Move rotation/angle functions to a different file

* Doesn't make sense to use rot method in expt because the regrid methods are in segment right now. Something to discuss and then add

* Clean up the keith method to use the regridding func add_secondary_dimension

* Add angle_calc to docs

* Main Page Link for now...

* Start testing setup

* Change func name for consistency

* Minor Commenting

* Minor Commenting

* Black

* Redo Auto Docs

* Start of testing

* Test until curved grid generation comes in

* Bug

* Test_Rotation Changes

* Adjust Docker Path

* Testing Framework Trial 1

* Docker Docs

* Test Cleaning

* Change name of docker docs

* Adjust docker image to crocodile one

* Step 1: Setup Framework Tidal Regridding Nans/LandMask BugFix

* Finish setting up masking framework

* Revert "Finish setting up masking framework"

This reverts commit 9287030.

* Revert "Step 1: Setup Framework Tidal Regridding Nans/LandMask BugFix"

This reverts commit a2b961a.

* respond to alper comments

* Docs changes

* Seg Fault Issue Pt1

* Disable threading

* Just single threading

* Clean up testing

* Remove Single Threading

* Add back single threading

* Spelling Mistake

* Zero Out Attempt

* Black + Add Mask to Regrid_vt

* Zero Out Corner + 3 Cell

* Update Land Mask Tests

* Fix Bathy NTiles Issue

* Minor Cleaning + Variable Renaming

* minor changes ahead of visualCaseGen integration in CrocoDash:

- correct the first arg of a classmethod (from self to cls).
- introduce optional write_to_file arg in setup_bathymetry.
- introduce optional bathymetry obj arg in tidy_bathymetry.

* Mirro GFDL NWA12-Cobalt a bit more and add diag table date adjustment

* Black

* Add aiohttp and copernicusmarine dependencies

* add hgrid_path and vgrid_path args to __init__ to allow non-standard filenames. Similarly, add thickesses arg to _make_vgrid.

* black reformatting

* Update Initial Condition + Alternate Rotation Function

* Rename get_glorys_rect to get_glorys

* Move RM6 to logging over print statements, but still report regional_mom6 to stdout

* Formatting

* Fix logging bug

* Revert RM6 Logging

* Formatting

* Alper Review Comments Pt1

* Relative Imports

* Revert "Relative Imports"

This reverts commit 15d8d36.

* Check if the ESMF warning is the issue in the tests failure

* Add Rotational Methods function

* Small Adj to Docs'

---------

Co-authored-by: alperaltuntas <alperaltuntas@gmail.com>

.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

@@ -44,17 +44,30 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
+    "import warnings\n",
+    "warnings.filterwarnings(\"ignore\")\n",
     "import regional_mom6 as rmom6\n",
     "\n",
     "import os\n",
     "from pathlib import Path\n",
     "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 +204,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "expt.get_glorys_rectangular(\n",
+    "expt.get_glorys(\n",
     "    raw_boundaries_path=glorys_path\n",
     ")"
    ]
@@ -428,7 +441,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "crr_dev",
+   "display_name": "CrocoDash",
    "language": "python",
    "name": "python3"
   },
@@ -442,7 +455,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.7"
+   "version": "3.12.8"
   }
  },
  "nbformat": 4,

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. The EXPAND_GRID 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.