Skip to content

Q GCM Tutorial

Jump to bottom Edit New page
Chris Chapman edited this page May 22, 2014 · 9 revisions

#Introduction

The purpose of this guide is to help new users quickly compile and run the Q-GCM. For more detailed information, please see the Q-GCM users guide, available on the Q-GCM website (q-gcm.org).

This quick start guide proceeds by way of an example. We will compile and run a simple double gyre case with simple “box” geometry, in an uncoupled, ocean only mode.

#Getting Started

Before you begin, note that we have tested Q-GCM on Unix based systems only. Q-GCM has not been tested on Windows based machines.

##Prerequisites

To begin, you will need:

  • A Fortran compiler;
  • Access to the LAPACK and BLAS linear algebra libraries. If using an Intel Fortran compiler, note that Intel's Math Kernal Library (MKL) contains these routines. LAPACK/BLAS can be downloaded from netlib;
  • If a parallel OpenMP compilation is desired, OpenMP libraries are required.

Although not strictly necessary, the use of NetCDF as both an input and output data format is recommended. NetCDF libraries are available from Unidata.

##Directory Structure

Downloading Q-GCM from the website or Github and extract the contents. The Q-GCM files are contained in the directory q-gcm. The source code is contained in the directory src. Example configuration files are contained in the directory examples. Within the examples directory, there are four directories, each containing the files required to run an example case:

  • double_gyre_ocean_only (uses box ocean basin geometry);
  • double_gyre_coupled (uses box ocean basin geometry);
  • southern_ocean_ocean_only (uses channel geometry);
  • southern_ocean_coupled (uses channel geometry).

As an example, we will use the double gyre ocean only case. Navigate to the double_gyre_ocean_only directory and examine the contents. You should see the following files:

  • parameters_data.F.dg_oo. A Fortran file that is used for the set the number of grid points in the domain. This file is required to compile the code;
  • make.config.dg_oo. A file used by Make to compile the code.
  • input.params.dg_oo. An input file used to specify a number of parameters for the model. It is required when running the model, and is not required for to compile the code.
  • avges.nc.dg_oo. An input file used to specify the imposed wind forcing. A file of this type is required by Q-GCM when run in either ocean only or atmosphere only configuration, and is not required in a coupled model run.

#Compiling

Compiling is accomplished using a makefile. Example makefiles are included with the distribution in the src directory.

