This chapter is divided into two main parts. The first part, which is covered in sections :numref:`whereToFindInfo` through :numref:`run_the_model`, contains information about how to download, build and run MITgcm. We believe the best way to familiarize yourself with the model is to run one of the tutorial examples provided in the MITgcm repository (see :numref:`chap_modelExamples`), so would suggest newer MITgcm users jump there following a read-through of the first part of this chapter. Information is also provided in this chapter on how to customize the code when you are ready to try implementing the configuration you have in mind, in the second part (:numref:`customize_model`). The code and algorithm are described more fully in :numref:`discret_algorithm` and :numref:`sarch` and chapters thereafter.
In this chapter and others (e.g., chapter :ref:`chap_contributing`),
for arguments where the user is expected to replace the text
with a user-chosen name, userid, etc., our convention
is to show these as upper-case
text surrounded by « »
, such as «USER_MUST_REPLACE_TEXT_HERE»
.
The «
and »
characters are NOT typed when the text is replaced.
There is a web-archived support mailing list for the model that you can email at MITgcm-support@mitgcm.org once you have subscribed.
To sign up (subscribe) for the mailing list (highly recommended), click here
To browse through the support archive, click here
The MITgcm code and documentation are under continuous development and we generally recommend that one downloads the latest version of the code. You will need to decide if you want to work in a “git-aware” environment (Method 1) or with a one-time “stagnant” download (Method 2). We generally recommend method 1, as it is more flexible and allows your version of the code to be regularly updated as MITgcm developers check in bug fixes and new features. However, this typically requires at minimum a rudimentary understanding of git in order to make it worth one’s while.
Periodically we release an official checkpoint (or “tag”). We recommend one download the latest code, unless there are reasons for obtaining a specific checkpoint (e.g. duplicating older results, collaborating with someone using an older release, etc.)
This section describes how to download git-aware copies of the repository. In a terminal window, cd to the directory where you want your code to reside. Type:
% git clone https://github.com/MITgcm/MITgcm.git
This will download the latest available code. If you now want to revert this
code to a specific checkpoint release, first cd
into the MITgcm directory
you just downloaded, then type git checkout checkpoint«XXX»
where «XXX»
is the checkpoint version.
Alternatively, if you prefer to use ssh keys (say for example, you have a firewall which won’t allow a https download), type:
% git clone git@github.com:MITgcm/MITgcm.git
You will need a GitHub account for this, and will have to generate a ssh key though your GitHub account user settings.
The fully git-aware download is over several hundred MB, which is considerable
if one has limited internet download speed. In comparison, the one-time
download zip file (Method 2, below) is order 100 MB. However, one can
obtain a truncated, yet still git-aware copy of the current code by adding
the option --depth=1
to the git clone command above; all files will be
present, but it will not include the full git history. However, the repository
can be updated going forward.
This section describes how to do a one-time download of MITgcm, NOT git-aware.
In a terminal window, cd
to the directory where
you want your code to reside. To obtain the current code, type:
% wget https://github.com/MITgcm/MITgcm/archive/master.zip
For specific checkpoint release XXX
, instead type:
% wget https://github.com/MITgcm/MITgcm/archive/checkpoint«XXX».zip
There are several different approaches one can use to obtain updates to MITgcm; which is best for you depends a bit on how you intend to use MITgcm and your knowledge of git (and/or willingness to learn). Below we outline three suggested update pathways:
- Fresh Download of MITgcm
This approach is the most simple, and virtually foolproof. Whether you downloaded the code from a static zip file (Method 2) or used the git clone command (Method 1), create a new directory and repeat this procedure to download a current copy of MITgcm. Say for example you are starting a new research project, this would be a great time to grab the most recent code repository and keep this new work entirely separate from any past simulations. This approach requires no understanding of git, and you are free to make changes to any files in the MIT repo tree (although we generally recommend that you avoid doing so, instead working in new subdirectories or on separate scratch disks as described :ref:`here <build_elsewhere>`, for example).
- Using
git pull
to update the (unmodified) MITgcm repo tree
If you have downloaded the code through a git clone command (Method 1 above), you can incorporate any changes to the source code (including any changes to any files in the MITgcm repository, new packages or analysis routines, etc.) that may have occurred since your original download. There is a simple command to bring all code in the repository to a ‘current release’ state. From the MITgcm top directory or any of its subdirectories, type:
% git pull
and all files will be updated to match the current state of the code
repository, as it exists at GitHub.
(Note: if you plan to contribute to MITgcm and followed the steps to
download the code as described in :numref:`chap_contributing`,
you will need to type git pull upstream
instead.)
This update pathway is ideal if you are in the midst of a project and you want to incorporate new MITgcm features into your executable(s), or take advantage of recently added analysis utilties, etc. After the git pull, any changes in model source code and include files will be updated, so you can repeat the build procedure (:numref:`building_code`) and you will include all these new features in your new executable.
Be forewarned, this will only work if you have not modified ANY of the
files in the MITgcm repository (adding new files is ok; also, all
verification run subdirectories build
and run
are also ignored by git).
If you have modified files and the git pull
fails with errors,
there is no easy fix other than to learn something
about git (continue reading...)
- Fully embracing the power of git!
Git offers many tools to help organize and track changes in your work.
For example, one might keep separate projects on different branches,
and update the code separately (using git pull
) on these separate branches.
You can even make changes to code in the MIT repo tree; when git then
tries to update code from upstream (see :numref:`git_setup`), it will notify
you about possible conflicts and even merge the code changes
together if it can. You can also use git commit
to help you track what
you are modifying in your simulations over time. If you're planning to
submit a pull request to include your changes, you should read the
contributing guide in :numref:`chap_contributing`, and we suggest you do
this model development in a separate, fresh copy of the code. See
:numref:`using_git_and_github` for more information and how
to use git effectively to manage your workflow.
The “numerical” model is contained within a execution environment support wrapper. This wrapper is designed to provide a general framework for grid-point models; MITgcm is a specific numerical model that makes use of this framework (see :numref:`wrapper` for additional detail). Under this structure, the model is split into execution environment support code and conventional numerical model code. The execution environment support code is held under the :filelink:`eesupp` directory. The grid point model code is held under the :filelink:`model` directory. Code execution actually starts in the :filelink:`eesupp` routines and not in the :filelink:`model` routines. For this reason the top-level :filelink:`main.F <eesupp/src/main.F>` is in the :filelink:`eesupp/src` directory. In general, end-users should not need to worry about the wrapper support code. The top-level routine for the numerical part of the code is in :filelink:`model/src/the_model_main.F`. Here is a brief description of the directory structure of the model under the root tree.
- :filelink:`model`: this directory contains the main source code. Also subdivided into two subdirectories: :filelink:`model/inc` (includes files) and :filelink:`model/src` (source code).
- :filelink:`eesupp`: contains the execution environment source code. Also subdivided into two subdirectories: :filelink:`eesupp/inc` and :filelink:`eesupp/src`.
- :filelink:`pkg`: contains the source code for the packages. Each package corresponds to a subdirectory. For example, :filelink:`pkg/gmredi` contains the code related to the Gent-McWilliams/Redi scheme, :filelink:`pkg/seaice` the code for a dynamic seaice model which can be coupled to the ocean model. The packages are described in detail in :numref:`packagesI` and :numref:`outp_pack`].
- :filelink:`doc`: contains MITgcm documentation in reStructured Text (rst) format.
- :filelink:`tools`: this directory contains various useful tools. For example, :filelink:`genmake2 <tools/genmake2>` is a script written in bash that should be used to generate your makefile. The subdirectory :filelink:`tools/build_options` contains ‘optfiles’ with the compiler options for many different compilers and machines that can run MITgcm (see :numref:`genmake2_optfiles`). This directory also contains subdirectories :filelink:`tools/adjoint_options` and :filelink:`tools/OAD_support` that are used to generate the tangent linear and adjoint model (see details in :numref:`chap_autodiff`).
- :filelink:`utils`: this directory contains various utilities. The :filelink:`utils/matlab` subdirectory contains matlab scripts for reading model output directly into matlab. The subdirectory :filelink:`utils/python` contains similar routines for python. :filelink:`utils/scripts` contains C-shell post-processing scripts for joining processor-based and tiled-based model output.
- :filelink:`verification`: this directory contains the model examples. See :numref:`chap_modelExamples`.
- :filelink:`jobs`: contains sample job scripts for running MITgcm.
- :filelink:`lsopt`: Line search code used for optimization.
- :filelink:`optim`: Interface between MITgcm and line search code.
To compile the code, we use the make
program. This uses a file
(Makefile
) that allows us to pre-process source files, specify
compiler and optimization options and also figures out any file
dependencies. We supply a script (:filelink:`genmake2 <tools/genmake2>`),
described in section :numref:`genmake2_desc`, that automatically generates
the Makefile
for you. You then need to build the dependencies and
compile the code (:numref:`make_target_commands`).
As an example, assume that you want to build and run experiment :filelink:`verification/exp2`. Let’s build the code in :filelink:`verification/exp2/build`:
% cd verification/exp2/build
First, generate the Makefile
:
% ../../../tools/genmake2 -mods ../code -optfile «/PATH/TO/OPTFILE»
The -mods
command line option tells :filelink:`genmake2 <tools/genmake2>`
to override model source code with any files in the subdirectory ../code
(here, you need to configure the size of the model domain by overriding
MITgcm’s default :filelink:`SIZE.h <model/inc/SIZE.h>`
with an edited copy :filelink:`../code/SIZE.h <verification/exp2/code/SIZE.h>`
containing the specific domain size for :filelink:`exp2 <verification/exp2>`).
The -optfile
command line option tells :filelink:`genmake2 <tools/genmake2>`
to run the specified
:ref:`optfile <genmake2_optfiles>`, a bash
shell script, during :filelink:`genmake2 <tools/genmake2>`’s execution.
An :ref:`optfile <genmake2_optfiles>` typically contains
definitions of
environment variables,
paths, compiler options, and anything else that needs to be set in order
to compile on your local computer system or cluster with your specific
Fortan compiler. As an example, we might replace «/PATH/TO/OPTFILE»
with
:filelink:`../../../tools/build_options/linux_amd64_ifort11 <tools/build_options/linux_amd64_ifort11>`
for use with the
Intel Fortran compiler
(version 11 and above) on a linux x86_64 platform.
This and many other :ref:`optfiles <genmake2_optfiles>` for common systems
and Fortran compilers are located in :filelink:`tools/build_options`.
-mods
, -optfile
, and many additional
:filelink:`genmake2 <tools/genmake2>` command line options are described
more fully in :numref:`command_line_options`. Detailed instructions on
building with
MPI
are given in :numref:`build_mpi`.
Once a Makefile
has been generated, we create the dependencies with
the command:
% make depend
It is important to note that the make depend
stage will occasionally
produce warnings or errors if the dependency parsing tool is unable
to find all of the necessary header files (e.g., netcdf.inc
, or worse,
say it cannot find a Fortran compiler in your path). In some cases you
may need to obtain help from your system administrator to locate these files.
Next, one can compile the code using:
% make
Assuming no errors occurred, the make
command creates
an executable called mitgcmuv
.
Now you are ready to run the model. General instructions for doing so are given in section :numref:`run_the_model`.
A shell script called genmake2
for generating a Makefile
is
included as part of MITgcm.
Typically genmake2
is used in a sequence of steps as shown below:
% ../../../tools/genmake2 -mods ../code -optfile «/PATH/TO/OPTFILE» % make depend % make
The first step above creates a unix-style Makefile
. The Makefile
is used by make
to specify how to compile the MITgcm source files
(for more detailed descriptions of what the make
tools
are, and how they are used, see
here).
This section describes details and capabilities of
:filelink:`genmake2 <tools/genmake2>`, located in the
:filelink:`tools` directory. :filelink:`genmake2 <tools/genmake2>` is a shell
script written to work in
bash (and with all
“sh”–compatible shells including
Bourne shells).
Like many unix tools, there is a help option that is invoked
thru genmake2 -h
. :filelink:`genmake2 <tools/genmake2>` parses
information from the following sources, in this order:
- Command-line options (see :numref:`command_line_options`)
- A
genmake_local
file if one is found in the current directory. This is a bash shell script that is executed prior to the :ref:`optfile <genmake2_optfiles>` (see step #3), used in some special model configurations and/or to set some options that can affect which lines of the :ref:`optfile <genmake2_optfiles>` are executed. For example, this :filelink:`genmake_local <verification/cpl_aim+ocn/build_cpl/genmake_local>` file is required for a special setup, building a ‘MITgcm coupler’ executable; in a more typical setup, one will not require agenmake_local
file. - An “options file” a.k.a. :ref:`optfile <genmake2_optfiles>`
(a bash shell
script) specified by the command-line option
–optfile «/PATH/TO/OPTFILE»
, as mentioned briefly in :numref:`building_quickstart` and described in detail in :numref:`genmake2_optfiles`. - A
packages.conf
file (if one is found) with the specific list of packages to compile (see :numref:`using_packages`). The search path for filepackages.conf
is first the current directory, and then each of the-mods
directories in the given order (as described :ref:`here <mods_option>`).
When you run the :filelink:`genmake2 <tools/genmake2>` script, typical output might be as follows:
% ../../../tools/genmake2 -mods ../code -optfile ../../../tools/build_options/linux_amd64_gfortran GENMAKE : A program for GENerating MAKEfiles for the MITgcm project. For a quick list of options, use "genmake2 -h" or for more detail see the documentation, section "Building the model" (under "Getting Started") at: https://mitgcm.readthedocs.io/ === Processing options files and arguments === getting local config information: none found Warning: ROOTDIR was not specified ; try using a local copy of MITgcm found at "../../.." getting OPTFILE information: using OPTFILE="../../../tools/build_options/linux_amd64_gfortran" getting AD_OPTFILE information: using AD_OPTFILE="../../../tools/adjoint_options/adjoint_default" check Fortran Compiler... pass (set FC_CHECK=5/5) check makedepend (local: 0, system: 1, 1) === Checking system libraries === Do we have the system() command using gfortran... yes Do we have the fdate() command using gfortran... yes Do we have the etime() command using gfortran... c,r: yes (SbR) Can we call simple C routines (here, "cloc()") using gfortran... yes Can we unlimit the stack size using gfortran... yes Can we register a signal handler using gfortran... yes Can we use stat() through C calls... yes Can we create NetCDF-enabled binaries... yes skip check for LAPACK Libs Can we call FLUSH intrinsic subroutine... yes === Setting defaults === Adding MODS directories: ../code Making source files in eesupp from templates Making source files in pkg/exch2 from templates Making source files in pkg/regrid from templates === Determining package settings === getting package dependency info from ../../../pkg/pkg_depend getting package groups info from ../../../pkg/pkg_groups checking list of packages to compile: using PKG_LIST="../code/packages.conf" before group expansion packages are: oceanic -kpp -gmredi cd_code replacing "oceanic" with: gfd gmredi kpp replacing "gfd" with: mom_common mom_fluxform mom_vecinv generic_advdiff debug mdsio rw monitor after group expansion packages are: mom_common mom_fluxform mom_vecinv generic_advdiff debug mdsio rw monitor gmredi kpp -kpp -gmredi cd_code applying DISABLE settings applying ENABLE settings packages are: cd_code debug generic_advdiff mdsio mom_common mom_fluxform mom_vecinv monitor rw applying package dependency rules packages are: cd_code debug generic_advdiff mdsio mom_common mom_fluxform mom_vecinv monitor rw Adding STANDARDDIRS='eesupp model' Searching for *OPTIONS.h files in order to warn about the presence of "#define "-type statements that are no longer allowed: found CPP_EEOPTIONS="../../../eesupp/inc/CPP_EEOPTIONS.h" found CPP_OPTIONS="../../../model/inc/CPP_OPTIONS.h" Creating the list of files for the adjoint compiler. === Creating the Makefile === setting INCLUDES Determining the list of source and include files Writing makefile: Makefile Add the source list for AD code generation Making list of "exceptions" that need ".p" files Making list of NOOPTFILES Add rules for links Adding makedepend marker === Done === original 'Makefile' generated successfully => next steps: > make depend > make (<-- to generate executable)
In the above, notice:
- we did not specify
ROOTDIR
, i.e., a path to your MITgcm repository, but here we are building code from within the repository (specifically, in one of the verification subdirectory experiments). As such, :filelink:`genmake2 <tools/genmake2>` was smart enough to locate all necessary files on its own. To specify a remoteROOTDIR
, see :ref:`here <build_elsewhere>`. - we specified the :ref:`optfile <genmake2_optfiles>` :filelink:`linux_amd64_gfortran <tools/build_options/linux_amd64_gfortran>` based on the computer system and Fortran compiler we used (here, a linux 64-bit machine with gfortran installed).
- :filelink:`genmake2 <tools/genmake2>` did
some simple checking on availability
of certain system libraries; all were found (except
LAPACK,
which was not checked since it is not needed here).
NetCDF only requires a ‘yes’
if you want to write netCDF
output; more specifically, a ‘no’ response to “Can we create NetCDF-enabled
binaries” will disable including :filelink:`pkg/mnc` and switch to output
plain binary files. While the makefile can still be built with other
‘no’ responses, sometimes this will foretell errors during the
make depend
ormake
commands. - any
.F
or.h
files in the-mods
directory../code
will also be compiled, overriding any MITgcm repository versions of files, if they exist. - a handful of packages are being used in this build; see :numref:`using_packages` for more detail about how to enable and disable packages.
- :filelink:`genmake2 <tools/genmake2>` terminated without error
(note output at end after
=== Done ===
), generatingMakefile
and a log filegenmake.log
. As mentioned, this does not guarantee that your setup will compile properly, but if there are errors duringmake depend
ormake
, these error messages and/or the standard output from :filelink:`genmake2 <tools/genmake2>` orgenmake.log
may provide clues as to the problem. If instead :filelink:`genmake2 <tools/genmake2>` finishes with a warning messageWarning: FORTRAN compiler test failed
, this means that :filelink:`genmake2 <tools/genmake2>` is unable to locate the Fortran compiler or pass a trivial “hello world” Fortran compilation test. In this case, you should seegenmake.log
for errors and/or seek assistance from your system administrator; these tests need to pass in order to proceed to themake
steps.
:filelink:`genmake2 <tools/genmake2>` supports a number of helpful command-line options. A complete list of these options can be obtained by:
% genmake2 -h
The most important command-line options are:
–optfile «/PATH/TO/OPTFILE»
(or shorter:
-of
) specifies the :ref:`optfile <genmake2_optfiles>` that should be used for a particular build.If no :ref:`optfile <genmake2_optfiles>` is specified through the command line, :filelink:`genmake2 <tools/genmake2>` will try to make a reasonable guess from the list provided in :filelink:`tools/build_options`. The method used for making this guess is to first determine the combination of operating system and hardware and then find a working Fortran compiler within the user’s path. When these three items have been identified, :filelink:`genmake2 <tools/genmake2>` will try to find an :ref:`optfile <genmake2_optfiles>` that has a matching name. See :numref:`genmake2_optfiles`.
–mods '«DIR1 DIR2 DIR3 ...»'
specifies a list of directories containing “modifications”. These directories contain files with names that may (or may not) exist in the main MITgcm source tree but will be overridden by any identically-named sources within the
-mods
directories. Note the quotes around the list of directories, necessary given multiple arguments.The order of precedence for versions of files with identical names:
- “mods” directories in the order given (e.g., will use copy of file located in DIR1 instead of DIR2)
- Packages either explicitly specified or included by default
- Packages included due to package dependencies
- The “standard dirs” (which may have been specified by the
-standarddirs
option below)
-rootdir «/PATH/TO/MITGCMDIR»
specify the location of the MITgcm repository top directory (
ROOTDIR
). By default, :filelink:`genmake2 <tools/genmake2>` will try to find this location by looking in parent directories from where :filelink:`genmake2 <tools/genmake2>` is executed (up to 5 directory levels above the current directory).In the quickstart example above (:numref:`building_quickstart`) we built the executable in the
build
directory of the experiment. Below, we show how to configure and compile the code on a scratch disk, without having to copy the entire source tree. The only requirement is that you have :filelink:`genmake2 <tools/genmake2>` in your $PATH, or you know the absolute path to :filelink:`genmake2 <tools/genmake2>`. In general, one can compile the code in any given directory by following this procedure. Assuming the model source is in~/MITgcm
, then the following commands will build the model in/scratch/exp2-run1
:% cd /scratch/exp2-run1 % ~/MITgcm/tools/genmake2 -rootdir ~/MITgcm -mods ~/MITgcm/verification/exp2/code % make depend % make
As an alternative to specifying the MITgcm repository location through the
-rootdir
command-line option, :filelink:`genmake2 <tools/genmake2>` recognizes the environment variable$MITGCM_ROOTDIR
.-standarddirs «/PATH/TO/STANDARDDIR»
- specify a path to the standard MITgcm directories for source and includes
files. By default, :filelink:`model` and :filelink:`eesupp`
directories (
src
andinc
) are the “standard dirs”. This command can be used to reset these default standard directories, or instead NOT include either :filelink:`model` or :filelink:`eesupp` as done in some specialized configurations. -oad
- generates a makefile for an OpenAD build (see :numref:`ad_openad`)
–adoptfile «/PATH/TO/FILE»
(or shorter:
-adof
) specifies the “adjoint” or automatic differentiation options file to be used. The file is analogous to the optfile defined above but it specifies information for the AD build process. See :numref:`adoptfile`.The default file is located in :filelink:`tools/adjoint_options/adjoint_default` and it defines the “TAF” and “TAMC” compiler options.
–mpi
- enables certain
MPI
features (using CPP
#define
) within the code and is necessary for MPI builds (see :numref:`build_mpi`). –omp
- enables OpenMP code and compiler flag
OMPFLAG
(see :numref:`build_openmp`). –ieee
- use IEEE numerics (requires support in optfile). This option is typically a good choice if one wants to compare output from different machines running the same code. Note using IEEE disables all compiler optimizations.
-devel
- use IEEE numerics (requires support in optfile) and add additional compiler options to check array bounds and add other additional warning and debugging flags.
–make «/PATH/TO/GMAKE»
- due to the poor handling of soft-links and other bugs common with
the
make
versions provided by commercial unix vendors, GNUmake
(sometimes calledgmake
) may be preferred. This option provides a means for specifying the make executable to be used.
While it is possible to use :filelink:`genmake2 <tools/genmake2>` command-line
options to set the Fortran or C compiler name (-fc
and -cc
respectively), we generally recommend setting these through an
:ref:`optfile <genmake2_optfiles>`, as discussed in :numref:`genmake2_optfiles`.
Other :filelink:`genmake2 <tools/genmake2>` options are available to
enable performance/timing analyses, etc.; see genmake2 -h
for more info.
The purpose of the optfiles is to provide all the compilation options for particular “platforms” (where “platform” roughly means the combination of the hardware and the compiler) and code configurations. Given the combinations of possible compilers and library dependencies (e.g., MPI or netCDF) there may be numerous optfiles available for a single machine. The naming scheme for the majority of the optfiles shipped with the code is OS_HARDWARE_COMPILER where
- OS
- is the name of the operating system (generally the lower-case output
of a linux terminal
uname
command) - HARDWARE
is a string that describes the CPU type and corresponds to output from a
uname -m
command. Some common CPU types:amd64
- use this code for x86_64 systems (most common, including AMD and Intel 64-bit CPUs)
ia64
- is for Intel IA64 systems (eg. Itanium, Itanium2)
ppc
- is for (old) Mac PowerPC systems
- COMPILER
- is the compiler name (generally, the name of the Fortran compiler executable). MITgcm is primarily written in FORTRAN 77. Compiling the code requires a FORTRAN 77 compiler. Any more recent compiler which is backwards compatible with FORTRAN 77 can also be used; for example, the model will build successfully with a Fortran 90 or Fortran 95 compiler. A C99 compatible compiler is also need, together with a C preprocessor . Some optional packages make use of Fortran 90 constructs (either free-form formatting, or dynamic memory allocation); as such, setups which use these packages require a Fortran 90 or later compiler build.
There are existing optfiles that work with many common hardware/compiler configurations; we first suggest you peruse the list in :filelink:`tools/build_options` and try to find your platform/compiler configuration. These are the most common:
- :filelink:`linux_amd64_gfortran <tools/build_options/linux_amd64_gfortran>`
- :filelink:`linux_amd64_ifort11 <tools/build_options/linux_amd64_ifort11>`
- :filelink:`linux_amd64_ifort+impi <tools/build_options/linux_amd64_ifort+impi>`
- :filelink:`linux_amd64_pgf77 <tools/build_options/linux_amd64_pgf77>`
The above optfiles are all for linux x86_64 (64-bit) systems, utilized in many
large high-performance computing centers. All of the above will work with
single-threaded,
MPI,
or shared memory (OpenMP) code
configurations. gfortran is GNU Fortran,
ifort is Intel Fortran,
pgf77 is PGI Fortran (formerly known as
“The Portland Group”). Note in the above list there are two ifort
optfiles:
:filelink:`linux_amd64_ifort+impi <tools/build_options/linux_amd64_ifort+impi>`
is for a specific case of using ifort
with the
Intel MPI library
(a.k.a. impi
), which requires special define statements in the optfile
(in contrast with Open MPI or
MVAPICH2 libraries;
see :numref:`build_mpi`). Note that both ifort optfiles require ifort
version 11 or higher. Many clusters nowadays use
environment modules,
which allows one to easily choose which compiler to use through
module load «MODULENAME»
, automatically configuring your environment
for a specific compiler choice (type echo $PATH
to see where
:filelink:`genmake2 <tools/genmake2>` will look for compilers
and system software).
In most cases, your platform configuration will be included in the available
optfiles :filelink:`list <tools/build_options/>` and will result in a
usable Makefile
being generated. If you are unsure which optfile is
correct for your configuration, you can try not specifying an optfile;
on some systems the :filelink:`genmake2 <tools/genmake2>` program will be able
to automatically recognize the hardware, find a compiler and other tools
within the user’s path, and then make a best guess as to an appropriate optfile
from the list in the :filelink:`tools/build_options` directory.
However, for some platforms and code configurations, new
optfiles must be written. To create a new optfile, it is generally
best to start with one of the defaults and modify it to suit your needs.
Like
:filelink:`genmake2 <tools/genmake2>`, the optfiles are all written in bash
(or using a simple
sh–compatible syntax).
While nearly all
environment variables
used within :filelink:`genmake2 <tools/genmake2>` may be specified in the
optfiles, the critical ones that should be defined are:
FC
- the Fortran compiler (executable) to use on
.F
files, e.g.,ifort
orgfortran
, or if using MPI, the mpi-wrapper equivalent, e.g.,mpif77
F90C
- the Fortran compiler to use on
.F90
files (only necessary if your setup includes a package which contains.F90
source code) CC
- similarly, the C compiler to use, e.g.,
icc
orgcc
, or if using MPI, the mpi-wrapper equivalent, e.g.,mpicc
DEFINES
- command-line options passed to the compiler
CPP
- the C preprocessor to use, and any necessary command-line options,
e.g.
cpp -traditional -P
CFLAGS
,FFLAGS
- command-line compiler flags required for your C and Fortran compilers, respectively, to compile and execute properly. See your C and Fortran compiler documentation for specific options and syntax.
FOPTIM
- command-line optimization Fortran compiler settings. See your Fortran compiler documentation for specific options and syntax.
NOOPTFLAGS
- command-line settings for special files that should not be optimized
using the
FOPTIM
flags NOOPTFILES
- list of source code files that should be compiled using
NOOPTFLAGS
settings INCLUDES
- path for additional files (e.g.,
netcdf.inc
,mpif.h
) to include in the compilation using the command-line-I
option INCLUDEDIRS
- path for additional files to be included in the compilation
LIBS
- path for additional library files that need to be linked to generate the
final executable, e.g.,
libnetcdf.a
For example, an excerpt from an optfile which specifies several of these variables (here, for the linux-amd64 architecture using the PGI Fortran compiler) is as follows:
.. literalinclude:: ../../tools/build_options/linux_amd64_pgf77 :start-at: if test "x$MPI" = xtrue ; then :end-at: F90OPTIM=$FOPTIM
The :ref:`above <list_of_optfile_env_vars>` list of environment variables typically specified in an optfile is by no means complete; additional variables may be required for your specific setup and/or your specific Fortran (or C) compiler.
If you write an optfile for an unrepresented machine or compiler, you are strongly encouraged to submit the optfile to the MITgcm project for inclusion. MITgcm developers are willing to provide help writing or modifing optfiles. Please submit the file through the GitHub issue tracker or email the MITgcm-support@mitgcm.org list.
Instructions on how to use optfiles to build MPI-enabled executables is presented in :numref:`build_mpi`.
Following a successful build of Makefile
, type make depend
. This
command modifies the Makefile
by attaching a (usually, long) list of
files upon which other files depend. The purpose of this is to reduce
re-compilation if and when you start to modify the code. The make depend
command also creates local links for all source files from the source
directories (see "-mods" description in :numref:`command_line_options`),
so that all source files to be used are visible from the local build directory,
either as hardcopy or as symbolic link.
IMPORTANT NOTE: Editing the source code files in the build directory
will not edit a local copy (since these are just links) but will
edit the original files in :filelink:`model/src` (or :filelink:`model/inc`)
or in the specified -mods
directory. While the latter might
be what you intend, editing the master copy in :filelink:`model/src`
is usually NOT what is intended and may cause grief somewhere down
the road. Rather, if you need to add
to the list of modified source code files, place a copy of
the file(s) to edit in the -mods
directory, make the edits to
these -mods
directory files, go back to the build directory and
type make Clean
, and then re-build the makefile (these latter steps
critical or the makefile will not link to this newly edited file).
The final make
invokes the
C preprocessor
to produce the “little f” files (*.f
and *.f90
) and then compiles them
to object code using the specified Fortran compiler and options.
The C preprocessor step converts a number of CPP macros and #ifdef
statements to actual Fortran and expands C-style #include
statements to
incorporate header files into the “little f" files. CPP style macros and
#ifdef
statements are used to support generating
different compile code for different model configurations.
The result of the build process is an executable with the name mitgcmuv
.
Additional make “targets” are defined within the makefile to aid in the production of adjoint (:numref:`building_adcode_using_taf`) and other versions of MITgcm.
On computers with multiple processor cores, the build process can often be sped up appreciably using the command:
% make -j 2
where the “2” can be replaced with a number that corresponds to the number of cores (or discrete CPUs) available.
In addition, there are several housekeeping make clean
options that might
be useful:
make clean
removes files thatmake
generates (e.g., *.o and *.f files)make Clean
removes files and links generated bymake
andmake depend
; strongly recommended for “un-clean” directories which may contain the (perhaps partial) results of previous buildsmake CLEAN
removes pretty much everything, including any executables and output from :filelink:`genmake2 <tools/genmake2>`
Building MITgcm to use MPI libraries can be complicated due to the variety of different MPI implementations available, their dependencies or interactions with different compilers, and their often ad-hoc locations within file systems. For these reasons, its generally a good idea to start by finding and reading the documentation for your machine(s) and, if necessary, seeking help from your local systems administrator.
The steps for building MITgcm with MPI support are:
Make sure you have MPI libraries installed on your computer system or cluster. Different Fortran compilers (and different versions of a specific compiler) will generally require a custom version (of a MPI library) built specifically for it. On environment module-enabled clusters, one typically must first load a Fortran compiler, then specific MPI libraries for that compiler will become available to load. If libraries are not installed, MPI implementations and related tools are available including:
Ask you systems administrator for assistance in installing these libraries.
Determine the location of your MPI library “wrapper” Fortran compiler, e.g.,
mpif77
ormpifort
etc. which will be used instead of the name of the fortran compiler (gfortran
,ifort
,pgi77
etc.) to compile your code. Often the directory in which these wrappers are located will be automatically added to your $PATH environment variable when you perform amodule load «SOME_MPI_MODULE»
; thus, you will not need to do anything beyond the module load itself. If you are on a cluster that does not support environment modules, you may have to manually add this directory to your path, e.g., typePATH=$PATH:«ADD_ADDITIONAL_PATH_TO_MPI_WRAPPER_HERE»
in a bash shell.Determine the location of the includes file
mpif.h
and any other MPI-related includes files. Often these files will be located in a subdirectory off the main MPI libraryinclude/
. In all optfiles in :filelink:`tools/build_options`, it is assumed environment variable$MPI_INC_DIR
specifies this location;$MPI_INC_DIR
should be set in your terminal session prior to generating aMakefile
.Determine how many processors (i.e., CPU cores) you will be using in your run, and modify your configuration’s :filelink:`SIZE.h <model/inc/SIZE.h>` (located in a “modified code” directory, as specified in your :filelink:`genmake2 <tools/genmake2>` :ref:`command-line <command_line_options>`). In :filelink:`SIZE.h <model/inc/SIZE.h>`, you will need to set variables :varlink:`nPx`*:varlink:`nPy` to match the number of processors you will specify in your run script’s MITgcm execution statement (i.e., typically
mpirun
or some similar command, see :numref:`running_mpi`). Note that MITgcm does not use dynamic memory allocation (a feature of Fortran 90, not FORTRAN 77), so all array sizes, and hence the number of processors to be used in your MPI run, must be specified at compile-time in addition to run-time. More information about the MITgcm WRAPPER, domain decomposition, and how to configure :filelink:`SIZE.h <model/inc/SIZE.h>` can be found in :numref:`using_wrapper`.Build the code with the :filelink:`genmake2 <tools/genmake2>`
-mpi
option using commands such as:% ../../../tools/genmake2 -mods=../code -mpi -of=«/PATH/TO/OPTFILE» % make depend % make
Unlike MPI, which requires installation of additional software support
libraries, using shared memory
(OpenMP) for multi-threaded
executable builds can be accomplished simply through the
:filelink:`genmake2 <tools/genmake2>` command-line option -omp
:
% ../../../tools/genmake2 -mods=../code -omp -of=«/PATH/TO/OPTFILE» % make depend % make
While the most common optfiles specified in :numref:`genmake2_optfiles` include
support for the -omp
option, some optfiles in
:filelink:`tools/build_options` do not include support for multi-threaded
executable builds. Before using one of the less common optfiles,
check whether OMPFLAG
is defined.
Note that one does not need to specify the number of threads until runtime (see :numref:`running_openmp`). However, the default maximum number of threads in MITgcm is set to a (low) value of 4, so if you plan on more you will need to change this value in :filelink:`eesupp/inc/EEPARAMS.h` in your modified code directory.
If compilation finished successfully (:numref:`building_code`) then an
executable called mitgcmuv
will now exist in the
local (build
) directory.
To run the model as a single process (i.e., not in parallel) simply
type (assuming you are still in the build
directory):
% cd ../run % ln -s ../input/* . % cp ../build/mitgcmuv . % ./mitgcmuv
Here, we are making a link to all the support data files (in ../input/
)
needed by the MITgcm for this experiment, and then copying the executable from
the the build directory. The ./
in the last step is a safe-guard to make
sure you use the local executable in case you have others that might exist in
your $PATH
. The above command will spew out many lines of text output to
your screen. This output contains details such as parameter values as well as
diagnostics such as mean kinetic energy, largest CFL number, etc. It is
worth keeping this text output with the binary output so we normally
re-direct the stdout
stream as follows:
% ./mitgcmuv > output.txt
In the event that the model encounters an error and stops, it is very
helpful to include the last few line of this output.txt
file along
with the (stderr
) error message within any bug reports.
For the example experiment in :filelink:`verification/exp2`, an example of the
output is kept in :filelink:`verification/exp2/results/output.txt` for
comparison. You can compare your output.txt
with the corresponding one for
that experiment to check that your set-up indeed works. Congratulations!
Run the code with the appropriate MPI “run” or “exec” program provided with your particular implementation of MPI. Typical MPI packages such as Open MPI will use something like:
% mpirun -np 4 ./mitgcmuv
Sightly more complicated scripts may be needed for many machines since execution of the code may be controlled by both the MPI library and a job scheduling and queueing system such as Slurm, PBS/TORQUE, LoadLeveler, or any of a number of similar tools. See your local cluster documentation or system administrator for the specific syntax required to run on your computing facility.
Assuming the executable mitgcmuv
was built with OpenMP
(see :numref:`build_openmp`), the syntax to run a multi-threaded simulation is
the same as running single-threaded (see :numref:`run_the_model`), except that
the following additional steps are required beforehand:
- Environment variables
for the number of threads and the stacksize need to be set prior to
executing the model. The exact names of these
environment variables
differ by Fortran compiler, but are typically some variant of
OMP_NUM_THREADS
andOMP_STACKSIZE
, respectively. For the latter, in your run script we recommend adding the lineexport OMP_STACKSIZE=400M
(or for a C shell-variant,setenv OMP_STACKSIZE 400M
). If this stacksize setting is insufficient, MITgcm will crash, in which case a larger number can be used. Similarly,OMP_NUM_THREADS
should be set to the exact number of threads you require. - In file
eedata
you will need to change namelist parameters :varlink:`nTx` and :varlink:`nTy` to reflect the number of threads in x and y, respectively (for a single-threaded run, :varlink:`nTx` =:varlink:`nTy`=1). The value of :varlink:`nTx` *:varlink:`nTy` must equal the value of environment variableOMP_NUM_THREADS
(or its name-equivalent for your Fortan compiler) or MITgcm will terminate during its initialization with an error message.
MITgcm will take the number of tiles used in the model (as specified in
:filelink:`SIZE.h <model/inc/SIZE.h>`) and the number of threads
(:varlink:`nTx` and :varlink:`nTy` from file eedata
),
and in running will spread the tiles out evenly across the threads.
This is done independently for x and y. As such,
the number of tiles in x (variable :varlink:`nSx` as defined in
:filelink:`SIZE.h <model/inc/SIZE.h>`) must divide evenly by
the number of threads in x (namelist parameter :varlink:`nTx`),
and similarly for :varlink:`nSy` and :varlink:`nTy`, else MITgcm will
terminate on initialization. More information about the MITgcm
WRAPPER, domain decomposition, and how to configure
:filelink:`SIZE.h <model/inc/SIZE.h>` can be found in :numref:`using_wrapper`.
The model produces various output files and, when using :filelink:`pkg/mnc`
(i.e., netCDF),
sometimes even directories. Depending upon the I/O package(s) selected
at compile time (either :filelink:`pkg/mdsio`, :filelink:`pkg/mnc`, or both as
determined by packages.conf
) and the run-time flags set (in
data.pkg
), the following output may appear. More complete information
describing output files and model diagnostics is described
in :numref:`outp_pack`.
The “traditional” output files are generated by the :filelink:`pkg/mdsio`
(see :numref:`pkg_mdsio`).The :filelink:`pkg/mdsio` model data are written
according to a “meta/data” file format. Each variable is associated with two
files with suffix names .data
and .meta
. The .data
file contains
the data written in binary form (big endian by default). The .meta
file
is a “header” file that contains information about the size and the
structure of the .data
file. This way of organizing the output is
particularly useful when running multi-processors calculations.
At a minimum, the instantaneous “state” of the model is written out, which is made of the following files:
U.00000nIter
- zonal component of velocity field (m/s and positive eastward).V.00000nIter
- meridional component of velocity field (m/s and positive northward).W.00000nIter
- vertical component of velocity field (ocean: m/s and positive upward, atmosphere: Pa/s and positive towards increasing pressure i.e., downward).T.00000nIter
- potential temperature (ocean: ^{\circ}\mathrm{C}, atmosphere: \mathrm{K}).S.00000nIter
- ocean: salinity (g/kg), atmosphere: water vapor (g/kg).Eta.00000nIter
- ocean: surface elevation (m), atmosphere: surface pressure anomaly (Pa).
The chain 00000nIter
consists of ten figures that specify the
iteration number at which the output is written out. For example,
U.0000000300
is the zonal velocity at iteration 300.
In addition, a “pickup” or “checkpoint” file called:
pickup.00000nIter
is written out. This file represents the state of the model in a condensed form and is used for restarting the integration (at the specific iteration number). Some additional parameterizations and packages also produce separate pickup files, e.g.,
pickup_cd.00000nIter
if the C-D scheme is used (see :ref:`C_D Scheme <C-D_scheme>`)pickup_seaice.00000nIter
if the seaice package is turned on (see :ref:`sub_phys_pkg_seaice`)pickup_ptracers.00000nIter
if passive tracers are included in the simulation (see :ref:`sub_phys_pkg_ptracers`)
Rolling checkpoint files are
the same as the pickup files but are named differently. Their name
contain the chain ckptA
or ckptB
instead of 00000nIter
. They
can be used to restart the model but are overwritten every other time
they are output to save disk space during long integrations.
:filelink:`pkg/mnc` is a set of routines written to read, write, and
append netCDF files.
Unlike the :filelink:`pkg/mdsio` output, the :filelink:`pkg/mnc`–generated
output is usually placed within a subdirectory with a name such as
mnc_output_
(by default,
netCDF tries to append,
rather than overwrite, existing files,
so a unique output directory is helpful for each separate run).
The :filelink:`pkg/mnc` output files are all in the “self-describing” netCDF format and can thus be browsed and/or plotted using tools such as:
- ncdump is a utility which is typically included with every netCDF install, and converts the netCDF binaries into formatted ASCII text files.
- ncview is a very convenient and quick way to plot netCDF data and it runs on most platforms. Panoply is a similar alternative.
- MATLAB, GrADS, IDL and other common post-processing environments provide built-in netCDF interfaces.
The repository includes a few MATLAB utilities to read binary output files written in the :filelink:`/pkg/mdsio` format. The MATLAB scripts are located in the directory :filelink:`utils/matlab` under the root tree. The script :filelink:`utils/matlab/rdmds.m` reads the data. Look at the comments inside the script to see how to use it.
Some examples of reading and visualizing some output in MATLAB:
% matlab >> H=rdmds('Depth'); >> contourf(H');colorbar; >> title('Depth of fluid as used by model'); >> eta=rdmds('Eta',10); >> imagesc(eta');axis ij;colorbar; >> title('Surface height at iter=10'); >> [eta,iters,M]=rdmds('Eta',NaN); % this will read all dumped iterations >> % iter numbers put in variable 'iters'; 'M' is a character string w/metadata >> for n=1:length(iters); imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
Typing help rdmds
in
MATLAB will pull up further
information on how to use the :filelink:`rdmds <utils/matlab/rdmds.m>` utility.
Similar scripts for netCDF output (e.g., :filelink:`utils/matlab/rdmnc.m`) are available and they are described in :numref:`pkg_mnc`.
Install the MITgcmutils python package following the instructions in :numref:`MITgcmutils`.
The following example shows how to load in some data:
# python from MITgcmutils import mds Eta = mds.rdmds('Eta', itrs=10)
For more information about this function and its options, see the API docs, :meth:`MITgcmutils.mds.rdmds`.
The netCDF output is currently produced with one file per processor. This means the individual tiles need to be stitched together to create a single netCDF file that spans the model domain. The script :filelink:`utils/python/MITgcmutils/scripts/gluemncbig` can do this efficiently from the command line. If you have installed the MITgcmutils package, a copy of gluemncbig should be on your path. For usage information, see :numref:`gluemncbig`.
The following example shows how to use the xarray python package to read the resulting netCDF file into Python:
# python import xarray as xr Eta = xr.open_dataset('Eta.nc')
MITgcm’s array dimensions need to be configured for each unique model domain. The size of each tile (in dimensions x, y, and vertical coordinate r) the “overlap” region of each tile (in x and y), the number of tiles in the x and y dimensions, and the number of processes (using MPI) in the x and y dimensions all need to be specified in :filelink:`SIZE.h <model/inc/SIZE.h>`. From these parameters, global domain-size variables :varlink:`Nx`, :varlink:`Ny` are computed by the model. See a more technical discussion of :filelink:`SIZE.h <model/inc/SIZE.h>` parameters in in :numref:`specify_decomp`, and a detailed explanation of an example :filelink:`SIZE.h <model/inc/SIZE.h>` setup in tutorial :ref:`Baroclinic Ocean Gyre <baroc_code_size>`.
Parameter | Default :filelink:`SIZE.h <model/inc/SIZE.h>` | Description |
---|---|---|
:varlink:`sNx` | 30 | number of points in x dimension in a single tile |
:varlink:`sNy` | 15 | number of points in y dimension in a single tile |
:varlink:`Nr` | 4 | number of points in r dimension |
:varlink:`OLx` | 2 | number of “overlap” points in x dimension for a tile |
:varlink:`OLy` | 2 | number of “overlap” points in y dimension for a tile |
:varlink:`nSx` | 2 | number of tile per process in x dimension |
:varlink:`nSy` | 4 | number of tile per process in y dimension |
:varlink:`nPx` | 1 | number of processes in x dimension |
:varlink:`nPy` | 1 | number of processes in y dimension |
Note the repository version of :filelink:`SIZE.h <model/inc/SIZE.h>` includes several lines of text at the top that will halt compilation with errors. Thus, to use MITgcm you will need to copy :filelink:`SIZE.h <model/inc/SIZE.h>` to a code modification directory and make edits, including deleting or commenting out the offending lines of text.
The CPP flags relative to the “numerical model” part of the code are defined and set in the file :filelink:`CPP_OPTIONS.h <model/inc/CPP_OPTIONS.h>` in the directory :filelink:`model/inc/`. In the parameter tables in :numref:`customize_model` we have noted CPP options that need to be changed from the default to enable specific runtime parameter to be used properly. Also note many of the options below are for less-common situations or are somewhat obscure, so newer users of the MITgcm are encouraged to jump to :numref:`customize_model` where more basic runtime parameters are discussed.
.. tabularcolumns:: |\Y{.475}|\Y{.1}|\Y{.45}|
CPP Flag Name | Default | Description |
---|---|---|
:varlink:`SHORTWAVE_HEATING` | #undef | provide separate shortwave heating file, allowing shortwave to penetrate below surface layer |
:varlink:`ALLOW_GEOTHERMAL_FLUX` | #undef | include code for applying geothermal heat flux at the bottom of the ocean |
:varlink:`ALLOW_FRICTION_HEATING` | #undef | include code to allow heating due to friction (and momentum dissipation) |
:varlink:`ALLOW_ADDFLUID` | #undef | allow mass source or sink of fluid in the interior (3D generalization of oceanic real-fresh water flux) |
:varlink:`ATMOSPHERIC_LOADING` | #define | include code for atmospheric pressure-loading (and seaice-loading) on ocean surface |
:varlink:`ALLOW_BALANCE_FLUXES` | #undef | include balancing surface forcing fluxes code |
:varlink:`ALLOW_BALANCE_RELAX` | #undef | include balancing surface forcing relaxation code |
:varlink:`CHECK_SALINITY_FOR_NEGATIVE_VALUES` | #undef | include code checking for negative salinity |
:varlink:`EXCLUDE_FFIELDS_LOAD` | #undef | exclude external forcing-fields load; code allows reading and simple linear time interpolation of oceanic forcing fields, if no specific pkg (e.g., :filelink:`pkg/exf`) is used to compute them |
:varlink:`INCLUDE_PHIHYD_CALCULATION_CODE` | #define | include code to calculate \phi_{hyd} |
:varlink:`INCLUDE_CONVECT_CALL` | #define | include code for convective adjustment mixing algorithm |
:varlink:`INCLUDE_CALC_DIFFUSIVITY_CALL` | #define | include codes that calculates (tracer) diffusivities and viscosities |
:varlink:`ALLOW_3D_DIFFKR` | #undef | allow full 3D specification of vertical diffusivity |
:varlink:`ALLOW_BL79_LAT_VARY` | #undef | allow latitudinally varying Bryan and Lewis 1979 :cite:`bryan:79` vertical diffusivity |
:varlink:`EXCLUDE_PCELL_MIX_CODE` | #undef | exclude code for partial-cell effect (physical or enhanced) in vertical mixing; this allows accounting for partial-cell in vertical viscosity and diffusion, either from grid-spacing reduction effect or as artificially enhanced mixing near surface & bottom for too thin grid-cell |
:varlink:`ALLOW_SMAG_3D_DIFFUSIVITY` | #undef | include code for isotropic 3-D Smagorinsky diffusivity for tracers (viscosity scaled by constant Prandtl number) |
:varlink:`ALLOW_SOLVE4_PS_AND_DRAG` | #undef | include code for combined surface pressure and drag implicit solver |
:varlink:`INCLUDE_IMPLVERTADV_CODE` | #define | include code for implicit vertical advection |
:varlink:`ALLOW_ADAMSBASHFORTH_3` | #undef | include code for Adams-Bashforth 3rd-order |
:varlink:`ALLOW_QHYD_STAGGER_TS` | #undef | include code for quasi-hydrostatic stagger time-step Adams-Bashforth code |
:varlink:`EXACT_CONSERV` | #define | include code for “exact conservation" of fluid in free-surface formulation (recompute divergence after pressure solver) |
:varlink:`NONLIN_FRSURF` | #undef | allow the use of non-linear free-surface formulation; implies that grid-cell thickness (hFactors) varies with time |
:varlink:`ALLOW_NONHYDROSTATIC` | #undef | include non-hydrostatic and 3D pressure solver codes |
:varlink:`ALLOW_EDDYPSI` | #undef | include GM-like eddy stress in momentum code (untested, not recommended) |
:varlink:`ALLOW_CG2D_NSA` | #undef | use non-self-adjoint (NSA) conjugate-gradient solver |
:varlink:`ALLOW_SRCG` | #define | include code for single reduction conjugate gradient solver |
:varlink:`SOLVE_DIAGONAL_LOWMEMORY` | #undef | low memory footprint (not suitable for AD) choice for implicit solver routines solve_*diagonal.F |
:varlink:`SOLVE_DIAGONAL_KINNER` | #undef | choice for implicit solver routines solve_*diagonal.F suitable for AD |
:varlink:`COSINEMETH_III` | #define | selects implementation form of \cos{\varphi} scaling of bi-harmonic term for viscosity (note, CPP option for tracer diffusivity set independently in :filelink:`GAD_OPTIONS.h <pkg/generic_advdiff/GAD_OPTIONS.h>`) |
:varlink:`ISOTROPIC_COS_SCALING` | #undef | selects isotropic scaling of harmonic and bi-harmonic viscous terms when using the \cos{\varphi} scaling (note, CPP option for tracer diffusivity set independently in :filelink:`GAD_OPTIONS.h <pkg/generic_advdiff/GAD_OPTIONS.h>`) |
By default, MITgcm includes several core packages, i.e., these packages are
enabled during :filelink:`genmake2 <tools/genmake2>` execution if a file
packages.conf
is not found. See :numref:`using_packages` for more
information about packages.conf
, and see :filelink:`pkg/pkg_groups` for
more information about default packages and package groups.
These default packages are as follows:
- :filelink:`pkg/mom_common`
- :filelink:`pkg/mom_fluxform`
- :filelink:`pkg/mom_vecinv`
- :filelink:`pkg/generic_advdiff`
- :filelink:`pkg/debug`
- :filelink:`pkg/mdsio`
- :filelink:`pkg/rw`
- :filelink:`pkg/monitor`
Additional CPP options that affect the model core code are set in files
${PKG}_OPTIONS.h
located in these packages' directories. Similarly,
optional (non-default) packages also include package-specific CPP options that
must be set in files ${PKG}_OPTIONS.h
.
The file :filelink:`eesupp/inc/CPP_EEOPTIONS.h` does not contain any CPP options that typically will need to be modified by users.
When you are ready to run the model in the configuration you want, the
most straightforward approach is to use and adapt the setup of a tutorial or
verification experiment (described in :numref:`chap_modelExamples`) that is the
closest to your configuration. Then, the amount of setup will be minimized.
In this section, we document the complete list of MITgcm model namelist runtime
parameters set in file data
, which needs to be located in the
directory where you will run the model.
Model parameters are defined and
declared in the file :filelink:`PARAMS.h <model/inc/PARAMS.h>` and their
default values are generally set in the routine
:filelink:`set_defaults.F <model/src/set_defaults.F>`, otherwise
when initialized in the routine :filelink:`ini_parms.F <model/src/ini_parms.F>`.
:numref:`eedata_parms` documents the “execution environment” namelist parameters
in file eedata
, which must also reside in the current run directory.
Note that runtime parameters used by (non-default) MITgcm packages are not
documented here but rather in :numref:`packagesI`
and :numref:`outp_pack`, and prescribed in package-specific data.${pkg}
namelist files which are read in via package-specific
${pkg}_readparms.F
where ${pkg}
is the package name
(see :numref:`using_packages`).
In what follows, model parameters are grouped into categories related to
configuration/computational domain, algorithmic parameters, equations solved
in the model, parameters related to model forcing, and simulation controls.
The tables below specify the namelist parameter name, the namelist parameter
group in data
(and eedata
in :numref:`eedata_parms`), the default
value, and a short description of its function. Runtime parameters that
require non-default CPP options to be set prior to compilation
(see :numref:`customize_compilation`) for proper use are noted.
:varlink:`buoyancyRelation` is set to OCEANIC
by default, which employes a
z-coordinate vertical axis. To simulate an ocean using pressure
coordinates in the vertical, set it to OCEANICP
. For atmospheric
simulations, :varlink:`buoyancyRelation` needs to be set to ATMOSPHERIC
,
which also uses pressure as the vertical coordinate.
The default model configuration is hydrostatic; to run a non-hydrostatic
simulation, set the logical variable :varlink:`nonHydrostatic` to .TRUE.
.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`buoyancyRelation` | PARM01 | OCEANIC | buoyancy relation (OCEANIC , OCEANICP , or ATMOSPHERIC ) |
:varlink:`quasiHydrostatic` | PARM01 | FALSE | quasi-hydrostatic formulation on/off flag |
:varlink:`rhoRefFile` | PARM01 | ' ' | filename for reference density profile (kg/m3); activates anelastic form of model |
:varlink:`nonHydrostatic` | PARM01 | FALSE | non-hydrostatic formulation on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
Four different grids are available: Cartesian, spherical polar, cylindrical, and curvilinear (which includes the cubed sphere). The grid is set through the logical variables :varlink:`usingCartesianGrid`, :varlink:`usingSphericalPolarGrid`, :varlink:`usingCylindricalGrid`, and :varlink:`usingCurvilinearGrid`. Note that the cylindrical grid is designed for modeling a rotating tank, so that x is the azimuthual direction, y is the radial direction, and r is vertical coordinate (see tutorial :ref:`rotating tank <sec_eg_tank>`).
The variable :varlink:`xgOrigin` sets the position of the western most gridcell face in the x dimension (Cartesian, meters; spherical and cyclindrical, degrees). For a Cartesian or spherical grid, the southern boundary is defined through the variable :varlink:`ygOrigin` which corresponds to the latitude of the southern most gridcell face (Cartesian, meters; spherical, degrees). For a cyclindrical grid, a positive :varlink:`ygOrigin` (m) adds an inner cylindrical boundary at the center of the tank. The resolution along the x and y directions is controlled by the 1-D arrays :varlink:`delX` (meters for a Cartesian grid, degrees otherwise) and :varlink:`delY` (meters for Cartesian and cyclindrical grids, degrees spherical). On a spherical polar grid, you might decide to set the variable :varlink:`cosPower` which is set to 0 by default and which represents n in (\cos\varphi)^n, the power of cosine of latitude to multiply horizontal viscosity and tracer diffusivity. The vertical grid spacing is set through the 1-D array :varlink:`delR` (z-coordinates: in meters; p-coordinates, in Pa). Using a curvilinear grid requires complete specification of all horizontal MITgcm grid variables, either through a default filename (link to new doc section) or as specified by :varlink:`horizGridFile`.
The variable :varlink:`seaLev_Z` represents the standard position of sea level, in meters. This is typically set to 0 m for the ocean (default value). If instead pressure is used as the vertical coordinate, the pressure at the top (of the atmosphere or ocean) is set through :varlink:`top_Pres`, typically 0 Pa. As such, these variables are analogous to :varlink:`xgOrigin` and :varlink:`ygOrigin` to define the vertical grid axis. But they also are used for a second purpose: in a z-coordinate setup, :varlink:`top_Pres` sets a reference top pressure (required in a non-linear equation of state computation, for example); note that 1 bar (i.e., typical Earth atmospheric sea-level pressure) is added already, so the default is 0 Pa. Similarly, for a p-coordinate setup, :varlink:`seaLev_Z` is used to set a reference geopotential (after gravity scaling) at the top of the ocean or bottom of the atmosphere.
.. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`usingCartesianGrid` | PARM04 | TRUE | use Cartesian grid/coordinates on/off flag |
:varlink:`usingSphericalPolarGrid` | PARM04 | FALSE | use spherical grid/coordinates on/off flag |
:varlink:`usingCylindricalGrid` | PARM04 | FALSE | use cylindrical grid/coordinates on/off flag |
:varlink:`usingCurvilinearGrid` | PARM04 | FALSE | use curvilinear grid/coordinates on/off flag |
:varlink:`xgOrigin` | PARM04 | 0.0 | west edge x-axis origin (Cartesian: m; spherical and cyclindrical: degrees longitude) |
:varlink:`ygOrigin` | PARM04 | 0.0 | South edge y-axis origin (Cartesian and cyclindrical: m; spherical: degrees latitude) |
:varlink:`dxSpacing` | PARM04 | unset | x-axis uniform grid spacing, separation between cell faces (Cartesian: m; spherical and cyclindrical: degrees) |
:varlink:`delX` | PARM04 | :varlink:`dxSpacing` | 1D array of x-axis grid spacing, separation between cell faces (Cartesian: m; spherical and cyclindrical: degrees) |
:varlink:`delXFile` | PARM04 | ' ' | filename containing 1D array of x-axis grid spacing |
:varlink:`dySpacing` | PARM04 | unset | y-axis uniform grid spacing, separation between cell faces (Cartesian and cyclindrical: m; spherical: degrees) |
:varlink:`delY` | PARM04 | :varlink:`dySpacing` | 1D array of x-axis grid spacing, separation between cell faces (Cartesian and cyclindrical: m; spherical: degrees) |
:varlink:`delYFile` | PARM04 | ' ' | filename containing 1D array of y-axis grid spacing |
:varlink:`cosPower` | PARM01 | 0.0 | power law n in (\cos\varphi)^n factor for horizontal (harmonic or biharmonic) viscosity and tracer diffusivity (spherical polar) |
:varlink:`delR` | PARM04 | computed using delRc | vertical grid spacing 1D array ([r] unit) |
:varlink:`delRc` | PARM04 | computed using delR | vertical cell center spacing 1D array ([r] unit) |
:varlink:`delRFile` | PARM04 | ' ' | filename for vertical grid spacing 1D array ([r] unit) |
:varlink:`delRcFile` | PARM04 | ' ' | filename for vertical cell center spacing 1D array ([r] unit) |
:varlink:`rSphere` | PARM04 | 6.37E+06 | radius of sphere for spherical polar or curvilinear grid (m) |
:varlink:`seaLev_Z` | PARM04 | 0.0 | reference height of sea level (m) |
:varlink:`top_Pres` | PARM04 | 0.0 | top pressure (p-coordinates) or top reference pressure (z-coordinates) (Pa) |
:varlink:`selectFindRoSurf` | PARM01 | 0 | select method to determine surface reference pressure from orography (atmos.-only) |
:varlink:`horizGridFile` | PARM04 | ' ' | filename containing full set of horizontal grid variables (curvilinear) |
:varlink:`radius_fromHorizGrid` | PARM04 | :varlink:`rSphere` | radius of sphere used in input curvilinear horizontal grid file (m) |
:varlink:`phiEuler` | PARM04 | 0.0 | Euler angle, rotation about original z-axis (spherical polar) (degrees) |
:varlink:`thetaEuler` | PARM04 | 0.0 | Euler angle, rotation about new x-axis (spherical polar) (degrees) |
:varlink:`psiEuler` | PARM04 | 0.0 | Euler angle, rotation about new z-axis (spherical polar) (degrees) |
For the ocean, the topography is read from a file that contains a 2-D(x,y) map of bathymetry, in meters for z-coordinates, in pascals for p-coordinates. The bathymetry is specified by entering the vertical position of the ocean floor relative to the surface, so by convention in z-coordinates bathymetry is specified as negative numbers (“depth” is defined as positive-definite) whereas in p-coordinates bathymetry data is positive. The file name is represented by the variable :varlink:`bathyFile`. See our introductory tutorial setup :numref:`sec_eg_baro` for additional details on the file format. Note no changes are required in the model source code to represent enclosed, periodic, or double periodic domains: periodicity is assumed by default and is suppressed by setting the depths to 0 m for the cells at the limits of the computational domain.
To use the partial cell capability, the variable :varlink:`hFacMin` needs to be set to a value between 0.0 and 1.0 (it is set to 1.0 by default) corresponding to the minimum fractional size of a gridcell. For example, if a gridcell is 500 m thick and :varlink:`hFacMin` is set to 0.1, the minimum thickness for a “thin-cell” for this specific gridcell is 50 m. Thus, if the specified bathymetry depth were to fall exactly in the middle of this 500m thick gridcell, the initial model variable :varlink:`hFacC`(x,y,r) would be set to 0.5. If the specified bathymetry depth fell within the top 50m of this gridcell (i.e., less than :varlink:`hFacMin`), the model bathymetry would snap to the nearest legal value (i.e., initial :varlink:`hFacC`(x,y,r) would be equal to 0.0 or 0.1 depending if the depth was within 0-25 m or 25-50 m, respectively). Also note while specified bathymetry bottom depths (or pressures) need not coincide with the model's levels as deduced from :varlink:`delR`, any depth falling below the model's defined vertical axis is truncated.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`bathyFile` | PARM05 | ' ' | filename for 2D bathymetry (ocean) (z-coor.: m, negative; p-coor.: Pa, positive) |
:varlink:`topoFile` | PARM05 | ' ' | filename for 2D surface topography (atmosphere) (m) |
:varlink:`addWwallFile` | PARM05 | ' ' | filename for 2D western cell-edge “thin-wall” |
:varlink:`addSwallFile` | PARM05 | ' ' | filename for 2D southern cell-edge “thin-wall” |
:varlink:`hFacMin` | PARM01 | 1.0E+00 | minimum fraction size of a cell |
:varlink:`hFacMinDr` | PARM01 | 1.0E+00 | minimum dimensional size of a cell ([r] unit) |
:varlink:`hFacInf` | PARM01 | 2.0E-01 | lower threshold fraction for surface cell; for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>` |
:varlink:`hFacSup` | PARM01 | 2.0E+00 | upper threshold fraction for surface cell; for non-linear free surface, only see parameter :ref:`nonlinFreeSurf <free_surface_parms>` |
:varlink:`useMin4hFacEdges` | PARM04 | FALSE | set :varlink:`hFacW`, :varlink:`hFacS` as minimum of adjacent :varlink:`hFacC` on/off flag |
:varlink:`pCellMix_select` | PARM04 | 0 | option/factor to enhance mixing at the surface or bottom (0- 99) |
:varlink:`pCellMix_maxFac` | PARM04 | 1.0E+04 | maximum enhanced mixing factor for too thin partial-cell (non-dim.) |
:varlink:`pCellMix_delR` | PARM04 | 0.0 | thickness criteria for too thin partial-cell ([r] unit) |
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`rhoConst` | PARM01 | :varlink:`rhoNil` | vertically constant reference density (Boussinesq) (kg/m3) |
:varlink:`gravity` | PARM01 | 9.81E+00 | gravitational acceleration (m/s2) |
:varlink:`gravityFile` | PARM01 | ' ' | filename for 1D gravity vertical profile (m/s2) |
:varlink:`gBaro` | PARM01 | :varlink:`gravity` | gravity constant in barotropic equation (m/s2) |
.. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
For a Cartesian or cylindical grid, the Coriolis parameter f is set through the variables :varlink:`f0` (in s--1) and :varlink:`beta` (\frac{\partial f}{ \partial y}; in m--1s--1), which corresponds to a Coriolis parameter f = f_o + \beta y (the so-called \beta-plane).
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`rotationPeriod` | PARM01 | 8.6164E+04 | rotation period (s) |
:varlink:`omega` | PARM01 | 2\pi/:varlink:`rotationPeriod` | angular velocity (rad/s) |
:varlink:`selectCoriMap` | PARM01 | depends on grid (Cartesian and cylindrical=1, spherical and curvilinear=2) | Coriolis map options
|
:varlink:`f0` | PARM01 | 1.0E-04 | reference Coriolis parameter (Cartesian or cylindrical grid) (1/s) |
:varlink:`beta` | PARM01 | 1.0E-11 | \beta (Cartesian or cylindrical grid) (m--1s--1) |
:varlink:`fPrime` | PARM01 | 0.0 | 2 \Omega \cos{\phi} parameter (Cartesian or cylindical grid) (1/s); i.e., for \cos{\varphi} Coriolis terms from horizontal component of rotation vector (also sometimes referred to as reciprocal Coriolis parm.) |
The logical variables :varlink:`rigidLid` and :varlink:`implicitFreeSurface`
specify your choice for ocean upper boundary (or lower boundary if using
p-coordinates); set one to .TRUE.
and the other to .FALSE.
.
These settings affect the calculations of surface pressure (for the ocean) or
surface geopotential (for the atmosphere); see :numref:`parms-main_algorithm`.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`implicitFreeSurface` | PARM01 | TRUE | implicit free surface on/off flag |
:varlink:`rigidLid` | PARM01 | FALSE | rigid lid on/off flag |
:varlink:`useRealFreshWaterFlux` | PARM01 | FALSE | use true E-P-R freshwater flux (changes free surface/sea level) on/off flag |
:varlink:`implicSurfPress` | PARM01 | 1.0E+00 | implicit fraction of the surface pressure gradient (0-1) |
:varlink:`implicDiv2Dflow` | PARM01 | 1.0E+00 | implicit fraction of the barotropic flow divergence (0-1) |
:varlink:`implicitNHPress` | PARM01 | :varlink:`implicSurfPress` | implicit fraction of the non-hydrostatic pressure gradient (0-1); for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` |
:varlink:`nonlinFreeSurf` | PARM01 | 0 | non-linear free surface options (-1,0,1,2,3; see :numref:`nonlinFreeSurf-flags`); requires #define :varlink:`NONLIN_FRSURF` |
:varlink:`select_rStar` | PARM01 | 0 | vertical coordinate option
see :numref:`nonlinFreeSurf-flags`; requires #define :varlink:`NONLIN_FRSURF` |
:varlink:`selectNHfreeSurf` | PARM01 | 0 | non-hydrostatic free surface formulation option
requires non-hydrostatic formulation, see parameter :ref:`nonHydrostatic <model_config_parms>` |
:varlink:`exactConserv` | PARM01 | FALSE | exact total volume conservation (recompute divergence after pressure solver) on/off flag |
The time steps are set through the real variables :varlink:`deltaTMom` and :varlink:`deltaTtracer` (in seconds) which represent the time step for the momentum and tracer equations, respectively (or you can prescribe a single time step value for all parameters using :varlink:`deltaT`). The model “clock” is defined by the variable :varlink:`deltaTClock` (in seconds) which determines the I/O frequencies and is used in tagging output. Time in the model is thus computed as:
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`deltaT` | PARM03 | 0.0 | default value used for model time step parameters (s) |
:varlink:`deltaTClock` | PARM03 | :varlink:`deltaT` | timestep used for model clock (s): used for I/O frequency and tagging output and checkpoints |
:varlink:`deltaTmom` | PARM03 | :varlink:`deltaT` | momentum equation timestep (s) |
:varlink:`deltaTtracer` | PARM03 | :varlink:`deltaT` | tracer equation timestep (s) |
:varlink:`dTtracerLev` | PARM03 | :varlink:`deltaTtracer` | tracer equation timestep specified at each vertical level (s) |
:varlink:`deltaTfreesurf` | PARM03 | :varlink:`deltaTmom` | free-surface equation timestep (s) |
:varlink:`baseTime` | PARM03 | 0.0 | model base time corresponding to iteration 0 (s) |
By default, a hydrostatic simulation is assumed and a 2-D elliptic equation is used to invert the pressure field. If using a non-hydrostatic configuration, the pressure field is inverted through a 3-D elliptic equation (note this capability is not yet available for the atmosphere). The parameters controlling the behavior of the elliptic solvers are the variables :varlink:`cg2dMaxIters` and :varlink:`cg2dTargetResidual` for the 2-D case and :varlink:`cg3dMaxIters` and :varlink:`cg3dTargetResidual` for the 3-D case.
.. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`cg2dMaxIters` | PARM02 | 150 | upper limit on 2D conjugate gradient solver iterations |
:varlink:`cg2dTargetResidual` | PARM02 | 1.0E-07 | 2D conjugate gradient target residual (non-dim. due to RHS normalization ) |
:varlink:`cg2dTargetResWunit` | PARM02 | -1.0E+00 | 2D conjugate gradient target residual (\dot{r} units); <0: use RHS normalization, i.e., :varlink:`cg2dTargetResidual` instead |
:varlink:`cg2dPreCondFreq` | PARM02 | 1 | frequency (in number of iterations) for updating cg2d pre-conditioner; for non-linear free surface only, see parameter :ref:`nonlinFreeSurf <free_surface_parms>` |
:varlink:`cg2dUseMinResSol` | PARM02 | 0 unless flat-bottom, Cartesian |
|
:varlink:`cg3dMaxIters` | PARM02 | 150 | upper limit on 3D conjugate gradient solver iterations; requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
:varlink:`cg3dTargetResidual` | PARM02 | 1.0E-07 | 3D conjugate gradient target residual (non-dim. due to RHS normalization ); requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
:varlink:`useSRCGSolver` | PARM02 | FALSE | use conjugate gradient solver with single reduction (single call of mpi_allreduce) |
:varlink:`printResidualFreq` | PARM02 | 1 unless :varlink:`debugLevel` >4 | frequency (in number of iterations) of printing conjugate gradient residual |
:varlink:`integr_GeoPot` | PARM01 | 2 | select method to integrate geopotential
|
:varlink:`uniformLin_PhiSurf` | PARM01 | TRUE | use uniform b_s relation for \phi_s on/off flag |
:varlink:`deepAtmosphere` | PARM04 | FALSE | don’t make the thin shell/shallow water approximation |
:varlink:`nh_Am2` | PARM01 | 1.0E+00 | non-hydrostatic terms scaling factor; requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
The Adams-Bashforth stabilizing parameter is set through the
variable :varlink:`abEps` (dimensionless). The stagger baroclinic time
stepping algorithm can be activated by setting the logical variable
:varlink:`staggerTimeStep` to .TRUE.
.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`abEps` | PARM03 | 1.0E-02 | Adams-Bashforth-2 stabilizing weight (non-dim.) |
:varlink:`alph_AB` | PARM03 | 0.5E+00 | Adams-Bashforth-3 primary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` |
:varlink:`beta_AB` | PARM03 | 5/12 | Adams-Bashforth-3 secondary factor (non-dim.); requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` |
:varlink:`staggerTimeStep` | PARM01 | FALSE | use staggered time stepping (thermodynamic vs. flow variables) on/off flag |
:varlink:`multiDimAdvection` | PARM01 | TRUE | use multi-dim. advection algorithm in schemes where non multi-dim. is possible on/off flag |
:varlink:`implicitIntGravWave` | PARM01 | FALSE | treat internal gravity waves implicitly on/off flag; requires #define :varlink:`ALLOW_NONHYDROSTATIC` |
The form of the equation of state is controlled by the model configuration and :varlink:`eosType`.
For the atmosphere, :varlink:`eosType` must be set to IDEALGAS
.
For the ocean, several forms of the equation of state are available:
For a linear approximation, set :varlink:`eosType` to
LINEAR
), and you will need to specify the thermal and haline expansion coefficients, represented by the variables :varlink:`tAlpha` (in K--1) and :varlink:`sBeta` (in (g/kg)--1). Because the model equations are written in terms of perturbations, a reference thermodynamic state needs to be specified. This is done through the 1-D arrays :varlink:`tRef` and :varlink:`sRef`. :varlink:`tRef` specifies the reference potential temperature profile (in oC for the ocean and K for the atmosphere) starting from the level k=1. Similarly, :varlink:`sRef` specifies the reference salinity profile (in g/kg) for the ocean or the reference specific humidity profile (in g/kg) for the atmosphere.MITgcm offers several approximations to the full (oceanic) non-linear equation of state that can be selected as :varlink:`eosType`:
'POLYNOMIAL'
:This approximation is based on the Knudsen formula (see Bryan and Cox 1972 :cite:`bryan:72`). For this option you need to generate a file of polynomial coefficients called
POLY3.COEFFS
. To do this, use the program :filelink:`utils/knudsen2/knudsen2.f` under the model tree (aMakefile
is available in the same directory; you will need to edit the number and the values of the vertical levels in :filelink:`knudsen2.f <utils/knudsen2/knudsen2.f>` so that they match those of your configuration).’UNESCO’
:The UNESCO equation of state formula (IES80) of Fofonoff and Millard (1983) :cite:`fofonoff:83`. This equation of state assumes in-situ temperature, which is not a model variable; its use is therefore discouraged.
’JMD95Z’
:A modified UNESCO formula by Jackett and McDougall (1995) :cite:`jackett:95`, which uses the model variable potential temperature as input. The ’Z’ indicates that this equation of state uses a horizontally and temporally constant pressure p_{0}=-g\rho_{0}z.
’JMD95P’
:A modified UNESCO formula by Jackett and McDougall (1995) :cite:`jackett:95`, which uses the model variable potential temperature as input. The ’P’ indicates that this equation of state uses the actual hydrostatic pressure of the last time step. Lagging the pressure in this way requires an additional pickup file for restarts.
’MDJWF’
:A more accurate and less expensive equation of state than UNESCO by McDougall et al. (2003) :cite:`mcdougall:03`, also using the model variable potential temperature as input. It also requires lagging the pressure and therefore an additional pickup file for restarts.
’TEOS10’
:TEOS-10 is based on a Gibbs function formulation from which all thermodynamic properties of seawater (density, enthalpy, entropy sound speed, etc.) can be derived in a thermodynamically consistent manner; see http://www.teos-10.org. See IOC et al. (2010) :cite:`ioc:10`, McDougall and Parker (2011) :cite:`mcdougall:11`, and Roquet et al. (2015) :cite:`roquet:15` for implementation details. It also requires lagging the pressure and therefore an additional pickup file for restarts. Note at this time a full implementation of TEOS10 (i.e., ocean variables of conservative temperature and practical salinity, including consideration of surface forcings) has not been implemented; also note the original 48-term polynomial term is used, not the newer, preferred 75-term polynomial.
For these non-linear approximations, neither a reference profile of temperature or salinity is required, except for a setup where :varlink:`implicitIntGravWave` is set to
.TRUE.
or :varlink:`selectP_inEOS_Zc`=1.
Note that for simplicity, salinity is expressed as a ratio in g/kg (thus effectively unitless) regardless of the choice of equation of state, despite "Practical Salinity" not precisely equal to salinity expressed as a dissolved mass fraction. If TEOS-10 is selected, the model variable :varlink:`salt` can be interpreted as "Absolute Salinity". See Millero (2010) :cite:`millero:10` and Pawlowicz (2013) :cite:`pawlowicz:13` for detailed discussion of salinity measurements, and why being expressed as g/kg is preferred, in the context of the ocean equation of state.
.. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.2}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`eosType` | PARM01 | LINEAR | equation of state form |
:varlink:`tRef` | PARM01 | 20.0 oC (ocn) or 300.0 K (atm) | 1D vertical reference temperature profile (oC or K) |
:varlink:`tRefFile` | PARM01 | ' ' | filename for reference temperature profile (oC or K) |
:varlink:`thetaConst` | PARM01 | :varlink:`tRef`(k=1) | vertically constant reference temp. for atmosphere p^* coordinates (oK); for ocean, specify instead of :varlink:`tRef` or :varlink:`tRefFile` for vertically constant reference temp. (oC ) |
:varlink:`sRef` | PARM01 | 30.0 (g/kg) (ocn) or 0.0 (atm) | 1D vertical reference salinity profile (g/kg) |
:varlink:`sRefFile` | PARM01 | ' ' | filename for reference salinity profile (g/kg) |
:varlink:`selectP_inEOS_Zc` | PARM01 | depends on :varlink:`eosType` | select which pressure to use in EOS for z-coor.
for |
:varlink:`rhonil` | PARM01 | 9.998E+02 | reference density for linear EOS (kg/m3) |
:varlink:`tAlpha` | PARM01 | 2.0E-04 | linear EOS thermal expansion coefficient (1/oC) |
:varlink:`sBeta` | PARM01 | 7.4E-04 | linear EOS haline contraction coefficient ((g/kg)-1) |
.. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.175}|\Y{.55}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`HeatCapacity_Cp` | PARM01 | 3.994E+03 | specific heat capacity Cp (ocean) (J/kg/K) |
:varlink:`celsius2K` | PARM01 | 2.7315E+02 | conversion constant oC to Kelvin |
:varlink:`atm_Cp` | PARM01 | 1.004E+03 | specific heat capacity Cp dry air at const. press. (J/kg/K) |
:varlink:`atm_Rd` | PARM01 | :varlink:`atm_Cp`*(2/7) | gas constant for dry air (J/kg/K) |
:varlink:`atm_Rq` | PARM01 | 0.0 | water vapor specific volume anomaly relative to dry air (g/kg) |
:varlink:`atm_Po` | PARM01 | 1.0E+05 | atmosphere standard reference pressure (for potential temp. defn.) (Pa) |
There are a few logical variables that allow you to turn on/off various
terms in the momentum equation. These variables are called
:varlink:`momViscosity`, :varlink:`momAdvection`, :varlink:`useCoriolis`,
:varlink:`momStepping`, :varlink:`metricTerms`, and
:varlink:`momPressureForcing` and by default are set to .TRUE.
.
Vertical diffusive fluxes of momentum can be computed implicitly
by setting the logical variable :varlink:`implicitViscosity` to
.TRUE.
. The details relevant to both the momentum flux-form and the
vector-invariant form of the equations and the various (momentum) advection
schemes are covered in :numref:`discret_algorithm`.
.. tabularcolumns:: |\Y{.275}|\Y{.1}|\Y{.125}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`momStepping` | PARM01 | TRUE | momentum equation time-stepping on/off flag |
:varlink:`momViscosity` | PARM01 | TRUE | momentum friction terms on/off flag |
:varlink:`momAdvection` | PARM01 | TRUE | advection of momentum on/off flag |
:varlink:`momPressureForcing` | PARM01 | TRUE | pressure term in momentum equation on/off flag |
:varlink:`metricTerms` | PARM01 | TRUE | include metric terms (spherical polar, momentum flux-form) on/off flag |
:varlink:`useNHMTerms` | PARM01 | FALSE | use "non-hydrostatic form" of metric terms on/off flag; (see :numref:`non_hyd_metric_terms`; note these terms are non-zero in many model configurations beside non-hydrostatic) |
:varlink:`momImplVertAdv` | PARM01 | FALSE | momentum implicit vertical advection on/off flag; requires #define :varlink:`INCLUDE_IMPLVERTADV_CODE` |
:varlink:`implicitViscosity` | PARM01 | FALSE | implicit vertical viscosity on/off flag |
:varlink:`interViscAr_pCell` | PARM04 | FALSE | account for partial-cell in interior vertical viscosity on/off flag |
:varlink:`momDissip_In_AB` | PARM03 | TRUE | use Adams-Bashforth time stepping for dissipation tendency |
:varlink:`useCoriolis` | PARM01 | TRUE | include Coriolis terms on/off flag |
:varlink:`use3dCoriolis` | PARM01 | TRUE | include \cos{\varphi} Coriolis terms on/off flag |
:varlink:`selectCoriScheme` | PARM01 | 0 | Coriolis scheme selector
|
:varlink:`vectorInvariantMomentum` | PARM01 | FALSE | use vector-invariant form of momentum equations flag |
:varlink:`useJamartMomAdv` | PARM01 | FALSE | use Jamart wetpoints method for relative vorticity advection (vector invariant form) on/off flag |
:varlink:`selectVortScheme` | PARM01 | 1 | vorticity scheme (vector invariant form) options
see Sadourny 1975 :cite:`sadourny:75` and Burridge & Haseler 1977 :cite:`burridge:77` |
:varlink:`upwindVorticity` | PARM01 | FALSE | bias interpolation of vorticity in the Coriolis term (vector invariant form) on/off flag |
:varlink:`useAbsVorticity` | PARM01 | FALSE | use f + \zeta in Coriolis terms (vector invariant form) on/off flag |
:varlink:`highOrderVorticity` | PARM01 | FALSE | use 3rd/4th order interpolation of vorticity (vector invariant form) on/off flag |
:varlink:`upwindShear` | PARM01 | FALSE | use 1st order upwind for vertical advection (vector invariant form) on/off flag |
:varlink:`selectKEscheme` | PARM01 | 0 | kinetic energy computation in Bernoulli function (vector invariant form) options
see :filelink:`mom_calc_ke.F <pkg/mom_common/mom_calc_ke.F>` |
The initial horizontal velocity components can be specified from binary files :varlink:`uVelInitFile` and :varlink:`vVelInitFile`. These files should contain 3-D data ordered in an (x,y,r) fashion with k=1 as the first vertical level (surface level). If no file names are provided, the velocity is initialized to zero. The initial vertical velocity is always derived from the horizontal velocity using the continuity equation. In the case of a restart (from the end of a previous simulation), the velocity field is read from a pickup file (see :numref:`simulation_controls`) and the initial velocity files are ignored.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`uVelInitFile` | PARM05 | ' ' | filename for 3D specification of initial zonal velocity field (m/s) |
:varlink:`vVelInitFile` | PARM05 | ' ' | filename for 3D specification of initial meridional velocity field (m/s) |
:varlink:`pSurfInitFile` | PARM05 | ' ' | filename for 2D specification of initial free surface position ([r] unit) |
The lateral eddy viscosity coefficient is specified through the variable :varlink:`viscAh` (in m2s--1). The vertical eddy viscosity coefficient is specified through the variable :varlink:`viscAr` (in [r]2s--1, where [r] is the dimension of the vertical coordinate). In addition, biharmonic mixing can be added as well through the variable :varlink:`viscA4` (in m4s--1).
.. tabularcolumns:: |\Y{.215}|\Y{.1}|\Y{.115}|\Y{.595}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`viscAh` | PARM01 | 0.0 | lateral eddy viscosity (m2/s) |
:varlink:`viscAhD` | PARM01 | :varlink:`viscAh` | lateral eddy viscosity acts on divergence part (m2/s) |
:varlink:`viscAhZ` | PARM01 | :varlink:`viscAh` | lateral eddy viscosity acts on vorticity part (\zeta points) (m2/s) |
:varlink:`viscAhW` | PARM01 | :varlink:`viscAhD` | lateral eddy viscosity for mixing vertical momentum (non-hydrostatic form) (m2/s); for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` |
:varlink:`viscAhDfile` | PARM05 | ' ' | filename for 3D specification of lateral eddy viscosity (divergence part) (m2/s); requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
:varlink:`viscAhZfile` | PARM05 | ' ' | filename for 3D specification of lateral eddy viscosity (vorticity part, \zeta points); requires #define :varlink:`ALLOW_3D_VISCAH` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
:varlink:`viscAhGrid` | PARM01 | 0.0 | grid-dependent lateral eddy viscosity (non-dim.) |
:varlink:`viscAhMax` | PARM01 | 1.0E+21 | maximum lateral eddy viscosity (m2/s) |
:varlink:`viscAhGridMax` | PARM01 | 1.0E+21 | maximum lateral eddy (grid-dependent) viscosity (non-dim.) |
:varlink:`viscAhGridMin` | PARM01 | 0.0 | minimum lateral eddy (grid-dependent) viscosity (non-dim.) |
:varlink:`viscAhReMax` | PARM01 | 0.0 | minimum lateral eddy viscosity based on Reynolds number (non-dim.) |
:varlink:`viscC2leith` | PARM01 | 0.0 | Leith harmonic viscosity factor (vorticity part, \zeta points) (non-dim.) |
:varlink:`viscC2leithD` | PARM01 | 0.0 | Leith harmonic viscosity factor (divergence part) (non-dim.) |
:varlink:`viscC2LeithQG` | PARM01 | 0.0 | Quasi-geostrophic Leith viscosity factor (non-dim.) |
:varlink:`viscC2smag` | PARM01 | 0.0 | Smagorinsky harmonic viscosity factor (non-dim.) |
:varlink:`viscA4` | PARM01 | 0.0 | lateral biharmonic viscosity (m4/s) |
:varlink:`viscA4D` | PARM01 | :varlink:`viscA4` | lateral biharmonic viscosity (divergence part) (m4/s) |
:varlink:`viscA4Z` | PARM01 | :varlink:`viscA4` | lateral biharmonic viscosity (vorticity part, \zeta points) (m4/s) |
:varlink:`viscA4W` | PARM01 | :varlink:`viscA4D` | lateral biharmonic viscosity for mixing vertical momentum (non-hydrostatic form) (m4/s); for non-hydrostatic only, see parameter :ref:`nonHydrostatic <model_config_parms>` |
:varlink:`viscA4Dfile` | PARM05 | ' ' | filename for 3D specification of lateral biharmonic viscosity (divergence part) (m4/s); requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
:varlink:`viscA4Zfile` | PARM05 | ' ' | filename for 3D specification of lateral biharmonic viscosity (vorticity part, \zeta points); requires #define :varlink:`ALLOW_3D_VISCA4` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
:varlink:`viscA4Grid` | PARM01 | 0.0 | grid dependent biharmonic viscosity (non-dim.) |
:varlink:`viscA4Max` | PARM01 | 1.0E+21 | maximum biharmonic viscosity (m4/s) |
:varlink:`viscA4GridMax` | PARM01 | 1.0E+21 | maximum biharmonic (grid-dependent) viscosity (non-dim.) |
:varlink:`viscA4GridMin` | PARM01 | 0.0 | minimum biharmonic (grid-dependent) viscosity (mon-dim.) |
:varlink:`viscA4ReMax` | PARM01 | 0.0 | minimum biharmonic viscosity based on Reynolds number (non-dim.) |
:varlink:`viscC4leith` | PARM01 | 0.0 | Leith biharmonic viscosity factor (vorticity part, \zeta points) (non-dim.) |
:varlink:`viscC4leithD` | PARM01 | 0.0 | Leith biharmonic viscosity factor (divergence part) (non-dim.) |
:varlink:`viscC4smag` | PARM01 | 0.0 | Smagorinsky biharmonic viscosity factor (non-dim.) |
:varlink:`useFullLeith` | PARM01 | FALSE | use full form of Leith viscosities on/off flag |
:varlink:`useSmag3D` | PARM01 | FALSE | use isotropic 3D Smagorinsky harmonic viscosities flag; requires #define :varlink:`ALLOW_SMAG_3D` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
:varlink:`smag3D_coeff` | PARM01 | 1.0E-02 | isotropic 3D Smagorinsky coefficient (non-dim.); requires #define :varlink:`ALLOW_SMAG_3D` in :filelink:`pkg/mom_common/MOM_COMMON_OPTIONS.h` |
:varlink:`useStrainTensionVisc` | PARM01 | FALSE | flag to use strain-tension form of viscous operator |
:varlink:`useAreaViscLength` | PARM01 | FALSE | flag to use area for viscous L^2 instead of harmonic mean of {L_x}^2, {L_y}^2 |
:varlink:`viscAr` | PARM01 | 0.0 | vertical eddy viscosity ([r]2/s) |
:varlink:`viscArNr` | PARM01 | 0.0 | vertical profile of vertical eddy viscosity ([r]2/s) |
:varlink:`pCellMix_viscAr` | PARM04 | :varlink:`viscArNr` | vertical viscosity for too thin partial-cell ([r]2/s) |
Slip or no-slip conditions at lateral and bottom
boundaries are specified through the logical variables
:varlink:`no_slip_sides` and :varlink:`no_slip_bottom`. If set to
.FALSE.
, free-slip boundary conditions are applied. If no-slip
boundary conditions are applied at the bottom, a bottom drag can be
applied as well. Two forms are available: linear (set the variable
:varlink:`bottomDragLinear` in [r]/s, )
and quadratic (set the variable
:varlink:`bottomDragQuadratic`, [r]/m).
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`no_slip_sides` | PARM01 | TRUE | viscous BCs: no-slip sides on/off flag |
:varlink:`sideDragFactor` | PARM01 | 2.0E+00 | side-drag scaling factor (2.0: full drag) (non-dim.) |
:varlink:`no_slip_bottom` | PARM01 | TRUE | viscous BCs: no-slip bottom on/off flag |
:varlink:`bottomDragLinear` | PARM01 | 0.0 | linear bottom-drag coefficient ([r]/s) |
:varlink:`bottomDragQuadratic` | PARM01 | 0.0 | quadratic bottom-drag coefficient ([r]/m) |
:varlink:`selectBotDragQuadr` | PARM01 | -1 | select quadratic bottom drag discretization option
if :varlink:`bottomDragQuadratic` \neq 0. then default is 0 |
:varlink:`selectImplicitDrag` | PARM01 | 0 | top/bottom drag implicit treatment options
if =2, requires #define :varlink:`ALLOW_SOLVE4_PS_AND_DRAG` |
:varlink:`bottomVisc_pCell` | PARM01 | FALSE | account for partial-cell in bottom viscosity (using :varlink:`no_slip_bottom` = .TRUE. ) on/off flag |
This section covers the tracer equations, i.e., the potential temperature equation and the salinity (for the ocean) or specific humidity (for the atmosphere) equation.
The logical variables :varlink:`tempAdvection`, and
:varlink:`tempStepping` allow you to turn on/off terms in the temperature
equation (similarly for salinity or specific humidity with variables
:varlink:`saltAdvection` etc.). These variables all
default to a value of .TRUE.
. The vertical diffusive
fluxes can be computed implicitly by setting the logical variable
:varlink:`implicitDiffusion` to .TRUE.
.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.175}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`tempStepping` | PARM01 | TRUE | temperature equation time-stepping on/off flag |
:varlink:`tempAdvection` | PARM01 | TRUE | advection of temperature on/off flag |
:varlink:`tempAdvScheme` | PARM01 | 2 | temperature horizontal advection scheme selector (see :numref:`adv_scheme_summary`) |
:varlink:`tempVertAdvScheme` | PARM01 | :varlink:`tempAdvScheme` | temperature vertical advection scheme selector (see :numref:`adv_scheme_summary`) |
:varlink:`tempImplVertAdv` | PARM01 | FALSE | temperature implicit vertical advection on/off flag |
:varlink:`addFrictionHeating` | PARM01 | FALSE | include frictional heating in temperature equation on/off flag; requires #define :varlink:`ALLOW_FRICTION_HEATING` |
:varlink:`temp_stayPositive` | PARM01 | FALSE | use Smolarkiewicz hack to ensure temperature stays positive on/off flag; requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h` |
:varlink:`saltStepping` | PARM01 | TRUE | salinity equation time-stepping on/off flag |
:varlink:`saltAdvection` | PARM01 | TRUE | advection of salinity on/off flag |
:varlink:`saltAdvScheme` | PARM01 | 2 | salinity horizontal advection scheme selector (see :numref:`adv_scheme_summary`) |
:varlink:`saltVertAdvScheme` | PARM01 | :varlink:`saltAdvScheme` | salinity vertical advection scheme selector (see :numref:`adv_scheme_summary`) |
:varlink:`saltImplVertAdv` | PARM01 | FALSE | salinity implicit vertical advection on/off flag |
:varlink:`salt_stayPositive` | PARM01 | FALSE | use Smolarkiewicz hack to ensure salinity stays positive on/off flag; requires #define :varlink:`GAD_SMOLARKIEWICZ_HACK` in :filelink:`pkg/generic_advdiff/GAD_OPTIONS.h` |
:varlink:`implicitDiffusion` | PARM01 | FALSE | implicit vertical diffusion on/off flag |
:varlink:`interDiffKr_pCell` | PARM04 | FALSE | account for partial-cell in interior vertical diffusion on/off flag |
:varlink:`linFSConserveTr` | PARM01 | TRUE | correct source/sink of tracer due to use of linear free surface on/off flag |
:varlink:`doAB_onGtGs` | PARM03 | TRUE | apply Adams-Bashforth on tendencies (rather than on T,S) on/off flag |
The initial tracer data can be contained in the binary files :varlink:`hydrogThetaFile` and :varlink:`hydrogSaltFile`. These files should contain 3-D data ordered in an (x,y,r) fashion with k=1 as the first vertical level. If no file names are provided, the tracers are then initialized with the values of :varlink:`tRef` and :varlink:`sRef` discussed in :numref:`parms-eos`. In this case, the initial tracer data are uniform in x and y for each depth level.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`hydrogThetaFile` | PARM05 | ' ' | filename for 3D specification of initial potential temperature (oC) |
:varlink:`hydrogSaltFile` | PARM05 | ' ' | filename for 3D specification of initial salinity (g/kg) |
:varlink:`maskIniTemp` | PARM05 | TRUE | apply (center-point) mask to initial hydrographic theta data on/off flag |
:varlink:`maskIniSalt` | PARM05 | TRUE | apply (center-point) mask to initial hydrographic salinity on/off flag |
:varlink:`checkIniTemp` | PARM05 | TRUE | check if initial theta (at wet-point) identically zero on/off flag |
:varlink:`checkIniSalt` | PARM05 | TRUE | check if initial salinity (at wet-point) identically zero on/off flag |
Lateral eddy diffusivities for temperature and salinity/specific humidity are specified through the variables :varlink:`diffKhT` and :varlink:`diffKhS` (in m2/s). Vertical eddy diffusivities are specified through the variables :varlink:`diffKrT` and :varlink:`diffKrS`. In addition, biharmonic diffusivities can be specified as well through the coefficients :varlink:`diffK4T` and :varlink:`diffK4S` (in m4/s). The Gent and McWilliams parameterization for advection and mixing of oceanic tracers is described in :numref:`sub_phys_pkg_gmredi`.
.. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.15}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`diffKhT` | PARM01 | 0.0 | Laplacian diffusivity of heat laterally (m2/s) |
:varlink:`diffK4T` | PARM01 | 0.0 | biharmonic diffusivity of heat laterally (m4/s) |
:varlink:`diffKrT` | PARM01 | 0.0 | Laplacian diffusivity of heat vertically (m2/s) |
:varlink:`diffKr4T` | PARM01 | 0.0 | biharmonic diffusivity of heat vertically (m2/s) |
:varlink:`diffKrNrT` | PARM01 | 0.0 at k=top | vertical profile of vertical diffusivity of temperature (m2/s) |
:varlink:`pCellMix_diffKr` | PARM04 | :varlink:`diffKrNr` | vertical diffusivity for too thin partial-cell ([r]2/s) |
:varlink:`diffKhS` | PARM01 | 0.0 | Laplacian diffusivity of salt laterally (m2/s) |
:varlink:`diffK4S` | PARM01 | 0.0 | biharmonic diffusivity of salt laterally (m4/s) |
:varlink:`diffKrS` | PARM01 | 0.0 | Laplacian diffusivity of salt vertically (m2/s) |
:varlink:`diffKr4S` | PARM01 | 0.0 | biharmonic diffusivity of salt vertically (m2/s) |
:varlink:`diffKrNrS` | PARM01 | 0.0 at k=top | vertical profile of vertical diffusivity of salt (m2/s) |
:varlink:`diffKrFile` | PARM05 | ' ' | filename for 3D specification of vertical diffusivity (m2/s); requires #define :varlink:`ALLOW_3D_DIFFKR` |
:varlink:`diffKrBL79surf` | PARM01 | 0.0 | surface diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m2/s) |
:varlink:`diffKrBL79deep` | PARM01 | 0.0 | deep diffusivity for Bryan & Lewis 1979 :cite:`bryan:79` (m2/s) |
:varlink:`diffKrBL79scl` | PARM01 | 2.0E+02 | depth scale for Bryan & Lewis 1979 :cite:`bryan:79` (m) |
:varlink:`diffKrBL79Ho` | PARM01 | -2.0E+03 | turning depth for Bryan & Lewis 1979 :cite:`bryan:79` (m) |
:varlink:`diffKrBLEQsurf` | PARM01 | 0.0 | same as :varlink:`diffKrBL79surf` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
:varlink:`diffKrBLEQdeep` | PARM01 | 0.0 | same as :varlink:`diffKrBL79deep` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
:varlink:`diffKrBLEQscl` | PARM01 | 2.0E+02 | same as :varlink:`diffKrBL79scl` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
:varlink:`diffKrBLEQHo` | PARM01 | -2.0E+03 | same as :varlink:`diffKrBL79Ho` but at equator; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
:varlink:`BL79LatVary` | PARM01 | 3.0E+01 | transition from diffKrBLEQ to diffKrBL79 parms at this latitude; requires #define :varlink:`ALLOW_BL79_LAT_VARY` |
In addition to specific packages that parameterize ocean convection, two main
model options are available. To use the first option, a convective adjustment
scheme, you need to set the variable :varlink:`cadjFreq`, the frequency
(in seconds) with which the adjustment algorithm is called, to a non-zero value
(note, if :varlink:`cadjFreq` set to a negative value by the user, the model
will set it to the model clock time step). The second option is to parameterize
convection with implicit vertical diffusion. To do this, set the
logical variable :varlink:`implicitDiffusion` to .TRUE.
and the real
variable :varlink:`ivdc_kappa` (in m2/s) to
an appropriate tracer vertical diffusivity value for mixing
due to static instabilities (typically, several orders of magnitude above the
background vertical diffusivity). Note that :varlink:`cadjFreq` and
:varlink:`ivdc_kappa` cannot both have non-zero value.
.. tabularcolumns:: |\Y{.2}|\Y{.1}|\Y{.125}|\Y{.6}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`ivdc_kappa` | PARM01 | 0.0 | implicit vertical diffusivity for convection (m2/s) |
:varlink:`cAdjFreq` | PARM03 | 0 | frequency of convective adj. scheme; <0: sets value to :varlink:`deltaTclock` (s) |
:varlink:`hMixCriteria` | PARM01 | -0.8E+00 |
|
:varlink:`hMixSmooth` | PARM01 | 0.0 | use this fraction of neighboring points (for smoothing) in ML calculation (0-1; 0: no smoothing) |
The forcing options that can be prescribed through runtime parameters in
data
are easy to use but somewhat limited in scope. More complex forcing
setups are possible with optional packages such as :filelink:`pkg/exf` or
:filelink:`pkg/rbcs`, in which case most or all of the parameters in this
section can simply be left at their default value.
This section only applies to the ocean. You need to generate
wind-stress data into two files :varlink:`zonalWindFile` and
:varlink:`meridWindFile` corresponding to the zonal and meridional
components of the wind stress, respectively (if you want the stress
to be along the direction of only one of the model horizontal axes,
you only need to generate one file). The format of the files is
similar to the bathymetry file. The zonal (meridional) stress data
are assumed to be in pascals and located at U-points (V-points). See the MATLAB
program gendata.m
in the input
directories of
verification
for several tutorial example (e.g.
:filelink:`gendata.m <verification/tutorial_barotropic_gyre/input/gendata.m>`
in the :ref:`barotropic gyre tutorial <sec_eg_baro>`)
to see how simple analytical wind forcing data are generated for the
case study experiments.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`momForcing` | PARM01 | TRUE | included external forcing of momentum on/off flag |
:varlink:`zonalWindFile` | PARM05 | ' ' | filename for 2D specification of zonal component of wind forcing (N/m2) |
:varlink:`meridWindFile` | PARM05 | ' ' | filename for 2D specification of meridional component of wind forcing (N/m2) |
:varlink:`momForcingOutAB` | PARM03 | 0 | 1: take momentum forcing out of Adams-Bashforth time stepping |
:varlink:`momTidalForcing` | PARM01 | TRUE | tidal forcing of momentum equation on/off flag (requires tidal forcing files) |
:varlink:`ploadFile` | PARM05 | ' ' | filename for 2D specification of atmospheric pressure loading (ocean z-coor. only) (Pa) |
A combination of flux data and relaxation terms can be used for driving the tracer equations. For potential temperature, heat flux data (in W/m2) can be stored in the 2-D binary file :varlink:`surfQnetfile`. Alternatively or in addition, the forcing can be specified through a relaxation term. The SST data to which the model surface temperatures are restored are stored in the 2-D binary file :varlink:`thetaClimFile`. The corresponding relaxation time scale coefficient is set through the variable :varlink:`tauThetaClimRelax` (in seconds). The same procedure applies for salinity with the variable names :varlink:`EmPmRfile`, :varlink:`saltClimFile`, and :varlink:`tauSaltClimRelax` for freshwater flux (in m/s) and surface salinity (in g/kg) data files and relaxation timescale coefficient (in seconds), respectively.
.. tabularcolumns:: |\Y{.24}|\Y{.1}|\Y{.15}|\Y{.535}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`tempForcing` | PARM01 | TRUE | external forcing of temperature forcing on/off flag |
:varlink:`surfQnetFile` | PARM05 | ' ' | filename for 2D specification of net total heat flux (W/m2) |
:varlink:`surfQswFile` | PARM05 | ' ' | filename for 2D specification of net shortwave flux (W/m2); requires #define :varlink:`SHORTWAVE_HEATING` |
:varlink:`tauThetaClimRelax` | PARM03 | 0.0 | temperature (surface) relaxation time scale (s) |
:varlink:`lambdaThetaFile` | PARM05 | ' ' | filename for 2D specification of inverse temperature (surface) relaxation time scale (1/s) |
:varlink:`ThetaClimFile` | PARM05 | ' ' | filename for specification of (surface) temperature relaxation values (oC) |
:varlink:`balanceThetaClimRelax` | PARM01 | FALSE | subtract global mean heat flux due to temp. relaxation flux every time step on/off flag; requires #define :varlink:`ALLOW_BALANCE_RELAX` |
:varlink:`balanceQnet` | PARM01 | FALSE | subtract global mean Qnet every time step on/off flag; requires #define :varlink:`ALLOW_BALANCE_FLUXES` |
:varlink:`geothermalFile` | PARM05 | ' ' | filename for 2D specification of geothermal heating flux through bottom (W/m2); requires #define :varlink:`ALLOW_GEOTHERMAL_FLUX` |
:varlink:`temp_EvPrRn` | PARM01 | UNSET | temperature of rain and evaporated water (unset, use local temp.) (oC) |
:varlink:`allowFreezing` | PARM01 | FALSE | limit (ocean) temperature at surface to >= -1.9oC |
:varlink:`saltForcing` | PARM01 | TRUE | external forcing of salinity forcing on/off flag |
:varlink:`convertFW2Salt` | PARM01 | 3.5E+01 | salinity used to convert freshwater flux to salt flux (-1: use local S) (g/kg)
(note default is -1 if :varlink:`useRealFreshWaterFlux`= .TRUE. ) |
:varlink:`rhoConstFresh` | PARM01 | :varlink:`rhoConst` | constant reference density for fresh water (rain) (kg/m3) |
:varlink:`EmPmRFile` | PARM05 | ' ' | filename for 2D specification of net freshwater flux (m/s) |
:varlink:`saltFluxFile` | PARM05 | ' ' | filename for 2D specification of salt flux (from seaice) ((g/kg).kg/m2/s) |
:varlink:`tauSaltClimRelax` | PARM03 | 0.0 | salinity (surface) relaxation time scale (s) |
:varlink:`lambdaSaltFile` | PARM05 | ' ' | filename for 2D specification of inverse salinity (surface) relaxation time scale (1/s) |
:varlink:`saltClimFile` | PARM05 | ' ' | filename for specification of (surface) salinity relaxation values (g/kg) |
:varlink:`balanceSaltClimRelax` | PARM01 | FALSE | subtract global mean flux due to salt relaxation every time step on/off flag |
:varlink:`balanceEmPmR` | PARM01 | FALSE | subtract global mean EmPmR every time step on/off flag; requires #define :varlink:`ALLOW_BALANCE_FLUXES` |
:varlink:`salt_EvPrRn` | PARM01 | 0.0 | salinity of rain and evaporated water (g/kg) |
:varlink:`selectAddFluid` | PARM01 | 0 | add fluid to ocean interior options (-1, 0: off, or 1); requires #define :varlink:`ALLOW_ADDFLUID` |
:varlink:`temp_addMass` | PARM01 | :varlink:`temp_EvPrRn` | temp. of added or removed (interior) water (oC); requires #define :varlink:`ALLOW_ADDFLUID` |
:varlink:`salt_addMass` | PARM01 | :varlink:`salt_EvPrRn` | salinity of added or removed (interior) water (oC); requires #define :varlink:`ALLOW_ADDFLUID` |
:varlink:`addMassFile` | PARM05 | ' ' | filename for 3D specification of mass source/sink (+=source, kg/s); requires #define :varlink:`ALLOW_ADDFLUID` |
:varlink:`balancePrintMean` | PARM01 | FALSE | print subtracted balancing means to STDOUT on/off flag; requires #define :varlink:`ALLOW_BALANCE_FLUXES` and/or #define :varlink:`ALLOW_BALANCE_RELAX` |
:varlink:`latBandClimRelax` | PARM03 | whole domain | relaxation to (T,S) climatology equatorward of this latitude band is applied |
:varlink:`tracForcingOutAB` | PARM03 | 0 | 1: take T, S, and pTracer forcing out of Adams-Bashforth time stepping |
To prescribe time-dependent periodic
forcing, concatenate successive time records into a
single file ordered in a (x,y,time) fashion
and set the following variables: :varlink:`periodicExternalForcing` to
.TRUE.
, :varlink:`externForcingPeriod` to the period (in seconds between
two records in input files) with which
the forcing varies (e.g., 1 month), and :varlink:`externForcingCycle`
to the repeat time (in seconds) of the forcing (e.g., 1 year; note
:varlink:`externForcingCycle` must be a multiple of
:varlink:`externForcingPeriod`). With these variables specified, the model
will interpolate the forcing linearly at each iteration.
.. tabularcolumns:: |\Y{.25}|\Y{.1}|\Y{.125}|\Y{.55}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`periodicExternalForcing` | PARM03 | FALSE | allow time-dependent periodic forcing on/off flag |
:varlink:`externForcingPeriod` | PARM03 | 0.0 | period over which forcing varies (e.g. monthly) (s) |
:varlink:`externForcingCycle` | PARM03 | 0.0 | period over which the forcing cycle repeats (e.g. one year) (s) |
The beginning of a simulation is set by specifying a start time (in seconds)
through the real variable :varlink:`startTime` or by specifying an
initial iteration number through the integer variable :varlink:`nIter0`. If
these variables are set to non-zero values, the model will look for a
”pickup” file (by default, pickup.0000nIter0
) to restart the integration.
The end of a simulation is set through the real variable :varlink:`endTime`
(in seconds). Alternatively, one can instead specify the number of time steps
to execute through the integer variable :varlink:`nTimeSteps`.
Iterations are referenced to :varlink:`deltaTClock`, i.e., each iteration is
:varlink:`deltaTClock` seconds of model time.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`nIter0` | PARM03 | 0 | starting timestep iteration number for this integration |
:varlink:`nTimeSteps` | PARM03 | 0 | number of (model clock) timesteps to execute |
:varlink:`nEndIter` | PARM03 | 0 | run ending timestep iteration number (alternate way to prescribe :varlink:`nTimeSteps`) |
:varlink:`startTime` | PARM03 | :varlink:`baseTime` | run start time for this integration (s) (alternate way to prescribe :varlink:`nIter0`) |
:varlink:`endTime` | PARM03 | 0.0 | run ending time (s) (with :varlink:`startTime`, alternate way to prescribe :varlink:`nTimeSteps`) |
The precision with which to read binary data is
controlled by the integer variable :varlink:`readBinaryPrec`, which can take
the value 32 (single precision) or 64 (double precision). Similarly, the
precision with which to write binary data is controlled by the integer variable
:varlink:`writeBinaryPrec`. By default, MITgcm writes output (snapshots,
diagnostics, and pickups) separately for individual tiles, leaving it to the
user to reassemble these into global files, if needed (scripts are available in
:filelink:`utils/`). There are two options however to have the model do this
for you. Setting :varlink:`globalFiles` to .TRUE.
should always work in a
single process setup (including multi-threaded processes), but for
MPI runs this will
depend on the platform -- it requires simultaneous write access to a common
file (permissible in typical
Lustre setups, but not
on all file systems). Alternatively, one can set :varlink:`useSingleCpuIO`
to .TRUE.
to generate global files, which should always work, but requires
additional mpi-passing of data and may result in slower execution.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`globalFiles` | PARM01 | FALSE | write output “global” (i.e. not per tile) files on/off flag |
:varlink:`useSingleCpuIO` | PARM01 | FALSE | only master MPI process does I/O (producing global output files) |
:varlink:`the_run_name` | PARM05 | ' ' | string identifying the name of the model "run" for meta files |
:varlink:`readBinaryPrec` | PARM01 | 32 | precision used for reading binary files (32 or 64) |
:varlink:`writeBinaryPrec` | PARM01 | 32 | precision used for writing binary files (32 or 64) |
:varlink:`outputTypesInclusive` | PARM03 | FALSE | allows writing of output files in multiple formats (i.e. :filelink:`pkg/mdsio` and :filelink:`pkg/mnc`) |
:varlink:`rwSuffixType` | PARM03 | 0 | controls the format of the :filelink:`pkg/mdsio` binary file “suffix”
where :varlink:`myTime` is model time in seconds |
:varlink:`mdsioLocalDir` | PARM05 | ' ' | if not blank, read-write output tiled files from/to this directory name (+four-digit processor-rank code) |
The frequency (in seconds) with which output is written to disk needs to be specified. :varlink:`dumpFreq` controls the frequency with which the instantaneous state of the model is written. :varlink:`monitorFreq` controls the frequency with which monitor output is dumped to the standard output file(s). The frequency of output is referenced to :varlink:`deltaTClock`.
.. tabularcolumns:: |\Y{.18}|\Y{.1}|\Y{.2}|\Y{.545}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`dumpFreq` | PARM03 | 0.0 | interval to write model state/snapshot data (s) |
:varlink:`dumpInitAndLast` | PARM03 | TRUE | write out initial and last iteration model state on/off flag |
:varlink:`diagFreq` | PARM03 | 0.0 | interval to write additional intermediate (debugging cg2d/3d) output (s) |
:varlink:`monitorFreq` | PARM03 | lowest of other output *Freq parms | interval to write monitor output (s) |
:varlink:`monitorSelect` | PARM03 | 2 (3 if fluid is water) | select group of monitor variables to output
|
:varlink:`debugLevel` | PARM01 | depends on :varlink:`debugMode` | level of printing of MITgcm activity messages/statistics (1-5, higher -> more activity messages) |
:varlink:`plotLevel` | PARM01 | :varlink:`debugLevel` | controls printing of field maps (1-5, higher -> more fields) |
:varlink:`chkPtFreq` and :varlink:`pchkPtFreq` control the output frequency of rolling and permanent pickup (a.k.a. checkpoint) files, respectively. These frequencies are referenced to :varlink:`deltaTClock`.
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`pChkPtFreq` | PARM03 | 0.0 | permanent restart/pickup checkpoint file write interval ( s ) |
:varlink:`chkPtFreq` | PARM03 | 0.0 | rolling restart/pickup checkpoint file write interval ( s ) |
:varlink:`pickupSuff` | PARM03 | ' ' | force run to use pickups (even if :varlink:`nIter0` =0) and read files with this suffix (10 char. max) |
:varlink:`pickupStrictlyMatch` | PARM03 | TRUE | force pickup (meta) file formats to exactly match (or terminate with error) on/off flag |
:varlink:`writePickupAtEnd` | PARM03 | FALSE | write a (rolling) pickup file at run completion on/off flag |
:varlink:`usePickupBeforeC54` | PARM01 | FALSE | initialize run using old pickup format from code prior to checkpoint54a |
:varlink:`startFromPickupAB2` | PARM03 | FALSE | using Adams-Bashforth-3, start using Adams-Bashforth-2 pickup format; requires #define :varlink:`ALLOW_ADAMSBASHFORTH_3` |
Some optional packages were not written with package-specific namelist
parameters in a data.${pkg}
file; or for historical and/or other reasons,
several package-specific namelist parameters remain in data
.
(package :filelink:`pkg/cd_code`)
If you run at a sufficiently coarse resolution, you might choose to enable the C-D scheme for the computation of the Coriolis terms. The variable :varlink:`tauCD`, which represents the C-D scheme coupling timescale (in seconds) needs to be set.
.. tabularcolumns:: |\Y{.175}|\Y{.1}|\Y{.225}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`useCDscheme` | PARM01 | FALSE | use C-D scheme for Coriolis terms on/off flag |
:varlink:`tauCD` | PARM03 | :varlink:`deltaTMom` | C-D scheme coupling timescale (s) |
:varlink:`rCD` | PARM03 | 1 - :varlink:`deltaTMom`/:varlink:`tauCD` | C-D scheme normalized coupling parameter (non-dim.) |
:varlink:`epsAB_CD` | PARM03 | :varlink:`abEps` | Adams-Bashforth-2 stabilizing weight used in C-D scheme |
(package :filelink:`pkg/autodiff`; see :numref:`chap_autodiff`)
.. tabularcolumns:: |\Y{.225}|\Y{.1}|\Y{.125}|\Y{.575}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`nTimeSteps_l2` | PARM03 | 4 | number of inner timesteps to execute per timestep |
:varlink:`adjdumpFreq` | PARM03 | 0.0 | interval to write model state/snapshot data adjoint run (s) |
:varlink:`adjMonitorFreq` | PARM03 | 0.0 | interval to write monitor output adjoint run (s) |
:varlink:`adTapeDir` | PARM05 | ' ' | if not blank, read-write checkpointing files from/to this directory name |
If running multi-threaded (i.e., using shared memory/OpenMP), you will need to set :varlink:`nTx` and/or :varlink:`nTy` so that :varlink:`nTx`*:varlink:`nTy` is the total number of threads (per process).
The parameter :varlink:`useCubedSphereExchange` needs to be changed to
.TRUE.
if you are using any type of grid composed of interconnected
individual faces, including the cubed sphere topology or a lat-lon cap grid.
See (needs section to be written).
Note that setting flag :varlink:`debugMode` to .TRUE.
activates a separate
set of debugging print statements than parameter :varlink:`debugLevel`
(see :numref:`freq_of_output`). The latter controls print statements that
monitor model activity (such as opening files, etc.), whereas the former
produces a more coding-oriented set of print statements (e.g., entering and
exiting subroutines, etc.)
.. tabularcolumns:: |\Y{.25}|\Y{.125}|\Y{.125}|\Y{.525}|
Parameter | Group | Default | Description |
---|---|---|---|
:varlink:`useCubedSphereExchange` | EEPARMS | FALSE | use cubed-sphere topology domain on/off flag |
:varlink:`nTx` | EEPARMS | 1 | number of threads in the x direction |
:varlink:`nTy` | EEPARMS | 1 | number of threads in the y direction |
:varlink:`useCoupler` | EEPARMS | FALSE | communicate with other model components through a coupler on/off flag |
:varlink:`useSETRLSTK` | EEPARMS | FALSE | call C routine to set environment stacksize to ‘unlimited’ |
:varlink:`useSIGREG` | EEPARMS | FALSE | enable signal handler to receive signal to terminate run cleanly on/off flag |
:varlink:`debugMode` | EEPARMS | FALSE | print additional debugging messages; also “flush” STDOUT file unit after each print |
:varlink:`printMapIncludesZeros` | EEPARMS | FALSE | text map plots of fields should ignore exact zero values on/off flag |
:varlink:`maxLengthPrt1D` | EEPARMS | 65 | maximum number of 1D array elements to print to standard output |
MITgcm input files for grid-related data (e.g., :varlink:`delXFile`), forcing fields (e.g., :varlink:`tauThetaClimRelax`), parameter fields (e.g., :varlink:`viscAhZfile`), etc. are assumed to be in "flat" or "unblocked" binary format. For historical reasons, MITgcm files use big-endian byte ordering, NOT little-endian which is the more common default for today's computers. Thus, some care is required to create MITgcm-readable input files.
Using MATLAB: When writing binary files, MATLAB's fopen command includes a MACHINEFORMAT option
'b'
which instructs MATLAB to read or write using big-endian byte ordering. 2-D arrays should be index-ordered in MATLAB as (x, y) and 3-D arrays as (x, y, z); data is ordered from low to high in each index, with x varying most rapidly.An example to create a bathymetry file of single-precision, floating point values (from tutorial :ref:`sec_eg_baro`, a simple enclosed, flat-bottom domain) is as follows:
ieee = 'b'; % big-endian format accuracy = 'float32'; % this is single-precision (='real*4') Ho=5000; % ocean depth in meters nx=62; % number of gridpoints in x-direction ny=62; % number of gridpoints in y-direction % Flat bottom at z = -Ho h = -Ho * ones(nx, ny); % Walls (surrounding domain) h([1 end], :) = 0; % set ocean depth to zero at east and west walls h(:, [1 end]) = 0; % set ocean depth to zero at south and north walls % save as single-precision (float32) with big-endian byte ordering fid = fopen('bathy.bin', 'w', ieee); fwrite(fid, h, accuracy); fclose(fid);
To read this bathymetry file back into MATLAB, reshaped back to (nx, ny):
fid = fopen('bathy.bin', 'r', ieee); h = reshape(fread(fid, Inf, accuracy), nx, ny); fclose(fid);
Using Python:
A python version of the above script to create a bathymetry file is as follows:
import numpy as np Ho = 5000 # ocean depth in meters nx = 62 # number of gridpoints in x-direction ny = 62 # number of gridpoints in y-direction # Flat bottom at z = -Ho h = -Ho * np.ones((ny, nx)) # Walls (surrounding domain) h[:, [0,-1]] = 0 # set ocean depth to zero at east and west walls h[[0,-1], :] = 0 # set ocean depth to zero at south and north walls # save as single-precision (NumPy type float32) with big-endian byte ordering h.astype('>f4').tofile('bathy.bin')
The dtype specification
'>f4'
above instructs Python to write the file with big-endian byte ordering (specifically, due to the '>') as single-precision real numbers (due to the 'f4' which is NumPyfloat32
or equivalently, Fortranreal*4
format).To read this bathymetry file back into Python, reshaped back to (ny, nx):
h = np.fromfile('bathy.bin', '>f4').reshape(ny, nx)
where again the dtype spec instructs Python to read a big-endian file of single-precision, floating point values.
Note that 2-D and 3-D arrays should be index-ordered as (y, x) and (z, y, x), respectively, to be written in proper ordering for MITgcm.
A more complicated example of using Python to generate input date is provided in :filelink:`verification/tutorial_baroclinic_gyre/input/gendata.py`.
Using Fortran: To create flat binary files in Fortran, open with syntax
OPEN(..., ACCESS='DIRECT', ...)
(i.e., NOTACCESS='SEQUENTIAL'
which includes additional metadata). By default Fortran will use the local computer system's native byte ordering for reading and writing binary files, which for most systems will be little-endian. One therefore has two options: after creating a binary file in Fortran, use MATLAB or Python (or some other utility) to read in and swap the bytes in the process of writing a new file; or, determine if your local Fortran has a compiler flag to control byte-ordering of binary files. Similar to MATLAB, 2-D and 3-D arrays in Fortran should be index-ordered as (x, y) and (x, y, z), respectively.
Using NetCDF format for input files is only partially implemented at present in MITgcm, and use is thus discouraged.
Input files are by default single-precision real numbers (32-bit, real*4
),
but can be switched to double precision by setting
namelist parameter :varlink:`readBinaryPrec` (PARM01
in file data
)
to a value of 64.