Merge remote-tracking branch 'origin/main' into bug/repro

.github/workflows/NWA12-ci.yaml

@@ -23,11 +23,11 @@ jobs:
         path: ${{ github.run_id }}/NWA12_CHECK
         submodules: recursive
 
-    - uses: jitterbit/get-changed-files@v1
-      id: abc
-      with:
-        format: space-delimited
-        token: ${{ secrets.GITHUB_TOKEN }}     
+#    - uses: jitterbit/get-changed-files@v1
+#      id: abc
+#      with:
+#        format: space-delimited
+#        token: ${{ secrets.GITHUB_TOKEN }}     
 
     - name: Build MOM6SIS2
       run: |

.github/workflows/mom6_cobalt_1D.yaml

@@ -15,15 +15,15 @@ jobs:
 
     steps:        
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         submodules: recursive
 
-    - uses: jitterbit/get-changed-files@v1
-      id: abc
-      with:
-        format: space-delimited
-        token: ${{ secrets.GITHUB_TOKEN }}        
+#    - uses: jitterbit/get-changed-files@v1
+#      id: abc
+#      with:
+#        format: space-delimited
+#        token: ${{ secrets.GITHUB_TOKEN }}        
 
 #    - name: Login to DockerHub Registry
 #      run: echo ${{ secrets.DOCKERHUB_PASSWORD }} | docker login -u ${{ secrets.DOCKERHUB_USERNAME }} --password-stdin

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

README.md

