PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

## Module tracer_manager_mod

Contact: William Cooke
Reviewers: Matt Harrison , Bruce Wyman , Peter Phillipps
Change History: WebCVS Log

#### OVERVIEW

Code to manage the simple addition of tracers to the FMS code. This code keeps track of the numbers and names of tracers included in a tracer table.

This code is a grouping of calls which will allow the simple introduction of tracers into the FMS framework. It is designed to allow users of a variety of component models interact easily with the dynamical core of the model.
In calling the tracer manager routines the user must provide a parameter identifying the model that the user is working with. This parameter is defined within field_manager as MODEL_X where X is one of [ATMOS, OCEAN, LAND, ICE].
In many of these calls the argument list includes model and tracer_index. These are the parameter corresponding to the component model and the tracer_index N is the Nth tracer within the component model. Therefore a call with MODEL_ATMOS and 5 is different from a call with MODEL_OCEAN and 5.

#### OTHER MODULES USED

              mpp_mod
           mpp_io_mod
              fms_mod
    field_manager_mod

#### PUBLIC INTERFACE

tracer_manager_init:
  It is not necessary to call this routine. It is included only for backward compatability.
get_tracer_meta_data:
  read tracer table and store tracer information associated with "model" in "tracers" array.
register_tracers:
  It is not necessary to call this routine. It is included only for backward compatability.
get_number_tracers:
  A routine to return the number of tracers included in a component model.
get_tracer_indices:
  Routine to return the component model tracer indices as defined within the tracer manager.
get_tracer_index:
  Function which returns the number assigned to the tracer name.
tracer_manager_end:
  Routine to write to the log file that the tracer manager is ending.
get_tracer_names:
  Routine to find the names associated with a tracer number.
get_tracer_name:
  Routine to find the names associated with a tracer number.
check_if_prognostic:
  Function to see if a tracer is prognostic or diagnostic.
set_tracer_profile:
  Subroutine to set the tracer field to the wanted profile.
query_method:
  A function to query the "methods" associated with each tracer.
set_tracer_atts:
  A subroutine to allow the user set the tracer longname and units from the tracer initialization routine.
set_tracer_method:
  A subroutine to allow the user to set some tracer specific methods.

#### PUBLIC DATA

None.

#### PUBLIC ROUTINES

1. #### tracer_manager_init

       call tracer_manager_init

   DESCRIPTION
     This routine writes the version and tagname to the logfile and sets the module initialization flag.

2. #### get_tracer_meta_data

   DESCRIPTION

3. #### register_tracers

       call register_tracers (model, num_tracers,num_prog,num_diag)

   DESCRIPTION
     This routine returns the total number of valid tracers, the number of prognostic and diagnostic tracers.
   INPUT

     `model` | A parameter to identify which model is being used. [integer]

   OUTPUT

     `num_tracers` | The total number of valid tracers within the component model. [integer]
     `num_prog` | The number of prognostic tracers within the component model. [integer]
     `num_diag` | The number of diagnostic tracers within the component model. [integer]

4. #### get_number_tracers

       call get_number_tracers (model, num_tracers,num_prog,num_diag)

   DESCRIPTION
     This routine returns the total number of valid tracers, the number of prognostic and diagnostic tracers
   INPUT

     `model` | A parameter to identify which model is being used. [integer]

   OUTPUT

     `num_tracers` | The total number of valid tracers within the component model. [integer, optional]
     `num_prog` | The number of prognostic tracers within the component model. [integer, optional]
     `num_diag` | The number of diagnostic tracers within the component model. [integer, optional]

5. #### get_tracer_indices

       call get_tracer_indices (model, ind, prog_ind, diag_ind)

   DESCRIPTION
     If several models are being used or redundant tracers have been written to the tracer_table, then the indices in the component model and the tracer manager may not have a one to one correspondence. Therefore the component model needs to know what index to pass to calls to tracer_manager routines in order that the correct tracer information be accessed.
   INPUT

     `model` | A parameter to identify which model is being used. [integer]

   OUTPUT

     `ind` | An array containing the tracer manager defined indices for all the tracers within the component model. [integer, optional, dimension(:)]
     `prog_ind` | An array containing the tracer manager defined indices for the prognostic tracers within the component model. [integer, optional, dimension(:)]
     `diag_ind` | An array containing the tracer manager defined indices for the diagnostic tracers within the component model. [integer, optional, dimension(:)]