The complete makefile consists of three sub files:

  • make.config is used to configure Q-GCM to the particular kind of problem you wish to solve (for example: enclosed basin or channel geometry; coupled ocean and atmosphere or ocean only). This file contains various flags which can be turned `on' or 'off' by the user to enable them to configure the model;
  • make.macro is used to configure the build to the user's system. This file allows the use to specify the Fortran compiler to be used; the locations of NetCDF and/or LAPACK libraries and included variables; and compiler options (such as the level of optimisation and whether to compile against static or dynamic libraries).
  • Makefile which takes the make.config and make.macro as inputs. It should not be necessary for the user to alter the contents of this file.

For the double gyre ocean only case, an example make.config.dg.oo included in the examples/double_gyre_ocean_only directory. Navigate to this directory and view this file.

Navigate to the examples directory and view the make.config.dg.oo file.

You should see that three compiler preprocessor directives are set:

  • OCOPT = -Docean_only. Sets ocean only mode;
  • NCOPT = -Duse_netcdf. Specifies we are using NetCDF for I/O.
  • HFLUX = -Dsb_hflux. Sets the equatorward temperature boundary conditions.

Other directives may be turned on or off at the user's discretion.

Copy this file to the src directory, removing the .dg.oo tag at end of the file name:

$cp make.config.dg.oo path_to_qgcm/src/make.config

While still in the examples/double_gyre_ocean_only directory, view the parameters_data.F.dg_oo file. This file is used by Q-GCM to determine number of grid points in the domain and to allocate memory for the arrays used in the model. For the current example, the file specifies that the domain is to be 960x960 grid points.

All memory allocation in the model is performed statically in order to reduce the run time. As such, should you desire to change the number of grid points in the domain, the model will have to be recompiled!

When you are satisfied with the domain size, move the file to the src directory, dropping the dg_oo tag as before:

$cp parameters_data.F.dg_oo path_to_source/src/parameters_data.

Now, navigate to the src directory. There you should find the Make and make.macro files.

Examine the contents of the make.macro file. There are 3 main blocks in the file:

  • A block for the configuration of the Fortran compiler;
  • A block for the configuration of the LAPACK/BLAS libraries;
  • A block for the configuration of Netcdf libraries.

The first block allows for the user to set their Fortran compiler, specify options (such as the level of optimisation) and the OpenMP options for parallelisation.

The 2nd block allows for the user to specify their LAPACK/BLAS configuration. If building Q-GCM using the Intel MKL libraries, the following library search path and compiler flags must be set:

LAPACK = path_to_mkl_libraries -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core

If you are using a locally built version of the LAPACK/BLAS, in addition to setting the search path and library flags, the user must also LAPSRC and LAPOBJ options to ensure that the required subroutines are included.

The 3rd block configures the NetCDF I/O. The user must include the built-in NetCDF variables by linking to the include file, as well as linking to the NetCDF libraries:

NCBASE = path_to_netcdf_source

NCIDIR = ${NCBASE}/include

NCDINC = ${NCIDIR}/netcdf.inc

NCINCL = -I${NCIDIR}

When you are satisfied with the configuration, Q-GCM can be compiled by invoking the make command in the src directory.

$make q-gcm

If the compilation is successful, an executable file q-gcm will be produced.

#Running Q-GCM

The Q-GCM executable requires several input files in order to run. These files are:

  • input.params (specifies model parameters, such as grid spacing, layer depths, etc...);
  • outdata.dat (specifies where the model should write output. An example outdata.dat file is included in the src directory. ).

In addition, depending on the configuration of the model, several more input files might be needed. These include:

  • avges.nc (Specifies the input surface forcing in an atmosphere or ocean only cases);
  • topography file - the name of the input topography file is set in input.params
  • initial state file – the name of this file is set in input.params

For the double gyre, ocean only example case, we require the avges.nc to impose the wind stress, but the model will be started from a motionless initial state and will have a flat bottom topography, so neither an initial condition file, nor a topography file are required.

To run Q-GCM, it is good practice to create a clean directory to run the model in. For example:

$mkdir example_path/test_run_1.

Then, copy the executable and all required files to the test_run_1 directory.

$ cp path_to_qgcm/src/q-gcm example_path/test_run_1

$ cp path_to_qgcm/ examples/double_gyre_ocean_only/input.params example_path/test_run_1

$ cp path_to_qgcm/ examples/double_gyre_ocean_only/avges.nc example_path/test_run_1

and create an outdata.dat file in the test_run_1 directory to tell Q-GCM where to send its output:

$ echo example_path/test_run_1/output > example_path/test_run_1/outdata.dat.

Now, navigate to the example_path/test_run_1 directory. Investigate the input.params file. The first block in the file is for the user to specify the length of time (in model years) that Q-GCM will be run for. Select a run time of 20 days by uncommenting (i.e. Remove the '!') the line that begins with 0.054794521. Ensure all other 'trun' lines are commented out so that Q-GCM does no become confused.

##OpenMP parallelisation

If using OpenMP parallelisation, you must also set the OMP_NUM_THREADS environment variable that tells the processor how many threads to spawn. This environment variable can be set with the command:

$export OMP_NUM_THREADS = 8

##Stacksize Limits

Before running Q-GCM, it is a good idea to ensure that the stacksize limits have been increased to their maximum, otherwise Q-GCM can give you infuriating segmentation faults. In the bash shell, the stacksize limits can be set with the command:

$ulimit -s unlimited

##Running the Executable Finally to run the model, simply invoke the executable:

$./q-gcm > qgcm.log

Model diagnostics should be piped to the text file qgcm.log, while the output is sent to the location indicated in outdata.dat

Add a custom footer
Add a custom sidebar
Clone this wiki locally