@@ -1,3 +1,5 @@
+[![doc](https://readthedocs.org/projects/cefi-regional-mom6/badge/?version=latest)](https://cefi-regional-mom6.readthedocs.io/en/latest/?badge=latest)
+
 # CEFI-regional-MOM6
 NOAA is embarking on an ambitious effort, the Climate, Ecosystems and Fisheries Initiative ([CEFI](https://www.fisheries.noaa.gov/topic/climate-change/climate,-ecosystems,-and-fisheries)), to develop and deploy a nation-wide ocean modeling, prediction, and decision support system to meet the challenge of coastal ecosystem management in a changing climate. 
 
@@ -6,6 +8,8 @@ As described in the link above, CEFI will integrate expertise and capabilities a
 This repository contains pre/post-processing tools and CEFI regional-MOM6 configurations for running regional-MOM6 OBGC simulations.
 Users are welcome to use the [discussions board](https://github.com/NOAA-GFDL/CEFI-regional-MOM6/discussions) to ask questions related to the model or the tools.
 
+Documentation (in progress) is available [here](https://cefi-regional-mom6.readthedocs.io/en/latest/index.html)
+
 ## What files are what
 
 | File/directory    | Purpose |
@@ -18,9 +22,10 @@ Users are welcome to use the [discussions board](https://github.com/NOAA-GFDL/CE
 | ```exps/```       | Contains 1D mom6-cobalt exmaple and NWA12 configurtions. See [exps/README.md](exps/README.md) |
 | ```tools/```      | Contains tools that can be used to generate initial conditions (ICs), boundary conditions (BCs), and other required inputs for MOM6-SIS2-cobalt model runs.  See [tools/README.md](tools/README.md) |
 | ```xmls/```       | Contains FRE xml files designed for running the CEFI-regional-MOM6 workflow on NOAA Gaea C5. See [xmls/README.md](xmls/README.md) |
+| ```docs/```       | Contains release notes, documentation, and [User’s Guide](https://cefi-regional-mom6.readthedocs.io/en/latest/index.html) |
 
 ## Quick Start Guide
-To learn how to compile/build MOM6-SIS2-cobalt and run an example regional test case, refer to [builds/README](builds/README) and [exps/README.md](exps/README.md).
+To learn how to compile/build MOM6-SIS2-cobalt and run an example regional test case, refer to [builds/README](builds/README.md) and [exps/README.md](exps/README.md).
 Users who are interested in model inputs generation can check [tools/README.md](tools/README.md). 
 
 ## Disclaimer

builds/README.md

@@ -1,11 +1,63 @@
-This tool can be use to build the executable for the model.
-E.g., on machine gaea for platform c5 with intel23 compiler:
+This tool can be use to build the executable for the model. If you have Gaea C5 access, try the following command directly. Otherwise please check [Build CEFI-regional-MOM6](#build-cefi-regional-mom6) for detailed instructions.
 
+On machine gaea for platform c5 with intel23 compiler:
+```console
 ./linux-build.bash -m gaea -p ncrc5.intel23 -t prod -f mom6sis2
-
+```
 This assumes that the files build/gaea/ncrc5.intel23.env and build/gaea/ncrc5.intel23.mk exist.
 -  build/gaea/ncrc5.intel23.env contains all the necessary environment variables and modules
 that must be loaded before a build / run on that machine
 -  build/gaea/ncrc5.intel23.mk  contains the compile instructions for the particular compiler and machine
 
+# Quick Start Guide
+
+**Conda warning**: before you install anything or try to build the model, make sure to deactivate your `conda` environment because it could interfere with brew and the model build process.
+conda deactivate.
+
+## Prerequisites
+**For PC users:** 
+- Install WSL (Windows Subsystem for Ubuntu and Linux):  [link](https://learn.microsoft.com/en-us/windows/wsl/install) and install the following softwares:
+```console
+sudo apt update
+sudo apt install make gfortran git tcsh netcdf-bin libnetcdf-dev libnetcdff-dev openmpi-bin libopenmpi-dev
+```
+- Container approach: Docker container is available for Window10 or 11: [link]([https://docs.docker.com/desktop/install/windows-install/#:~:text=To%20run%20Windows%20containers%2C%20you,you%20to%20run%20Linux%20containers.&text=Docker%20only%20supports%20Docker%20Desktop,still%20within%20Microsoft's%20servicing%20timeline%20](https://docs.docker.com/desktop/install/windows-install/#:~:text=To%20run%20Windows%20containers%2C%20you,you%20to%20run%20Linux%20containers.&text=Docker%20only%20supports%20Docker%20Desktop,still%20within%20Microsoft's%20servicing%20timeline%20.)https://docs.docker.com/desktop/install/windows-install/#:~:text=To%20run%20Windows%20containers%2C%20you,you%20to%20run%20Linux%20containers.&text=Docker%20only%20supports%20Docker%20Desktop,still%20within%20Microsoft's%20servicing%20timeline%20.)
+  Then follow the instruction [here](../ci/docker/README.md) to build the model.
+
+**For MacOS users:** 
+- Install HomeBrew: [link](https://brew.sh/) and install the following software from terminal:
+```console
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+brew install make
+brew install gfortran
+brew install openmpi
+brew install netcdf
+brew install netcdf-fortran
+brew install wget
+```
+
+## Build CEFI-regional-MOM6:
+- After `git clone https://github.com/NOAA-GFDL/CEFI-regional-MOM6.git --recursive` navigate to the `builds` directory: `cd CEFI-regional-MOM6\builds`
+- mkdir `YOUR_MACHINE_DIRECTORY`: This should be the name of your system, e.g, mac-m1. Then `cd YOUR_MACHINE_DIRECTORY`
+- you will need two files: `NAME_OF_YOUR_mk_FILE.env` and `NAME_OF_YOUR_mk_FILE.mk` in this folder (e.g. gnu.env and gnu.mk or somthing similiar).
+- The `NAME_OF_YOUR_mk_FILE.env` file is mainly used for the HPC system to allow you to load necessary software to build the model. In most cases, if you already have gfortran, mpi (openmpi or mpich), and netcdf installed on your system, the `***.env` file can be left blank.
+- The `NAME_OF_YOUR_mk_FILE.mk` file may be different depends on your system configurations (e.g. Intel v.s. GNU compilers). We already have a few examples within the `builds` folder. Users can also find more general templates [here](https://github.com/NOAA-GFDL/mkmf/tree/af34a3f5845c5781101567e043e0dd3d93ff4145/templates). Below are some recommended templates:
+
+| Platform          | Template |
+| --------------    | ------- |
+| ```gaea```        | ncrc5-intel-classic.mk |
+| ```Ubuntu```      | linux-ubuntu-trusty-gnu.mk |
+| ```MacOS```       | osx-gnu.mk |
+
+- Use the following command to build the model (Make sure to use correct names that are consistent with both your machine folder and your mk/env files.):
+```console
+./linux-build.bash -m YOUR_MACHINE_DIRECTORY -p NAME_OF_YOUR_mk_FILE -t repro -f mom6sis2
+```
+- If the build completes successfully, you should be able to find the executable here: `builds/build/YOUR_MACHINE_DIRECTORY-NAME_OF_YOUR_mk_FILE/ocean_ice/repro/MOM6SIS2`
 
+## Test run: 1-D MOM6-COBALT
+- To test your `MOM6SIS2`, first navigate to the `exps` folder: `cd ../exps`
+- Download the model input files: `wget https://gfdl-med.s3.amazonaws.com/OceanBGC_dataset/1d_datasets.tar.gz && tar -zxvf 1d_datasets.tar.gz`
+- navigate to the 1-D example: `cd OM4.single_column.COBALT`
+- USe the following command to run the 1-D example: `mpirun -np 1 ../../builds/build/YOUR_MACHINE_DIRECTORY-NAME_OF_YOUR_mk_FILE/ocean_ice/repro/MOM6SIS2`
+>>>>>>> origin/main

builds/linux-build.bash

@@ -1,6 +1,6 @@
 #!/bin/bash -x                                     
 machine_name="gaea" 
-platform="intel18"
+platform="ncrc5.intel23"
 #machine_name="tiger" 
 #platform="intel18"
 #machine_name="googcp" 
@@ -17,8 +17,8 @@ platform="intel18"
 #platform     = "intel16"
 #machine_name="lscsky50"
 #platform="intel19up2_avx1" #"intel18_avx1" # "intel18up2_avx1" 
-target="prod" #"debug-openmp"       
-flavor="mom6solo" #"mom6solo
+target="repro" #"debug-openmp"       
+flavor="mom6sis2" #"mom6solo
 
 usage()
 {

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,40 @@
+Steps to build and use the Sphinx documentation tool:
+
+1) Get Sphinx, sphinxcontrib-bibtex, and the RTD theme installed on your desktop from
+    http://www.sphinx-doc.org/en/master/usage/installation.html
+    https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation
+    https://pypi.org/project/sphinx-rtd-theme/
+
+    For example:
+    ``` 
+    pip install sphinx
+    pip install sphinxcontrib-bibtex
+    pip install sphinx-rtd-theme
+    ```   
+
+    One approach that has worked to resolve "Module Not Found" errors for users with MacPorts package manager: 
+    ```
+    $ sudo port install py-six  # may not be necessary
+    $ sudo port install py310-sphinxcontrib-bibtex
+    $ sudo port select --set sphinx py310-sphinx
+    $ sudo port install py310-sphinx_rtd_theme
+    ```
+
+    py310 can be replaced with the user's version of Python (e.g., py39) 
+
+To build html:
+
+```
+$ cd CEFI-regional-MOM6/docs
+$ make clean && sphinx-build -b html source build
+```
+
+The "make html" command can often be used in place of the previous command.
+
+Sphinx uses Latex to export the documentation as a PDF file.  To build pdf:
+
+```
+make latexpdf
+```
+
+It will generate a PDF file in ./build/latex/<sphinx-project-name>.pdf

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinxcontrib-bibtex
+sphinx_rtd_theme
+docutils==0.16