Skip to content

Latest commit

 

History

History
181 lines (119 loc) · 5.6 KB

README.md

File metadata and controls

181 lines (119 loc) · 5.6 KB
Raw

Autoconf Build Configuration

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.

Requirements

The following tools and libraries must be installed on your system.

  • Autoconf
  • Fortran compiler (e.g. GFortran)
  • MPI (e.g. Open MPI, MPICH)
  • netCDF, with Fortran support

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.

Quick start guide

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.

Build rules

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.

Build configuration settings

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.

GFDL Dependencies

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)

Known issues / Future development

MPI configuration

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.

Coupled builds

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.