6. #### get_tracer_index

       integer: index = get_tracer_index (model, name, indices, verbose) logical: if ( get_tracer_index(model, name, index, indices, verbose) ) then

   DESCRIPTION
     This is a function which returns the index, as implied within the component model. There are two overloaded interfaces: one of type integer, one logical.
   INPUT

     `model` | A parameter to identify which model is being used. [integer]
     `name` | The name of the tracer (as assigned in the field table). [character]
     `indices` | An array indices. When present, the returned index will limit the search for the tracer to those tracers whos indices are amoung those in array "indices". This would be useful when it is desired to limit the search to a subset of the tracers. Such a subset might be the diagnostic or prognostic tracers. (Note that subroutine get_tracer_indices returns these subsets) [integer, optional, dimension(:)]
     `verbose` | A flag to allow the message saying that a tracer with this name has not been found. This should only be used for debugging purposes. [logical, optional]

   OUTPUT

     `get_tracer_index` | integer function: The index of the tracer named "name". If no tracer by that name exists then the returned value is NO_TRACER. logical function: If no tracer by that name exists then the returned value is .false., otherwise the returned value is .true. [integer]

7. #### tracer_manager_end

       call tracer_manager_end

   DESCRIPTION
     Routine to write to the log file that the tracer manager is ending.

8. #### get_tracer_names

       call get_tracer_names (model,n,name,longname, units)

   DESCRIPTION
     This routine can return the name, long name and units associated with a tracer.
   INPUT

     `model` | A parameter representing the component model in use. [integer]
     `n` | Tracer number. [integer]

   OUTPUT

     `name` | Field name associated with tracer number. [character]
     `longname` | The long name associated with tracer number. [character, optional]
     `units` | The units associated with tracer number. [character, optional]

