GFDL - Geophysical Fluid Dynamics Laboratory

The HIM User’s Manual

by Robert Hallberg1

NOAA Geophysical Fluid Dynamics Laboratory

last updated June 30, 2002

This technical note describes how the Hallberg Isopycnal Model (HIM) is used
and configured. The numerical schemes used in HIM are described elsewhere.


The Hallberg Isopycnal Model (HIM) simulates the ocean by numerically solving
the Boussinesq primitive equations in isopycnal vertical coordinates and general
orthogonal horizontal coordinates. These equations are horizontally discretized
on an Arakawa C-grid. There are a range of options for the physical parameterizations,
from those most appropriate to highly idealized models for studies of geophysical
fluid dynamics to a rich suite of processes appropriate for realistic ocean simulations.
The thermodynamic options range from an adiabatic model with fixed density layers
to a model with temperature and salinity as state variables and using a full nonlinear
equation of state. The uppermost few layers may be used to describe a bulk mixed
layer, including the effects of penetrating shortwave radiation. Either a split-
explicit time stepping scheme or a non-split scheme may be used for the dynamics,
while the time stepping may be split (and use different numbers of steps to cover
the same interval) for the forcing, the thermodynamics, and for the dynamics. Most
of the numerics are second order accurate in space and great care is taken in the
handling of vanishing layers.

This user’s manual describes how to configure and run HIM. It is short because
the model is fairly simple to run. It is the author’s experience that a number of
people have been able to get scientifically meaningful simulations going in less
than a day with about this level of guidance.

Running HIM

Typically HIM is compiled and run from a working directory. That directory usually
contains the makefile (Makefile), the include file init.h, in which many parameters
of the run are specified, and any source or header files which differ from the canonical
case (initialize.c is almost always modified). The Makefile must reflect the locations
of the source files to be used, and compilation is required after each change in

When run, HIM takes four lines of input. The first queries whether a new run
is to be started (in which case the response is `n’), or restarted (`r’) from a
restart file, or initialized from a saves file (in which case the response is the
name of the saves file). The second line is a directory to be used to read input
files. The third line is a directory to use for writing output. If the third line
is omitted, the directory specified in the second line is used for output. The fourth
line is the path of a namelist file (with the same format as init.h) that is read
to override the values specified in init.h at run time. HIM prompts the interactive
user for all of these inputs.

HIM can be run in parallel with 1-D or 2-D domain decomposition, if PARALLEL_X
or PARALLEL_Y are defined in init.h. The number of processors may be specified at
run time, but must be in the range from NXPROC*NYPROC to MAXPROC. If this flexibility
is not needed, memory can be saved by setting MAXPROC equal to NXPROC*NYPROC. Either
MPI or shmem can be used for the parallelization, depending on whether or not MPI_PARALLEL
is defined in init.h

Setting initial conditions

Initial conditions are specified in two places; domain wide parameters are set
in the include file init.h, while initial fields are specified or read in initialize.c.
Any input file can be read (in initialize.c) from a netcdf file with the same grid
as the simulation. Some of the domain-wide parameters can be respecified at run
time (without recompiling) in the namelist file.

Inside of initialize.c are a number (of order 10) of subroutines with self-explanatory
names like USER_initialize_velocity. These subroutines can be used to read the fields
from a specified file. Otherwise, the user can internally calculate all of the appropriate

Specifying the forcing

Boundary flux or restoring boundary conditions are specified by modifying surface_forcing.c.
In that file, fields may be calculated internally or read from NetCDF files. Working
examples of both types are given with the HIM1.10 beta release. The user can specify
a wide range of fluxes by setting pointers to them in the forcing structure “fluxes”.
Most sensible combinations of fluxes should be handled gracefully. For example,
either the combined precipitation minus evaporation may be given, or the user may
provide separate precipitation and evaporation fields, but there will be an error
if precipitation is given but evaporation is not! The forcing sign convention is
that all fluxes (of momentum, heat, or fresh water) are positive into the ocean.

Choosing the included parameterizations

The choice of parameterizations is made through C-preprocessor directives in
init.h, or by replacing one file with another in a makefile. (For example, continuity.c,
continuity_MPDATA.c and continuity_FCT.c are interchangeable.) Most of the options
are fairly well documented in init.h.

Output and post-processing

When a new simulation is started, HIM saves a file with a name like D.100.150.12.cdf
(for a run with 100 by 150 points in the compuational domain and 12 layers), which
contains fields, like bottom depth, which do not change during the simulation. In
addition, a

HIM will automatically produce restart files periodically, with a frequency (in
days) specified by the definition of RESTINT in init.h or the namelist file. From
these files a simulation can be resumed with exactly the same results as if it had
never been interrupted. In addition, HIM may be directed to save a restart file
and stop itself after a given amount of CPU time has been consumed.

HIM can be directed to save a wide array of model state variables and diagnostic
quantities. The output is dictated primarily in initialize_output.c. Elsewhere in
the code are numerous tests to calculate or record diagnostic quantities that are
requested by allocating the corresponding space in the diagnostic structure diag.
Output may be either of instantaneous fields, or of time averages. Different files
may be saved with different frequencies and starting at different times. The user
controls all of this with the calls made from initialize_output.c or from another
appropriate location such as surface_forcing.c or USER_tracer_example.c.

All output, including restart files, is in NetCDF. Previous incarnations of HIM
also allowed native binary output, but there was no real justification for retaining
that facility.

Compatible pre- and postprocessing code that prepares initial condition fields
or reproduces diagnostic quantities will be released shortly after the HIM1.10 public

Further Reading

The reference to the technical description of all of the numerical algorithms
will be provided as they are accessible, although a somewhat dated version is available, and extensive updates are planned. Certain aspects
are described in the following papers in the peer-reviewed literature.

Griffies, S., and R. Hallberg, 2000: Biharmonic friction with a Smagorinsky-like
viscosity for use in large-scale eddy-permitting ocean models. Mon. Wea. Rev.
, in press.

Hallberg, R., and P. B. Rhines, 1996: Buoyancy-driven circulation in an ocean
basin with isopycnals intersecting the sloping boundary. J. Phys. Oceanogr
., 26 , 913-940.

Hallberg, R., 1997: Stable split time stepping for large-scale ocean modeling.
J. Comp. Phys ., 135 , 54-65.

Hallberg, R., 2000: Time integration of diapycnal diffusion and Richardson number-dependent
mixing in isopycnal coordinate ocean models. Mon. Wea. Rev ., 128
, 1402-1419.

1.Corresponding Author Address: Dr. Robert Hallberg, NOAA GFDL, Princeton University,
Forrestal Campus, U. S. Route 1, 201 Forrestal Road, Princeton, NJ 08542; e-mail:;
phone (609)452-6508