MITgcm MITgcm/​doc/​getting_started/​getting_started.rst	Source navigation Diff markup Identifier search General search
	Version: master Revert   Change

Warning, /doc/getting_started/getting_started.rst is written in an unsupported language. File is not indexed.

69e7157c80 Jeff* .. _chap_getting_started:
                 
                 Getting Started with MITgcm
                 ***************************
                 
                 This chapter is divided into two main parts. The first part, which is
                 covered in sections :numref:`whereToFindInfo` through
31584ea246 Jeff* :numref:`run_the_model`, contains information about how to download,
                 build and run MITgcm.
69e7157c80 Jeff* We believe the best way to familiarize yourself with the
af61fa61c7 Jeff* model is to run one of the tutorial examples provided in the MITgcm repository
                 (see :numref:`chap_modelExamples`), so would suggest newer MITgcm users
516b08a580 jm-c  jump there following a read-through of the first part of this chapter.
69e7157c80 Jeff* Information is also provided
ba0b047096 Mart* in this chapter on how to customize the code
                 when you are ready to try implementing
                 the configuration you have in mind, in the second
                 part (:numref:`customize_model`).
                 The code and algorithm are described more fully in
                 :numref:`discret_algorithm` and
516b08a580 jm-c  :numref:`sarch` and chapters thereafter.
69e7157c80 Jeff* 
af61fa61c7 Jeff* In this chapter and others (e.g., chapter :ref:`chap_contributing`),
                 for arguments where the user is expected to replace the text
ba0b047096 Mart* with a user-chosen name, userid, etc., our convention
                 is to show these as upper-case
af61fa61c7 Jeff* text surrounded by ``« »``, such as ``«USER_MUST_REPLACE_TEXT_HERE»``.
                 The ``«`` and ``»`` characters are **NOT** typed when  the text is replaced.
                 
69e7157c80 Jeff* .. _whereToFindInfo:
                 
                 Where to find information
                 =========================
                 
                 There is a web-archived support mailing list for the model that you can
                 email at MITgcm-support@mitgcm.org once you have subscribed.
                 
31584ea246 Jeff* To sign up (subscribe) for the mailing list (highly recommended),
                 click `here <http://mailman.mitgcm.org/mailman/listinfo/mitgcm-support/>`__
69e7157c80 Jeff* 
31584ea246 Jeff* To browse through the support archive,
                 click `here <http://mailman.mitgcm.org/pipermail/mitgcm-support/>`__
69e7157c80 Jeff* 
                 Obtaining the code
                 ==================
                 
ba0b047096 Mart* The MITgcm code and documentation are under
                 continuous development and we generally
                 recommend that one downloads the latest version of the code.
                 You will need to decide if you want to work in a “git-aware”
                 environment (`Method 1`_) or with a one-time “stagnant” download (`Method 2`_).
                 We generally recommend method 1, as it is more
31584ea246 Jeff* flexible and allows your version of the code to be regularly updated as MITgcm
ba0b047096 Mart* developers check in bug fixes and new features. However, this typically
                 requires at minimum a rudimentary understanding of git in
                 order to make it worth one’s while.
69e7157c80 Jeff* 
ba0b047096 Mart* Periodically we release an official checkpoint
                 (or “tag”). We recommend one download
31584ea246 Jeff* the latest code, unless there are reasons for obtaining a specific checkpoint
ba0b047096 Mart* (e.g. duplicating older results, collaborating with
                 someone using an older release, etc.)
69e7157c80 Jeff* 
                 .. _git-aware_download:
                 
                 Method 1
                 --------
                 
                 This section describes how to download git-aware copies of the repository.
516b08a580 jm-c  In a terminal window, cd to the directory where you want your code to reside.
69e7157c80 Jeff* Type:
                 
                 ::
                 
                     % git clone https://github.com/MITgcm/MITgcm.git
                 
31584ea246 Jeff* This will download the latest available code. If you now want to revert this
                 code to a specific checkpoint release, first ``cd`` into the MITgcm directory
ba0b047096 Mart* you just downloaded, then type ``git checkout checkpoint«XXX»``
                 where ``«XXX»`` is the checkpoint version.
69e7157c80 Jeff* 
31584ea246 Jeff* Alternatively, if you prefer to use ssh keys (say for example, you have
                 a firewall which won’t allow a https download), type:
69e7157c80 Jeff* 
                 ::
                 
                     % git clone git@github.com:MITgcm/MITgcm.git
                 
31584ea246 Jeff* You will need a GitHub account for this, and will have to generate a ssh
516b08a580 jm-c  key though your GitHub account user settings.
69e7157c80 Jeff* 
31584ea246 Jeff* The fully git-aware download is over several hundred MB, which is considerable
                 if one has limited internet download speed. In comparison, the one-time
83cdbd2346 Jeff* download zip file (`Method 2`_, below) is order 100 MB. However, one can
31584ea246 Jeff* obtain a truncated, yet still git-aware copy of the current code by adding
                 the option ``--depth=1`` to the git clone command above; all files will be
                 present, but it will not include the full git history. However, the repository
516b08a580 jm-c  can be updated going forward.
69e7157c80 Jeff* 
                 Method 2
                 --------
                 
31584ea246 Jeff* This section describes how to do a one-time download of MITgcm, NOT git-aware.
ba0b047096 Mart* In a terminal window, ``cd`` to the directory where
                 you want your code to reside. To obtain the current code, type:
69e7157c80 Jeff* 
                 ::
                 
                     % wget https://github.com/MITgcm/MITgcm/archive/master.zip
                 
516b08a580 jm-c  For specific checkpoint release ``XXX``, instead type:
69e7157c80 Jeff* 
                 ::
                 
af61fa61c7 Jeff*     % wget https://github.com/MITgcm/MITgcm/archive/checkpoint«XXX».zip
69e7157c80 Jeff* 
                 Updating the code
                 =================
                 
ba0b047096 Mart* There are several different approaches one can use to obtain updates to MITgcm;
                 which is best for you depends a bit on how you intend to use MITgcm and your
                 knowledge of git (and/or willingness to learn).
                 Below we outline three suggested update pathways:
69e7157c80 Jeff* 
31584ea246 Jeff* 1. **Fresh Download of MITgcm**
69e7157c80 Jeff* 
ba0b047096 Mart* This approach is the most simple, and virtually foolproof. Whether you
                 downloaded the code from a static zip file (`Method 2`_) or used the git
                 clone command (`Method 1`_), create a new directory and repeat
                 this procedure to download a current copy of MITgcm. Say for example you
                 are starting a new research project, this would be a great time to grab the
                 most recent code repository and keep this new work entirely separate
                 from any past simulations. This approach requires no understanding of git,
                 and you are free to make changes to any files in the MIT repo tree
                 (although we generally recommend that you avoid doing so, instead working
                 in new subdirectories or on separate scratch disks as described
516b08a580 jm-c  :ref:`here <build_elsewhere>`, for example).
69e7157c80 Jeff* 
                 2. **Using** ``git pull`` **to update the (unmodified) MITgcm repo tree**
                 
ba0b047096 Mart* If you have downloaded the code through a git clone command
                 (`Method 1`_ above), you can incorporate any changes to the source code
                 (including any changes to any files in the MITgcm repository, new packages
                 or analysis routines, etc.) that may have occurred since your
                 original download. There is a simple command to bring all code in the
                 repository to a ‘current release’ state. From the MITgcm top directory
69e7157c80 Jeff* or any of its subdirectories, type:
                 
                 ::
                 
                     % git pull
                 
ba0b047096 Mart* and all files will be updated to match the current state of the code
                 repository, as it exists at `GitHub <https://github.com/MITgcm/MITgcm.git>`_.
                 (*Note:* if you plan to contribute to MITgcm and followed the steps to
                 download the code as described in :numref:`chap_contributing`,
                 you will need to type ``git pull upstream`` instead.)
                 
                 This update pathway is ideal if you are in the midst of a project and
                 you want to incorporate new MITgcm features into your executable(s),
                 or take advantage of recently added analysis utilties, etc.
                 After the git pull, any changes in model source code and include files
                 will be updated, so you can repeat the build procedure
                 (:numref:`building_code`) and you will include all these new features
69e7157c80 Jeff* in your new executable.
                 
ba0b047096 Mart* Be forewarned, this will only work if you have not modified ANY of the
                 files in the MITgcm repository (adding new files is ok; also, all
                 verification run subdirectories ``build`` and ``run`` are also ignored by git).
                 If you have modified files and the ``git pull`` fails with errors,
                 there is no easy fix other than to learn something
                 about git (continue reading...)
69e7157c80 Jeff* 
                 3. **Fully embracing the power of git!**
                 
ce0d9af5ea Jeff* Git offers many tools to help organize and track changes in your work.
ba0b047096 Mart* For example, one might keep separate projects on different branches,
                 and update the code separately (using ``git pull``) on these separate branches.
                 You can even make changes to code in the MIT repo tree; when git then
                 tries to update code from upstream (see :numref:`git_setup`), it will notify
                 you about possible conflicts and even merge the code changes
                 together if it can. You can also use ``git commit`` to help you track what
                 you are modifying in your simulations over time. If you're planning to
                 submit a pull request to include your changes, you should read the
                 contributing guide in :numref:`chap_contributing`, and we suggest you do
                 this model development in a separate, fresh copy of the code. See
                 :numref:`using_git_and_github` for more information and how
69e7157c80 Jeff* to use git effectively to manage your workflow.
                 
                 Model and directory structure
                 =============================
                 
                 The “numerical” model is contained within a execution environment
                 support wrapper. This wrapper is designed to provide a general framework
                 for grid-point models; MITgcm is a specific numerical model that makes use of
ba0b047096 Mart* this framework (see :numref:`wrapper` for additional detail).
                 Under this structure, the model is split into execution
69e7157c80 Jeff* environment support code and conventional numerical model code. The
af61fa61c7 Jeff* execution environment support code is held under the :filelink:`eesupp`
                 directory. The grid point model code is held under the :filelink:`model`
ba0b047096 Mart* directory. Code execution actually starts in the :filelink:`eesupp` routines
                 and not in the :filelink:`model` routines. For this reason the top-level
                 :filelink:`main.F <eesupp/src/main.F>` is in the :filelink:`eesupp/src`
                 directory. In general, end-users should not need to worry about the
                 wrapper support code. The top-level routine for the numerical
af61fa61c7 Jeff* part of the code is in :filelink:`model/src/the_model_main.F`. Here is a brief
69e7157c80 Jeff* description of the directory structure of the model under the root tree.
                 
af61fa61c7 Jeff* -  :filelink:`model`: this directory contains the main source code. Also
ba0b047096 Mart*    subdivided into two subdirectories: :filelink:`model/inc` (includes files)
                    and :filelink:`model/src` (source code).
69e7157c80 Jeff* 
ba0b047096 Mart* -  :filelink:`eesupp`: contains the execution environment source code.
                    Also subdivided into two subdirectories: :filelink:`eesupp/inc`
                    and :filelink:`eesupp/src`.
69e7157c80 Jeff* 
af61fa61c7 Jeff* -  :filelink:`pkg`: contains the source code for the packages. Each package
ba0b047096 Mart*    corresponds to a subdirectory. For example, :filelink:`pkg/gmredi`
                    contains the code related to the Gent-McWilliams/Redi scheme,
                    :filelink:`pkg/seaice` the code for a dynamic seaice model which can be
                    coupled to the ocean model. The packages are described in detail in
                    :numref:`packagesI` and :numref:`outp_pack`].
                 
                 -  :filelink:`doc`: contains MITgcm documentation in reStructured
                    Text (rst) format.
                 
                 -  :filelink:`tools`: this directory contains various useful tools.
                    For example, :filelink:`genmake2 <tools/genmake2>` is a script written
                    in bash that should be used to generate your makefile.
                    The subdirectory :filelink:`tools/build_options` contains
                    ‘optfiles’ with the compiler options for many different
                    compilers and machines that can run MITgcm
                    (see :numref:`genmake2_optfiles`). This directory also contains
                    subdirectories :filelink:`tools/adjoint_options` and
                    :filelink:`tools/OAD_support` that are used to generate the tangent linear
                    and adjoint model (see details in :numref:`chap_autodiff`).
                 
                 -  :filelink:`utils`: this directory contains various utilities.
                    The :filelink:`utils/matlab` subdirectory
69e7157c80 Jeff*    contains matlab scripts for reading model output directly into
ba0b047096 Mart*    matlab. The subdirectory :filelink:`utils/python` contains similar
                    routines for python. :filelink:`utils/scripts` contains C-shell
                    post-processing scripts for joining processor-based and
                    tiled-based model output.
69e7157c80 Jeff* 
af61fa61c7 Jeff* -  :filelink:`verification`: this directory contains the model examples. See
69e7157c80 Jeff*    :numref:`chap_modelExamples`.
                 
af61fa61c7 Jeff* -  :filelink:`jobs`: contains sample job scripts for running MITgcm.
69e7157c80 Jeff* 
af61fa61c7 Jeff* -  :filelink:`lsopt`: Line search code used for optimization.
69e7157c80 Jeff* 
af61fa61c7 Jeff* -  :filelink:`optim`: Interface between MITgcm and line search code.
69e7157c80 Jeff* 
                 .. _building_code:
                 
31584ea246 Jeff* Building the model
                 ==================
                 
                 .. _building_quickstart:
                 
                 Quickstart Guide
                 ----------------
69e7157c80 Jeff* 
                 To compile the code, we use the ``make`` program. This uses a file
                 (``Makefile``) that allows us to pre-process source files, specify
                 compiler and optimization options and also figures out any file
ba0b047096 Mart* dependencies. We supply a script (:filelink:`genmake2 <tools/genmake2>`),
                 described in section :numref:`genmake2_desc`, that automatically generates
                 the ``Makefile`` for you. You then need to build the dependencies and
                 compile the code (:numref:`make_target_commands`).
69e7157c80 Jeff* 
                 As an example, assume that you want to build and run experiment
ba0b047096 Mart* :filelink:`verification/exp2`.
                 Let’s build the code in :filelink:`verification/exp2/build`:
69e7157c80 Jeff* 
                 ::
                 
                     % cd verification/exp2/build
                 
017e3135cd Jeff* First, generate the ``Makefile``:
69e7157c80 Jeff* 
                 ::
                 
3b0572824e Jeff*     % ../../../tools/genmake2 -mods ../code -optfile «/PATH/TO/OPTFILE»
69e7157c80 Jeff* 
ba0b047096 Mart* The ``-mods`` command line option tells :filelink:`genmake2 <tools/genmake2>`
                 to override model source code with any files in the subdirectory ``../code``
                 (here, you need to configure the size of the model domain by overriding
                 MITgcm’s default :filelink:`SIZE.h <model/inc/SIZE.h>`
e7309a0b9d Jeff* with an edited copy :filelink:`../code/SIZE.h <verification/exp2/code/SIZE.h>`
3b0572824e Jeff* containing the specific domain size for :filelink:`exp2 <verification/exp2>`).
e7309a0b9d Jeff* 
                 The ``-optfile`` command line option tells :filelink:`genmake2 <tools/genmake2>`
ba0b047096 Mart* to run the specified
                 :ref:`optfile <genmake2_optfiles>`, a  `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_
                 shell script, during :filelink:`genmake2 <tools/genmake2>`’s execution.
3b0572824e Jeff* An :ref:`optfile <genmake2_optfiles>` typically contains
ba0b047096 Mart* definitions of
                 `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_,
                 paths, compiler options, and anything else that needs to be set in order
                 to compile on your local computer system or cluster with your specific
                 Fortan compiler. As an example, we might replace ``«/PATH/TO/OPTFILE»`` with
                 :filelink:`../../../tools/build_options/linux_amd64_ifort11 <tools/build_options/linux_amd64_ifort11>`
                 for use with the
                 `Intel Fortran <https://software.intel.com/en-us/fortran-compilers>`_ compiler
3b0572824e Jeff* (version 11 and above) on a linux x86_64 platform.
ba0b047096 Mart* This and many other :ref:`optfiles <genmake2_optfiles>` for common systems
                 and Fortran compilers are located in :filelink:`tools/build_options`.
69e7157c80 Jeff* 
ba0b047096 Mart* ``-mods``, ``-optfile``, and many additional
                 :filelink:`genmake2 <tools/genmake2>` command line options are described
                 more fully in :numref:`command_line_options`. Detailed instructions on
                 building with
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
                 are given in :numref:`build_mpi`.
69e7157c80 Jeff* 
                 Once a ``Makefile`` has been generated, we create the dependencies with
                 the command:
                 
                 ::
                 
                     % make depend
                 
b3d71355f7 Jeff* It is important to note that the ``make depend`` stage will occasionally
69e7157c80 Jeff* produce warnings or errors if the dependency parsing tool is unable
516b08a580 jm-c  to find all of the necessary header files (e.g., ``netcdf.inc``, or worse,
e7309a0b9d Jeff* say it cannot find a Fortran compiler in your path). In some cases you
69e7157c80 Jeff* may need to obtain help from your system administrator to locate these files.
                 
                 Next, one can compile the code using:
                 
                 ::
                 
                     % make
                 
ba0b047096 Mart* Assuming no errors occurred, the ``make`` command creates
                 an executable called ``mitgcmuv``.
69e7157c80 Jeff* 
                 Now you are ready to run the model. General instructions for doing so
516b08a580 jm-c  are given in section :numref:`run_the_model`.
69e7157c80 Jeff* 
31584ea246 Jeff* .. _genmake2_desc:
69e7157c80 Jeff* 
b3d71355f7 Jeff* Generating a ``Makefile`` using genmake2
                 ----------------------------------------
69e7157c80 Jeff* 
ba0b047096 Mart* A shell script called ``genmake2`` for generating a ``Makefile`` is
                 included as part of MITgcm.
b3d71355f7 Jeff* Typically ``genmake2`` is used in a sequence of steps as shown below:
69e7157c80 Jeff* 
                 ::
                 
516b08a580 jm-c    % ../../../tools/genmake2 -mods ../code -optfile «/PATH/TO/OPTFILE»
31584ea246 Jeff*   % make depend
                   % make
69e7157c80 Jeff* 
ba0b047096 Mart* The first step above creates a unix-style ``Makefile``. The ``Makefile``
                 is used by ``make`` to specify how to compile the MITgcm source files
                 (for more detailed descriptions of what the ``make`` tools
                 are, and how they are used, see
                 `here <https://www.gnu.org/software/make/make.html>`__).
3396b55b9d chri* 
ba0b047096 Mart* This section describes details and capabilities of
                 :filelink:`genmake2 <tools/genmake2>`, located in the
b3d71355f7 Jeff* :filelink:`tools` directory. :filelink:`genmake2 <tools/genmake2>` is a shell
ba0b047096 Mart* script written to work in
                 `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_ (and with all
ce0d9af5ea Jeff* “sh”–compatible shells including
ba0b047096 Mart* `Bourne <https://en.wikipedia.org/wiki/Bourne_shell>`_ shells).
                 Like many unix tools, there is a help option that is invoked
                 thru ``genmake2 -h``. :filelink:`genmake2 <tools/genmake2>` parses
                 information from the following sources, in this order:
31584ea246 Jeff* 
e7309a0b9d Jeff* #.    Command-line options (see :numref:`command_line_options`)
31584ea246 Jeff* 
                 #.    A ``genmake_local`` file if one is found in the current directory.
3b0572824e Jeff*       This is a `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_ shell
ba0b047096 Mart*       script that is executed prior to the :ref:`optfile <genmake2_optfiles>`
                       (see step #3), used in some special model configurations and/or to
                       set some options that can affect which lines of the
                       :ref:`optfile <genmake2_optfiles>` are executed.
                       For example, this
                       :filelink:`genmake_local <verification/cpl_aim+ocn/build_cpl/genmake_local>`
                       file is required for a special setup, building a ‘MITgcm coupler’
                       executable; in a more typical setup, one will not require a
                       ``genmake_local`` file.
69e7157c80 Jeff* 
3b0572824e Jeff* #.    An “options file” a.k.a. :ref:`optfile <genmake2_optfiles>`
ba0b047096 Mart*       (a `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_ shell
                       script) specified by the command-line option
                       ``–optfile «/PATH/TO/OPTFILE»``, as mentioned briefly
                       in :numref:`building_quickstart`
b3d71355f7 Jeff*       and described in detail in :numref:`genmake2_optfiles`.
69e7157c80 Jeff* 
31584ea246 Jeff* #.    A ``packages.conf`` file (if one is found) with the specific list of
ba0b047096 Mart*       packages to compile (see :numref:`using_packages`). The search path for
                       file ``packages.conf`` is first the current directory, and then each
                       of the ``-mods`` directories in the given order (as described
                       :ref:`here <mods_option>`).
69e7157c80 Jeff* 
ba0b047096 Mart* When you run the :filelink:`genmake2 <tools/genmake2>` script,
                 typical output might be as follows:
31584ea246 Jeff* 
                 ::
                 
e7309a0b9d Jeff*   % ../../../tools/genmake2 -mods ../code -optfile ../../../tools/build_options/linux_amd64_gfortran
516b08a580 jm-c  
e7309a0b9d Jeff*   GENMAKE :
516b08a580 jm-c  
e7309a0b9d Jeff*   A program for GENerating MAKEfiles for the MITgcm project.
                      For a quick list of options, use "genmake2 -h"
516b08a580 jm-c    or for more detail see the documentation, section "Building the model"
                      (under "Getting Started") at:  https://mitgcm.readthedocs.io/
                 
e7309a0b9d Jeff*   ===  Processing options files and arguments  ===
                     getting local config information:  none found
                   Warning: ROOTDIR was not specified ; try using a local copy of MITgcm found at "../../.."
                     getting OPTFILE information:
                       using OPTFILE="../../../tools/build_options/linux_amd64_gfortran"
                     getting AD_OPTFILE information:
                       using AD_OPTFILE="../../../tools/adjoint_options/adjoint_default"
516b08a580 jm-c      check Fortran Compiler...  pass  (set FC_CHECK=5/5)
e7309a0b9d Jeff*     check makedepend (local: 0, system: 1, 1)
516b08a580 jm-c  
e7309a0b9d Jeff*   ===  Checking system libraries  ===
                     Do we have the system() command using gfortran...  yes
                     Do we have the fdate() command using gfortran...  yes
                     Do we have the etime() command using gfortran... c,r: yes (SbR)
                     Can we call simple C routines (here, "cloc()") using gfortran...  yes
                     Can we unlimit the stack size using gfortran...  yes
                     Can we register a signal handler using gfortran...  yes
                     Can we use stat() through C calls...  yes
                     Can we create NetCDF-enabled binaries...  yes
