Initial Documentation Draft for CEFI-regional-MOM6 (#6)

* This PR adds an online documentation so beginners can learn the basics of the CEFI-regional-MOM6 (e.g. compile/build, brief descriptions of model inputs and outputs, how to run an example experiment) --------- Co-authored-by: Theresa Morrison <[email protected]>
NOAA-GFDL · Mar 1, 2024 · 521a54a · 521a54a
1 parent cd9dc68
commit 521a54a
Show file tree

Hide file tree

Showing 18 changed files with 1,212 additions and 0 deletions.
diff --git a/.readthedocs.yaml b/.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
diff --git a/README.md b/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,6 +22,7 @@ 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.md) and [exps/README.md](exps/README.md).

diff --git a/docs/Makefile b/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)
diff --git a/docs/README.md b/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
diff --git a/docs/make.bat b/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
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+sphinxcontrib-bibtex
+sphinx_rtd_theme
+docutils==0.16
diff --git a/docs/source/BuildMOM6.rst b/docs/source/BuildMOM6.rst
@@ -0,0 +1,149 @@
+.. _BuildMOM6:
+
+====================================
+Build the MOM6-SIS2-COBALT
+====================================
+
+To build the MOM6-SIS2-COBALT, users will complete the following steps:
+
+   #. :ref:`Install prerequisites <StackInfo>`
+   #. :ref:`Clone the CEFI-regional-MOM6 from GitHub <DownloadMOM6>`
+   #. :ref:`Set up the build environment and build the executables <BuildExecutables>`
+
+.. _StackInfo:
+
+Install the Prerequisite Softwares 
+==========================================
+
+.. note::
+
+   **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.
+
+Users on any sufficiently up-to-date machine with a UNIX-based operating system should be able to install the prerequisite software and build the MOM6-SIS2-COBALT. Users can follow the commands below to install the prerequisite software with admin access or ask their HPC helpdesks for any issues related to the installation of the prerequisite software.
+
+.. code-block:: console
+
+   # Linux system such as Ubuntu 
+   sudo apt update
+   sudo apt install make gfortran git git-lfs tcsh netcdf-bin libnetcdf-dev libnetcdff-dev openmpi-bin libopenmpi-dev
+
+   # MacOS, install Homebrew from terminal and install the prerequisite software
+   /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
+   brew install git
+   brew install git-lfs
+
+For **Windows users**, we recommend installing `WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`__ (Windows Subsystem for Ubuntu and Linux), and following the above steps to install the prerequisite software. Alternatively users can opt for the Docker container approach. See :ref:`Container-Based Quick Start Guide <QuickstartC>` for more details.
+
+After completing installation, continue to the :ref:`next section <DownloadMOM6>` to download the CEFI-regional-MOM6. 
+
+.. _DownloadMOM6:
+
+Download the CEFI-regional-MOM6 Code
+======================================
+The CEFI-regional-MOM6 source code is publicly available on GitHub. To download the code (including submodules), clone the **main** branch of the repository:
+
+.. code-block:: console
+
+   git clone https://github.com/NOAA-GFDL/CEFI-regional-MOM6.git --recursive 
+
+The cloned repository contains files and sub-directories shown in :numref:`Table %s <FilesAndSubDirs>`. 
+
+.. _FilesAndSubDirs:
+
+.. list-table:: Files and Subdirectories of the *CEFI-regional-MOM6* Repository
+   :widths: 20 50
+   :header-rows: 1
+
+   * - File/Directory Name
+     - Description
+   * - LICENSE.md 
+     - A copy of the Gnu lesser general public license, version 3
+   * - README.md
+     - This file with basic pointers to more information
+   * - src
+     - Contains the source code for MOM6-SIS2-COBALT model 
+   * - builds
+     - Contains build script to build MOM6-SIS2-COBALT
+   * - diagnostics
+     - Contains scripts that can be utilized for analyzing model results after postprocessing
+   * - exps
+     - Contains 1D MOM6-SIS2-COBALT example and other CEFI regional configurations
+   * - tools
+     - Contains preprocessing scripts that can be used to generate model input files
+   * - xmls
+     - Contains FRE xml files designed for running the CEFI-regional-MOM6 workflow on Gaea   
+   * - docs
+     - Contains release notes, documentation, and User's Guide
+
+.. _BuildExecutables:
+
+Set Up the Environment and Build the Executables
+=================================================== 
+
+After download the source code, users can navigate to the ``builds`` directory and create a folder for your machine configurations:
+
+.. code-block:: console
+
+   cd CEFI-regional-MOM6/builds
+   mkdir YOUR_MACHINE_DIRECTORY
+   cd YOUR_MACHINE_DIRECTORY
+
+The ``YOUR_MACHINE_DIRECTORY`` should contain two files: ``NAME_OF_YOUR_mk_FILE.env`` and ``NAME_OF_YOUR_mk_FILE.mk`` (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 ``module load`` necessary software to build the model. In most cases, if you already have gfortran (or intel compiler), mpi (openmpi or mpich), and netcdf installed on your system, the ``NAME_OF_YOUR_mk_FILE.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:
+
+.. _mkmftempDescription:
+
+.. table:: Recommended mkmf templates
+
+   +------------------------+---------------------------------------------------------------------------------+
+   | **Platform/Compiler**  | **Template**                                                                    |
+   +========================+=================================================================================+
+   | gaea (Intel)           | mkmf/templates/ncrc5-intel-classic.mk                                           |
+   +------------------------+---------------------------------------------------------------------------------+
+   | MacOS (GNU)            | CEFI-regional-MOM6/builds/MacOS/osx-gnu.mk                                      |
+   +------------------------+---------------------------------------------------------------------------------+
+   | Ubuntu (GNU)           | mkmf/templates/linux-ubuntu-trusty-gnu.mk                                       |
+   +------------------------+---------------------------------------------------------------------------------+
+
+Once the two files are created, 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):  
+
+.. code-block:: console
+
+   cd CEFI-regional-MOM6/builds
+   ./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``  
+
+Run an Experiment
+=====================
+
+To test your ``MOM6SIS2``, first navigate to the ``exps`` folder: 
+
+.. code-block:: console
+
+   cd ../exps
+
+Download the model input files:
+
+.. code-block:: console
+
+   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:
+
+.. code-block:: console
+
+   cd OM4.single_column.COBALT
+
+Use the following command to run the 1-D example:    
+
+.. code-block:: console
+ 
+   mpirun -np 1 ../../builds/build/YOUR_MACHINE_DIRECTORY-NAME_OF_YOUR_mk_FILE/ocean_ice/repro/MOM6SIS2
diff --git a/docs/source/ContainerQuickstart.rst b/docs/source/ContainerQuickstart.rst
@@ -0,0 +1,75 @@
+.. _QuickstartC:
+
+====================================
+Container-Based Quick Start Guide
+====================================
+
+This Container-Based Quick Start Guide will help users build and run the 1D case for the MOM6-SIS2-COBALT System using a `Singularity/Apptainer <https://apptainer.org/docs/user/1.2/introduction.html>`__ container. The :term:`container` approach provides a uniform enviroment in which to build and run the MOM6-SIS2-COBALT. Normally, the details of building and running the MOM6-COBALT vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPIs <MPI>`, and package versions available. Installation via container reduces this variability and allows for a smoother MOM6-SIS2-COBALT build experience. 
+
+The basic "1D" case described here builds a MOM6-COBALT for the Bermuda Atlantic Time-series Study (BATS) with OM4 single column configuration as well as COBALTV3.0.
+
+Prerequisites 
+-------------------
+
+Users must have either Docker (recommended for personal Windows/macOS systems) or Singularity/Apptainer (recommended for users working on Linux, NOAA Cloud, or HPC systems).
+
+Install Docker on Windows/macOS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To build and run the MOM6-SIS2-COBALT using a Docker container, first install the software according to the `Docker Installation Guide for Windows <https://docs.docker.com/desktop/install/windows-install/>`__ or `Docker Installation Guide for macOS <https://docs.docker.com/desktop/install/mac-install/>`__. 
+
+Install Singularity/Apptainer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   As of November 2021, the Linux-supported version of Singularity has been `renamed <https://apptainer.org/news/community-announcement-20211130/>`__ to *Apptainer*. Apptainer has maintained compatibility with Singularity, so ``singularity`` commands should work with either Singularity or Apptainer (see compatibility details `here <https://apptainer.org/docs/user/1.2/introduction.html>`__.)
+
+To build and run the MOM6-COBALT using a Singularity/Apptainer container, first install the software according to the `Apptainer Installation Guide <https://apptainer.org/docs/admin/1.2/installation.html>`__. This will include the installation of all dependencies.
+
+Build and run 1-D example using Docker 
+-----------------------------------------
+User can follow the following steps to build and run MOM6-SIS2-COBALT 1-D case within a Docker container.
+
+.. code-block::
+
+   #Assume user is under $HOME 
+   docker pull clouden90/1d_mom6_cobalt:base #This will pull docker image to your local machine
+   git clone https://github.com/NOAA-GFDL/CEFI-regional-MOM6.git --recursive #git clone CEFI-regional-MOM6 repo
+   cd $HOME/CEFI-regional-MOM6/exps
+   wget https://gfdl-med.s3.amazonaws.com/OceanBGC_dataset/1d_datasets.tar.gz && tar -zxvf 1d_datasets.tar.gz && rm -rf 1d_datasets.tar.gz
+   cd $HOME
+   docker run --rm -v $HOME:/work -it clouden90/1d_mom6_cobalt:v0.1 bash --login # run docker container interactively
+   cd /work/CEFI-regional-MOM6/builds
+   ./linux-build.bash -m docker -p linux-gnu -t repro -f mom6sis2 #build MOM6-SIS2-COBALT
+   cd /work/CEFI-regional-MOM6/exps
+   cd OM4.single_column.COBALT
+   mpirun -np 1 ../../builds/build/docker-linux-gnu/ocean_ice/repro/MOM6SIS2
+
+
+Build and run 1-D example using Singularity/Apptainer container
+-----------------------------------------
+For users working on systems with limited disk space in their ``/home`` directory, it is recommended to set the ``SINGULARITY_CACHEDIR`` and ``SINGULARITY_TMPDIR`` environment variables to point to a location with adequate disk space. For example:
+
+.. code-block:: 
+
+   export SINGULARITY_CACHEDIR=/absolute/path/to/writable/directory/cache
+   export SINGULARITY_TMPDIR=/absolute/path/to/writable/directory/tmp
+
+where ``/absolute/path/to/writable/directory/`` refers to a writable directory (usually a project or user directory within ``/lustre``, ``/work``, ``/scratch``, or ``/glade`` on NOAA RDHPC systems). If the ``cache`` and ``tmp`` directories do not exist already, they must be created with a ``mkdir`` command.
+
+Then User can follow the following steps to build and run MOM6-SIS2-COBALT 1-D case within a Singularity/Apptainer container.
+.. code-block::
+
+   #Assume user is under $HOME 
+   cd $HOME 
+   singularity pull 1d_mom6_cobalt.sif docker://clouden90/1d_mom6_cobalt:base #pull docker image and convert to sif
+   git clone https://github.com/NOAA-GFDL/CEFI-regional-MOM6.git --recursive #git clone CEFI-regional-MOM6 repo 
+   cd $HOME/CEFI-regional-MOM6/exps
+   wget https://gfdl-med.s3.amazonaws.com/OceanBGC_dataset/1d_datasets.tar.gz && tar -zxvf 1d_datasets.tar.gz && rm -rf 1d_datasets.tar.gz
+   cd $HOME 
+   singularity shell -B $HOME:/work -e $HOME/1d_mom6_cobalt.sif # start singularity/apptainer container interactively
+   cd /work/CEFI-regional-MOM6/builds
+   ./linux-build.bash -m docker -p linux-gnu -t repro -f mom6sis2 #build MOM6-SIS2-COBALT
+   cd /work/CEFI-regional-MOM6/exps
+   cd OM4.single_column.COBALT
+   mpirun -np 1 ../../builds/build/docker-linux-gnu/ocean_ice/repro/MOM6SIS2