9. #### get_tracer_name

       if(.not. get_tracer_name (model,n,name,longname, units, err_msg)) call mpp_error(.....

   DESCRIPTION
     This routine can return the name, long name and units associated with a tracer. The return value of get_tracer_name is .false. when a FATAL error condition is detected, otherwise the return value is .true.
   INPUT

     `model` | A parameter representing the component model in use. [integer]
     `n` | Tracer number. [integer]

   OUTPUT

     `name` | Field name associated with tracer number. [character]
     `longname` | The long name associated with tracer number. [character, optional]
     `units` | The units associated with tracer number. [character, optional]
     `err_msg` | When present: If a FATAL error condition is detected then err_msg will contain an error message and the return value of get_tracer_name will be .false. If no FATAL error is detected err_msg will be filled with space characters and and the return value of get_tracer_name will be .true. When not present: A FATAL error will result in termination inside get_tracer_name without returning. If no FATAL error is detected the return value of get_tracer_name will be .true. [character, optional]

10. #### check_if_prognostic

        logical = check_if_prognostic (model, n)

    DESCRIPTION
      All tracers are assumed to be prognostic when read in from the field_table However a tracer can be changed to a diagnostic tracer by adding the line "tracer_type","diagnostic" to the tracer description in field_table.
    INPUT

      `model` | A parameter representing the component model in use. [integer]
      `n` | Tracer number [integer]

    OUTPUT

      `check_if_prognostic` | A logical flag set TRUE if the tracer is prognostic. [logical]

11. #### set_tracer_profile

        call set_tracer_profile (model, n, tracer)

    DESCRIPTION
      If the profile type is 'fixed' then the tracer field values are set equal to the surface value. If the profile type is 'profile' then the top/bottom of model and surface values are read and an exponential profile is calculated, with the profile being dependent on the number of levels in the component model. This should be called from the part of the dynamical core where tracer restarts are called in the event that a tracer restart file does not exist.
      This can be activated by adding a method to the field_table e.g. "profile_type","fixed","surface_value = 1e-12" would return values of surf_value = 1e-12 and a multiplier of 1.0 One can use these to initialize the entire field with a value of 1e-12.
      "profile_type","profile","surface_value = 1e-12, top_value = 1e-15" In a 15 layer model this would return values of surf_value = 1e-12 and multiplier = 0.6309573 i.e 1e-15 = 1e-12*(0.6309573^15) In this case the model should be MODEL_ATMOS as you have a "top" value.
      If you wish to initialize the ocean model, one can use bottom_value instead of top_value.
    INPUT

      `model` | A parameter representing the component model in use. [integer]
      `n` | Tracer number. [integer]

    INPUT/OUTPUT

      `tracer_array` | The initialized tracer array. [real]

12. #### query_method

        logical = query_method (method_type, model, n, name, control)

    DESCRIPTION
      A function to query the "methods" associated with each tracer. The "methods" are the parameters of the component model that can be adjusted by user by placing formatted strings, associated with a particular tracer, within the field table. These methods can control the advection, wet deposition, dry deposition or initial profile of the tracer in question. Any parametrization can use this function as long as a routine for parsing the name and control strings are provided by that routine.
    INPUT

      `method_type` | The method that is being requested. [character]
      `model` | A parameter representing the component model in use. [integer]
      `n` | Tracer number [integer]

    OUTPUT

      `name` | A string containing the modified name to be used with method_type. i.e. "2nd_order" might be the default for advection. One could use "4th_order" here to modify that behaviour. [character]
      `control` | A string containing the modified parameters that are associated with the method_type and name. [character, optional]
      `query_method` | A flag to show whether method_type exists with regard to tracer n. If method_type is not present then one must have default values. [logical]

    NOTE
      At present the tracer manager module allows the initialization of a tracer profile if a restart does not exist for that tracer. Options for this routine are as follows
      Tracer profile setup ================================================================== |method_type |method_name |method_control | ================================================================== |profile_type |fixed |surface_value = X | |profile_type |profile |surface_value = X, top_value = Y |(atmosphere) |profile_type |profile |surface_value = X, bottom_value = Y |(ocean) ==================================================================

13. #### set_tracer_atts

        call set_tracer_atts (model, name, longname, units)

    DESCRIPTION
      A function to allow the user set the tracer longname and units from the tracer initialization routine. It seems sensible that the user who is coding the tracer code will know what units they are working in and it is probably safer to set the value in the tracer code rather than in the field table.
    INPUT

      `model` | A parameter representing the component model in use. [integer]
      `name` | Tracer name. [character]

    OUTPUT

      `longname` | A string describing the longname of the tracer for output to NetCDF files [character, optional]
      `units` | A string describing the units of the tracer for output to NetCDF files [character, optional]

14. #### set_tracer_method

        call set_tracer_method (model, name, method_type, method_name, method_control)

    DESCRIPTION
      A subroutine to allow the user to set methods for a specific tracer.
    INPUT

      `model` | A parameter representing the component model in use. [integer]
      `name` | Tracer name. [character]
      `method_type` | The type of the method to be set. [character]
      `method_name` | The name of the method to be set. [character]
      `method_control` | The control parameters of the method to be set. [character]

#### DATA SETS

None.

#### ERROR MESSAGES

FATAL in get_tracer_meta_data
  invalid model type
  The index for the model type is invalid.
NOTE in get_tracer_meta_data
  No tracers are available to be registered.
  No tracers are available to be registered. This means that the field table does not exist or is empty.
FATAL in get_tracer_meta_data
  MAX_TRACER_FIELDS exceeded
  The maximum number of tracer fields has been exceeded.
FATAL in get_number_tracers
  Model number is invalid.
  The index of the component model is invalid.
FATAL in get_tracer_indices
  index array size too small in get_tracer_indices
  The global index array is too small and cannot contain all the tracer numbers.
FATAL in get_tracer_indices
  prognostic array size too small in get_tracer_indices
  The prognostic index array is too small and cannot contain all the tracer numbers.
FATAL in get_tracer_indices
  diagnostic array size too small in get_tracer_indices
  The diagnostic index array is too small and cannot contain all the tracer numbers.
NOTE in get_tracer_index
  tracer with this name not found: X

top