Warning, /doc/getting_started/getting_started.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit f955de4b on 2025-01-19 04:15:59 UTC
69e7157c80 Jeff*0001 .. _chap_getting_started:
0002
0003 Getting Started with MITgcm
0004 ***************************
0005
0006 This chapter is divided into two main parts. The first part, which is
0007 covered in sections :numref:`whereToFindInfo` through
31584ea246 Jeff*0008 :numref:`run_the_model`, contains information about how to download,
0009 build and run MITgcm.
69e7157c80 Jeff*0010 We believe the best way to familiarize yourself with the
af61fa61c7 Jeff*0011 model is to run one of the tutorial examples provided in the MITgcm repository
0012 (see :numref:`chap_modelExamples`), so would suggest newer MITgcm users
516b08a580 jm-c 0013 jump there following a read-through of the first part of this chapter.
69e7157c80 Jeff*0014 Information is also provided
ba0b047096 Mart*0015 in this chapter on how to customize the code
0016 when you are ready to try implementing
0017 the configuration you have in mind, in the second
0018 part (:numref:`customize_model`).
0019 The code and algorithm are described more fully in
0020 :numref:`discret_algorithm` and
516b08a580 jm-c 0021 :numref:`sarch` and chapters thereafter.
69e7157c80 Jeff*0022
af61fa61c7 Jeff*0023 In this chapter and others (e.g., chapter :ref:`chap_contributing`),
0024 for arguments where the user is expected to replace the text
ba0b047096 Mart*0025 with a user-chosen name, userid, etc., our convention
0026 is to show these as upper-case
af61fa61c7 Jeff*0027 text surrounded by ``« »``, such as ``«USER_MUST_REPLACE_TEXT_HERE»``.
0028 The ``«`` and ``»`` characters are **NOT** typed when the text is replaced.
0029
69e7157c80 Jeff*0030 .. _whereToFindInfo:
0031
0032 Where to find information
0033 =========================
0034
0035 There is a web-archived support mailing list for the model that you can
0036 email at MITgcm-support@mitgcm.org once you have subscribed.
0037
31584ea246 Jeff*0038 To sign up (subscribe) for the mailing list (highly recommended),
0039 click `here <http://mailman.mitgcm.org/mailman/listinfo/mitgcm-support/>`__
69e7157c80 Jeff*0040
31584ea246 Jeff*0041 To browse through the support archive,
0042 click `here <http://mailman.mitgcm.org/pipermail/mitgcm-support/>`__
69e7157c80 Jeff*0043
0044 Obtaining the code
0045 ==================
0046
ba0b047096 Mart*0047 The MITgcm code and documentation are under
0048 continuous development and we generally
0049 recommend that one downloads the latest version of the code.
0050 You will need to decide if you want to work in a âgit-awareâ
0051 environment (`Method 1`_) or with a one-time âstagnantâ download (`Method 2`_).
0052 We generally recommend method 1, as it is more
31584ea246 Jeff*0053 flexible and allows your version of the code to be regularly updated as MITgcm
ba0b047096 Mart*0054 developers check in bug fixes and new features. However, this typically
0055 requires at minimum a rudimentary understanding of git in
0056 order to make it worth oneâs while.
69e7157c80 Jeff*0057
ba0b047096 Mart*0058 Periodically we release an official checkpoint
0059 (or âtagâ). We recommend one download
31584ea246 Jeff*0060 the latest code, unless there are reasons for obtaining a specific checkpoint
ba0b047096 Mart*0061 (e.g. duplicating older results, collaborating with
0062 someone using an older release, etc.)
69e7157c80 Jeff*0063
0064 .. _git-aware_download:
0065
0066 Method 1
0067 --------
0068
0069 This section describes how to download git-aware copies of the repository.
516b08a580 jm-c 0070 In a terminal window, cd to the directory where you want your code to reside.
69e7157c80 Jeff*0071 Type:
0072
0073 ::
0074
0075 % git clone https://github.com/MITgcm/MITgcm.git
0076
31584ea246 Jeff*0077 This will download the latest available code. If you now want to revert this
0078 code to a specific checkpoint release, first ``cd`` into the MITgcm directory
ba0b047096 Mart*0079 you just downloaded, then type ``git checkout checkpoint«XXX»``
0080 where ``«XXX»`` is the checkpoint version.
69e7157c80 Jeff*0081
31584ea246 Jeff*0082 Alternatively, if you prefer to use ssh keys (say for example, you have
0083 a firewall which wonât allow a https download), type:
69e7157c80 Jeff*0084
0085 ::
0086
0087 % git clone git@github.com:MITgcm/MITgcm.git
0088
31584ea246 Jeff*0089 You will need a GitHub account for this, and will have to generate a ssh
516b08a580 jm-c 0090 key though your GitHub account user settings.
69e7157c80 Jeff*0091
31584ea246 Jeff*0092 The fully git-aware download is over several hundred MB, which is considerable
0093 if one has limited internet download speed. In comparison, the one-time
83cdbd2346 Jeff*0094 download zip file (`Method 2`_, below) is order 100 MB. However, one can
31584ea246 Jeff*0095 obtain a truncated, yet still git-aware copy of the current code by adding
0096 the option ``--depth=1`` to the git clone command above; all files will be
0097 present, but it will not include the full git history. However, the repository
516b08a580 jm-c 0098 can be updated going forward.
69e7157c80 Jeff*0099
0100 Method 2
0101 --------
0102
31584ea246 Jeff*0103 This section describes how to do a one-time download of MITgcm, NOT git-aware.
ba0b047096 Mart*0104 In a terminal window, ``cd`` to the directory where
0105 you want your code to reside. To obtain the current code, type:
69e7157c80 Jeff*0106
0107 ::
0108
0109 % wget https://github.com/MITgcm/MITgcm/archive/master.zip
0110
516b08a580 jm-c 0111 For specific checkpoint release ``XXX``, instead type:
69e7157c80 Jeff*0112
0113 ::
0114
af61fa61c7 Jeff*0115 % wget https://github.com/MITgcm/MITgcm/archive/checkpoint«XXX».zip
69e7157c80 Jeff*0116
0117 Updating the code
0118 =================
0119
ba0b047096 Mart*0120 There are several different approaches one can use to obtain updates to MITgcm;
0121 which is best for you depends a bit on how you intend to use MITgcm and your
0122 knowledge of git (and/or willingness to learn).
0123 Below we outline three suggested update pathways:
69e7157c80 Jeff*0124
31584ea246 Jeff*0125 1. **Fresh Download of MITgcm**
69e7157c80 Jeff*0126
ba0b047096 Mart*0127 This approach is the most simple, and virtually foolproof. Whether you
0128 downloaded the code from a static zip file (`Method 2`_) or used the git
0129 clone command (`Method 1`_), create a new directory and repeat
0130 this procedure to download a current copy of MITgcm. Say for example you
0131 are starting a new research project, this would be a great time to grab the
0132 most recent code repository and keep this new work entirely separate
0133 from any past simulations. This approach requires no understanding of git,
0134 and you are free to make changes to any files in the MIT repo tree
0135 (although we generally recommend that you avoid doing so, instead working
0136 in new subdirectories or on separate scratch disks as described
516b08a580 jm-c 0137 :ref:`here <build_elsewhere>`, for example).
69e7157c80 Jeff*0138
0139 2. **Using** ``git pull`` **to update the (unmodified) MITgcm repo tree**
0140
ba0b047096 Mart*0141 If you have downloaded the code through a git clone command
0142 (`Method 1`_ above), you can incorporate any changes to the source code
0143 (including any changes to any files in the MITgcm repository, new packages
0144 or analysis routines, etc.) that may have occurred since your
0145 original download. There is a simple command to bring all code in the
0146 repository to a âcurrent releaseâ state. From the MITgcm top directory
69e7157c80 Jeff*0147 or any of its subdirectories, type:
0148
0149 ::
0150
0151 % git pull
0152
ba0b047096 Mart*0153 and all files will be updated to match the current state of the code
0154 repository, as it exists at `GitHub <https://github.com/MITgcm/MITgcm.git>`_.
0155 (*Note:* if you plan to contribute to MITgcm and followed the steps to
0156 download the code as described in :numref:`chap_contributing`,
0157 you will need to type ``git pull upstream`` instead.)
0158
0159 This update pathway is ideal if you are in the midst of a project and
0160 you want to incorporate new MITgcm features into your executable(s),
0161 or take advantage of recently added analysis utilties, etc.
0162 After the git pull, any changes in model source code and include files
0163 will be updated, so you can repeat the build procedure
0164 (:numref:`building_code`) and you will include all these new features
69e7157c80 Jeff*0165 in your new executable.
0166
ba0b047096 Mart*0167 Be forewarned, this will only work if you have not modified ANY of the
0168 files in the MITgcm repository (adding new files is ok; also, all
0169 verification run subdirectories ``build`` and ``run`` are also ignored by git).
0170 If you have modified files and the ``git pull`` fails with errors,
0171 there is no easy fix other than to learn something
0172 about git (continue reading...)
69e7157c80 Jeff*0173
0174 3. **Fully embracing the power of git!**
0175
ce0d9af5ea Jeff*0176 Git offers many tools to help organize and track changes in your work.
ba0b047096 Mart*0177 For example, one might keep separate projects on different branches,
0178 and update the code separately (using ``git pull``) on these separate branches.
0179 You can even make changes to code in the MIT repo tree; when git then
0180 tries to update code from upstream (see :numref:`git_setup`), it will notify
0181 you about possible conflicts and even merge the code changes
0182 together if it can. You can also use ``git commit`` to help you track what
0183 you are modifying in your simulations over time. If you're planning to
0184 submit a pull request to include your changes, you should read the
0185 contributing guide in :numref:`chap_contributing`, and we suggest you do
0186 this model development in a separate, fresh copy of the code. See
0187 :numref:`using_git_and_github` for more information and how
69e7157c80 Jeff*0188 to use git effectively to manage your workflow.
0189
0190 Model and directory structure
0191 =============================
0192
0193 The ânumericalâ model is contained within a execution environment
0194 support wrapper. This wrapper is designed to provide a general framework
0195 for grid-point models; MITgcm is a specific numerical model that makes use of
ba0b047096 Mart*0196 this framework (see :numref:`wrapper` for additional detail).
0197 Under this structure, the model is split into execution
69e7157c80 Jeff*0198 environment support code and conventional numerical model code. The
af61fa61c7 Jeff*0199 execution environment support code is held under the :filelink:`eesupp`
0200 directory. The grid point model code is held under the :filelink:`model`
ba0b047096 Mart*0201 directory. Code execution actually starts in the :filelink:`eesupp` routines
0202 and not in the :filelink:`model` routines. For this reason the top-level
0203 :filelink:`main.F <eesupp/src/main.F>` is in the :filelink:`eesupp/src`
0204 directory. In general, end-users should not need to worry about the
0205 wrapper support code. The top-level routine for the numerical
af61fa61c7 Jeff*0206 part of the code is in :filelink:`model/src/the_model_main.F`. Here is a brief
69e7157c80 Jeff*0207 description of the directory structure of the model under the root tree.
0208
af61fa61c7 Jeff*0209 - :filelink:`model`: this directory contains the main source code. Also
ba0b047096 Mart*0210 subdivided into two subdirectories: :filelink:`model/inc` (includes files)
0211 and :filelink:`model/src` (source code).
69e7157c80 Jeff*0212
ba0b047096 Mart*0213 - :filelink:`eesupp`: contains the execution environment source code.
0214 Also subdivided into two subdirectories: :filelink:`eesupp/inc`
0215 and :filelink:`eesupp/src`.
69e7157c80 Jeff*0216
af61fa61c7 Jeff*0217 - :filelink:`pkg`: contains the source code for the packages. Each package
ba0b047096 Mart*0218 corresponds to a subdirectory. For example, :filelink:`pkg/gmredi`
0219 contains the code related to the Gent-McWilliams/Redi scheme,
0220 :filelink:`pkg/seaice` the code for a dynamic seaice model which can be
0221 coupled to the ocean model. The packages are described in detail in
0222 :numref:`packagesI` and :numref:`outp_pack`].
0223
0224 - :filelink:`doc`: contains MITgcm documentation in reStructured
0225 Text (rst) format.
0226
0227 - :filelink:`tools`: this directory contains various useful tools.
0228 For example, :filelink:`genmake2 <tools/genmake2>` is a script written
0229 in bash that should be used to generate your makefile.
0230 The subdirectory :filelink:`tools/build_options` contains
0231 âoptfilesâ with the compiler options for many different
0232 compilers and machines that can run MITgcm
0233 (see :numref:`genmake2_optfiles`). This directory also contains
0234 subdirectories :filelink:`tools/adjoint_options` and
0235 :filelink:`tools/OAD_support` that are used to generate the tangent linear
0236 and adjoint model (see details in :numref:`chap_autodiff`).
0237
0238 - :filelink:`utils`: this directory contains various utilities.
0239 The :filelink:`utils/matlab` subdirectory
69e7157c80 Jeff*0240 contains matlab scripts for reading model output directly into
ba0b047096 Mart*0241 matlab. The subdirectory :filelink:`utils/python` contains similar
0242 routines for python. :filelink:`utils/scripts` contains C-shell
0243 post-processing scripts for joining processor-based and
0244 tiled-based model output.
69e7157c80 Jeff*0245
af61fa61c7 Jeff*0246 - :filelink:`verification`: this directory contains the model examples. See
69e7157c80 Jeff*0247 :numref:`chap_modelExamples`.
0248
af61fa61c7 Jeff*0249 - :filelink:`jobs`: contains sample job scripts for running MITgcm.
69e7157c80 Jeff*0250
af61fa61c7 Jeff*0251 - :filelink:`lsopt`: Line search code used for optimization.
69e7157c80 Jeff*0252
af61fa61c7 Jeff*0253 - :filelink:`optim`: Interface between MITgcm and line search code.
69e7157c80 Jeff*0254
0255 .. _building_code:
0256
31584ea246 Jeff*0257 Building the model
0258 ==================
0259
0260 .. _building_quickstart:
0261
0262 Quickstart Guide
0263 ----------------
69e7157c80 Jeff*0264
0265 To compile the code, we use the ``make`` program. This uses a file
0266 (``Makefile``) that allows us to pre-process source files, specify
0267 compiler and optimization options and also figures out any file
ba0b047096 Mart*0268 dependencies. We supply a script (:filelink:`genmake2 <tools/genmake2>`),
0269 described in section :numref:`genmake2_desc`, that automatically generates
0270 the ``Makefile`` for you. You then need to build the dependencies and
0271 compile the code (:numref:`make_target_commands`).
69e7157c80 Jeff*0272
0273 As an example, assume that you want to build and run experiment
ba0b047096 Mart*0274 :filelink:`verification/exp2`.
0275 Letâs build the code in :filelink:`verification/exp2/build`:
69e7157c80 Jeff*0276
0277 ::
0278
0279 % cd verification/exp2/build
0280
017e3135cd Jeff*0281 First, generate the ``Makefile``:
69e7157c80 Jeff*0282
0283 ::
0284
3b0572824e Jeff*0285 % ../../../tools/genmake2 -mods ../code -optfile «/PATH/TO/OPTFILE»
69e7157c80 Jeff*0286
ba0b047096 Mart*0287 The ``-mods`` command line option tells :filelink:`genmake2 <tools/genmake2>`
0288 to override model source code with any files in the subdirectory ``../code``
0289 (here, you need to configure the size of the model domain by overriding
0290 MITgcmâs default :filelink:`SIZE.h <model/inc/SIZE.h>`
e7309a0b9d Jeff*0291 with an edited copy :filelink:`../code/SIZE.h <verification/exp2/code/SIZE.h>`
3b0572824e Jeff*0292 containing the specific domain size for :filelink:`exp2 <verification/exp2>`).
e7309a0b9d Jeff*0293
0294 The ``-optfile`` command line option tells :filelink:`genmake2 <tools/genmake2>`
ba0b047096 Mart*0295 to run the specified
0296 :ref:`optfile <genmake2_optfiles>`, a `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_
0297 shell script, during :filelink:`genmake2 <tools/genmake2>`âs execution.
3b0572824e Jeff*0298 An :ref:`optfile <genmake2_optfiles>` typically contains
ba0b047096 Mart*0299 definitions of
0300 `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_,
0301 paths, compiler options, and anything else that needs to be set in order
0302 to compile on your local computer system or cluster with your specific
0303 Fortan compiler. As an example, we might replace ``«/PATH/TO/OPTFILE»`` with
0304 :filelink:`../../../tools/build_options/linux_amd64_ifort11 <tools/build_options/linux_amd64_ifort11>`
0305 for use with the
0306 `Intel Fortran <https://software.intel.com/en-us/fortran-compilers>`_ compiler
3b0572824e Jeff*0307 (version 11 and above) on a linux x86_64 platform.
ba0b047096 Mart*0308 This and many other :ref:`optfiles <genmake2_optfiles>` for common systems
0309 and Fortran compilers are located in :filelink:`tools/build_options`.
69e7157c80 Jeff*0310
ba0b047096 Mart*0311 ``-mods``, ``-optfile``, and many additional
0312 :filelink:`genmake2 <tools/genmake2>` command line options are described
0313 more fully in :numref:`command_line_options`. Detailed instructions on
0314 building with
0315 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
0316 are given in :numref:`build_mpi`.
69e7157c80 Jeff*0317
0318 Once a ``Makefile`` has been generated, we create the dependencies with
0319 the command:
0320
0321 ::
0322
0323 % make depend
0324
b3d71355f7 Jeff*0325 It is important to note that the ``make depend`` stage will occasionally
69e7157c80 Jeff*0326 produce warnings or errors if the dependency parsing tool is unable
516b08a580 jm-c 0327 to find all of the necessary header files (e.g., ``netcdf.inc``, or worse,
e7309a0b9d Jeff*0328 say it cannot find a Fortran compiler in your path). In some cases you
69e7157c80 Jeff*0329 may need to obtain help from your system administrator to locate these files.
0330
0331 Next, one can compile the code using:
0332
0333 ::
0334
0335 % make
0336
ba0b047096 Mart*0337 Assuming no errors occurred, the ``make`` command creates
0338 an executable called ``mitgcmuv``.
69e7157c80 Jeff*0339
0340 Now you are ready to run the model. General instructions for doing so
516b08a580 jm-c 0341 are given in section :numref:`run_the_model`.
69e7157c80 Jeff*0342
31584ea246 Jeff*0343 .. _genmake2_desc:
69e7157c80 Jeff*0344
b3d71355f7 Jeff*0345 Generating a ``Makefile`` using genmake2
0346 ----------------------------------------
69e7157c80 Jeff*0347
ba0b047096 Mart*0348 A shell script called ``genmake2`` for generating a ``Makefile`` is
0349 included as part of MITgcm.
b3d71355f7 Jeff*0350 Typically ``genmake2`` is used in a sequence of steps as shown below:
69e7157c80 Jeff*0351
0352 ::
0353
516b08a580 jm-c 0354 % ../../../tools/genmake2 -mods ../code -optfile «/PATH/TO/OPTFILE»
31584ea246 Jeff*0355 % make depend
0356 % make
69e7157c80 Jeff*0357
ba0b047096 Mart*0358 The first step above creates a unix-style ``Makefile``. The ``Makefile``
0359 is used by ``make`` to specify how to compile the MITgcm source files
0360 (for more detailed descriptions of what the ``make`` tools
0361 are, and how they are used, see
0362 `here <https://www.gnu.org/software/make/make.html>`__).
3396b55b9d chri*0363
ba0b047096 Mart*0364 This section describes details and capabilities of
0365 :filelink:`genmake2 <tools/genmake2>`, located in the
b3d71355f7 Jeff*0366 :filelink:`tools` directory. :filelink:`genmake2 <tools/genmake2>` is a shell
ba0b047096 Mart*0367 script written to work in
0368 `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_ (and with all
ce0d9af5ea Jeff*0369 âshââcompatible shells including
ba0b047096 Mart*0370 `Bourne <https://en.wikipedia.org/wiki/Bourne_shell>`_ shells).
0371 Like many unix tools, there is a help option that is invoked
0372 thru ``genmake2 -h``. :filelink:`genmake2 <tools/genmake2>` parses
0373 information from the following sources, in this order:
31584ea246 Jeff*0374
e7309a0b9d Jeff*0375 #. Command-line options (see :numref:`command_line_options`)
31584ea246 Jeff*0376
0377 #. A ``genmake_local`` file if one is found in the current directory.
3b0572824e Jeff*0378 This is a `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_ shell
ba0b047096 Mart*0379 script that is executed prior to the :ref:`optfile <genmake2_optfiles>`
0380 (see step #3), used in some special model configurations and/or to
0381 set some options that can affect which lines of the
0382 :ref:`optfile <genmake2_optfiles>` are executed.
0383 For example, this
0384 :filelink:`genmake_local <verification/cpl_aim+ocn/build_cpl/genmake_local>`
0385 file is required for a special setup, building a âMITgcm couplerâ
0386 executable; in a more typical setup, one will not require a
0387 ``genmake_local`` file.
69e7157c80 Jeff*0388
3b0572824e Jeff*0389 #. An âoptions fileâ a.k.a. :ref:`optfile <genmake2_optfiles>`
ba0b047096 Mart*0390 (a `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_ shell
0391 script) specified by the command-line option
0392 ``âoptfile «/PATH/TO/OPTFILE»``, as mentioned briefly
0393 in :numref:`building_quickstart`
b3d71355f7 Jeff*0394 and described in detail in :numref:`genmake2_optfiles`.
69e7157c80 Jeff*0395
31584ea246 Jeff*0396 #. A ``packages.conf`` file (if one is found) with the specific list of
ba0b047096 Mart*0397 packages to compile (see :numref:`using_packages`). The search path for
0398 file ``packages.conf`` is first the current directory, and then each
0399 of the ``-mods`` directories in the given order (as described
0400 :ref:`here <mods_option>`).
69e7157c80 Jeff*0401
ba0b047096 Mart*0402 When you run the :filelink:`genmake2 <tools/genmake2>` script,
0403 typical output might be as follows:
31584ea246 Jeff*0404
0405 ::
0406
e7309a0b9d Jeff*0407 % ../../../tools/genmake2 -mods ../code -optfile ../../../tools/build_options/linux_amd64_gfortran
516b08a580 jm-c 0408
e7309a0b9d Jeff*0409 GENMAKE :
516b08a580 jm-c 0410
e7309a0b9d Jeff*0411 A program for GENerating MAKEfiles for the MITgcm project.
0412 For a quick list of options, use "genmake2 -h"
516b08a580 jm-c 0413 or for more detail see the documentation, section "Building the model"
0414 (under "Getting Started") at: https://mitgcm.readthedocs.io/
0415
e7309a0b9d Jeff*0416 === Processing options files and arguments ===
0417 getting local config information: none found
f955de4ba2 Jean*0418 Warning: MITgcm root directory was not specified ; try using a local copy of MITgcm found at "../../.."
e7309a0b9d Jeff*0419 getting OPTFILE information:
0420 using OPTFILE="../../../tools/build_options/linux_amd64_gfortran"
0421 getting AD_OPTFILE information:
0422 using AD_OPTFILE="../../../tools/adjoint_options/adjoint_default"
516b08a580 jm-c 0423 check Fortran Compiler... pass (set FC_CHECK=5/5)
e7309a0b9d Jeff*0424 check makedepend (local: 0, system: 1, 1)
516b08a580 jm-c 0425
e7309a0b9d Jeff*0426 === Checking system libraries ===
0427 Do we have the system() command using gfortran... yes
0428 Do we have the fdate() command using gfortran... yes
0429 Do we have the etime() command using gfortran... c,r: yes (SbR)
0430 Can we call simple C routines (here, "cloc()") using gfortran... yes
0431 Can we unlimit the stack size using gfortran... yes
0432 Can we register a signal handler using gfortran... yes
0433 Can we use stat() through C calls... yes
0434 Can we create NetCDF-enabled binaries... yes
516b08a580 jm-c 0435 skip check for LAPACK Libs
e7309a0b9d Jeff*0436 Can we call FLUSH intrinsic subroutine... yes
516b08a580 jm-c 0437
e7309a0b9d Jeff*0438 === Setting defaults ===
516b08a580 jm-c 0439 Adding MODS directories: ../code
e7309a0b9d Jeff*0440 Making source files in eesupp from templates
0441 Making source files in pkg/exch2 from templates
0442 Making source files in pkg/regrid from templates
516b08a580 jm-c 0443
e7309a0b9d Jeff*0444 === Determining package settings ===
0445 getting package dependency info from ../../../pkg/pkg_depend
0446 getting package groups info from ../../../pkg/pkg_groups
0447 checking list of packages to compile:
0448 using PKG_LIST="../code/packages.conf"
0449 before group expansion packages are: oceanic -kpp -gmredi cd_code
0450 replacing "oceanic" with: gfd gmredi kpp
0451 replacing "gfd" with: mom_common mom_fluxform mom_vecinv generic_advdiff debug mdsio rw monitor
0452 after group expansion packages are: mom_common mom_fluxform mom_vecinv generic_advdiff debug mdsio rw monitor gmredi kpp -kpp -gmredi cd_code
0453 applying DISABLE settings
0454 applying ENABLE settings
0455 packages are: cd_code debug generic_advdiff mdsio mom_common mom_fluxform mom_vecinv monitor rw
0456 applying package dependency rules
0457 packages are: cd_code debug generic_advdiff mdsio mom_common mom_fluxform mom_vecinv monitor rw
0458 Adding STANDARDDIRS='eesupp model'
0459 Searching for *OPTIONS.h files in order to warn about the presence
0460 of "#define "-type statements that are no longer allowed:
516b08a580 jm-c 0461 found CPP_EEOPTIONS="../../../eesupp/inc/CPP_EEOPTIONS.h"
0462 found CPP_OPTIONS="../../../model/inc/CPP_OPTIONS.h"
e7309a0b9d Jeff*0463 Creating the list of files for the adjoint compiler.
516b08a580 jm-c 0464
e7309a0b9d Jeff*0465 === Creating the Makefile ===
0466 setting INCLUDES
0467 Determining the list of source and include files
0468 Writing makefile: Makefile
0469 Add the source list for AD code generation
0470 Making list of "exceptions" that need ".p" files
0471 Making list of NOOPTFILES
0472 Add rules for links
0473 Adding makedepend marker
516b08a580 jm-c 0474
e7309a0b9d Jeff*0475 === Done ===
f7aaac66f3 jm-c 0476 original 'Makefile' generated successfully
0477 => next steps:
0478 > make depend
0479 > make (<-- to generate executable)
e7309a0b9d Jeff*0480
31584ea246 Jeff*0481 In the above, notice:
0482
f955de4ba2 Jean*0483 - we did not specify MITgcm root directory,
516b08a580 jm-c 0484 i.e., a path to your MITgcm repository,
31584ea246 Jeff*0485 but here we are building code from within the repository (specifically,
516b08a580 jm-c 0486 in one of the verification subdirectory experiments). As such,
31584ea246 Jeff*0487 :filelink:`genmake2 <tools/genmake2>` was smart enough to
f955de4ba2 Jean*0488 locate all necessary files on its own. To specify a remote MITgcm root directory,
ba0b047096 Mart*0489 see :ref:`here <build_elsewhere>`.
0490 - we specified the :ref:`optfile <genmake2_optfiles>`
0491 :filelink:`linux_amd64_gfortran <tools/build_options/linux_amd64_gfortran>`
e7309a0b9d Jeff*0492 based on the computer system and Fortran compiler we used
31584ea246 Jeff*0493 (here, a linux 64-bit machine with gfortran installed).
ba0b047096 Mart*0494 - :filelink:`genmake2 <tools/genmake2>` did
0495 some simple checking on availability
0496 of certain system libraries; all were found (except
0497 `LAPACK <https://en.wikipedia.org/wiki/LAPACK>`_,
516b08a580 jm-c 0498 which was not checked since it is not needed here).
31584ea246 Jeff*0499 `NetCDF <http://www.unidata.ucar.edu/software/netcdf>`_ only requires a âyesâ
ba0b047096 Mart*0500 if you want to write `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
0501 output; more specifically, a ânoâ response to âCan we create NetCDF-enabled
0502 binariesâ will disable including :filelink:`pkg/mnc` and switch to output
0503 plain binary files. While the makefile can still be built with other
0504 ânoâ responses, sometimes this will foretell errors during the
31584ea246 Jeff*0505 ``make depend`` or ``make`` commands.
ba0b047096 Mart*0506 - any ``.F`` or ``.h`` files in the ``-mods`` directory ``../code`` will
0507 also be compiled, overriding any MITgcm repository versions of files,
0508 if they exist.
0509 - a handful of packages are being used in this build; see
0510 :numref:`using_packages` for more detail about how to enable and disable
0511 packages.
0512 - :filelink:`genmake2 <tools/genmake2>` terminated without error
0513 (note output at end after ``=== Done ===``), generating ``Makefile`` and
0514 a log file ``genmake.log``. As mentioned, this does not guarantee that
0515 your setup will compile properly, but if there are errors during
0516 ``make depend`` or ``make``, these error messages and/or the
0517 standard output from :filelink:`genmake2 <tools/genmake2>` or
0518 ``genmake.log`` may provide clues as to the problem.
516b08a580 jm-c 0519 If instead :filelink:`genmake2 <tools/genmake2>` finishes with
0520 a warning message ``Warning: FORTRAN compiler test failed`` , this means
0521 that :filelink:`genmake2 <tools/genmake2>` is unable to locate the Fortran
ba0b047096 Mart*0522 compiler or pass a trivial âhello worldâ Fortran compilation test.
0523 In this case, you should see ``genmake.log`` for errors and/or seek
0524 assistance from your system administrator;
f7aaac66f3 jm-c 0525 these tests need to pass in order to proceed to the ``make`` steps.
0526
e7309a0b9d Jeff*0527 .. _command_line_options:
69e7157c80 Jeff*0528
0529 Command-line options:
0530 ~~~~~~~~~~~~~~~~~~~~~
0531
e7309a0b9d Jeff*0532 :filelink:`genmake2 <tools/genmake2>` supports a number of helpful
69e7157c80 Jeff*0533 command-line options. A complete list of these options can be obtained by:
0534
0535 ::
0536
0537 % genmake2 -h
0538
0539 The most important command-line options are:
0540
e7309a0b9d Jeff*0541 ``âoptfile «/PATH/TO/OPTFILE»``
ba0b047096 Mart*0542 (or shorter: ``-of`` ) specifies the :ref:`optfile <genmake2_optfiles>`
0543 that should be used for a particular build.
69e7157c80 Jeff*0544
ba0b047096 Mart*0545 If no :ref:`optfile <genmake2_optfiles>` is specified through the command
0546 line, :filelink:`genmake2 <tools/genmake2>` will try to make a
af61fa61c7 Jeff*0547 reasonable guess from the list provided in :filelink:`tools/build_options`.
69e7157c80 Jeff*0548 The method used for making this guess is to first determine the
31584ea246 Jeff*0549 combination of operating system and hardware and
e7309a0b9d Jeff*0550 then find a working Fortran compiler within the userâs path. When
ba0b047096 Mart*0551 these three items have been identified,
0552 :filelink:`genmake2 <tools/genmake2>` will try to find an
0553 :ref:`optfile <genmake2_optfiles>` that has a matching name.
0554 See :numref:`genmake2_optfiles`.
69e7157c80 Jeff*0555
0556 .. _mods_option:
0557
b3d71355f7 Jeff*0558 ``âmods '«DIR1 DIR2 DIR3 ...»'``
69e7157c80 Jeff*0559 specifies a list of directories containing âmodificationsâ. These
0560 directories contain files with names that may (or may not) exist in
0561 the main MITgcm source tree but will be overridden by any
0562 identically-named sources within the ``-mods`` directories.
ba0b047096 Mart*0563 Note the quotes around the list of directories,
0564 necessary given multiple arguments.
69e7157c80 Jeff*0565
e7309a0b9d Jeff*0566 The order of precedence for versions of files with identical names:
69e7157c80 Jeff*0567
ba0b047096 Mart*0568 - âmodsâ directories in the order given (e.g., will use copy of file
0569 located in DIR1 instead of DIR2)
69e7157c80 Jeff*0570
b3d71355f7 Jeff*0571 - Packages either explicitly specified or included by default
69e7157c80 Jeff*0572
b3d71355f7 Jeff*0573 - Packages included due to package dependencies
69e7157c80 Jeff*0574
0575 - The âstandard dirsâ (which may have been specified by the
e7309a0b9d Jeff*0576 ``-standarddirs`` option below)
0577
0578 .. _build_elsewhere:
69e7157c80 Jeff*0579
31584ea246 Jeff*0580 ``-rootdir «/PATH/TO/MITGCMDIR»``
f955de4ba2 Jean*0581 specify the location of the MITgcm repository top directory (MITgcm root directory).
ba0b047096 Mart*0582 By default, :filelink:`genmake2 <tools/genmake2>` will try to find this
0583 location by looking in parent directories from where
0584 :filelink:`genmake2 <tools/genmake2>` is executed
b3d71355f7 Jeff*0585 (up to 5 directory levels above the current directory).
e7309a0b9d Jeff*0586
ba0b047096 Mart*0587 In the quickstart example above (:numref:`building_quickstart`) we built
0588 the executable in the ``build`` directory of the experiment.
e7309a0b9d Jeff*0589 Below, we show how to configure and compile the code on a scratch disk,
0590 without having to copy the entire source
ba0b047096 Mart*0591 tree. The only requirement is that you have
0592 :filelink:`genmake2 <tools/genmake2>`
b3d71355f7 Jeff*0593 in your `$PATH <https://en.wikipedia.org/wiki/PATH_(variable)>`_, or
ba0b047096 Mart*0594 you know the absolute path to :filelink:`genmake2 <tools/genmake2>`.
0595 In general, one can compile the code in any given directory by following
0596 this procedure. Assuming the model source is in ``~/MITgcm``, then the
e7309a0b9d Jeff*0597 following commands will build the model in ``/scratch/exp2-run1``:
0598
0599 ::
31584ea246 Jeff*0600
e7309a0b9d Jeff*0601 % cd /scratch/exp2-run1
0602 % ~/MITgcm/tools/genmake2 -rootdir ~/MITgcm -mods ~/MITgcm/verification/exp2/code
0603 % make depend
0604 % make
31584ea246 Jeff*0605
b3d71355f7 Jeff*0606 As an alternative to specifying the MITgcm repository location through
ba0b047096 Mart*0607 the ``-rootdir`` command-line option, :filelink:`genmake2 <tools/genmake2>`
0608 recognizes the
0609 `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
0610 ``$MITGCM_ROOTDIR``.
3b0572824e Jeff*0611
31584ea246 Jeff*0612 ``-standarddirs «/PATH/TO/STANDARDDIR»``
ba0b047096 Mart*0613 specify a path to the standard MITgcm directories for source and includes
0614 files. By default, :filelink:`model` and :filelink:`eesupp`
0615 directories (``src`` and ``inc``) are the âstandard dirsâ.
0616 This command can be used
b3d71355f7 Jeff*0617 to reset these default standard directories,
31584ea246 Jeff*0618 or instead NOT include either :filelink:`model` or :filelink:`eesupp`
0619 as done in some specialized configurations.
0620
69e7157c80 Jeff*0621 ``-oad``
e7309a0b9d Jeff*0622 generates a makefile for an OpenAD build (see :numref:`ad_openad`)
69e7157c80 Jeff*0623
af61fa61c7 Jeff*0624 ``âadoptfile «/PATH/TO/FILE»``
ba0b047096 Mart*0625 (or shorter: ``-adof`` ) specifies the âadjointâ or automatic
0626 differentiation options file to be used. The file is analogous to the
0627 optfile defined above but it specifies information for the AD
0628 build process. See :numref:`adoptfile`.
69e7157c80 Jeff*0629
0630 The default file is located in
af61fa61c7 Jeff*0631 :filelink:`tools/adjoint_options/adjoint_default` and it defines the âTAFâ
516b08a580 jm-c 0632 and âTAMCâ compiler options.
69e7157c80 Jeff*0633
0634 ``âmpi``
ba0b047096 Mart*0635 enables certain
0636 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
0637 features (using CPP ``#define``) within the code and is necessary for
0638 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ builds
b3d71355f7 Jeff*0639 (see :numref:`build_mpi`).
69e7157c80 Jeff*0640
0641 ``âomp``
ba0b047096 Mart*0642 enables OpenMP code and compiler flag ``OMPFLAG``
0643 (see :numref:`build_openmp`).
69e7157c80 Jeff*0644
0645 ``âieee``
b3d71355f7 Jeff*0646 use IEEE numerics (requires support in optfile).
ba0b047096 Mart*0647 This option is typically a good choice if one wants to compare output
0648 from different machines running the same code.
0649 Note using IEEE disables all compiler optimizations.
31584ea246 Jeff*0650
0651 ``-devel``
ba0b047096 Mart*0652 use IEEE numerics (requires support in optfile) and add additional
0653 compiler options to check array bounds and add other additional warning
0654 and debugging flags.
69e7157c80 Jeff*0655
af61fa61c7 Jeff*0656 ``âmake «/PATH/TO/GMAKE»``
69e7157c80 Jeff*0657 due to the poor handling of soft-links and other bugs common with
31584ea246 Jeff*0658 the ``make`` versions provided by commercial unix vendors, GNU
69e7157c80 Jeff*0659 ``make`` (sometimes called ``gmake``) may be preferred. This
0660 option provides a means for specifying the make executable to be
0661 used.
0662
ba0b047096 Mart*0663 While it is possible to use :filelink:`genmake2 <tools/genmake2>` command-line
0664 options to set the Fortran or C compiler name (``-fc`` and ``-cc``
0665 respectively), we generally recommend setting these through an
0666 :ref:`optfile <genmake2_optfiles>`, as discussed in :numref:`genmake2_optfiles`.
31584ea246 Jeff*0667 Other :filelink:`genmake2 <tools/genmake2>` options are available to
0668 enable performance/timing analyses, etc.; see ``genmake2 -h`` for more info.
0669
e7309a0b9d Jeff*0670 .. _genmake2_optfiles:
0671
0672 Optfiles in tools/build_options directory:
0673 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0674
0675 The purpose of the optfiles is to provide all the compilation options
0676 for particular âplatformsâ (where âplatformâ roughly means the
0677 combination of the hardware and the compiler) and code configurations.
0678 Given the combinations of possible compilers and library dependencies
0679 (e.g., `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ or
b3d71355f7 Jeff*0680 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_) there may be
0681 numerous optfiles available for a
e7309a0b9d Jeff*0682 single machine. The naming scheme for the majority of the optfiles
0683 shipped with the code is **OS_HARDWARE_COMPILER** where
0684
0685 **OS**
0686 is the name of the operating system (generally the lower-case output
0687 of a linux terminal ``uname`` command)
0688
0689 **HARDWARE**
0690 is a string that describes the CPU type and corresponds to output
0691 from a ``uname -m`` command. Some common CPU types:
0692
0693 ``amd64``
ba0b047096 Mart*0694 use this code for x86_64 systems (most common, including AMD and
0695 Intel 64-bit CPUs)
e7309a0b9d Jeff*0696
0697 ``ia64``
0698 is for Intel IA64 systems (eg. Itanium, Itanium2)
0699
0700 ``ppc``
0701 is for (old) Mac PowerPC systems
0702
0703 **COMPILER**
ba0b047096 Mart*0704 is the compiler name (generally, the name of the Fortran compiler
0705 executable). MITgcm is primarily written in
0706 `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_.
0707 Compiling the code requires a
0708 `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_ compiler.
0709 Any more recent compiler which is backwards compatible with
0710 `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_
b3d71355f7 Jeff*0711 can also be used; for example, the model will build successfully
516b08a580 jm-c 0712 with a `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_
ba0b047096 Mart*0713 or `Fortran 95 <https://en.wikipedia.org/wiki/Fortran#Fortran_95>`_
0714 compiler. A `C99 <https://en.wikipedia.org/wiki/C99>`_ compatible compiler
0715 is also need, together with a
0716 `C preprocessor <https://en.wikipedia.org/wiki/C_preprocessor>`_ .
0717 Some optional packages make use of
0718 `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_ constructs
0719 (either
0720 `free-form formatting <https://en.wikipedia.org/wiki/Free-form_language>`_,
0721 or
0722 `dynamic memory allocation <https://en.wikipedia.org/wiki/Memory_management#DYNAMIC>`_);
0723 as such, setups which use these packages require a
0724 `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_
5564cc2c2d chri*0725 or later compiler build.
e7309a0b9d Jeff*0726
ba0b047096 Mart*0727 There are existing optfiles that work with many common hardware/compiler
0728 configurations; we first suggest you peruse the list in
0729 :filelink:`tools/build_options` and try to find your platform/compiler
0730 configuration. These are the most common:
e7309a0b9d Jeff*0731
0732 - :filelink:`linux_amd64_gfortran <tools/build_options/linux_amd64_gfortran>`
0733 - :filelink:`linux_amd64_ifort11 <tools/build_options/linux_amd64_ifort11>`
0734 - :filelink:`linux_amd64_ifort+impi <tools/build_options/linux_amd64_ifort+impi>`
0735 - :filelink:`linux_amd64_pgf77 <tools/build_options/linux_amd64_pgf77>`
0736
ba0b047096 Mart*0737 The above optfiles are all for linux x86_64 (64-bit) systems, utilized in many
0738 large high-performance computing centers. All of the above will work with
0739 single-threaded,
0740 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_,
0741 or shared memory (`OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_) code
0742 configurations. gfortran is `GNU Fortran <https://gcc.gnu.org/fortran>`_,
e7309a0b9d Jeff*0743 ifort is `Intel Fortran <https://software.intel.com/en-us/fortran-compilers>`_,
ba0b047096 Mart*0744 pgf77 is `PGI Fortran <https://www.pgroup.com/>`_ (formerly known as
0745 âThe Portland Groupâ). Note in the above list there are two ``ifort`` optfiles:
e7309a0b9d Jeff*0746 :filelink:`linux_amd64_ifort+impi <tools/build_options/linux_amd64_ifort+impi>`
0747 is for a specific case of using ``ifort`` with the
ba0b047096 Mart*0748 `Intel MPI library <https://software.intel.com/en-us/intel-mpi-library>`_
0749 (a.k.a. ``impi``), which requires special define statements in the optfile
0750 (in contrast with `Open MPI <https://www.open-mpi.org/>`_ or
0751 `MVAPICH2 <http:mvapich.cse.ohio-state.edu/>`_ libraries;
0752 see :numref:`build_mpi`). Note that both ifort optfiles require ifort
0753 version 11 or higher. Many clusters nowadays use
0754 `environment modules <http:modules.sourceforge.net>`_,
0755 which allows one to easily choose which compiler to use through
0756 ``module load «MODULENAME»``, automatically configuring your environment
0757 for a specific compiler choice (type ``echo $PATH`` to see where
0758 :filelink:`genmake2 <tools/genmake2>` will look for compilers
0759 and system software).
0760
0761 In most cases, your platform configuration will be included in the available
0762 optfiles :filelink:`list <tools/build_options/>` and will result in a
0763 usable ``Makefile`` being generated. If you are unsure which optfile is
0764 correct for your configuration, you can try not specifying an optfile;
0765 on some systems the :filelink:`genmake2 <tools/genmake2>` program will be able
0766 to automatically recognize the hardware, find a compiler and other tools
0767 within the userâs path, and then make a best guess as to an appropriate optfile
3b0572824e Jeff*0768 from the list in the :filelink:`tools/build_options` directory.
e7309a0b9d Jeff*0769 However, for some platforms and code configurations, new
0770 optfiles must be written. To create a new optfile, it is generally
0771 best to start with one of the defaults and modify it to suit your needs.
ba0b047096 Mart*0772 Like
0773 :filelink:`genmake2 <tools/genmake2>`, the optfiles are all written in `bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_
ce0d9af5ea Jeff*0774 (or using a simple
ba0b047096 Mart*0775 `shâcompatible <https://en.wikipedia.org/wiki/Bourne_shell>`_ syntax).
0776 While nearly all
0777 `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
0778 used within :filelink:`genmake2 <tools/genmake2>` may be specified in the
0779 optfiles, the critical ones that should be defined are:
e7309a0b9d Jeff*0780
3b0572824e Jeff*0781 .. _list_of_optfile_env_vars:
0782
e7309a0b9d Jeff*0783 ``FC``
ba0b047096 Mart*0784 the Fortran compiler (executable) to use on ``.F`` files, e.g., ``ifort``
0785 or ``gfortran``, or if using MPI, the mpi-wrapper equivalent,
0786 e.g., ``mpif77``
e7309a0b9d Jeff*0787
0788 ``F90C``
ba0b047096 Mart*0789 the Fortran compiler to use on ``.F90`` files (only necessary if your setup
0790 includes a package which contains ``.F90`` source code)
e7309a0b9d Jeff*0791
0792 ``CC``
ba0b047096 Mart*0793 similarly, the C compiler to use, e.g., ``icc`` or ``gcc``, or if using MPI,
0794 the mpi-wrapper equivalent, e.g., ``mpicc``
e7309a0b9d Jeff*0795
0796 ``DEFINES``
0797 command-line options passed to the compiler
0798
0799 ``CPP``
ba0b047096 Mart*0800 the C preprocessor to use, and any necessary command-line options,
0801 e.g. ``cpp -traditional -P``
e7309a0b9d Jeff*0802
0803 ``CFLAGS``, ``FFLAGS``
ba0b047096 Mart*0804 command-line compiler flags required for your C and Fortran compilers,
0805 respectively, to compile and execute properly. See your C and Fortran
0806 compiler documentation for specific options and syntax.
e7309a0b9d Jeff*0807
0808 ``FOPTIM``
ba0b047096 Mart*0809 command-line optimization Fortran compiler settings. See your Fortran
0810 compiler documentation for specific options and syntax.
e7309a0b9d Jeff*0811
0812 ``NOOPTFLAGS``
ba0b047096 Mart*0813 command-line settings for special files that should not be optimized
0814 using the ``FOPTIM`` flags
3b0572824e Jeff*0815
0816 ``NOOPTFILES``
ba0b047096 Mart*0817 list of source code files that should be compiled using ``NOOPTFLAGS``
0818 settings
e7309a0b9d Jeff*0819
0820 ``INCLUDES``
ba0b047096 Mart*0821 path for additional files (e.g., ``netcdf.inc``, ``mpif.h``) to include
0822 in the compilation using the command-line ``-I`` option
e7309a0b9d Jeff*0823
0824 ``INCLUDEDIRS``
0825 path for additional files to be included in the compilation
0826
0827 ``LIBS``
ba0b047096 Mart*0828 path for additional library files that need to be linked to generate the
0829 final executable, e.g., ``libnetcdf.a``
e7309a0b9d Jeff*0830
ba0b047096 Mart*0831 For example, an excerpt from an optfile which specifies several of these
0832 variables (here, for the linux-amd64 architecture using the PGI Fortran
0833 compiler) is as follows:
e7309a0b9d Jeff*0834
0835 .. literalinclude:: ../../tools/build_options/linux_amd64_pgf77
0836 :start-at: if test "x$MPI" = xtrue ; then
0837 :end-at: F90OPTIM=$FOPTIM
0838
ba0b047096 Mart*0839 The
0840 :ref:`above <list_of_optfile_env_vars>` list of `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
e7309a0b9d Jeff*0841 typically specified in an optfile is by no means complete;
ba0b047096 Mart*0842 additional variables may be required for your specific setup and/or your
0843 specific Fortran (or C) compiler.
e7309a0b9d Jeff*0844
0845 If you write an optfile for an unrepresented machine or compiler, you
0846 are strongly encouraged to submit the optfile to the MITgcm project for
3b0572824e Jeff*0847 inclusion. MITgcm developers are willing to
e7309a0b9d Jeff*0848 provide help writing or modifing optfiles. Please submit the file through
0849 the `GitHub issue tracker <https://github.com/MITgcm/MITgcm/issues>`_
0850 or email the MITgcm-support@mitgcm.org list.
0851
ba0b047096 Mart*0852 Instructions on how to use optfiles to build
0853 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_\ -enabled
0854 executables is presented in :numref:`build_mpi`.
e7309a0b9d Jeff*0855
0856 .. _make_target_commands:
31584ea246 Jeff*0857
0858 ``make`` commands
e7309a0b9d Jeff*0859 -----------------
31584ea246 Jeff*0860
ba0b047096 Mart*0861 Following a successful build of ``Makefile``, type ``make depend``. This
0862 command modifies the ``Makefile`` by attaching a (usually, long) list of
31584ea246 Jeff*0863 files upon which other files depend. The purpose of this is to reduce
0864 re-compilation if and when you start to modify the code. The ``make depend``
ba0b047096 Mart*0865 command also creates local links for all source files from the source
0866 directories (see "-mods" description in :numref:`command_line_options`),
0867 so that all source files to be used are visible from the local build directory,
7b2871578c Jean*0868 either as hardcopy or as symbolic link.
dcd2d356ad chri*0869
31584ea246 Jeff*0870 **IMPORTANT NOTE:** Editing the source code files in the build directory
0871 will not edit a local copy (since these are just links) but will
0872 edit the original files in :filelink:`model/src` (or :filelink:`model/inc`)
0873 or in the specified ``-mods`` directory. While the latter might
0874 be what you intend, editing the master copy in :filelink:`model/src`
ba0b047096 Mart*0875 is usually **NOT** what is intended and may cause grief somewhere down
0876 the road. Rather, if you need to add
31584ea246 Jeff*0877 to the list of modified source code files, place a copy of
0878 the file(s) to edit in the ``-mods`` directory, make the edits to
ba0b047096 Mart*0879 these ``-mods`` directory files, go back to the build directory and
0880 type ``make Clean``, and then re-build the makefile (these latter steps
0881 critical or the makefile will not link to this newly edited file).
31584ea246 Jeff*0882
ba0b047096 Mart*0883 The final ``make`` invokes the
0884 `C preprocessor <https://en.wikipedia.org/wiki/C_preprocessor>`_
e7309a0b9d Jeff*0885 to produce the âlittle fâ files (``*.f`` and ``*.f90``) and then compiles them
516b08a580 jm-c 0886 to object code using the specified Fortran compiler and options.
ba0b047096 Mart*0887 The C preprocessor step converts a number of CPP macros and ``#ifdef``
0888 statements to actual Fortran and expands C-style ``#include`` statements to
0889 incorporate header files into the âlittle f" files. CPP style macros and
0890 ``#ifdef`` statements are used to support generating
dcd2d356ad chri*0891 different compile code for different model configurations.
ba0b047096 Mart*0892 The result of the build process is an executable with the name ``mitgcmuv``.
31584ea246 Jeff*0893
ba0b047096 Mart*0894 Additional make âtargetsâ are defined within the makefile to aid in the
0895 production of adjoint (:numref:`building_adcode_using_taf`) and other
0896 versions of MITgcm.
b3d71355f7 Jeff*0897
e7309a0b9d Jeff*0898 On computers with multiple processor cores, the build process can often be sped
31584ea246 Jeff*0899 up appreciably using the command:
0900
0901 ::
0902
0903 % make -j 2
0904
0905 where the â2â can be replaced with a number that corresponds to the
0906 number of cores (or discrete CPUs) available.
0907
ba0b047096 Mart*0908 In addition, there are several housekeeping ``make clean`` options that might
0909 be useful:
31584ea246 Jeff*0910
ba0b047096 Mart*0911 - ``make clean`` removes files that ``make`` generates
0912 (e.g., \*.o and \*.f files)
0913 - ``make Clean`` removes files and links generated by ``make`` and
0914 ``make depend``; strongly recommended for âun-cleanâ directories which
0915 may contain the (perhaps partial) results of previous builds
0916 - ``make CLEAN`` removes pretty much everything, including any executables
0917 and output from :filelink:`genmake2 <tools/genmake2>`
31584ea246 Jeff*0918
69e7157c80 Jeff*0919 .. _build_mpi:
0920
94151a9b18 Jeff*0921 Building with MPI
0922 -----------------
69e7157c80 Jeff*0923
ba0b047096 Mart*0924 Building MITgcm to use
0925 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ libraries can
0926 be complicated due to the variety of different
0927 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
76a376d977 Jeff*0928 implementations available, their dependencies
69e7157c80 Jeff*0929 or interactions with different compilers, and their often ad-hoc
0930 locations within file systems. For these reasons, its generally a good
0931 idea to start by finding and reading the documentation for your
0932 machine(s) and, if necessary, seeking help from your local systems
0933 administrator.
0934
ba0b047096 Mart*0935 The steps for building MITgcm with
0936 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ support are:
0937
0938 #. Make sure you have
0939 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ libraries
0940 installed on your computer system or cluster. Different Fortran compilers
0941 (and different versions of a specific compiler) will generally require a
0942 custom version (of a
0943 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ library)
0944 built specifically for it.
0945 On `environment module <http:modules.sourceforge.net>`_-enabled
b3d71355f7 Jeff*0946 clusters, one typically must first load a
ba0b047096 Mart*0947 Fortran compiler, then specific
0948 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
0949 libraries for that compiler will become available to load.
0950 If libraries are not installed, MPI implementations and related tools are
0951 available including:
69e7157c80 Jeff*0952
516b08a580 jm-c 0953 - `Open MPI <https://www.open-mpi.org/>`_
69e7157c80 Jeff*0954
0955 - `MVAPICH2 <http:mvapich.cse.ohio-state.edu/>`_
0956
0957 - `MPICH <https://www.mpich.org/>`_
0958
0959 - `Intel MPI <https://software.intel.com/en-us/intel-mpi-library/>`_
0960
e7309a0b9d Jeff*0961 Ask you systems administrator for assistance in installing these libraries.
0962
ba0b047096 Mart*0963 #. Determine the location of your
0964 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
3b0572824e Jeff*0965 library âwrapperâ Fortran compiler, e.g., ``mpif77`` or ``mpifort`` etc.
ba0b047096 Mart*0966 which will be used instead of the name of the fortran compiler
0967 (``gfortran``, ``ifort``, ``pgi77`` etc.) to compile your code.
0968 Often the directory in which these wrappers are located will be
0969 automatically added to your
0970 `$PATH <https://en.wikipedia.org/wiki/PATH_(variable)>`_
0971 `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
0972 when you perform a ``module load «SOME_MPI_MODULE»``; thus, you will not
0973 need to do anything beyond the module load itself.
b3d71355f7 Jeff*0974 If you are on a cluster that does not support
4bad209eba Jeff*0975 `environment modules <http:modules.sourceforge.net>`_,
3b0572824e Jeff*0976 you may have to manually add this directory to your path,
ba0b047096 Mart*0977 e.g., type ``PATH=$PATH:«ADD_ADDITIONAL_PATH_TO_MPI_WRAPPER_HERE»``
0978 in a bash shell.
e7309a0b9d Jeff*0979
ba0b047096 Mart*0980 #. Determine the location of the includes file ``mpif.h`` and any other
0981 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_-related
0982 includes files. Often these files will be located in a subdirectory off
0983 the main `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
4bad209eba Jeff*0984 library ``include/``. In all optfiles in :filelink:`tools/build_options`,
ba0b047096 Mart*0985 it is assumed
0986 `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
516b08a580 jm-c 0987 ``$MPI_INC_DIR`` specifies this location; ``$MPI_INC_DIR``
4bad209eba Jeff*0988 should be set in your terminal session prior to generating a ``Makefile``.
0989
ba0b047096 Mart*0990 #. Determine how many processors (i.e., CPU cores) you will be using in your
0991 run, and modify your configurationâs :filelink:`SIZE.h <model/inc/SIZE.h>`
0992 (located in a âmodified codeâ directory, as specified in your
0993 :filelink:`genmake2 <tools/genmake2>`
0994 :ref:`command-line <command_line_options>`).
0995 In :filelink:`SIZE.h <model/inc/SIZE.h>`,
76a376d977 Jeff*0996 you will need to set variables :varlink:`nPx`\*\ :varlink:`nPy` to
0997 match the number of processors you will specify in
0998 your run scriptâs MITgcm execution statement (i.e., typically ``mpirun``
0999 or some similar command, see :numref:`running_mpi`).
516b08a580 jm-c 1000 Note that MITgcm does not use
ba0b047096 Mart*1001 `dynamic memory allocation <https://en.wikipedia.org/wiki/Memory_management#DYNAMIC>`_
1002 (a feature of
4bad209eba Jeff*1003 `Fortran 90 <https://en.wikipedia.org/wiki/Fortran#Fortran_90>`_,
76a376d977 Jeff*1004 not `FORTRAN 77 <https://en.wikipedia.org/wiki/Fortran#FORTRAN_77>`_), so
1005 all array sizes, and hence the number of processors
ba0b047096 Mart*1006 to be used in your
1007 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ run,
1008 must be specified at compile-time in addition to run-time. More information
1009 about the MITgcm WRAPPER, domain decomposition, and how to configure
1010 :filelink:`SIZE.h <model/inc/SIZE.h>`
4bad209eba Jeff*1011 can be found in :numref:`using_wrapper`.
76a376d977 Jeff*1012
ba0b047096 Mart*1013 #. Build the code with the :filelink:`genmake2 <tools/genmake2>` ``-mpi``
1014 option using commands such as:
69e7157c80 Jeff*1015
1016 ::
1017
e7309a0b9d Jeff*1018 % ../../../tools/genmake2 -mods=../code -mpi -of=«/PATH/TO/OPTFILE»
69e7157c80 Jeff*1019 % make depend
1020 % make
1021
e7309a0b9d Jeff*1022 .. _build_openmp:
1023
1024 Building with OpenMP
1025 ---------------------
1026
ba0b047096 Mart*1027 Unlike MPI, which requires installation of additional software support
1028 libraries, using shared memory
4bad209eba Jeff*1029 (`OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_) for multi-threaded
ba0b047096 Mart*1030 executable builds can be accomplished simply through the
1031 :filelink:`genmake2 <tools/genmake2>` command-line option ``-omp``:
4bad209eba Jeff*1032
1033 ::
1034
1035 % ../../../tools/genmake2 -mods=../code -omp -of=«/PATH/TO/OPTFILE»
1036 % make depend
1037 % make
1038
ba0b047096 Mart*1039 While the most common optfiles specified in :numref:`genmake2_optfiles` include
1040 support for the ``-omp`` option, some optfiles in
1041 :filelink:`tools/build_options` do not include support for multi-threaded
1042 executable builds. Before using one of the less common optfiles,
1043 check whether ``OMPFLAG`` is defined.
4bad209eba Jeff*1044
ba0b047096 Mart*1045 Note that one does not need to specify the number of threads until runtime
1046 (see :numref:`running_openmp`). However, the default maximum number of threads
1047 in MITgcm is set to a (low) value of 4, so if you plan on more you will need
1048 to change this value in :filelink:`eesupp/inc/EEPARAMS.h` in your modified
1049 code directory.
3b0572824e Jeff*1050
69e7157c80 Jeff*1051 .. _run_the_model:
1052
516b08a580 jm-c 1053 Running the model
69e7157c80 Jeff*1054 =================
1055
1056 If compilation finished successfully (:numref:`building_code`) then an
ba0b047096 Mart*1057 executable called ``mitgcmuv`` will now exist in the
1058 local (``build``) directory.
69e7157c80 Jeff*1059
1060 To run the model as a single process (i.e., not in parallel) simply
1061 type (assuming you are still in the ``build`` directory):
1062
1063 ::
1064
1065 % cd ../run
1066 % ln -s ../input/* .
1067 % cp ../build/mitgcmuv .
1068 % ./mitgcmuv
1069
ba0b047096 Mart*1070 Here, we are making a link to all the support data files (in ``../input/``)
1071 needed by the MITgcm for this experiment, and then copying the executable from
1072 the the build directory. The ``./`` in the last step is a safe-guard to make
1073 sure you use the local executable in case you have others that might exist in
1074 your ``$PATH``. The above command will spew out many lines of text output to
1075 your screen. This output contains details such as parameter values as well as
69e7157c80 Jeff*1076 diagnostics such as mean kinetic energy, largest CFL number, etc. It is
1077 worth keeping this text output with the binary output so we normally
1078 re-direct the ``stdout`` stream as follows:
1079
1080 ::
1081
1082 % ./mitgcmuv > output.txt
1083
1084 In the event that the model encounters an error and stops, it is very
1085 helpful to include the last few line of this ``output.txt`` file along
1086 with the (``stderr``) error message within any bug reports.
1087
af61fa61c7 Jeff*1088 For the example experiment in :filelink:`verification/exp2`, an example of the
ba0b047096 Mart*1089 output is kept in :filelink:`verification/exp2/results/output.txt` for
1090 comparison. You can compare your ``output.txt`` with the corresponding one for
1091 that experiment to check that your set-up indeed works. Congratulations!
69e7157c80 Jeff*1092
1093 .. _running_mpi:
1094
1095 Running with MPI
1096 ----------------
1097
ba0b047096 Mart*1098 Run the code with the appropriate
1099 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ ârunâ or
1100 âexecâ program provided with your particular implementation of
1101 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_.
3b0572824e Jeff*1102 Typical `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
ba0b047096 Mart*1103 packages such as `Open MPI <https://www.open-mpi.org/>`_ will
1104 use something like:
69e7157c80 Jeff*1105
1106 ::
1107
1108 % mpirun -np 4 ./mitgcmuv
1109
1110 Sightly more complicated scripts may be needed for many machines
3b0572824e Jeff*1111 since execution of the code may be controlled by both the
1112 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ library
ba0b047096 Mart*1113 and a job scheduling and queueing system such as
1114 `Slurm <https://slurm.schedmd.com/>`_,
31584ea246 Jeff*1115 `PBS/TORQUE <http://www.adaptivecomputing.com/products/open-source/torque>`_,
1116 `LoadLeveler <https://www-03.ibm.com/systems/power/software/loadleveler/>`_,
516b08a580 jm-c 1117 or any of a number of similar tools. See your local cluster documentation
ba0b047096 Mart*1118 or system administrator for the specific syntax required to run on your
1119 computing facility.
69e7157c80 Jeff*1120
4bad209eba Jeff*1121 .. _running_openmp:
1122
1123 Running with OpenMP
1124 -------------------
1125
ba0b047096 Mart*1126 Assuming the executable ``mitgcmuv`` was built with OpenMP
1127 (see :numref:`build_openmp`), the syntax to run a multi-threaded simulation is
1128 the same as running single-threaded (see :numref:`run_the_model`), except that
1129 the following additional steps are required beforehand:
76a376d977 Jeff*1130
516b08a580 jm-c 1131 #. `Environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
ba0b047096 Mart*1132 for the number of threads and the stacksize need to be set prior to
1133 executing the model. The exact names of these
1134 `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_
1135 differ by Fortran compiler, but are typically some variant of
1136 ``OMP_NUM_THREADS`` and ``OMP_STACKSIZE``, respectively.
76a376d977 Jeff*1137 For the latter, in your run script we recommend adding the line
1138 ``export OMP_STACKSIZE=400M`` (or for a
ba0b047096 Mart*1139 `C shell <https://en.wikipedia.org/wiki/C_shell>`_-variant,
1140 ``setenv OMP_STACKSIZE 400M``). If this stacksize setting is insufficient,
1141 MITgcm will crash, in which case a larger number can be used. Similarly,
1142 ``OMP_NUM_THREADS`` should be set to the exact number of threads you require.
1143
1144 #. In file ``eedata`` you will need to change namelist parameters :varlink:`nTx`
1145 and :varlink:`nTy` to reflect the number of threads in x and y, respectively
1146 (for a single-threaded run, :varlink:`nTx` \=\ :varlink:`nTy`\ =1).
76a376d977 Jeff*1147 The value of :varlink:`nTx` \*\ :varlink:`nTy` must equal the value of
ba0b047096 Mart*1148 `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_
1149 ``OMP_NUM_THREADS`` (or its name-equivalent for your Fortan compiler) or
1150 MITgcm will terminate during its initialization with an error message.
1151
1152 MITgcm will take the number of tiles used in the model (as specified in
1153 :filelink:`SIZE.h <model/inc/SIZE.h>`) and the number of threads
1154 (:varlink:`nTx` and :varlink:`nTy` from file ``eedata``),
1155 and in running will spread the tiles out evenly across the threads.
1156 This is done independently for x and y. As such,
1157 the number of tiles in x (variable :varlink:`nSx` as defined in
1158 :filelink:`SIZE.h <model/inc/SIZE.h>`) must divide evenly by
76a376d977 Jeff*1159 the number of threads in x (namelist parameter :varlink:`nTx`),
ba0b047096 Mart*1160 and similarly for :varlink:`nSy` and :varlink:`nTy`, else MITgcm will
1161 terminate on initialization. More information about the MITgcm
1162 WRAPPER, domain decomposition, and how to configure
1163 :filelink:`SIZE.h <model/inc/SIZE.h>` can be found in :numref:`using_wrapper`.
24adb58dd2 Jean*1164
69e7157c80 Jeff*1165 Output files
1166 ------------
1167
76a376d977 Jeff*1168 The model produces various output files and, when using :filelink:`pkg/mnc`
1169 (i.e., `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_),
69e7157c80 Jeff*1170 sometimes even directories. Depending upon the I/O package(s) selected
ba0b047096 Mart*1171 at compile time (either :filelink:`pkg/mdsio`, :filelink:`pkg/mnc`, or both as
1172 determined by ``packages.conf``) and the run-time flags set (in
1173 ``data.pkg``), the following output may appear. More complete information
1174 describing output files and model diagnostics is described
1175 in :numref:`outp_pack`.
69e7157c80 Jeff*1176
9ce7d74115 Jeff*1177 Raw binary output files
1178 ~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff*1179
516b08a580 jm-c 1180 The âtraditionalâ output files are generated by the :filelink:`pkg/mdsio`
ba0b047096 Mart*1181 (see :numref:`pkg_mdsio`).The :filelink:`pkg/mdsio` model data are written
1182 according to a âmeta/dataâ file format. Each variable is associated with two
1183 files with suffix names ``.data`` and ``.meta``. The ``.data`` file contains
1184 the data written in binary form (big endian by default). The ``.meta`` file
69e7157c80 Jeff*1185 is a âheaderâ file that contains information about the size and the
1186 structure of the ``.data`` file. This way of organizing the output is
516b08a580 jm-c 1187 particularly useful when running multi-processors calculations.
69e7157c80 Jeff*1188
1189 At a minimum, the instantaneous âstateâ of the model is written out,
1190 which is made of the following files:
1191
1192 - ``U.00000nIter`` - zonal component of velocity field (m/s and
1193 positive eastward).
1194
1195 - ``V.00000nIter`` - meridional component of velocity field (m/s and
1196 positive northward).
1197
1198 - ``W.00000nIter`` - vertical component of velocity field (ocean: m/s
1199 and positive upward, atmosphere: Pa/s and positive towards increasing
1200 pressure i.e., downward).
1201
1202 - ``T.00000nIter`` - potential temperature (ocean:
ce0d9af5ea Jeff*1203 :math:`^{\circ}\mathrm{C}`, atmosphere: :math:`\mathrm{K}`).
69e7157c80 Jeff*1204
ba0b047096 Mart*1205 - ``S.00000nIter`` - ocean: salinity (g/kg), atmosphere: water vapor
69e7157c80 Jeff*1206 (g/kg).
1207
1208 - ``Eta.00000nIter`` - ocean: surface elevation (m), atmosphere:
1209 surface pressure anomaly (Pa).
1210
1211 The chain ``00000nIter`` consists of ten figures that specify the
1212 iteration number at which the output is written out. For example,
1213 ``U.0000000300`` is the zonal velocity at iteration 300.
1214
1215 In addition, a âpickupâ or âcheckpointâ file called:
1216
1217 - ``pickup.00000nIter``
1218
1219 is written out. This file represents the state of the model in a
ba0b047096 Mart*1220 condensed form and is used for restarting the integration (at the specific
1221 iteration number). Some additional parameterizations and packages also produce
1222 separate pickup files, e.g.,
69e7157c80 Jeff*1223
ba0b047096 Mart*1224 - ``pickup_cd.00000nIter`` if the C-D scheme is used (see
1225 :ref:`C_D Scheme <C-D_scheme>`)
69e7157c80 Jeff*1226
ba0b047096 Mart*1227 - ``pickup_seaice.00000nIter`` if the seaice package is turned on (see
1228 :ref:`sub_phys_pkg_seaice`)
69e7157c80 Jeff*1229
ba0b047096 Mart*1230 - ``pickup_ptracers.00000nIter`` if passive tracers are included in the
1231 simulation (see :ref:`sub_phys_pkg_ptracers`)
69e7157c80 Jeff*1232
1233 Rolling checkpoint files are
1234 the same as the pickup files but are named differently. Their name
1235 contain the chain ``ckptA`` or ``ckptB`` instead of ``00000nIter``. They
1236 can be used to restart the model but are overwritten every other time
1237 they are output to save disk space during long integrations.
1238
9ce7d74115 Jeff*1239 NetCDF output files
1240 ~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff*1241
9ce7d74115 Jeff*1242 :filelink:`pkg/mnc` is a set of routines written to read, write, and
1243 append `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ files.
ba0b047096 Mart*1244 Unlike the :filelink:`pkg/mdsio` output, the :filelink:`pkg/mnc`âgenerated
1245 output is usually placed within a subdirectory with a name such as
ce0d9af5ea Jeff*1246 ``mnc_output_`` (by default,
ba0b047096 Mart*1247 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ tries to append,
1248 rather than overwrite, existing files,
69e7157c80 Jeff*1249 so a unique output directory is helpful for each separate run).
1250
ba0b047096 Mart*1251 The :filelink:`pkg/mnc` output files are all in the âself-describingâ
1252 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ format and
69e7157c80 Jeff*1253 can thus be browsed and/or plotted using tools such as:
1254
af61fa61c7 Jeff*1255 - `ncdump <https://www.unidata.ucar.edu/software/netcdf/netcdf-4/newdocs/netcdf/ncdump.html>`_
ba0b047096 Mart*1256 is a utility which is typically included with every
1257 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
1258 install, and converts the
1259 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ binaries
1260 into formatted ASCII text files.
69e7157c80 Jeff*1261
af61fa61c7 Jeff*1262 - `ncview <http://meteora.ucsd.edu/~pierce/ncview_home_page.html>`_
ba0b047096 Mart*1263 is a very convenient and quick way to plot
1264 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
1265 data and it runs on most platforms.
1266 `Panoply <https://www.giss.nasa.gov/tools/panoply/>`_ is a similar
1267 alternative.
1268
1269 - `MATLAB <https://www.mathworks.com/products/matlab.html>`_,
1270 `GrADS <http://cola.gmu.edu/grads/>`_,
1271 `IDL <http://www.harrisgeospatial.com/SoftwareTechnology/IDL.aspx>`_ and
1272 other common post-processing environments provide
9ce7d74115 Jeff*1273 built-in `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ interfaces.
1274
69e7157c80 Jeff*1275 Looking at the output
1276 ---------------------
1277
9ce7d74115 Jeff*1278 MATLAB
1279 ~~~~~~
69e7157c80 Jeff*1280
9ce7d74115 Jeff*1281 Raw binary output
1282 ^^^^^^^^^^^^^^^^^
69e7157c80 Jeff*1283
ba0b047096 Mart*1284 The repository includes a few
1285 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ utilities to read
1286 binary output files written in the :filelink:`/pkg/mdsio` format. The
1287 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ scripts are located
1288 in the directory :filelink:`utils/matlab` under the root tree. The script
1289 :filelink:`utils/matlab/rdmds.m` reads the data. Look at the comments inside
1290 the script to see how to use it.
69e7157c80 Jeff*1291
ba0b047096 Mart*1292 Some examples of reading and visualizing some output in
1293 `MATLAB <https://www.mathworks.com/products/matlab.html>`_:
69e7157c80 Jeff*1294
1295 ::
1296
1297 % matlab
1298 >> H=rdmds('Depth');
1299 >> contourf(H');colorbar;
1300 >> title('Depth of fluid as used by model');
1301
1302 >> eta=rdmds('Eta',10);
1303 >> imagesc(eta');axis ij;colorbar;
1304 >> title('Surface height at iter=10');
1305
83cdbd2346 Jeff*1306 >> [eta,iters,M]=rdmds('Eta',NaN); % this will read all dumped iterations
1307 >> % iter numbers put in variable 'iters'; 'M' is a character string w/metadata
1308 >> for n=1:length(iters); imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
1309
ba0b047096 Mart*1310 Typing ``help rdmds`` in
1311 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ will pull up further
83cdbd2346 Jeff*1312 information on how to use the :filelink:`rdmds <utils/matlab/rdmds.m>` utility.
69e7157c80 Jeff*1313
516b08a580 jm-c 1314 NetCDF output
9ce7d74115 Jeff*1315 ^^^^^^^^^^^^^
69e7157c80 Jeff*1316
ba0b047096 Mart*1317 Similar scripts for `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_
1318 output (e.g., :filelink:`utils/matlab/rdmnc.m`) are available and they
9ce7d74115 Jeff*1319 are described in :numref:`pkg_mnc`.
69e7157c80 Jeff*1320
7621b5d564 Oliv*1321 .. _sec_python:
1322
9ce7d74115 Jeff*1323 Python
1324 ~~~~~~
69e7157c80 Jeff*1325
ba0b047096 Mart*1326 Install the MITgcmutils python package following the instructions in
1327 :numref:`MITgcmutils`.
7621b5d564 Oliv*1328
9ce7d74115 Jeff*1329 Raw binary output
1330 ^^^^^^^^^^^^^^^^^
69e7157c80 Jeff*1331
1332 The following example shows how to load in some data:
1333
1334 ::
516b08a580 jm-c 1335
69e7157c80 Jeff*1336 # python
7621b5d564 Oliv*1337 from MITgcmutils import mds
69e7157c80 Jeff*1338
1339 Eta = mds.rdmds('Eta', itrs=10)
1340
83cdbd2346 Jeff*1341 For more information about this function and its options,
7621b5d564 Oliv*1342 see the API docs, :meth:`MITgcmutils.mds.rdmds`.
69e7157c80 Jeff*1343
516b08a580 jm-c 1344 NetCDF output
9ce7d74115 Jeff*1345 ^^^^^^^^^^^^^
69e7157c80 Jeff*1346
9ce7d74115 Jeff*1347 The `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ output
ba0b047096 Mart*1348 is currently produced with one file per processor. This means the individual
1349 tiles need to be stitched together to create a single
1350 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ file that spans the
1351 model domain. The script :filelink:`utils/python/MITgcmutils/scripts/gluemncbig`
1352 can do this efficiently from the command line. If you have installed the
1353 MITgcmutils package, a copy of gluemncbig should be on your path. For usage
1354 information, see :numref:`gluemncbig`.
1355
1356 The following example shows how to use the
1357 `xarray python package <http://xarray.pydata.org/>`_ to read
1358 the resulting `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ file
1359 into `Python <https://www.python.org/>`_:
9ce7d74115 Jeff*1360
69e7157c80 Jeff*1361 ::
516b08a580 jm-c 1362
69e7157c80 Jeff*1363 # python
1364 import xarray as xr
1365
1366 Eta = xr.open_dataset('Eta.nc')
1367
dcaaa42497 Jeff*1368 .. _customize_compilation:
1369
1370 Customizing the Model Configuration - Code Parameters and Compilation Options
1371 =============================================================================
1372
1373 Model Array Dimensions
1374 ----------------------
1375
1376 MITgcmâs array dimensions need to be configured for each unique model domain.
ba0b047096 Mart*1377 The size of each tile (in dimensions :math:`x`, :math:`y`, and vertical
1378 coordinate :math:`r`) the âoverlapâ region of each tile (in :math:`x` and
1379 :math:`y`), the number of tiles in the :math:`x` and :math:`y` dimensions,
1380 and the number of processes (using
1381 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_)
1382 in the :math:`x` and :math:`y` dimensions all need to be specified in
1383 :filelink:`SIZE.h <model/inc/SIZE.h>`. From these parameters, global
1384 domain-size variables :varlink:`Nx`, :varlink:`Ny` are computed by the model.
1385 See a more technical discussion of :filelink:`SIZE.h <model/inc/SIZE.h>`
1386 parameters in in :numref:`specify_decomp`, and a detailed explanation of an
1387 example :filelink:`SIZE.h <model/inc/SIZE.h>` setup in tutorial
1388 :ref:`Baroclinic Ocean Gyre <baroc_code_size>`.
dcaaa42497 Jeff*1389
1390 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1391 | Parameter | Default :filelink:`SIZE.h <model/inc/SIZE.h>` | Description |
1392 +========================================+==================================================+=========================================================================================================+
1393 | :varlink:`sNx` | 30 | number of points in :math:`x` dimension in a single tile |
1394 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1395 | :varlink:`sNy` | 15 | number of points in :math:`y` dimension in a single tile |
1396 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1397 | :varlink:`Nr` | 4 | number of points in :math:`r` dimension |
1398 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1399 | :varlink:`OLx` | 2 | number of âoverlapâ points in :math:`x` dimension for a tile |
1400 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1401 | :varlink:`OLy` | 2 | number of âoverlapâ points in :math:`y` dimension for a tile |
1402 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1403 | :varlink:`nSx` | 2 | number of tile per process in :math:`x` dimension |
1404 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1405 | :varlink:`nSy` | 4 | number of tile per process in :math:`y` dimension |
1406 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1407 | :varlink:`nPx` | 1 | number of processes in :math:`x` dimension |
1408 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1409 | :varlink:`nPy` | 1 | number of processes in :math:`y` dimension |
1410 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1411
ba0b047096 Mart*1412 Note the repository version of :filelink:`SIZE.h <model/inc/SIZE.h>` includes
1413 several lines of text at the top that will halt compilation with errors. Thus,
1414 to use MITgcm you will need to copy :filelink:`SIZE.h <model/inc/SIZE.h>` to a
1415 code modification directory and make edits, including deleting or commenting
1416 out the offending lines of text.
dcaaa42497 Jeff*1417
1418 C Preprocessor Options
1419 ----------------------
1420
1421 The CPP flags relative to the ânumerical modelâ part of the code are
ba0b047096 Mart*1422 defined and set in the file :filelink:`CPP_OPTIONS.h <model/inc/CPP_OPTIONS.h>`
1423 in the directory :filelink:`model/inc/`. In the parameter tables in
1424 :numref:`customize_model` we have noted CPP options **that need to be changed
1425 from the default** to enable specific runtime parameter to be used properly.
1426 Also note many of the options below are for less-common situations or are
1427 somewhat obscure, so newer users of the MITgcm are encouraged to jump to
1428 :numref:`customize_model` where more basic runtime parameters are discussed.
dcaaa42497 Jeff*1429
1430 .. tabularcolumns:: |\Y{.475}|\Y{.1}|\Y{.45}|
1431
a332812c22 Jeff*1432 .. table::
1433 :class: longtable
1434
1435 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1436 | CPP Flag Name | Default | Description |
1437 +===============================================+=========+======================================================================================================================+
1438 | :varlink:`SHORTWAVE_HEATING` | #undef | provide separate shortwave heating file, allowing shortwave to penetrate below surface layer |
1439 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1440 | :varlink:`ALLOW_GEOTHERMAL_FLUX` | #undef | include code for applying geothermal heat flux at the bottom of the ocean |
1441 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1442 | :varlink:`ALLOW_FRICTION_HEATING` | #undef | include code to allow heating due to friction (and momentum dissipation) |
1443 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1444 | :varlink:`ALLOW_ADDFLUID` | #undef | allow mass source or sink of fluid in the interior (3D generalization of oceanic real-fresh water flux) |
1445 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1446 | :varlink:`ATMOSPHERIC_LOADING` | #define | include code for atmospheric pressure-loading (and seaice-loading) on ocean surface |
1447 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1448 | :varlink:`ALLOW_BALANCE_FLUXES` | #undef | include balancing surface forcing fluxes code |
1449 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1450 | :varlink:`ALLOW_BALANCE_RELAX` | #undef | include balancing surface forcing relaxation code |
1451 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1452 | :varlink:`CHECK_SALINITY_FOR_NEGATIVE_VALUES` | #undef | include code checking for negative salinity |
1453 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1454 | :varlink:`EXCLUDE_FFIELDS_LOAD` | #undef | exclude external forcing-fields load; code allows reading and simple linear time interpolation of oceanic |
1455 | | | forcing fields, if no specific pkg (e.g., :filelink:`pkg/exf`) is used to compute them |
1456 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0bad585a21 Navi*1457 | :varlink:`INCLUDE_PHIHYD_CALCULATION_CODE` | #define | include code to calculate :math:`\phi_{\rm hyd}` |
a332812c22 Jeff*1458 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1459 | :varlink:`INCLUDE_CONVECT_CALL` | #define | include code for convective adjustment mixing algorithm |
1460 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1461 | :varlink:`INCLUDE_CALC_DIFFUSIVITY_CALL` | #define | include codes that calculates (tracer) diffusivities and viscosities |
1462 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1463 | :varlink:`ALLOW_3D_DIFFKR` | #undef | allow full 3D specification of vertical diffusivity |
1464 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1465 | :varlink:`ALLOW_BL79_LAT_VARY` | #undef | allow latitudinally varying Bryan and Lewis 1979 :cite:`bryan:79` vertical diffusivity |
1466 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1467 | :varlink:`EXCLUDE_PCELL_MIX_CODE` | #undef | exclude code for partial-cell effect (physical or enhanced) in vertical mixing; this allows accounting |
1468 | | | for partial-cell in vertical viscosity and diffusion, either from grid-spacing reduction effect or as |
1469 | | | artificially enhanced mixing near surface & bottom for too thin grid-cell |
1470 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
dafe4f37ba Jean*1471 | :varlink:`ALLOW_SMAG_3D_DIFFUSIVITY` | #undef | include code for isotropic 3-D Smagorinsky diffusivity for tracers (viscosity scaled by constant Prandtl number) |
1472 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*1473 | :varlink:`ALLOW_SOLVE4_PS_AND_DRAG` | #undef | include code for combined surface pressure and drag implicit solver |
1474 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1475 | :varlink:`INCLUDE_IMPLVERTADV_CODE` | #define | include code for implicit vertical advection |
1476 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1477 | :varlink:`ALLOW_ADAMSBASHFORTH_3` | #undef | include code for Adams-Bashforth 3rd-order |
1478 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
5e119ceb68 Jeff*1479 | :varlink:`ALLOW_QHYD_STAGGER_TS` | #undef | include code for quasi-hydrostatic stagger time-step Adams-Bashforth code |
dafe4f37ba Jean*1480 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*1481 | :varlink:`EXACT_CONSERV` | #define | include code for âexact conservation" of fluid in free-surface formulation |
1482 | | | (recompute divergence after pressure solver) |
1483 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1484 | :varlink:`NONLIN_FRSURF` | #undef | allow the use of non-linear free-surface formulation; implies that grid-cell thickness (hFactors) varies with time |
1485 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1486 | :varlink:`ALLOW_NONHYDROSTATIC` | #undef | include non-hydrostatic and 3D pressure solver codes |
1487 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1488 | :varlink:`ALLOW_EDDYPSI` | #undef | include GM-like eddy stress in momentum code (untested, not recommended) |
1489 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1490 | :varlink:`ALLOW_CG2D_NSA` | #undef | use non-self-adjoint (NSA) conjugate-gradient solver |
1491 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1492 | :varlink:`ALLOW_SRCG` | #define | include code for single reduction conjugate gradient solver |
1493 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1494 | :varlink:`SOLVE_DIAGONAL_LOWMEMORY` | #undef | low memory footprint (not suitable for AD) choice for implicit solver routines solve_*diagonal.F |
1495 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1496 | :varlink:`SOLVE_DIAGONAL_KINNER` | #undef | choice for implicit solver routines solve_*diagonal.F suitable for AD |
1497 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*1498
94151a9b18 Jeff*1499 .. _default_pkg_list:
1500
ba0b047096 Mart*1501 By default, MITgcm includes several core packages, i.e., these packages are
1502 enabled during :filelink:`genmake2 <tools/genmake2>` execution if a file
1503 ``packages.conf`` is not found. See :numref:`using_packages` for more
1504 information about ``packages.conf``, and see :filelink:`pkg/pkg_groups` for
1505 more information about default packages and package groups.
dcaaa42497 Jeff*1506 These default packages are as follows:
1507
1508 - :filelink:`pkg/mom_common`
1509 - :filelink:`pkg/mom_fluxform`
1510 - :filelink:`pkg/mom_vecinv`
1511 - :filelink:`pkg/generic_advdiff`
1512 - :filelink:`pkg/debug`
1513 - :filelink:`pkg/mdsio`
1514 - :filelink:`pkg/rw`
1515 - :filelink:`pkg/monitor`
1516
ba0b047096 Mart*1517 Additional CPP options that affect the model core code are set in files
1518 ``${PKG}_OPTIONS.h`` located in these packages' directories. Similarly,
1519 optional (non-default) packages also include package-specific CPP options that
1520 must be set in files ``${PKG}_OPTIONS.h``.
dcaaa42497 Jeff*1521
bcfb652725 Jeff*1522 .. _cpp_eeoptions_doc:
1523
1524 Preprocessor Execution Environment Options
1525 ------------------------------------------
1526
1527 **Most MITgcm users can skip this section**; many of these flags were
1528 intended for very specific platform environments, and not meant to be changed
1529 for more general environments (an exception being if you are using a coupled
1530 setup, see below).
1531
1532 The file :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` in the
1533 directory :filelink:`eesupp/inc/` contains a number of CPP flags related to
1534 the execution environment where the model will run. Below we describe the
1535 subset of user-editable CPP flags:
1536
1537 .. tabularcolumns:: |\Y{.475}|\Y{.1}|\Y{.45}|
1538
1539 .. table::
1540 :class: longtable
1541 :name: cpp_eeopt_flags
1542
1543 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1544 | CPP Flag Name | Default | Description |
1545 +===============================================+=========+======================================================================================================================+
1546 | :varlink:`GLOBAL_SUM_ORDER_TILES` | #define | always cumulate tile local-sum in the same order by applying MPI allreduce to array of tiles |
1547 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1548 | :varlink:`CG2D_SINGLECPU_SUM` | #undef | alternative way of doing global sum on a single CPU to eliminate tiling-dependent roundoff errors |
1549 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1550 | :varlink:`SINGLE_DISK_IO` | #undef | to write STDOUT, STDERR and scratch files from process 0 only |
1551 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1552 | :varlink:`USE_FORTRAN_SCRATCH_FILES` | #undef | flag to turn on old default of opening scratch files with the STATUS='SCRATCH' option |
1553 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1554 | :varlink:`COMPONENT_MODULE` | #undef | control use of communication with other components, i.e., sets component to work with a coupler interface |
1555 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1556 | :varlink:`DISCONNECTED_TILES` | #undef | use disconnected tiles (no exchange between tiles, just fill-in edges assuming locally periodic subdomain) |
1557 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1558 | :varlink:`REAL4_IS_SLOW` | #define | if undefined, force ``_RS`` variables to be declared as real*4 |
1559 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
1560
1561 The default setting of ``#define`` :varlink:`GLOBAL_SUM_ORDER_TILES` in
1562 :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` provides a way to
1563 achieve numerically reproducible global sums for a given tile domain
1564 decomposition. As implemented however, this
1565 approach will increase the volume of network traffic in a way that scales
1566 with the total number of tiles.
1567 Profiling has shown that letting the code fall through to a baseline
1568 approach that simply uses
1569 `MPI_Allreduce() <https://www.open-mpi.org/doc/v3.0/man3/MPI_Allreduce.3.php>`_
1570 can provide significantly improved performance for certain simulations [#]_.
1571 The fall-though approach is activated by ``#undef``
1572 :varlink:`GLOBAL_SUM_ORDER_TILES`.
1573
1574 In order to get bit-wise reproducible results between different tile domain
1575 decompositions (e.g., single tile on single processor versus multiple tiles
1576 either on single or multiple processors), one can choose to ``#define``
1577 option :varlink:`CG2D_SINGLECPU_SUM` to use the **MUCH** slower
1578 :filelink:`global_sum_singlecpu.F <eesupp/src/global_sum_singlecpu.F>`
1579 for the key part of MITgcm algorithm :filelink:`CG2D <model/src/cg2d.F>`
1580 that relies on global sum.
1581 This option is not only much slower but also requires a large volume of
1582 communications so it is practically unusable for a large set-up;
1583 furthermore, it does not address reproducibility when global sum is used
1584 outside :filelink:`CG2D <model/src/cg2d.F>`, e.g., in non-hydrostatic simulations.
1585
1586 In a default multi-processor configuration, each process opens and reads its
1587 own set of namelist files and open and writes its own standard output. This can
1588 be slow or even problematic for very large processor counts. Defining the
1589 CPP-flag :varlink:`SINGLE_DISK_IO` suppresses this behavior and lets only the
1590 master process (process 0) read namelist files and write a standard output
1591 stream. This may seem advantageous, because it reduces the amount of seemingly
1592 redundant output, but use this option with caution and only when absolutely
1593 confident that the setup is working since any message (error/warning/print)
1594 from any processor :math:`\ne 0` will be lost.
1595
1596 The way the namelist files are read requires temporary (scratch) files in the
1597 initialization phase. By default, the MITgcm does not use intrinsic Fortran
1598 scratch files (``STATUS='scratch'``) because they can lead to conflicts in
1599 multi-processor simulations on some HPC-platforms, when the processors do not
1600 open scratch files with reserved names. However, the implemented default scheme
1601 for the scratch files can be slow for large processor counts. If this is a
1602 problem in a given configuration, defining the CPP-flag
1603 :varlink:`USE_FORTRAN_SCRATCH_FILES` may help by making the code use the
1604 intrinsic Fortran scratch files.
1605
1606 The CPP-flag :varlink:`COMPONENT_MODULE` needs to be set to ``#define`` only for
1607 builds in which the MITgcm executable (for either an oceanic or atmospheric
1608 simulation) is configured to communicate with a coupler.
1609 This coupler can be a specially configured build of MITgcm itself;
1610 see, for example, verification experiment `cpl_aim+ocn
1611 <https://github.com/MITgcm/MITgcm/tree/master/verification/cpl_aim+ocn>`_.
1612
1613 The CPP-flag :varlink:`DISCONNECTED_TILES` should not be ``#define``
1614 unless one wants to run simultaneously several small, single-tile ensemble
1615 members from a single process, as each tile will be disconnected from the others
1616 and considered locally as a doubly periodic patch.
1617
1618 ..
1619 should reference the to-be-written section about _RS, _RL within chapter 6
1620
1621 MITgcm ``_RS`` variables are forced to be declared as
1622 ``real*4`` if CPP-flag :varlink:`REAL4_IS_SLOW` to is set to ``#undef``
1623 in :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>`
1624 (``_RS`` is a macro used in declaring real variables that, in principle,
1625 do not require double precision). However, this option is not recommended
1626 except for computational benchmarking or for testing the trade-off between memory
1627 footprint and model precision. And even for these specialized tests, there is no need
1628 to edit :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>`
1629 since this feature can be activated using the :filelink:`genmake2 <tools/genmake2>`
1630 command line option ``-use_r4``, as done in some regression tests
1631 (see testing `results <https://mitgcm.org/testing-summary>`_
1632 page tests with optfile suffix ``.use_r4``).
1633
1634 .. [#] One example is the llc_540 case located at
1635 https://github.com/MITgcm-contrib/llc_hires/tree/master/llc_540. This case
1636 was run on the Pleiades computer for 20 simulated days using 767 and 2919
1637 MPI ranks. At 767 ranks, the fall-through approach provided a throughput of
1638 to 799.0 simulated days per calendar day (dd/d) while the default approach
1639 gave 781.0. The profiler showed the speedup was directly attributable to
1640 spending less time in MPI_Allreduce. The volume of memory traffic associated
1641 with MPI_Allreduce dropped by 3 orders (22.456T -> 32.596G). At 2819 MPI
1642 ranks the fall-through approach gave a throughput of 1300 dd/d while the
1643 default approach gave 800.0 dd/d. Put another way, this case did not scale
1644 at all from 767p to 2819p unless the fall-though approach was utilized. The
1645 profiler showed the speedup was directly attributable to spending less time
1646 in MPI_Allreduce. The volume of memory traffic associated with MPI_Allreduce
1647 dropped by 3 orders (303.70T ->121.08G ).
dcaaa42497 Jeff*1648
af61fa61c7 Jeff*1649 .. _customize_model:
1650
dcaaa42497 Jeff*1651 Customizing the Model Configuration - Runtime Parameters
1652 ========================================================
69e7157c80 Jeff*1653
1654 When you are ready to run the model in the configuration you want, the
ba0b047096 Mart*1655 most straightforward approach is to use and adapt the setup of a tutorial or
1656 verification experiment (described in :numref:`chap_modelExamples`) that is the
1657 closest to your configuration. Then, the amount of setup will be minimized.
1658 In this section, we document the complete list of MITgcm model namelist runtime
dcaaa42497 Jeff*1659 parameters set in file ``data``, which needs to be located in the
516b08a580 jm-c 1660 directory where you will run the model.
dcaaa42497 Jeff*1661 Model parameters are defined and
ba0b047096 Mart*1662 declared in the file :filelink:`PARAMS.h <model/inc/PARAMS.h>` and their
1663 default values are generally set in the routine
1664 :filelink:`set_defaults.F <model/src/set_defaults.F>`, otherwise
1665 when initialized in the routine :filelink:`ini_parms.F <model/src/ini_parms.F>`.
1666 :numref:`eedata_parms` documents the âexecution environmentâ namelist parameters
dcaaa42497 Jeff*1667 in file ``eedata``, which must also reside in the current run directory.
ba0b047096 Mart*1668 Note that runtime parameters used by (non-default) MITgcm packages are not
1669 documented here but rather in :numref:`packagesI`
1670 and :numref:`outp_pack`, and prescribed in package-specific ``data.${pkg}``
1671 namelist files which are read in via package-specific
1672 ``${pkg}_readparms.F`` where ``${pkg}`` is the package name
dcaaa42497 Jeff*1673 (see :numref:`using_packages`).
69e7157c80 Jeff*1674
dcaaa42497 Jeff*1675 In what follows, model parameters are grouped into categories related to
ba0b047096 Mart*1676 configuration/computational domain, algorithmic parameters, equations solved
1677 in the model, parameters related to model forcing, and simulation controls.
1678 The tables below specify the namelist parameter name, the namelist parameter
1679 group in ``data`` (and ``eedata`` in :numref:`eedata_parms`), the default
1680 value, and a short description of its function. Runtime parameters that
1681 require **non-default** CPP options to be set prior to compilation
1682 (see :numref:`customize_compilation`) for proper use are noted.
dcaaa42497 Jeff*1683
516b08a580 jm-c 1684 Parameters: Configuration, Computational Domain, Geometry, and Time-Discretization
dcaaa42497 Jeff*1685 ----------------------------------------------------------------------------------
1686
1687 .. _model_config_parms:
1688
1689 Model Configuration
1690 ~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff*1691
ba0b047096 Mart*1692 :varlink:`buoyancyRelation` is set to ``OCEANIC`` by default, which employes a
1693 :math:`z`-coordinate vertical axis. To simulate an ocean using pressure
1694 coordinates in the vertical, set it to ``OCEANICP``. For atmospheric
1695 simulations, :varlink:`buoyancyRelation` needs to be set to ``ATMOSPHERIC``,
1696 which also uses pressure as the vertical coordinate.
1697 The default model configuration is hydrostatic; to run a non-hydrostatic
1698 simulation, set the logical variable :varlink:`nonHydrostatic` to ``.TRUE.``.
69e7157c80 Jeff*1699
dcaaa42497 Jeff*1700 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
69e7157c80 Jeff*1701
dcaaa42497 Jeff*1702 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1703 | Parameter | Group | Default | Description |
1704 +========================================+===========+==================================================+=========================================================================================================+
1705 | :varlink:`buoyancyRelation` | PARM01 | OCEANIC | buoyancy relation (``OCEANIC``, ``OCEANICP``, or ``ATMOSPHERIC``) |
1706 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1707 | :varlink:`quasiHydrostatic` | PARM01 | FALSE | quasi-hydrostatic formulation on/off flag |
1708 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1709 | :varlink:`rhoRefFile` | PARM01 | :kbd:`' '` | filename for reference density profile (kg/m\ :sup:`3`); activates anelastic form of model |
1710 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1711 | :varlink:`nonHydrostatic` | PARM01 | FALSE | non-hydrostatic formulation on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
1712 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
69e7157c80 Jeff*1713
1714 Grid
dcaaa42497 Jeff*1715 ~~~~
1716
1717 Four different grids are available: Cartesian, spherical polar, cylindrical, and
1718 curvilinear (which includes the cubed sphere). The grid is set
1719 through the logical variables :varlink:`usingCartesianGrid`,
1720 :varlink:`usingSphericalPolarGrid`, :varlink:`usingCylindricalGrid`,
ba0b047096 Mart*1721 and :varlink:`usingCurvilinearGrid`. Note that the cylindrical grid is designed
1722 for modeling a rotating tank, so that :math:`x` is the azimuthual direction,
1723 :math:`y` is the radial direction, and :math:`r` is vertical coordinate
1724 (see tutorial :ref:`rotating tank <sec_eg_tank>`).
dcaaa42497 Jeff*1725
1726 The variable :varlink:`xgOrigin` sets the position of the western
ba0b047096 Mart*1727 most gridcell face in the :math:`x` dimension (Cartesian, meters; spherical and
1728 cyclindrical, degrees). For a Cartesian or spherical grid, the southern boundary
1729 is defined through the variable :varlink:`ygOrigin` which corresponds to the
1730 latitude of the southern most gridcell face (Cartesian, meters; spherical,
1731 degrees). For a cyclindrical grid, a positive :varlink:`ygOrigin` (m) adds an
1732 inner cylindrical boundary at the center of the tank. The resolution
1733 along the :math:`x` and :math:`y` directions is controlled by the 1-D arrays
1734 :varlink:`delX` (meters for a Cartesian grid, degrees otherwise)
1735 and :varlink:`delY` (meters for Cartesian and cyclindrical grids, degrees
1736 spherical). On a spherical polar grid, you might decide to set the variable
1737 :varlink:`cosPower` which is set to 0 by default and which represents :math:`n`
1738 in :math:`(\cos\varphi)^n`, the power of cosine of latitude to
dcaaa42497 Jeff*1739 multiply horizontal viscosity and tracer diffusivity.
83cdbd2346 Jeff*1740 The vertical grid spacing is set through the 1-D array
ba0b047096 Mart*1741 :varlink:`delR` (:math:`z`-coordinates: in meters; :math:`p`-coordinates,
1742 in Pa). Using a curvilinear grid requires complete specification of all
1743 horizontal MITgcm grid variables, either through a default filename (link to
1744 new doc section) or as specified by :varlink:`horizGridFile`.
dcaaa42497 Jeff*1745
1746 The variable :varlink:`seaLev_Z` represents the standard
1747 position of sea level, in meters. This is typically set to 0 m
ba0b047096 Mart*1748 for the ocean (default value). If instead pressure is used as the vertical
1749 coordinate, the pressure at the top (of the atmosphere or ocean) is set through
1750 :varlink:`top_Pres`, typically 0 Pa. As such, these variables are analogous to
1751 :varlink:`xgOrigin` and :varlink:`ygOrigin` to define the vertical grid axis.
1752 But they also are used for a second purpose: in a :math:`z`-coordinate setup,
1753 :varlink:`top_Pres` sets a reference top pressure (required in a non-linear
1754 equation of state computation, for example); note that 1 bar
1755 (i.e., typical Earth atmospheric sea-level pressure) is added already, so the
1756 default is 0 Pa. Similarly, for a :math:`p`-coordinate setup,
1757 :varlink:`seaLev_Z` is used to set a reference geopotential (after gravity
1758 scaling) at the top of the ocean or bottom of the atmosphere.
dcaaa42497 Jeff*1759
1760 .. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}|
1761
a332812c22 Jeff*1762 .. table::
1763 :class: longtable
1764
1765 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1766 | Parameter | Group | Default | Description |
1767 +========================================+===========+==================================================+=========================================================================================================+
1768 | :varlink:`usingCartesianGrid` | PARM04 | TRUE | use Cartesian grid/coordinates on/off flag |
1769 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1770 | :varlink:`usingSphericalPolarGrid` | PARM04 | FALSE | use spherical grid/coordinates on/off flag |
1771 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1772 | :varlink:`usingCylindricalGrid` | PARM04 | FALSE | use cylindrical grid/coordinates on/off flag |
1773 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1774 | :varlink:`usingCurvilinearGrid` | PARM04 | FALSE | use curvilinear grid/coordinates on/off flag |
1775 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1776 | :varlink:`xgOrigin` | PARM04 | 0.0 | west edge :math:`x`-axis origin (Cartesian: m; spherical and cyclindrical: degrees longitude) |
1777 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1778 | :varlink:`ygOrigin` | PARM04 | 0.0 | South edge :math:`y`-axis origin (Cartesian and cyclindrical: m; spherical: degrees latitude) |
1779 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1780 | :varlink:`dxSpacing` | PARM04 | unset | :math:`x`-axis uniform grid spacing, separation between cell faces |
1781 | | | | (Cartesian: m; spherical and cyclindrical: degrees) |
1782 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1783 | :varlink:`delX` | PARM04 | :varlink:`dxSpacing` | 1D array of :math:`x`-axis grid spacing, separation between cell faces |
1784 | | | | (Cartesian: m; spherical and cyclindrical: degrees) |
1785 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1786 | :varlink:`delXFile` | PARM04 | :kbd:`' '` | filename containing 1D array of :math:`x`-axis grid spacing |
1787 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1788 | :varlink:`dySpacing` | PARM04 | unset | :math:`y`-axis uniform grid spacing, separation between cell faces |
1789 | | | | (Cartesian and cyclindrical: m; spherical: degrees) |
1790 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1791 | :varlink:`delY` | PARM04 | :varlink:`dySpacing` | 1D array of :math:`x`-axis grid spacing, separation between cell faces |
1792 | | | | (Cartesian and cyclindrical: m; spherical: degrees) |
1793 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1794 | :varlink:`delYFile` | PARM04 | :kbd:`' '` | filename containing 1D array of :math:`y`-axis grid spacing |
1795 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1796 | :varlink:`cosPower` | PARM01 | 0.0 | power law :math:`n` in :math:`(\cos\varphi)^n` factor for horizontal (harmonic or biharmonic) |
1797 | | | | viscosity and tracer diffusivity (spherical polar) |
1798 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1799 | :varlink:`delR` | PARM04 | computed using delRc | vertical grid spacing 1D array ([:math:`r`] unit) |
1800 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1801 | :varlink:`delRc` | PARM04 | computed using delR | vertical cell center spacing 1D array ([:math:`r`] unit) |
1802 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1803 | :varlink:`delRFile` | PARM04 | :kbd:`' '` | filename for vertical grid spacing 1D array ([:math:`r`] unit) |
1804 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1805 | :varlink:`delRcFile` | PARM04 | :kbd:`' '` | filename for vertical cell center spacing 1D array ([:math:`r`] unit) |
1806 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1807 | :varlink:`rSphere` | PARM04 | 6.37E+06 | radius of sphere for spherical polar or curvilinear grid (m) |
1808 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1809 | :varlink:`seaLev_Z` | PARM04 | 0.0 | reference height of sea level (m) |
1810 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1811 | :varlink:`top_Pres` | PARM04 | 0.0 | top pressure (:math:`p`-coordinates) or top reference pressure (:math:`z`-coordinates) (Pa) |
1812 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1813 | :varlink:`selectFindRoSurf` | PARM01 | 0 | select method to determine surface reference pressure from orography (atmos.-only) |
1814 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1815 | :varlink:`horizGridFile` | PARM04 | :kbd:`' '` | filename containing full set of horizontal grid variables (curvilinear) |
1816 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1817 | :varlink:`radius_fromHorizGrid` | PARM04 | :varlink:`rSphere` | radius of sphere used in input curvilinear horizontal grid file (m) |
1818 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1819 | :varlink:`phiEuler` | PARM04 | 0.0 | Euler angle, rotation about original :math:`z`-axis (spherical polar) (degrees) |
1820 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1821 | :varlink:`thetaEuler` | PARM04 | 0.0 | Euler angle, rotation about new :math:`x`-axis (spherical polar) (degrees) |
1822 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1823 | :varlink:`psiEuler` | PARM04 | 0.0 | Euler angle, rotation about new :math:`z`-axis (spherical polar) (degrees) |
1824 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*1825
9c8516d9da Jeff*1826 .. _parms_topo:
1827
69e7157c80 Jeff*1828 Topography - Full and Partial Cells
dcaaa42497 Jeff*1829 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1830
ba0b047096 Mart*1831 For the ocean, the topography is read from a file that contains a
1832 2-D(:math:`x,y`) map of bathymetry, in meters for :math:`z`-coordinates, in
1833 pascals for :math:`p`-coordinates. The bathymetry is specified by entering the
1834 vertical position of the ocean floor relative to the surface, so by convention
1835 in :math:`z`-coordinates bathymetry is specified as negative numbers (âdepthâ
1836 is defined as positive-definite) whereas in :math:`p`-coordinates
dcaaa42497 Jeff*1837 bathymetry data is positive. The file name is represented by the variable
ba0b047096 Mart*1838 :varlink:`bathyFile`. See our introductory tutorial setup :numref:`sec_eg_baro`
1839 for additional details on the file format. Note no changes are required in the
1840 model source code to represent enclosed, periodic, or double periodic
dcaaa42497 Jeff*1841 domains: periodicity is assumed by default and is suppressed by
1842 setting the depths to 0 m for the cells at the limits of the
1843 computational domain.
1844
1845 To use the partial cell capability, the variable :varlink:`hFacMin` needs
1846 to be set to a value between 0.0 and 1.0 (it is set to 1.0 by default)
1847 corresponding to the minimum fractional size of a gridcell. For
1848 example, if a gridcell is 500 m thick and :varlink:`hFacMin` is set to
ba0b047096 Mart*1849 0.1, the minimum thickness for a âthin-cellâ for this specific gridcell is 50 m.
1850 Thus, if the specified bathymetry depth were to fall exactly
1851 in the middle of this 500m thick gridcell, the initial model variable
1852 :varlink:`hFacC`\ (:math:`x,y,r`) would be set to 0.5.
1853 If the specified bathymetry depth fell within the top 50m of this gridcell
1854 (i.e., less than :varlink:`hFacMin`), the model bathymetry would snap to the
1855 nearest legal value (i.e., initial :varlink:`hFacC`\ (:math:`x,y,r`) would be
1856 equal to 0.0 or 0.1 depending if the depth was within 0-25 m or 25-50 m,
1857 respectively). Also note while specified bathymetry bottom depths (or
1858 pressures) need not coincide with the model's levels as deduced from
1859 :varlink:`delR`, any depth falling below the model's defined vertical axis is
1860 truncated.
dcaaa42497 Jeff*1861
1862 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
1863
a332812c22 Jeff*1864 .. table::
1865 :class: longtable
de49ce6f4b Ed D*1866
a332812c22 Jeff*1867 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1868 | Parameter | Group | Default | Description |
1869 +========================================+===========+==================================================+=========================================================================================================+
1870 | :varlink:`bathyFile` | PARM05 | :kbd:`' '` | filename for 2D bathymetry (ocean) (:math:`z`-coor.: m, negative; :math:`p`-coor.: Pa, positive) |
1871 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1872 | :varlink:`topoFile` | PARM05 | :kbd:`' '` | filename for 2D surface topography (atmosphere) (m) |
1873 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1874 | :varlink:`addWwallFile` | PARM05 | :kbd:`' '` | filename for 2D western cell-edge âthin-wallâ |
1875 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1876 | :varlink:`addSwallFile` | PARM05 | :kbd:`' '` | filename for 2D southern cell-edge âthin-wallâ |
1877 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1878 | :varlink:`hFacMin` | PARM01 | 1.0E+00 | minimum fraction size of a cell |
1879 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1880 | :varlink:`hFacMinDr` | PARM01 | 1.0E+00 | minimum dimensional size of a cell ([:math:`r`] unit) |
1881 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1882 | :varlink:`hFacInf` | PARM01 | 2.0E-01 | lower threshold fraction for surface cell; |
1883 | | | | for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>` |
1884 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1885 | :varlink:`hFacSup` | PARM01 | 2.0E+00 | upper threshold fraction for surface cell; |
1886 | | | | for non-linear free surface, only see parameter :ref:`nonlinFreeSurf <free_surface_parms>` |
1887 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1888 | :varlink:`useMin4hFacEdges` | PARM04 | FALSE | set :varlink:`hFacW`, :varlink:`hFacS` as minimum of adjacent :varlink:`hFacC` on/off flag |
1889 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1890 | :varlink:`pCellMix_select` | PARM04 | 0 | option/factor to enhance mixing at the surface or bottom (0- 99) |
1891 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1892 | :varlink:`pCellMix_maxFac` | PARM04 | 1.0E+04 | maximum enhanced mixing factor for too thin partial-cell (non-dim.) |
1893 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1894 | :varlink:`pCellMix_delR` | PARM04 | 0.0 | thickness criteria for too thin partial-cell ([:math:`r`] unit) |
1895 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*1896
1897 Physical Constants
1898 ~~~~~~~~~~~~~~~~~~
1899
1900 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
1901
1902 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1903 | Parameter | Group | Default | Description |
1904 +========================================+===========+==================================================+=========================================================================================================+
1905 | :varlink:`rhoConst` | PARM01 | :varlink:`rhoNil` | vertically constant reference density (Boussinesq) (kg/m\ :sup:`3`) |
1906 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1907 | :varlink:`gravity` | PARM01 | 9.81E+00 | gravitational acceleration (m/s\ :sup:`2`) |
1908 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
516b08a580 jm-c 1909 | :varlink:`gravityFile` | PARM01 | :kbd:`' '` | filename for 1D gravity vertical profile (m/s\ :sup:`2`) |
dcaaa42497 Jeff*1910 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1911 | :varlink:`gBaro` | PARM01 | :varlink:`gravity` | gravity constant in barotropic equation (m/s\ :sup:`2`) |
1912 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1913
1914 Rotation
1915 ~~~~~~~~
1916
1917 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
1918
1919 For a Cartesian or cylindical grid, the Coriolis parameter :math:`f` is set
ba0b047096 Mart*1920 through the variables :varlink:`f0` (in s\ :sup:`--1`) and :varlink:`beta`
1921 (:math:`\frac{\partial f}{ \partial y}`; in m\ :sup:`--1`\ s\ :sup:`--1`),
1922 which corresponds to a Coriolis parameter :math:`f = f_o + \beta y`
1923 (the so-called :math:`\beta`\ -plane).
dcaaa42497 Jeff*1924
1925 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1926 | Parameter | Group | Default | Description |
1927 +========================================+===========+==================================================+=========================================================================================================+
1928 | :varlink:`rotationPeriod` | PARM01 | 8.6164E+04 | rotation period (s) |
1929 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1930 | :varlink:`omega` | PARM01 | :math:`2\pi/`\ :varlink:`rotationPeriod` | angular velocity (rad/s) |
1931 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*1932 | :varlink:`selectCoriMap` | PARM01 | depends on grid | Coriolis map options |
1933 | | | (Cartesian and cylindrical=1, | |
1934 | | | spherical and curvilinear=2) | - 0: f-plane |
1935 | | | | - 1: beta-plane |
1936 | | | | - 2: spherical Coriolis (:math:`=2\Omega\sin{\varphi}`) |
1937 | | | | - 3: read 2D field from file |
dcaaa42497 Jeff*1938 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*1939 | :varlink:`f0` | PARM01 | 1.0E-04 | reference Coriolis parameter (Cartesian or cylindrical grid) (1/s) |
dcaaa42497 Jeff*1940 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*1941 | :varlink:`beta` | PARM01 | 1.0E-11 | :math:`\beta` (Cartesian or cylindrical grid) (m\ :sup:`--1`\ s\ :sup:`--1`) |
dcaaa42497 Jeff*1942 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*1943 | :varlink:`fPrime` | PARM01 | 0.0 | :math:`2 \Omega \cos{\phi}` parameter (Cartesian or cylindical grid) (1/s); i.e., for |
dcaaa42497 Jeff*1944 | | | | :math:`\cos{\varphi}` Coriolis terms from horizontal component of rotation vector |
1945 | | | | (also sometimes referred to as reciprocal Coriolis parm.) |
1946 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1947
1948 .. _free_surface_parms:
1949
1950 Free Surface
1951 ~~~~~~~~~~~~
1952
ba0b047096 Mart*1953 The logical variables :varlink:`rigidLid` and :varlink:`implicitFreeSurface`
1954 specify your choice for ocean upper boundary (or lower boundary if using
1955 :math:`p`-coordinates); set one to ``.TRUE.`` and the other to ``.FALSE.``.
1956 These settings affect the calculations of surface pressure (for the ocean) or
dcaaa42497 Jeff*1957 surface geopotential (for the atmosphere); see :numref:`parms-main_algorithm`.
1958
1959 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}|
1960
a332812c22 Jeff*1961 .. table::
1962 :class: longtable
1963
1964 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1965 | Parameter | Group | Default | Description |
1966 +========================================+===========+==================================================+=========================================================================================================+
1967 | :varlink:`implicitFreeSurface` | PARM01 | TRUE | implicit free surface on/off flag |
1968 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1969 | :varlink:`rigidLid` | PARM01 | FALSE | rigid lid on/off flag |
1970 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1971 | :varlink:`useRealFreshWaterFlux` | PARM01 | FALSE | use true E-P-R freshwater flux (changes free surface/sea level) on/off flag |
1972 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1973 | :varlink:`implicSurfPress` | PARM01 | 1.0E+00 | implicit fraction of the surface pressure gradient (0-1) |
1974 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1975 | :varlink:`implicDiv2Dflow` | PARM01 | 1.0E+00 | implicit fraction of the barotropic flow divergence (0-1) |
1976 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1977 | :varlink:`implicitNHPress` | PARM01 | :varlink:`implicSurfPress` | implicit fraction of the non-hydrostatic pressure gradient (0-1); |
1978 | | | | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` |
1979 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1980 | :varlink:`nonlinFreeSurf` | PARM01 | 0 | non-linear free surface options (-1,0,1,2,3; see :numref:`nonlinFreeSurf-flags`); |
1981 | | | | requires #define :varlink:`NONLIN_FRSURF` |
1982 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1983 | :varlink:`select_rStar` | PARM01 | 0 | vertical coordinate option |
1984 | | | | |
1985 | | | | - 0: use r |
1986 | | | | - >0: use :math:`r^*` |
1987 | | | | |
1988 | | | | see :numref:`nonlinFreeSurf-flags`; requires #define :varlink:`NONLIN_FRSURF` |
1989 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1990 | :varlink:`selectNHfreeSurf` | PARM01 | 0 | non-hydrostatic free surface formulation option |
1991 | | | | |
1992 | | | | - 0: donât use |
1993 | | | | - >0: use |
1994 | | | | |
1995 | | | | requires non-hydrostatic formulation, see parameter :ref:`nonHydrostatic <model_config_parms>` |
1996 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
1997 | :varlink:`exactConserv` | PARM01 | FALSE | exact total volume conservation (recompute divergence after pressure solver) on/off flag |
1998 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*1999
69e7157c80 Jeff*2000 Time-Discretization
dcaaa42497 Jeff*2001 ~~~~~~~~~~~~~~~~~~~
2002
2003 The time steps are set through the real variables :varlink:`deltaTMom` and
2004 :varlink:`deltaTtracer` (in seconds) which represent the time step for the
ba0b047096 Mart*2005 momentum and tracer equations, respectively (or you can prescribe a single
2006 time step value for all parameters using :varlink:`deltaT`). The model âclockâ
2007 is defined by the variable :varlink:`deltaTClock` (in seconds)
dcaaa42497 Jeff*2008 which determines the I/O frequencies and is used in tagging output.
2009 Time in the model is thus computed as:
2010
ba0b047096 Mart*2011 | model time = :varlink:`baseTime` + iteration number * :varlink:`deltaTClock`
dcaaa42497 Jeff*2012
2013 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2014
2015 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2016 | Parameter | Group | Default | Description |
2017 +========================================+===========+==================================================+=========================================================================================================+
2018 | :varlink:`deltaT` | PARM03 | 0.0 | default value used for model time step parameters (s) |
2019 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2020 | :varlink:`deltaTClock` | PARM03 | :varlink:`deltaT` | timestep used for model clock (s): used for I/O frequency and tagging output and checkpoints |
2021 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2022 | :varlink:`deltaTmom` | PARM03 | :varlink:`deltaT` | momentum equation timestep (s) |
2023 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2024 | :varlink:`deltaTtracer` | PARM03 | :varlink:`deltaT` | tracer equation timestep (s) |
2025 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2026 | :varlink:`dTtracerLev` | PARM03 | :varlink:`deltaTtracer` | tracer equation timestep specified at each vertical level (s) |
2027 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2028 | :varlink:`deltaTfreesurf` | PARM03 | :varlink:`deltaTmom` | free-surface equation timestep (s) |
2029 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2030 | :varlink:`baseTime` | PARM03 | 0.0 | model base time corresponding to iteration 0 (s) |
2031 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2032
2033 .. _parms-main_algorithm:
2034
2035 Parameters: Main Algorithmic Parameters
2036 ---------------------------------------
2037
2038 Pressure Solver
2039 ~~~~~~~~~~~~~~~
2040
2041 By default, a hydrostatic
ba0b047096 Mart*2042 simulation is assumed and a 2-D elliptic equation is used to invert the
2043 pressure field. If using a non-hydrostatic configuration, the pressure field is
2044 inverted through a 3-D elliptic equation (note this capability is not yet
2045 available for the atmosphere). The parameters controlling the behavior of the
dcaaa42497 Jeff*2046 elliptic solvers are the variables :varlink:`cg2dMaxIters` and
83cdbd2346 Jeff*2047 :varlink:`cg2dTargetResidual` for the 2-D case and :varlink:`cg3dMaxIters` and
2048 :varlink:`cg3dTargetResidual` for the 3-D case.
dcaaa42497 Jeff*2049
2050 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
2051
a332812c22 Jeff*2052 .. table::
2053 :class: longtable
2054
2055 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2056 | Parameter | Group | Default | Description |
2057 +========================================+===========+==================================================+=========================================================================================================+
2058 | :varlink:`cg2dMaxIters` | PARM02 | 150 | upper limit on 2D conjugate gradient solver iterations |
2059 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2060 | :varlink:`cg2dTargetResidual` | PARM02 | 1.0E-07 | 2D conjugate gradient target residual (non-dim. due to RHS normalization ) |
2061 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2062 | :varlink:`cg2dTargetResWunit` | PARM02 | -1.0E+00 | 2D conjugate gradient target residual (:math:`\dot{r}` units); |
2063 | | | | <0: use RHS normalization, i.e., :varlink:`cg2dTargetResidual` instead |
2064 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2065 | :varlink:`cg2dPreCondFreq` | PARM02 | 1 | frequency (in number of iterations) for updating cg2d pre-conditioner; |
2066 | | | | for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>` |
2067 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2068 | :varlink:`cg2dUseMinResSol` | PARM02 | 0 unless flat-bottom, Cartesian | - 0: use last-iteration/converged cg2d solution |
2069 | | | | - 1: use solver minimum-residual solution |
2070 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2071 | :varlink:`cg3dMaxIters` | PARM02 | 150 | upper limit on 3D conjugate gradient solver iterations; requires #define :varlink:`ALLOW_NONHYDROSTATIC`|
2072 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2073 | :varlink:`cg3dTargetResidual` | PARM02 | 1.0E-07 | 3D conjugate gradient target residual (non-dim. due to RHS normalization ); |
2074 | | | | requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
2075 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e6e223b277 Jean*2076 | :varlink:`cg3dTargetResWunit` | PARM02 | -1.0E+00 | 3D conjugate gradient target residual (:math:`\dot{r}` units); |
2077 | | | | <0: use RHS normalization, i.e., :varlink:`cg3dTargetResidual` instead |
2078 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*2079 | :varlink:`useSRCGSolver` | PARM02 | FALSE | use conjugate gradient solver with single reduction (single call of mpi_allreduce) |
2080 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2081 | :varlink:`printResidualFreq` | PARM02 | 1 unless :varlink:`debugLevel` >4 | frequency (in number of iterations) of printing conjugate gradient residual |
2082 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2083 | :varlink:`integr_GeoPot` | PARM01 | 2 | select method to integrate geopotential |
2084 | | | | |
2085 | | | | - 1: finite volume |
2086 | | | | - :math:`\neq`\ 1: finite difference |
2087 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2088 | :varlink:`uniformLin_PhiSurf` | PARM01 | TRUE | use uniform :math:`b_s` relation for :math:`\phi_s` on/off flag |
2089 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2090 | :varlink:`deepAtmosphere` | PARM04 | FALSE | donât make the thin shell/shallow water approximation |
2091 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2092 | :varlink:`nh_Am2` | PARM01 | 1.0E+00 | non-hydrostatic terms scaling factor; requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
2093 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*2094
2095 Time-Stepping Algorithm
2096 ~~~~~~~~~~~~~~~~~~~~~~~
2097
2098 The Adams-Bashforth stabilizing parameter is set through the
2099 variable :varlink:`abEps` (dimensionless). The stagger baroclinic time
2100 stepping algorithm can be activated by setting the logical variable
2101 :varlink:`staggerTimeStep` to ``.TRUE.``.
2102
2103 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2104
2105 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2106 | Parameter | Group | Default | Description |
2107 +========================================+===========+==================================================+=========================================================================================================+
2108 | :varlink:`abEps` | PARM03 | 1.0E-02 | Adams-Bashforth-2 stabilizing weight (non-dim.) |
2109 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2110 | :varlink:`alph_AB` | PARM03 | 0.5E+00 | Adams-Bashforth-3 primary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` |
2111 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2112 | :varlink:`beta_AB` | PARM03 | 5/12 | Adams-Bashforth-3 secondary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` |
2113 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2114 | :varlink:`staggerTimeStep` | PARM01 | FALSE | use staggered time stepping (thermodynamic vs. flow variables) on/off flag |
2115 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2116 | :varlink:`multiDimAdvection` | PARM01 | TRUE | use multi-dim. advection algorithm in schemes where non multi-dim. is possible on/off flag |
2117 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2118 | :varlink:`implicitIntGravWave` | PARM01 | FALSE | treat internal gravity waves implicitly on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
2119 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2120
69e7157c80 Jeff*2121 .. _parms-eos:
2122
2123 Parameters: Equation of State
2124 -----------------------------
2125
dcaaa42497 Jeff*2126 The form of the equation of state is controlled by the model configuration
516b08a580 jm-c 2127 and :varlink:`eosType`.
dcaaa42497 Jeff*2128
516b08a580 jm-c 2129 For the atmosphere, :varlink:`eosType` must be set to ``IDEALGAS``.
dcaaa42497 Jeff*2130
2131 For the ocean, several forms of the equation of state are
2132 available:
2133
2134 - For a linear approximation, set :varlink:`eosType` to ``LINEAR``),
2135 and you will need to specify the thermal
2136 and haline expansion coefficients, represented by the variables
ba0b047096 Mart*2137 :varlink:`tAlpha` (in K\ :sup:`--1`) and :varlink:`sBeta`
2138 (in (g/kg)\ :sup:`--1`).
dcaaa42497 Jeff*2139 Because the model equations are written in terms of
2140 perturbations, a reference thermodynamic state needs to be specified.
ba0b047096 Mart*2141 This is done through the 1-D arrays :varlink:`tRef` and :varlink:`sRef`.
2142 :varlink:`tRef` specifies the reference potential temperature profile (in
2143 :sup:`o`\ C for the ocean and K for the atmosphere) starting
2144 from the level k=1. Similarly, :varlink:`sRef` specifies the reference
2145 salinity profile (in g/kg) for the ocean or the reference specific
dcaaa42497 Jeff*2146 humidity profile (in g/kg) for the atmosphere.
2147
2148 - MITgcm offers several approximations to the full (oceanic) non-linear equation
2149 of state that can be selected as :varlink:`eosType`:
2150
516b08a580 jm-c 2151 ``'POLYNOMIAL'``:
ba0b047096 Mart*2152 This approximation is based on the Knudsen formula (see Bryan and Cox 1972
2153 :cite:`bryan:72`). For this option you need to generate a file of polynomial
dcaaa42497 Jeff*2154 coefficients called ``POLY3.COEFFS``. To do this, use the program
ba0b047096 Mart*2155 :filelink:`utils/knudsen2/knudsen2.f` under the model tree (a ``Makefile``
2156 is available in the same directory; you will need to edit the number and
2157 the values of the vertical levels in
2158 :filelink:`knudsen2.f <utils/knudsen2/knudsen2.f>`
dcaaa42497 Jeff*2159 so that they match those of your configuration).
2160
2161 ``âUNESCOâ``:
2162 The UNESCO equation of state formula (IES80) of Fofonoff and Millard (1983)
69e7157c80 Jeff*2163 :cite:`fofonoff:83`. This equation of state assumes
dcaaa42497 Jeff*2164 in-situ temperature, which is not a model variable; **its use is
2165 therefore discouraged**.
69e7157c80 Jeff*2166
dcaaa42497 Jeff*2167 ``âJMD95Zâ``:
69e7157c80 Jeff*2168 A modified UNESCO formula by Jackett and McDougall (1995)
2169 :cite:`jackett:95`, which uses the model variable
2170 potential temperature as input. The âZâ indicates that this
2171 equation of state uses a horizontally and temporally constant
2172 pressure :math:`p_{0}=-g\rho_{0}z`.
2173
dcaaa42497 Jeff*2174 ``âJMD95Pâ``:
69e7157c80 Jeff*2175 A modified UNESCO formula by Jackett and McDougall (1995)
2176 :cite:`jackett:95`, which uses the model variable
2177 potential temperature as input. The âPâ indicates that this
2178 equation of state uses the actual hydrostatic pressure of the last
2179 time step. Lagging the pressure in this way requires an additional
2180 pickup file for restarts.
2181
dcaaa42497 Jeff*2182 ``âMDJWFâ``:
2183 A more accurate and less expensive equation of state than UNESCO by
2184 McDougall et al. (2003) :cite:`mcdougall:03`, also using the model variable
2185 potential temperature as input. It also requires
69e7157c80 Jeff*2186 lagging the pressure and therefore an additional pickup file for
2187 restarts.
2188
dcaaa42497 Jeff*2189 ``âTEOS10â``:
ba0b047096 Mart*2190 TEOS-10 is based on a Gibbs function formulation from which all
2191 thermodynamic properties of seawater (density, enthalpy, entropy sound
2192 speed, etc.) can be derived in a thermodynamically consistent manner;
2193 see http://www.teos-10.org. See IOC et al. (2010) :cite:`ioc:10`, McDougall
2194 and Parker (2011) :cite:`mcdougall:11`, and Roquet et al. (2015)
2195 :cite:`roquet:15` for implementation details.
2196 It also requires lagging the pressure and therefore an additional pickup
2197 file for restarts. Note at this time a full implementation of TEOS10 (i.e.,
2198 ocean variables of conservative temperature and practical salinity,
dcaaa42497 Jeff*2199 including consideration of surface forcings) has not been implemented;
ba0b047096 Mart*2200 also note the original 48-term polynomial term is used, not the newer,
2201 preferred 75-term polynomial.
2202
2203 For these non-linear approximations, neither a reference profile of
2204 temperature or salinity is required, except for a setup where
2205 :varlink:`implicitIntGravWave` is set to ``.TRUE.`` or
2206 :varlink:`selectP_inEOS_Zc`\ =1.
2207
2208 Note that for simplicity, salinity is expressed as a ratio in g/kg (thus
2209 effectively unitless) regardless of the choice of equation of state,
2210 despite "Practical Salinity" not precisely equal to salinity expressed as a
2211 dissolved mass fraction. If TEOS-10 is selected, the model variable
2212 :varlink:`salt` can be interpreted as "Absolute Salinity". See Millero (2010)
2213 :cite:`millero:10` and Pawlowicz (2013) :cite:`pawlowicz:13` for detailed
2214 discussion of salinity measurements, and why being expressed
2215 as g/kg is preferred, in the context of the ocean equation of state.
dcaaa42497 Jeff*2216
2217 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
2218
a332812c22 Jeff*2219 .. table::
2220 :class: longtable
2221
2222 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2223 | Parameter | Group | Default | Description |
2224 +========================================+===========+==================================================+=========================================================================================================+
2225 | :varlink:`eosType` | PARM01 | LINEAR | equation of state form |
2226 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2227 | :varlink:`tRef` | PARM01 | 20.0 :sup:`o`\ C (ocn) or 300.0 K (atm) | 1D vertical reference temperature profile (:sup:`o`\ C or K) |
2228 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2229 | :varlink:`tRefFile` | PARM01 | :kbd:`' '` | filename for reference temperature profile (:sup:`o`\ C or K) |
2230 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2231 | :varlink:`thetaConst` | PARM01 | :varlink:`tRef`\ (k=1) | vertically constant reference temp. for atmosphere :math:`p^*` coordinates (:sup:`o`\ K); |
2232 | | | | for ocean, specify instead of :varlink:`tRef` or :varlink:`tRefFile` |
2233 | | | | for vertically constant reference temp. (:sup:`o`\ C ) |
2234 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2235 | :varlink:`sRef` | PARM01 | 30.0 (g/kg) (ocn) or 0.0 (atm) | 1D vertical reference salinity profile (g/kg) |
a332812c22 Jeff*2236 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2237 | :varlink:`sRefFile` | PARM01 | :kbd:`' '` | filename for reference salinity profile (g/kg) |
a332812c22 Jeff*2238 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2239 | :varlink:`selectP_inEOS_Zc` | PARM01 | depends on :varlink:`eosType` | select which pressure to use in EOS for :math:`z`-coor. |
2240 | | | | |
2241 | | | | - 0: use :math:`-g \rho_c z` |
2242 | | | | - 1: use :math:`p_{ref} = -\int{-g\rho(T_{ref},S_{ref},p_{ref})dz}` |
2243 | | | | - 2: hydrostatic dynamical pressure |
2244 | | | | - 3: use full hyd.+non-hyd. pressure |
2245 | | | | |
2246 | | | | for ``JMD95P``, ``UNESCO``, ``MDJWF``, ``TEOS10`` default=2, otherwise default =0 |
2247 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2248 | :varlink:`rhonil` | PARM01 | 9.998E+02 | reference density for linear EOS (kg/m\ :sup:`3`) |
2249 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2250 | :varlink:`tAlpha` | PARM01 | 2.0E-04 | linear EOS thermal expansion coefficient (1/\ :sup:`o`\ C) |
2251 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2252 | :varlink:`sBeta` | PARM01 | 7.4E-04 | linear EOS haline contraction coefficient ((g/kg)\ :sup:`-1`) |
a332812c22 Jeff*2253 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*2254
2255 Thermodynamic Constants
2256 ~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff*2257
dcaaa42497 Jeff*2258 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.175}|\Y{.55}|
69e7157c80 Jeff*2259
dcaaa42497 Jeff*2260 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2261 | Parameter | Group | Default | Description |
2262 +========================================+===========+==================================================+=========================================================================================================+
2263 | :varlink:`HeatCapacity_Cp` | PARM01 | 3.994E+03 | specific heat capacity C\ :sub:`p` (ocean) (J/kg/K) |
2264 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2265 | :varlink:`celsius2K` | PARM01 | 2.7315E+02 | conversion constant :sup:`o`\ C to Kelvin |
2266 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2267 | :varlink:`atm_Cp` | PARM01 | 1.004E+03 | specific heat capacity C\ :sub:`p` dry air at const. press. (J/kg/K) |
2268 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2269 | :varlink:`atm_Rd` | PARM01 | :varlink:`atm_Cp`\*(2/7) | gas constant for dry air (J/kg/K) |
2270 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2271 | :varlink:`atm_Rq` | PARM01 | 0.0 | water vapor specific volume anomaly relative to dry air (g/kg) |
2272 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2273 | :varlink:`atm_Po` | PARM01 | 1.0E+05 | atmosphere standard reference pressure (for potential temp. defn.) (Pa) |
2274 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
69e7157c80 Jeff*2275
9c8516d9da Jeff*2276 .. _parms_mom:
2277
dcaaa42497 Jeff*2278 Parameters: Momentum Equations
2279 ------------------------------
69e7157c80 Jeff*2280
dcaaa42497 Jeff*2281 Configuration
2282 ~~~~~~~~~~~~~
69e7157c80 Jeff*2283
dcaaa42497 Jeff*2284 There are a few logical variables that allow you to turn on/off various
2285 terms in the momentum equation. These variables are called
2286 :varlink:`momViscosity`, :varlink:`momAdvection`, :varlink:`useCoriolis`,
ba0b047096 Mart*2287 :varlink:`momStepping`, :varlink:`metricTerms`, and
2288 :varlink:`momPressureForcing` and by default are set to ``.TRUE.``.
2289 Vertical diffusive fluxes of momentum can be computed implicitly
dcaaa42497 Jeff*2290 by setting the logical variable :varlink:`implicitViscosity` to
ba0b047096 Mart*2291 ``.TRUE.``. The details relevant to both the momentum flux-form and the
2292 vector-invariant form of the equations and the various (momentum) advection
2293 schemes are covered in :numref:`discret_algorithm`.
dcaaa42497 Jeff*2294
2295 .. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}|
2296
a332812c22 Jeff*2297 .. table::
2298 :class: longtable
2299
2300 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2301 | Parameter | Group | Default | Description |
2302 +========================================+===========+==================================================+=========================================================================================================+
2303 | :varlink:`momStepping` | PARM01 | TRUE | momentum equation time-stepping on/off flag |
2304 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2305 | :varlink:`momViscosity` | PARM01 | TRUE | momentum friction terms on/off flag |
2306 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2307 | :varlink:`momAdvection` | PARM01 | TRUE | advection of momentum on/off flag |
2308 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2309 | :varlink:`momPressureForcing` | PARM01 | TRUE | pressure term in momentum equation on/off flag |
2310 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2311 | :varlink:`metricTerms` | PARM01 | TRUE | include metric terms (spherical polar, momentum flux-form) on/off flag |
2312 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2313 | :varlink:`useNHMTerms` | PARM01 | FALSE | use "non-hydrostatic form" of metric terms on/off flag; (see :numref:`non_hyd_metric_terms`; |
2314 | | | | note these terms are non-zero in many model configurations beside non-hydrostatic) |
2315 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2316 | :varlink:`momImplVertAdv` | PARM01 | FALSE | momentum implicit vertical advection on/off flag; requires #define :varlink:`INCLUDE_IMPLVERTADV_CODE` |
2317 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2318 | :varlink:`implicitViscosity` | PARM01 | FALSE | implicit vertical viscosity on/off flag |
2319 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2320 | :varlink:`interViscAr_pCell` | PARM04 | FALSE | account for partial-cell in interior vertical viscosity on/off flag |
2321 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2322 | :varlink:`momDissip_In_AB` | PARM03 | TRUE | use Adams-Bashforth time stepping for dissipation tendency |
2323 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2324 | :varlink:`useCoriolis` | PARM01 | TRUE | include Coriolis terms on/off flag |
2325 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2326 | :varlink:`use3dCoriolis` | PARM01 | TRUE | include :math:`\cos{\varphi}` Coriolis terms on/off flag |
2327 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
7843dde2de jm-c 2328 | :varlink:`selectCoriScheme` | PARM01 | 0 | Coriolis scheme selector |
2329 | | | | |
2330 | | | | - 0: original scheme |
2331 | | | | - 1: wet-point averaging method |
2332 | | | | - 2: Flux-Form: energy conserving; Vector-Inv: hFac weighted average |
2333 | | | | - 3: Flux-Form: energy conserving using wet-point method; Vector-Inv: energy conserving with hFac weight|
a332812c22 Jeff*2334 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2335 | :varlink:`vectorInvariantMomentum` | PARM01 | FALSE | use vector-invariant form of momentum equations flag |
2336 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2337 | :varlink:`useJamartMomAdv` | PARM01 | FALSE | use Jamart wetpoints method for relative vorticity advection (vector invariant form) on/off flag |
2338 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2339 | :varlink:`selectVortScheme` | PARM01 | 1 | vorticity scheme (vector invariant form) options |
2340 | | | | |
2341 | | | | - 0,1: enstrophy conserving forms |
2342 | | | | - 2: energy conserving form |
2343 | | | | - 3: energy and enstrophy conserving form |
2344 | | | | |
2345 | | | | see Sadourny 1975 :cite:`sadourny:75` and Burridge & Haseler 1977 :cite:`burridge:77` |
2346 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2347 | :varlink:`upwindVorticity` | PARM01 | FALSE | bias interpolation of vorticity in the Coriolis term (vector invariant form) on/off flag |
2348 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2349 | :varlink:`useAbsVorticity` | PARM01 | FALSE | use :math:`f + \zeta` in Coriolis terms (vector invariant form) on/off flag |
2350 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2351 | :varlink:`highOrderVorticity` | PARM01 | FALSE | use 3rd/4th order interpolation of vorticity (vector invariant form) on/off flag |
2352 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2353 | :varlink:`upwindShear` | PARM01 | FALSE | use 1st order upwind for vertical advection (vector invariant form) on/off flag |
2354 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2355 | :varlink:`selectKEscheme` | PARM01 | 0 | kinetic energy computation in Bernoulli function (vector invariant form) options |
2356 | | | | |
2357 | | | | - 0: standard form |
2358 | | | | - 1: area-weighted standard form |
2359 | | | | - 2: as 0 but account for partial cells |
2360 | | | | - 3: as 1 w/partial cells |
2361 | | | | |
2362 | | | | see :filelink:`mom_calc_ke.F <pkg/mom_common/mom_calc_ke.F>` |
2363 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
69e7157c80 Jeff*2364
dcaaa42497 Jeff*2365 Initialization
2366 ~~~~~~~~~~~~~~
2367
2368 The initial horizontal velocity components can be specified from
2369 binary files :varlink:`uVelInitFile` and :varlink:`vVelInitFile`. These files
83cdbd2346 Jeff*2370 should contain 3-D data ordered in an (:math:`x,y,r`) fashion with k=1 as the
dcaaa42497 Jeff*2371 first vertical level (surface level). If no file names are provided,
2372 the velocity is initialized to zero. The initial vertical velocity
2373 is always derived from the horizontal velocity using the continuity
2374 equation. In the case of a restart (from the end of a previous simulation),
ba0b047096 Mart*2375 the velocity field is read from a pickup file
2376 (see :numref:`simulation_controls`) and the initial velocity files are ignored.
dcaaa42497 Jeff*2377
2378 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2379
2380 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2381 | Parameter | Group | Default | Description |
2382 +========================================+===========+==================================================+=========================================================================================================+
2383 | :varlink:`uVelInitFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial zonal velocity field (m/s) |
2384 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2385 | :varlink:`vVelInitFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial meridional velocity field (m/s) |
2386 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2387 | :varlink:`pSurfInitFile` | PARM05 | :kbd:`' '` | filename for 2D specification of initial free surface position ([:math:`r`] unit) |
2388 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2389
69e7157c80 Jeff*2390 .. _mom_dissip:
2391
dcaaa42497 Jeff*2392 General Dissipation Scheme
2393 ~~~~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff*2394
dcaaa42497 Jeff*2395 The lateral eddy viscosity coefficient is specified through the
2396 variable :varlink:`viscAh` (in m\ :sup:`2`\ s\ :sup:`--1`). The
2397 vertical eddy viscosity coefficient is specified through the
2398 variable :varlink:`viscAr` (in [:math:`r`]\ :sup:`2`\ s\ :sup:`--1`,
2399 where [:math:`r`] is the dimension of the vertical coordinate).
2400 In addition, biharmonic mixing can be added as well
2401 through the variable :varlink:`viscA4` (in
516b08a580 jm-c 2402 m\ :sup:`4`\ s\ :sup:`--1`).
dcaaa42497 Jeff*2403
2404 .. tabularcolumns:: |\Y{.215}|\Y{.1}|\Y{.115}|\Y{.595}|
2405
a332812c22 Jeff*2406 .. table::
2407 :class: longtable
2408
2409 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2410 | Parameter | Group | Default | Description |
2411 +========================================+===========+==================================================+=========================================================================================================+
2412 | :varlink:`viscAh` | PARM01 | 0.0 | lateral eddy viscosity (m\ :sup:`2`\ /s) |
2413 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2414 | :varlink:`viscAhD` | PARM01 | :varlink:`viscAh` | lateral eddy viscosity acts on divergence part (m\ :sup:`2`\ /s) |
2415 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2416 | :varlink:`viscAhZ` | PARM01 | :varlink:`viscAh` | lateral eddy viscosity acts on vorticity part (:math:`\zeta` points) (m\ :sup:`2`\ /s) |
2417 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2418 | :varlink:`viscAhW` | PARM01 | :varlink:`viscAhD` | lateral eddy viscosity for mixing vertical momentum (non-hydrostatic form) (m\ :sup:`2`\ /s); |
2419 | | | | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` |
2420 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2421 | :varlink:`viscAhDfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral eddy viscosity (divergence part) (m\ :sup:`2`\ /s); |
2422 | | | | requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
2423 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2424 | :varlink:`viscAhZfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral eddy viscosity (vorticity part, :math:`\zeta` points); |
2425 | | | | requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
2426 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2427 | :varlink:`viscAhGrid` | PARM01 | 0.0 | grid-dependent lateral eddy viscosity (non-dim.) |
2428 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2429 | :varlink:`viscAhMax` | PARM01 | 1.0E+21 | maximum lateral eddy viscosity (m\ :sup:`2`\ /s) |
2430 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2431 | :varlink:`viscAhGridMax` | PARM01 | 1.0E+21 | maximum lateral eddy (grid-dependent) viscosity (non-dim.) |
2432 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2433 | :varlink:`viscAhGridMin` | PARM01 | 0.0 | minimum lateral eddy (grid-dependent) viscosity (non-dim.) |
2434 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2435 | :varlink:`viscAhReMax` | PARM01 | 0.0 | minimum lateral eddy viscosity based on Reynolds number (non-dim.) |
2436 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2437 | :varlink:`viscC2leith` | PARM01 | 0.0 | Leith harmonic viscosity factor (vorticity part, :math:`\zeta` points) (non-dim.) |
2438 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2439 | :varlink:`viscC2leithD` | PARM01 | 0.0 | Leith harmonic viscosity factor (divergence part) (non-dim.) |
2440 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
f59d76b0dd Ed D*2441 | :varlink:`viscC2LeithQG` | PARM01 | 0.0 | Quasi-geostrophic Leith viscosity factor (non-dim.) |
2442 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*2443 | :varlink:`viscC2smag` | PARM01 | 0.0 | Smagorinsky harmonic viscosity factor (non-dim.) |
2444 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2445 | :varlink:`viscA4` | PARM01 | 0.0 | lateral biharmonic viscosity (m\ :sup:`4`\ /s) |
2446 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2447 | :varlink:`viscA4D` | PARM01 | :varlink:`viscA4` | lateral biharmonic viscosity (divergence part) (m\ :sup:`4`\ /s) |
2448 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2449 | :varlink:`viscA4Z` | PARM01 | :varlink:`viscA4` | lateral biharmonic viscosity (vorticity part, :math:`\zeta` points) (m\ :sup:`4`\ /s) |
2450 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2451 | :varlink:`viscA4W` | PARM01 | :varlink:`viscA4D` | lateral biharmonic viscosity for mixing vertical momentum (non-hydrostatic form) (m\ :sup:`4`\ /s); |
2452 | | | | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` |
2453 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2454 | :varlink:`viscA4Dfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral biharmonic viscosity (divergence part) (m\ :sup:`4`\ /s); |
2455 | | | | requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
2456 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2457 | :varlink:`viscA4Zfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral biharmonic viscosity (vorticity part, :math:`\zeta` points); |
2458 | | | | requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
2459 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2460 | :varlink:`viscA4Grid` | PARM01 | 0.0 | grid dependent biharmonic viscosity (non-dim.) |
2461 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2462 | :varlink:`viscA4Max` | PARM01 | 1.0E+21 | maximum biharmonic viscosity (m\ :sup:`4`\ /s) |
2463 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2464 | :varlink:`viscA4GridMax` | PARM01 | 1.0E+21 | maximum biharmonic (grid-dependent) viscosity (non-dim.) |
2465 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2466 | :varlink:`viscA4GridMin` | PARM01 | 0.0 | minimum biharmonic (grid-dependent) viscosity (mon-dim.) |
2467 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2468 | :varlink:`viscA4ReMax` | PARM01 | 0.0 | minimum biharmonic viscosity based on Reynolds number (non-dim.) |
2469 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2470 | :varlink:`viscC4leith` | PARM01 | 0.0 | Leith biharmonic viscosity factor (vorticity part, :math:`\zeta` points) (non-dim.) |
2471 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2472 | :varlink:`viscC4leithD` | PARM01 | 0.0 | Leith biharmonic viscosity factor (divergence part) (non-dim.) |
2473 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2474 | :varlink:`viscC4smag` | PARM01 | 0.0 | Smagorinsky biharmonic viscosity factor (non-dim.) |
2475 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2476 | :varlink:`useFullLeith` | PARM01 | FALSE | use full form of Leith viscosities on/off flag |
2477 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2478 | :varlink:`useSmag3D` | PARM01 | FALSE | use isotropic 3D Smagorinsky harmonic viscosities flag; requires #define :varlink:`ALLOW_SMAG_3D` |
2479 | | | | in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
2480 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2481 | :varlink:`smag3D_coeff` | PARM01 | 1.0E-02 | isotropic 3D Smagorinsky coefficient (non-dim.); requires #define :varlink:`ALLOW_SMAG_3D` |
2482 | | | | in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
2483 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2484 | :varlink:`useStrainTensionVisc` | PARM01 | FALSE | flag to use strain-tension form of viscous operator |
2485 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2486 | :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` |
2487 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2488 | :varlink:`viscAr` | PARM01 | 0.0 | vertical eddy viscosity ([:math:`r`]\ :sup:`2`\ /s) |
2489 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2490 | :varlink:`viscArNr` | PARM01 | 0.0 | vertical profile of vertical eddy viscosity ([:math:`r`]\ :sup:`2`\ /s) |
2491 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2492 | :varlink:`pCellMix_viscAr` | PARM04 | :varlink:`viscArNr` | vertical viscosity for too thin partial-cell ([:math:`r`]\ :sup:`2`\ /s) |
2493 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*2494
2495 Sidewall/Bottom Dissipation
2496 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2497
2498 Slip or no-slip conditions at lateral and bottom
2499 boundaries are specified through the logical variables
2500 :varlink:`no_slip_sides` and :varlink:`no_slip_bottom`. If set to
2501 ``.FALSE.``, free-slip boundary conditions are applied. If no-slip
2502 boundary conditions are applied at the bottom, a bottom drag can be
2503 applied as well. Two forms are available: linear (set the variable
2504 :varlink:`bottomDragLinear` in [:math:`r`]/s, )
2505 and quadratic (set the variable
2506 :varlink:`bottomDragQuadratic`, [:math:`r`]/m).
2507
2508 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2509
2510 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2511 | Parameter | Group | Default | Description |
2512 +========================================+===========+==================================================+=========================================================================================================+
2513 | :varlink:`no_slip_sides` | PARM01 | TRUE | viscous BCs: no-slip sides on/off flag |
2514 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff*2515 | :varlink:`sideDragFactor` | PARM01 | 2.0E+00 | side-drag scaling factor (2.0: full drag) (non-dim.) |
dcaaa42497 Jeff*2516 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2517 | :varlink:`no_slip_bottom` | PARM01 | TRUE | viscous BCs: no-slip bottom on/off flag |
2518 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2519 | :varlink:`bottomDragLinear` | PARM01 | 0.0 | linear bottom-drag coefficient ([:math:`r`]/s) |
2520 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2521 | :varlink:`bottomDragQuadratic` | PARM01 | 0.0 | quadratic bottom-drag coefficient ([:math:`r`]/m) |
2522 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ab47de63dc Mart*2523 | :varlink:`zRoughBot` | PARM01 | 0.0 | roughness length for quadratic bottom friction coefficient (m) |
2524 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*2525 | :varlink:`selectBotDragQuadr` | PARM01 | -1 | select quadratic bottom drag discretization option |
2526 | | | | |
2527 | | | | - -1: not used |
2528 | | | | - 0: average KE from grid center to :math:`u,v` location |
2529 | | | | - 1: use local velocity norm @ :math:`u,v` location |
2530 | | | | - 2: as 1 with wet-point averaging of other velocity component |
2531 | | | | |
dcaaa42497 Jeff*2532 | | | | if :varlink:`bottomDragQuadratic` :math:`\neq 0.` then default is 0 |
2533 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*2534 | :varlink:`selectImplicitDrag` | PARM01 | 0 | top/bottom drag implicit treatment options |
2535 | | | | |
2536 | | | | - 0: fully explicit |
2537 | | | | - 1: implicit on provisional velocity, i.e., before :math:`\nabla \eta` increment |
2538 | | | | - 2: fully implicit |
2539 | | | | |
dcaaa42497 Jeff*2540 | | | | if =2, requires #define :varlink:`ALLOW_SOLVE4_PS_AND_DRAG` |
2541 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2542 | :varlink:`bottomVisc_pCell` | PARM01 | FALSE | account for partial-cell in bottom viscosity (using :varlink:`no_slip_bottom` = ``.TRUE.``) on/off flag |
2543 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2544
69e7157c80 Jeff*2545 Parameters: Tracer Equations
2546 ----------------------------
2547
dcaaa42497 Jeff*2548 This section covers the tracer equations, i.e., the potential temperature
69e7157c80 Jeff*2549 equation and the salinity (for the ocean) or specific humidity (for the
516b08a580 jm-c 2550 atmosphere) equation.
dcaaa42497 Jeff*2551
2552 Configuration
2553 ~~~~~~~~~~~~~
2554
2555 The logical variables :varlink:`tempAdvection`, and
69e7157c80 Jeff*2556 :varlink:`tempStepping` allow you to turn on/off terms in the temperature
dcaaa42497 Jeff*2557 equation (similarly for salinity or specific humidity with variables
2558 :varlink:`saltAdvection` etc.). These variables all
2559 default to a value of ``.TRUE.``. The vertical diffusive
2560 fluxes can be computed implicitly by setting the logical variable
516b08a580 jm-c 2561 :varlink:`implicitDiffusion` to ``.TRUE.``.
dcaaa42497 Jeff*2562
2563 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}|
2564
a332812c22 Jeff*2565 .. table::
2566 :class: longtable
2567
2568 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2569 | Parameter | Group | Default | Description |
2570 +========================================+===========+==================================================+=========================================================================================================+
2571 | :varlink:`tempStepping` | PARM01 | TRUE | temperature equation time-stepping on/off flag |
2572 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2573 | :varlink:`tempAdvection` | PARM01 | TRUE | advection of temperature on/off flag |
2574 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2575 | :varlink:`tempAdvScheme` | PARM01 | 2 | temperature horizontal advection scheme selector (see :numref:`adv_scheme_summary`) |
2576 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2577 | :varlink:`tempVertAdvScheme` | PARM01 | :varlink:`tempAdvScheme` | temperature vertical advection scheme selector (see :numref:`adv_scheme_summary`) |
2578 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2579 | :varlink:`tempImplVertAdv` | PARM01 | FALSE | temperature implicit vertical advection on/off flag |
2580 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2581 | :varlink:`addFrictionHeating` | PARM01 | FALSE | include frictional heating in temperature equation on/off flag; |
2582 | | | | requires #define :varlink:`ALLOW_FRICTION_HEATING` |
2583 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2584 | :varlink:`temp_stayPositive` | PARM01 | FALSE | use Smolarkiewicz hack to ensure temperature stays positive on/off flag; |
2585 | | | | requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h` |
2586 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2587 | :varlink:`saltStepping` | PARM01 | TRUE | salinity equation time-stepping on/off flag |
2588 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2589 | :varlink:`saltAdvection` | PARM01 | TRUE | advection of salinity on/off flag |
2590 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2591 | :varlink:`saltAdvScheme` | PARM01 | 2 | salinity horizontal advection scheme selector (see :numref:`adv_scheme_summary`) |
2592 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2593 | :varlink:`saltVertAdvScheme` | PARM01 | :varlink:`saltAdvScheme` | salinity vertical advection scheme selector (see :numref:`adv_scheme_summary`) |
2594 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2595 | :varlink:`saltImplVertAdv` | PARM01 | FALSE | salinity implicit vertical advection on/off flag |
2596 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2597 | :varlink:`salt_stayPositive` | PARM01 | FALSE | use Smolarkiewicz hack to ensure salinity stays positive on/off flag; |
2598 | | | | requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h` |
2599 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2600 | :varlink:`implicitDiffusion` | PARM01 | FALSE | implicit vertical diffusion on/off flag |
2601 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2602 | :varlink:`interDiffKr_pCell` | PARM04 | FALSE | account for partial-cell in interior vertical diffusion on/off flag |
2603 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
837f8d0bd9 Dhru*2604 | :varlink:`linFSConserveTr` | PARM01 | FALSE | correct source/sink of tracer due to use of linear free surface on/off flag |
a332812c22 Jeff*2605 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2606 | :varlink:`doAB_onGtGs` | PARM03 | TRUE | apply Adams-Bashforth on tendencies (rather than on T,S) on/off flag |
2607 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*2608
69e7157c80 Jeff*2609 Initialization
dcaaa42497 Jeff*2610 ~~~~~~~~~~~~~~
2611
2612 The initial tracer data can be contained in the binary files
2613 :varlink:`hydrogThetaFile` and :varlink:`hydrogSaltFile`. These files should
83cdbd2346 Jeff*2614 contain 3-D data ordered in an (:math:`x,y,r`) fashion with k=1 as the first
dcaaa42497 Jeff*2615 vertical level. If no file names are provided, the tracers are then
ba0b047096 Mart*2616 initialized with the values of :varlink:`tRef` and :varlink:`sRef` discussed in
2617 :numref:`parms-eos`. In this case, the initial tracer data are uniform in
2618 :math:`x` and :math:`y` for each depth level.
dcaaa42497 Jeff*2619
2620 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2621
2622 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2623 | Parameter | Group | Default | Description |
2624 +========================================+===========+==================================================+=========================================================================================================+
2625 | :varlink:`hydrogThetaFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial potential temperature (:sup:`o`\ C) |
2626 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2627 | :varlink:`hydrogSaltFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial salinity (g/kg) |
dcaaa42497 Jeff*2628 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2629 | :varlink:`maskIniTemp` | PARM05 | TRUE | apply (center-point) mask to initial hydrographic theta data on/off flag |
2630 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2631 | :varlink:`maskIniSalt` | PARM05 | TRUE | apply (center-point) mask to initial hydrographic salinity on/off flag |
2632 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2633 | :varlink:`checkIniTemp` | PARM05 | TRUE | check if initial theta (at wet-point) identically zero on/off flag |
2634 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2635 | :varlink:`checkIniSalt` | PARM05 | TRUE | check if initial salinity (at wet-point) identically zero on/off flag |
2636 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2637
2638 Tracer Diffusivities
2639 ~~~~~~~~~~~~~~~~~~~~
2640
2641 Lateral eddy diffusivities for temperature and salinity/specific
2642 humidity are specified through the variables :varlink:`diffKhT` and
2643 :varlink:`diffKhS` (in m\ :sup:`2`\ /s). Vertical eddy diffusivities are
ba0b047096 Mart*2644 specified through the variables :varlink:`diffKrT` and :varlink:`diffKrS`.
2645 In addition, biharmonic diffusivities can be specified as well through the
2646 coefficients :varlink:`diffK4T` and :varlink:`diffK4S` (in m\ :sup:`4`\ /s).
2647 The Gent and McWilliams parameterization for advection and mixing of oceanic
2648 tracers is described in :numref:`sub_phys_pkg_gmredi`.
dcaaa42497 Jeff*2649
2650 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.15}|\Y{.575}|
2651
a332812c22 Jeff*2652 .. table::
2653 :class: longtable
2654
2655 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2656 | Parameter | Group | Default | Description |
2657 +========================================+===========+==================================================+=========================================================================================================+
2658 | :varlink:`diffKhT` | PARM01 | 0.0 | Laplacian diffusivity of heat laterally (m\ :sup:`2`\ /s) |
2659 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2660 | :varlink:`diffK4T` | PARM01 | 0.0 | biharmonic diffusivity of heat laterally (m\ :sup:`4`\ /s) |
2661 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2662 | :varlink:`diffKrT` | PARM01 | 0.0 | Laplacian diffusivity of heat vertically (m\ :sup:`2`\ /s) |
2663 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2664 | :varlink:`diffKr4T` | PARM01 | 0.0 | biharmonic diffusivity of heat vertically (m\ :sup:`2`\ /s) |
2665 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2666 | :varlink:`diffKrNrT` | PARM01 | 0.0 at k=top | vertical profile of vertical diffusivity of temperature (m\ :sup:`2`\ /s) |
2667 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2668 | :varlink:`pCellMix_diffKr` | PARM04 | :varlink:`diffKrNr` | vertical diffusivity for too thin partial-cell ([r]\ :sup:`2`\ /s) |
2669 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2670 | :varlink:`diffKhS` | PARM01 | 0.0 | Laplacian diffusivity of salt laterally (m\ :sup:`2`\ /s) |
2671 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2672 | :varlink:`diffK4S` | PARM01 | 0.0 | biharmonic diffusivity of salt laterally (m\ :sup:`4`\ /s) |
2673 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2674 | :varlink:`diffKrS` | PARM01 | 0.0 | Laplacian diffusivity of salt vertically (m\ :sup:`2`\ /s) |
2675 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2676 | :varlink:`diffKr4S` | PARM01 | 0.0 | biharmonic diffusivity of salt vertically (m\ :sup:`2`\ /s) |
2677 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2678 | :varlink:`diffKrNrS` | PARM01 | 0.0 at k=top | vertical profile of vertical diffusivity of salt (m\ :sup:`2`\ /s) |
2679 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2680 | :varlink:`diffKrFile` | PARM05 | :kbd:`' '` | filename for 3D specification of vertical diffusivity (m\ :sup:`2`\ /s); |
2681 | | | | requires #define :varlink:`ALLOW_3D_DIFFKR` |
2682 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2683 | :varlink:`diffKrBL79surf` | PARM01 | 0.0 | surface diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m\ :sup:`2`\ /s) |
2684 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2685 | :varlink:`diffKrBL79deep` | PARM01 | 0.0 | deep diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m\ :sup:`2`\ /s) |
2686 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2687 | :varlink:`diffKrBL79scl` | PARM01 | 2.0E+02 | depth scale for Bryan & Lewis 1979 :cite:`bryan:79` (m) |
2688 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2689 | :varlink:`diffKrBL79Ho` | PARM01 | -2.0E+03 | turning depth for Bryan & Lewis 1979 :cite:`bryan:79` (m) |
2690 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2691 | :varlink:`diffKrBLEQsurf` | PARM01 | 0.0 | same as :varlink:`diffKrBL79surf` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
2692 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2693 | :varlink:`diffKrBLEQdeep` | PARM01 | 0.0 | same as :varlink:`diffKrBL79deep` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
2694 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2695 | :varlink:`diffKrBLEQscl` | PARM01 | 2.0E+02 | same as :varlink:`diffKrBL79scl` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
2696 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2697 | :varlink:`diffKrBLEQHo` | PARM01 | -2.0E+03 | same as :varlink:`diffKrBL79Ho` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
2698 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2699 | :varlink:`BL79LatVary` | PARM01 | 3.0E+01 | transition from diffKrBLEQ to diffKrBL79 parms at this latitude; |
2700 | | | | requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
2701 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*2702
94151a9b18 Jeff*2703 .. _ocean_convection_parms:
2704
dcaaa42497 Jeff*2705 Ocean Convection
2706 ~~~~~~~~~~~~~~~~
2707
ba0b047096 Mart*2708 In addition to specific packages that parameterize ocean convection, two main
2709 model options are available. To use the first option, a convective adjustment
2710 scheme, you need to set the variable :varlink:`cadjFreq`, the frequency
2711 (in seconds) with which the adjustment algorithm is called, to a non-zero value
2712 (note, if :varlink:`cadjFreq` set to a negative value by the user, the model
2713 will set it to the model clock time step). The second option is to parameterize
dcaaa42497 Jeff*2714 convection with implicit vertical diffusion. To do this, set the
2715 logical variable :varlink:`implicitDiffusion` to ``.TRUE.`` and the real
2716 variable :varlink:`ivdc_kappa` (in m\ :sup:`2`\ /s) to
2717 an appropriate tracer vertical diffusivity value for mixing
ba0b047096 Mart*2718 due to static instabilities (typically, several orders of magnitude above the
2719 background vertical diffusivity). Note that :varlink:`cadjFreq` and
dcaaa42497 Jeff*2720 :varlink:`ivdc_kappa` cannot both have non-zero value.
2721
2722 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.125}|\Y{.6}|
2723
2724 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2725 | Parameter | Group | Default | Description |
2726 +========================================+===========+==================================================+=========================================================================================================+
2727 | :varlink:`ivdc_kappa` | PARM01 | 0.0 | implicit vertical diffusivity for convection (m\ :sup:`2`\ /s) |
2728 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff*2729 | :varlink:`cAdjFreq` | PARM03 | 0 | frequency of convective adj. scheme; <0: sets value to :varlink:`deltaTclock` (s) |
dcaaa42497 Jeff*2730 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*2731 | :varlink:`hMixCriteria` | PARM01 | -0.8E+00 | - <0: specifies :math:`\Delta T` (:sup:`o`\ C) to define ML depth where |
2732 | | | | :math:`\Delta\rho = \Delta T*d\rho/dT` occurs |
2733 | | | | - >1: define ML depth where local strat. exceeds mean strat. by this factor (non-dim.) |
dcaaa42497 Jeff*2734 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff*2735 | :varlink:`hMixSmooth` | PARM01 | 0.0 | use this fraction of neighboring points (for smoothing) in ML calculation (0-1; 0: no smoothing) |
dcaaa42497 Jeff*2736 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2737
2738 Parameters: Model Forcing
2739 -------------------------
2740
ba0b047096 Mart*2741 The forcing options that can be prescribed through runtime parameters in
2742 ``data`` are easy to use but somewhat limited in scope. More complex forcing
2743 setups are possible with optional packages such as :filelink:`pkg/exf` or
2744 :filelink:`pkg/rbcs`, in which case most or all of the parameters in this
2745 section can simply be left at their default value.
dcaaa42497 Jeff*2746
2747 Momentum Forcing
2748 ~~~~~~~~~~~~~~~~
2749
2750 This section only applies to the ocean. You need to generate
2751 wind-stress data into two files :varlink:`zonalWindFile` and
2752 :varlink:`meridWindFile` corresponding to the zonal and meridional
2753 components of the wind stress, respectively (if you want the stress
2754 to be along the direction of only one of the model horizontal axes,
2755 you only need to generate one file). The format of the files is
2756 similar to the bathymetry file. The zonal (meridional) stress data
83cdbd2346 Jeff*2757 are assumed to be in pascals and located at U-points (V-points). See the MATLAB
dcaaa42497 Jeff*2758 program ``gendata.m`` in the ``input`` directories of
ba0b047096 Mart*2759 ``verification`` for several tutorial example (e.g.
2760 :filelink:`gendata.m <verification/tutorial_barotropic_gyre/input/gendata.m>`
dcaaa42497 Jeff*2761 in the :ref:`barotropic gyre tutorial <sec_eg_baro>`)
2762 to see how simple analytical wind forcing data are generated for the
2763 case study experiments.
2764
2765 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2766
2767 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2768 | Parameter | Group | Default | Description |
2769 +========================================+===========+==================================================+=========================================================================================================+
2770 | :varlink:`momForcing` | PARM01 | TRUE | included external forcing of momentum on/off flag |
2771 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2772 | :varlink:`zonalWindFile` | PARM05 | :kbd:`' '` | filename for 2D specification of zonal component of wind forcing (N/m\ :sup:`2`) |
2773 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2774 | :varlink:`meridWindFile` | PARM05 | :kbd:`' '` | filename for 2D specification of meridional component of wind forcing (N/m\ :sup:`2`) |
2775 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
e52125a087 Jeff*2776 | :varlink:`momForcingOutAB` | PARM03 | 0 | 1: take momentum forcing out of Adams-Bashforth time stepping |
dcaaa42497 Jeff*2777 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2778 | :varlink:`momTidalForcing` | PARM01 | TRUE | tidal forcing of momentum equation on/off flag (requires tidal forcing files) |
2779 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2780 | :varlink:`ploadFile` | PARM05 | :kbd:`' '` | filename for 2D specification of atmospheric pressure loading (ocean :math:`z`-coor. only) (Pa) |
2781 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2782
2783 Tracer Forcing
2784 ~~~~~~~~~~~~~~
2785
2786 A combination of flux data and relaxation terms can be used for
2787 driving the tracer equations. For potential temperature, heat flux
83cdbd2346 Jeff*2788 data (in W/m\ :sup:`2`) can be stored in the 2-D binary file
dcaaa42497 Jeff*2789 :varlink:`surfQnetfile`. Alternatively or in addition, the forcing can be
2790 specified through a relaxation term. The SST data to which the model
2791 surface temperatures are restored are stored in
83cdbd2346 Jeff*2792 the 2-D binary file :varlink:`thetaClimFile`. The corresponding relaxation
dcaaa42497 Jeff*2793 time scale coefficient is set through the variable
2794 :varlink:`tauThetaClimRelax` (in seconds). The same procedure applies for
2795 salinity with the variable names :varlink:`EmPmRfile`, :varlink:`saltClimFile`,
2796 and :varlink:`tauSaltClimRelax` for freshwater flux (in m/s) and surface
ba0b047096 Mart*2797 salinity (in g/kg) data files and relaxation timescale coefficient
516b08a580 jm-c 2798 (in seconds), respectively.
dcaaa42497 Jeff*2799
2800 .. tabularcolumns:: |\Y{.24}|\Y{.1}|\Y{.15}|\Y{.535}|
2801
a332812c22 Jeff*2802 .. table::
2803 :class: longtable
2804
2805 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2806 | Parameter | Group | Default | Description |
2807 +========================================+===========+==================================================+=========================================================================================================+
2808 | :varlink:`tempForcing` | PARM01 | TRUE | external forcing of temperature forcing on/off flag |
2809 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2810 | :varlink:`surfQnetFile` | PARM05 | :kbd:`' '` | filename for 2D specification of net total heat flux (W/m\ :sup:`2`) |
2811 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2812 | :varlink:`surfQswFile` | PARM05 | :kbd:`' '` | filename for 2D specification of net shortwave flux (W/m\ :sup:`2`); |
2813 | | | | requires #define :varlink:`SHORTWAVE_HEATING` |
2814 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2815 | :varlink:`tauThetaClimRelax` | PARM03 | 0.0 | temperature (surface) relaxation time scale (s) |
2816 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2817 | :varlink:`lambdaThetaFile` | PARM05 | :kbd:`' '` | filename for 2D specification of inverse temperature (surface) relaxation time scale (1/s) |
2818 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2819 | :varlink:`ThetaClimFile` | PARM05 | :kbd:`' '` | filename for specification of (surface) temperature relaxation values (:sup:`o`\ C) |
2820 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2821 | :varlink:`balanceThetaClimRelax` | PARM01 | FALSE | subtract global mean heat flux due to temp. relaxation flux every time step on/off flag; |
2822 | | | | requires #define :varlink:`ALLOW_BALANCE_RELAX` |
2823 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2824 | :varlink:`balanceQnet` | PARM01 | FALSE | subtract global mean Qnet every time step on/off flag; requires #define :varlink:`ALLOW_BALANCE_FLUXES` |
2825 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2826 | :varlink:`geothermalFile` | PARM05 | :kbd:`' '` | filename for 2D specification of geothermal heating flux through bottom (W/m\ :sup:`2`); |
2827 | | | | requires #define :varlink:`ALLOW_GEOTHERMAL_FLUX` |
2828 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2829 | :varlink:`temp_EvPrRn` | PARM01 | UNSET | temperature of rain and evaporated water (unset, use local temp.) (:sup:`o`\ C) |
2830 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2831 | :varlink:`allowFreezing` | PARM01 | FALSE | limit (ocean) temperature at surface to >= -1.9\ :sup:`o`\ C |
2832 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2833 | :varlink:`saltForcing` | PARM01 | TRUE | external forcing of salinity forcing on/off flag |
2834 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2835 | :varlink:`convertFW2Salt` | PARM01 | 3.5E+01 | salinity used to convert freshwater flux to salt flux (-1: use local S) (g/kg) |
a332812c22 Jeff*2836 | | | | (note default is -1 if :varlink:`useRealFreshWaterFlux`\ = ``.TRUE.``) |
2837 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2838 | :varlink:`rhoConstFresh` | PARM01 | :varlink:`rhoConst` | constant reference density for fresh water (rain) (kg/m\ :sup:`3`) |
2839 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2840 | :varlink:`EmPmRFile` | PARM05 | :kbd:`' '` | filename for 2D specification of net freshwater flux (m/s) |
2841 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2842 | :varlink:`saltFluxFile` | PARM05 | :kbd:`' '` | filename for 2D specification of salt flux (from seaice) ((g/kg).kg/m\ :sup:`2`\/s) |
a332812c22 Jeff*2843 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2844 | :varlink:`tauSaltClimRelax` | PARM03 | 0.0 | salinity (surface) relaxation time scale (s) |
2845 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2846 | :varlink:`lambdaSaltFile` | PARM05 | :kbd:`' '` | filename for 2D specification of inverse salinity (surface) relaxation time scale (1/s) |
2847 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2848 | :varlink:`saltClimFile` | PARM05 | :kbd:`' '` | filename for specification of (surface) salinity relaxation values (g/kg) |
a332812c22 Jeff*2849 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2850 | :varlink:`balanceSaltClimRelax` | PARM01 | FALSE | subtract global mean flux due to salt relaxation every time step on/off flag |
2851 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
7e00d7e8f9 Jean*2852 | :varlink:`selectBalanceEmPmR` | PARM01 | 0 | option to balance net surface freshwater flux every time step |
2853 | | | | |
2854 | | | | - 0: off |
2855 | | | | - 1: uniform surface correction |
2856 | | | | - 2: non-uniform surface correction, scaled using :varlink:`wghtBalancedFile` for local weighting |
2857 | | | | |
2858 | | | | if =1 or 2, requires #define :varlink:`ALLOW_BALANCE_FLUXES` |
2859 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2860 | :varlink:`wghtBalanceFile` | PARM05 | :kbd:`' '` | filename for 2D specification of weights used in :varlink:`selectBalanceEmPmR` =2 correction |
a332812c22 Jeff*2861 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
ba0b047096 Mart*2862 | :varlink:`salt_EvPrRn` | PARM01 | 0.0 | salinity of rain and evaporated water (g/kg) |
a332812c22 Jeff*2863 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2864 | :varlink:`selectAddFluid` | PARM01 | 0 | add fluid to ocean interior options (-1, 0: off, or 1); requires #define :varlink:`ALLOW_ADDFLUID` |
2865 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2866 | :varlink:`temp_addMass` | PARM01 | :varlink:`temp_EvPrRn` | temp. of added or removed (interior) water (:sup:`o`\ C); requires #define :varlink:`ALLOW_ADDFLUID` |
2867 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2868 | :varlink:`salt_addMass` | PARM01 | :varlink:`salt_EvPrRn` | salinity of added or removed (interior) water (:sup:`o`\ C); requires #define :varlink:`ALLOW_ADDFLUID` |
2869 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2870 | :varlink:`addMassFile` | PARM05 | :kbd:`' '` | filename for 3D specification of mass source/sink (+=source, kg/s); |
2871 | | | | requires #define :varlink:`ALLOW_ADDFLUID` |
2872 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2873 | :varlink:`balancePrintMean` | PARM01 | FALSE | print subtracted balancing means to STDOUT on/off flag; |
2874 | | | | requires #define :varlink:`ALLOW_BALANCE_FLUXES` and/or #define :varlink:`ALLOW_BALANCE_RELAX` |
2875 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2876 | :varlink:`latBandClimRelax` | PARM03 | whole domain | relaxation to (T,S) climatology equatorward of this latitude band is applied |
2877 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2878 | :varlink:`tracForcingOutAB` | PARM03 | 0 | 1: take T, S, and pTracer forcing out of Adams-Bashforth time stepping |
2879 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
dcaaa42497 Jeff*2880
2881 .. _periodic_forcing_expl:
2882
2883 Periodic Forcing
2884 ~~~~~~~~~~~~~~~~
2885
2886 To prescribe time-dependent periodic
2887 forcing, concatenate successive time records into a
2888 single file ordered in a (:math:`x,y`,time) fashion
2889 and set the following variables: :varlink:`periodicExternalForcing` to
ba0b047096 Mart*2890 ``.TRUE.``, :varlink:`externForcingPeriod` to the period (in seconds between
2891 two records in input files) with which
dcaaa42497 Jeff*2892 the forcing varies (e.g., 1 month), and :varlink:`externForcingCycle`
2893 to the repeat time (in seconds) of the forcing (e.g., 1 year; note
2894 :varlink:`externForcingCycle` must be a multiple of
2895 :varlink:`externForcingPeriod`). With these variables specified, the model
2896 will interpolate the forcing linearly at each iteration.
2897
2898 .. tabularcolumns:: |\Y{.25}|\Y{.1}|\Y{.125}|\Y{.55}|
2899
2900 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2901 | Parameter | Group | Default | Description |
2902 +========================================+===========+==================================================+=========================================================================================================+
2903 | :varlink:`periodicExternalForcing` | PARM03 | FALSE | allow time-dependent periodic forcing on/off flag |
2904 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2905 | :varlink:`externForcingPeriod` | PARM03 | 0.0 | period over which forcing varies (e.g. monthly) (s) |
2906 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2907 | :varlink:`externForcingCycle` | PARM03 | 0.0 | period over which the forcing cycle repeats (e.g. one year) (s) |
2908 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2909
2910 .. _simulation_controls:
69e7157c80 Jeff*2911
2912 Parameters: Simulation Controls
2913 -------------------------------
2914
dcaaa42497 Jeff*2915 Run Start and Duration
2916 ~~~~~~~~~~~~~~~~~~~~~~
2917
2918 The beginning of a simulation is set by specifying a start time (in seconds)
2919 through the real variable :varlink:`startTime` or by specifying an
2920 initial iteration number through the integer variable :varlink:`nIter0`. If
2921 these variables are set to non-zero values, the model will look for a
ba0b047096 Mart*2922 âpickupâ file (by default, ``pickup.0000nIter0``) to restart the integration.
2923 The end of a simulation is set through the real variable :varlink:`endTime`
2924 (in seconds). Alternatively, one can instead specify the number of time steps
dcaaa42497 Jeff*2925 to execute through the integer variable :varlink:`nTimeSteps`.
ba0b047096 Mart*2926 Iterations are referenced to :varlink:`deltaTClock`, i.e., each iteration is
2927 :varlink:`deltaTClock` seconds of model time.
dcaaa42497 Jeff*2928
2929 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2930
2931 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2932 | Parameter | Group | Default | Description |
2933 +========================================+===========+==================================================+=========================================================================================================+
2934 | :varlink:`nIter0` | PARM03 | 0 | starting timestep iteration number for this integration |
2935 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2936 | :varlink:`nTimeSteps` | PARM03 | 0 | number of (model clock) timesteps to execute |
2937 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2938 | :varlink:`nEndIter` | PARM03 | 0 | run ending timestep iteration number (alternate way to prescribe :varlink:`nTimeSteps`) |
2939 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2940 | :varlink:`startTime` | PARM03 | :varlink:`baseTime` | run start time for this integration (s) (alternate way to prescribe :varlink:`nIter0`) |
2941 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2942 | :varlink:`endTime` | PARM03 | 0.0 | run ending time (s) (with :varlink:`startTime`, alternate way to prescribe :varlink:`nTimeSteps`) |
2943 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2944
2945 Input/Output Files
2946 ~~~~~~~~~~~~~~~~~~
2947
2948 The precision with which to read binary data is
2949 controlled by the integer variable :varlink:`readBinaryPrec`, which can take
ba0b047096 Mart*2950 the value 32 (single precision) or 64 (double precision). Similarly, the
2951 precision with which to write binary data is controlled by the integer variable
2952 :varlink:`writeBinaryPrec`. By default, MITgcm writes output (snapshots,
2953 diagnostics, and pickups) separately for individual tiles, leaving it to the
2954 user to reassemble these into global files, if needed (scripts are available in
2955 :filelink:`utils/`). There are two options however to have the model do this
2956 for you. Setting :varlink:`globalFiles` to ``.TRUE.`` should always work in a
2957 single process setup (including multi-threaded processes), but for
2958 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ runs this will
2959 depend on the platform -- it requires simultaneous write access to a common
2960 file (permissible in typical
2961 `Lustre <https://en.wikipedia.org/wiki/Lustre_(file_system)>`_ setups, but not
2962 on all file systems). Alternatively, one can set :varlink:`useSingleCpuIO`
2963 to ``.TRUE.`` to generate global files, which should always work, but requires
2964 additional mpi-passing of data and may result in slower execution.
dcaaa42497 Jeff*2965
2966 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
2967
2968 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2969 | Parameter | Group | Default | Description |
2970 +========================================+===========+==================================================+=========================================================================================================+
e52125a087 Jeff*2971 | :varlink:`globalFiles` | PARM01 | FALSE | write output âglobalâ (i.e. not per tile) files on/off flag |
dcaaa42497 Jeff*2972 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2973 | :varlink:`useSingleCpuIO` | PARM01 | FALSE | only master MPI process does I/O (producing global output files) |
2974 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2975 | :varlink:`the_run_name` | PARM05 | :kbd:`' '` | string identifying the name of the model "run" for meta files |
2976 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2977 | :varlink:`readBinaryPrec` | PARM01 | 32 | precision used for reading binary files (32 or 64) |
2978 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2979 | :varlink:`writeBinaryPrec` | PARM01 | 32 | precision used for writing binary files (32 or 64) |
2980 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2981 | :varlink:`outputTypesInclusive` | PARM03 | FALSE | allows writing of output files in multiple formats (i.e. :filelink:`pkg/mdsio` and :filelink:`pkg/mnc`)|
2982 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2983 | :varlink:`rwSuffixType` | PARM03 | 0 | controls the format of the :filelink:`pkg/mdsio` binary file âsuffixâ |
a332812c22 Jeff*2984 | | | | |
2985 | | | | - 0: use iteration number (myIter, I10.10) |
2986 | | | | - 1: 100*myTime |
2987 | | | | - 2: myTime |
2988 | | | | - 3: myTime/360 |
2989 | | | | - 4: myTime/3600 |
2990 | | | | |
2991 | | | | where :varlink:`myTime` is model time in seconds |
dcaaa42497 Jeff*2992 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2993 | :varlink:`mdsioLocalDir` | PARM05 | :kbd:`' '` | if not blank, read-write output tiled files from/to this directory name |
2994 | | | | (+four-digit processor-rank code) |
2995 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
2996
69e7157c80 Jeff*2997 .. _freq_of_output:
2998
dcaaa42497 Jeff*2999 Frequency/Amount of Output
3000 ~~~~~~~~~~~~~~~~~~~~~~~~~~
69e7157c80 Jeff*3001
dcaaa42497 Jeff*3002 The frequency (in seconds) with which output
3003 is written to disk needs to be specified. :varlink:`dumpFreq` controls the
ba0b047096 Mart*3004 frequency with which the instantaneous state of the model is written.
3005 :varlink:`monitorFreq` controls the frequency with which monitor output is
3006 dumped to the standard output file(s). The frequency of output is referenced
3007 to :varlink:`deltaTClock`.
69e7157c80 Jeff*3008
dcaaa42497 Jeff*3009 .. tabularcolumns:: |\Y{.18}|\Y{.1}|\Y{.2}|\Y{.545}|
69e7157c80 Jeff*3010
dcaaa42497 Jeff*3011 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3012 | Parameter | Group | Default | Description |
3013 +========================================+===========+==================================================+=========================================================================================================+
3014 | :varlink:`dumpFreq` | PARM03 | 0.0 | interval to write model state/snapshot data (s) |
3015 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3016 | :varlink:`dumpInitAndLast` | PARM03 | TRUE | write out initial and last iteration model state on/off flag |
3017 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3018 | :varlink:`diagFreq` | PARM03 | 0.0 | interval to write additional intermediate (debugging cg2d/3d) output (s) |
3019 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3020 | :varlink:`monitorFreq` | PARM03 | lowest of other output \*Freq parms | interval to write monitor output (s) |
3021 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
a332812c22 Jeff*3022 | :varlink:`monitorSelect` | PARM03 | 2 (3 if fluid is water) | select group of monitor variables to output |
3023 | | | | |
3024 | | | | - 1: dynamic variables only |
3025 | | | | - 2: add vorticity variables |
3026 | | | | - 3: add surface variables |
dcaaa42497 Jeff*3027 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
5f61c21b01 Jeff*3028 | :varlink:`debugLevel` | PARM01 | depends on :varlink:`debugMode` | level of printing of MITgcm activity messages/statistics (1-5, higher -> more activity messages) |
dcaaa42497 Jeff*3029 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3030 | :varlink:`plotLevel` | PARM01 | :varlink:`debugLevel` | controls printing of field maps (1-5, higher -> more fields) |
3031 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3032
3033 Restart/Pickup Files
3034 ~~~~~~~~~~~~~~~~~~~~
3035
3036 :varlink:`chkPtFreq` and :varlink:`pchkPtFreq` control the output frequency of
ba0b047096 Mart*3037 rolling and permanent pickup (a.k.a. checkpoint) files, respectively. These
3038 frequencies are referenced to :varlink:`deltaTClock`.
dcaaa42497 Jeff*3039
3040 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
69e7157c80 Jeff*3041
dcaaa42497 Jeff*3042 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3043 | Parameter | Group | Default | Description |
3044 +========================================+===========+==================================================+=========================================================================================================+
3045 | :varlink:`pChkPtFreq` | PARM03 | 0.0 | permanent restart/pickup checkpoint file write interval ( s ) |
3046 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3047 | :varlink:`chkPtFreq` | PARM03 | 0.0 | rolling restart/pickup checkpoint file write interval ( s ) |
3048 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
5f61c21b01 Jeff*3049 | :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*3050 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3051 | :varlink:`pickupStrictlyMatch` | PARM03 | TRUE | force pickup (meta) file formats to exactly match (or terminate with error) on/off flag |
3052 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3053 | :varlink:`writePickupAtEnd` | PARM03 | FALSE | write a (rolling) pickup file at run completion on/off flag |
3054 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3055 | :varlink:`usePickupBeforeC54` | PARM01 | FALSE | initialize run using old pickup format from code prior to checkpoint54a |
3056 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3057 | :varlink:`startFromPickupAB2` | PARM03 | FALSE | using Adams-Bashforth-3, start using Adams-Bashforth-2 pickup format; |
3058 | | | | requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` |
3059 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3060
3061 Parameters Used In Optional Packages
3062 ------------------------------------
3063
ba0b047096 Mart*3064 Some optional packages were not written with package-specific namelist
3065 parameters in a ``data.${pkg}`` file; or for historical and/or other reasons,
3066 several package-specific namelist parameters remain in ``data``.
dcaaa42497 Jeff*3067
3068 .. _c-d_scheme:
3069
3070 C-D Scheme
3071 ~~~~~~~~~~
3072
3073 (package :filelink:`pkg/cd_code`)
3074
3075 If you run at a sufficiently coarse resolution, you might choose to enable the
3076 C-D scheme for the computation of the Coriolis terms. The
3077 variable :varlink:`tauCD`, which represents the C-D scheme coupling
3078 timescale (in seconds) needs to be set.
3079
3080 .. tabularcolumns:: |\Y{.175}|\Y{.1}|\Y{.225}|\Y{.525}|
3081
3082 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3083 | Parameter | Group | Default | Description |
3084 +========================================+===========+==================================================+=========================================================================================================+
3085 | :varlink:`useCDscheme` | PARM01 | FALSE | use C-D scheme for Coriolis terms on/off flag |
3086 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3087 | :varlink:`tauCD` | PARM03 | :varlink:`deltaTMom` | C-D scheme coupling timescale (s) |
3088 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3089 | :varlink:`rCD` | PARM03 | 1 - :varlink:`deltaTMom`/:varlink:`tauCD` | C-D scheme normalized coupling parameter (non-dim.) |
3090 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3091 | :varlink:`epsAB_CD` | PARM03 | :varlink:`abEps` | Adams-Bashforth-2 stabilizing weight used in C-D scheme |
3092 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3093
3094 Automatic Differentiation
3095 ~~~~~~~~~~~~~~~~~~~~~~~~~
3096
3097 (package :filelink:`pkg/autodiff`; see :numref:`chap_autodiff`)
3098
3099 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
3100
3101 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3102 | Parameter | Group | Default | Description |
3103 +========================================+===========+==================================================+=========================================================================================================+
3104 | :varlink:`nTimeSteps_l2` | PARM03 | 4 | number of inner timesteps to execute per timestep |
3105 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3106 | :varlink:`adjdumpFreq` | PARM03 | 0.0 | interval to write model state/snapshot data adjoint run (s) |
3107 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3108 | :varlink:`adjMonitorFreq` | PARM03 | 0.0 | interval to write monitor output adjoint run (s) |
3109 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3110 | :varlink:`adTapeDir` | PARM05 | :kbd:`' '` | if not blank, read-write checkpointing files from/to this directory name |
3111 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3112
3113 .. _eedata_parms:
3114
3115 Execution Environment Parameters
3116 --------------------------------
3117
ba0b047096 Mart*3118 If running multi-threaded (i.e., using shared
3119 memory/`OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_), you will need to set
3120 :varlink:`nTx` and/or :varlink:`nTy` so that :varlink:`nTx`\ \*\ :varlink:`nTy`
3121 is the total number of threads (per process).
dcaaa42497 Jeff*3122
ba0b047096 Mart*3123 The parameter :varlink:`useCubedSphereExchange` needs to be changed to
3124 ``.TRUE.`` if you are using any type of grid composed of interconnected
3125 individual faces, including the cubed sphere topology or a lat-lon cap grid.
3126 See (needs section to be written).
dcaaa42497 Jeff*3127
ba0b047096 Mart*3128 Note that setting flag :varlink:`debugMode` to ``.TRUE.`` activates a separate
3129 set of debugging print statements than parameter :varlink:`debugLevel`
3130 (see :numref:`freq_of_output`). The latter controls print statements that
3131 monitor model activity (such as opening files, etc.), whereas the former
3132 produces a more coding-oriented set of print statements (e.g., entering and
3133 exiting subroutines, etc.)
dcaaa42497 Jeff*3134
3135 .. tabularcolumns:: |\Y{.25}|\Y{.125}|\Y{.125}|\Y{.525}|
3136
3137 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3138 | Parameter | Group | Default | Description |
3139 +========================================+===========+==================================================+=========================================================================================================+
3140 | :varlink:`useCubedSphereExchange` | EEPARMS | FALSE | use cubed-sphere topology domain on/off flag |
3141 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3142 | :varlink:`nTx` | EEPARMS | 1 | number of threads in the :math:`x` direction |
3143 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3144 | :varlink:`nTy` | EEPARMS | 1 | number of threads in the :math:`y` direction |
3145 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3146 | :varlink:`useCoupler` | EEPARMS | FALSE | communicate with other model components through a coupler on/off flag |
3147 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3148 | :varlink:`useSETRLSTK` | EEPARMS | FALSE | call C routine to set environment stacksize to âunlimitedâ |
3149 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3150 | :varlink:`useSIGREG` | EEPARMS | FALSE | enable signal handler to receive signal to terminate run cleanly on/off flag |
3151 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3152 | :varlink:`debugMode` | EEPARMS | FALSE | print additional debugging messages; also âflushâ STDOUT file unit after each print |
3153 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3154 | :varlink:`printMapIncludesZeros` | EEPARMS | FALSE | text map plots of fields should ignore exact zero values on/off flag |
3155 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
3156 | :varlink:`maxLengthPrt1D` | EEPARMS | 65 | maximum number of 1D array elements to print to standard output |
3157 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+
83cdbd2346 Jeff*3158
3159 .. _sec_mitgcm_inp_file_format:
3160
3161 MITgcm Input Data File Format
3162 =============================
3163
ce0d9af5ea Jeff*3164 MITgcm input files for grid-related data (e.g., :varlink:`delXFile`),
3165 forcing fields (e.g., :varlink:`tauThetaClimRelax`),
3166 parameter fields (e.g., :varlink:`viscAhZfile`), etc. are assumed to
3167 be in "flat" or "unblocked" `binary format <https://en.wikipedia.org/wiki/Binary_file>`_.
fbfa6b7fb7 Jody*3168
3169 Data is expected to be in
3170 `Fortran/column-major order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_,
3171 in the order (:math:`x`, :math:`y`, :math:`z`, :math:`t`).
3172 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ typically
3173 uses F-order, while Python's `NumPy <https://numpy.org>`_ uses C-order (row-major order).
3174
3175 For historical reasons, many large MITgcm projects use big-endian
ce0d9af5ea Jeff*3176 `byte ordering <https://en.wikipedia.org/wiki/Endianness>`_,
3177 **NOT** little-endian which is the more common default for today's computers.
fbfa6b7fb7 Jody*3178 Thus, some care is required to create MITgcm-readable input files. However, if
3179 you prepare your own input files, it is perfectly fine to use little-endian so
3180 long as you also compile your executable to be little-endian compatible.
83cdbd2346 Jeff*3181
ce0d9af5ea Jeff*3182 - Using `MATLAB <https://www.mathworks.com/products/matlab.html>`_:
3183 When writing binary files, MATLAB's `fopen <https://www.mathworks.com/help/matlab/ref/fopen.html>`_
3184 command includes a MACHINEFORMAT option ``'b'`` which instructs MATLAB
3185 to read or write using big-endian byte ordering. 2-D arrays should be
fbfa6b7fb7 Jody*3186 index-ordered in MATLAB as (:math:`x`, :math:`y`), 3-D arrays as
3187 (:math:`x`, :math:`y`, :math:`z`), and 4-D arrays as
3188 (:math:`x`, :math:`y`, :math:`z`, :math:`t`); data is ordered from low to high in
ce0d9af5ea Jeff*3189 each index, with :math:`x` varying most rapidly.
83cdbd2346 Jeff*3190
ce0d9af5ea Jeff*3191 An example to create a bathymetry file of single-precision, floating
3192 point values (from tutorial :ref:`sec_eg_baro`, a simple enclosed,
3193 flat-bottom domain) is as follows:
83cdbd2346 Jeff*3194
3195 ::
3196
ce0d9af5ea Jeff*3197 ieee = 'b'; % big-endian format
3198 accuracy = 'float32'; % this is single-precision (='real*4')
83cdbd2346 Jeff*3199
3200 Ho=5000; % ocean depth in meters
ce0d9af5ea Jeff*3201 nx=62; % number of gridpoints in x-direction
3202 ny=62; % number of gridpoints in y-direction
83cdbd2346 Jeff*3203
ce0d9af5ea Jeff*3204 % Flat bottom at z = -Ho
3205 h = -Ho * ones(nx, ny);
83cdbd2346 Jeff*3206
ce0d9af5ea Jeff*3207 % Walls (surrounding domain)
3208 h([1 end], :) = 0; % set ocean depth to zero at east and west walls
3209 h(:, [1 end]) = 0; % set ocean depth to zero at south and north walls
83cdbd2346 Jeff*3210
ce0d9af5ea Jeff*3211 % save as single-precision (float32) with big-endian byte ordering
3212 fid = fopen('bathy.bin', 'w', ieee);
3213 fwrite(fid, h, accuracy);
3214 fclose(fid);
3215
3216 To read this bathymetry file back into MATLAB, reshaped back to (nx, ny):
83cdbd2346 Jeff*3217
3218 ::
3219
ce0d9af5ea Jeff*3220 fid = fopen('bathy.bin', 'r', ieee);
3221 h = reshape(fread(fid, Inf, accuracy), nx, ny);
3222 fclose(fid);
3223
fbfa6b7fb7 Jody*3224 - Using Python's `NumPy <https://numpy.org>`_:
83cdbd2346 Jeff*3225
fbfa6b7fb7 Jody*3226 The `tofile <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.tofile.html>`_
3227 method on a NumPy array writes the data in
3228 `row-major or C-order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_,
3229 so arrays should be shaped to take this into account for the MITgcm:
3230 (:math:`y`, :math:`x`) for 2-D, (:math:`z`, :math:`y`, :math:`x`) for 3-D, and
3231 (:math:`t`, :math:`z`, :math:`y`, :math:`x`) for 4-D.
3232
3233 A python version of the above script can use NumPy to create a bathymetry file is as
3234 follows:
83cdbd2346 Jeff*3235
3236 ::
3237
ce0d9af5ea Jeff*3238 import numpy as np
83cdbd2346 Jeff*3239
ce0d9af5ea Jeff*3240 Ho = 5000 # ocean depth in meters
3241 nx = 62 # number of gridpoints in x-direction
3242 ny = 62 # number of gridpoints in y-direction
83cdbd2346 Jeff*3243
ce0d9af5ea Jeff*3244 # Flat bottom at z = -Ho
3245 h = -Ho * np.ones((ny, nx))
3246
3247 # Walls (surrounding domain)
3248 h[:, [0,-1]] = 0 # set ocean depth to zero at east and west walls
3249 h[[0,-1], :] = 0 # set ocean depth to zero at south and north walls
3250
3251 # save as single-precision (NumPy type float32) with big-endian byte ordering
3252 h.astype('>f4').tofile('bathy.bin')
3253
fbfa6b7fb7 Jody*3254 The dtype specification ``'>f4'`` above instructs NumPy to write the file with
ce0d9af5ea Jeff*3255 big-endian byte ordering (specifically, due to the '>') as single-precision real
3256 numbers (due to the 'f4' which is NumPy ``float32`` or equivalently,
3257 Fortran ``real*4`` format).
3258
fbfa6b7fb7 Jody*3259 To read this bathymetry file back into NumPy, reshaped back to (ny, nx):
83cdbd2346 Jeff*3260
3261 ::
3262
ce0d9af5ea Jeff*3263 h = np.fromfile('bathy.bin', '>f4').reshape(ny, nx)
83cdbd2346 Jeff*3264
fbfa6b7fb7 Jody*3265 where again the dtype spec instructs NumPy to read a big-endian
ce0d9af5ea Jeff*3266 file of single-precision, floating point values.
83cdbd2346 Jeff*3267
ce0d9af5ea Jeff*3268 A more complicated example of using Python to generate input date is provided in
3269 :filelink:`verification/tutorial_baroclinic_gyre/input/gendata.py`.
83cdbd2346 Jeff*3270
3271 - Using `Fortran <https://en.wikipedia.org/wiki/Fortran>`_:
ce0d9af5ea Jeff*3272 To create flat binary files in Fortran, open with
3273 syntax ``OPEN(..., ACCESS='DIRECT', ...)`` (i.e., **NOT** ``ACCESS='SEQUENTIAL'``
3274 which includes additional metadata). By default Fortran will use the
3275 local computer system's native byte ordering for reading and writing binary files,
83cdbd2346 Jeff*3276 which for most systems will be little-endian. One therefore has two options:
ce0d9af5ea Jeff*3277 after creating a binary file in Fortran, use MATLAB or Python (or some
3278 other utility) to read in and swap the bytes in the process of writing a new file;
3279 or, determine if your local Fortran has
3280 a compiler flag to control byte-ordering of binary files.
3281 Similar to MATLAB, 2-D and 3-D arrays in Fortran should be index-ordered
3282 as (:math:`x`, :math:`y`) and (:math:`x`, :math:`y`, :math:`z`), respectively.
ba0b047096 Mart*3283
ce0d9af5ea Jeff*3284 Using `NetCDF <http://www.unidata.ucar.edu/software/netcdf>`_ format for input files is only
3285 partially implemented at present in MITgcm, and use is thus discouraged.
ba0b047096 Mart*3286
3287 Input files are by default single-precision real numbers (32-bit, ``real*4``),
ce0d9af5ea Jeff*3288 but can be switched to double precision by setting
3289 namelist parameter :varlink:`readBinaryPrec` (``PARM01`` in file ``data``)
3290 to a value of 64.