This directory contains the configuration files required to build MOM6 using Autoconf.
Note that a top-level ./configure is not contained in the repository, and the
instruction below will generate this script in the ac directory.
The following tools and libraries must be installed on your system.
On some platforms, such as macOS, the Autoconf package may also require an installation of Automake.
Some packages such as netCDF may require an additional packages for Fortran support.
The following instructions will allow a new user to quickly create a MOM6 executable for ocean-only simulations.
Before starting, ensure that all submodules have been updated.
$ git submodule update --init --recursive
Next, fetch the GFDL mkmf build tool and build the FMS framework library.
For new users, a separate Makefile in ./ac/deps/ is provided for this step.
$ cd ac/deps
$ make -j
To build MOM6, first generate the Autoconf configure script in ./ac.
$ cd ../.. # Return to the root directory
$ cd ac
$ autoreconf
Then select your build directory, run the configure script, and build the model.
The instructions below build the model in the ./build directory.
$ cd .. # Return to the root directory
$ mkdir -p build
$ cd build
$ ../ac/configure
$ make -j
This will create the MOM6 executable in the build directory.
The steps above will produce an executable for ocean-only simulations, and
cannot be used for coupled modeling. It also requires the necessary experiment
configuration files, such as input.nml and MOM_input. For more
information, consult the MOM6-examples
wiki.
The Makefile produced by Autoconf provides the following rules.
make
Build the MOM6 executable.
make clean
Delete the executable and any object and module files, but preserve the Autoconf output.
make distclean
Delete all of the files above, as well as any files generated by
./configure. Note that this will delete the Makefile containing this rule.
make ac-clean
Delete all of the files above, including ./configure and any other files
created by autoreconf. As with make distclean, this will also delete the
Makefile containing this rule.
Autoconf will resolve most model dependencies, and includes the standard set of
configuration options, such as FC or FCFLAGS. The configure settings
specific to MOM6 are described below.
--enable-asymmetric
The MOM6 executable is configured to use symmetric grids by default.
Use the flag above to compile using uniform (asymmetric) grids.
Symmetric grids are defined such that the fields for every C-grid cell are fully specified by their local values. In particular, quantities such as velocities or vorticity are defined along the boundaries of the domain.
Use of symmetric grids simplifies many calculations, but also results in nonuniform domain sizes for different fields, and slightly greater storage since the additional values can be considered redundant.
--enable-openmp
Use this flag to enable OpenMP in the build.
--disable-real-8
While MOM6 does not explicitly use double precision reals, most of the algorithms are designed and tested under this assumption, and the default configuration is to enforce 8-byte reals.
This flag may be used to relax this requirement, causing the compiler to use the default size (usually single precision reals), although there is no guarantee that the model will be usable.
For the complete list of settings, run ./configure --help.
This section briefly describes the management of the mkmf and FMS
dependencies.
When building MOM6, the configure script will first check if the compiler and
its configured flags (FCFLAGS, LDFLAGS, etc.) can locate mkmf and the FMS
library. If unavailable, then it will search in the local ac/deps library.
If still unavailable, then the build will abort.
The dependencies are not automatically provided in ac/deps. However, running
make -C ac/deps will fetch and build them. If the user wishes to target an
external FMS library or mkmf tools, then they should set PATH, FCFLAGS
and LDFLAGS so that configure can locate them.
Exported environment variables such as FC or FCFLAGS will be passed to the
corresponding configure scripts.
The following configuration options are also provided, which can be used to specify the git URL and commit of the dependencies.
MKMF_URL (default: https://github.com/NOAA-GFDL/mkmf.git)
MKMF_COMMIT(default: master)
FMS_URL (default: https://github.com/NOAA-GFDL/FMS.git)
FMS_COMMIT (default: 2019.01.03)
There are minor issues with the MPI configuration macro, where it may use an
MPI build wrapper (e.g. mpifort) whose underlying compiler does not match
the FC compiler, which will often be auto-configured to gfortran.
This is usually not an issue, but can cause confusion if FCFLAGS is
configured for the MPI wrapper but is incompatible with the FC compiler.
To resolve this, ensure that FC and FCFLAGS are specified for the same
compiler.
The Autoconf build is currently only capable of building ocean-only executables, and cannot yet be used as part of a coupled model, nor as a standalone library. This is planned to be addressed in a future release.