[Mitgcm-support] Re: KPP (c30) bug

[mitgcm-support at dev.mitgcm.org]

Chris just wrote some words to help define how
we write/use packages.

Call us at 508 289 2806

A.


           MITgcmUV Packages
           =================

  Optional parts of code are separated from
the MITgcmUV core driver code and organised into 
packages. The packaging structure provides a mechanism for
maintaining suites of code, specific to particular
classes of problem, in a way that is cleanly
separated from the generic fluid dynamical engine.

 The MITgcmUV packaging structure is describe 
below using generic package names PKGX01, PKGX02 ... PKGXnn. 
A concrete examples of a package is the code
for implementing GM/Redi mixing. This code uses
the package name "GMREDI".

Package states
==============

 Packages can be any one of four states, included,
 excluded, enabled, disabled as follows:

 included(excluded) compile time state which
                    includes(excludes) package
                    code and routine calls from 
                    compilation/linking etc...
 
 enabled(disabled)  run-time state which
                    enables(disables) package code
                    execution.

 Package states are generally not expected to change during 
 a model run.

Package structure
=================

o  Each package gets its runtime configuration
   parameters from a file named "data.PKGX01"
   Package runtime config. options are imported
   into a common block held in a header file
   called "PKGX01.h".

o  The core driver part of the model can check 
   for runtime enabling or disabling of individual packages
   through logical flags use_PKGX01, use_PKGX02,
   etc... The information is loaded from a 
   global package setup file called "data.pkgs".
   The uss_PKGXnn flags are *not* used within 
   individual packages.

o  Included in "PKGX01.h" is a logical flag
   called PKGX01_packageIsOn. The "PKGX01.h" header file can be
   imported by other packages to check dependencies and requirements
   from other packages ( see "Package Boot Sequence" section).

CPP Flags
=========
    
    1. Within the core driver code flags of the form
       ALLOW_PKGX01 are used to include or exclude
       whole packages. The ALLOW_PKGXnn flags are included
       from a PACKAGE_OPTIONS block which is currently
       held in-line in the CPP_OPTIONS.h header file.
       e.g.

       Core model code .....

       #include "CPP_OPTIONS.h"
         :
         :
         :

       #ifdef ALLOW_PKGX01       #endif

    2. Within an individual package a header file,
       "PKGX01_OPTIONS.h", is used to set CPP flags
       specific to that package.


Package Boot Sequence
=====================

    Calls to package routines within the core code timestepping
    loop can vary. However, all packages follow a required
    "boot" sequence outlined here:

    1. S/R PACKAGES_READ_PARMS()
            :
        #ifdef ALLOW_PKGX01
          CALL PKGX01_READPARMS( retCode )
        #endif

    2. S/R PACKAGES_CHECK()
            :
        #ifdef ALLOW_PKGX01
          CALL PKGX01_CHECK( retCode )
        #else
          if ( usePKGX01 )
     &     CALL PACKAGES_CHECK_ERROR('PKGX01')
        #endif

    3. S/R PACKAGES_INIT()
            :
        #ifdef ALLOW_PKGX01
          CALL PKGX01_INIT( retCode )
        #endif
          
    Routine PKGX01_READPARMS() is responsible for reading
    in the package parameters file data.PKGX01, setting
    the PKGX01_packageIsOn flag appropriately and storing
    the package parameters in "PKGX01.h".

    Routine PKGX01_CHECK() is responsible for validating 
    basic package setup and inter-package dependencies.
    PKGX01_CHECK can import other package parameters it may 
    need to check. This is done through header files "PKGXnn.h".
    It is assumed that parameters owned by other packages
    will not be reset during PKGX01_CHECK().

    Routine PKGX01_INIT() is responsible for completing the
    internal setup of a package. This routine is called after
    the core model state has been completely initialised 
    but before the core model timestepping starts.

        CALL PKGX01_DO_SOMETHING(...)