darwin3 |
|
|
|
|||
Warning, /doc/getting_started/getting_started.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit 31fb0e0e on 2025-05-05 02:15:14 UTC69e7157c80 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.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 51.
0050 You will need to decide if you want to work in a âgit-awareâ** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 52.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 57.
0056 order to make it worth oneâs while. 69e7157c80 Jeff*0057 ba0b047096 Mart*0058 Periodically we release an official checkpoint** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 60.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 84.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 147.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 194.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 232.
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`.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 276.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 291.
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)>`_** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 298.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 370.
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>`** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 386.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 390.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 393.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 500.
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>`_** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 502.
0501 output; more specifically, a ânoâ response to âCan we create NetCDF-enabled** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 503.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 505.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 523.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 542.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 551.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 559.
0558 ``âmods '«DIR1 DIR2 DIR3 ...»'`` 69e7157c80 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 560.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 569.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 576.
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`** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 616.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 625.
0624 ``âadoptfile «/PATH/TO/FILE»`` ba0b047096 Mart*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 626.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 632.
0631 :filelink:`tools/adjoint_options/adjoint_default` and it defines the âTAFâ 516b08a580 jm-c** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 633.
0632 and âTAMCâ compiler options. 69e7157c80 Jeff*0633** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 635.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 642.
0641 ``âomp`` ba0b047096 Mart*0642 enables OpenMP code and compiler flag ``OMPFLAG`` 0643 (see :numref:`build_openmp`). 69e7157c80 Jeff*0644** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 646.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 657.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 677.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 746.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 768.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 776.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 886.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 890.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 895.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 906.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 915.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 966.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 992.
0991 run, and modify your configurationâs :filelink:`SIZE.h <model/inc/SIZE.h>`** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 993.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 999.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1100.
1099 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ ârunâ or** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1101.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1181.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1183.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1186.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1190.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1216.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1245.
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*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1252.
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 f460f9a57e Ivan*1368 Bash scripts 1369 ~~~~~~~~~~~~ 1370 1371 The repository includes utilities for handling model input and output. You can 1372 add these command line scripts to the system's search path by modifying the 1373 unix `PATH <https://www.digitalocean.com/community/tutorials/how-to-view-and-update-the-linux-path-environment-variable>`_ 1374 variable. To permanently access MITgcm bash utilities, put this line in 1375 your shell configuration file e.g. ``.bashrc`` or ``.zshrc``: 1376 1377 :: 1378 1379 export PATH=$PATH:/path/to/your/MITgcm/utils/scripts 1380 1381 NetCDF output 1382 ^^^^^^^^^^^^^ 1383 1384 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ output is produced 1385 with one file per processor. This means unique tiles need to be stitched 1386 together to create a single 1387 `netCDF <http://www.unidata.ucar.edu/software/netcdf>`_ file that spans the 1388 model domain. The script :filelink:`utils/scripts/gluemnc` can do this from the 1389 command line. For usage information and dependencies, see :numref:`gluemnc`. 1390 dcaaa42497 Jeff*1391 .. _customize_compilation: 1392 1393 Customizing the Model Configuration - Code Parameters and Compilation Options 1394 ============================================================================= 1395 1396 Model Array Dimensions 1397 ---------------------- 1398** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1400.
1399 MITgcmâs array dimensions need to be configured for each unique model domain. ba0b047096 Mart*1400 The size of each tile (in dimensions :math:`x`, :math:`y`, and vertical** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1402.
1401 coordinate :math:`r`) the âoverlapâ region of each tile (in :math:`x` and 1402 :math:`y`), the number of tiles in the :math:`x` and :math:`y` dimensions, 1403 and the number of processes (using 1404 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_) 1405 in the :math:`x` and :math:`y` dimensions all need to be specified in 1406 :filelink:`SIZE.h <model/inc/SIZE.h>`. From these parameters, global 1407 domain-size variables :varlink:`Nx`, :varlink:`Ny` are computed by the model. 1408 See a more technical discussion of :filelink:`SIZE.h <model/inc/SIZE.h>` 1409 parameters in in :numref:`specify_decomp`, and a detailed explanation of an 1410 example :filelink:`SIZE.h <model/inc/SIZE.h>` setup in tutorial 1411 :ref:`Baroclinic Ocean Gyre <baroc_code_size>`. dcaaa42497 Jeff*1412 1413 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1414 | Parameter | Default :filelink:`SIZE.h <model/inc/SIZE.h>` | Description | 1415 +========================================+==================================================+=========================================================================================================+ 1416 | :varlink:`sNx` | 30 | number of points in :math:`x` dimension in a single tile | 1417 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1418 | :varlink:`sNy` | 15 | number of points in :math:`y` dimension in a single tile | 1419 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1420 | :varlink:`Nr` | 4 | number of points in :math:`r` dimension | 1421 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1423.
1422 | :varlink:`OLx` | 2 | number of âoverlapâ points in :math:`x` dimension for a tile | 1423 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1425.
1424 | :varlink:`OLy` | 2 | number of âoverlapâ points in :math:`y` dimension for a tile | 1425 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1426 | :varlink:`nSx` | 2 | number of tile per process in :math:`x` dimension | 1427 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1428 | :varlink:`nSy` | 4 | number of tile per process in :math:`y` dimension | 1429 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1430 | :varlink:`nPx` | 1 | number of processes in :math:`x` dimension | 1431 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1432 | :varlink:`nPy` | 1 | number of processes in :math:`y` dimension | 1433 +----------------------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1434 ba0b047096 Mart*1435 Note the repository version of :filelink:`SIZE.h <model/inc/SIZE.h>` includes 1436 several lines of text at the top that will halt compilation with errors. Thus, 1437 to use MITgcm you will need to copy :filelink:`SIZE.h <model/inc/SIZE.h>` to a 1438 code modification directory and make edits, including deleting or commenting 1439 out the offending lines of text. dcaaa42497 Jeff*1440 1441 C Preprocessor Options 1442 ---------------------- 1443** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1445.
1444 The CPP flags relative to the ânumerical modelâ part of the code are ba0b047096 Mart*1445 defined and set in the file :filelink:`CPP_OPTIONS.h <model/inc/CPP_OPTIONS.h>` 1446 in the directory :filelink:`model/inc/`. In the parameter tables in 1447 :numref:`customize_model` we have noted CPP options **that need to be changed 1448 from the default** to enable specific runtime parameter to be used properly. 1449 Also note many of the options below are for less-common situations or are 1450 somewhat obscure, so newer users of the MITgcm are encouraged to jump to 1451 :numref:`customize_model` where more basic runtime parameters are discussed. dcaaa42497 Jeff*1452 1453 .. tabularcolumns:: |\Y{.475}|\Y{.1}|\Y{.45}| 1454 a332812c22 Jeff*1455 .. table:: 1456 :class: longtable 1457 1458 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1459 | CPP Flag Name | Default | Description | 1460 +===============================================+=========+======================================================================================================================+ 1461 | :varlink:`SHORTWAVE_HEATING` | #undef | provide separate shortwave heating file, allowing shortwave to penetrate below surface layer | 1462 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1463 | :varlink:`ALLOW_GEOTHERMAL_FLUX` | #undef | include code for applying geothermal heat flux at the bottom of the ocean | 1464 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1465 | :varlink:`ALLOW_FRICTION_HEATING` | #undef | include code to allow heating due to friction (and momentum dissipation) | 1466 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1467 | :varlink:`ALLOW_ADDFLUID` | #undef | allow mass source or sink of fluid in the interior (3D generalization of oceanic real-fresh water flux) | 1468 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1469 | :varlink:`ATMOSPHERIC_LOADING` | #define | include code for atmospheric pressure-loading (and seaice-loading) on ocean surface | 1470 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1471 | :varlink:`ALLOW_BALANCE_FLUXES` | #undef | include balancing surface forcing fluxes code | 1472 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1473 | :varlink:`ALLOW_BALANCE_RELAX` | #undef | include balancing surface forcing relaxation code | 1474 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1475 | :varlink:`CHECK_SALINITY_FOR_NEGATIVE_VALUES` | #undef | include code checking for negative salinity | 1476 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1477 | :varlink:`EXCLUDE_FFIELDS_LOAD` | #undef | exclude external forcing-fields load; code allows reading and simple linear time interpolation of oceanic | 1478 | | | forcing fields, if no specific pkg (e.g., :filelink:`pkg/exf`) is used to compute them | 1479 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 0bad585a21 Navi*1480 | :varlink:`INCLUDE_PHIHYD_CALCULATION_CODE` | #define | include code to calculate :math:`\phi_{\rm hyd}` | a332812c22 Jeff*1481 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1482 | :varlink:`INCLUDE_CONVECT_CALL` | #define | include code for convective adjustment mixing algorithm | 1483 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1484 | :varlink:`INCLUDE_CALC_DIFFUSIVITY_CALL` | #define | include codes that calculates (tracer) diffusivities and viscosities | 1485 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1486 | :varlink:`ALLOW_3D_DIFFKR` | #undef | allow full 3D specification of vertical diffusivity | 1487 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1488 | :varlink:`ALLOW_BL79_LAT_VARY` | #undef | allow latitudinally varying Bryan and Lewis 1979 :cite:`bryan:79` vertical diffusivity | 1489 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1490 | :varlink:`EXCLUDE_PCELL_MIX_CODE` | #undef | exclude code for partial-cell effect (physical or enhanced) in vertical mixing; this allows accounting | 1491 | | | for partial-cell in vertical viscosity and diffusion, either from grid-spacing reduction effect or as | 1492 | | | artificially enhanced mixing near surface & bottom for too thin grid-cell | 1493 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ dafe4f37ba Jean*1494 | :varlink:`ALLOW_SMAG_3D_DIFFUSIVITY` | #undef | include code for isotropic 3-D Smagorinsky diffusivity for tracers (viscosity scaled by constant Prandtl number) | 1495 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*1496 | :varlink:`ALLOW_SOLVE4_PS_AND_DRAG` | #undef | include code for combined surface pressure and drag implicit solver | 1497 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1498 | :varlink:`INCLUDE_IMPLVERTADV_CODE` | #define | include code for implicit vertical advection | 1499 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1500 | :varlink:`ALLOW_ADAMSBASHFORTH_3` | #undef | include code for Adams-Bashforth 3rd-order | 1501 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 5e119ceb68 Jeff*1502 | :varlink:`ALLOW_QHYD_STAGGER_TS` | #undef | include code for quasi-hydrostatic stagger time-step Adams-Bashforth code | dafe4f37ba Jean*1503 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1505.
1504 | :varlink:`EXACT_CONSERV` | #define | include code for âexact conservation" of fluid in free-surface formulation | 1505 | | | (recompute divergence after pressure solver) | 1506 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1507 | :varlink:`NONLIN_FRSURF` | #undef | allow the use of non-linear free-surface formulation; implies that grid-cell thickness (hFactors) varies with time | 1508 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1509 | :varlink:`ALLOW_NONHYDROSTATIC` | #undef | include non-hydrostatic and 3D pressure solver codes | 1510 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1511 | :varlink:`ALLOW_EDDYPSI` | #undef | include GM-like eddy stress in momentum code (untested, not recommended) | 1512 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1513 | :varlink:`ALLOW_CG2D_NSA` | #undef | use non-self-adjoint (NSA) conjugate-gradient solver | 1514 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1515 | :varlink:`ALLOW_SRCG` | #define | include code for single reduction conjugate gradient solver | 1516 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1517 | :varlink:`SOLVE_DIAGONAL_LOWMEMORY` | #undef | low memory footprint (not suitable for AD) choice for implicit solver routines solve_*diagonal.F | 1518 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1519 | :varlink:`SOLVE_DIAGONAL_KINNER` | #undef | choice for implicit solver routines solve_*diagonal.F suitable for AD | 1520 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*1521 94151a9b18 Jeff*1522 .. _default_pkg_list: 1523 ba0b047096 Mart*1524 By default, MITgcm includes several core packages, i.e., these packages are 1525 enabled during :filelink:`genmake2 <tools/genmake2>` execution if a file 1526 ``packages.conf`` is not found. See :numref:`using_packages` for more 1527 information about ``packages.conf``, and see :filelink:`pkg/pkg_groups` for 1528 more information about default packages and package groups. dcaaa42497 Jeff*1529 These default packages are as follows: 1530 1531 - :filelink:`pkg/mom_common` 1532 - :filelink:`pkg/mom_fluxform` 1533 - :filelink:`pkg/mom_vecinv` 1534 - :filelink:`pkg/generic_advdiff` 1535 - :filelink:`pkg/debug` 1536 - :filelink:`pkg/mdsio` 1537 - :filelink:`pkg/rw` 1538 - :filelink:`pkg/monitor` 1539 ba0b047096 Mart*1540 Additional CPP options that affect the model core code are set in files 1541 ``${PKG}_OPTIONS.h`` located in these packages' directories. Similarly, 1542 optional (non-default) packages also include package-specific CPP options that 1543 must be set in files ``${PKG}_OPTIONS.h``. dcaaa42497 Jeff*1544 bcfb652725 Jeff*1545 .. _cpp_eeoptions_doc: 1546 1547 Preprocessor Execution Environment Options 1548 ------------------------------------------ 1549 1550 **Most MITgcm users can skip this section**; many of these flags were 1551 intended for very specific platform environments, and not meant to be changed 1552 for more general environments (an exception being if you are using a coupled 1553 setup, see below). 1554 1555 The file :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` in the 1556 directory :filelink:`eesupp/inc/` contains a number of CPP flags related to 1557 the execution environment where the model will run. Below we describe the 1558 subset of user-editable CPP flags: 1559 1560 .. tabularcolumns:: |\Y{.475}|\Y{.1}|\Y{.45}| 1561 1562 .. table:: 1563 :class: longtable 1564 :name: cpp_eeopt_flags 1565 1566 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1567 | CPP Flag Name | Default | Description | 1568 +===============================================+=========+======================================================================================================================+ 1569 | :varlink:`GLOBAL_SUM_ORDER_TILES` | #define | always cumulate tile local-sum in the same order by applying MPI allreduce to array of tiles | 1570 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1571 | :varlink:`CG2D_SINGLECPU_SUM` | #undef | alternative way of doing global sum on a single CPU to eliminate tiling-dependent roundoff errors | 1572 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1573 | :varlink:`SINGLE_DISK_IO` | #undef | to write STDOUT, STDERR and scratch files from process 0 only | 1574 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1575 | :varlink:`USE_FORTRAN_SCRATCH_FILES` | #undef | flag to turn on old default of opening scratch files with the STATUS='SCRATCH' option | 1576 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1577 | :varlink:`COMPONENT_MODULE` | #undef | control use of communication with other components, i.e., sets component to work with a coupler interface | 1578 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1579 | :varlink:`DISCONNECTED_TILES` | #undef | use disconnected tiles (no exchange between tiles, just fill-in edges assuming locally periodic subdomain) | 1580 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1581 | :varlink:`REAL4_IS_SLOW` | #define | if undefined, force ``_RS`` variables to be declared as real*4 | 1582 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+ 1583 1584 The default setting of ``#define`` :varlink:`GLOBAL_SUM_ORDER_TILES` in 1585 :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` provides a way to 1586 achieve numerically reproducible global sums for a given tile domain 1587 decomposition. As implemented however, this 1588 approach will increase the volume of network traffic in a way that scales 1589 with the total number of tiles. 1590 Profiling has shown that letting the code fall through to a baseline 1591 approach that simply uses 1592 `MPI_Allreduce() <https://www.open-mpi.org/doc/v3.0/man3/MPI_Allreduce.3.php>`_ 1593 can provide significantly improved performance for certain simulations [#]_. 1594 The fall-though approach is activated by ``#undef`` 1595 :varlink:`GLOBAL_SUM_ORDER_TILES`. 1596 1597 In order to get bit-wise reproducible results between different tile domain 1598 decompositions (e.g., single tile on single processor versus multiple tiles 1599 either on single or multiple processors), one can choose to ``#define`` 1600 option :varlink:`CG2D_SINGLECPU_SUM` to use the **MUCH** slower 1601 :filelink:`global_sum_singlecpu.F <eesupp/src/global_sum_singlecpu.F>` 1602 for the key part of MITgcm algorithm :filelink:`CG2D <model/src/cg2d.F>` 1603 that relies on global sum. 1604 This option is not only much slower but also requires a large volume of 1605 communications so it is practically unusable for a large set-up; 1606 furthermore, it does not address reproducibility when global sum is used 1607 outside :filelink:`CG2D <model/src/cg2d.F>`, e.g., in non-hydrostatic simulations. 1608 1609 In a default multi-processor configuration, each process opens and reads its 1610 own set of namelist files and open and writes its own standard output. This can 1611 be slow or even problematic for very large processor counts. Defining the 1612 CPP-flag :varlink:`SINGLE_DISK_IO` suppresses this behavior and lets only the 1613 master process (process 0) read namelist files and write a standard output 1614 stream. This may seem advantageous, because it reduces the amount of seemingly 1615 redundant output, but use this option with caution and only when absolutely 1616 confident that the setup is working since any message (error/warning/print) 1617 from any processor :math:`\ne 0` will be lost. 1618 1619 The way the namelist files are read requires temporary (scratch) files in the 1620 initialization phase. By default, the MITgcm does not use intrinsic Fortran 1621 scratch files (``STATUS='scratch'``) because they can lead to conflicts in 1622 multi-processor simulations on some HPC-platforms, when the processors do not 1623 open scratch files with reserved names. However, the implemented default scheme 1624 for the scratch files can be slow for large processor counts. If this is a 1625 problem in a given configuration, defining the CPP-flag 1626 :varlink:`USE_FORTRAN_SCRATCH_FILES` may help by making the code use the 1627 intrinsic Fortran scratch files. 1628 1629 The CPP-flag :varlink:`COMPONENT_MODULE` needs to be set to ``#define`` only for 1630 builds in which the MITgcm executable (for either an oceanic or atmospheric 1631 simulation) is configured to communicate with a coupler. 1632 This coupler can be a specially configured build of MITgcm itself; 1633 see, for example, verification experiment `cpl_aim+ocn 1634 <https://github.com/MITgcm/MITgcm/tree/master/verification/cpl_aim+ocn>`_. 1635 1636 The CPP-flag :varlink:`DISCONNECTED_TILES` should not be ``#define`` 1637 unless one wants to run simultaneously several small, single-tile ensemble 1638 members from a single process, as each tile will be disconnected from the others 1639 and considered locally as a doubly periodic patch. 1640 1641 .. 1642 should reference the to-be-written section about _RS, _RL within chapter 6 1643 1644 MITgcm ``_RS`` variables are forced to be declared as 1645 ``real*4`` if CPP-flag :varlink:`REAL4_IS_SLOW` to is set to ``#undef`` 1646 in :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` 1647 (``_RS`` is a macro used in declaring real variables that, in principle, 1648 do not require double precision). However, this option is not recommended 1649 except for computational benchmarking or for testing the trade-off between memory 1650 footprint and model precision. And even for these specialized tests, there is no need 1651 to edit :filelink:`CPP_EEOPTIONS.h <eesupp/inc/CPP_EEOPTIONS.h>` 1652 since this feature can be activated using the :filelink:`genmake2 <tools/genmake2>` 1653 command line option ``-use_r4``, as done in some regression tests 1654 (see testing `results <https://mitgcm.org/testing-summary>`_ 1655 page tests with optfile suffix ``.use_r4``). 1656 1657 .. [#] One example is the llc_540 case located at 1658 https://github.com/MITgcm-contrib/llc_hires/tree/master/llc_540. This case 1659 was run on the Pleiades computer for 20 simulated days using 767 and 2919 1660 MPI ranks. At 767 ranks, the fall-through approach provided a throughput of 1661 to 799.0 simulated days per calendar day (dd/d) while the default approach 1662 gave 781.0. The profiler showed the speedup was directly attributable to 1663 spending less time in MPI_Allreduce. The volume of memory traffic associated 1664 with MPI_Allreduce dropped by 3 orders (22.456T -> 32.596G). At 2819 MPI 1665 ranks the fall-through approach gave a throughput of 1300 dd/d while the 1666 default approach gave 800.0 dd/d. Put another way, this case did not scale 1667 at all from 767p to 2819p unless the fall-though approach was utilized. The 1668 profiler showed the speedup was directly attributable to spending less time 1669 in MPI_Allreduce. The volume of memory traffic associated with MPI_Allreduce 1670 dropped by 3 orders (303.70T ->121.08G ). dcaaa42497 Jeff*1671 af61fa61c7 Jeff*1672 .. _customize_model: 1673 dcaaa42497 Jeff*1674 Customizing the Model Configuration - Runtime Parameters 1675 ======================================================== 69e7157c80 Jeff*1676 1677 When you are ready to run the model in the configuration you want, the ba0b047096 Mart*1678 most straightforward approach is to use and adapt the setup of a tutorial or 1679 verification experiment (described in :numref:`chap_modelExamples`) that is the 1680 closest to your configuration. Then, the amount of setup will be minimized. 1681 In this section, we document the complete list of MITgcm model namelist runtime dcaaa42497 Jeff*1682 parameters set in file ``data``, which needs to be located in the 516b08a580 jm-c 1683 directory where you will run the model. dcaaa42497 Jeff*1684 Model parameters are defined and ba0b047096 Mart*1685 declared in the file :filelink:`PARAMS.h <model/inc/PARAMS.h>` and their 1686 default values are generally set in the routine 1687 :filelink:`set_defaults.F <model/src/set_defaults.F>`, otherwise 1688 when initialized in the routine :filelink:`ini_parms.F <model/src/ini_parms.F>`.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1690.
1689 :numref:`eedata_parms` documents the âexecution environmentâ namelist parameters dcaaa42497 Jeff*1690 in file ``eedata``, which must also reside in the current run directory. ba0b047096 Mart*1691 Note that runtime parameters used by (non-default) MITgcm packages are not 1692 documented here but rather in :numref:`packagesI` 1693 and :numref:`outp_pack`, and prescribed in package-specific ``data.${pkg}`` 1694 namelist files which are read in via package-specific 1695 ``${pkg}_readparms.F`` where ``${pkg}`` is the package name dcaaa42497 Jeff*1696 (see :numref:`using_packages`). 69e7157c80 Jeff*1697 dcaaa42497 Jeff*1698 In what follows, model parameters are grouped into categories related to ba0b047096 Mart*1699 configuration/computational domain, algorithmic parameters, equations solved 1700 in the model, parameters related to model forcing, and simulation controls. 1701 The tables below specify the namelist parameter name, the namelist parameter 1702 group in ``data`` (and ``eedata`` in :numref:`eedata_parms`), the default 1703 value, and a short description of its function. Runtime parameters that 1704 require **non-default** CPP options to be set prior to compilation 1705 (see :numref:`customize_compilation`) for proper use are noted. dcaaa42497 Jeff*1706 516b08a580 jm-c 1707 Parameters: Configuration, Computational Domain, Geometry, and Time-Discretization dcaaa42497 Jeff*1708 ---------------------------------------------------------------------------------- 1709 1710 .. _model_config_parms: 1711 1712 Model Configuration 1713 ~~~~~~~~~~~~~~~~~~~ 69e7157c80 Jeff*1714 ba0b047096 Mart*1715 :varlink:`buoyancyRelation` is set to ``OCEANIC`` by default, which employes a 1716 :math:`z`-coordinate vertical axis. To simulate an ocean using pressure 1717 coordinates in the vertical, set it to ``OCEANICP``. For atmospheric 1718 simulations, :varlink:`buoyancyRelation` needs to be set to ``ATMOSPHERIC``, 1719 which also uses pressure as the vertical coordinate. 1720 The default model configuration is hydrostatic; to run a non-hydrostatic 1721 simulation, set the logical variable :varlink:`nonHydrostatic` to ``.TRUE.``. 69e7157c80 Jeff*1722 dcaaa42497 Jeff*1723 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 69e7157c80 Jeff*1724 dcaaa42497 Jeff*1725 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1726 | Parameter | Group | Default | Description | 1727 +========================================+===========+==================================================+=========================================================================================================+ 1728 | :varlink:`buoyancyRelation` | PARM01 | OCEANIC | buoyancy relation (``OCEANIC``, ``OCEANICP``, or ``ATMOSPHERIC``) | 1729 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1730 | :varlink:`quasiHydrostatic` | PARM01 | FALSE | quasi-hydrostatic formulation on/off flag | 1731 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1732 | :varlink:`rhoRefFile` | PARM01 | :kbd:`' '` | filename for reference density profile (kg/m\ :sup:`3`); activates anelastic form of model | 1733 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1734 | :varlink:`nonHydrostatic` | PARM01 | FALSE | non-hydrostatic formulation on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC` | 1735 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 69e7157c80 Jeff*1736 1737 Grid dcaaa42497 Jeff*1738 ~~~~ 1739 1740 Four different grids are available: Cartesian, spherical polar, cylindrical, and 1741 curvilinear (which includes the cubed sphere). The grid is set 1742 through the logical variables :varlink:`usingCartesianGrid`, 1743 :varlink:`usingSphericalPolarGrid`, :varlink:`usingCylindricalGrid`, ba0b047096 Mart*1744 and :varlink:`usingCurvilinearGrid`. Note that the cylindrical grid is designed 1745 for modeling a rotating tank, so that :math:`x` is the azimuthual direction, 1746 :math:`y` is the radial direction, and :math:`r` is vertical coordinate 1747 (see tutorial :ref:`rotating tank <sec_eg_tank>`). dcaaa42497 Jeff*1748 1749 The variable :varlink:`xgOrigin` sets the position of the western ba0b047096 Mart*1750 most gridcell face in the :math:`x` dimension (Cartesian, meters; spherical and 1751 cyclindrical, degrees). For a Cartesian or spherical grid, the southern boundary 1752 is defined through the variable :varlink:`ygOrigin` which corresponds to the 1753 latitude of the southern most gridcell face (Cartesian, meters; spherical, 1754 degrees). For a cyclindrical grid, a positive :varlink:`ygOrigin` (m) adds an 1755 inner cylindrical boundary at the center of the tank. The resolution 1756 along the :math:`x` and :math:`y` directions is controlled by the 1-D arrays 1757 :varlink:`delX` (meters for a Cartesian grid, degrees otherwise) 1758 and :varlink:`delY` (meters for Cartesian and cyclindrical grids, degrees 1759 spherical). On a spherical polar grid, you might decide to set the variable 1760 :varlink:`cosPower` which is set to 0 by default and which represents :math:`n` 1761 in :math:`(\cos\varphi)^n`, the power of cosine of latitude to dcaaa42497 Jeff*1762 multiply horizontal viscosity and tracer diffusivity. 83cdbd2346 Jeff*1763 The vertical grid spacing is set through the 1-D array ba0b047096 Mart*1764 :varlink:`delR` (:math:`z`-coordinates: in meters; :math:`p`-coordinates, 1765 in Pa). Using a curvilinear grid requires complete specification of all 1766 horizontal MITgcm grid variables, either through a default filename (link to 1767 new doc section) or as specified by :varlink:`horizGridFile`. dcaaa42497 Jeff*1768 1769 The variable :varlink:`seaLev_Z` represents the standard 1770 position of sea level, in meters. This is typically set to 0 m ba0b047096 Mart*1771 for the ocean (default value). If instead pressure is used as the vertical 1772 coordinate, the pressure at the top (of the atmosphere or ocean) is set through 1773 :varlink:`top_Pres`, typically 0 Pa. As such, these variables are analogous to 1774 :varlink:`xgOrigin` and :varlink:`ygOrigin` to define the vertical grid axis. 1775 But they also are used for a second purpose: in a :math:`z`-coordinate setup, 1776 :varlink:`top_Pres` sets a reference top pressure (required in a non-linear 1777 equation of state computation, for example); note that 1 bar 1778 (i.e., typical Earth atmospheric sea-level pressure) is added already, so the 1779 default is 0 Pa. Similarly, for a :math:`p`-coordinate setup, 1780 :varlink:`seaLev_Z` is used to set a reference geopotential (after gravity 1781 scaling) at the top of the ocean or bottom of the atmosphere. dcaaa42497 Jeff*1782 1783 .. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}| 1784 a332812c22 Jeff*1785 .. table:: 1786 :class: longtable 1787 1788 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1789 | Parameter | Group | Default | Description | 1790 +========================================+===========+==================================================+=========================================================================================================+ 1791 | :varlink:`usingCartesianGrid` | PARM04 | TRUE | use Cartesian grid/coordinates on/off flag | 1792 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1793 | :varlink:`usingSphericalPolarGrid` | PARM04 | FALSE | use spherical grid/coordinates on/off flag | 1794 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1795 | :varlink:`usingCylindricalGrid` | PARM04 | FALSE | use cylindrical grid/coordinates on/off flag | 1796 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1797 | :varlink:`usingCurvilinearGrid` | PARM04 | FALSE | use curvilinear grid/coordinates on/off flag | 1798 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1799 | :varlink:`xgOrigin` | PARM04 | 0.0 | west edge :math:`x`-axis origin (Cartesian: m; spherical and cyclindrical: degrees longitude) | 1800 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1801 | :varlink:`ygOrigin` | PARM04 | 0.0 | South edge :math:`y`-axis origin (Cartesian and cyclindrical: m; spherical: degrees latitude) | 1802 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1803 | :varlink:`dxSpacing` | PARM04 | unset | :math:`x`-axis uniform grid spacing, separation between cell faces | 1804 | | | | (Cartesian: m; spherical and cyclindrical: degrees) | 1805 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1806 | :varlink:`delX` | PARM04 | :varlink:`dxSpacing` | 1D array of :math:`x`-axis grid spacing, separation between cell faces | 1807 | | | | (Cartesian: m; spherical and cyclindrical: degrees) | 1808 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1809 | :varlink:`delXFile` | PARM04 | :kbd:`' '` | filename containing 1D array of :math:`x`-axis grid spacing | 1810 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1811 | :varlink:`dySpacing` | PARM04 | unset | :math:`y`-axis uniform grid spacing, separation between cell faces | 1812 | | | | (Cartesian and cyclindrical: m; spherical: degrees) | 1813 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1814 | :varlink:`delY` | PARM04 | :varlink:`dySpacing` | 1D array of :math:`x`-axis grid spacing, separation between cell faces | 1815 | | | | (Cartesian and cyclindrical: m; spherical: degrees) | 1816 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1817 | :varlink:`delYFile` | PARM04 | :kbd:`' '` | filename containing 1D array of :math:`y`-axis grid spacing | 1818 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1819 | :varlink:`cosPower` | PARM01 | 0.0 | power law :math:`n` in :math:`(\cos\varphi)^n` factor for horizontal (harmonic or biharmonic) | 1820 | | | | viscosity and tracer diffusivity (spherical polar) | 1821 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1822 | :varlink:`delR` | PARM04 | computed using delRc | vertical grid spacing 1D array ([:math:`r`] unit) | 1823 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1824 | :varlink:`delRc` | PARM04 | computed using delR | vertical cell center spacing 1D array ([:math:`r`] unit) | 1825 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1826 | :varlink:`delRFile` | PARM04 | :kbd:`' '` | filename for vertical grid spacing 1D array ([:math:`r`] unit) | 1827 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1828 | :varlink:`delRcFile` | PARM04 | :kbd:`' '` | filename for vertical cell center spacing 1D array ([:math:`r`] unit) | 1829 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1830 | :varlink:`rSphere` | PARM04 | 6.37E+06 | radius of sphere for spherical polar or curvilinear grid (m) | 1831 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1832 | :varlink:`seaLev_Z` | PARM04 | 0.0 | reference height of sea level (m) | 1833 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1834 | :varlink:`top_Pres` | PARM04 | 0.0 | top pressure (:math:`p`-coordinates) or top reference pressure (:math:`z`-coordinates) (Pa) | 1835 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1836 | :varlink:`selectFindRoSurf` | PARM01 | 0 | select method to determine surface reference pressure from orography (atmos.-only) | 1837 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1838 | :varlink:`horizGridFile` | PARM04 | :kbd:`' '` | filename containing full set of horizontal grid variables (curvilinear) | 1839 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1840 | :varlink:`radius_fromHorizGrid` | PARM04 | :varlink:`rSphere` | radius of sphere used in input curvilinear horizontal grid file (m) | 1841 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1842 | :varlink:`phiEuler` | PARM04 | 0.0 | Euler angle, rotation about original :math:`z`-axis (spherical polar) (degrees) | 1843 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1844 | :varlink:`thetaEuler` | PARM04 | 0.0 | Euler angle, rotation about new :math:`x`-axis (spherical polar) (degrees) | 1845 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1846 | :varlink:`psiEuler` | PARM04 | 0.0 | Euler angle, rotation about new :math:`z`-axis (spherical polar) (degrees) | 1847 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*1848 9c8516d9da Jeff*1849 .. _parms_topo: 1850 69e7157c80 Jeff*1851 Topography - Full and Partial Cells dcaaa42497 Jeff*1852 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1853 ba0b047096 Mart*1854 For the ocean, the topography is read from a file that contains a 1855 2-D(:math:`x,y`) map of bathymetry, in meters for :math:`z`-coordinates, in 1856 pascals for :math:`p`-coordinates. The bathymetry is specified by entering the 1857 vertical position of the ocean floor relative to the surface, so by convention** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1859.
1858 in :math:`z`-coordinates bathymetry is specified as negative numbers (âdepthâ 1859 is defined as positive-definite) whereas in :math:`p`-coordinates dcaaa42497 Jeff*1860 bathymetry data is positive. The file name is represented by the variable ba0b047096 Mart*1861 :varlink:`bathyFile`. See our introductory tutorial setup :numref:`sec_eg_baro` 1862 for additional details on the file format. Note no changes are required in the 1863 model source code to represent enclosed, periodic, or double periodic dcaaa42497 Jeff*1864 domains: periodicity is assumed by default and is suppressed by 1865 setting the depths to 0 m for the cells at the limits of the 1866 computational domain. 1867 1868 To use the partial cell capability, the variable :varlink:`hFacMin` needs 1869 to be set to a value between 0.0 and 1.0 (it is set to 1.0 by default) 1870 corresponding to the minimum fractional size of a gridcell. For 1871 example, if a gridcell is 500 m thick and :varlink:`hFacMin` is set to ba0b047096 Mart*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1873.
1872 0.1, the minimum thickness for a âthin-cellâ for this specific gridcell is 50 m. 1873 Thus, if the specified bathymetry depth were to fall exactly 1874 in the middle of this 500m thick gridcell, the initial model variable 1875 :varlink:`hFacC`\ (:math:`x,y,r`) would be set to 0.5. 1876 If the specified bathymetry depth fell within the top 50m of this gridcell 1877 (i.e., less than :varlink:`hFacMin`), the model bathymetry would snap to the 1878 nearest legal value (i.e., initial :varlink:`hFacC`\ (:math:`x,y,r`) would be 1879 equal to 0.0 or 0.1 depending if the depth was within 0-25 m or 25-50 m, 1880 respectively). Also note while specified bathymetry bottom depths (or 1881 pressures) need not coincide with the model's levels as deduced from 1882 :varlink:`delR`, any depth falling below the model's defined vertical axis is 1883 truncated. dcaaa42497 Jeff*1884 1885 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 1886 a332812c22 Jeff*1887 .. table:: 1888 :class: longtable de49ce6f4b Ed D*1889 a332812c22 Jeff*1890 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1891 | Parameter | Group | Default | Description | 1892 +========================================+===========+==================================================+=========================================================================================================+ 1893 | :varlink:`bathyFile` | PARM05 | :kbd:`' '` | filename for 2D bathymetry (ocean) (:math:`z`-coor.: m, negative; :math:`p`-coor.: Pa, positive) | 1894 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1895 | :varlink:`topoFile` | PARM05 | :kbd:`' '` | filename for 2D surface topography (atmosphere) (m) | 1896 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1898.
1897 | :varlink:`addWwallFile` | PARM05 | :kbd:`' '` | filename for 2D western cell-edge âthin-wallâ | 1898 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1900.
1899 | :varlink:`addSwallFile` | PARM05 | :kbd:`' '` | filename for 2D southern cell-edge âthin-wallâ | 1900 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1901 | :varlink:`hFacMin` | PARM01 | 1.0E+00 | minimum fraction size of a cell | 1902 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1903 | :varlink:`hFacMinDr` | PARM01 | 1.0E+00 | minimum dimensional size of a cell ([:math:`r`] unit) | 1904 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1905 | :varlink:`hFacInf` | PARM01 | 2.0E-01 | lower threshold fraction for surface cell; | 1906 | | | | for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>` | 1907 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1908 | :varlink:`hFacSup` | PARM01 | 2.0E+00 | upper threshold fraction for surface cell; | 1909 | | | | for non-linear free surface, only see parameter :ref:`nonlinFreeSurf <free_surface_parms>` | 1910 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1911 | :varlink:`useMin4hFacEdges` | PARM04 | FALSE | set :varlink:`hFacW`, :varlink:`hFacS` as minimum of adjacent :varlink:`hFacC` on/off flag | 1912 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1913 | :varlink:`pCellMix_select` | PARM04 | 0 | option/factor to enhance mixing at the surface or bottom (0- 99) | 1914 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1915 | :varlink:`pCellMix_maxFac` | PARM04 | 1.0E+04 | maximum enhanced mixing factor for too thin partial-cell (non-dim.) | 1916 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1917 | :varlink:`pCellMix_delR` | PARM04 | 0.0 | thickness criteria for too thin partial-cell ([:math:`r`] unit) | 1918 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*1919 1920 Physical Constants 1921 ~~~~~~~~~~~~~~~~~~ 1922 1923 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 1924 1925 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1926 | Parameter | Group | Default | Description | 1927 +========================================+===========+==================================================+=========================================================================================================+ 1928 | :varlink:`rhoConst` | PARM01 | :varlink:`rhoNil` | vertically constant reference density (Boussinesq) (kg/m\ :sup:`3`) | 1929 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1930 | :varlink:`gravity` | PARM01 | 9.81E+00 | gravitational acceleration (m/s\ :sup:`2`) | 1931 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 516b08a580 jm-c 1932 | :varlink:`gravityFile` | PARM01 | :kbd:`' '` | filename for 1D gravity vertical profile (m/s\ :sup:`2`) | dcaaa42497 Jeff*1933 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1934 | :varlink:`gBaro` | PARM01 | :varlink:`gravity` | gravity constant in barotropic equation (m/s\ :sup:`2`) | 1935 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1936 1937 Rotation 1938 ~~~~~~~~ 1939 1940 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}| 1941 1942 For a Cartesian or cylindical grid, the Coriolis parameter :math:`f` is set ba0b047096 Mart*1943 through the variables :varlink:`f0` (in s\ :sup:`--1`) and :varlink:`beta` 1944 (:math:`\frac{\partial f}{ \partial y}`; in m\ :sup:`--1`\ s\ :sup:`--1`), 1945 which corresponds to a Coriolis parameter :math:`f = f_o + \beta y` 1946 (the so-called :math:`\beta`\ -plane). dcaaa42497 Jeff*1947 1948 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1949 | Parameter | Group | Default | Description | 1950 +========================================+===========+==================================================+=========================================================================================================+ 1951 | :varlink:`rotationPeriod` | PARM01 | 8.6164E+04 | rotation period (s) | 1952 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1953 | :varlink:`omega` | PARM01 | :math:`2\pi/`\ :varlink:`rotationPeriod` | angular velocity (rad/s) | 1954 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*1955 | :varlink:`selectCoriMap` | PARM01 | depends on grid | Coriolis map options | 1956 | | | (Cartesian and cylindrical=1, | | 1957 | | | spherical and curvilinear=2) | - 0: f-plane | 1958 | | | | - 1: beta-plane | 1959 | | | | - 2: spherical Coriolis (:math:`=2\Omega\sin{\varphi}`) | 1960 | | | | - 3: read 2D field from file | dcaaa42497 Jeff*1961 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*1962 | :varlink:`f0` | PARM01 | 1.0E-04 | reference Coriolis parameter (Cartesian or cylindrical grid) (1/s) | dcaaa42497 Jeff*1963 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*1964 | :varlink:`beta` | PARM01 | 1.0E-11 | :math:`\beta` (Cartesian or cylindrical grid) (m\ :sup:`--1`\ s\ :sup:`--1`) | dcaaa42497 Jeff*1965 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*1966 | :varlink:`fPrime` | PARM01 | 0.0 | :math:`2 \Omega \cos{\phi}` parameter (Cartesian or cylindical grid) (1/s); i.e., for | dcaaa42497 Jeff*1967 | | | | :math:`\cos{\varphi}` Coriolis terms from horizontal component of rotation vector | 1968 | | | | (also sometimes referred to as reciprocal Coriolis parm.) | 1969 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1970 1971 .. _free_surface_parms: 1972 1973 Free Surface 1974 ~~~~~~~~~~~~ 1975 ba0b047096 Mart*1976 The logical variables :varlink:`rigidLid` and :varlink:`implicitFreeSurface` 1977 specify your choice for ocean upper boundary (or lower boundary if using 1978 :math:`p`-coordinates); set one to ``.TRUE.`` and the other to ``.FALSE.``. 1979 These settings affect the calculations of surface pressure (for the ocean) or dcaaa42497 Jeff*1980 surface geopotential (for the atmosphere); see :numref:`parms-main_algorithm`. 1981 1982 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}| 1983 a332812c22 Jeff*1984 .. table:: 1985 :class: longtable 1986 1987 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1988 | Parameter | Group | Default | Description | 1989 +========================================+===========+==================================================+=========================================================================================================+ 1990 | :varlink:`implicitFreeSurface` | PARM01 | TRUE | implicit free surface on/off flag | 1991 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1992 | :varlink:`rigidLid` | PARM01 | FALSE | rigid lid on/off flag | 1993 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1994 | :varlink:`useRealFreshWaterFlux` | PARM01 | FALSE | use true E-P-R freshwater flux (changes free surface/sea level) on/off flag | 1995 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1996 | :varlink:`implicSurfPress` | PARM01 | 1.0E+00 | implicit fraction of the surface pressure gradient (0-1) | 1997 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 1998 | :varlink:`implicDiv2Dflow` | PARM01 | 1.0E+00 | implicit fraction of the barotropic flow divergence (0-1) | 1999 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2000 | :varlink:`implicitNHPress` | PARM01 | :varlink:`implicSurfPress` | implicit fraction of the non-hydrostatic pressure gradient (0-1); | 2001 | | | | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` | 2002 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2003 | :varlink:`nonlinFreeSurf` | PARM01 | 0 | non-linear free surface options (-1,0,1,2,3; see :numref:`nonlinFreeSurf-flags`); | 2004 | | | | requires #define :varlink:`NONLIN_FRSURF` | 2005 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2006 | :varlink:`select_rStar` | PARM01 | 0 | vertical coordinate option | 2007 | | | | | 2008 | | | | - 0: use r | 2009 | | | | - >0: use :math:`r^*` | 2010 | | | | | 2011 | | | | see :numref:`nonlinFreeSurf-flags`; requires #define :varlink:`NONLIN_FRSURF` | 2012 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2013 | :varlink:`selectNHfreeSurf` | PARM01 | 0 | non-hydrostatic free surface formulation option | 2014 | | | | |** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2016.
2015 | | | | - 0: donât use | 2016 | | | | - >0: use | 2017 | | | | | 2018 | | | | requires non-hydrostatic formulation, see parameter :ref:`nonHydrostatic <model_config_parms>` | 2019 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2020 | :varlink:`exactConserv` | PARM01 | FALSE | exact total volume conservation (recompute divergence after pressure solver) on/off flag | 2021 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*2022 69e7157c80 Jeff*2023 Time-Discretization dcaaa42497 Jeff*2024 ~~~~~~~~~~~~~~~~~~~ 2025 2026 The time steps are set through the real variables :varlink:`deltaTMom` and 2027 :varlink:`deltaTtracer` (in seconds) which represent the time step for the ba0b047096 Mart*2028 momentum and tracer equations, respectively (or you can prescribe a single** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2030.
2029 time step value for all parameters using :varlink:`deltaT`). The model âclockâ 2030 is defined by the variable :varlink:`deltaTClock` (in seconds) dcaaa42497 Jeff*2031 which determines the I/O frequencies and is used in tagging output. 2032 Time in the model is thus computed as: 2033 ba0b047096 Mart*2034 | model time = :varlink:`baseTime` + iteration number * :varlink:`deltaTClock` dcaaa42497 Jeff*2035 2036 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 2037 2038 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2039 | Parameter | Group | Default | Description | 2040 +========================================+===========+==================================================+=========================================================================================================+ 2041 | :varlink:`deltaT` | PARM03 | 0.0 | default value used for model time step parameters (s) | 2042 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2043 | :varlink:`deltaTClock` | PARM03 | :varlink:`deltaT` | timestep used for model clock (s): used for I/O frequency and tagging output and checkpoints | 2044 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2045 | :varlink:`deltaTmom` | PARM03 | :varlink:`deltaT` | momentum equation timestep (s) | 2046 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2047 | :varlink:`deltaTtracer` | PARM03 | :varlink:`deltaT` | tracer equation timestep (s) | 2048 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2049 | :varlink:`dTtracerLev` | PARM03 | :varlink:`deltaTtracer` | tracer equation timestep specified at each vertical level (s) | 2050 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2051 | :varlink:`deltaTfreesurf` | PARM03 | :varlink:`deltaTmom` | free-surface equation timestep (s) | 2052 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2053 | :varlink:`baseTime` | PARM03 | 0.0 | model base time corresponding to iteration 0 (s) | 2054 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2055 2056 .. _parms-main_algorithm: 2057 2058 Parameters: Main Algorithmic Parameters 2059 --------------------------------------- 2060 2061 Pressure Solver 2062 ~~~~~~~~~~~~~~~ 2063 2064 By default, a hydrostatic ba0b047096 Mart*2065 simulation is assumed and a 2-D elliptic equation is used to invert the 2066 pressure field. If using a non-hydrostatic configuration, the pressure field is 2067 inverted through a 3-D elliptic equation (note this capability is not yet 2068 available for the atmosphere). The parameters controlling the behavior of the dcaaa42497 Jeff*2069 elliptic solvers are the variables :varlink:`cg2dMaxIters` and 83cdbd2346 Jeff*2070 :varlink:`cg2dTargetResidual` for the 2-D case and :varlink:`cg3dMaxIters` and 2071 :varlink:`cg3dTargetResidual` for the 3-D case. dcaaa42497 Jeff*2072 2073 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}| 2074 a332812c22 Jeff*2075 .. table:: 2076 :class: longtable 2077 2078 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2079 | Parameter | Group | Default | Description | 2080 +========================================+===========+==================================================+=========================================================================================================+ 2081 | :varlink:`cg2dMaxIters` | PARM02 | 150 | upper limit on 2D conjugate gradient solver iterations | 2082 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2083 | :varlink:`cg2dTargetResidual` | PARM02 | 1.0E-07 | 2D conjugate gradient target residual (non-dim. due to RHS normalization ) | 2084 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2085 | :varlink:`cg2dTargetResWunit` | PARM02 | -1.0E+00 | 2D conjugate gradient target residual (:math:`\dot{r}` units); | 2086 | | | | <0: use RHS normalization, i.e., :varlink:`cg2dTargetResidual` instead | 2087 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2088 | :varlink:`cg2dPreCondFreq` | PARM02 | 1 | frequency (in number of iterations) for updating cg2d pre-conditioner; | 2089 | | | | for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>` | 2090 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2091 | :varlink:`cg2dUseMinResSol` | PARM02 | 0 unless flat-bottom, Cartesian | - 0: use last-iteration/converged cg2d solution | 2092 | | | | - 1: use solver minimum-residual solution | 2093 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2094 | :varlink:`cg3dMaxIters` | PARM02 | 150 | upper limit on 3D conjugate gradient solver iterations; requires #define :varlink:`ALLOW_NONHYDROSTATIC`| 2095 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2096 | :varlink:`cg3dTargetResidual` | PARM02 | 1.0E-07 | 3D conjugate gradient target residual (non-dim. due to RHS normalization ); | 2097 | | | | requires #define :varlink:`ALLOW_NONHYDROSTATIC` | 2098 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ e6e223b277 Jean*2099 | :varlink:`cg3dTargetResWunit` | PARM02 | -1.0E+00 | 3D conjugate gradient target residual (:math:`\dot{r}` units); | 2100 | | | | <0: use RHS normalization, i.e., :varlink:`cg3dTargetResidual` instead | 2101 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*2102 | :varlink:`useSRCGSolver` | PARM02 | FALSE | use conjugate gradient solver with single reduction (single call of mpi_allreduce) | 2103 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2104 | :varlink:`printResidualFreq` | PARM02 | 1 unless :varlink:`debugLevel` >4 | frequency (in number of iterations) of printing conjugate gradient residual | 2105 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2106 | :varlink:`integr_GeoPot` | PARM01 | 2 | select method to integrate geopotential | 2107 | | | | | 2108 | | | | - 1: finite volume | 2109 | | | | - :math:`\neq`\ 1: finite difference | 2110 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2111 | :varlink:`uniformLin_PhiSurf` | PARM01 | TRUE | use uniform :math:`b_s` relation for :math:`\phi_s` on/off flag | 2112 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2114.
2113 | :varlink:`deepAtmosphere` | PARM04 | FALSE | donât make the thin shell/shallow water approximation | 2114 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2115 | :varlink:`nh_Am2` | PARM01 | 1.0E+00 | non-hydrostatic terms scaling factor; requires #define :varlink:`ALLOW_NONHYDROSTATIC` | 2116 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*2117 2118 Time-Stepping Algorithm 2119 ~~~~~~~~~~~~~~~~~~~~~~~ 2120 2121 The Adams-Bashforth stabilizing parameter is set through the 2122 variable :varlink:`abEps` (dimensionless). The stagger baroclinic time 2123 stepping algorithm can be activated by setting the logical variable 2124 :varlink:`staggerTimeStep` to ``.TRUE.``. 2125 2126 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 2127 2128 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2129 | Parameter | Group | Default | Description | 2130 +========================================+===========+==================================================+=========================================================================================================+ 2131 | :varlink:`abEps` | PARM03 | 1.0E-02 | Adams-Bashforth-2 stabilizing weight (non-dim.) | 2132 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2133 | :varlink:`alph_AB` | PARM03 | 0.5E+00 | Adams-Bashforth-3 primary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` | 2134 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2135 | :varlink:`beta_AB` | PARM03 | 5/12 | Adams-Bashforth-3 secondary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` | 2136 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2137 | :varlink:`staggerTimeStep` | PARM01 | FALSE | use staggered time stepping (thermodynamic vs. flow variables) on/off flag | 2138 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2139 | :varlink:`multiDimAdvection` | PARM01 | TRUE | use multi-dim. advection algorithm in schemes where non multi-dim. is possible on/off flag | 2140 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2141 | :varlink:`implicitIntGravWave` | PARM01 | FALSE | treat internal gravity waves implicitly on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC` | 2142 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2143 69e7157c80 Jeff*2144 .. _parms-eos: 2145 2146 Parameters: Equation of State 2147 ----------------------------- 2148 dcaaa42497 Jeff*2149 The form of the equation of state is controlled by the model configuration 516b08a580 jm-c 2150 and :varlink:`eosType`. dcaaa42497 Jeff*2151 516b08a580 jm-c 2152 For the atmosphere, :varlink:`eosType` must be set to ``IDEALGAS``. dcaaa42497 Jeff*2153 2154 For the ocean, several forms of the equation of state are 2155 available: 2156 2157 - For a linear approximation, set :varlink:`eosType` to ``LINEAR``), 2158 and you will need to specify the thermal 2159 and haline expansion coefficients, represented by the variables ba0b047096 Mart*2160 :varlink:`tAlpha` (in K\ :sup:`--1`) and :varlink:`sBeta` 2161 (in (g/kg)\ :sup:`--1`). dcaaa42497 Jeff*2162 Because the model equations are written in terms of 2163 perturbations, a reference thermodynamic state needs to be specified. ba0b047096 Mart*2164 This is done through the 1-D arrays :varlink:`tRef` and :varlink:`sRef`. 2165 :varlink:`tRef` specifies the reference potential temperature profile (in 2166 :sup:`o`\ C for the ocean and K for the atmosphere) starting 2167 from the level k=1. Similarly, :varlink:`sRef` specifies the reference 2168 salinity profile (in g/kg) for the ocean or the reference specific dcaaa42497 Jeff*2169 humidity profile (in g/kg) for the atmosphere. 2170 2171 - MITgcm offers several approximations to the full (oceanic) non-linear equation 2172 of state that can be selected as :varlink:`eosType`: 2173 516b08a580 jm-c 2174 ``'POLYNOMIAL'``: ba0b047096 Mart*2175 This approximation is based on the Knudsen formula (see Bryan and Cox 1972 2176 :cite:`bryan:72`). For this option you need to generate a file of polynomial dcaaa42497 Jeff*2177 coefficients called ``POLY3.COEFFS``. To do this, use the program ba0b047096 Mart*2178 :filelink:`utils/knudsen2/knudsen2.f` under the model tree (a ``Makefile`` 2179 is available in the same directory; you will need to edit the number and 2180 the values of the vertical levels in 2181 :filelink:`knudsen2.f <utils/knudsen2/knudsen2.f>` dcaaa42497 Jeff*2182 so that they match those of your configuration). 2183** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2185.
2184 ``âUNESCOâ``: 2185 The UNESCO equation of state formula (IES80) of Fofonoff and Millard (1983) 69e7157c80 Jeff*2186 :cite:`fofonoff:83`. This equation of state assumes dcaaa42497 Jeff*2187 in-situ temperature, which is not a model variable; **its use is 2188 therefore discouraged**. 69e7157c80 Jeff*2189 dcaaa42497 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2191.
2190 ``âJMD95Zâ``: 69e7157c80 Jeff*2191 A modified UNESCO formula by Jackett and McDougall (1995) 2192 :cite:`jackett:95`, which uses the model variable** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2194.
2193 potential temperature as input. The âZâ indicates that this 2194 equation of state uses a horizontally and temporally constant 2195 pressure :math:`p_{0}=-g\rho_{0}z`. 2196 dcaaa42497 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2198.
2197 ``âJMD95Pâ``: 69e7157c80 Jeff*2198 A modified UNESCO formula by Jackett and McDougall (1995) 2199 :cite:`jackett:95`, which uses the model variable** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2201.
2200 potential temperature as input. The âPâ indicates that this 2201 equation of state uses the actual hydrostatic pressure of the last 2202 time step. Lagging the pressure in this way requires an additional 2203 pickup file for restarts. 2204 dcaaa42497 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2206.
2205 ``âMDJWFâ``: 2206 A more accurate and less expensive equation of state than UNESCO by 2207 McDougall et al. (2003) :cite:`mcdougall:03`, also using the model variable 2208 potential temperature as input. It also requires 69e7157c80 Jeff*2209 lagging the pressure and therefore an additional pickup file for 2210 restarts. 2211 dcaaa42497 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2213.
2212 ``âTEOS10â``: ba0b047096 Mart*2213 TEOS-10 is based on a Gibbs function formulation from which all 2214 thermodynamic properties of seawater (density, enthalpy, entropy sound 2215 speed, etc.) can be derived in a thermodynamically consistent manner; 2216 see http://www.teos-10.org. See IOC et al. (2010) :cite:`ioc:10`, McDougall 2217 and Parker (2011) :cite:`mcdougall:11`, and Roquet et al. (2015) 2218 :cite:`roquet:15` for implementation details. 2219 It also requires lagging the pressure and therefore an additional pickup 2220 file for restarts. Note at this time a full implementation of TEOS10 (i.e., 2221 ocean variables of conservative temperature and practical salinity, dcaaa42497 Jeff*2222 including consideration of surface forcings) has not been implemented; ba0b047096 Mart*2223 also note the original 48-term polynomial term is used, not the newer, 2224 preferred 75-term polynomial. 2225 2226 For these non-linear approximations, neither a reference profile of 2227 temperature or salinity is required, except for a setup where 2228 :varlink:`implicitIntGravWave` is set to ``.TRUE.`` or 2229 :varlink:`selectP_inEOS_Zc`\ =1. 2230 2231 Note that for simplicity, salinity is expressed as a ratio in g/kg (thus 2232 effectively unitless) regardless of the choice of equation of state, 2233 despite "Practical Salinity" not precisely equal to salinity expressed as a 2234 dissolved mass fraction. If TEOS-10 is selected, the model variable 2235 :varlink:`salt` can be interpreted as "Absolute Salinity". See Millero (2010) 2236 :cite:`millero:10` and Pawlowicz (2013) :cite:`pawlowicz:13` for detailed 2237 discussion of salinity measurements, and why being expressed 2238 as g/kg is preferred, in the context of the ocean equation of state. dcaaa42497 Jeff*2239 2240 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}| 2241 a332812c22 Jeff*2242 .. table:: 2243 :class: longtable 2244 2245 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2246 | Parameter | Group | Default | Description | 2247 +========================================+===========+==================================================+=========================================================================================================+ 2248 | :varlink:`eosType` | PARM01 | LINEAR | equation of state form | 2249 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2250 | :varlink:`tRef` | PARM01 | 20.0 :sup:`o`\ C (ocn) or 300.0 K (atm) | 1D vertical reference temperature profile (:sup:`o`\ C or K) | 2251 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2252 | :varlink:`tRefFile` | PARM01 | :kbd:`' '` | filename for reference temperature profile (:sup:`o`\ C or K) | 2253 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2254 | :varlink:`thetaConst` | PARM01 | :varlink:`tRef`\ (k=1) | vertically constant reference temp. for atmosphere :math:`p^*` coordinates (:sup:`o`\ K); | 2255 | | | | for ocean, specify instead of :varlink:`tRef` or :varlink:`tRefFile` | 2256 | | | | for vertically constant reference temp. (:sup:`o`\ C ) | 2257 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2258 | :varlink:`sRef` | PARM01 | 30.0 (g/kg) (ocn) or 0.0 (atm) | 1D vertical reference salinity profile (g/kg) | a332812c22 Jeff*2259 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2260 | :varlink:`sRefFile` | PARM01 | :kbd:`' '` | filename for reference salinity profile (g/kg) | a332812c22 Jeff*2261 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2262 | :varlink:`selectP_inEOS_Zc` | PARM01 | depends on :varlink:`eosType` | select which pressure to use in EOS for :math:`z`-coor. | 2263 | | | | | 2264 | | | | - 0: use :math:`-g \rho_c z` | 2265 | | | | - 1: use :math:`p_{ref} = -\int{-g\rho(T_{ref},S_{ref},p_{ref})dz}` | 2266 | | | | - 2: hydrostatic dynamical pressure | 2267 | | | | - 3: use full hyd.+non-hyd. pressure | 2268 | | | | | 2269 | | | | for ``JMD95P``, ``UNESCO``, ``MDJWF``, ``TEOS10`` default=2, otherwise default =0 | 2270 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2271 | :varlink:`rhonil` | PARM01 | 9.998E+02 | reference density for linear EOS (kg/m\ :sup:`3`) | 2272 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2273 | :varlink:`tAlpha` | PARM01 | 2.0E-04 | linear EOS thermal expansion coefficient (1/\ :sup:`o`\ C) | 2274 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2275 | :varlink:`sBeta` | PARM01 | 7.4E-04 | linear EOS haline contraction coefficient ((g/kg)\ :sup:`-1`) | a332812c22 Jeff*2276 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*2277 2278 Thermodynamic Constants 2279 ~~~~~~~~~~~~~~~~~~~~~~~ 69e7157c80 Jeff*2280 dcaaa42497 Jeff*2281 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.175}|\Y{.55}| 69e7157c80 Jeff*2282 dcaaa42497 Jeff*2283 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2284 | Parameter | Group | Default | Description | 2285 +========================================+===========+==================================================+=========================================================================================================+ 2286 | :varlink:`HeatCapacity_Cp` | PARM01 | 3.994E+03 | specific heat capacity C\ :sub:`p` (ocean) (J/kg/K) | 2287 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2288 | :varlink:`celsius2K` | PARM01 | 2.7315E+02 | conversion constant :sup:`o`\ C to Kelvin | 2289 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2290 | :varlink:`atm_Cp` | PARM01 | 1.004E+03 | specific heat capacity C\ :sub:`p` dry air at const. press. (J/kg/K) | 2291 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2292 | :varlink:`atm_Rd` | PARM01 | :varlink:`atm_Cp`\*(2/7) | gas constant for dry air (J/kg/K) | 2293 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2294 | :varlink:`atm_Rq` | PARM01 | 0.0 | water vapor specific volume anomaly relative to dry air (g/kg) | 2295 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2296 | :varlink:`atm_Po` | PARM01 | 1.0E+05 | atmosphere standard reference pressure (for potential temp. defn.) (Pa) | 2297 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 69e7157c80 Jeff*2298 9c8516d9da Jeff*2299 .. _parms_mom: 2300 dcaaa42497 Jeff*2301 Parameters: Momentum Equations 2302 ------------------------------ 69e7157c80 Jeff*2303 dcaaa42497 Jeff*2304 Configuration 2305 ~~~~~~~~~~~~~ 69e7157c80 Jeff*2306 dcaaa42497 Jeff*2307 There are a few logical variables that allow you to turn on/off various 2308 terms in the momentum equation. These variables are called 2309 :varlink:`momViscosity`, :varlink:`momAdvection`, :varlink:`useCoriolis`, ba0b047096 Mart*2310 :varlink:`momStepping`, :varlink:`metricTerms`, and 2311 :varlink:`momPressureForcing` and by default are set to ``.TRUE.``. 2312 Vertical diffusive fluxes of momentum can be computed implicitly dcaaa42497 Jeff*2313 by setting the logical variable :varlink:`implicitViscosity` to ba0b047096 Mart*2314 ``.TRUE.``. The details relevant to both the momentum flux-form and the 2315 vector-invariant form of the equations and the various (momentum) advection 2316 schemes are covered in :numref:`discret_algorithm`. dcaaa42497 Jeff*2317 2318 .. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}| 2319 a332812c22 Jeff*2320 .. table:: 2321 :class: longtable 2322 2323 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2324 | Parameter | Group | Default | Description | 2325 +========================================+===========+==================================================+=========================================================================================================+ 2326 | :varlink:`momStepping` | PARM01 | TRUE | momentum equation time-stepping on/off flag | 2327 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2328 | :varlink:`momViscosity` | PARM01 | TRUE | momentum friction terms on/off flag | 2329 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2330 | :varlink:`momAdvection` | PARM01 | TRUE | advection of momentum on/off flag | 2331 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2332 | :varlink:`momPressureForcing` | PARM01 | TRUE | pressure term in momentum equation on/off flag | 2333 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 31fb0e0e6d Jean*2334 | :varlink:`selectmetricTerms` | PARM01 | 1 | spherical-polar, cyclindrical grid momentum flux-form metric terms options | 2335 | | | | | 2336 | | | | - 0: don't include terms | 2337 | | | | - 1 (and above): include terms (1=original discretization) | 2338 | | | | - 2: alternate discretization, see :eq:`gu_metric`, :eq:`gv_metric` but averaging centered | 2339 | | | | at gridcell corner | 2340 | | | | - 3: as 2 but skip gU spherical terms by advecting :varlink:`uVel` * :varlink:`dxC` | a332812c22 Jeff*2341 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2342 | :varlink:`useNHMTerms` | PARM01 | FALSE | use "non-hydrostatic form" of metric terms on/off flag; (see :numref:`non_hyd_metric_terms`; | 2343 | | | | note these terms are non-zero in many model configurations beside non-hydrostatic) | 2344 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2345 | :varlink:`momImplVertAdv` | PARM01 | FALSE | momentum implicit vertical advection on/off flag; requires #define :varlink:`INCLUDE_IMPLVERTADV_CODE` | 2346 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2347 | :varlink:`implicitViscosity` | PARM01 | FALSE | implicit vertical viscosity on/off flag | 2348 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2349 | :varlink:`interViscAr_pCell` | PARM04 | FALSE | account for partial-cell in interior vertical viscosity on/off flag | 2350 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2351 | :varlink:`momDissip_In_AB` | PARM03 | TRUE | use Adams-Bashforth time stepping for dissipation tendency | 2352 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2353 | :varlink:`useCoriolis` | PARM01 | TRUE | include Coriolis terms on/off flag | 2354 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 7843dde2de jm-c 2355 | :varlink:`selectCoriScheme` | PARM01 | 0 | Coriolis scheme selector | 2356 | | | | | 2357 | | | | - 0: original scheme | 2358 | | | | - 1: wet-point averaging method | 2359 | | | | - 2: Flux-Form: energy conserving; Vector-Inv: hFac weighted average | 2360 | | | | - 3: Flux-Form: energy conserving using wet-point method; Vector-Inv: energy conserving with hFac weight| 31fb0e0e6d Jean*2361 | | | | - 4: Flux-Form: hFac weighted average (angular momentum conserving) | 2362 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2363 | :varlink:`select3dCoriScheme` | PARM01 | 1 | :math:`\cos{\varphi}` Coriolis terms options | 2364 | | | | | 2365 | | | | - 0: don't include terms | 2366 | | | | - 1: (and above): include terms (1=original discretization) | 2367 | | | | - 2: alternative discretization using averaged transport | 2368 | | | | - 3: same as 2 with hFac in :math:`G_w^{\rm Cor}` term | a332812c22 Jeff*2369 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2370 | :varlink:`vectorInvariantMomentum` | PARM01 | FALSE | use vector-invariant form of momentum equations flag | 2371 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2372 | :varlink:`useJamartMomAdv` | PARM01 | FALSE | use Jamart wetpoints method for relative vorticity advection (vector invariant form) on/off flag | 2373 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2374 | :varlink:`selectVortScheme` | PARM01 | 1 | vorticity scheme (vector invariant form) options | 2375 | | | | | 2376 | | | | - 0,1: enstrophy conserving forms | 2377 | | | | - 2: energy conserving form | 2378 | | | | - 3: energy and enstrophy conserving form | 31fb0e0e6d Jean*2379 | | | | - 4: shift 1/hFac from vorticity equation to final gU, gV tendency (angular momentum conserving) | a332812c22 Jeff*2380 | | | | | 2381 | | | | see Sadourny 1975 :cite:`sadourny:75` and Burridge & Haseler 1977 :cite:`burridge:77` | 2382 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2383 | :varlink:`upwindVorticity` | PARM01 | FALSE | bias interpolation of vorticity in the Coriolis term (vector invariant form) on/off flag | 2384 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2385 | :varlink:`useAbsVorticity` | PARM01 | FALSE | use :math:`f + \zeta` in Coriolis terms (vector invariant form) on/off flag | 2386 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2387 | :varlink:`highOrderVorticity` | PARM01 | FALSE | use 3rd/4th order interpolation of vorticity (vector invariant form) on/off flag | 2388 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2389 | :varlink:`upwindShear` | PARM01 | FALSE | use 1st order upwind for vertical advection (vector invariant form) on/off flag | 2390 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2391 | :varlink:`selectKEscheme` | PARM01 | 0 | kinetic energy computation in Bernoulli function (vector invariant form) options | 2392 | | | | | 2393 | | | | - 0: standard form | 2394 | | | | - 1: area-weighted standard form | 2395 | | | | - 2: as 0 but account for partial cells | 2396 | | | | - 3: as 1 w/partial cells | 2397 | | | | | 2398 | | | | see :filelink:`mom_calc_ke.F <pkg/mom_common/mom_calc_ke.F>` | 2399 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 69e7157c80 Jeff*2400 dcaaa42497 Jeff*2401 Initialization 2402 ~~~~~~~~~~~~~~ 2403 2404 The initial horizontal velocity components can be specified from 2405 binary files :varlink:`uVelInitFile` and :varlink:`vVelInitFile`. These files 83cdbd2346 Jeff*2406 should contain 3-D data ordered in an (:math:`x,y,r`) fashion with k=1 as the dcaaa42497 Jeff*2407 first vertical level (surface level). If no file names are provided, 2408 the velocity is initialized to zero. The initial vertical velocity 2409 is always derived from the horizontal velocity using the continuity 2410 equation. In the case of a restart (from the end of a previous simulation), ba0b047096 Mart*2411 the velocity field is read from a pickup file 2412 (see :numref:`simulation_controls`) and the initial velocity files are ignored. dcaaa42497 Jeff*2413 2414 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 2415 2416 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2417 | Parameter | Group | Default | Description | 2418 +========================================+===========+==================================================+=========================================================================================================+ 2419 | :varlink:`uVelInitFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial zonal velocity field (m/s) | 2420 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2421 | :varlink:`vVelInitFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial meridional velocity field (m/s) | 2422 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2423 | :varlink:`pSurfInitFile` | PARM05 | :kbd:`' '` | filename for 2D specification of initial free surface position ([:math:`r`] unit) | 2424 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2425 69e7157c80 Jeff*2426 .. _mom_dissip: 2427 dcaaa42497 Jeff*2428 General Dissipation Scheme 2429 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 69e7157c80 Jeff*2430 dcaaa42497 Jeff*2431 The lateral eddy viscosity coefficient is specified through the 2432 variable :varlink:`viscAh` (in m\ :sup:`2`\ s\ :sup:`--1`). The 2433 vertical eddy viscosity coefficient is specified through the 2434 variable :varlink:`viscAr` (in [:math:`r`]\ :sup:`2`\ s\ :sup:`--1`, 2435 where [:math:`r`] is the dimension of the vertical coordinate). 2436 In addition, biharmonic mixing can be added as well 2437 through the variable :varlink:`viscA4` (in 516b08a580 jm-c 2438 m\ :sup:`4`\ s\ :sup:`--1`). dcaaa42497 Jeff*2439 2440 .. tabularcolumns:: |\Y{.215}|\Y{.1}|\Y{.115}|\Y{.595}| 2441 a332812c22 Jeff*2442 .. table:: 2443 :class: longtable 2444 2445 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2446 | Parameter | Group | Default | Description | 2447 +========================================+===========+==================================================+=========================================================================================================+ 2448 | :varlink:`viscAh` | PARM01 | 0.0 | lateral eddy viscosity (m\ :sup:`2`\ /s) | 2449 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2450 | :varlink:`viscAhD` | PARM01 | :varlink:`viscAh` | lateral eddy viscosity acts on divergence part (m\ :sup:`2`\ /s) | 2451 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2452 | :varlink:`viscAhZ` | PARM01 | :varlink:`viscAh` | lateral eddy viscosity acts on vorticity part (:math:`\zeta` points) (m\ :sup:`2`\ /s) | 2453 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2454 | :varlink:`viscAhW` | PARM01 | :varlink:`viscAhD` | lateral eddy viscosity for mixing vertical momentum (non-hydrostatic form) (m\ :sup:`2`\ /s); | 2455 | | | | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` | 2456 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2457 | :varlink:`viscAhDfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral eddy viscosity (divergence part) (m\ :sup:`2`\ /s); | 2458 | | | | requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` | 2459 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2460 | :varlink:`viscAhZfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral eddy viscosity (vorticity part, :math:`\zeta` points); | 2461 | | | | requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` | 2462 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2463 | :varlink:`viscAhGrid` | PARM01 | 0.0 | grid-dependent lateral eddy viscosity (non-dim.) | 2464 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2465 | :varlink:`viscAhMax` | PARM01 | 1.0E+21 | maximum lateral eddy viscosity (m\ :sup:`2`\ /s) | 2466 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2467 | :varlink:`viscAhGridMax` | PARM01 | 1.0E+21 | maximum lateral eddy (grid-dependent) viscosity (non-dim.) | 2468 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2469 | :varlink:`viscAhGridMin` | PARM01 | 0.0 | minimum lateral eddy (grid-dependent) viscosity (non-dim.) | 2470 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2471 | :varlink:`viscAhReMax` | PARM01 | 0.0 | minimum lateral eddy viscosity based on Reynolds number (non-dim.) | 2472 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2473 | :varlink:`viscC2leith` | PARM01 | 0.0 | Leith harmonic viscosity factor (vorticity part, :math:`\zeta` points) (non-dim.) | 2474 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2475 | :varlink:`viscC2leithD` | PARM01 | 0.0 | Leith harmonic viscosity factor (divergence part) (non-dim.) | 2476 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ f59d76b0dd Ed D*2477 | :varlink:`viscC2LeithQG` | PARM01 | 0.0 | Quasi-geostrophic Leith viscosity factor (non-dim.) | 2478 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*2479 | :varlink:`viscC2smag` | PARM01 | 0.0 | Smagorinsky harmonic viscosity factor (non-dim.) | 2480 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2481 | :varlink:`viscA4` | PARM01 | 0.0 | lateral biharmonic viscosity (m\ :sup:`4`\ /s) | 2482 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2483 | :varlink:`viscA4D` | PARM01 | :varlink:`viscA4` | lateral biharmonic viscosity (divergence part) (m\ :sup:`4`\ /s) | 2484 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2485 | :varlink:`viscA4Z` | PARM01 | :varlink:`viscA4` | lateral biharmonic viscosity (vorticity part, :math:`\zeta` points) (m\ :sup:`4`\ /s) | 2486 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2487 | :varlink:`viscA4W` | PARM01 | :varlink:`viscA4D` | lateral biharmonic viscosity for mixing vertical momentum (non-hydrostatic form) (m\ :sup:`4`\ /s); | 2488 | | | | for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` | 2489 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2490 | :varlink:`viscA4Dfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral biharmonic viscosity (divergence part) (m\ :sup:`4`\ /s); | 2491 | | | | requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` | 2492 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2493 | :varlink:`viscA4Zfile` | PARM05 | :kbd:`' '` | filename for 3D specification of lateral biharmonic viscosity (vorticity part, :math:`\zeta` points); | 2494 | | | | requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` | 2495 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2496 | :varlink:`viscA4Grid` | PARM01 | 0.0 | grid dependent biharmonic viscosity (non-dim.) | 2497 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2498 | :varlink:`viscA4Max` | PARM01 | 1.0E+21 | maximum biharmonic viscosity (m\ :sup:`4`\ /s) | 2499 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2500 | :varlink:`viscA4GridMax` | PARM01 | 1.0E+21 | maximum biharmonic (grid-dependent) viscosity (non-dim.) | 2501 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2502 | :varlink:`viscA4GridMin` | PARM01 | 0.0 | minimum biharmonic (grid-dependent) viscosity (mon-dim.) | 2503 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2504 | :varlink:`viscA4ReMax` | PARM01 | 0.0 | minimum biharmonic viscosity based on Reynolds number (non-dim.) | 2505 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2506 | :varlink:`viscC4leith` | PARM01 | 0.0 | Leith biharmonic viscosity factor (vorticity part, :math:`\zeta` points) (non-dim.) | 2507 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2508 | :varlink:`viscC4leithD` | PARM01 | 0.0 | Leith biharmonic viscosity factor (divergence part) (non-dim.) | 2509 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2510 | :varlink:`viscC4smag` | PARM01 | 0.0 | Smagorinsky biharmonic viscosity factor (non-dim.) | 2511 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2512 | :varlink:`useFullLeith` | PARM01 | FALSE | use full form of Leith viscosities on/off flag | 2513 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2514 | :varlink:`useSmag3D` | PARM01 | FALSE | use isotropic 3D Smagorinsky harmonic viscosities flag; requires #define :varlink:`ALLOW_SMAG_3D` | 2515 | | | | in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` | 2516 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2517 | :varlink:`smag3D_coeff` | PARM01 | 1.0E-02 | isotropic 3D Smagorinsky coefficient (non-dim.); requires #define :varlink:`ALLOW_SMAG_3D` | 2518 | | | | in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` | 2519 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2520 | :varlink:`useStrainTensionVisc` | PARM01 | FALSE | flag to use strain-tension form of viscous operator | 2521 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2522 | :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` | 2523 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2524 | :varlink:`viscAr` | PARM01 | 0.0 | vertical eddy viscosity ([:math:`r`]\ :sup:`2`\ /s) | 2525 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2526 | :varlink:`viscArNr` | PARM01 | 0.0 | vertical profile of vertical eddy viscosity ([:math:`r`]\ :sup:`2`\ /s) | 2527 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2528 | :varlink:`pCellMix_viscAr` | PARM04 | :varlink:`viscArNr` | vertical viscosity for too thin partial-cell ([:math:`r`]\ :sup:`2`\ /s) | 2529 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*2530 2531 Sidewall/Bottom Dissipation 2532 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2533 2534 Slip or no-slip conditions at lateral and bottom 2535 boundaries are specified through the logical variables 2536 :varlink:`no_slip_sides` and :varlink:`no_slip_bottom`. If set to 2537 ``.FALSE.``, free-slip boundary conditions are applied. If no-slip 2538 boundary conditions are applied at the bottom, a bottom drag can be 2539 applied as well. Two forms are available: linear (set the variable 2540 :varlink:`bottomDragLinear` in [:math:`r`]/s, ) 2541 and quadratic (set the variable 2542 :varlink:`bottomDragQuadratic`, [:math:`r`]/m). 2543 2544 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 2545 2546 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2547 | Parameter | Group | Default | Description | 2548 +========================================+===========+==================================================+=========================================================================================================+ 2549 | :varlink:`no_slip_sides` | PARM01 | TRUE | viscous BCs: no-slip sides on/off flag | 2550 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ e52125a087 Jeff*2551 | :varlink:`sideDragFactor` | PARM01 | 2.0E+00 | side-drag scaling factor (2.0: full drag) (non-dim.) | dcaaa42497 Jeff*2552 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2553 | :varlink:`no_slip_bottom` | PARM01 | TRUE | viscous BCs: no-slip bottom on/off flag | 2554 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2555 | :varlink:`bottomDragLinear` | PARM01 | 0.0 | linear bottom-drag coefficient ([:math:`r`]/s) | 2556 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2557 | :varlink:`bottomDragQuadratic` | PARM01 | 0.0 | quadratic bottom-drag coefficient ([:math:`r`]/m) | 2558 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ab47de63dc Mart*2559 | :varlink:`zRoughBot` | PARM01 | 0.0 | roughness length for quadratic bottom friction coefficient (m) | 2560 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*2561 | :varlink:`selectBotDragQuadr` | PARM01 | -1 | select quadratic bottom drag discretization option | 2562 | | | | | 2563 | | | | - -1: not used | 2564 | | | | - 0: average KE from grid center to :math:`u,v` location | 2565 | | | | - 1: use local velocity norm @ :math:`u,v` location | 2566 | | | | - 2: as 1 with wet-point averaging of other velocity component | 2567 | | | | | dcaaa42497 Jeff*2568 | | | | if :varlink:`bottomDragQuadratic` :math:`\neq 0.` then default is 0 | 2569 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*2570 | :varlink:`selectImplicitDrag` | PARM01 | 0 | top/bottom drag implicit treatment options | 2571 | | | | | 2572 | | | | - 0: fully explicit | 2573 | | | | - 1: implicit on provisional velocity, i.e., before :math:`\nabla \eta` increment | 2574 | | | | - 2: fully implicit | 2575 | | | | | dcaaa42497 Jeff*2576 | | | | if =2, requires #define :varlink:`ALLOW_SOLVE4_PS_AND_DRAG` | 2577 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2578 | :varlink:`bottomVisc_pCell` | PARM01 | FALSE | account for partial-cell in bottom viscosity (using :varlink:`no_slip_bottom` = ``.TRUE.``) on/off flag | 2579 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2580 69e7157c80 Jeff*2581 Parameters: Tracer Equations 2582 ---------------------------- 2583 dcaaa42497 Jeff*2584 This section covers the tracer equations, i.e., the potential temperature 69e7157c80 Jeff*2585 equation and the salinity (for the ocean) or specific humidity (for the 516b08a580 jm-c 2586 atmosphere) equation. dcaaa42497 Jeff*2587 2588 Configuration 2589 ~~~~~~~~~~~~~ 2590 2591 The logical variables :varlink:`tempAdvection`, and 69e7157c80 Jeff*2592 :varlink:`tempStepping` allow you to turn on/off terms in the temperature dcaaa42497 Jeff*2593 equation (similarly for salinity or specific humidity with variables 2594 :varlink:`saltAdvection` etc.). These variables all 2595 default to a value of ``.TRUE.``. The vertical diffusive 2596 fluxes can be computed implicitly by setting the logical variable 516b08a580 jm-c 2597 :varlink:`implicitDiffusion` to ``.TRUE.``. dcaaa42497 Jeff*2598 2599 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}| 2600 a332812c22 Jeff*2601 .. table:: 2602 :class: longtable 2603 2604 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2605 | Parameter | Group | Default | Description | 2606 +========================================+===========+==================================================+=========================================================================================================+ 2607 | :varlink:`tempStepping` | PARM01 | TRUE | temperature equation time-stepping on/off flag | 2608 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2609 | :varlink:`tempAdvection` | PARM01 | TRUE | advection of temperature on/off flag | 2610 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2611 | :varlink:`tempAdvScheme` | PARM01 | 2 | temperature horizontal advection scheme selector (see :numref:`adv_scheme_summary`) | 2612 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2613 | :varlink:`tempVertAdvScheme` | PARM01 | :varlink:`tempAdvScheme` | temperature vertical advection scheme selector (see :numref:`adv_scheme_summary`) | 2614 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2615 | :varlink:`tempImplVertAdv` | PARM01 | FALSE | temperature implicit vertical advection on/off flag | 2616 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2617 | :varlink:`addFrictionHeating` | PARM01 | FALSE | include frictional heating in temperature equation on/off flag; | 2618 | | | | requires #define :varlink:`ALLOW_FRICTION_HEATING` | 2619 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2620 | :varlink:`temp_stayPositive` | PARM01 | FALSE | use Smolarkiewicz hack to ensure temperature stays positive on/off flag; | 2621 | | | | requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h` | 2622 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2623 | :varlink:`saltStepping` | PARM01 | TRUE | salinity equation time-stepping on/off flag | 2624 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2625 | :varlink:`saltAdvection` | PARM01 | TRUE | advection of salinity on/off flag | 2626 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2627 | :varlink:`saltAdvScheme` | PARM01 | 2 | salinity horizontal advection scheme selector (see :numref:`adv_scheme_summary`) | 2628 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2629 | :varlink:`saltVertAdvScheme` | PARM01 | :varlink:`saltAdvScheme` | salinity vertical advection scheme selector (see :numref:`adv_scheme_summary`) | 2630 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2631 | :varlink:`saltImplVertAdv` | PARM01 | FALSE | salinity implicit vertical advection on/off flag | 2632 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2633 | :varlink:`salt_stayPositive` | PARM01 | FALSE | use Smolarkiewicz hack to ensure salinity stays positive on/off flag; | 2634 | | | | requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h` | 2635 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2636 | :varlink:`implicitDiffusion` | PARM01 | FALSE | implicit vertical diffusion on/off flag | 2637 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2638 | :varlink:`interDiffKr_pCell` | PARM04 | FALSE | account for partial-cell in interior vertical diffusion on/off flag | 2639 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 837f8d0bd9 Dhru*2640 | :varlink:`linFSConserveTr` | PARM01 | FALSE | correct source/sink of tracer due to use of linear free surface on/off flag | a332812c22 Jeff*2641 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2642 | :varlink:`doAB_onGtGs` | PARM03 | TRUE | apply Adams-Bashforth on tendencies (rather than on T,S) on/off flag | 2643 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*2644 69e7157c80 Jeff*2645 Initialization dcaaa42497 Jeff*2646 ~~~~~~~~~~~~~~ 2647 2648 The initial tracer data can be contained in the binary files 2649 :varlink:`hydrogThetaFile` and :varlink:`hydrogSaltFile`. These files should 83cdbd2346 Jeff*2650 contain 3-D data ordered in an (:math:`x,y,r`) fashion with k=1 as the first dcaaa42497 Jeff*2651 vertical level. If no file names are provided, the tracers are then ba0b047096 Mart*2652 initialized with the values of :varlink:`tRef` and :varlink:`sRef` discussed in 2653 :numref:`parms-eos`. In this case, the initial tracer data are uniform in 2654 :math:`x` and :math:`y` for each depth level. dcaaa42497 Jeff*2655 2656 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 2657 2658 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2659 | Parameter | Group | Default | Description | 2660 +========================================+===========+==================================================+=========================================================================================================+ 2661 | :varlink:`hydrogThetaFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial potential temperature (:sup:`o`\ C) | 2662 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2663 | :varlink:`hydrogSaltFile` | PARM05 | :kbd:`' '` | filename for 3D specification of initial salinity (g/kg) | dcaaa42497 Jeff*2664 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2665 | :varlink:`maskIniTemp` | PARM05 | TRUE | apply (center-point) mask to initial hydrographic theta data on/off flag | 2666 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2667 | :varlink:`maskIniSalt` | PARM05 | TRUE | apply (center-point) mask to initial hydrographic salinity on/off flag | 2668 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2669 | :varlink:`checkIniTemp` | PARM05 | TRUE | check if initial theta (at wet-point) identically zero on/off flag | 2670 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2671 | :varlink:`checkIniSalt` | PARM05 | TRUE | check if initial salinity (at wet-point) identically zero on/off flag | 2672 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2673 2674 Tracer Diffusivities 2675 ~~~~~~~~~~~~~~~~~~~~ 2676 2677 Lateral eddy diffusivities for temperature and salinity/specific 2678 humidity are specified through the variables :varlink:`diffKhT` and 2679 :varlink:`diffKhS` (in m\ :sup:`2`\ /s). Vertical eddy diffusivities are ba0b047096 Mart*2680 specified through the variables :varlink:`diffKrT` and :varlink:`diffKrS`. 2681 In addition, biharmonic diffusivities can be specified as well through the 2682 coefficients :varlink:`diffK4T` and :varlink:`diffK4S` (in m\ :sup:`4`\ /s). 2683 The Gent and McWilliams parameterization for advection and mixing of oceanic 2684 tracers is described in :numref:`sub_phys_pkg_gmredi`. dcaaa42497 Jeff*2685 2686 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.15}|\Y{.575}| 2687 a332812c22 Jeff*2688 .. table:: 2689 :class: longtable 2690 2691 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2692 | Parameter | Group | Default | Description | 2693 +========================================+===========+==================================================+=========================================================================================================+ 2694 | :varlink:`diffKhT` | PARM01 | 0.0 | Laplacian diffusivity of heat laterally (m\ :sup:`2`\ /s) | 2695 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2696 | :varlink:`diffK4T` | PARM01 | 0.0 | biharmonic diffusivity of heat laterally (m\ :sup:`4`\ /s) | 2697 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2698 | :varlink:`diffKrT` | PARM01 | 0.0 | Laplacian diffusivity of heat vertically (m\ :sup:`2`\ /s) | 2699 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2700 | :varlink:`diffKr4T` | PARM01 | 0.0 | biharmonic diffusivity of heat vertically (m\ :sup:`2`\ /s) | 2701 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2702 | :varlink:`diffKrNrT` | PARM01 | 0.0 at k=top | vertical profile of vertical diffusivity of temperature (m\ :sup:`2`\ /s) | 2703 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2704 | :varlink:`pCellMix_diffKr` | PARM04 | :varlink:`diffKrNr` | vertical diffusivity for too thin partial-cell ([r]\ :sup:`2`\ /s) | 2705 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2706 | :varlink:`diffKhS` | PARM01 | 0.0 | Laplacian diffusivity of salt laterally (m\ :sup:`2`\ /s) | 2707 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2708 | :varlink:`diffK4S` | PARM01 | 0.0 | biharmonic diffusivity of salt laterally (m\ :sup:`4`\ /s) | 2709 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2710 | :varlink:`diffKrS` | PARM01 | 0.0 | Laplacian diffusivity of salt vertically (m\ :sup:`2`\ /s) | 2711 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2712 | :varlink:`diffKr4S` | PARM01 | 0.0 | biharmonic diffusivity of salt vertically (m\ :sup:`2`\ /s) | 2713 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2714 | :varlink:`diffKrNrS` | PARM01 | 0.0 at k=top | vertical profile of vertical diffusivity of salt (m\ :sup:`2`\ /s) | 2715 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2716 | :varlink:`diffKrFile` | PARM05 | :kbd:`' '` | filename for 3D specification of vertical diffusivity (m\ :sup:`2`\ /s); | 2717 | | | | requires #define :varlink:`ALLOW_3D_DIFFKR` | 2718 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2719 | :varlink:`diffKrBL79surf` | PARM01 | 0.0 | surface diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m\ :sup:`2`\ /s) | 2720 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2721 | :varlink:`diffKrBL79deep` | PARM01 | 0.0 | deep diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m\ :sup:`2`\ /s) | 2722 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2723 | :varlink:`diffKrBL79scl` | PARM01 | 2.0E+02 | depth scale for Bryan & Lewis 1979 :cite:`bryan:79` (m) | 2724 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2725 | :varlink:`diffKrBL79Ho` | PARM01 | -2.0E+03 | turning depth for Bryan & Lewis 1979 :cite:`bryan:79` (m) | 2726 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2727 | :varlink:`diffKrBLEQsurf` | PARM01 | 0.0 | same as :varlink:`diffKrBL79surf` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` | 2728 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2729 | :varlink:`diffKrBLEQdeep` | PARM01 | 0.0 | same as :varlink:`diffKrBL79deep` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` | 2730 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2731 | :varlink:`diffKrBLEQscl` | PARM01 | 2.0E+02 | same as :varlink:`diffKrBL79scl` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` | 2732 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2733 | :varlink:`diffKrBLEQHo` | PARM01 | -2.0E+03 | same as :varlink:`diffKrBL79Ho` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` | 2734 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2735 | :varlink:`BL79LatVary` | PARM01 | 3.0E+01 | transition from diffKrBLEQ to diffKrBL79 parms at this latitude; | 2736 | | | | requires #define :varlink:`ALLOW_BL79_LAT_VARY` | 2737 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*2738 94151a9b18 Jeff*2739 .. _ocean_convection_parms: 2740 dcaaa42497 Jeff*2741 Ocean Convection 2742 ~~~~~~~~~~~~~~~~ 2743 ba0b047096 Mart*2744 In addition to specific packages that parameterize ocean convection, two main 2745 model options are available. To use the first option, a convective adjustment 2746 scheme, you need to set the variable :varlink:`cadjFreq`, the frequency 2747 (in seconds) with which the adjustment algorithm is called, to a non-zero value 2748 (note, if :varlink:`cadjFreq` set to a negative value by the user, the model 2749 will set it to the model clock time step). The second option is to parameterize dcaaa42497 Jeff*2750 convection with implicit vertical diffusion. To do this, set the 2751 logical variable :varlink:`implicitDiffusion` to ``.TRUE.`` and the real 2752 variable :varlink:`ivdc_kappa` (in m\ :sup:`2`\ /s) to 2753 an appropriate tracer vertical diffusivity value for mixing ba0b047096 Mart*2754 due to static instabilities (typically, several orders of magnitude above the 2755 background vertical diffusivity). Note that :varlink:`cadjFreq` and dcaaa42497 Jeff*2756 :varlink:`ivdc_kappa` cannot both have non-zero value. 2757 2758 .. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.125}|\Y{.6}| 2759 2760 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2761 | Parameter | Group | Default | Description | 2762 +========================================+===========+==================================================+=========================================================================================================+ 2763 | :varlink:`ivdc_kappa` | PARM01 | 0.0 | implicit vertical diffusivity for convection (m\ :sup:`2`\ /s) | 2764 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ e52125a087 Jeff*2765 | :varlink:`cAdjFreq` | PARM03 | 0 | frequency of convective adj. scheme; <0: sets value to :varlink:`deltaTclock` (s) | dcaaa42497 Jeff*2766 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*2767 | :varlink:`hMixCriteria` | PARM01 | -0.8E+00 | - <0: specifies :math:`\Delta T` (:sup:`o`\ C) to define ML depth where | 2768 | | | | :math:`\Delta\rho = \Delta T*d\rho/dT` occurs | 2769 | | | | - >1: define ML depth where local strat. exceeds mean strat. by this factor (non-dim.) | dcaaa42497 Jeff*2770 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ e52125a087 Jeff*2771 | :varlink:`hMixSmooth` | PARM01 | 0.0 | use this fraction of neighboring points (for smoothing) in ML calculation (0-1; 0: no smoothing) | dcaaa42497 Jeff*2772 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2773 2774 Parameters: Model Forcing 2775 ------------------------- 2776 ba0b047096 Mart*2777 The forcing options that can be prescribed through runtime parameters in 2778 ``data`` are easy to use but somewhat limited in scope. More complex forcing 2779 setups are possible with optional packages such as :filelink:`pkg/exf` or 2780 :filelink:`pkg/rbcs`, in which case most or all of the parameters in this 2781 section can simply be left at their default value. dcaaa42497 Jeff*2782 2783 Momentum Forcing 2784 ~~~~~~~~~~~~~~~~ 2785 2786 This section only applies to the ocean. You need to generate 2787 wind-stress data into two files :varlink:`zonalWindFile` and 2788 :varlink:`meridWindFile` corresponding to the zonal and meridional 2789 components of the wind stress, respectively (if you want the stress 2790 to be along the direction of only one of the model horizontal axes, 2791 you only need to generate one file). The format of the files is 2792 similar to the bathymetry file. The zonal (meridional) stress data 83cdbd2346 Jeff*2793 are assumed to be in pascals and located at U-points (V-points). See the MATLAB dcaaa42497 Jeff*2794 program ``gendata.m`` in the ``input`` directories of ba0b047096 Mart*2795 ``verification`` for several tutorial example (e.g. 2796 :filelink:`gendata.m <verification/tutorial_barotropic_gyre/input/gendata.m>` dcaaa42497 Jeff*2797 in the :ref:`barotropic gyre tutorial <sec_eg_baro>`) 2798 to see how simple analytical wind forcing data are generated for the 2799 case study experiments. 2800 2801 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 2802 2803 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2804 | Parameter | Group | Default | Description | 2805 +========================================+===========+==================================================+=========================================================================================================+ 2806 | :varlink:`momForcing` | PARM01 | TRUE | included external forcing of momentum on/off flag | 2807 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2808 | :varlink:`zonalWindFile` | PARM05 | :kbd:`' '` | filename for 2D specification of zonal component of wind forcing (N/m\ :sup:`2`) | 2809 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2810 | :varlink:`meridWindFile` | PARM05 | :kbd:`' '` | filename for 2D specification of meridional component of wind forcing (N/m\ :sup:`2`) | 2811 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ e52125a087 Jeff*2812 | :varlink:`momForcingOutAB` | PARM03 | 0 | 1: take momentum forcing out of Adams-Bashforth time stepping | dcaaa42497 Jeff*2813 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2814 | :varlink:`momTidalForcing` | PARM01 | TRUE | tidal forcing of momentum equation on/off flag (requires tidal forcing files) | 2815 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2816 | :varlink:`ploadFile` | PARM05 | :kbd:`' '` | filename for 2D specification of atmospheric pressure loading (ocean :math:`z`-coor. only) (Pa) | 2817 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2818 2819 Tracer Forcing 2820 ~~~~~~~~~~~~~~ 2821 2822 A combination of flux data and relaxation terms can be used for 2823 driving the tracer equations. For potential temperature, heat flux 83cdbd2346 Jeff*2824 data (in W/m\ :sup:`2`) can be stored in the 2-D binary file dcaaa42497 Jeff*2825 :varlink:`surfQnetfile`. Alternatively or in addition, the forcing can be 2826 specified through a relaxation term. The SST data to which the model 2827 surface temperatures are restored are stored in 83cdbd2346 Jeff*2828 the 2-D binary file :varlink:`thetaClimFile`. The corresponding relaxation dcaaa42497 Jeff*2829 time scale coefficient is set through the variable 2830 :varlink:`tauThetaClimRelax` (in seconds). The same procedure applies for 2831 salinity with the variable names :varlink:`EmPmRfile`, :varlink:`saltClimFile`, 2832 and :varlink:`tauSaltClimRelax` for freshwater flux (in m/s) and surface ba0b047096 Mart*2833 salinity (in g/kg) data files and relaxation timescale coefficient 516b08a580 jm-c 2834 (in seconds), respectively. dcaaa42497 Jeff*2835 2836 .. tabularcolumns:: |\Y{.24}|\Y{.1}|\Y{.15}|\Y{.535}| 2837 a332812c22 Jeff*2838 .. table:: 2839 :class: longtable 2840 2841 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2842 | Parameter | Group | Default | Description | 2843 +========================================+===========+==================================================+=========================================================================================================+ 2844 | :varlink:`tempForcing` | PARM01 | TRUE | external forcing of temperature forcing on/off flag | 2845 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2846 | :varlink:`surfQnetFile` | PARM05 | :kbd:`' '` | filename for 2D specification of net total heat flux (W/m\ :sup:`2`) | 2847 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2848 | :varlink:`surfQswFile` | PARM05 | :kbd:`' '` | filename for 2D specification of net shortwave flux (W/m\ :sup:`2`); | 2849 | | | | requires #define :varlink:`SHORTWAVE_HEATING` | 2850 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2851 | :varlink:`tauThetaClimRelax` | PARM03 | 0.0 | temperature (surface) relaxation time scale (s) | 2852 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2853 | :varlink:`lambdaThetaFile` | PARM05 | :kbd:`' '` | filename for 2D specification of inverse temperature (surface) relaxation time scale (1/s) | 2854 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2855 | :varlink:`ThetaClimFile` | PARM05 | :kbd:`' '` | filename for specification of (surface) temperature relaxation values (:sup:`o`\ C) | 2856 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2857 | :varlink:`balanceThetaClimRelax` | PARM01 | FALSE | subtract global mean heat flux due to temp. relaxation flux every time step on/off flag; | 2858 | | | | requires #define :varlink:`ALLOW_BALANCE_RELAX` | 2859 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2860 | :varlink:`balanceQnet` | PARM01 | FALSE | subtract global mean Qnet every time step on/off flag; requires #define :varlink:`ALLOW_BALANCE_FLUXES` | 2861 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2862 | :varlink:`geothermalFile` | PARM05 | :kbd:`' '` | filename for 2D specification of geothermal heating flux through bottom (W/m\ :sup:`2`); | 2863 | | | | requires #define :varlink:`ALLOW_GEOTHERMAL_FLUX` | 2864 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2865 | :varlink:`temp_EvPrRn` | PARM01 | UNSET | temperature of rain and evaporated water (unset, use local temp.) (:sup:`o`\ C) | 2866 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2867 | :varlink:`allowFreezing` | PARM01 | FALSE | limit (ocean) temperature at surface to >= -1.9\ :sup:`o`\ C | 2868 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2869 | :varlink:`saltForcing` | PARM01 | TRUE | external forcing of salinity forcing on/off flag | 2870 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2871 | :varlink:`convertFW2Salt` | PARM01 | 3.5E+01 | salinity used to convert freshwater flux to salt flux (-1: use local S) (g/kg) | a332812c22 Jeff*2872 | | | | (note default is -1 if :varlink:`useRealFreshWaterFlux`\ = ``.TRUE.``) | 2873 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2874 | :varlink:`rhoConstFresh` | PARM01 | :varlink:`rhoConst` | constant reference density for fresh water (rain) (kg/m\ :sup:`3`) | 2875 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2876 | :varlink:`EmPmRFile` | PARM05 | :kbd:`' '` | filename for 2D specification of net freshwater flux (m/s) | 2877 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2878 | :varlink:`saltFluxFile` | PARM05 | :kbd:`' '` | filename for 2D specification of salt flux (from seaice) ((g/kg).kg/m\ :sup:`2`\/s) | a332812c22 Jeff*2879 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2880 | :varlink:`tauSaltClimRelax` | PARM03 | 0.0 | salinity (surface) relaxation time scale (s) | 2881 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2882 | :varlink:`lambdaSaltFile` | PARM05 | :kbd:`' '` | filename for 2D specification of inverse salinity (surface) relaxation time scale (1/s) | 2883 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2884 | :varlink:`saltClimFile` | PARM05 | :kbd:`' '` | filename for specification of (surface) salinity relaxation values (g/kg) | a332812c22 Jeff*2885 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2886 | :varlink:`balanceSaltClimRelax` | PARM01 | FALSE | subtract global mean flux due to salt relaxation every time step on/off flag | 2887 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 7e00d7e8f9 Jean*2888 | :varlink:`selectBalanceEmPmR` | PARM01 | 0 | option to balance net surface freshwater flux every time step | 2889 | | | | | 2890 | | | | - 0: off | 2891 | | | | - 1: uniform surface correction | 2892 | | | | - 2: non-uniform surface correction, scaled using :varlink:`wghtBalancedFile` for local weighting | 2893 | | | | | 2894 | | | | if =1 or 2, requires #define :varlink:`ALLOW_BALANCE_FLUXES` | 2895 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2896 | :varlink:`wghtBalanceFile` | PARM05 | :kbd:`' '` | filename for 2D specification of weights used in :varlink:`selectBalanceEmPmR` =2 correction | a332812c22 Jeff*2897 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ ba0b047096 Mart*2898 | :varlink:`salt_EvPrRn` | PARM01 | 0.0 | salinity of rain and evaporated water (g/kg) | a332812c22 Jeff*2899 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2900 | :varlink:`selectAddFluid` | PARM01 | 0 | add fluid to ocean interior options (-1, 0: off, or 1); requires #define :varlink:`ALLOW_ADDFLUID` | 2901 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2902 | :varlink:`temp_addMass` | PARM01 | :varlink:`temp_EvPrRn` | temp. of added or removed (interior) water (:sup:`o`\ C); requires #define :varlink:`ALLOW_ADDFLUID` | 2903 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2904 | :varlink:`salt_addMass` | PARM01 | :varlink:`salt_EvPrRn` | salinity of added or removed (interior) water (:sup:`o`\ C); requires #define :varlink:`ALLOW_ADDFLUID` | 2905 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2906 | :varlink:`addMassFile` | PARM05 | :kbd:`' '` | filename for 3D specification of mass source/sink (+=source, kg/s); | 2907 | | | | requires #define :varlink:`ALLOW_ADDFLUID` | 2908 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2909 | :varlink:`balancePrintMean` | PARM01 | FALSE | print subtracted balancing means to STDOUT on/off flag; | 2910 | | | | requires #define :varlink:`ALLOW_BALANCE_FLUXES` and/or #define :varlink:`ALLOW_BALANCE_RELAX` | 2911 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2912 | :varlink:`latBandClimRelax` | PARM03 | whole domain | relaxation to (T,S) climatology equatorward of this latitude band is applied | 2913 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2914 | :varlink:`tracForcingOutAB` | PARM03 | 0 | 1: take T, S, and pTracer forcing out of Adams-Bashforth time stepping | 2915 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ dcaaa42497 Jeff*2916 2917 .. _periodic_forcing_expl: 2918 2919 Periodic Forcing 2920 ~~~~~~~~~~~~~~~~ 2921 2922 To prescribe time-dependent periodic 2923 forcing, concatenate successive time records into a 2924 single file ordered in a (:math:`x,y`,time) fashion 2925 and set the following variables: :varlink:`periodicExternalForcing` to ba0b047096 Mart*2926 ``.TRUE.``, :varlink:`externForcingPeriod` to the period (in seconds between 2927 two records in input files) with which dcaaa42497 Jeff*2928 the forcing varies (e.g., 1 month), and :varlink:`externForcingCycle` 2929 to the repeat time (in seconds) of the forcing (e.g., 1 year; note 2930 :varlink:`externForcingCycle` must be a multiple of 2931 :varlink:`externForcingPeriod`). With these variables specified, the model 2932 will interpolate the forcing linearly at each iteration. 2933 2934 .. tabularcolumns:: |\Y{.25}|\Y{.1}|\Y{.125}|\Y{.55}| 2935 2936 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2937 | Parameter | Group | Default | Description | 2938 +========================================+===========+==================================================+=========================================================================================================+ 2939 | :varlink:`periodicExternalForcing` | PARM03 | FALSE | allow time-dependent periodic forcing on/off flag | 2940 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2941 | :varlink:`externForcingPeriod` | PARM03 | 0.0 | period over which forcing varies (e.g. monthly) (s) | 2942 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2943 | :varlink:`externForcingCycle` | PARM03 | 0.0 | period over which the forcing cycle repeats (e.g. one year) (s) | 2944 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2945 2946 .. _simulation_controls: 69e7157c80 Jeff*2947 2948 Parameters: Simulation Controls 2949 ------------------------------- 2950 dcaaa42497 Jeff*2951 Run Start and Duration 2952 ~~~~~~~~~~~~~~~~~~~~~~ 2953 2954 The beginning of a simulation is set by specifying a start time (in seconds) 2955 through the real variable :varlink:`startTime` or by specifying an 2956 initial iteration number through the integer variable :varlink:`nIter0`. If 2957 these variables are set to non-zero values, the model will look for a ba0b047096 Mart*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 2959.
2958 âpickupâ file (by default, ``pickup.0000nIter0``) to restart the integration. 2959 The end of a simulation is set through the real variable :varlink:`endTime` 2960 (in seconds). Alternatively, one can instead specify the number of time steps dcaaa42497 Jeff*2961 to execute through the integer variable :varlink:`nTimeSteps`. ba0b047096 Mart*2962 Iterations are referenced to :varlink:`deltaTClock`, i.e., each iteration is 2963 :varlink:`deltaTClock` seconds of model time. dcaaa42497 Jeff*2964 2965 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 2966 2967 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2968 | Parameter | Group | Default | Description | 2969 +========================================+===========+==================================================+=========================================================================================================+ 2970 | :varlink:`nIter0` | PARM03 | 0 | starting timestep iteration number for this integration | 2971 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2972 | :varlink:`nTimeSteps` | PARM03 | 0 | number of (model clock) timesteps to execute | 2973 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2974 | :varlink:`nEndIter` | PARM03 | 0 | run ending timestep iteration number (alternate way to prescribe :varlink:`nTimeSteps`) | 2975 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2976 | :varlink:`startTime` | PARM03 | :varlink:`baseTime` | run start time for this integration (s) (alternate way to prescribe :varlink:`nIter0`) | 2977 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2978 | :varlink:`endTime` | PARM03 | 0.0 | run ending time (s) (with :varlink:`startTime`, alternate way to prescribe :varlink:`nTimeSteps`) | 2979 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 2980 2981 Input/Output Files 2982 ~~~~~~~~~~~~~~~~~~ 2983 2984 The precision with which to read binary data is 2985 controlled by the integer variable :varlink:`readBinaryPrec`, which can take ba0b047096 Mart*2986 the value 32 (single precision) or 64 (double precision). Similarly, the 2987 precision with which to write binary data is controlled by the integer variable 2988 :varlink:`writeBinaryPrec`. By default, MITgcm writes output (snapshots, 2989 diagnostics, and pickups) separately for individual tiles, leaving it to the 2990 user to reassemble these into global files, if needed (scripts are available in 2991 :filelink:`utils/`). There are two options however to have the model do this 2992 for you. Setting :varlink:`globalFiles` to ``.TRUE.`` should always work in a 2993 single process setup (including multi-threaded processes), but for 2994 `MPI <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ runs this will 2995 depend on the platform -- it requires simultaneous write access to a common 2996 file (permissible in typical 2997 `Lustre <https://en.wikipedia.org/wiki/Lustre_(file_system)>`_ setups, but not 2998 on all file systems). Alternatively, one can set :varlink:`useSingleCpuIO` 2999 to ``.TRUE.`` to generate global files, which should always work, but requires 3000 additional mpi-passing of data and may result in slower execution. dcaaa42497 Jeff*3001 3002 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 3003 3004 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3005 | Parameter | Group | Default | Description | 3006 +========================================+===========+==================================================+=========================================================================================================+ e52125a087 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 3008.
3007 | :varlink:`globalFiles` | PARM01 | FALSE | write output âglobalâ (i.e. not per tile) files on/off flag | dcaaa42497 Jeff*3008 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3009 | :varlink:`useSingleCpuIO` | PARM01 | FALSE | only master MPI process does I/O (producing global output files) | 3010 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3011 | :varlink:`the_run_name` | PARM05 | :kbd:`' '` | string identifying the name of the model "run" for meta files | 3012 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3013 | :varlink:`readBinaryPrec` | PARM01 | 32 | precision used for reading binary files (32 or 64) | 3014 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3015 | :varlink:`writeBinaryPrec` | PARM01 | 32 | precision used for writing binary files (32 or 64) | 3016 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3017 | :varlink:`outputTypesInclusive` | PARM03 | FALSE | allows writing of output files in multiple formats (i.e. :filelink:`pkg/mdsio` and :filelink:`pkg/mnc`)| 3018 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 3020.
3019 | :varlink:`rwSuffixType` | PARM03 | 0 | controls the format of the :filelink:`pkg/mdsio` binary file âsuffixâ | a332812c22 Jeff*3020 | | | | | 3021 | | | | - 0: use iteration number (myIter, I10.10) | 3022 | | | | - 1: 100*myTime | 3023 | | | | - 2: myTime | 3024 | | | | - 3: myTime/360 | 3025 | | | | - 4: myTime/3600 | 3026 | | | | | 3027 | | | | where :varlink:`myTime` is model time in seconds | dcaaa42497 Jeff*3028 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3029 | :varlink:`mdsioLocalDir` | PARM05 | :kbd:`' '` | if not blank, read-write output tiled files from/to this directory name | 3030 | | | | (+four-digit processor-rank code) | 3031 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3032 69e7157c80 Jeff*3033 .. _freq_of_output: 3034 dcaaa42497 Jeff*3035 Frequency/Amount of Output 3036 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 69e7157c80 Jeff*3037 dcaaa42497 Jeff*3038 The frequency (in seconds) with which output 3039 is written to disk needs to be specified. :varlink:`dumpFreq` controls the ba0b047096 Mart*3040 frequency with which the instantaneous state of the model is written. 3041 :varlink:`monitorFreq` controls the frequency with which monitor output is 3042 dumped to the standard output file(s). The frequency of output is referenced 3043 to :varlink:`deltaTClock`. 69e7157c80 Jeff*3044 dcaaa42497 Jeff*3045 .. tabularcolumns:: |\Y{.18}|\Y{.1}|\Y{.2}|\Y{.545}| 69e7157c80 Jeff*3046 dcaaa42497 Jeff*3047 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3048 | Parameter | Group | Default | Description | 3049 +========================================+===========+==================================================+=========================================================================================================+ 3050 | :varlink:`dumpFreq` | PARM03 | 0.0 | interval to write model state/snapshot data (s) | 3051 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3052 | :varlink:`dumpInitAndLast` | PARM03 | TRUE | write out initial and last iteration model state on/off flag | 3053 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3054 | :varlink:`diagFreq` | PARM03 | 0.0 | interval to write additional intermediate (debugging cg2d/3d) output (s) | 3055 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3056 | :varlink:`monitorFreq` | PARM03 | lowest of other output \*Freq parms | interval to write monitor output (s) | 3057 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ a332812c22 Jeff*3058 | :varlink:`monitorSelect` | PARM03 | 2 (3 if fluid is water) | select group of monitor variables to output | 3059 | | | | | 3060 | | | | - 1: dynamic variables only | 3061 | | | | - 2: add vorticity variables | 3062 | | | | - 3: add surface variables | dcaaa42497 Jeff*3063 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 5f61c21b01 Jeff*3064 | :varlink:`debugLevel` | PARM01 | depends on :varlink:`debugMode` | level of printing of MITgcm activity messages/statistics (1-5, higher -> more activity messages) | dcaaa42497 Jeff*3065 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3066 | :varlink:`plotLevel` | PARM01 | :varlink:`debugLevel` | controls printing of field maps (1-5, higher -> more fields) | 3067 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3068 3069 Restart/Pickup Files 3070 ~~~~~~~~~~~~~~~~~~~~ 3071 3072 :varlink:`chkPtFreq` and :varlink:`pchkPtFreq` control the output frequency of ba0b047096 Mart*3073 rolling and permanent pickup (a.k.a. checkpoint) files, respectively. These 3074 frequencies are referenced to :varlink:`deltaTClock`. dcaaa42497 Jeff*3075 3076 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 69e7157c80 Jeff*3077 dcaaa42497 Jeff*3078 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3079 | Parameter | Group | Default | Description | 3080 +========================================+===========+==================================================+=========================================================================================================+ 3081 | :varlink:`pChkPtFreq` | PARM03 | 0.0 | permanent restart/pickup checkpoint file write interval ( s ) | 3082 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3083 | :varlink:`chkPtFreq` | PARM03 | 0.0 | rolling restart/pickup checkpoint file write interval ( s ) | 3084 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 5f61c21b01 Jeff*3085 | :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*3086 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3087 | :varlink:`pickupStrictlyMatch` | PARM03 | TRUE | force pickup (meta) file formats to exactly match (or terminate with error) on/off flag | 3088 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3089 | :varlink:`writePickupAtEnd` | PARM03 | FALSE | write a (rolling) pickup file at run completion on/off flag | 3090 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3091 | :varlink:`usePickupBeforeC54` | PARM01 | FALSE | initialize run using old pickup format from code prior to checkpoint54a | 3092 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3093 | :varlink:`startFromPickupAB2` | PARM03 | FALSE | using Adams-Bashforth-3, start using Adams-Bashforth-2 pickup format; | 3094 | | | | requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` | 3095 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3096 3097 Parameters Used In Optional Packages 3098 ------------------------------------ 3099 ba0b047096 Mart*3100 Some optional packages were not written with package-specific namelist 3101 parameters in a ``data.${pkg}`` file; or for historical and/or other reasons, 3102 several package-specific namelist parameters remain in ``data``. dcaaa42497 Jeff*3103 3104 .. _c-d_scheme: 3105 3106 C-D Scheme 3107 ~~~~~~~~~~ 3108 3109 (package :filelink:`pkg/cd_code`) 3110 3111 If you run at a sufficiently coarse resolution, you might choose to enable the 3112 C-D scheme for the computation of the Coriolis terms. The 3113 variable :varlink:`tauCD`, which represents the C-D scheme coupling 3114 timescale (in seconds) needs to be set. 3115 3116 .. tabularcolumns:: |\Y{.175}|\Y{.1}|\Y{.225}|\Y{.525}| 3117 3118 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3119 | Parameter | Group | Default | Description | 3120 +========================================+===========+==================================================+=========================================================================================================+ 3121 | :varlink:`useCDscheme` | PARM01 | FALSE | use C-D scheme for Coriolis terms on/off flag | 3122 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3123 | :varlink:`tauCD` | PARM03 | :varlink:`deltaTMom` | C-D scheme coupling timescale (s) | 3124 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3125 | :varlink:`rCD` | PARM03 | 1 - :varlink:`deltaTMom`/:varlink:`tauCD` | C-D scheme normalized coupling parameter (non-dim.) | 3126 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3127 | :varlink:`epsAB_CD` | PARM03 | :varlink:`abEps` | Adams-Bashforth-2 stabilizing weight used in C-D scheme | 3128 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3129 3130 Automatic Differentiation 3131 ~~~~~~~~~~~~~~~~~~~~~~~~~ 3132 3133 (package :filelink:`pkg/autodiff`; see :numref:`chap_autodiff`) 3134 3135 .. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}| 3136 3137 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3138 | Parameter | Group | Default | Description | 3139 +========================================+===========+==================================================+=========================================================================================================+ 3140 | :varlink:`nTimeSteps_l2` | PARM03 | 4 | number of inner timesteps to execute per timestep | 3141 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3142 | :varlink:`adjdumpFreq` | PARM03 | 0.0 | interval to write model state/snapshot data adjoint run (s) | 3143 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3144 | :varlink:`adjMonitorFreq` | PARM03 | 0.0 | interval to write monitor output adjoint run (s) | 3145 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3146 | :varlink:`adTapeDir` | PARM05 | :kbd:`' '` | if not blank, read-write checkpointing files from/to this directory name | 3147 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3148 3149 .. _eedata_parms: 3150 3151 Execution Environment Parameters 3152 -------------------------------- 3153 ba0b047096 Mart*3154 If running multi-threaded (i.e., using shared 3155 memory/`OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_), you will need to set 3156 :varlink:`nTx` and/or :varlink:`nTy` so that :varlink:`nTx`\ \*\ :varlink:`nTy` 3157 is the total number of threads (per process). dcaaa42497 Jeff*3158 ba0b047096 Mart*3159 The parameter :varlink:`useCubedSphereExchange` needs to be changed to 3160 ``.TRUE.`` if you are using any type of grid composed of interconnected 3161 individual faces, including the cubed sphere topology or a lat-lon cap grid. 3162 See (needs section to be written). dcaaa42497 Jeff*3163 ba0b047096 Mart*3164 Note that setting flag :varlink:`debugMode` to ``.TRUE.`` activates a separate 3165 set of debugging print statements than parameter :varlink:`debugLevel` 3166 (see :numref:`freq_of_output`). The latter controls print statements that 3167 monitor model activity (such as opening files, etc.), whereas the former 3168 produces a more coding-oriented set of print statements (e.g., entering and 3169 exiting subroutines, etc.) dcaaa42497 Jeff*3170 3171 .. tabularcolumns:: |\Y{.25}|\Y{.125}|\Y{.125}|\Y{.525}| 3172 3173 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3174 | Parameter | Group | Default | Description | 3175 +========================================+===========+==================================================+=========================================================================================================+ 3176 | :varlink:`useCubedSphereExchange` | EEPARMS | FALSE | use cubed-sphere topology domain on/off flag | 3177 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3178 | :varlink:`nTx` | EEPARMS | 1 | number of threads in the :math:`x` direction | 3179 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3180 | :varlink:`nTy` | EEPARMS | 1 | number of threads in the :math:`y` direction | 3181 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3182 | :varlink:`useCoupler` | EEPARMS | FALSE | communicate with other model components through a coupler on/off flag | 3183 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 3185.
3184 | :varlink:`useSETRLSTK` | EEPARMS | FALSE | call C routine to set environment stacksize to âunlimitedâ | 3185 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3186 | :varlink:`useSIGREG` | EEPARMS | FALSE | enable signal handler to receive signal to terminate run cleanly on/off flag | 3187 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 3189.
3188 | :varlink:`debugMode` | EEPARMS | FALSE | print additional debugging messages; also âflushâ STDOUT file unit after each print | 3189 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3190 | :varlink:`printMapIncludesZeros` | EEPARMS | FALSE | text map plots of fields should ignore exact zero values on/off flag | 3191 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 3192 | :varlink:`maxLengthPrt1D` | EEPARMS | 65 | maximum number of 1D array elements to print to standard output | 3193 +----------------------------------------+-----------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------+ 83cdbd2346 Jeff*3194 3195 .. _sec_mitgcm_inp_file_format: 3196 3197 MITgcm Input Data File Format 3198 ============================= 3199 ce0d9af5ea Jeff*3200 MITgcm input files for grid-related data (e.g., :varlink:`delXFile`), 3201 forcing fields (e.g., :varlink:`tauThetaClimRelax`), 3202 parameter fields (e.g., :varlink:`viscAhZfile`), etc. are assumed to 3203 be in "flat" or "unblocked" `binary format <https://en.wikipedia.org/wiki/Binary_file>`_. fbfa6b7fb7 Jody*3204 3205 Data is expected to be in 3206 `Fortran/column-major order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_, 3207 in the order (:math:`x`, :math:`y`, :math:`z`, :math:`t`). 3208 `MATLAB <https://www.mathworks.com/products/matlab.html>`_ typically 3209 uses F-order, while Python's `NumPy <https://numpy.org>`_ uses C-order (row-major order). 3210 3211 For historical reasons, many large MITgcm projects use big-endian ce0d9af5ea Jeff*3212 `byte ordering <https://en.wikipedia.org/wiki/Endianness>`_, 3213 **NOT** little-endian which is the more common default for today's computers. fbfa6b7fb7 Jody*3214 Thus, some care is required to create MITgcm-readable input files. However, if 3215 you prepare your own input files, it is perfectly fine to use little-endian so 3216 long as you also compile your executable to be little-endian compatible. 83cdbd2346 Jeff*3217 ce0d9af5ea Jeff*3218 - Using `MATLAB <https://www.mathworks.com/products/matlab.html>`_: 3219 When writing binary files, MATLAB's `fopen <https://www.mathworks.com/help/matlab/ref/fopen.html>`_ 3220 command includes a MACHINEFORMAT option ``'b'`` which instructs MATLAB 3221 to read or write using big-endian byte ordering. 2-D arrays should be fbfa6b7fb7 Jody*3222 index-ordered in MATLAB as (:math:`x`, :math:`y`), 3-D arrays as 3223 (:math:`x`, :math:`y`, :math:`z`), and 4-D arrays as 3224 (:math:`x`, :math:`y`, :math:`z`, :math:`t`); data is ordered from low to high in ce0d9af5ea Jeff*3225 each index, with :math:`x` varying most rapidly. 83cdbd2346 Jeff*3226 ce0d9af5ea Jeff*3227 An example to create a bathymetry file of single-precision, floating 3228 point values (from tutorial :ref:`sec_eg_baro`, a simple enclosed, 3229 flat-bottom domain) is as follows: 83cdbd2346 Jeff*3230 3231 :: 3232 ce0d9af5ea Jeff*3233 ieee = 'b'; % big-endian format 3234 accuracy = 'float32'; % this is single-precision (='real*4') 83cdbd2346 Jeff*3235 3236 Ho=5000; % ocean depth in meters ce0d9af5ea Jeff*3237 nx=62; % number of gridpoints in x-direction 3238 ny=62; % number of gridpoints in y-direction 83cdbd2346 Jeff*3239 ce0d9af5ea Jeff*3240 % Flat bottom at z = -Ho 3241 h = -Ho * ones(nx, ny); 83cdbd2346 Jeff*3242 ce0d9af5ea Jeff*3243 % Walls (surrounding domain) 3244 h([1 end], :) = 0; % set ocean depth to zero at east and west walls 3245 h(:, [1 end]) = 0; % set ocean depth to zero at south and north walls 83cdbd2346 Jeff*3246 ce0d9af5ea Jeff*3247 % save as single-precision (float32) with big-endian byte ordering 3248 fid = fopen('bathy.bin', 'w', ieee); 3249 fwrite(fid, h, accuracy); 3250 fclose(fid); 3251 3252 To read this bathymetry file back into MATLAB, reshaped back to (nx, ny): 83cdbd2346 Jeff*3253 3254 :: 3255 ce0d9af5ea Jeff*3256 fid = fopen('bathy.bin', 'r', ieee); 3257 h = reshape(fread(fid, Inf, accuracy), nx, ny); 3258 fclose(fid); 3259 fbfa6b7fb7 Jody*3260 - Using Python's `NumPy <https://numpy.org>`_: 83cdbd2346 Jeff*3261 fbfa6b7fb7 Jody*3262 The `tofile <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.tofile.html>`_ 3263 method on a NumPy array writes the data in 3264 `row-major or C-order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_, 3265 so arrays should be shaped to take this into account for the MITgcm: 3266 (:math:`y`, :math:`x`) for 2-D, (:math:`z`, :math:`y`, :math:`x`) for 3-D, and 3267 (:math:`t`, :math:`z`, :math:`y`, :math:`x`) for 4-D. 3268 3269 A python version of the above script can use NumPy to create a bathymetry file is as 3270 follows: 83cdbd2346 Jeff*3271 3272 :: 3273 ce0d9af5ea Jeff*3274 import numpy as np 83cdbd2346 Jeff*3275 ce0d9af5ea Jeff*3276 Ho = 5000 # ocean depth in meters 3277 nx = 62 # number of gridpoints in x-direction 3278 ny = 62 # number of gridpoints in y-direction 83cdbd2346 Jeff*3279 ce0d9af5ea Jeff*3280 # Flat bottom at z = -Ho 3281 h = -Ho * np.ones((ny, nx)) 3282 3283 # Walls (surrounding domain) 3284 h[:, [0,-1]] = 0 # set ocean depth to zero at east and west walls 3285 h[[0,-1], :] = 0 # set ocean depth to zero at south and north walls 3286 3287 # save as single-precision (NumPy type float32) with big-endian byte ordering 3288 h.astype('>f4').tofile('bathy.bin') 3289 fbfa6b7fb7 Jody*3290 The dtype specification ``'>f4'`` above instructs NumPy to write the file with ce0d9af5ea Jeff*3291 big-endian byte ordering (specifically, due to the '>') as single-precision real 3292 numbers (due to the 'f4' which is NumPy ``float32`` or equivalently, 3293 Fortran ``real*4`` format). 3294 fbfa6b7fb7 Jody*3295 To read this bathymetry file back into NumPy, reshaped back to (ny, nx): 83cdbd2346 Jeff*3296 3297 :: 3298 ce0d9af5ea Jeff*3299 h = np.fromfile('bathy.bin', '>f4').reshape(ny, nx) 83cdbd2346 Jeff*3300 fbfa6b7fb7 Jody*3301 where again the dtype spec instructs NumPy to read a big-endian ce0d9af5ea Jeff*3302 file of single-precision, floating point values. 83cdbd2346 Jeff*3303 ce0d9af5ea Jeff*3304 A more complicated example of using Python to generate input date is provided in 3305 :filelink:`verification/tutorial_baroclinic_gyre/input/gendata.py`. 83cdbd2346 Jeff*3306 3307 - Using `Fortran <https://en.wikipedia.org/wiki/Fortran>`_: ce0d9af5ea Jeff*3308 To create flat binary files in Fortran, open with 3309 syntax ``OPEN(..., ACCESS='DIRECT', ...)`` (i.e., **NOT** ``ACCESS='SEQUENTIAL'`` 3310 which includes additional metadata). By default Fortran will use the 3311 local computer system's native byte ordering for reading and writing binary files, 83cdbd2346 Jeff*3312 which for most systems will be little-endian. One therefore has two options: ce0d9af5ea Jeff*3313 after creating a binary file in Fortran, use MATLAB or Python (or some 3314 other utility) to read in and swap the bytes in the process of writing a new file; 3315 or, determine if your local Fortran has 3316 a compiler flag to control byte-ordering of binary files. 3317 Similar to MATLAB, 2-D and 3-D arrays in Fortran should be index-ordered 3318 as (:math:`x`, :math:`y`) and (:math:`x`, :math:`y`, :math:`z`), respectively. ba0b047096 Mart*3319 ce0d9af5ea Jeff*3320 Using `NetCDF <http://www.unidata.ucar.edu/software/netcdf>`_ format for input files is only 3321 partially implemented at present in MITgcm, and use is thus discouraged. ba0b047096 Mart*3322 3323 Input files are by default single-precision real numbers (32-bit, ``real*4``), ce0d9af5ea Jeff*3324 but can be switched to double precision by setting 3325 namelist parameter :varlink:`readBinaryPrec` (``PARM01`` in file ``data``) 3326 to a value of 64.
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated from https://github.com/darwinproject/darwin3 by the 2.3.7-MITgcm-0.1 LXR engine. The LXR team |
|