The HIM User’s Manual

by Robert Hallberg¹

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.

Overview

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 code.

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 NXPROCNYPROC to MAXPROC. If this flexibility is not needed, memory can be saved by setting MAXPROC equal to NXPROCNYPROC. 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 runtimetime (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 fields.

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 computational 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 release.