PUBLIC INTERFACE / ROUTINES / NAMELIST / ERRORS / REFERENCES / NOTES

## Module shallow_conv_mod

         Contact:   Peter Phillipps
         Reviewers:

#### OVERVIEW

         Produces regularized topography according to Lindberg and Broccoli,
         J. of Climate vol 9, no 11 pg. 2641-2659 (1996)

       Smooths topography in such a way as to reduce Gibbs ripples that
       result from spectral truncation.

#### OTHER MODULES USED

      mpp_mod
      transforms_mod
      fms_mod
      global_integral_mod
      spec_mpp_mod
      mpp_domains_mod

#### PUBLIC INTERFACE

    use topog_regularization_mod [,only: compute_lambda, regularize]

    regularize - Performs regularization of topography.

    compute_lambda - Given a fractional smoothing over water, returns
                     lambda, the smoothing constant which is input to
    		 subroutine regularize.

#### PUBLIC ROUTINES

     call regularize( lambda, ocean_mask, unsmoothed_field, smoothed_field, fraction_smoothed )

    input:

       real :: lambda -- Determines degrees of smoothing
                        (Smoothing increases with increasing lambda)

       logical, dimension(:,:) :: ocean_mask -- .true. over ocean, false over land

       real, dimension(:,:) :: unsmoothed_field -- The unsmoothed topography

    output:

       real, dimension(:,:) :: smoothed_field -- The smoothed topography

       real :: fraction_smoothed -- The fractional smoothing over water.
    ---------------------------------------------------------------------

      call compute_lambda( ocean_topog_smoothing, ocean_mask, &
                        unsmoothed_field, lambda, actual_fraction_smoothed )

    input

       real, ocean_topog_smoothing -- The desired fractional smoothing over water.

       logical, dimension(:,:) :: ocean_mask -- .true. over ocean, false over land

       real, dimension(:,:) :: unsmoothed_field -- The unsmoothed topography

    output

       real :: lambda -- Determines degrees of smoothing
                        (Smoothing increases with increasing lambda)

       real :: actual_fraction_smoothed -- The actual fraction smoothed, which
                         is within some tolerance of ocean_topog_smoothing.

#### NAMELIST

     There is no namelist.

#### ERROR MESSAGES

    Fatal errors :

        Input argument unsmoothed_field has incorrect dimensions.

        Iterative scheme for computing lambda may not work unless initial values of lambda_1 and lambda_2 are reduced.

        Iterative scheme for finding lambda failed. lambda went negative on iteration number ...
           Should never see this message, if you do there probably is a bug in the code.

        Cannot converge on a value of lambda. Perhaps more interations are needed.

        subroutine regularize is not yet coded for 2-d decomposition. It was assumed that it will never be needed.

        Failure to converge
           The iterative scheme for smoothing topography (subroutine regularize) did not converge
           after the maximum number of iterations is reached.

        Transforms are not initialized
           The spectral transform package must be initialized before calling any interface of this module.

        Input argument ocean_mask has incorrect dimensions.

#### REFERENCES

    Lindberg and Broccoli, J. of Climate vol 9, no 11 pg. 2641-2659 (1996)

#### KNOWN BUGS

         There are no known bugs, but this is only the initial revision.

#### NOTES

#### FUTURE PLANS