516b08a580 jm-c        skip check for LAPACK Libs
e7309a0b9d Jeff*     Can we call FLUSH intrinsic subroutine...  yes
516b08a580 jm-c  
e7309a0b9d Jeff*   ===  Setting defaults  ===
516b08a580 jm-c      Adding MODS directories: ../code
e7309a0b9d Jeff*     Making source files in eesupp from templates
                     Making source files in pkg/exch2 from templates
                     Making source files in pkg/regrid from templates
516b08a580 jm-c  
e7309a0b9d Jeff*   ===  Determining package settings  ===
                     getting package dependency info from  ../../../pkg/pkg_depend
                     getting package groups info from      ../../../pkg/pkg_groups
                     checking list of packages to compile:
                       using PKG_LIST="../code/packages.conf"
                       before group expansion packages are: oceanic -kpp -gmredi cd_code
                       replacing "oceanic" with:  gfd gmredi kpp
                       replacing "gfd" with:  mom_common mom_fluxform mom_vecinv generic_advdiff debug mdsio rw monitor
                       after group expansion packages are:  mom_common mom_fluxform mom_vecinv generic_advdiff debug mdsio rw monitor gmredi kpp -kpp -gmredi cd_code
                     applying DISABLE settings
                     applying ENABLE settings
                       packages are:  cd_code debug generic_advdiff mdsio mom_common mom_fluxform mom_vecinv monitor rw
                     applying package dependency rules
                       packages are:  cd_code debug generic_advdiff mdsio mom_common mom_fluxform mom_vecinv monitor rw
                     Adding STANDARDDIRS='eesupp model'
                     Searching for *OPTIONS.h files in order to warn about the presence
                       of "#define "-type statements that are no longer allowed:
516b08a580 jm-c        found CPP_EEOPTIONS="../../../eesupp/inc/CPP_EEOPTIONS.h"
                       found CPP_OPTIONS="../../../model/inc/CPP_OPTIONS.h"
e7309a0b9d Jeff*     Creating the list of files for the adjoint compiler.
516b08a580 jm-c  
e7309a0b9d Jeff*   ===  Creating the Makefile  ===
                     setting INCLUDES
                     Determining the list of source and include files
                     Writing makefile: Makefile
                     Add the source list for AD code generation
                     Making list of "exceptions" that need ".p" files
                     Making list of NOOPTFILES
                     Add rules for links
                     Adding makedepend marker
516b08a580 jm-c  
e7309a0b9d Jeff*   ===  Done  ===
f7aaac66f3 jm-c      original 'Makefile' generated successfully
                   => next steps:
                     > make depend
                     > make       (<-- to generate executable)
e7309a0b9d Jeff* 
31584ea246 Jeff* In the above, notice:
                 
e7309a0b9d Jeff* - we did not specify ``ROOTDIR``,
516b08a580 jm-c    i.e., a path to your MITgcm repository,
31584ea246 Jeff*   but here we are building code from within the repository (specifically,
516b08a580 jm-c    in one of the verification subdirectory experiments). As such,
31584ea246 Jeff*   :filelink:`genmake2 <tools/genmake2>` was smart enough to
ba0b047096 Mart*   locate all necessary files on its own. To specify a remote ``ROOTDIR``,
                   see :ref:`here <build_elsewhere>`.
                 - we specified the :ref:`optfile <genmake2_optfiles>`
                   :filelink:`linux_amd64_gfortran <tools/build_options/linux_amd64_gfortran>`
e7309a0b9d Jeff*   based on the computer system and Fortran compiler we used
31584ea246 Jeff*   (here, a linux 64-bit machine with gfortran installed).
ba0b047096 Mart* - :filelink:`genmake2 <tools/genmake2>` did
                   some simple checking on availability
                   of certain system libraries; all were found (except
                   `LAPACK <https://en.wikipedia.org/wiki/LAPACK>`_,
516b08a580 jm-c    which was not checked since it is not needed here).
31584ea246 Jeff*   `NetCDF <http://www.unidata.ucar.edu/software/netcdf>`_ only requires a ‘yes’
ba0b047096 Mart*   if you want to write `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
                   output; more specifically, a ‘no’ response to “Can we create NetCDF-enabled
                   binaries” will disable including  :filelink:`pkg/mnc` and switch to output
                   plain binary files. While the makefile can still be built with other
                   ‘no’ responses, sometimes this will foretell errors during the
31584ea246 Jeff*   ``make depend`` or ``make`` commands.
ba0b047096 Mart* - any ``.F`` or ``.h`` files in the ``-mods`` directory ``../code`` will
                   also be compiled, overriding any MITgcm repository versions of files,
                   if they exist.
                 - a handful of packages are being used in this build; see
                   :numref:`using_packages` for more detail about how to enable and disable
                   packages.
                 - :filelink:`genmake2 <tools/genmake2>` terminated without error
                   (note output at end after ``===  Done  ===``), generating ``Makefile`` and
                   a log file ``genmake.log``. As mentioned, this does not guarantee that
                   your setup will compile properly, but if there are errors during
                   ``make depend`` or ``make``, these error messages and/or the
                   standard output from :filelink:`genmake2 <tools/genmake2>` or
                   ``genmake.log`` may provide clues as to the problem.
516b08a580 jm-c    If instead :filelink:`genmake2 <tools/genmake2>` finishes with
                   a warning message  ``Warning: FORTRAN compiler test failed`` , this means
                   that :filelink:`genmake2 <tools/genmake2>` is unable to locate the Fortran
ba0b047096 Mart*   compiler or pass a trivial “hello world” Fortran compilation test.
                   In this case, you should see ``genmake.log`` for errors and/or seek
                   assistance from your system administrator;
f7aaac66f3 jm-c    these tests need to pass in order to proceed to the ``make`` steps.
                 
e7309a0b9d Jeff* .. _command_line_options:
69e7157c80 Jeff* 
                 Command-line options:
                 ~~~~~~~~~~~~~~~~~~~~~
                 
e7309a0b9d Jeff* :filelink:`genmake2 <tools/genmake2>` supports a number of helpful
69e7157c80 Jeff* command-line options. A complete list of these options can be obtained by:
                 
                 ::
                 
                     % genmake2 -h
                 
                 The most important command-line options are:
                 
e7309a0b9d Jeff* ``–optfile «/PATH/TO/OPTFILE»``
ba0b047096 Mart*     (or shorter: ``-of`` ) specifies the :ref:`optfile <genmake2_optfiles>`
                     that should be used for a particular build.
69e7157c80 Jeff* 
ba0b047096 Mart*     If no :ref:`optfile <genmake2_optfiles>` is specified through the command
                     line, :filelink:`genmake2 <tools/genmake2>` will try to make a
af61fa61c7 Jeff*     reasonable guess from the list provided in :filelink:`tools/build_options`.
69e7157c80 Jeff*     The method used for making this guess is to first determine the
31584ea246 Jeff*     combination of operating system and hardware and
e7309a0b9d Jeff*     then find a working Fortran compiler within the user’s path. When
ba0b047096 Mart*     these three items have been identified,
                     :filelink:`genmake2 <tools/genmake2>` will try to find an
                     :ref:`optfile <genmake2_optfiles>` that has a matching name.
                     See :numref:`genmake2_optfiles`.
69e7157c80 Jeff* 
                 .. _mods_option:
                 
b3d71355f7 Jeff* ``–mods '«DIR1 DIR2 DIR3 ...»'``
69e7157c80 Jeff*     specifies a list of directories containing “modifications”. These
                     directories contain files with names that may (or may not) exist in
                     the main MITgcm source tree but will be overridden by any
                     identically-named sources within the ``-mods`` directories.
ba0b047096 Mart*     Note the quotes around the list of directories,
                     necessary given multiple arguments.
69e7157c80 Jeff* 
e7309a0b9d Jeff*     The order of precedence for versions of files with identical names:
69e7157c80 Jeff* 
ba0b047096 Mart*     -  “mods” directories in the order given (e.g., will use copy of file
                        located in DIR1 instead of DIR2)
69e7157c80 Jeff* 
b3d71355f7 Jeff*     -  Packages either explicitly specified or included by default
69e7157c80 Jeff* 
b3d71355f7 Jeff*     -  Packages included due to package dependencies
69e7157c80 Jeff* 
                     -  The “standard dirs” (which may have been specified by the
e7309a0b9d Jeff*        ``-standarddirs`` option below)
                 
                 .. _build_elsewhere:
69e7157c80 Jeff* 
31584ea246 Jeff* ``-rootdir «/PATH/TO/MITGCMDIR»``
                     specify the location of the MITgcm repository top directory (``ROOTDIR``).
ba0b047096 Mart*     By default, :filelink:`genmake2 <tools/genmake2>` will try to find this
                     location by looking in parent directories from where
                     :filelink:`genmake2 <tools/genmake2>` is executed
b3d71355f7 Jeff*     (up to 5 directory levels above the current directory).
e7309a0b9d Jeff* 
ba0b047096 Mart*     In the quickstart example above (:numref:`building_quickstart`) we built
                     the executable in the ``build`` directory of the experiment.
e7309a0b9d Jeff*     Below, we show how to configure and compile the code on a scratch disk,
                     without having to copy the entire source
ba0b047096 Mart*     tree. The only requirement is that you have
                     :filelink:`genmake2 <tools/genmake2>`
b3d71355f7 Jeff*     in your `$PATH <https://en.wikipedia.org/wiki/PATH_(variable)>`_, or
ba0b047096 Mart*     you know the absolute path to :filelink:`genmake2 <tools/genmake2>`.
                     In general, one can compile the code in any given directory by following
                     this procedure. Assuming the model source is in ``~/MITgcm``, then the
e7309a0b9d Jeff*     following commands will build the model in ``/scratch/exp2-run1``:
                 
                     ::
31584ea246 Jeff* 
e7309a0b9d Jeff*        % cd /scratch/exp2-run1
                        % ~/MITgcm/tools/genmake2 -rootdir ~/MITgcm -mods ~/MITgcm/verification/exp2/code
                        % make depend
                        % make
31584ea246 Jeff* 
b3d71355f7 Jeff*     As an alternative to specifying the MITgcm repository location through
ba0b047096 Mart*     the ``-rootdir`` command-line option, :filelink:`genmake2 <tools/genmake2>`
                     recognizes the
                     `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
                     ``$MITGCM_ROOTDIR``.
3b0572824e Jeff* 
31584ea246 Jeff* ``-standarddirs «/PATH/TO/STANDARDDIR»``
ba0b047096 Mart*     specify a path to the standard MITgcm directories for source and includes
                     files. By default, :filelink:`model` and :filelink:`eesupp`
                     directories (``src`` and ``inc``)  are the “standard dirs”.
                     This command can be used
b3d71355f7 Jeff*     to reset these default standard directories,
31584ea246 Jeff*     or instead NOT include either :filelink:`model` or :filelink:`eesupp`
                     as done in some specialized configurations.
                 
69e7157c80 Jeff* ``-oad``
e7309a0b9d Jeff*     generates a makefile for an OpenAD build (see :numref:`ad_openad`)
69e7157c80 Jeff* 
af61fa61c7 Jeff* ``–adoptfile «/PATH/TO/FILE»``
ba0b047096 Mart*     (or shorter: ``-adof`` ) specifies the “adjoint” or automatic
                     differentiation options file to be used. The file is analogous to the
                     optfile defined above but it specifies information for the AD
                     build process. See :numref:`adoptfile`.
69e7157c80 Jeff* 
                     The default file is located in
af61fa61c7 Jeff*     :filelink:`tools/adjoint_options/adjoint_default` and it defines the “TAF”
516b08a580 jm-c      and “TAMC” compiler options.
69e7157c80 Jeff* 
                 ``–mpi``
ba0b047096 Mart*     enables certain
                     `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
                     features (using CPP ``#define``) within the code and is necessary for
                     `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ builds
b3d71355f7 Jeff*     (see :numref:`build_mpi`).
69e7157c80 Jeff* 
                 ``–omp``
ba0b047096 Mart*     enables OpenMP code and compiler flag ``OMPFLAG``
                     (see :numref:`build_openmp`).
69e7157c80 Jeff* 
                 ``–ieee``
b3d71355f7 Jeff*     use IEEE numerics (requires support in optfile).
ba0b047096 Mart*     This option is typically a good choice if one wants to compare output
                     from different machines running the same code.
                     Note using IEEE disables all compiler optimizations.
31584ea246 Jeff* 
                 ``-devel``
ba0b047096 Mart*     use IEEE numerics (requires support in optfile) and add additional
                     compiler options to check array bounds and add other additional warning
                     and debugging flags.
69e7157c80 Jeff* 
af61fa61c7 Jeff* ``–make «/PATH/TO/GMAKE»``
69e7157c80 Jeff*     due to the poor handling of soft-links and other bugs common with
31584ea246 Jeff*     the ``make`` versions provided by commercial unix vendors, GNU
69e7157c80 Jeff*     ``make`` (sometimes called ``gmake``) may be preferred. This
                     option provides a means for specifying the make executable to be
                     used.
                 
ba0b047096 Mart* While it is possible to use :filelink:`genmake2 <tools/genmake2>` command-line
                 options to set the Fortran or C compiler name (``-fc`` and ``-cc``
                 respectively), we generally recommend setting these through an
                 :ref:`optfile <genmake2_optfiles>`, as discussed in :numref:`genmake2_optfiles`.
31584ea246 Jeff* Other :filelink:`genmake2 <tools/genmake2>` options  are available to
                 enable performance/timing analyses, etc.; see ``genmake2 -h`` for more info.
                 
e7309a0b9d Jeff* .. _genmake2_optfiles:
                 
                 Optfiles in tools/build_options directory:
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                 
                 The purpose of the optfiles is to provide all the compilation options
                 for particular “platforms” (where “platform” roughly means the
                 combination of the hardware and the compiler) and code configurations.
                 Given the combinations of possible compilers and library dependencies
                 (e.g., `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ or
b3d71355f7 Jeff* `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_) there may be
                 numerous optfiles available for a
e7309a0b9d Jeff* single machine. The naming scheme for the majority of the optfiles
                 shipped with the code is **OS_HARDWARE_COMPILER** where
                 
                 **OS**
                     is the name of the operating system (generally the lower-case output
                     of a linux terminal ``uname`` command)
                 
                 **HARDWARE**
                     is a string that describes the CPU type and corresponds to output
                     from a ``uname -m`` command. Some common CPU types:
                 
                     ``amd64``
ba0b047096 Mart*         use this code for x86_64 systems (most common, including AMD and
                         Intel 64-bit CPUs)
e7309a0b9d Jeff* 
                     ``ia64``
                         is for Intel IA64 systems (eg. Itanium, Itanium2)
                 
                     ``ppc``
                         is for (old) Mac PowerPC systems
                 
                 **COMPILER**
ba0b047096 Mart*     is the compiler name (generally, the name of the Fortran compiler
                     executable). MITgcm is primarily written in
                     `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_.
                     Compiling the code  requires a
                     `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_ compiler.
                     Any more recent compiler which is backwards compatible with
                     `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_
b3d71355f7 Jeff*     can also be used; for example, the model will build successfully
516b08a580 jm-c      with a `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_
ba0b047096 Mart*     or  `Fortran 95 <https://en.wikipedia.org/wiki/Fortran#Fortran_95>`_
                     compiler. A `C99 <https://en.wikipedia.org/wiki/C99>`_ compatible compiler
                     is also need, together with a
                     `C preprocessor <https://en.wikipedia.org/wiki/C_preprocessor>`_ .
                     Some optional packages make use of
                     `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_ constructs
                     (either
                     `free-form formatting <https://en.wikipedia.org/wiki/Free-form_language>`_,
                     or
                     `dynamic memory allocation <https://en.wikipedia.org/wiki/Memory_management#DYNAMIC>`_);
                     as such, setups which use these packages require a
                     `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_
5564cc2c2d chri*     or later compiler build.
e7309a0b9d Jeff* 
ba0b047096 Mart* There are existing optfiles that work with many common hardware/compiler
                 configurations; we first suggest you peruse the list in
                 :filelink:`tools/build_options` and try to find your platform/compiler
                 configuration. These are the most common:
e7309a0b9d Jeff* 
                 - :filelink:`linux_amd64_gfortran <tools/build_options/linux_amd64_gfortran>`
                 - :filelink:`linux_amd64_ifort11 <tools/build_options/linux_amd64_ifort11>`
                 - :filelink:`linux_amd64_ifort+impi <tools/build_options/linux_amd64_ifort+impi>`
                 - :filelink:`linux_amd64_pgf77 <tools/build_options/linux_amd64_pgf77>`
                 
ba0b047096 Mart* The above optfiles are all for linux x86_64 (64-bit) systems, utilized in many
                 large high-performance computing centers. All of the above will work with
                 single-threaded,
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_,
                 or shared memory (`OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_) code
                 configurations. gfortran is `GNU Fortran <https://gcc.gnu.org/fortran>`_,
e7309a0b9d Jeff* ifort is `Intel Fortran <https://software.intel.com/en-us/fortran-compilers>`_,
ba0b047096 Mart* pgf77 is `PGI Fortran <https://www.pgroup.com/>`_ (formerly known as
                 “The Portland Group”). Note in the above list there are two ``ifort`` optfiles:
e7309a0b9d Jeff* :filelink:`linux_amd64_ifort+impi <tools/build_options/linux_amd64_ifort+impi>`
                 is for a specific case of using ``ifort`` with the
ba0b047096 Mart* `Intel MPI library <https://software.intel.com/en-us/intel-mpi-library>`_
                 (a.k.a. ``impi``), which requires special define statements in the optfile
                 (in contrast with `Open MPI <https://www.open-mpi.org/>`_ or
                 `MVAPICH2 <http:mvapich.cse.ohio-state.edu/>`_ libraries;
                 see :numref:`build_mpi`). Note that both ifort optfiles require ifort
                 version 11 or higher. Many clusters nowadays use
                 `environment modules <http:modules.sourceforge.net>`_,
                 which allows one to easily choose which compiler to use through
                 ``module load «MODULENAME»``, automatically configuring your environment
                 for a specific compiler choice (type ``echo $PATH`` to see where
                 :filelink:`genmake2 <tools/genmake2>` will look for compilers
                 and system software).
                 
                 In most cases, your platform configuration will be included in the available
                 optfiles :filelink:`list <tools/build_options/>` and will result in a
                 usable ``Makefile`` being generated. If you are unsure which optfile is
                 correct for your configuration, you can try not specifying an optfile;
                 on some systems the :filelink:`genmake2 <tools/genmake2>` program will be able
                 to automatically recognize the hardware, find a compiler and other tools
                 within the user’s path, and then make a best guess as to an appropriate optfile
3b0572824e Jeff* from the list in the :filelink:`tools/build_options` directory.
e7309a0b9d Jeff* However, for some platforms and code configurations, new
                 optfiles must be written. To create a new optfile, it is generally
                 best to start with one of the defaults and modify it to suit your needs.
ba0b047096 Mart* Like
                 :filelink:`genmake2 <tools/genmake2>`, the optfiles are all written in `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_
ce0d9af5ea Jeff* (or using a simple
ba0b047096 Mart* `sh–compatible <https://en.wikipedia.org/wiki/Bourne_shell>`_ syntax).
                 While nearly all
                 `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
                 used within :filelink:`genmake2 <tools/genmake2>` may be specified in the
                 optfiles, the critical ones that should be defined are:
e7309a0b9d Jeff* 
3b0572824e Jeff* .. _list_of_optfile_env_vars:
                 
e7309a0b9d Jeff* ``FC``
ba0b047096 Mart*     the Fortran compiler (executable) to use on ``.F`` files, e.g., ``ifort``
                     or ``gfortran``, or if using MPI, the mpi-wrapper equivalent,
                     e.g., ``mpif77``
e7309a0b9d Jeff* 
                 ``F90C``
ba0b047096 Mart*     the Fortran compiler to use on ``.F90`` files (only necessary if your setup
                     includes a package which contains ``.F90`` source code)
e7309a0b9d Jeff* 
                 ``CC``
ba0b047096 Mart*     similarly, the C compiler to use, e.g., ``icc`` or ``gcc``, or if using MPI,
                     the mpi-wrapper equivalent, e.g., ``mpicc``
e7309a0b9d Jeff* 
                 ``DEFINES``
                     command-line options passed to the compiler
                 
                 ``CPP``
ba0b047096 Mart*     the C preprocessor to use, and any necessary command-line options,
                     e.g. ``cpp -traditional -P``
e7309a0b9d Jeff* 
                 ``CFLAGS``, ``FFLAGS``
ba0b047096 Mart*     command-line compiler flags required for your C and Fortran compilers,
                     respectively, to compile and execute properly. See your C and Fortran
                     compiler documentation for specific options and syntax.
e7309a0b9d Jeff* 
                 ``FOPTIM``
ba0b047096 Mart*     command-line optimization Fortran compiler settings. See your Fortran
                     compiler documentation for specific options and syntax.
e7309a0b9d Jeff* 
                 ``NOOPTFLAGS``
ba0b047096 Mart*     command-line settings for special files that should not be optimized
                     using the ``FOPTIM`` flags
3b0572824e Jeff* 
                 ``NOOPTFILES``
ba0b047096 Mart*     list of source code files that should be compiled using ``NOOPTFLAGS``
                     settings
e7309a0b9d Jeff* 
                 ``INCLUDES``
ba0b047096 Mart*     path for additional files (e.g., ``netcdf.inc``, ``mpif.h``) to include
                     in the compilation using the command-line ``-I`` option
e7309a0b9d Jeff* 
                 ``INCLUDEDIRS``
                    path for additional files to be included in the compilation
                 
                 ``LIBS``
ba0b047096 Mart*    path for additional library files that need to be linked to generate the
                    final executable, e.g., ``libnetcdf.a``
e7309a0b9d Jeff* 
ba0b047096 Mart* For example, an excerpt from an optfile which specifies several of these
                 variables (here, for the linux-amd64 architecture using the PGI Fortran
                 compiler) is as follows:
e7309a0b9d Jeff* 
                 .. literalinclude:: ../../tools/build_options/linux_amd64_pgf77
                     :start-at: if test "x$MPI" = xtrue ; then
                     :end-at: F90OPTIM=$FOPTIM
                 
ba0b047096 Mart* The
                 :ref:`above <list_of_optfile_env_vars>` list of `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
e7309a0b9d Jeff* typically specified in an optfile is by no means complete;
ba0b047096 Mart* additional variables may be required for your specific setup and/or your
                 specific Fortran (or C) compiler.
e7309a0b9d Jeff* 
                 If you write an optfile for an unrepresented machine or compiler, you
                 are strongly encouraged to submit the optfile to the MITgcm project for
3b0572824e Jeff* inclusion. MITgcm developers are willing to
e7309a0b9d Jeff* provide help writing or modifing optfiles.  Please submit the file through
                 the `GitHub issue tracker <https://github.com/MITgcm/MITgcm/issues>`_
                 or email the MITgcm-support@mitgcm.org list.
                 
