.. _computational-options:

Computational options
======================

Barotropic mode solver
-----------------------

As part of the implicit solution of the barotropic mode, a
two-dimensional elliptic equation for the surface pressure is solved.
Two solver methods are available, both iterative: preconditioned
conjugate gradient and a Chronopouos-Gear form of pcg requiring fewer
global reductions. Convergence of the iterative solvers is governed by
the two parameters ``convergenceCriterion`` and ``maxIterations`` as
shown in the table below. The convergence criterion
``convergenceCriterion`` should be chosen small enough such that the
pressure balance (printed as part of the model global diagnostics)
agrees to 3-4 digits. The parameter ``maxIterations`` must be chosen
large enough to allow the solver to converge (typically a few hundred),
but small enough so that the code will terminate in a reasonable time if
the solver is unable to converge.

.. todo:: Add link to namelist group **&solvers** for **Barotropic solver namelist**

Occasionally, when benchmarking the code, it is useful to fix the
number of iterations to give a consistent iteration count between
runs. In this case, ``convergenceCriterion`` is set to exactly zero
and the solver will iterate ``maxIterations`` and continue with the
simulation without terminating. This feature should only be used for
benchmarking and not for actual ocean simulations.

The ``convergenceCheckFreq`` provides a means to improve performance by
checking for convergence every ``convergenceCheckFreq`` iterations, thus
eliminating an extra global sum on most iterations. Another means for
improving performance is to supply a preconditioner to improve
convergence. The preconditioner must be computed off-line and must be in
the form of a nine point stencil operator. The preconditioner is then
supplied in a file named ``preconditionerFile`` containing the nine
operator weights.

Advection methods
------------------

Currently, advection of momentum is always done by leapfrog centered
advection with periodic `'mixing' steps. <node33.html#sec:op-timemanager>`__ For tracer advection, three
options are available. The first is standard leapfrog centered
advection; the second is a 3\ :sup:`rd`-order upwinding [Leonard] which,
although not monotone, will improve monotonicity at a somewhat increased
computational cost, and the third, available only in CESM1 POP2, is a
one-dimensional Lax-Wendroff with one-dimensional flux limiters.

.. todo:: Add link to namelist group **&advect** for **Advection namelist**

Pressure gradient options
--------------------------

The pressure-averaging technique was explained in `a previous
section. <node10.html#sec:improve-pressavg>`__ Because it increases the
timestep, it should always be enabled. The option to turn it off is
provided only to permit comparisons with and without pressure-averaging
or between POP and other codes that do not incorporate this technique.

The pressure gradient term includes a density factor which is assumed to
be a constant reference density in Boussinesq models. The
depth-dependent pressure effects on this density can be corrected for
using simple depth-dependent factors.

.. todo:: Add link to namelist group **&advect** for **Pressure averaging namelist**