Module tracer_manager

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

tracer_manager_init
```
call tracer_manager_init 
```
DESCRIPTION

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

DESCRIPTION

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]

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]

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(:)]

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]

tracer_manager_end
```
call tracer_manager_end 
```
DESCRIPTION

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

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]

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]

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]
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]

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

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]

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