ba0b047096 Mart* Instructions on how to use optfiles to build
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_\ -enabled
                 executables is presented in :numref:`build_mpi`.
e7309a0b9d Jeff* 
                 .. _make_target_commands:
31584ea246 Jeff* 
                 ``make`` commands
e7309a0b9d Jeff* -----------------
31584ea246 Jeff* 
ba0b047096 Mart* Following a successful build of ``Makefile``, type ``make depend``. This
                 command modifies the ``Makefile`` by attaching a (usually, long) list of
31584ea246 Jeff* files upon which other files depend. The purpose of this is to reduce
                 re-compilation if and when you start to modify the code. The ``make depend``
ba0b047096 Mart* command also creates local links for all source files from the source
                 directories (see "-mods" description in :numref:`command_line_options`),
                 so that all source files to be used are visible from the local build directory,
7b2871578c Jean* either as hardcopy or as symbolic link.
dcd2d356ad chri* 
31584ea246 Jeff* **IMPORTANT NOTE:** Editing the source code files in the build directory
                 will not edit a local copy (since these are just links) but will
                 edit the original files in :filelink:`model/src` (or :filelink:`model/inc`)
                 or in the specified ``-mods`` directory. While the latter might
                 be what you intend, editing the master copy in :filelink:`model/src`
ba0b047096 Mart* is usually **NOT** what is intended and may cause grief somewhere down
                 the road. Rather, if you need to add
31584ea246 Jeff* to the list of modified source code files, place a copy of
                 the file(s) to edit in the ``-mods`` directory, make the edits to
ba0b047096 Mart* these ``-mods`` directory files, go back to the build directory and
                 type ``make Clean``, and then re-build the makefile (these latter steps
                 critical or the makefile will not link to this newly edited file).
31584ea246 Jeff* 
ba0b047096 Mart* The final ``make`` invokes the
                 `C preprocessor <https://en.wikipedia.org/wiki/C_preprocessor>`_
e7309a0b9d Jeff* to produce the “little f” files (``*.f`` and ``*.f90``) and then compiles them
516b08a580 jm-c  to object code using the specified Fortran compiler and options.
ba0b047096 Mart* The C preprocessor step converts a number of CPP macros and ``#ifdef``
                 statements to actual Fortran and expands C-style ``#include`` statements to
                 incorporate header files into the “little f" files. CPP style macros and
                 ``#ifdef`` statements are used to support generating
dcd2d356ad chri* different compile code for different model configurations.
ba0b047096 Mart* The result of the build process is an executable with the name ``mitgcmuv``.
31584ea246 Jeff* 
ba0b047096 Mart* Additional make “targets” are defined within the makefile to aid in the
                 production of adjoint (:numref:`building_adcode_using_taf`) and other
                 versions of MITgcm.
b3d71355f7 Jeff* 
e7309a0b9d Jeff* On computers with multiple processor cores, the build process can often be sped
31584ea246 Jeff* up appreciably using the command:
                 
                 ::
                 
                     % make -j 2
                 
                 where the “2” can be replaced with a number that corresponds to the
                 number of cores (or discrete CPUs) available.
                 
ba0b047096 Mart* In addition, there are several housekeeping ``make clean`` options that might
                 be useful:
31584ea246 Jeff* 
ba0b047096 Mart* - ``make clean`` removes files that ``make`` generates
                   (e.g., \*.o and \*.f files)
                 - ``make Clean`` removes files and links generated by ``make`` and
                   ``make depend``; strongly recommended for “un-clean” directories which
                   may contain the (perhaps partial) results of previous builds
                 - ``make CLEAN`` removes pretty much everything, including any executables
                   and output from :filelink:`genmake2 <tools/genmake2>`
31584ea246 Jeff* 
69e7157c80 Jeff* .. _build_mpi:
                 
94151a9b18 Jeff* Building with MPI
                 -----------------
69e7157c80 Jeff* 
ba0b047096 Mart* Building MITgcm to use
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ libraries can
                 be complicated due to the variety of different
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
76a376d977 Jeff* implementations available, their dependencies
69e7157c80 Jeff* or interactions with different compilers, and their often ad-hoc
                 locations within file systems. For these reasons, its generally a good
                 idea to start by finding and reading the documentation for your
                 machine(s) and, if necessary, seeking help from your local systems
                 administrator.
                 
ba0b047096 Mart* The steps for building MITgcm with
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ support are:
                 
                 #. Make sure you have
                    `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ libraries
                    installed on your computer system or cluster. Different Fortran compilers
                    (and different versions of a specific compiler) will generally require a
                    custom version (of a
                    `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ library)
                    built specifically for it.
                    On `environment module <http:modules.sourceforge.net>`_-enabled
b3d71355f7 Jeff*    clusters, one typically must first load a
ba0b047096 Mart*    Fortran compiler, then specific
                    `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
                    libraries for that compiler will become available to load.
                    If libraries are not installed, MPI implementations and related tools are
                    available including:
69e7157c80 Jeff* 
516b08a580 jm-c     -  `Open MPI <https://www.open-mpi.org/>`_
69e7157c80 Jeff* 
                    -  `MVAPICH2 <http:mvapich.cse.ohio-state.edu/>`_
                 
                    -  `MPICH <https://www.mpich.org/>`_
                 
                    -  `Intel MPI <https://software.intel.com/en-us/intel-mpi-library/>`_
                 
e7309a0b9d Jeff*    Ask you systems administrator for assistance in installing these libraries.
                 
ba0b047096 Mart* #. Determine the location of your
                    `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
3b0572824e Jeff*    library “wrapper” Fortran compiler, e.g., ``mpif77`` or ``mpifort`` etc.
ba0b047096 Mart*    which will be used instead of the name of the fortran compiler
                    (``gfortran``, ``ifort``, ``pgi77`` etc.) to compile your code.
                    Often the directory in which these wrappers are located will be
                    automatically added to your
                    `$PATH <https://en.wikipedia.org/wiki/PATH_(variable)>`_
                    `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
                    when you perform a ``module load «SOME_MPI_MODULE»``; thus, you will not
                    need to do anything beyond the module load itself.
b3d71355f7 Jeff*    If you are on a cluster that does not support
4bad209eba Jeff*    `environment modules <http:modules.sourceforge.net>`_,
3b0572824e Jeff*    you may have to manually add this directory to your path,
ba0b047096 Mart*    e.g., type ``PATH=$PATH:«ADD_ADDITIONAL_PATH_TO_MPI_WRAPPER_HERE»``
                    in a bash shell.
e7309a0b9d Jeff* 
ba0b047096 Mart* #. Determine the location of the includes file ``mpif.h`` and any other
                    `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_-related
                    includes files. Often these files will be located in a subdirectory off
                    the main `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
4bad209eba Jeff*    library ``include/``. In all optfiles in :filelink:`tools/build_options`,
ba0b047096 Mart*    it is assumed
                    `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
516b08a580 jm-c     ``$MPI_INC_DIR`` specifies this location; ``$MPI_INC_DIR``
4bad209eba Jeff*    should be set in your terminal session prior to generating a ``Makefile``.
                 
ba0b047096 Mart* #. Determine how many processors (i.e., CPU cores) you will be using in your
                    run, and modify your configuration’s :filelink:`SIZE.h <model/inc/SIZE.h>`
                    (located in a “modified code” directory, as specified in your
                    :filelink:`genmake2 <tools/genmake2>`
                    :ref:`command-line <command_line_options>`).
                    In :filelink:`SIZE.h <model/inc/SIZE.h>`,
76a376d977 Jeff*    you will need to set variables :varlink:`nPx`\*\ :varlink:`nPy` to
                    match the number of processors you will specify in
                    your run script’s MITgcm execution statement (i.e., typically ``mpirun``
                    or some similar command, see :numref:`running_mpi`).
516b08a580 jm-c     Note that MITgcm does not use
ba0b047096 Mart*    `dynamic memory allocation <https://en.wikipedia.org/wiki/Memory_management#DYNAMIC>`_
                    (a feature of
4bad209eba Jeff*    `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_,
76a376d977 Jeff*    not `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_), so
                    all array sizes, and hence the number of processors
ba0b047096 Mart*    to be used in your
                    `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ run,
                    must be specified at compile-time in addition to run-time. More information
                    about the MITgcm WRAPPER, domain decomposition, and how to configure
                    :filelink:`SIZE.h <model/inc/SIZE.h>`
4bad209eba Jeff*    can be found in :numref:`using_wrapper`.
76a376d977 Jeff* 
ba0b047096 Mart* #. Build the code with the :filelink:`genmake2 <tools/genmake2>` ``-mpi``
                    option using commands such as:
69e7157c80 Jeff* 
                    ::
                 
e7309a0b9d Jeff*          %  ../../../tools/genmake2 -mods=../code -mpi -of=«/PATH/TO/OPTFILE»
69e7157c80 Jeff*          %  make depend
                          %  make
                 
e7309a0b9d Jeff* .. _build_openmp:
                 
                 Building  with OpenMP
                 ---------------------
                 
ba0b047096 Mart* Unlike MPI, which requires installation of additional software support
                 libraries, using shared memory
4bad209eba Jeff* (`OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_) for multi-threaded
ba0b047096 Mart* executable builds can be accomplished simply through the
                 :filelink:`genmake2 <tools/genmake2>` command-line option ``-omp``:
4bad209eba Jeff* 
                    ::
                 
                          %  ../../../tools/genmake2 -mods=../code -omp -of=«/PATH/TO/OPTFILE»
                          %  make depend
                          %  make
                 
ba0b047096 Mart* While the most common optfiles specified in :numref:`genmake2_optfiles` include
                 support for the ``-omp`` option, some optfiles in
                 :filelink:`tools/build_options` do not include support for multi-threaded
                 executable builds. Before using one of the less common optfiles,
                 check whether ``OMPFLAG`` is defined.
4bad209eba Jeff* 
ba0b047096 Mart* Note that one does not need to specify the number of threads until runtime
                 (see :numref:`running_openmp`). However, the default maximum number of threads
                 in MITgcm is set to a (low) value of 4, so if you plan on more you will need
                 to change this value in :filelink:`eesupp/inc/EEPARAMS.h` in your modified
                 code directory.
3b0572824e Jeff* 
69e7157c80 Jeff* .. _run_the_model:
                 
516b08a580 jm-c  Running the model
69e7157c80 Jeff* =================
                 
                 If compilation finished successfully (:numref:`building_code`) then an
ba0b047096 Mart* executable called ``mitgcmuv`` will now exist in the
                 local (``build``) directory.
