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.

Table: Barotropic solver namelist

&solvers	LANL default	CESM1 default	Valid values	Control of iterative solver for barotropic mode
solverChoice	'pcg'	'ChronGear'	'pcg', 'ChronGear'	preconditioned conjugate gradient or Chronopoulis-Gear preconditioned conjugate-gradient
preconditionerChoice	'diagonal'	'diagonal'	'diagonal', 'file'	If 'diagonal', then no preconditioner is used. If 'file', then a preconditioner is used to reduce number of iterations to convergence
preconditionerFile	'unknownPrecondFile'	'unknownPrecondFile'	string ≤ 256 characters	file containing preconditioner coefficients for solver
convergenceCriterion	1.0e-12	1.0e-13	< 1.0	convergence criterion: |δX/X| < convergenceCriterion
maxIterations	1000	1000	integer > 1	upper limit on number of iterations allowed
convergenceCheckFreq	10	10	integer ≥ 0	check for convergence every convergenceCheckFreq iterations
/

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.