69e7157c80 Jeff* 
                 To run the model as a single process (i.e., not in parallel) simply
                 type (assuming you are still in the ``build`` directory):
                 
                 ::
                 
                     % cd ../run
                     % ln -s ../input/* .
                     % cp ../build/mitgcmuv .
                     % ./mitgcmuv
                 
ba0b047096 Mart* Here, we are making a link to all the support data files (in ``../input/``)
                 needed by the MITgcm for this experiment, and then copying the executable from
                 the the build directory. The ``./`` in the last step is a safe-guard to make
                 sure you use the local executable in case you have others that might exist in
                 your ``$PATH``. The above command will spew out many lines of text output to
                 your screen. This output contains details such as parameter values as well as
69e7157c80 Jeff* diagnostics such as mean kinetic energy, largest CFL number, etc. It is
                 worth keeping this text output with the binary output so we normally
                 re-direct the ``stdout`` stream as follows:
                 
                 ::
                 
                     % ./mitgcmuv > output.txt
                 
                 In the event that the model encounters an error and stops, it is very
                 helpful to include the last few line of this ``output.txt`` file along
                 with the (``stderr``) error message within any bug reports.
                 
af61fa61c7 Jeff* For the example experiment in :filelink:`verification/exp2`, an example of the
ba0b047096 Mart* output is kept in :filelink:`verification/exp2/results/output.txt` for
                 comparison. You can compare your ``output.txt`` with the corresponding one for
                 that experiment to check that your set-up indeed works. Congratulations!
69e7157c80 Jeff* 
                 .. _running_mpi:
                 
                 Running with MPI
                 ----------------
                 
ba0b047096 Mart* Run the code with the appropriate
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ “run” or
                 “exec” program provided with your particular implementation of
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_.
3b0572824e Jeff* Typical `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
ba0b047096 Mart* packages such as `Open MPI <https://www.open-mpi.org/>`_ will
                 use something like:
69e7157c80 Jeff* 
                    ::
                 
                          %  mpirun -np 4 ./mitgcmuv
                 
                 Sightly more complicated scripts may be needed for many machines
3b0572824e Jeff* since execution of the code may be controlled by both the
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ library
ba0b047096 Mart* and a job scheduling and queueing system such as
                 `Slurm <https://slurm.schedmd.com/>`_,
31584ea246 Jeff* `PBS/TORQUE <http://www.adaptivecomputing.com/products/open-source/torque>`_,
                 `LoadLeveler <https://www-03.ibm.com/systems/power/software/loadleveler/>`_,
516b08a580 jm-c  or any of a number of similar tools. See your local cluster documentation
ba0b047096 Mart* or system administrator for the specific syntax required to run on your
                 computing facility.
69e7157c80 Jeff* 
4bad209eba Jeff* .. _running_openmp:
                 
                 Running with OpenMP
                 -------------------
                 
ba0b047096 Mart* Assuming the executable ``mitgcmuv`` was built with OpenMP
                 (see :numref:`build_openmp`), the syntax to run a multi-threaded simulation is
                 the same as running single-threaded (see :numref:`run_the_model`), except that
                 the following additional steps are required beforehand:
76a376d977 Jeff* 
516b08a580 jm-c  #. `Environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
ba0b047096 Mart*    for the number of threads and the stacksize need to be set prior to
                    executing the model. The exact names of these
                    `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
                    differ by Fortran compiler, but are typically some variant of
                    ``OMP_NUM_THREADS`` and ``OMP_STACKSIZE``, respectively.
76a376d977 Jeff*    For the latter, in your run script we recommend adding the line
                    ``export OMP_STACKSIZE=400M``  (or for a
ba0b047096 Mart*    `C shell <https://en.wikipedia.org/wiki/C_shell>`_-variant,
                    ``setenv OMP_STACKSIZE 400M``). If this stacksize setting is insufficient,
                    MITgcm will crash, in which case a larger number can be used. Similarly,
                    ``OMP_NUM_THREADS`` should be set to the exact number of threads you require.
                 
                 #. In file ``eedata`` you will need to change namelist parameters :varlink:`nTx`
                    and :varlink:`nTy` to reflect the number of threads in x and y, respectively
                    (for a single-threaded run, :varlink:`nTx` \=\ :varlink:`nTy`\ =1).
76a376d977 Jeff*    The value of :varlink:`nTx` \*\ :varlink:`nTy` must equal the value of
ba0b047096 Mart*    `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
                    ``OMP_NUM_THREADS`` (or its name-equivalent for your Fortan compiler) or
                    MITgcm will terminate during its initialization with an error message.
                 
                 MITgcm will take the number of tiles used in the model (as specified in
                 :filelink:`SIZE.h <model/inc/SIZE.h>`) and the number of threads
                 (:varlink:`nTx` and :varlink:`nTy` from file ``eedata``),
                 and in running will spread the tiles out evenly across the threads.
                 This is done independently for x and y. As such,
                 the number of tiles in x (variable :varlink:`nSx` as defined in
                 :filelink:`SIZE.h <model/inc/SIZE.h>`) must divide evenly by
76a376d977 Jeff* the number of threads in x (namelist parameter :varlink:`nTx`),
ba0b047096 Mart* and similarly for :varlink:`nSy` and :varlink:`nTy`, else MITgcm will
                 terminate on initialization. More information about the MITgcm
                 WRAPPER, domain decomposition, and how to configure
                 :filelink:`SIZE.h <model/inc/SIZE.h>` can be found in :numref:`using_wrapper`.
24adb58dd2 Jean* 
69e7157c80 Jeff* Output files
                 ------------
                 
76a376d977 Jeff* The model produces various output files and, when using :filelink:`pkg/mnc`
                 (i.e., `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_),
69e7157c80 Jeff* sometimes even directories. Depending upon the I/O package(s) selected
ba0b047096 Mart* at compile time (either :filelink:`pkg/mdsio`, :filelink:`pkg/mnc`, or both as
                 determined by ``packages.conf``) and the run-time flags set (in
                 ``data.pkg``), the following output may appear. More complete information
                 describing output files and model diagnostics is described
                 in :numref:`outp_pack`.
69e7157c80 Jeff* 
9ce7d74115 Jeff* Raw binary output files
                 ~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff* 
516b08a580 jm-c  The “traditional” output files are generated by the :filelink:`pkg/mdsio`
ba0b047096 Mart* (see :numref:`pkg_mdsio`).The :filelink:`pkg/mdsio` model data are written
                 according to a “meta/data” file format. Each variable is associated with two
                 files with suffix names ``.data`` and ``.meta``. The ``.data`` file contains
                 the data written in binary form (big endian by default). The ``.meta`` file
69e7157c80 Jeff* is a “header” file that contains information about the size and the
                 structure of the ``.data`` file. This way of organizing the output is
516b08a580 jm-c  particularly useful when running multi-processors calculations.
69e7157c80 Jeff* 
                 At a minimum, the instantaneous “state” of the model is written out,
                 which is made of the following files:
                 
                 -  ``U.00000nIter`` - zonal component of velocity field (m/s and
                    positive eastward).
                 
                 -  ``V.00000nIter`` - meridional component of velocity field (m/s and
                    positive northward).
                 
                 -  ``W.00000nIter`` - vertical component of velocity field (ocean: m/s
                    and positive upward, atmosphere: Pa/s and positive towards increasing
                    pressure i.e., downward).
                 
                 -  ``T.00000nIter`` - potential temperature (ocean:
ce0d9af5ea Jeff*    :math:`^{\circ}\mathrm{C}`, atmosphere: :math:`\mathrm{K}`).
69e7157c80 Jeff* 
ba0b047096 Mart* -  ``S.00000nIter`` - ocean: salinity (g/kg), atmosphere: water vapor
69e7157c80 Jeff*    (g/kg).
                 
                 -  ``Eta.00000nIter`` - ocean: surface elevation (m), atmosphere:
                    surface pressure anomaly (Pa).
                 
                 The chain ``00000nIter`` consists of ten figures that specify the
                 iteration number at which the output is written out. For example,
                 ``U.0000000300`` is the zonal velocity at iteration 300.
                 
                 In addition, a “pickup” or “checkpoint” file called:
                 
                 -  ``pickup.00000nIter``
                 
                 is written out. This file represents the state of the model in a
ba0b047096 Mart* condensed form and is used for restarting the integration (at the specific
                 iteration number). Some additional parameterizations and packages also produce
                 separate pickup files, e.g.,
69e7157c80 Jeff* 
ba0b047096 Mart* -  ``pickup_cd.00000nIter`` if the C-D scheme is used (see
                    :ref:`C_D Scheme <C-D_scheme>`)
69e7157c80 Jeff* 
ba0b047096 Mart* -  ``pickup_seaice.00000nIter`` if the seaice package is turned on (see
                    :ref:`sub_phys_pkg_seaice`)
69e7157c80 Jeff* 
ba0b047096 Mart* -  ``pickup_ptracers.00000nIter`` if passive tracers are included in the
                    simulation (see :ref:`sub_phys_pkg_ptracers`)
69e7157c80 Jeff* 
                 Rolling checkpoint files are
                 the same as the pickup files but are named differently. Their name
                 contain the chain ``ckptA`` or ``ckptB`` instead of ``00000nIter``. They
                 can be used to restart the model but are overwritten every other time
                 they are output to save disk space during long integrations.
                 
9ce7d74115 Jeff* NetCDF output files
                 ~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff* 
9ce7d74115 Jeff* :filelink:`pkg/mnc` is a set of routines written to read, write, and
                 append `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ files.
ba0b047096 Mart* Unlike the :filelink:`pkg/mdsio` output, the :filelink:`pkg/mnc`–generated
                 output is usually placed within a subdirectory with a name such as
ce0d9af5ea Jeff* ``mnc_output_`` (by default,
ba0b047096 Mart* `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ tries to append,
                 rather than overwrite, existing files,
69e7157c80 Jeff* so a unique output directory is helpful for each separate run).
                 
ba0b047096 Mart* The :filelink:`pkg/mnc` output files are all in the “self-describing”
                 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ format and
69e7157c80 Jeff* can thus be browsed and/or plotted using tools such as:
                 
af61fa61c7 Jeff* -  `ncdump <https://www.unidata.ucar.edu/software/netcdf/netcdf-4/newdocs/netcdf/ncdump.html>`_
ba0b047096 Mart*    is a utility which is typically included with every
                    `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
                    install, and converts the
                    `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ binaries
                    into formatted ASCII text files.
69e7157c80 Jeff* 
af61fa61c7 Jeff* -  `ncview <http://meteora.ucsd.edu/~pierce/ncview_home_page.html>`_
ba0b047096 Mart*    is a very convenient and quick way to plot
                    `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
                    data and it runs on most platforms.
                    `Panoply <https://www.giss.nasa.gov/tools/panoply/>`_ is a similar
                    alternative.
                 
                 -  `MATLAB <https://www.mathworks.com/products/matlab.html>`_,
                    `GrADS <http://cola.gmu.edu/grads/>`_,
                    `IDL <http://www.harrisgeospatial.com/SoftwareTechnology/IDL.aspx>`_ and
                    other common post-processing environments provide
9ce7d74115 Jeff*    built-in `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ interfaces.
                 
69e7157c80 Jeff* Looking at the output
                 ---------------------
                 
9ce7d74115 Jeff* MATLAB
                 ~~~~~~
69e7157c80 Jeff* 
9ce7d74115 Jeff* Raw binary output
                 ^^^^^^^^^^^^^^^^^
69e7157c80 Jeff* 
ba0b047096 Mart* The repository includes a few
                 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ utilities to read
                 binary output files written in the :filelink:`/pkg/mdsio` format. The
                 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ scripts are located
                 in the directory :filelink:`utils/matlab` under the root tree. The script
                 :filelink:`utils/matlab/rdmds.m` reads the data. Look at the comments inside
                 the script to see how to use it.
69e7157c80 Jeff* 
ba0b047096 Mart* Some examples of reading and visualizing some output in
                 `MATLAB <https://www.mathworks.com/products/matlab.html>`_:
69e7157c80 Jeff* 
                 ::
                 
                     % matlab
                     >> H=rdmds('Depth');
                     >> contourf(H');colorbar;
                     >> title('Depth of fluid as used by model');
                 
                     >> eta=rdmds('Eta',10);
                     >> imagesc(eta');axis ij;colorbar;
                     >> title('Surface height at iter=10');
                 
83cdbd2346 Jeff*     >> [eta,iters,M]=rdmds('Eta',NaN); % this will read all dumped iterations
                     >> % iter numbers put in variable 'iters'; 'M' is a character string w/metadata
                     >> for n=1:length(iters); imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
                 
ba0b047096 Mart* Typing ``help rdmds`` in
                 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ will pull up further
83cdbd2346 Jeff* information on how to use the :filelink:`rdmds <utils/matlab/rdmds.m>` utility.
69e7157c80 Jeff* 
516b08a580 jm-c  NetCDF output
9ce7d74115 Jeff* ^^^^^^^^^^^^^
69e7157c80 Jeff* 
ba0b047096 Mart* Similar scripts for `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
                 output (e.g., :filelink:`utils/matlab/rdmnc.m`) are available and they
9ce7d74115 Jeff* are described in :numref:`pkg_mnc`.
69e7157c80 Jeff* 
7621b5d564 Oliv* .. _sec_python:
                 
9ce7d74115 Jeff* Python
                 ~~~~~~
69e7157c80 Jeff* 
ba0b047096 Mart* Install the MITgcmutils python package following the instructions in
                 :numref:`MITgcmutils`.
7621b5d564 Oliv* 
9ce7d74115 Jeff* Raw binary output
                 ^^^^^^^^^^^^^^^^^
69e7157c80 Jeff* 
                 The following example shows how to load in some data:
                 
                 ::
516b08a580 jm-c  
69e7157c80 Jeff*     # python
7621b5d564 Oliv*     from MITgcmutils import mds
69e7157c80 Jeff* 
                     Eta = mds.rdmds('Eta', itrs=10)
                 
83cdbd2346 Jeff* For more information about this function and its options,
7621b5d564 Oliv* see the API docs, :meth:`MITgcmutils.mds.rdmds`.
69e7157c80 Jeff* 
516b08a580 jm-c  NetCDF output
9ce7d74115 Jeff* ^^^^^^^^^^^^^
69e7157c80 Jeff* 
9ce7d74115 Jeff* The `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ output
ba0b047096 Mart* is currently produced with one file per processor. This means the individual
                 tiles need to be stitched together to create a single
                 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ file that spans the
                 model domain. The script :filelink:`utils/python/MITgcmutils/scripts/gluemncbig`
                 can do this efficiently from the command line.  If you have installed the
                 MITgcmutils package, a copy of gluemncbig should be on your path.  For usage
                 information, see :numref:`gluemncbig`.
                 
                 The following example shows how to use the
                 `xarray python package <http://xarray.pydata.org/>`_ to read
                 the resulting `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ file
                 into `Python <https://www.python.org/>`_:
9ce7d74115 Jeff* 
69e7157c80 Jeff* ::
516b08a580 jm-c  
69e7157c80 Jeff*   # python
                   import xarray as xr
                 
                   Eta = xr.open_dataset('Eta.nc')
                 
dcaaa42497 Jeff* .. _customize_compilation:
                 
                 Customizing the Model Configuration - Code Parameters and Compilation Options
                 =============================================================================
                 
                 Model Array Dimensions
                 ----------------------     
                 
                 MITgcm’s array dimensions need to be configured for each unique model domain.
ba0b047096 Mart* The size of each tile (in dimensions :math:`x`, :math:`y`, and vertical
                 coordinate :math:`r`) the “overlap” region of each tile (in :math:`x` and
                 :math:`y`), the number of tiles in the :math:`x` and :math:`y` dimensions,
                 and the number of processes (using
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_)
                 in the :math:`x` and :math:`y` dimensions all need to be specified in
                 :filelink:`SIZE.h <model/inc/SIZE.h>`. From these parameters, global
                 domain-size variables :varlink:`Nx`, :varlink:`Ny` are computed by the model.
                 See a more technical discussion of :filelink:`SIZE.h <model/inc/SIZE.h>`
                 parameters in in :numref:`specify_decomp`, and a detailed explanation of an
                 example :filelink:`SIZE.h <model/inc/SIZE.h>` setup in tutorial
                 :ref:`Baroclinic Ocean Gyre <baroc_code_size>`.
dcaaa42497 Jeff* 
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Default :filelink:`SIZE.h <model/inc/SIZE.h>`    | Description                                                                                             |
                 +========================================+==================================================+=========================================================================================================+
                 | :varlink:`sNx`                         | 30                                               | number of points in :math:`x` dimension in a single tile                                                |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`sNy`                         | 15                                               | number of points in :math:`y` dimension in a single tile                                                |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`Nr`                          | 4                                                | number of points in :math:`r` dimension                                                                 |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`OLx`                         | 2                                                | number of “overlap” points in :math:`x` dimension for a tile                                            |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`OLy`                         | 2                                                | number of “overlap” points in :math:`y` dimension for a tile                                            |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nSx`                         | 2                                                | number of tile per process in :math:`x` dimension                                                       |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nSy`                         | 4                                                | number of tile per process in :math:`y` dimension                                                       |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nPx`                         | 1                                                | number of processes in :math:`x` dimension                                                              |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nPy`                         | 1                                                | number of processes in :math:`y` dimension                                                              |
                 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
ba0b047096 Mart* Note the repository version of :filelink:`SIZE.h <model/inc/SIZE.h>` includes
                 several lines of text at the top that will halt compilation with errors. Thus,
                 to use MITgcm you will need to copy :filelink:`SIZE.h <model/inc/SIZE.h>` to a
                 code modification directory and make edits, including deleting or commenting
                 out the offending lines of text.
dcaaa42497 Jeff* 
                 C Preprocessor Options
                 ----------------------
                 
                 The CPP flags relative to the “numerical model” part of the code are
ba0b047096 Mart* defined and set in the file :filelink:`CPP_OPTIONS.h <model/inc/CPP_OPTIONS.h>`
                 in the directory :filelink:`model/inc/`. In the parameter tables in
                 :numref:`customize_model` we have noted CPP options **that need to be changed
                 from the default** to enable specific runtime parameter to be used properly.
                 Also note many of the options below are for less-common situations or are
                 somewhat obscure, so newer users of the MITgcm are encouraged to jump to
                 :numref:`customize_model` where more basic runtime parameters are discussed.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.475}|\Y{.1}|\Y{.45}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | CPP Flag Name                                 | Default | Description                                                                                                          |
                    +===============================================+=========+======================================================================================================================+
                    | :varlink:`SHORTWAVE_HEATING`                  | #undef  | provide separate shortwave heating file, allowing shortwave to penetrate below surface layer                         |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_GEOTHERMAL_FLUX`              | #undef  | include code for applying geothermal heat flux at the bottom of the ocean                                            |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_FRICTION_HEATING`             | #undef  | include code to allow heating due to friction (and momentum dissipation)                                             |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_ADDFLUID`                     | #undef  | allow mass source or sink of fluid in the interior (3D generalization of oceanic real-fresh water flux)              |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ATMOSPHERIC_LOADING`                | #define | include code for atmospheric pressure-loading (and seaice-loading) on ocean surface                                  |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_BALANCE_FLUXES`               | #undef  | include balancing surface forcing fluxes code                                                                        |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_BALANCE_RELAX`                | #undef  | include balancing surface forcing relaxation code                                                                    |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`CHECK_SALINITY_FOR_NEGATIVE_VALUES` | #undef  | include code checking for negative salinity                                                                          |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`EXCLUDE_FFIELDS_LOAD`               | #undef  | exclude external forcing-fields load; code allows reading and simple linear time interpolation of oceanic            |
                    |                                               |         | forcing fields, if no specific pkg (e.g., :filelink:`pkg/exf`) is used to compute them                               |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0bad585a21 Navi*    | :varlink:`INCLUDE_PHIHYD_CALCULATION_CODE`    | #define | include code to calculate :math:`\phi_{\rm hyd}`                                                                     |
a332812c22 Jeff*    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`INCLUDE_CONVECT_CALL`               | #define | include code for convective adjustment mixing algorithm                                                              |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`INCLUDE_CALC_DIFFUSIVITY_CALL`      | #define | include codes that calculates (tracer) diffusivities and viscosities                                                 |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_3D_DIFFKR`                    | #undef  | allow full 3D specification of vertical diffusivity                                                                  |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_BL79_LAT_VARY`                | #undef  | allow latitudinally varying Bryan and Lewis 1979 :cite:`bryan:79` vertical diffusivity                               |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`EXCLUDE_PCELL_MIX_CODE`             | #undef  | exclude code for partial-cell effect (physical or enhanced) in vertical mixing; this allows accounting               |
                    |                                               |         | for partial-cell in vertical viscosity and diffusion, either from grid-spacing reduction effect or as                |
                    |                                               |         | artificially enhanced mixing near surface & bottom for too thin grid-cell                                            |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
dafe4f37ba Jean*    | :varlink:`ALLOW_SMAG_3D_DIFFUSIVITY`          | #undef  | include code for isotropic 3-D Smagorinsky diffusivity for tracers (viscosity scaled by constant Prandtl number)     |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*    | :varlink:`ALLOW_SOLVE4_PS_AND_DRAG`           | #undef  | include code for combined surface pressure and drag implicit solver                                                  |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`INCLUDE_IMPLVERTADV_CODE`           | #define | include code for implicit vertical advection                                                                         |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_ADAMSBASHFORTH_3`             | #undef  | include code for Adams-Bashforth 3rd-order                                                                           |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
5e119ceb68 Jeff*    | :varlink:`ALLOW_QHYD_STAGGER_TS`              | #undef  | include code for quasi-hydrostatic stagger time-step Adams-Bashforth code                                            |
dafe4f37ba Jean*    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*    | :varlink:`EXACT_CONSERV`                      | #define | include code for  “exact conservation" of fluid in free-surface formulation                                          |
                    |                                               |         | (recompute divergence after pressure solver)                                                                         |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`NONLIN_FRSURF`                      | #undef  | allow the use of non-linear free-surface formulation; implies that grid-cell thickness (hFactors) varies with time   |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_NONHYDROSTATIC`               | #undef  | include non-hydrostatic and 3D pressure solver codes                                                                 |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_EDDYPSI`                      | #undef  | include GM-like eddy stress in momentum code (untested, not recommended)                                             |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_CG2D_NSA`                     | #undef  | use non-self-adjoint (NSA) conjugate-gradient solver                                                                 |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ALLOW_SRCG`                         | #define | include code for single reduction conjugate gradient solver                                                          |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`SOLVE_DIAGONAL_LOWMEMORY`           | #undef  | low memory footprint (not suitable for AD) choice for implicit solver routines solve_*diagonal.F                     |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`SOLVE_DIAGONAL_KINNER`              | #undef  | choice for implicit solver routines solve_*diagonal.F suitable for AD                                                |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`COSINEMETH_III`                     | #define | selects implementation form of :math:`\cos{\varphi}` scaling of bi-harmonic term for viscosity                       |
                    |                                               |         | (note, CPP option for tracer diffusivity set independently in                                                        |
                    |                                               |         | :filelink:`GAD_OPTIONS.h <pkg/generic_advdiff/GAD_OPTIONS.h>`)                                                       |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`ISOTROPIC_COS_SCALING`              | #undef  | selects isotropic scaling of harmonic and bi-harmonic viscous terms when using the :math:`\cos{\varphi}` scaling     |
                    |                                               |         | (note, CPP option for tracer diffusivity set independently in                                                        |
                    |                                               |         | :filelink:`GAD_OPTIONS.h <pkg/generic_advdiff/GAD_OPTIONS.h>`)                                                       |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
94151a9b18 Jeff* .. _default_pkg_list:
                 
ba0b047096 Mart* By default, MITgcm includes several core packages, i.e., these packages are
                 enabled during :filelink:`genmake2 <tools/genmake2>` execution if a file
                 ``packages.conf`` is not found. See :numref:`using_packages` for more
                 information about ``packages.conf``, and see :filelink:`pkg/pkg_groups` for
                 more information about default packages and package groups.
dcaaa42497 Jeff* These default packages are as follows:
                 
                 - :filelink:`pkg/mom_common`
                 - :filelink:`pkg/mom_fluxform`
                 - :filelink:`pkg/mom_vecinv`
                 - :filelink:`pkg/generic_advdiff`
                 - :filelink:`pkg/debug`
                 - :filelink:`pkg/mdsio`
                 - :filelink:`pkg/rw`
                 - :filelink:`pkg/monitor`
                 
ba0b047096 Mart* Additional CPP options that affect the model core code are set in files
                 ``${PKG}_OPTIONS.h`` located in these packages' directories. Similarly,
                 optional (non-default) packages also include package-specific CPP options that
                 must be set in files ``${PKG}_OPTIONS.h``.
dcaaa42497 Jeff* 
bcfb652725 Jeff* .. _cpp_eeoptions_doc:
                 
                 Preprocessor Execution Environment Options
                 ------------------------------------------
                 
                 **Most MITgcm users can skip this section**; many of these flags were
                 intended for very specific platform environments, and not meant to be changed
                 for more general environments (an exception being if you are using a coupled
                 setup, see below).
                 
                 The file :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` in the
                 directory :filelink:`eesupp/inc/` contains a number of CPP flags related to
                 the execution environment where the model will run. Below we describe the
                 subset of user-editable CPP flags:
                 
                 .. tabularcolumns:: |\Y{.475}|\Y{.1}|\Y{.45}|
                 
                 .. table::
                    :class: longtable
                    :name: cpp_eeopt_flags
                 
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | CPP Flag Name                                 | Default | Description                                                                                                          |
                    +===============================================+=========+======================================================================================================================+
                    | :varlink:`GLOBAL_SUM_ORDER_TILES`             | #define | always cumulate tile local-sum in the same order by applying MPI allreduce to array of tiles                         |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`CG2D_SINGLECPU_SUM`                 | #undef  | alternative way of doing global sum on a single CPU  to eliminate tiling-dependent roundoff errors                   |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`SINGLE_DISK_IO`                     | #undef  | to write STDOUT, STDERR and scratch files from process 0 only                                                        |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`USE_FORTRAN_SCRATCH_FILES`          | #undef  | flag to turn on old default of opening scratch files with the STATUS='SCRATCH' option                                |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`COMPONENT_MODULE`                   | #undef  | control use of communication with other components, i.e., sets component to work with a coupler interface            |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`DISCONNECTED_TILES`                 | #undef  | use disconnected tiles (no exchange between tiles, just fill-in edges assuming locally periodic subdomain)           |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                    | :varlink:`REAL4_IS_SLOW`                      | #define | if undefined, force ``_RS`` variables to be declared as real*4                                                       |
                    +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
                 
                 The default setting of ``#define`` :varlink:`GLOBAL_SUM_ORDER_TILES` in
                 :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` provides a way to
                 achieve numerically reproducible global sums for a given tile domain
                 decomposition. As implemented however, this
                 approach will increase the volume of network traffic in a way that scales
                 with the total number of tiles.
                 Profiling has shown that letting the code fall through to a baseline
                 approach that simply uses
                 `MPI_Allreduce() <https://www.open-mpi.org/doc/v3.0/man3/MPI_Allreduce.3.php>`_
                 can provide significantly improved performance for certain simulations [#]_.
                 The fall-though approach is activated by ``#undef``
                 :varlink:`GLOBAL_SUM_ORDER_TILES`.
                 
                 In order to get bit-wise reproducible results between different tile domain
                 decompositions (e.g., single tile on single processor versus multiple tiles
                 either on single or multiple processors), one can choose to ``#define``
                 option :varlink:`CG2D_SINGLECPU_SUM` to use the **MUCH** slower
                 :filelink:`global_sum_singlecpu.F <eesupp/src/global_sum_singlecpu.F>`
                 for the key part of MITgcm algorithm :filelink:`CG2D <model/src/cg2d.F>`
                 that relies on global sum.
                 This option is not only much slower but also requires a large volume of
                 communications so it is practically unusable for a large set-up;
                 furthermore, it does not address reproducibility when global sum is used
                 outside :filelink:`CG2D <model/src/cg2d.F>`, e.g., in non-hydrostatic simulations.
                 
                 In a default multi-processor configuration, each process opens and reads its
                 own set of namelist files and open and writes its own standard output. This can
                 be slow or even problematic for very large processor counts. Defining the
                 CPP-flag :varlink:`SINGLE_DISK_IO` suppresses this behavior and lets only the
                 master process (process 0) read namelist files and write a standard output
                 stream. This may seem advantageous, because it reduces the amount of seemingly
                 redundant output, but use this option with caution and only when absolutely
                 confident that the setup is working since any message (error/warning/print)
                 from any processor :math:`\ne 0` will be lost.
                 
                 The way the namelist files are read requires temporary (scratch) files in the
                 initialization phase. By default, the MITgcm does not use intrinsic Fortran
                 scratch files (``STATUS='scratch'``) because they can lead to conflicts in
                 multi-processor simulations on some HPC-platforms, when the processors do not
                 open scratch files with reserved names. However, the implemented default scheme
                 for the scratch files can be slow for large processor counts. If this is a
                 problem in a given configuration, defining the CPP-flag
                 :varlink:`USE_FORTRAN_SCRATCH_FILES` may help by making the code use the
                 intrinsic Fortran scratch files.
                 
                 The CPP-flag :varlink:`COMPONENT_MODULE` needs to be set to ``#define`` only for
                 builds in which the MITgcm executable (for either an oceanic or atmospheric
                 simulation) is configured to communicate with a coupler.
                 This coupler can be a specially configured build of MITgcm itself;
                 see, for example, verification experiment `cpl_aim+ocn
                 <https://github.com/MITgcm/MITgcm/tree/master/verification/cpl_aim+ocn>`_.
                 
                 The CPP-flag :varlink:`DISCONNECTED_TILES` should not be ``#define``
                 unless one wants to run simultaneously several small, single-tile ensemble
                 members from a single process, as each tile will be disconnected from the others
                 and considered locally as a doubly periodic patch.
                 
                 ..
                     should reference the to-be-written section about _RS, _RL within chapter 6
                 
                 MITgcm ``_RS`` variables are forced to be declared as
                 ``real*4`` if CPP-flag :varlink:`REAL4_IS_SLOW` to is set to ``#undef``
                 in :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>`
                 (``_RS`` is a macro used in declaring real variables that, in principle,
                 do not require double precision). However, this option is not recommended
                 except for computational benchmarking or for testing the trade-off between memory
                 footprint and model precision.  And even for these specialized tests, there is no need
                 to edit :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>`
                 since this feature can be activated using the :filelink:`genmake2 <tools/genmake2>`
                 command line option ``-use_r4``,  as done in some regression tests
                 (see testing `results <https://mitgcm.org/testing-summary>`_
                 page tests with optfile suffix ``.use_r4``).
                 
                 .. [#] One example is the llc_540 case located at
                    https://github.com/MITgcm-contrib/llc_hires/tree/master/llc_540. This case
                    was run on the Pleiades computer for 20 simulated days using 767 and 2919
                    MPI ranks.  At 767 ranks, the fall-through approach provided a throughput of
                    to 799.0 simulated days per calendar day (dd/d) while the default approach
                    gave 781.0.  The profiler showed the speedup was directly attributable to
                    spending less time in MPI_Allreduce. The volume of memory traffic associated
                    with MPI_Allreduce dropped by 3 orders (22.456T -> 32.596G).  At 2819 MPI
                    ranks the fall-through approach gave a throughput of 1300 dd/d while the
                    default approach gave 800.0 dd/d. Put another way, this case did not scale
                    at all from 767p to 2819p unless the fall-though approach was utilized. The
                    profiler showed the speedup was directly attributable to spending less time
                    in MPI_Allreduce. The volume of memory traffic associated with MPI_Allreduce
                    dropped by 3 orders (303.70T ->121.08G ).
dcaaa42497 Jeff* 
af61fa61c7 Jeff* .. _customize_model:
                 
dcaaa42497 Jeff* Customizing the Model Configuration - Runtime Parameters
                 ========================================================
69e7157c80 Jeff* 
                 When you are ready to run the model in the configuration you want, the
ba0b047096 Mart* most straightforward approach is to use and adapt the setup of a tutorial or
                 verification experiment (described in :numref:`chap_modelExamples`) that is the
                 closest to your configuration. Then, the amount of setup will be minimized.
                 In this section, we document the complete list of MITgcm model namelist runtime
dcaaa42497 Jeff* parameters set in file ``data``, which needs to be located in the
516b08a580 jm-c  directory where you will run the model.
dcaaa42497 Jeff* Model parameters are defined and
ba0b047096 Mart* declared in the file :filelink:`PARAMS.h <model/inc/PARAMS.h>` and their
                 default values are generally set in the routine
                 :filelink:`set_defaults.F <model/src/set_defaults.F>`, otherwise
                 when initialized in the routine :filelink:`ini_parms.F <model/src/ini_parms.F>`.
                 :numref:`eedata_parms` documents the “execution environment” namelist parameters
dcaaa42497 Jeff* in file ``eedata``, which must also reside in the current run directory.
ba0b047096 Mart* Note that runtime parameters used by (non-default) MITgcm packages are not
                 documented here but rather in :numref:`packagesI`
                 and :numref:`outp_pack`, and prescribed in package-specific ``data.${pkg}``
                 namelist files which are read in via package-specific
                 ``${pkg}_readparms.F`` where ``${pkg}`` is the package name
dcaaa42497 Jeff* (see :numref:`using_packages`).
69e7157c80 Jeff* 
dcaaa42497 Jeff* In what follows, model parameters are grouped into categories related to
ba0b047096 Mart* configuration/computational domain, algorithmic parameters, equations solved
                 in the model, parameters related to model forcing, and simulation controls.
                 The tables below specify the namelist parameter name, the namelist parameter
                 group in ``data`` (and ``eedata`` in :numref:`eedata_parms`), the default
                 value, and a short description of its function. Runtime parameters that
                 require **non-default** CPP options to be set prior to compilation
                 (see :numref:`customize_compilation`) for proper use are noted.
dcaaa42497 Jeff* 
516b08a580 jm-c  Parameters: Configuration, Computational Domain, Geometry, and Time-Discretization
dcaaa42497 Jeff* ----------------------------------------------------------------------------------
                 
                 .. _model_config_parms:
                 
                 Model Configuration
                 ~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff* 
ba0b047096 Mart* :varlink:`buoyancyRelation` is set to ``OCEANIC`` by default, which employes a
                 :math:`z`-coordinate vertical axis. To simulate an ocean using pressure
                 coordinates in the vertical, set it to ``OCEANICP``. For atmospheric
                 simulations, :varlink:`buoyancyRelation` needs to be set to ``ATMOSPHERIC``,
                 which also uses pressure as the vertical coordinate.
                 The default model configuration is hydrostatic; to run a non-hydrostatic
                 simulation, set the logical variable :varlink:`nonHydrostatic` to ``.TRUE.``.
69e7157c80 Jeff* 
dcaaa42497 Jeff* .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
69e7157c80 Jeff* 
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`buoyancyRelation`            | PARM01    | OCEANIC                                          | buoyancy relation (``OCEANIC``, ``OCEANICP``, or ``ATMOSPHERIC``)                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`quasiHydrostatic`            | PARM01    | FALSE                                            | quasi-hydrostatic formulation on/off flag                                                               |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`rhoRefFile`                  | PARM01    | :kbd:`' '`                                       | filename for reference density profile (kg/m\ :sup:`3`); activates anelastic form of model              |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nonHydrostatic`              | PARM01    | FALSE                                            | non-hydrostatic formulation on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC`               |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
69e7157c80 Jeff* 
                 Grid
dcaaa42497 Jeff* ~~~~     
                 
                 Four different grids are available: Cartesian, spherical polar, cylindrical, and
                 curvilinear (which includes the cubed sphere). The grid is set
                 through the logical variables :varlink:`usingCartesianGrid`,
                 :varlink:`usingSphericalPolarGrid`, :varlink:`usingCylindricalGrid`,
ba0b047096 Mart* and :varlink:`usingCurvilinearGrid`. Note that the cylindrical grid is designed
                 for modeling a rotating tank, so that :math:`x` is the azimuthual direction,
                 :math:`y` is the radial direction, and :math:`r` is vertical coordinate
                 (see tutorial :ref:`rotating tank <sec_eg_tank>`).
dcaaa42497 Jeff* 
                 The variable :varlink:`xgOrigin` sets the position of the western
ba0b047096 Mart* most gridcell face in the :math:`x` dimension (Cartesian, meters; spherical and
                 cyclindrical, degrees). For a Cartesian or spherical grid, the southern boundary
                 is defined through the variable :varlink:`ygOrigin` which corresponds to the
                 latitude of the southern most gridcell face (Cartesian, meters; spherical,
                 degrees). For a cyclindrical grid, a positive :varlink:`ygOrigin` (m) adds an
                 inner cylindrical boundary at the center of the tank. The resolution
                 along the :math:`x` and :math:`y` directions is controlled by the 1-D arrays
                 :varlink:`delX` (meters for a Cartesian grid, degrees otherwise)
                 and :varlink:`delY` (meters for Cartesian and cyclindrical grids, degrees
                 spherical). On a spherical polar grid, you might decide to set the variable
                 :varlink:`cosPower` which is set to 0 by default and which represents :math:`n`
                 in :math:`(\cos\varphi)^n`, the power of cosine of latitude to
dcaaa42497 Jeff* multiply horizontal viscosity and tracer diffusivity.
83cdbd2346 Jeff* The vertical grid spacing is set through the 1-D array
ba0b047096 Mart* :varlink:`delR` (:math:`z`-coordinates: in meters; :math:`p`-coordinates,
                 in Pa). Using a curvilinear grid requires complete specification of all
                 horizontal MITgcm grid variables, either through a default filename (link to
                 new doc section) or as specified by :varlink:`horizGridFile`.
dcaaa42497 Jeff* 
                 The variable :varlink:`seaLev_Z` represents the standard
                 position of sea level, in meters. This is typically set to 0 m
ba0b047096 Mart* for the ocean (default value). If instead pressure is used as the vertical
                 coordinate, the pressure at the top (of the atmosphere or ocean) is set through
                 :varlink:`top_Pres`, typically 0 Pa. As such, these variables are analogous to
                 :varlink:`xgOrigin` and :varlink:`ygOrigin` to define the vertical grid axis.
                 But they also are used for a second purpose: in a :math:`z`-coordinate setup,
                 :varlink:`top_Pres` sets a reference top pressure (required in a non-linear
                 equation of state computation, for example); note that 1 bar
                 (i.e., typical Earth atmospheric sea-level pressure) is added already, so the
                 default is 0 Pa. Similarly, for a :math:`p`-coordinate setup,
                 :varlink:`seaLev_Z` is used to set a reference geopotential (after gravity
                 scaling) at the top of the ocean or bottom of the atmosphere.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`usingCartesianGrid`          | PARM04    | TRUE                                             | use Cartesian grid/coordinates on/off flag                                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`usingSphericalPolarGrid`     | PARM04    | FALSE                                            | use spherical grid/coordinates on/off flag                                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`usingCylindricalGrid`        | PARM04    | FALSE                                            | use cylindrical grid/coordinates on/off flag                                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`usingCurvilinearGrid`        | PARM04    | FALSE                                            | use curvilinear grid/coordinates on/off flag                                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`xgOrigin`                    | PARM04    | 0.0                                              | west edge :math:`x`-axis origin (Cartesian: m; spherical and cyclindrical: degrees longitude)           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`ygOrigin`                    | PARM04    | 0.0                                              | South edge :math:`y`-axis origin (Cartesian and cyclindrical: m; spherical: degrees latitude)           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`dxSpacing`                   | PARM04    | unset                                            | :math:`x`-axis uniform grid spacing, separation between cell faces                                      |
                    |                                        |           |                                                  | (Cartesian: m; spherical and cyclindrical: degrees)                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delX`                        | PARM04    | :varlink:`dxSpacing`                             | 1D array of :math:`x`-axis grid spacing, separation between cell faces                                  |
                    |                                        |           |                                                  | (Cartesian: m; spherical and cyclindrical: degrees)                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delXFile`                    | PARM04    | :kbd:`' '`                                       | filename containing 1D array of :math:`x`-axis grid spacing                                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`dySpacing`                   | PARM04    | unset                                            | :math:`y`-axis uniform grid spacing, separation between cell faces                                      |
                    |                                        |           |                                                  | (Cartesian and cyclindrical: m; spherical: degrees)                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delY`                        | PARM04    | :varlink:`dySpacing`                             | 1D array of :math:`x`-axis grid spacing, separation between cell faces                                  |
                    |                                        |           |                                                  | (Cartesian and cyclindrical: m; spherical: degrees)                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delYFile`                    | PARM04    | :kbd:`' '`                                       | filename containing 1D array of :math:`y`-axis grid spacing                                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`cosPower`                    | PARM01    | 0.0                                              | power law :math:`n` in :math:`(\cos\varphi)^n` factor for horizontal (harmonic or biharmonic)           |
                    |                                        |           |                                                  | viscosity and tracer diffusivity (spherical polar)                                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delR`                        | PARM04    | computed using delRc                             | vertical grid spacing 1D array ([:math:`r`] unit)                                                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delRc`                       | PARM04    | computed using delR                              | vertical cell center spacing 1D array ([:math:`r`] unit)                                                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delRFile`                    | PARM04    | :kbd:`' '`                                       | filename for vertical grid spacing 1D array ([:math:`r`] unit)                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`delRcFile`                   | PARM04    | :kbd:`' '`                                       | filename for vertical cell center spacing 1D array ([:math:`r`] unit)                                   |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`rSphere`                     | PARM04    | 6.37E+06                                         | radius of sphere for spherical polar or curvilinear grid (m)                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`seaLev_Z`                    | PARM04    | 0.0                                              | reference height of sea level (m)                                                                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`top_Pres`                    | PARM04    | 0.0                                              | top pressure (:math:`p`-coordinates) or top reference pressure (:math:`z`-coordinates) (Pa)             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`selectFindRoSurf`            | PARM01    | 0                                                | select method to determine surface reference pressure from orography (atmos.-only)                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`horizGridFile`               | PARM04    | :kbd:`' '`                                       | filename containing full set of horizontal grid variables (curvilinear)                                 |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`radius_fromHorizGrid`        | PARM04    | :varlink:`rSphere`                               | radius of sphere used in input curvilinear horizontal grid file (m)                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`phiEuler`                    | PARM04    | 0.0                                              | Euler angle, rotation about original :math:`z`-axis (spherical polar)  (degrees)                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`thetaEuler`                  | PARM04    | 0.0                                              | Euler angle, rotation about new :math:`x`-axis (spherical polar)  (degrees)                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`psiEuler`                    | PARM04    | 0.0                                              | Euler angle, rotation about new :math:`z`-axis (spherical polar)  (degrees)                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
9c8516d9da Jeff* .. _parms_topo:
                 
69e7157c80 Jeff* Topography - Full and Partial Cells
dcaaa42497 Jeff* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                 
ba0b047096 Mart* For the ocean, the topography is read from a file that contains a
                 2-D(:math:`x,y`) map of bathymetry, in meters for :math:`z`-coordinates, in
                 pascals for :math:`p`-coordinates. The bathymetry is specified by entering the
                 vertical position of the ocean floor relative to the surface, so by convention
                 in :math:`z`-coordinates bathymetry is specified as negative numbers (“depth”
                 is defined as positive-definite) whereas in :math:`p`-coordinates
dcaaa42497 Jeff* bathymetry data is positive. The file name is represented by the variable
ba0b047096 Mart* :varlink:`bathyFile`. See our introductory tutorial setup :numref:`sec_eg_baro`
                 for additional details on the file format. Note no changes are required in the
                 model source code to represent enclosed, periodic, or double periodic
dcaaa42497 Jeff* domains: periodicity is assumed by default and is suppressed by
                 setting the depths to 0 m for the cells at the limits of the
                 computational domain.
                 
                 To use the partial cell capability, the variable :varlink:`hFacMin` needs
                 to be set to a value between 0.0 and 1.0 (it is set to 1.0 by default)
                 corresponding to the minimum fractional size of a gridcell. For
                 example, if a gridcell is 500 m thick and :varlink:`hFacMin` is set to
ba0b047096 Mart* 0.1, the minimum thickness for a “thin-cell” for this specific gridcell is 50 m.
                 Thus, if the specified bathymetry depth were to fall exactly
                 in the middle of this 500m thick gridcell, the initial model variable
                 :varlink:`hFacC`\ (:math:`x,y,r`) would be set to 0.5.
                 If the specified bathymetry depth fell within the top 50m of this gridcell
                 (i.e., less than :varlink:`hFacMin`), the model bathymetry would snap to the
                 nearest legal value (i.e., initial :varlink:`hFacC`\ (:math:`x,y,r`) would be
                 equal to 0.0 or 0.1 depending if the depth was within 0-25 m or 25-50 m,
                 respectively). Also note while specified bathymetry bottom depths (or
                 pressures) need not coincide with the model's levels as deduced from
                 :varlink:`delR`, any depth falling below the model's defined vertical axis is
                 truncated.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
de49ce6f4b Ed D* 
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`bathyFile`                   | PARM05    | :kbd:`' '`                                       | filename for 2D bathymetry (ocean) (:math:`z`-coor.: m, negative; :math:`p`-coor.: Pa, positive)        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`topoFile`                    | PARM05    | :kbd:`' '`                                       | filename for 2D surface topography (atmosphere) (m)                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`addWwallFile`                | PARM05    | :kbd:`' '`                                       | filename for 2D western cell-edge “thin-wall”                                                           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`addSwallFile`                | PARM05    | :kbd:`' '`                                       | filename for 2D southern cell-edge “thin-wall”                                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`hFacMin`                     | PARM01    | 1.0E+00                                          | minimum fraction size of a cell                                                                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`hFacMinDr`                   | PARM01    | 1.0E+00                                          | minimum dimensional size of a cell ([:math:`r`] unit)                                                   |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`hFacInf`                     | PARM01    | 2.0E-01                                          | lower threshold fraction for surface cell;                                                              |
                    |                                        |           |                                                  | for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>`              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`hFacSup`                     | PARM01    | 2.0E+00                                          | upper threshold fraction for surface cell;                                                              |
                    |                                        |           |                                                  | for non-linear free surface, only see parameter :ref:`nonlinFreeSurf <free_surface_parms>`              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useMin4hFacEdges`            | PARM04    | FALSE                                            | set :varlink:`hFacW`, :varlink:`hFacS` as minimum of adjacent :varlink:`hFacC` on/off flag              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`pCellMix_select`             | PARM04    | 0                                                | option/factor to enhance mixing at the surface or bottom (0- 99)                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`pCellMix_maxFac`             | PARM04    | 1.0E+04                                          | maximum enhanced mixing factor for too thin partial-cell (non-dim.)                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`pCellMix_delR`               | PARM04    | 0.0                                              | thickness criteria for too thin partial-cell ([:math:`r`] unit)                                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
                 Physical Constants
                 ~~~~~~~~~~~~~~~~~~
                 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`rhoConst`                    | PARM01    | :varlink:`rhoNil`                                | vertically constant reference density (Boussinesq) (kg/m\ :sup:`3`)                                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`gravity`                     | PARM01    | 9.81E+00                                         | gravitational acceleration (m/s\ :sup:`2`)                                                              |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
516b08a580 jm-c  | :varlink:`gravityFile`                 | PARM01    | :kbd:`' '`                                       | filename for 1D gravity vertical profile (m/s\ :sup:`2`)                                                |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`gBaro`                       | PARM01    | :varlink:`gravity`                               | gravity constant in barotropic equation (m/s\ :sup:`2`)                                                 |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Rotation
                 ~~~~~~~~
                 
                 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
                 
                 For a Cartesian or cylindical grid, the Coriolis parameter :math:`f` is set
ba0b047096 Mart* through the variables :varlink:`f0` (in s\ :sup:`--1`) and :varlink:`beta`
                 (:math:`\frac{\partial f}{ \partial y}`; in m\ :sup:`--1`\ s\ :sup:`--1`),
                 which corresponds to a Coriolis parameter  :math:`f = f_o + \beta y`
                 (the so-called :math:`\beta`\ -plane).
dcaaa42497 Jeff* 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`rotationPeriod`              | PARM01    | 8.6164E+04                                       | rotation period (s)                                                                                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`omega`                       | PARM01    | :math:`2\pi/`\ :varlink:`rotationPeriod`         | angular velocity (rad/s)                                                                                |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`selectCoriMap`               | PARM01    | depends on grid                                  | Coriolis map options                                                                                    |
                 |                                        |           | (Cartesian and cylindrical=1,                    |                                                                                                         |
                 |                                        |           | spherical and curvilinear=2)                     | - 0: f-plane                                                                                            |
                 |                                        |           |                                                  | - 1: beta-plane                                                                                         |
                 |                                        |           |                                                  | - 2: spherical Coriolis (:math:`=2\Omega\sin{\varphi}`)                                                 |
                 |                                        |           |                                                  | - 3: read 2D field from file                                                                            |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`f0`                          | PARM01    | 1.0E-04                                          | reference Coriolis parameter (Cartesian or cylindrical grid) (1/s)                                      |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`beta`                        | PARM01    | 1.0E-11                                          | :math:`\beta` (Cartesian or cylindrical grid) (m\ :sup:`--1`\ s\ :sup:`--1`)                            |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`fPrime`                      | PARM01    | 0.0                                              | :math:`2 \Omega \cos{\phi}` parameter (Cartesian or cylindical grid) (1/s); i.e., for                   |
dcaaa42497 Jeff* |                                        |           |                                                  | :math:`\cos{\varphi}` Coriolis terms from horizontal component of rotation vector                       |
                 |                                        |           |                                                  | (also sometimes referred to as reciprocal Coriolis parm.)                                               |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 .. _free_surface_parms:
                 
                 Free Surface
                 ~~~~~~~~~~~~
                 
ba0b047096 Mart* The logical variables :varlink:`rigidLid` and :varlink:`implicitFreeSurface`
                 specify your choice for ocean upper boundary (or lower boundary if using
                 :math:`p`-coordinates); set one to ``.TRUE.`` and the other to ``.FALSE.``.
                 These settings affect the calculations of surface pressure (for the ocean) or
dcaaa42497 Jeff* surface geopotential (for the atmosphere); see :numref:`parms-main_algorithm`.
                 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`implicitFreeSurface`         | PARM01    | TRUE                                             | implicit free surface on/off flag                                                                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`rigidLid`                    | PARM01    | FALSE                                            | rigid lid on/off flag                                                                                   |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useRealFreshWaterFlux`       | PARM01    | FALSE                                            | use true E-P-R freshwater flux (changes free surface/sea level) on/off flag                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`implicSurfPress`             | PARM01    | 1.0E+00                                          | implicit fraction of the surface pressure gradient (0-1)                                                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`implicDiv2Dflow`             | PARM01    | 1.0E+00                                          | implicit fraction of the barotropic flow divergence (0-1)                                               |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`implicitNHPress`             | PARM01    | :varlink:`implicSurfPress`                       | implicit fraction of the non-hydrostatic pressure gradient (0-1);                                       |
                    |                                        |           |                                                  | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>`                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`nonlinFreeSurf`              | PARM01    | 0                                                | non-linear free surface options (-1,0,1,2,3; see :numref:`nonlinFreeSurf-flags`);                       |
                    |                                        |           |                                                  | requires #define :varlink:`NONLIN_FRSURF`                                                               |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`select_rStar`                | PARM01    | 0                                                | vertical coordinate option                                                                              |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | - 0: use r                                                                                              |
                    |                                        |           |                                                  | - >0: use :math:`r^*`                                                                                   |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | see :numref:`nonlinFreeSurf-flags`; requires #define :varlink:`NONLIN_FRSURF`                           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`selectNHfreeSurf`            | PARM01    | 0                                                | non-hydrostatic free surface formulation option                                                         |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | - 0: don’t use                                                                                          |
                    |                                        |           |                                                  | - >0: use                                                                                               |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | requires non-hydrostatic formulation, see parameter :ref:`nonHydrostatic <model_config_parms>`          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`exactConserv`                | PARM01    | FALSE                                            | exact total volume conservation (recompute divergence after pressure solver) on/off flag                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
69e7157c80 Jeff* Time-Discretization
dcaaa42497 Jeff* ~~~~~~~~~~~~~~~~~~~
                 
                 The time steps are set through the real variables :varlink:`deltaTMom` and
                 :varlink:`deltaTtracer` (in seconds) which represent the time step for the
ba0b047096 Mart* momentum and tracer equations, respectively (or you can prescribe a single
                 time step value for all parameters using :varlink:`deltaT`). The model “clock”
                 is defined by the variable :varlink:`deltaTClock` (in seconds)
dcaaa42497 Jeff* which determines the I/O frequencies and is used in tagging output.
                 Time in the model is thus computed as:
                 
ba0b047096 Mart* |  model time = :varlink:`baseTime` + iteration number  * :varlink:`deltaTClock`
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 |  :varlink:`deltaT`                     | PARM03    | 0.0                                              | default value used for model time step parameters (s)                                                   |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`deltaTClock`                | PARM03    | :varlink:`deltaT`                                | timestep used for model clock (s): used for I/O frequency and tagging output and checkpoints            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`deltaTmom`                  | PARM03    | :varlink:`deltaT`                                | momentum equation timestep (s)                                                                          |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`deltaTtracer`               | PARM03    | :varlink:`deltaT`                                | tracer equation timestep (s)                                                                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`dTtracerLev`                | PARM03    | :varlink:`deltaTtracer`                          | tracer equation timestep specified at each vertical level (s)                                           |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`deltaTfreesurf`             | PARM03    | :varlink:`deltaTmom`                             | free-surface equation timestep (s)                                                                      |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`baseTime`                    | PARM03    | 0.0                                              | model base time corresponding to iteration 0 (s)                                                        |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 .. _parms-main_algorithm:
                 
                 Parameters: Main Algorithmic Parameters
                 ---------------------------------------
                 
                 Pressure Solver
                 ~~~~~~~~~~~~~~~
                 
                 By default, a hydrostatic
ba0b047096 Mart* simulation is assumed and a 2-D elliptic equation is used to invert the
                 pressure field. If using a non-hydrostatic configuration, the pressure field is
                 inverted through a 3-D elliptic equation (note this capability is not yet
                 available for the atmosphere). The parameters controlling the behavior of the
dcaaa42497 Jeff* elliptic solvers are the variables :varlink:`cg2dMaxIters` and
83cdbd2346 Jeff* :varlink:`cg2dTargetResidual` for the 2-D case and :varlink:`cg3dMaxIters` and
                 :varlink:`cg3dTargetResidual` for the 3-D case.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`cg2dMaxIters`                | PARM02    | 150                                              | upper limit on 2D conjugate gradient solver iterations                                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`cg2dTargetResidual`          | PARM02    | 1.0E-07                                          | 2D conjugate gradient target residual (non-dim. due to RHS normalization )                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`cg2dTargetResWunit`          | PARM02    | -1.0E+00                                         | 2D conjugate gradient target residual (:math:`\dot{r}` units);                                          |
                    |                                        |           |                                                  | <0: use RHS normalization, i.e., :varlink:`cg2dTargetResidual` instead                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`cg2dPreCondFreq`             | PARM02    | 1                                                | frequency (in number of iterations) for updating cg2d pre-conditioner;                                  |
                    |                                        |           |                                                  | for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>`              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`cg2dUseMinResSol`            | PARM02    | 0 unless flat-bottom, Cartesian                  | - 0: use last-iteration/converged cg2d solution                                                         |
                    |                                        |           |                                                  | - 1: use solver minimum-residual solution                                                               |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`cg3dMaxIters`                | PARM02    | 150                                              | upper limit on 3D conjugate gradient solver iterations; requires #define :varlink:`ALLOW_NONHYDROSTATIC`|
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`cg3dTargetResidual`          | PARM02    | 1.0E-07                                          | 3D conjugate gradient target residual (non-dim. due to RHS normalization );                             |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_NONHYDROSTATIC`                                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e6e223b277 Jean*    | :varlink:`cg3dTargetResWunit`          | PARM02    | -1.0E+00                                         | 3D conjugate gradient target residual (:math:`\dot{r}` units);                                          |
                    |                                        |           |                                                  | <0: use RHS normalization, i.e., :varlink:`cg3dTargetResidual` instead                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*    | :varlink:`useSRCGSolver`               | PARM02    | FALSE                                            | use conjugate gradient solver with single reduction (single call of mpi_allreduce)                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`printResidualFreq`           | PARM02    | 1 unless :varlink:`debugLevel` >4                | frequency (in number of iterations) of printing conjugate gradient residual                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`integr_GeoPot`               | PARM01    | 2                                                | select method to integrate geopotential                                                                 |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | - 1: finite volume                                                                                      |
                    |                                        |           |                                                  | - :math:`\neq`\ 1: finite difference                                                                    |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`uniformLin_PhiSurf`          | PARM01    | TRUE                                             | use uniform :math:`b_s` relation for :math:`\phi_s` on/off flag                                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`deepAtmosphere`              | PARM04    | FALSE                                            | don’t make the thin shell/shallow water approximation                                                   |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`nh_Am2`                      | PARM01    | 1.0E+00                                          | non-hydrostatic terms scaling factor; requires #define :varlink:`ALLOW_NONHYDROSTATIC`                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
                 Time-Stepping Algorithm
                 ~~~~~~~~~~~~~~~~~~~~~~~
                 
                 The Adams-Bashforth stabilizing parameter is set through the
                 variable :varlink:`abEps` (dimensionless). The stagger baroclinic time
                 stepping algorithm can be activated by setting the logical variable
                 :varlink:`staggerTimeStep` to ``.TRUE.``.
                 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`abEps`                       | PARM03    | 1.0E-02                                          | Adams-Bashforth-2 stabilizing weight (non-dim.)                                                         |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`alph_AB`                     | PARM03    | 0.5E+00                                          | Adams-Bashforth-3 primary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3`         |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`beta_AB`                     | PARM03    | 5/12                                             | Adams-Bashforth-3 secondary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3`       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`staggerTimeStep`             | PARM01    | FALSE                                            | use staggered time stepping (thermodynamic vs. flow variables) on/off flag                              |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`multiDimAdvection`           | PARM01    | TRUE                                             | use multi-dim. advection algorithm in schemes where non multi-dim. is possible on/off flag              |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`implicitIntGravWave`         | PARM01    | FALSE                                            | treat internal gravity waves implicitly on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC`   |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
69e7157c80 Jeff* .. _parms-eos:
                 
                 Parameters: Equation of State
                 -----------------------------
                 
dcaaa42497 Jeff* The form of the equation of state is controlled by the model configuration
516b08a580 jm-c  and :varlink:`eosType`.
dcaaa42497 Jeff* 
516b08a580 jm-c  For the atmosphere, :varlink:`eosType` must be set to ``IDEALGAS``.
dcaaa42497 Jeff* 
                 For the ocean, several forms of the equation of state are
                 available:
                 
                 - For a linear approximation, set :varlink:`eosType` to ``LINEAR``),
                   and you will need to specify the thermal
                   and haline expansion coefficients, represented by the variables
ba0b047096 Mart*   :varlink:`tAlpha` (in K\ :sup:`--1`) and :varlink:`sBeta`
                   (in (g/kg)\ :sup:`--1`).
dcaaa42497 Jeff*   Because the model equations are written in terms of
                   perturbations, a reference thermodynamic state needs to be specified.
ba0b047096 Mart*   This is done through the 1-D arrays :varlink:`tRef` and :varlink:`sRef`.
                   :varlink:`tRef` specifies the reference potential temperature profile (in
                   :sup:`o`\ C for the ocean and K for the atmosphere) starting
                   from the level k=1. Similarly, :varlink:`sRef` specifies the reference
                   salinity profile (in g/kg) for the ocean or the reference specific
dcaaa42497 Jeff*   humidity profile (in g/kg) for the atmosphere.
                 
                 - MITgcm offers several approximations to the full (oceanic) non-linear equation
                   of state that can be selected as :varlink:`eosType`:
                 
516b08a580 jm-c     ``'POLYNOMIAL'``:
ba0b047096 Mart*     This approximation is based on the Knudsen formula (see Bryan and Cox 1972
                     :cite:`bryan:72`). For this option you need to generate a file of polynomial
dcaaa42497 Jeff*     coefficients called ``POLY3.COEFFS``. To do this, use the program
ba0b047096 Mart*     :filelink:`utils/knudsen2/knudsen2.f` under the model tree (a ``Makefile``
                     is available in the same directory; you will need to edit the number and
                     the values of the vertical levels in
                     :filelink:`knudsen2.f <utils/knudsen2/knudsen2.f>`
dcaaa42497 Jeff*     so that they match those of your configuration).
                 
                    ``’UNESCO’``:
                     The UNESCO equation of state formula (IES80) of Fofonoff and Millard (1983)
69e7157c80 Jeff*     :cite:`fofonoff:83`. This equation of state assumes
dcaaa42497 Jeff*     in-situ temperature, which is not a model variable; **its use is
                     therefore discouraged**.
69e7157c80 Jeff* 
dcaaa42497 Jeff*    ``’JMD95Z’``:
69e7157c80 Jeff*     A modified UNESCO formula by Jackett and McDougall (1995)
                     :cite:`jackett:95`, which uses the model variable
                     potential temperature as input. The ’Z’ indicates that this
                     equation of state uses a horizontally and temporally constant
                     pressure :math:`p_{0}=-g\rho_{0}z`.
                 
dcaaa42497 Jeff*    ``’JMD95P’``:
69e7157c80 Jeff*     A modified UNESCO formula by Jackett and McDougall (1995)
                     :cite:`jackett:95`, which uses the model variable
                     potential temperature as input. The ’P’ indicates that this
                     equation of state uses the actual hydrostatic pressure of the last
                     time step. Lagging the pressure in this way requires an additional
                     pickup file for restarts.
                 
dcaaa42497 Jeff*    ``’MDJWF’``:
                     A more accurate and less expensive equation of state than UNESCO by
                     McDougall et al. (2003) :cite:`mcdougall:03`, also using the model variable
                     potential temperature as input. It also requires
69e7157c80 Jeff*     lagging the pressure and therefore an additional pickup file for
                     restarts.
                 
dcaaa42497 Jeff*    ``’TEOS10’``:
ba0b047096 Mart*     TEOS-10 is based on a Gibbs function formulation from which all
                     thermodynamic properties of seawater (density, enthalpy, entropy sound
                     speed, etc.) can be derived in a thermodynamically consistent manner;
                     see http://www.teos-10.org. See IOC et al. (2010) :cite:`ioc:10`, McDougall
                     and Parker (2011) :cite:`mcdougall:11`, and Roquet et al. (2015)
                     :cite:`roquet:15` for implementation details.
                     It also requires lagging the pressure and therefore an additional pickup
                     file for restarts. Note at this time a full implementation of TEOS10 (i.e.,
                     ocean variables of conservative temperature and practical salinity,
dcaaa42497 Jeff*     including consideration of surface forcings) has not been implemented;
ba0b047096 Mart*     also note the original 48-term polynomial term is used, not the newer,
                     preferred 75-term polynomial.
                 
                    For these non-linear approximations, neither a reference profile of
                    temperature or salinity is required, except for a setup where
                    :varlink:`implicitIntGravWave` is set to ``.TRUE.`` or
                    :varlink:`selectP_inEOS_Zc`\ =1.
                 
                 Note that for simplicity, salinity is expressed as a ratio in g/kg (thus
                 effectively unitless) regardless of the choice of equation of state,
                 despite "Practical Salinity" not precisely equal to salinity expressed as a
                 dissolved mass fraction. If TEOS-10 is selected, the model variable
                 :varlink:`salt` can be interpreted as "Absolute Salinity". See Millero (2010)
                 :cite:`millero:10` and Pawlowicz (2013) :cite:`pawlowicz:13` for detailed
                 discussion of salinity measurements, and why being expressed
                 as g/kg is preferred, in the context of the ocean equation of state.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`eosType`                     | PARM01    | LINEAR                                           | equation of state form                                                                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tRef`                        | PARM01    | 20.0 :sup:`o`\ C (ocn) or 300.0 K (atm)          | 1D vertical reference temperature profile (:sup:`o`\ C or K)                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tRefFile`                    | PARM01    | :kbd:`' '`                                       | filename for reference temperature profile (:sup:`o`\ C or K)                                           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`thetaConst`                  | PARM01    | :varlink:`tRef`\ (k=1)                           | vertically constant reference temp. for atmosphere :math:`p^*` coordinates (:sup:`o`\ K);               |
                    |                                        |           |                                                  | for ocean, specify instead of :varlink:`tRef` or :varlink:`tRefFile`                                    |
                    |                                        |           |                                                  | for vertically constant reference temp. (:sup:`o`\ C )                                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*    | :varlink:`sRef`                        | PARM01    | 30.0 (g/kg) (ocn) or 0.0 (atm)                   | 1D vertical reference salinity profile (g/kg)                                                           |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*    | :varlink:`sRefFile`                    | PARM01    | :kbd:`' '`                                       | filename for reference salinity profile (g/kg)                                                          |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`selectP_inEOS_Zc`            | PARM01    | depends on :varlink:`eosType`                    | select which pressure to use in EOS for :math:`z`-coor.                                                 |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | -  0: use :math:`-g \rho_c z`                                                                           |
                    |                                        |           |                                                  | -  1: use :math:`p_{ref} = -\int{-g\rho(T_{ref},S_{ref},p_{ref})dz}`                                    |
                    |                                        |           |                                                  | -  2: hydrostatic dynamical pressure                                                                    |
                    |                                        |           |                                                  | -  3: use full hyd.+non-hyd. pressure                                                                   |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | for ``JMD95P``, ``UNESCO``, ``MDJWF``, ``TEOS10`` default=2,  otherwise default =0                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`rhonil`                      | PARM01    | 9.998E+02                                        | reference density for linear EOS (kg/m\ :sup:`3`)                                                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tAlpha`                      | PARM01    | 2.0E-04                                          | linear EOS thermal expansion coefficient (1/\ :sup:`o`\ C)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*    | :varlink:`sBeta`                       | PARM01    | 7.4E-04                                          | linear EOS haline contraction coefficient ((g/kg)\ :sup:`-1`)                                           |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
                 Thermodynamic Constants
                 ~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff* 
dcaaa42497 Jeff* .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.175}|\Y{.55}|
69e7157c80 Jeff* 
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`HeatCapacity_Cp`             | PARM01    | 3.994E+03                                        | specific heat capacity C\ :sub:`p` (ocean) (J/kg/K)                                                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`celsius2K`                   | PARM01    | 2.7315E+02                                       | conversion constant :sup:`o`\ C to Kelvin                                                               |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`atm_Cp`                      | PARM01    | 1.004E+03                                        | specific heat capacity C\ :sub:`p` dry air at const. press. (J/kg/K)                                    |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`atm_Rd`                      | PARM01    | :varlink:`atm_Cp`\*(2/7)                         | gas constant for dry air (J/kg/K)                                                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`atm_Rq`                      | PARM01    | 0.0                                              | water vapor specific volume anomaly relative to dry air (g/kg)                                          |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`atm_Po`                      | PARM01    | 1.0E+05                                          | atmosphere standard reference pressure (for potential temp. defn.)  (Pa)                                |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
69e7157c80 Jeff* 
9c8516d9da Jeff* .. _parms_mom:
                 
dcaaa42497 Jeff* Parameters: Momentum Equations
                 ------------------------------
69e7157c80 Jeff* 
dcaaa42497 Jeff* Configuration
                 ~~~~~~~~~~~~~
69e7157c80 Jeff* 
dcaaa42497 Jeff* There are a few logical variables that allow you to turn on/off various
                 terms in the momentum equation. These variables are called
                 :varlink:`momViscosity`, :varlink:`momAdvection`,  :varlink:`useCoriolis`,
ba0b047096 Mart* :varlink:`momStepping`, :varlink:`metricTerms`, and
                 :varlink:`momPressureForcing` and by default are set to ``.TRUE.``.
                 Vertical diffusive fluxes of momentum can be computed implicitly
dcaaa42497 Jeff* by setting the logical variable :varlink:`implicitViscosity` to
ba0b047096 Mart* ``.TRUE.``. The details relevant to both the momentum flux-form and the
                 vector-invariant form of the equations and the various (momentum) advection
                 schemes are covered in :numref:`discret_algorithm`.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`momStepping`                 | PARM01    | TRUE                                             | momentum equation time-stepping on/off flag                                                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`momViscosity`                | PARM01    | TRUE                                             | momentum friction terms on/off flag                                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`momAdvection`                | PARM01    | TRUE                                             | advection of momentum on/off flag                                                                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`momPressureForcing`          | PARM01    | TRUE                                             | pressure term in momentum equation on/off flag                                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`metricTerms`                 | PARM01    | TRUE                                             | include metric terms (spherical polar, momentum flux-form) on/off flag                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useNHMTerms`                 | PARM01    | FALSE                                            | use "non-hydrostatic form" of metric terms on/off flag; (see :numref:`non_hyd_metric_terms`;            |
                    |                                        |           |                                                  | note these terms are non-zero in many model configurations beside non-hydrostatic)                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`momImplVertAdv`              | PARM01    | FALSE                                            | momentum implicit vertical advection on/off flag; requires #define :varlink:`INCLUDE_IMPLVERTADV_CODE`  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`implicitViscosity`           | PARM01    | FALSE                                            | implicit vertical viscosity on/off flag                                                                 |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`interViscAr_pCell`           | PARM04    | FALSE                                            | account for partial-cell in interior vertical viscosity on/off flag                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`momDissip_In_AB`             | PARM03    | TRUE                                             | use Adams-Bashforth time stepping for dissipation tendency                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useCoriolis`                 | PARM01    | TRUE                                             | include Coriolis terms on/off flag                                                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`use3dCoriolis`               | PARM01    | TRUE                                             | include :math:`\cos{\varphi}` Coriolis terms on/off flag                                                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
7843dde2de jm-c     | :varlink:`selectCoriScheme`            | PARM01    | 0                                                | Coriolis scheme selector                                                                                |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | - 0: original scheme                                                                                    |
                    |                                        |           |                                                  | - 1: wet-point averaging method                                                                         |
                    |                                        |           |                                                  | - 2: Flux-Form: energy conserving; Vector-Inv: hFac weighted average                                    |
                    |                                        |           |                                                  | - 3: Flux-Form: energy conserving using wet-point method; Vector-Inv: energy conserving with hFac weight|
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`vectorInvariantMomentum`     | PARM01    | FALSE                                            | use vector-invariant form of momentum equations flag                                                    |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useJamartMomAdv`             | PARM01    | FALSE                                            | use Jamart wetpoints method for relative vorticity advection (vector invariant form) on/off flag        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`selectVortScheme`            | PARM01    | 1                                                | vorticity scheme (vector invariant form) options                                                        |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | - 0,1: enstrophy conserving forms                                                                       |
                    |                                        |           |                                                  | - 2: energy conserving form                                                                             |
                    |                                        |           |                                                  | - 3: energy and enstrophy conserving form                                                               |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | see Sadourny 1975 :cite:`sadourny:75` and Burridge & Haseler 1977 :cite:`burridge:77`                   |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    |  :varlink:`upwindVorticity`            | PARM01    | FALSE                                            | bias interpolation of vorticity in the Coriolis term (vector invariant form) on/off flag                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    |  :varlink:`useAbsVorticity`            | PARM01    | FALSE                                            | use :math:`f + \zeta` in Coriolis terms (vector invariant form) on/off flag                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    |  :varlink:`highOrderVorticity`         | PARM01    | FALSE                                            | use 3rd/4th order interpolation of vorticity (vector invariant form) on/off flag                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    |  :varlink:`upwindShear`                | PARM01    | FALSE                                            | use 1st order upwind for vertical advection (vector invariant form) on/off flag                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    |  :varlink:`selectKEscheme`             | PARM01    | 0                                                | kinetic energy computation in Bernoulli function (vector invariant form) options                        |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | - 0: standard form                                                                                      |
                    |                                        |           |                                                  | - 1: area-weighted standard form                                                                        |
                    |                                        |           |                                                  | - 2: as 0 but account for partial cells                                                                 |
                    |                                        |           |                                                  | - 3: as 1 w/partial cells                                                                               |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | see :filelink:`mom_calc_ke.F <pkg/mom_common/mom_calc_ke.F>`                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
69e7157c80 Jeff* 
dcaaa42497 Jeff* Initialization
                 ~~~~~~~~~~~~~~    
                 
                 The initial horizontal velocity components can be specified from
                 binary files :varlink:`uVelInitFile` and :varlink:`vVelInitFile`. These files
83cdbd2346 Jeff* should contain 3-D data ordered in an (:math:`x,y,r`) fashion with k=1 as the
dcaaa42497 Jeff* first vertical level (surface level). If no file names are provided,
                 the velocity is initialized to zero. The initial vertical velocity
                 is always derived from the horizontal velocity using the continuity
                 equation. In the case of a restart (from the end of a previous simulation),
ba0b047096 Mart* the velocity field is read from a pickup file
                 (see :numref:`simulation_controls`) and the initial velocity files are ignored.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`uVelInitFile`                | PARM05    | :kbd:`' '`                                       | filename for 3D specification of initial zonal velocity field (m/s)                                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`vVelInitFile`                | PARM05    | :kbd:`' '`                                       | filename for 3D specification of initial meridional velocity field (m/s)                                |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`pSurfInitFile`               | PARM05    | :kbd:`' '`                                       | filename for 2D specification of initial free surface position ([:math:`r`] unit)                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
69e7157c80 Jeff* .. _mom_dissip:
                 
dcaaa42497 Jeff* General Dissipation Scheme
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff*     
dcaaa42497 Jeff* The lateral eddy viscosity coefficient is specified through the
                 variable :varlink:`viscAh` (in m\ :sup:`2`\ s\ :sup:`--1`). The
                 vertical eddy viscosity coefficient is specified through the
                 variable :varlink:`viscAr` (in [:math:`r`]\ :sup:`2`\ s\ :sup:`--1`,
                 where [:math:`r`] is the dimension of the vertical coordinate).
                 In addition, biharmonic mixing can be added as well
                 through the variable :varlink:`viscA4` (in
516b08a580 jm-c  m\ :sup:`4`\ s\ :sup:`--1`).
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.215}|\Y{.1}|\Y{.115}|\Y{.595}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`viscAh`                      | PARM01    | 0.0                                              | lateral eddy viscosity (m\ :sup:`2`\ /s)                                                                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhD`                     | PARM01    | :varlink:`viscAh`                                | lateral eddy viscosity acts on divergence part (m\ :sup:`2`\ /s)                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhZ`                     | PARM01    | :varlink:`viscAh`                                | lateral eddy viscosity acts on vorticity part (:math:`\zeta` points) (m\ :sup:`2`\ /s)                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhW`                     | PARM01    | :varlink:`viscAhD`                               | lateral eddy viscosity for mixing vertical momentum (non-hydrostatic form) (m\ :sup:`2`\ /s);           |
                    |                                        |           |                                                  | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>`                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhDfile`                 | PARM05    | :kbd:`' '`                                       | filename for 3D specification of lateral eddy viscosity (divergence part) (m\ :sup:`2`\ /s);            |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h`          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhZfile`                 | PARM05    | :kbd:`' '`                                       | filename for 3D specification of lateral eddy viscosity (vorticity part, :math:`\zeta` points);         |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h`          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhGrid`                  | PARM01    | 0.0                                              | grid-dependent lateral eddy viscosity (non-dim.)                                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhMax`                   | PARM01    | 1.0E+21                                          | maximum lateral eddy viscosity (m\ :sup:`2`\ /s)                                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhGridMax`               | PARM01    | 1.0E+21                                          | maximum lateral eddy (grid-dependent) viscosity (non-dim.)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhGridMin`               | PARM01    | 0.0                                              | minimum lateral eddy (grid-dependent) viscosity (non-dim.)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAhReMax`                 | PARM01    | 0.0                                              | minimum lateral eddy viscosity based on Reynolds number (non-dim.)                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscC2leith`                 | PARM01    | 0.0                                              | Leith harmonic viscosity factor (vorticity part, :math:`\zeta` points) (non-dim.)                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscC2leithD`                | PARM01    | 0.0                                              | Leith harmonic viscosity factor (divergence part) (non-dim.)                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
f59d76b0dd Ed D*    | :varlink:`viscC2LeithQG`               | PARM01    | 0.0                                              | Quasi-geostrophic Leith  viscosity factor (non-dim.)                                                    |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*    | :varlink:`viscC2smag`                  | PARM01    | 0.0                                              | Smagorinsky harmonic viscosity factor (non-dim.)                                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4`                      | PARM01    | 0.0                                              | lateral biharmonic viscosity (m\ :sup:`4`\ /s)                                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4D`                     | PARM01    | :varlink:`viscA4`                                | lateral biharmonic viscosity (divergence part) (m\ :sup:`4`\ /s)                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4Z`                     | PARM01    | :varlink:`viscA4`                                | lateral biharmonic viscosity (vorticity part, :math:`\zeta` points) (m\ :sup:`4`\ /s)                   |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4W`                     | PARM01    | :varlink:`viscA4D`                               | lateral biharmonic viscosity for mixing vertical momentum (non-hydrostatic form) (m\ :sup:`4`\ /s);     |
                    |                                        |           |                                                  | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>`                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4Dfile`                 | PARM05    | :kbd:`' '`                                       | filename for 3D specification of lateral biharmonic viscosity (divergence part)  (m\ :sup:`4`\ /s);     |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h`          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4Zfile`                 | PARM05    | :kbd:`' '`                                       | filename for 3D specification of lateral biharmonic viscosity (vorticity part, :math:`\zeta` points);   |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h`          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4Grid`                  | PARM01    | 0.0                                              | grid dependent biharmonic viscosity (non-dim.)                                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4Max`                   | PARM01    | 1.0E+21                                          | maximum biharmonic viscosity (m\ :sup:`4`\ /s)                                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4GridMax`               | PARM01    | 1.0E+21                                          | maximum biharmonic (grid-dependent) viscosity (non-dim.)                                                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4GridMin`               | PARM01    | 0.0                                              | minimum biharmonic (grid-dependent) viscosity (mon-dim.)                                                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscA4ReMax`                 | PARM01    | 0.0                                              | minimum biharmonic viscosity based on Reynolds number (non-dim.)                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscC4leith`                 | PARM01    | 0.0                                              | Leith biharmonic viscosity factor (vorticity part, :math:`\zeta` points) (non-dim.)                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscC4leithD`                | PARM01    | 0.0                                              | Leith biharmonic viscosity factor (divergence part) (non-dim.)                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscC4smag`                  | PARM01    | 0.0                                              | Smagorinsky biharmonic viscosity factor (non-dim.)                                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useFullLeith`                | PARM01    | FALSE                                            | use full form of Leith viscosities on/off flag                                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useSmag3D`                   | PARM01    | FALSE                                            | use isotropic 3D Smagorinsky harmonic viscosities flag; requires #define :varlink:`ALLOW_SMAG_3D`       |
                    |                                        |           |                                                  | in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h`                                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`smag3D_coeff`                | PARM01    | 1.0E-02                                          | isotropic 3D Smagorinsky coefficient (non-dim.); requires #define :varlink:`ALLOW_SMAG_3D`              |
                    |                                        |           |                                                  | in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h`                                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useStrainTensionVisc`        | PARM01    | FALSE                                            | flag to use strain-tension form of viscous operator                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`useAreaViscLength`           | PARM01    | FALSE                                            | flag to use area for viscous :math:`L^2` instead of harmonic mean of :math:`{L_x}^2, {L_y}^2`           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscAr`                      | PARM01    | 0.0                                              | vertical eddy viscosity ([:math:`r`]\ :sup:`2`\ /s)                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`viscArNr`                    | PARM01    | 0.0                                              | vertical profile of vertical eddy viscosity ([:math:`r`]\ :sup:`2`\ /s)                                 |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`pCellMix_viscAr`             | PARM04    | :varlink:`viscArNr`                              | vertical viscosity for too thin partial-cell ([:math:`r`]\ :sup:`2`\ /s)                                |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
                 Sidewall/Bottom Dissipation
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
                 
                 Slip or no-slip conditions at lateral and bottom
                 boundaries are specified through the logical variables
                 :varlink:`no_slip_sides` and :varlink:`no_slip_bottom`. If set to
                 ``.FALSE.``, free-slip boundary conditions are applied. If no-slip
                 boundary conditions are applied at the bottom, a bottom drag can be
                 applied as well. Two forms are available: linear (set the variable
                 :varlink:`bottomDragLinear` in [:math:`r`]/s, )
                 and quadratic (set the variable
                 :varlink:`bottomDragQuadratic`, [:math:`r`]/m).
                 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`no_slip_sides`               | PARM01    | TRUE                                             | viscous BCs: no-slip sides on/off flag                                                                  |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff* | :varlink:`sideDragFactor`              | PARM01    | 2.0E+00                                          | side-drag scaling factor (2.0: full drag) (non-dim.)                                                    |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`no_slip_bottom`              | PARM01    | TRUE                                             | viscous BCs: no-slip bottom on/off flag                                                                 |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`bottomDragLinear`            | PARM01    | 0.0                                              | linear bottom-drag coefficient ([:math:`r`]/s)                                                          |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`bottomDragQuadratic`         | PARM01    | 0.0                                              | quadratic bottom-drag coefficient ([:math:`r`]/m)                                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ab47de63dc Mart* | :varlink:`zRoughBot`                   | PARM01    | 0.0                                              | roughness length for quadratic bottom friction coefficient (m)                                          |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`selectBotDragQuadr`          | PARM01    | -1                                               | select quadratic bottom drag discretization option                                                      |
                 |                                        |           |                                                  |                                                                                                         |
                 |                                        |           |                                                  | - -1: not used                                                                                          |
                 |                                        |           |                                                  | - 0: average KE from grid center to :math:`u,v` location                                                |
                 |                                        |           |                                                  | - 1: use local velocity norm @ :math:`u,v` location                                                     |
                 |                                        |           |                                                  | - 2: as 1 with wet-point averaging of other velocity component                                          |
                 |                                        |           |                                                  |                                                                                                         |
dcaaa42497 Jeff* |                                        |           |                                                  | if :varlink:`bottomDragQuadratic` :math:`\neq 0.` then default is 0                                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`selectImplicitDrag`          | PARM01    | 0                                                | top/bottom drag implicit treatment options                                                              |
                 |                                        |           |                                                  |                                                                                                         |
                 |                                        |           |                                                  | - 0: fully explicit                                                                                     |
                 |                                        |           |                                                  | - 1: implicit on provisional velocity, i.e., before :math:`\nabla \eta` increment                       |
                 |                                        |           |                                                  | - 2: fully implicit                                                                                     |
                 |                                        |           |                                                  |                                                                                                         |
dcaaa42497 Jeff* |                                        |           |                                                  | if =2, requires #define :varlink:`ALLOW_SOLVE4_PS_AND_DRAG`                                             |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`bottomVisc_pCell`            | PARM01    | FALSE                                            | account for partial-cell in bottom viscosity (using :varlink:`no_slip_bottom` = ``.TRUE.``) on/off flag |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
69e7157c80 Jeff* Parameters: Tracer Equations
                 ----------------------------
                 
dcaaa42497 Jeff* This section covers the tracer equations, i.e., the potential temperature
69e7157c80 Jeff* equation and the salinity (for the ocean) or specific humidity (for the
516b08a580 jm-c  atmosphere) equation.
dcaaa42497 Jeff* 
                 Configuration
                 ~~~~~~~~~~~~~
                 
                 The logical variables :varlink:`tempAdvection`,  and
69e7157c80 Jeff* :varlink:`tempStepping` allow you to turn on/off terms in the temperature
dcaaa42497 Jeff* equation (similarly for salinity or specific humidity with variables
                 :varlink:`saltAdvection` etc.). These variables all
                 default to a value of ``.TRUE.``.  The vertical diffusive
                 fluxes can be computed implicitly by setting the logical variable
516b08a580 jm-c  :varlink:`implicitDiffusion` to ``.TRUE.``.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`tempStepping`                | PARM01    | TRUE                                             | temperature equation time-stepping on/off flag                                                          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tempAdvection`               | PARM01    | TRUE                                             | advection of temperature on/off flag                                                                    |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tempAdvScheme`               | PARM01    | 2                                                | temperature horizontal advection scheme selector (see :numref:`adv_scheme_summary`)                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tempVertAdvScheme`           | PARM01    | :varlink:`tempAdvScheme`                         | temperature vertical advection scheme selector (see :numref:`adv_scheme_summary`)                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tempImplVertAdv`             | PARM01    | FALSE                                            | temperature implicit vertical advection on/off flag                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`addFrictionHeating`          | PARM01    | FALSE                                            | include frictional heating in temperature equation on/off flag;                                         |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_FRICTION_HEATING`                                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`temp_stayPositive`           | PARM01    | FALSE                                            | use Smolarkiewicz hack to ensure temperature stays positive on/off flag;                                |
                    |                                        |           |                                                  | requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h`     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`saltStepping`                | PARM01    | TRUE                                             | salinity equation time-stepping on/off flag                                                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`saltAdvection`               | PARM01    | TRUE                                             | advection of salinity on/off flag                                                                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`saltAdvScheme`               | PARM01    | 2                                                | salinity horizontal advection scheme selector (see :numref:`adv_scheme_summary`)                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`saltVertAdvScheme`           | PARM01    | :varlink:`saltAdvScheme`                         | salinity vertical  advection scheme selector (see :numref:`adv_scheme_summary`)                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`saltImplVertAdv`             | PARM01    | FALSE                                            | salinity implicit vertical advection on/off flag                                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`salt_stayPositive`           | PARM01    | FALSE                                            | use Smolarkiewicz hack to ensure salinity stays positive on/off flag;                                   |
                    |                                        |           |                                                  | requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h`     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`implicitDiffusion`           | PARM01    | FALSE                                            | implicit vertical diffusion on/off flag                                                                 |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`interDiffKr_pCell`           | PARM04    | FALSE                                            | account for partial-cell in interior vertical diffusion on/off flag                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
837f8d0bd9 Dhru*    | :varlink:`linFSConserveTr`             | PARM01    | FALSE                                            | correct source/sink of tracer due to use of linear free surface on/off flag                             |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`doAB_onGtGs`                 | PARM03    | TRUE                                             | apply Adams-Bashforth on tendencies (rather than on T,S) on/off flag                                    |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
69e7157c80 Jeff* Initialization
dcaaa42497 Jeff* ~~~~~~~~~~~~~~
                 
                 The initial tracer data can be contained in the binary files
                 :varlink:`hydrogThetaFile` and :varlink:`hydrogSaltFile`. These files should
83cdbd2346 Jeff* contain 3-D data ordered in an (:math:`x,y,r`) fashion with k=1 as the first
dcaaa42497 Jeff* vertical level. If no file names are provided, the tracers are then
ba0b047096 Mart* initialized with the values of :varlink:`tRef` and :varlink:`sRef` discussed in
                 :numref:`parms-eos`. In this case, the initial tracer data are uniform in
                 :math:`x` and :math:`y` for each depth level.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`hydrogThetaFile`             | PARM05    | :kbd:`' '`                                       | filename for 3D specification of initial potential temperature (:sup:`o`\ C)                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart* | :varlink:`hydrogSaltFile`              | PARM05    | :kbd:`' '`                                       | filename for 3D specification of initial salinity (g/kg)                                                |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`maskIniTemp`                 | PARM05    | TRUE                                             | apply (center-point) mask to initial hydrographic theta data on/off flag                                |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`maskIniSalt`                 | PARM05    | TRUE                                             | apply (center-point) mask to initial hydrographic salinity on/off flag                                  |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`checkIniTemp`                | PARM05    | TRUE                                             | check if initial theta (at wet-point) identically zero on/off flag                                      |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`checkIniSalt`                | PARM05    | TRUE                                             | check if initial salinity (at wet-point) identically zero on/off flag                                   |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Tracer Diffusivities
                 ~~~~~~~~~~~~~~~~~~~~     
                 
                 Lateral eddy diffusivities for temperature and salinity/specific
                 humidity are specified through the variables :varlink:`diffKhT` and
                 :varlink:`diffKhS` (in m\ :sup:`2`\ /s). Vertical eddy diffusivities are
ba0b047096 Mart* specified through the variables :varlink:`diffKrT` and :varlink:`diffKrS`.
                 In addition, biharmonic diffusivities can be specified as well through the
                 coefficients :varlink:`diffK4T` and :varlink:`diffK4S` (in m\ :sup:`4`\ /s).
                 The Gent and McWilliams parameterization for advection and mixing of oceanic
                 tracers is described in :numref:`sub_phys_pkg_gmredi`.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.15}|\Y{.575}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`diffKhT`                     | PARM01    | 0.0                                              | Laplacian diffusivity of heat laterally (m\ :sup:`2`\ /s)                                               |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffK4T`                     | PARM01    | 0.0                                              | biharmonic diffusivity of heat laterally (m\ :sup:`4`\ /s)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrT`                     | PARM01    | 0.0                                              | Laplacian diffusivity of heat vertically (m\ :sup:`2`\ /s)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKr4T`                    | PARM01    | 0.0                                              | biharmonic diffusivity of heat vertically (m\ :sup:`2`\ /s)                                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrNrT`                   | PARM01    | 0.0 at k=top                                     | vertical profile of vertical diffusivity of temperature (m\ :sup:`2`\ /s)                               |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`pCellMix_diffKr`             | PARM04    | :varlink:`diffKrNr`                              | vertical diffusivity for too thin partial-cell ([r]\ :sup:`2`\ /s)                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKhS`                     | PARM01    | 0.0                                              | Laplacian diffusivity of salt laterally (m\ :sup:`2`\ /s)                                               |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffK4S`                     | PARM01    | 0.0                                              | biharmonic diffusivity of salt laterally (m\ :sup:`4`\ /s)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrS`                     | PARM01    | 0.0                                              | Laplacian diffusivity of salt vertically (m\ :sup:`2`\ /s)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKr4S`                    | PARM01    | 0.0                                              | biharmonic diffusivity of salt vertically (m\ :sup:`2`\ /s)                                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrNrS`                   | PARM01    | 0.0 at k=top                                     | vertical profile of vertical diffusivity of salt (m\ :sup:`2`\ /s)                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrFile`                  | PARM05    | :kbd:`' '`                                       | filename for 3D specification of vertical diffusivity (m\ :sup:`2`\ /s);                                |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_3D_DIFFKR`                                                             |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBL79surf`              | PARM01    | 0.0                                              | surface diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m\ :sup:`2`\ /s)                           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBL79deep`              | PARM01    | 0.0                                              | deep diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m\ :sup:`2`\ /s)                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBL79scl`               | PARM01    | 2.0E+02                                          | depth scale for Bryan & Lewis 1979 :cite:`bryan:79` (m)                                                 |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBL79Ho`                | PARM01    | -2.0E+03                                         | turning depth for Bryan & Lewis 1979 :cite:`bryan:79` (m)                                               |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBLEQsurf`              | PARM01    | 0.0                                              | same as :varlink:`diffKrBL79surf` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY`       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBLEQdeep`              | PARM01    | 0.0                                              | same as :varlink:`diffKrBL79deep` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY`       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBLEQscl`               | PARM01    | 2.0E+02                                          | same as :varlink:`diffKrBL79scl` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY`        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`diffKrBLEQHo`                | PARM01    | -2.0E+03                                         | same as :varlink:`diffKrBL79Ho` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY`         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`BL79LatVary`                 | PARM01    | 3.0E+01                                          | transition from diffKrBLEQ to diffKrBL79 parms at this latitude;                                        |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_BL79_LAT_VARY`                                                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
94151a9b18 Jeff* .. _ocean_convection_parms:
                 
dcaaa42497 Jeff* Ocean Convection
                 ~~~~~~~~~~~~~~~~     
                 
ba0b047096 Mart* In addition to specific packages that parameterize ocean convection, two main
                 model options are available. To use the first option, a convective adjustment
                 scheme, you need to set the variable :varlink:`cadjFreq`, the frequency
                 (in seconds) with which the adjustment algorithm is called, to a non-zero value
                 (note, if :varlink:`cadjFreq` set to a negative value by the user, the model
                 will set it to the model clock time step). The second option is to parameterize
dcaaa42497 Jeff* convection with implicit vertical diffusion. To do this, set the
                 logical variable :varlink:`implicitDiffusion` to ``.TRUE.`` and the real
                 variable :varlink:`ivdc_kappa` (in m\ :sup:`2`\ /s) to
                 an appropriate tracer vertical diffusivity value for mixing
ba0b047096 Mart* due to static instabilities (typically, several orders of magnitude above the
                 background vertical diffusivity). Note that :varlink:`cadjFreq` and
dcaaa42497 Jeff* :varlink:`ivdc_kappa` cannot both have non-zero value.
                 
                 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.125}|\Y{.6}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`ivdc_kappa`                  | PARM01    | 0.0                                              | implicit vertical diffusivity for convection (m\ :sup:`2`\ /s)                                          |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff* | :varlink:`cAdjFreq`                    | PARM03    | 0                                                | frequency of convective adj. scheme; <0: sets value to :varlink:`deltaTclock` (s)                       |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`hMixCriteria`                | PARM01    | -0.8E+00                                         | - <0: specifies :math:`\Delta T` (:sup:`o`\ C) to define ML depth where                                 |
                 |                                        |           |                                                  |   :math:`\Delta\rho = \Delta T*d\rho/dT` occurs                                                         |
                 |                                        |           |                                                  | - >1: define ML depth where local strat. exceeds mean strat. by this factor (non-dim.)                  |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff* | :varlink:`hMixSmooth`                  | PARM01    | 0.0                                              | use this fraction of neighboring points (for smoothing) in ML calculation (0-1; 0: no smoothing)        |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Parameters: Model Forcing
                 -------------------------
                 
ba0b047096 Mart* The forcing options that can be prescribed through runtime parameters in
                 ``data`` are easy to use but somewhat limited in scope. More complex forcing
                 setups are possible with optional packages such as :filelink:`pkg/exf` or
                 :filelink:`pkg/rbcs`, in which case most or all of the parameters in this
                 section can simply be left at their default value.
dcaaa42497 Jeff* 
                 Momentum Forcing
                 ~~~~~~~~~~~~~~~~
                     
                 This section only applies to the ocean. You need to generate
                 wind-stress data into two files :varlink:`zonalWindFile` and
                 :varlink:`meridWindFile` corresponding to the zonal and meridional
                 components of the wind stress, respectively (if you want the stress
                 to be along the direction of only one of the model horizontal axes,
                 you only need to generate one file). The format of the files is
                 similar to the bathymetry file. The zonal (meridional) stress data
83cdbd2346 Jeff* are assumed to be in pascals and located at U-points (V-points). See the MATLAB
dcaaa42497 Jeff* program ``gendata.m`` in the ``input`` directories of
ba0b047096 Mart* ``verification`` for several tutorial example (e.g.
                 :filelink:`gendata.m <verification/tutorial_barotropic_gyre/input/gendata.m>`
dcaaa42497 Jeff* in the :ref:`barotropic gyre tutorial <sec_eg_baro>`)
                 to see how simple analytical wind forcing data are generated for the
                 case study experiments.
                 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`momForcing`                  | PARM01    | TRUE                                             | included external forcing of momentum on/off flag                                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`zonalWindFile`               | PARM05    | :kbd:`' '`                                       | filename for 2D specification of zonal component of wind forcing (N/m\ :sup:`2`)                        |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`meridWindFile`               | PARM05    | :kbd:`' '`                                       | filename for 2D specification of meridional component of wind forcing (N/m\ :sup:`2`)                   |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff* | :varlink:`momForcingOutAB`             | PARM03    | 0                                                | 1: take momentum forcing out of Adams-Bashforth time stepping                                           |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`momTidalForcing`             | PARM01    | TRUE                                             | tidal forcing of momentum equation on/off flag (requires tidal forcing files)                           |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`ploadFile`                   | PARM05    | :kbd:`' '`                                       | filename for 2D specification of atmospheric pressure loading (ocean :math:`z`-coor. only) (Pa)         |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Tracer Forcing
                 ~~~~~~~~~~~~~~     
                 
                 A combination of flux data and relaxation terms can be used for
                 driving the tracer equations. For potential temperature, heat flux
83cdbd2346 Jeff* data (in W/m\ :sup:`2`) can be stored in the 2-D binary file
dcaaa42497 Jeff* :varlink:`surfQnetfile`. Alternatively or in addition, the forcing can be
                 specified through a relaxation term. The SST data to which the model
                 surface temperatures are restored are stored in
83cdbd2346 Jeff* the 2-D binary file :varlink:`thetaClimFile`. The corresponding relaxation
dcaaa42497 Jeff* time scale coefficient is set through the variable
                 :varlink:`tauThetaClimRelax` (in seconds). The same procedure applies for
                 salinity with the variable names :varlink:`EmPmRfile`, :varlink:`saltClimFile`,
                 and :varlink:`tauSaltClimRelax` for freshwater flux (in m/s) and surface
ba0b047096 Mart* salinity (in g/kg) data files and relaxation timescale coefficient
516b08a580 jm-c  (in seconds), respectively.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.24}|\Y{.1}|\Y{.15}|\Y{.535}|
                 
a332812c22 Jeff* .. table::
                    :class: longtable
                 
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | Parameter                              | Group     | Default                                          | Description                                                                                             |
                    +========================================+===========+==================================================+=========================================================================================================+
                    | :varlink:`tempForcing`                 | PARM01    | TRUE                                             | external forcing of temperature forcing on/off flag                                                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`surfQnetFile`                | PARM05    | :kbd:`' '`                                       | filename for 2D specification of net total heat flux (W/m\ :sup:`2`)                                    |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`surfQswFile`                 | PARM05    | :kbd:`' '`                                       | filename for 2D specification of net shortwave flux (W/m\ :sup:`2`);                                    |
                    |                                        |           |                                                  | requires #define :varlink:`SHORTWAVE_HEATING`                                                           |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tauThetaClimRelax`           | PARM03    | 0.0                                              | temperature (surface) relaxation time scale (s)                                                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`lambdaThetaFile`             | PARM05    | :kbd:`' '`                                       | filename for 2D specification of inverse temperature (surface) relaxation time scale (1/s)              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`ThetaClimFile`               | PARM05    | :kbd:`' '`                                       | filename for specification of (surface) temperature relaxation values (:sup:`o`\ C)                     |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`balanceThetaClimRelax`       | PARM01    | FALSE                                            | subtract global mean heat flux due to temp. relaxation flux every time step on/off flag;                |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_BALANCE_RELAX`                                                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`balanceQnet`                 | PARM01    | FALSE                                            | subtract global mean Qnet every time step on/off flag; requires #define :varlink:`ALLOW_BALANCE_FLUXES` |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`geothermalFile`              | PARM05    | :kbd:`' '`                                       | filename for 2D specification of geothermal heating flux through bottom (W/m\ :sup:`2`);                |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_GEOTHERMAL_FLUX`                                                       |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`temp_EvPrRn`                 | PARM01    | UNSET                                            | temperature of rain and evaporated water (unset, use local temp.) (:sup:`o`\ C)                         |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`allowFreezing`               | PARM01    | FALSE                                            | limit (ocean) temperature at surface to >= -1.9\ :sup:`o`\ C                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`saltForcing`                 | PARM01    | TRUE                                             | external forcing of salinity forcing on/off flag                                                        |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*    | :varlink:`convertFW2Salt`              | PARM01    | 3.5E+01                                          | salinity used to convert freshwater flux to salt flux (-1: use local S) (g/kg)                          |
a332812c22 Jeff*    |                                        |           |                                                  | (note default is -1 if :varlink:`useRealFreshWaterFlux`\ = ``.TRUE.``)                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`rhoConstFresh`               | PARM01    | :varlink:`rhoConst`                              | constant reference density for fresh water (rain) (kg/m\ :sup:`3`)                                      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`EmPmRFile`                   | PARM05    | :kbd:`' '`                                       | filename for 2D specification of net freshwater flux (m/s)                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*    | :varlink:`saltFluxFile`                | PARM05    | :kbd:`' '`                                       | filename for 2D specification of salt flux (from seaice) ((g/kg).kg/m\ :sup:`2`\/s)                     |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tauSaltClimRelax`            | PARM03    | 0.0                                              | salinity (surface) relaxation time scale (s)                                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`lambdaSaltFile`              | PARM05    | :kbd:`' '`                                       | filename for 2D specification of inverse salinity (surface) relaxation time scale (1/s)                 |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*    | :varlink:`saltClimFile`                | PARM05    | :kbd:`' '`                                       | filename for specification of (surface) salinity relaxation values (g/kg)                               |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`balanceSaltClimRelax`        | PARM01    | FALSE                                            | subtract global mean flux due to salt relaxation every time step on/off flag                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
7e00d7e8f9 Jean*    | :varlink:`selectBalanceEmPmR`          | PARM01    | 0                                                | option to balance net surface freshwater flux every time step                                           |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | - 0: off                                                                                                |
                    |                                        |           |                                                  | - 1: uniform surface correction                                                                         |
                    |                                        |           |                                                  | - 2: non-uniform surface correction, scaled using :varlink:`wghtBalancedFile` for local weighting       |
                    |                                        |           |                                                  |                                                                                                         |
                    |                                        |           |                                                  | if =1 or 2, requires #define :varlink:`ALLOW_BALANCE_FLUXES`                                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`wghtBalanceFile`             | PARM05    | :kbd:`' '`                                       | filename for 2D specification of weights used in :varlink:`selectBalanceEmPmR` =2 correction            |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*    | :varlink:`salt_EvPrRn`                 | PARM01    | 0.0                                              | salinity of rain and evaporated water (g/kg)                                                            |
a332812c22 Jeff*    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`selectAddFluid`              | PARM01    | 0                                                | add fluid to ocean interior options (-1, 0: off, or 1); requires #define :varlink:`ALLOW_ADDFLUID`      |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`temp_addMass`                | PARM01    | :varlink:`temp_EvPrRn`                           | temp. of added or removed (interior) water (:sup:`o`\ C); requires #define :varlink:`ALLOW_ADDFLUID`    |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`salt_addMass`                | PARM01    | :varlink:`salt_EvPrRn`                           | salinity of added or removed (interior) water (:sup:`o`\ C); requires #define :varlink:`ALLOW_ADDFLUID` |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`addMassFile`                 | PARM05    | :kbd:`' '`                                       | filename for 3D specification of mass source/sink (+=source, kg/s);                                     |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_ADDFLUID`                                                              |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`balancePrintMean`            | PARM01    | FALSE                                            | print subtracted balancing means to STDOUT on/off flag;                                                 |
                    |                                        |           |                                                  | requires #define :varlink:`ALLOW_BALANCE_FLUXES` and/or #define :varlink:`ALLOW_BALANCE_RELAX`          |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`latBandClimRelax`            | PARM03    | whole domain                                     | relaxation to (T,S) climatology equatorward of this latitude band is applied                            |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                    | :varlink:`tracForcingOutAB`            | PARM03    | 0                                                | 1: take T, S, and pTracer forcing out of Adams-Bashforth time stepping                                  |
                    +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff* 
                 .. _periodic_forcing_expl:
                 
                 Periodic Forcing
                 ~~~~~~~~~~~~~~~~
                 
                 To prescribe time-dependent periodic
                 forcing, concatenate successive time records into a
                 single file ordered in a (:math:`x,y`,time) fashion
                 and set the following variables: :varlink:`periodicExternalForcing` to
ba0b047096 Mart* ``.TRUE.``, :varlink:`externForcingPeriod` to the period (in seconds between
                 two records in input files) with which
dcaaa42497 Jeff* the forcing varies (e.g., 1 month), and :varlink:`externForcingCycle`
                 to the repeat time (in seconds) of the forcing (e.g., 1 year; note
                 :varlink:`externForcingCycle` must be a multiple of
                 :varlink:`externForcingPeriod`). With these variables specified, the model
                 will interpolate the forcing linearly at each iteration.
                 
                 .. tabularcolumns:: |\Y{.25}|\Y{.1}|\Y{.125}|\Y{.55}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`periodicExternalForcing`     | PARM03    | FALSE                                            | allow time-dependent periodic forcing on/off flag                                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`externForcingPeriod`         | PARM03    | 0.0                                              | period over which forcing varies (e.g. monthly) (s)                                                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`externForcingCycle`          | PARM03    | 0.0                                              | period over which the forcing cycle repeats (e.g. one year) (s)                                         |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 .. _simulation_controls:
69e7157c80 Jeff* 
                 Parameters: Simulation Controls
                 -------------------------------
                 
dcaaa42497 Jeff* Run Start and Duration
                 ~~~~~~~~~~~~~~~~~~~~~~     
                 
                 The beginning of a simulation is set by specifying a start time (in seconds)
                 through the real variable :varlink:`startTime` or by specifying an
                 initial iteration number through the integer variable :varlink:`nIter0`. If
                 these variables are set to non-zero values, the model will look for a
ba0b047096 Mart* ”pickup” file (by default, ``pickup.0000nIter0``) to restart the integration.
                 The end of a simulation is set through the real variable :varlink:`endTime`
                 (in seconds). Alternatively, one can instead specify the number of time steps
dcaaa42497 Jeff* to execute through the integer variable :varlink:`nTimeSteps`.
ba0b047096 Mart* Iterations are referenced to :varlink:`deltaTClock`, i.e., each iteration is
                 :varlink:`deltaTClock` seconds of model time.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`nIter0`                      | PARM03    | 0                                                | starting timestep iteration number for this integration                                                 |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nTimeSteps`                  | PARM03    | 0                                                | number of (model clock) timesteps to execute                                                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nEndIter`                    | PARM03    | 0                                                | run ending timestep iteration number (alternate way to prescribe :varlink:`nTimeSteps`)                 |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`startTime`                   | PARM03    | :varlink:`baseTime`                              | run start time for this integration (s) (alternate way to prescribe :varlink:`nIter0`)                  |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`endTime`                     | PARM03    | 0.0                                              | run ending time (s) (with :varlink:`startTime`, alternate way to prescribe :varlink:`nTimeSteps`)       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Input/Output Files
                 ~~~~~~~~~~~~~~~~~~
                 
                 The precision with which to read binary data is
                 controlled by the integer variable :varlink:`readBinaryPrec`,  which can take
ba0b047096 Mart* the value 32 (single precision) or 64 (double precision). Similarly, the
                 precision with which to write binary data is controlled by the integer variable
                 :varlink:`writeBinaryPrec`. By default, MITgcm writes output (snapshots,
                 diagnostics, and pickups) separately for individual tiles, leaving it to the
                 user to reassemble these into global files, if needed (scripts are available in
                 :filelink:`utils/`). There are two options however to have the model do this
                 for you. Setting :varlink:`globalFiles` to ``.TRUE.`` should always work in a
                 single process setup (including multi-threaded processes), but for
                 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ runs this will
                 depend on the platform -- it requires simultaneous write access to a common
                 file (permissible in typical
                 `Lustre <https://en.wikipedia.org/wiki/Lustre_(file_system)>`_ setups, but not
                 on all file systems). Alternatively, one can set :varlink:`useSingleCpuIO`
                 to ``.TRUE.`` to generate global files, which should always work, but requires
                 additional mpi-passing of data and may result in slower execution.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
e52125a087 Jeff* |  :varlink:`globalFiles`                | PARM01    | FALSE                                            | write output “global” (i.e. not per tile) files on/off flag                                             |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`useSingleCpuIO`             | PARM01    | FALSE                                            | only master MPI process does I/O (producing global output files)                                        |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`the_run_name`               | PARM05    | :kbd:`' '`                                       | string identifying the name of the model "run" for meta files                                           |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`readBinaryPrec`             | PARM01    | 32                                               | precision used for reading binary files (32 or 64)                                                      |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`writeBinaryPrec`            | PARM01    | 32                                               | precision used for writing binary files (32 or 64)                                                      |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`outputTypesInclusive`       | PARM03    | FALSE                                            | allows writing of output files in multiple formats (i.e. :filelink:`pkg/mdsio` and  :filelink:`pkg/mnc`)|
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`rwSuffixType`               | PARM03    | 0                                                | controls the format of the :filelink:`pkg/mdsio` binary file “suffix”                                   |
a332812c22 Jeff* |                                        |           |                                                  |                                                                                                         |
                 |                                        |           |                                                  | - 0: use iteration number (myIter, I10.10)                                                              |
                 |                                        |           |                                                  | - 1: 100*myTime                                                                                         |
                 |                                        |           |                                                  | - 2: myTime                                                                                             |
                 |                                        |           |                                                  | - 3: myTime/360                                                                                         |
                 |                                        |           |                                                  | - 4: myTime/3600                                                                                        |
                 |                                        |           |                                                  |                                                                                                         |
                 |                                        |           |                                                  | where :varlink:`myTime` is model time in seconds                                                        |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`mdsioLocalDir`              | PARM05    | :kbd:`' '`                                       | if not blank, read-write output tiled files from/to this directory name                                 |
                 |                                        |           |                                                  | (+four-digit processor-rank code)                                                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
69e7157c80 Jeff* .. _freq_of_output:
                 
dcaaa42497 Jeff* Frequency/Amount of Output
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff* 
dcaaa42497 Jeff* The frequency (in seconds) with which output
                 is written to disk needs to be specified. :varlink:`dumpFreq` controls the
ba0b047096 Mart* frequency with which the instantaneous state of the model is written.
                 :varlink:`monitorFreq` controls the frequency with which monitor output is
                 dumped to the standard output file(s). The frequency of output is referenced
                 to :varlink:`deltaTClock`.
69e7157c80 Jeff* 
dcaaa42497 Jeff* .. tabularcolumns:: |\Y{.18}|\Y{.1}|\Y{.2}|\Y{.545}|
69e7157c80 Jeff* 
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`dumpFreq`                    | PARM03    | 0.0                                              | interval to write model state/snapshot data (s)                                                         |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`dumpInitAndLast`             | PARM03    | TRUE                                             | write out initial and last iteration model state on/off flag                                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`diagFreq`                    | PARM03    | 0.0                                              | interval to write additional intermediate (debugging cg2d/3d) output (s)                                |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`monitorFreq`                 | PARM03    | lowest of other output \*Freq parms              | interval to write monitor output (s)                                                                    |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff* | :varlink:`monitorSelect`               | PARM03    | 2 (3 if fluid is water)                          | select group of monitor variables to output                                                             |
                 |                                        |           |                                                  |                                                                                                         |
                 |                                        |           |                                                  | - 1: dynamic variables only                                                                             |
                 |                                        |           |                                                  | - 2: add vorticity variables                                                                            |
                 |                                        |           |                                                  | - 3: add surface variables                                                                              |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
5f61c21b01 Jeff* |  :varlink:`debugLevel`                 | PARM01    | depends on :varlink:`debugMode`                  | level of printing of MITgcm activity messages/statistics (1-5, higher -> more activity messages)        |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`plotLevel`                  | PARM01    | :varlink:`debugLevel`                            | controls printing of field maps (1-5, higher -> more fields)                                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Restart/Pickup Files
                 ~~~~~~~~~~~~~~~~~~~~
                 
                 :varlink:`chkPtFreq` and :varlink:`pchkPtFreq` control the output frequency of
ba0b047096 Mart* rolling and permanent pickup (a.k.a. checkpoint) files, respectively. These
                 frequencies are referenced to :varlink:`deltaTClock`.
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
69e7157c80 Jeff* 
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`pChkPtFreq`                  | PARM03    | 0.0                                              | permanent restart/pickup checkpoint file write interval ( s )                                           |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`chkPtFreq`                   | PARM03    | 0.0                                              | rolling restart/pickup checkpoint file write interval ( s )                                             |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
5f61c21b01 Jeff* | :varlink:`pickupSuff`                  | PARM03    | :kbd:`' '`                                       | force run to use pickups (even if :varlink:`nIter0` =0) and read files with this suffix (10 char. max)  |
dcaaa42497 Jeff* +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`pickupStrictlyMatch`         | PARM03    | TRUE                                             | force pickup (meta) file formats to exactly match (or terminate with error) on/off flag                 |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`writePickupAtEnd`            | PARM03    | FALSE                                            | write a (rolling) pickup file at run completion on/off flag                                             |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`usePickupBeforeC54`         | PARM01    | FALSE                                            | initialize run using old pickup format from code prior to checkpoint54a                                 |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`startFromPickupAB2`         | PARM03    | FALSE                                            | using Adams-Bashforth-3, start using Adams-Bashforth-2 pickup format;                                   |
                 |                                        |           |                                                  | requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3`                                                      |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Parameters Used In Optional Packages
                 ------------------------------------
                 
ba0b047096 Mart* Some optional packages were not written with package-specific namelist
                 parameters in a ``data.${pkg}`` file; or for historical and/or other reasons,
                 several package-specific namelist parameters remain in ``data``.
dcaaa42497 Jeff* 
                 .. _c-d_scheme:
                 
                 C-D Scheme
                 ~~~~~~~~~~     
                 
                 (package :filelink:`pkg/cd_code`)
                 
                 If you run at a sufficiently coarse resolution, you might choose to enable the
                 C-D scheme for the computation of the Coriolis terms. The
                 variable :varlink:`tauCD`, which represents the C-D scheme coupling
                 timescale (in seconds) needs to be set.
                 
                 .. tabularcolumns:: |\Y{.175}|\Y{.1}|\Y{.225}|\Y{.525}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`useCDscheme`                 | PARM01    | FALSE                                            | use C-D scheme for Coriolis terms on/off flag                                                           |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`tauCD`                       | PARM03    | :varlink:`deltaTMom`                             | C-D scheme coupling timescale (s)                                                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`rCD`                         | PARM03    | 1 - :varlink:`deltaTMom`/:varlink:`tauCD`        | C-D scheme normalized coupling parameter (non-dim.)                                                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`epsAB_CD`                    | PARM03    | :varlink:`abEps`                                 | Adams-Bashforth-2 stabilizing weight used in C-D scheme                                                 |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 Automatic Differentiation
                 ~~~~~~~~~~~~~~~~~~~~~~~~~
                 
                 (package :filelink:`pkg/autodiff`; see :numref:`chap_autodiff`)
                 
                 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`nTimeSteps_l2`               | PARM03    | 4                                                | number of inner timesteps to execute per timestep                                                       |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`adjdumpFreq`                 | PARM03    | 0.0                                              | interval to write model state/snapshot data adjoint run (s)                                             |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`adjMonitorFreq`              | PARM03    | 0.0                                              | interval to write monitor output adjoint run (s)                                                        |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 |  :varlink:`adTapeDir`                  | PARM05    | :kbd:`' '`                                       | if not blank, read-write checkpointing files from/to this directory name                                |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 
                 .. _eedata_parms:
                 
                 Execution Environment Parameters
                 --------------------------------
                 
ba0b047096 Mart* If running multi-threaded (i.e., using shared
                 memory/`OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_), you will need to set
                 :varlink:`nTx` and/or :varlink:`nTy` so that :varlink:`nTx`\ \*\ :varlink:`nTy`
                 is the total number of threads (per process).
dcaaa42497 Jeff* 
ba0b047096 Mart* The parameter :varlink:`useCubedSphereExchange` needs to be changed to
                 ``.TRUE.`` if you are using any type of grid composed of interconnected
                 individual faces, including the cubed sphere topology or a lat-lon cap grid.
                 See (needs section to be written).
dcaaa42497 Jeff* 
ba0b047096 Mart* Note that setting flag :varlink:`debugMode` to ``.TRUE.`` activates a separate
                 set of debugging print statements than parameter :varlink:`debugLevel`
                 (see :numref:`freq_of_output`). The latter controls print statements that
                 monitor model activity (such as opening files, etc.), whereas the former
                 produces a more coding-oriented set of print statements (e.g., entering and
                 exiting subroutines, etc.)
dcaaa42497 Jeff* 
                 .. tabularcolumns:: |\Y{.25}|\Y{.125}|\Y{.125}|\Y{.525}|
                 
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | Parameter                              | Group     | Default                                          | Description                                                                                             |
                 +========================================+===========+==================================================+=========================================================================================================+
                 | :varlink:`useCubedSphereExchange`      | EEPARMS   | FALSE                                            | use cubed-sphere topology domain on/off flag                                                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nTx`                         | EEPARMS   | 1                                                | number of threads in the :math:`x` direction                                                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`nTy`                         | EEPARMS   | 1                                                | number of threads in the :math:`y` direction                                                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`useCoupler`                  | EEPARMS   | FALSE                                            | communicate with other model components through a coupler on/off flag                                   |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`useSETRLSTK`                 | EEPARMS   | FALSE                                            | call C routine to set environment stacksize to ‘unlimited’                                              |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`useSIGREG`                   | EEPARMS   | FALSE                                            | enable signal handler to receive signal to terminate run cleanly on/off flag                            |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`debugMode`                   | EEPARMS   | FALSE                                            | print additional debugging messages; also “flush” STDOUT file unit after each print                     |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`printMapIncludesZeros`       | EEPARMS   | FALSE                                            | text map plots of fields should ignore exact zero values on/off flag                                    |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
                 | :varlink:`maxLengthPrt1D`              | EEPARMS   | 65                                               | maximum number of 1D array elements to print to standard output                                         |
                 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
83cdbd2346 Jeff* 
                 .. _sec_mitgcm_inp_file_format:
                 
                 MITgcm Input Data File Format
                 =============================
                 
ce0d9af5ea Jeff* MITgcm input files for grid-related data (e.g., :varlink:`delXFile`),
                 forcing fields (e.g., :varlink:`tauThetaClimRelax`),
                 parameter fields (e.g., :varlink:`viscAhZfile`), etc. are assumed to
                 be in "flat" or "unblocked" `binary format <https://en.wikipedia.org/wiki/Binary_file>`_.
fbfa6b7fb7 Jody* 
                 Data is expected to be in
                 `Fortran/column-major order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_,
                 in the order (:math:`x`, :math:`y`, :math:`z`, :math:`t`).
                 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ typically
                 uses F-order, while Python's `NumPy <https://numpy.org>`_ uses C-order (row-major order).
                 
                 For historical reasons, many large MITgcm projects use big-endian
ce0d9af5ea Jeff* `byte ordering <https://en.wikipedia.org/wiki/Endianness>`_,
                 **NOT** little-endian which is the more common default for today's computers.
fbfa6b7fb7 Jody* Thus, some care is required to create MITgcm-readable input files.  However, if
                 you prepare your own input files, it is perfectly fine to use little-endian so
                 long as you also compile your executable to be little-endian compatible.
83cdbd2346 Jeff* 
ce0d9af5ea Jeff* - Using `MATLAB <https://www.mathworks.com/products/matlab.html>`_:
                   When writing binary files, MATLAB's `fopen <https://www.mathworks.com/help/matlab/ref/fopen.html>`_
                   command includes a MACHINEFORMAT option ``'b'`` which instructs MATLAB
                   to read or write using big-endian byte ordering. 2-D arrays should be
fbfa6b7fb7 Jody*   index-ordered in MATLAB as (:math:`x`, :math:`y`), 3-D arrays as
                   (:math:`x`, :math:`y`, :math:`z`), and 4-D arrays as
                   (:math:`x`, :math:`y`, :math:`z`, :math:`t`); data is ordered from low to high in
ce0d9af5ea Jeff*   each index, with :math:`x` varying most rapidly.
83cdbd2346 Jeff* 
ce0d9af5ea Jeff*   An example to create a bathymetry file of single-precision, floating
                   point values (from tutorial :ref:`sec_eg_baro`, a simple enclosed,
                   flat-bottom domain) is as follows:
83cdbd2346 Jeff* 
                   ::
                 
ce0d9af5ea Jeff*      ieee = 'b';           % big-endian format
                      accuracy = 'float32'; % this is single-precision (='real*4')
83cdbd2346 Jeff* 
                      Ho=5000;  % ocean depth in meters
ce0d9af5ea Jeff*      nx=62;    % number of gridpoints in x-direction
                      ny=62;    % number of gridpoints in y-direction
83cdbd2346 Jeff* 
ce0d9af5ea Jeff*      % Flat bottom at z = -Ho
                      h = -Ho * ones(nx, ny);
83cdbd2346 Jeff* 
ce0d9af5ea Jeff*      % Walls (surrounding domain)
                      h([1 end], :) = 0;   % set ocean depth to zero at east and west walls
                      h(:, [1 end]) = 0;   % set ocean depth to zero at south and north walls
83cdbd2346 Jeff* 
ce0d9af5ea Jeff*      % save as single-precision (float32) with big-endian byte ordering
                      fid = fopen('bathy.bin', 'w', ieee);
                      fwrite(fid, h, accuracy);
                      fclose(fid);
                 
                   To read this bathymetry file back into MATLAB, reshaped back to (nx, ny):
83cdbd2346 Jeff* 
                   ::
                 
ce0d9af5ea Jeff*      fid = fopen('bathy.bin', 'r', ieee);
                      h = reshape(fread(fid, Inf, accuracy), nx, ny);
                      fclose(fid);
                 
fbfa6b7fb7 Jody* - Using Python's `NumPy <https://numpy.org>`_:
83cdbd2346 Jeff* 
fbfa6b7fb7 Jody*   The `tofile <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.tofile.html>`_
                   method on a NumPy array writes the data in
                   `row-major or C-order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_,
                   so arrays should be shaped to take this into account for the MITgcm:
                   (:math:`y`, :math:`x`) for 2-D,  (:math:`z`, :math:`y`, :math:`x`) for 3-D, and
                   (:math:`t`, :math:`z`, :math:`y`, :math:`x`) for 4-D.
                 
                   A python version of the above script can use NumPy to create a bathymetry file is as
                   follows:
83cdbd2346 Jeff* 
                   ::
                 
ce0d9af5ea Jeff*     import numpy as np
83cdbd2346 Jeff* 
ce0d9af5ea Jeff*     Ho = 5000  # ocean depth in meters
                     nx = 62    # number of gridpoints in x-direction
                     ny = 62    # number of gridpoints in y-direction
83cdbd2346 Jeff* 
ce0d9af5ea Jeff*     # Flat bottom at z = -Ho
                     h = -Ho * np.ones((ny, nx))
                 
                     # Walls (surrounding domain)
                     h[:, [0,-1]] = 0   # set ocean depth to zero at east and west walls
                     h[[0,-1], :] = 0   # set ocean depth to zero at south and north walls
                 
                     # save as single-precision (NumPy type float32) with big-endian byte ordering
                     h.astype('>f4').tofile('bathy.bin')
                 
fbfa6b7fb7 Jody*   The dtype specification ``'>f4'`` above instructs NumPy to write the file with
ce0d9af5ea Jeff*   big-endian byte ordering (specifically, due to the '>') as single-precision real
                   numbers (due to the 'f4' which is NumPy ``float32`` or equivalently,
                   Fortran ``real*4`` format).
                 
fbfa6b7fb7 Jody*   To read this bathymetry file back into NumPy, reshaped back to (ny, nx):
83cdbd2346 Jeff* 
                   ::
                 
ce0d9af5ea Jeff*     h = np.fromfile('bathy.bin', '>f4').reshape(ny, nx)
83cdbd2346 Jeff* 
fbfa6b7fb7 Jody*   where again the dtype spec instructs NumPy to read a big-endian
ce0d9af5ea Jeff*   file of single-precision, floating point values.
83cdbd2346 Jeff* 
ce0d9af5ea Jeff*   A more complicated example of using Python to generate input date is provided in
                   :filelink:`verification/tutorial_baroclinic_gyre/input/gendata.py`.
83cdbd2346 Jeff* 
                 - Using `Fortran <https://en.wikipedia.org/wiki/Fortran>`_:
ce0d9af5ea Jeff*   To create flat binary files in Fortran, open with
                   syntax ``OPEN(..., ACCESS='DIRECT', ...)`` (i.e., **NOT** ``ACCESS='SEQUENTIAL'``
                   which includes additional metadata). By default Fortran will use the
                   local computer system's native byte ordering for reading and writing binary files,
83cdbd2346 Jeff*   which for most systems will be little-endian. One therefore has two options:
ce0d9af5ea Jeff*   after creating a binary file in Fortran, use MATLAB or Python (or some
                   other utility) to read in and swap the bytes in the process of writing a new file;
                   or, determine if your local Fortran has
                   a compiler flag to control byte-ordering of binary files.
                   Similar to MATLAB, 2-D and 3-D arrays in Fortran should be index-ordered
                   as (:math:`x`, :math:`y`) and (:math:`x`, :math:`y`, :math:`z`), respectively.
ba0b047096 Mart* 
ce0d9af5ea Jeff* Using `NetCDF <http://www.unidata.ucar.edu/software/netcdf>`_ format for input files is only
                 partially implemented at present in MITgcm, and use is thus discouraged.
ba0b047096 Mart* 
                 Input files are by default single-precision real numbers (32-bit, ``real*4``),
ce0d9af5ea Jeff* but can be switched to double precision by setting
                 namelist parameter :varlink:`readBinaryPrec` (``PARM01`` in file ``data``)
                 to a value of 64.

This page was automatically generated from https://github.com/MITgcm/MITgcm by the 2.2.1-MITgcm-0.1 LXR engine. The LXR team