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. More...

Data Types
interface	get_tracer_index
	Function which returns the number assigned to the tracer name. More...

type	inst_type
	Private type to represent named instances. More...

type	tracer_name_type
	Private type to holds string data for a tracer. More...

type	tracer_type
	Private type to hold metadata for a tracer. More...

Functions/Subroutines
logical function, public	adjust_mass (model, n, err_msg)
	Function to check whether tracer should have its mass adjusted.

logical function, public	adjust_positive_def (model, n, err_msg)

logical function, public	check_if_prognostic (model, n, err_msg)
	Function to see if a tracer is prognostic or diagnostic. More...

logical function	error_handler (routine, err_msg_local, err_msg)

subroutine, public	get_number_tracers (model, num_tracers, num_prog, num_diag, num_family)
	A routine to return the number of tracers included in a component model. More...

integer function	get_tracer_index_integer (model, name, indices, verbose)
	Function which returns the number assigned to the tracer name. More...

logical function	get_tracer_index_logical (model, name, index, indices, verbose)
	Checks if tracer is present, and returns it's position in index. More...

subroutine, public	get_tracer_indices (model, ind, prog_ind, diag_ind, fam_ind)
	Routine to return the component model tracer indices as defined within the tracer manager. More...

subroutine	get_tracer_meta_data (model, num_tracers, num_prog, num_diag)
	Read in tracer table and store tracer information associated with "model" in "tracers" array. More...

logical function, public	get_tracer_name (model, n, name, longname, units, err_msg)
	Routine to find the names associated with a tracer number. More...

subroutine, public	get_tracer_names (model, n, name, longname, units, err_msg)
	Routine to find the names associated with a tracer number. More...

integer function	model_tracer_number (model, n)

subroutine	print_tracer_info (model, n)
	Routine to print out the components of the tracer. This is useful for informational purposes. Used in get_tracer_meta_data. More...

logical function, public	query_method (method_type, model, n, name, control, err_msg)
	A function to query the schemes associated with each tracer. More...

subroutine, public	register_tracers (model, num_tracers, num_prog, num_diag, num_family)
	Not necessary to call, only needed for backward compatability. More...

subroutine, public	set_tracer_atts (model, name, longname, units)
	A subroutine to allow the user set the tracer longname and units from the tracer initialization routine. More...

subroutine, public	set_tracer_method (model, name, method_type, method_name, method_control)
	A subroutine to allow the user to set some tracer specific methods. More...

subroutine, public	tracer_manager_end
	Uninitializes module and writes exit to logfile.

subroutine, public	tracer_manager_init
	Not necessary to call, only needed for backward compatability. More...

Variables
integer, dimension(num_models)	diag_tracers

type(inst_type), dimension(max_tracer_fields), save	instantiations

integer, parameter, public	max_tracer_fields = 250

integer, parameter	max_tracer_method = 20

logical, dimension(num_models)	model_registered = .FALSE.

logical	module_is_initialized = .false.

integer, parameter, public	no_tracer = 1-HUGE(1)

integer, parameter	notracer = -HUGE(1)

integer	num_tracer_fields = 0

integer, dimension(num_models)	prog_tracers

integer, dimension(num_models)	total_tracers

integer, dimension(num_models, max_tracer_fields)	tracer_array

type(tracer_type), dimension(max_tracer_fields), save	tracers

logical	verbose_local

Detailed Description

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.

Author: William Cooke

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.

Data Type Documentation

◆ tracer_manager_mod::get_tracer_index

interface tracer_manager_mod::get_tracer_index

Function which returns the number assigned to the tracer name.

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.

Parameters

	model	A integer parameter to identify which model is being used
	name	The name of the tracer (as assigned in the field table).
	indices	An array indices. When present, the returned index will limit the search for the tracer to thos tracers whose indices are among 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 get_tracer_indices returns these subsets)
	verbose	Optional flag for debugging
[out]	index	Holds the returned index if given

Returns: The integer function returns the index of the tracer named "name". If no tracer by that name exists then the returned value is NO_TRACER. The logical function returns false if no tracer by the given name exists and true otherwise, and stores the returned value in index.

Example usage:

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

Definition at line 126 of file tracer_manager.F90.

Private Member Functions
integer function	get_tracer_index_integer (model, name, indices, verbose)
	Function which returns the number assigned to the tracer name. More...

logical function	get_tracer_index_logical (model, name, index, indices, verbose)
	Checks if tracer is present, and returns it's position in index. More...

Member Function/Subroutine Documentation

◆ get_tracer_index_integer()

integer function get_tracer_index_integer	(	integer, intent(in)	model,
		character(len=*), intent(in)	name,
		integer, dimension(:), intent(in), optional	indices,
		logical, intent(in), optional	verbose
	)

private

Function which returns the number assigned to the tracer name.

See get_tracer_index Interface for more information.

Returns: index of given tracer name if present, otherwise returns NO_TRACER

Parameters

[in]	model	Parameter to identify which model is used
[in]	name	name of the tracer
[in]	indices	An array of indices, limits search to tracers whose indices are within the array.
[in]	verbose	debug flag

Definition at line 738 of file tracer_manager.F90.

◆ get_tracer_index_logical()

logical function get_tracer_index_logical	(	integer, intent(in)	model,
		character(len=*), intent(in)	name,
		integer, intent(out)	index,
		integer, dimension(:), intent(in), optional	indices,
		logical, intent(in), optional	verbose
	)

private

Checks if tracer is present, and returns it's position in index.

Parameters

[in]	model	Parameter for which model is used
[in]	name	name of given drifter
[out]	index	returned drifter index
[in]	indices	optional list of indices to limit results to
[in]	verbose	debug flag

Definition at line 787 of file tracer_manager.F90.

◆ tracer_manager_mod::inst_type

type tracer_manager_mod::inst_type

Private type to represent named instances.

Definition at line 158 of file tracer_manager.F90.

Collaboration diagram for inst_type:

[legend]

Private Attributes
integer	instances

character(len=128)	name

◆ tracer_manager_mod::tracer_name_type

type tracer_manager_mod::tracer_name_type

Private type to holds string data for a tracer.

Definition at line 151 of file tracer_manager.F90.

Collaboration diagram for tracer_name_type:

[legend]

Private Attributes
character(len=32)	model_name

character(len=128)	tracer_longname

character(len=32)	tracer_name

character(len=32)	tracer_units

◆ tracer_manager_mod::tracer_type

type tracer_manager_mod::tracer_type

Private type to hold metadata for a tracer.

Definition at line 137 of file tracer_manager.F90.

Collaboration diagram for tracer_type:

[legend]

Private Attributes
integer	instances

logical	instances_set

logical	is_prognostic

integer	model

logical	needs_init

logical	needs_mass_adjust

logical	needs_positive_adjust

integer	num_methods

character(len=128)	tracer_longname

character(len=32)	tracer_name

character(len=32)	tracer_units

Function/Subroutine Documentation

◆ check_if_prognostic()

logical function, public tracer_manager_mod::check_if_prognostic	(	integer, intent(in)	model,
		integer, intent(in)	n,
		character(len=*), intent(out), optional	err_msg
	)

Function to see if a tracer is prognostic or diagnostic.

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.

Returns: A logical flag set TRUE if the tracer is prognostic.

Parameters

[in]	model	Parameter representing component model in use
[in]	n	Tracer number

Definition at line 940 of file tracer_manager.F90.

◆ get_number_tracers()

subroutine, public tracer_manager_mod::get_number_tracers	(	integer, intent(in)	model,
		integer, intent(out), optional	num_tracers,
		integer, intent(out), optional	num_prog,
		integer, intent(out), optional	num_diag,
		integer, intent(out), optional	num_family
	)

A routine to return the number of tracers included in a component model.

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

Parameters

[in]	model	A parameter to identify which model is being used
[out]	num_tracers	The total number of valid tracers within the component model
[out]	num_prog	The number of prognostic tracers within the component model.
[out]	num_diag	The number of diagnostic tracers within the component model

Definition at line 597 of file tracer_manager.F90.

◆ get_tracer_index_integer()

integer function tracer_manager_mod::get_tracer_index_integer	(	integer, intent(in)	model,
		character(len=*), intent(in)	name,
		integer, dimension(:), intent(in), optional	indices,
		logical, intent(in), optional	verbose
	)

private

Function which returns the number assigned to the tracer name.

See get_tracer_index Interface for more information.

Returns: index of given tracer name if present, otherwise returns NO_TRACER

Parameters

[in]	model	Parameter to identify which model is used
[in]	name	name of the tracer
[in]	indices	An array of indices, limits search to tracers whose indices are within the array.
[in]	verbose	debug flag

Definition at line 738 of file tracer_manager.F90.

◆ get_tracer_index_logical()

logical function tracer_manager_mod::get_tracer_index_logical	(	integer, intent(in)	model,
		character(len=*), intent(in)	name,
		integer, intent(out)	index,
		integer, dimension(:), intent(in), optional	indices,
		logical, intent(in), optional	verbose
	)

private

Checks if tracer is present, and returns it's position in index.

Parameters

[in]	model	Parameter for which model is used
[in]	name	name of given drifter
[out]	index	returned drifter index
[in]	indices	optional list of indices to limit results to
[in]	verbose	debug flag

Definition at line 787 of file tracer_manager.F90.

◆ get_tracer_indices()

subroutine, public tracer_manager_mod::get_tracer_indices	(	integer, intent(in)	model,
		integer, dimension(:), intent(out), optional	ind,
		integer, dimension(:), intent(out), optional	prog_ind,
		integer, dimension(:), intent(out), optional	diag_ind,
		integer, dimension(:), intent(out), optional	fam_ind
	)

Routine to return the component model tracer indices as defined within the tracer manager.

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.

Parameters

model	A parameter to identify which model is being used.
ind	An array containing the tracer manager defined indices for all the tracers within the component model.
prog_ind	An array containing the tracer manager defined indices for the prognostic tracers within the component model.
diag_ind	An array containing the tracer manager defined indices for the diagnostic tracers within the component model.

Definition at line 640 of file tracer_manager.F90.

◆ get_tracer_meta_data()

subroutine tracer_manager_mod::get_tracer_meta_data	(	integer, intent(in)	model,
		integer, intent(out)	num_tracers,
		integer, intent(out)	num_prog,
		integer, intent(out)	num_diag
	)

private

Read in tracer table and store tracer information associated with "model" in "tracers" array.

Parameters

[in] model model being used

Definition at line 210 of file tracer_manager.F90.

◆ get_tracer_name()

logical function, public tracer_manager_mod::get_tracer_name	(	integer, intent(in)	model,
		integer, intent(in)	n,
		character (len=*), intent(out)	name,
		character (len=*), intent(out), optional	longname,
		character (len=*), intent(out), optional	units,
		character (len=*), intent(out), optional	err_msg
	)

Routine to find the names associated with a tracer number.

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.

Parameters

[in]	model	A parameter representing component model in use
[in]	n	Tracer number
[out]	name	Field name associate with tracer number
[out]	longname	Long name associated with tracer number
[out]	units	Tracer associated units
[out]	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.

Definition at line 889 of file tracer_manager.F90.

◆ get_tracer_names()

subroutine, public tracer_manager_mod::get_tracer_names	(	integer, intent(in)	model,
		integer, intent(in)	n,
		character (len=*), intent(out)	name,
		character (len=*), intent(out), optional	longname,
		character (len=*), intent(out), optional	units,
		character (len=*), intent(out), optional	err_msg
	)

Routine to find the names associated with a tracer number.

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

Parameters

[in]	model	A parameter representing component model in use
[in]	n	Tracer number
[out]	name	Field name associate with tracer number
[out]	longname	Long name associated with tracer number
[out]	units	Tracer associated units

Definition at line 855 of file tracer_manager.F90.

◆ print_tracer_info()

subroutine tracer_manager_mod::print_tracer_info	(	integer, intent(in)	model,
		integer, intent(in)	n
	)

private

Routine to print out the components of the tracer. This is useful for informational purposes. Used in get_tracer_meta_data.

Parameters

[in] n index of the tracer that is being printed

Definition at line 826 of file tracer_manager.F90.

◆ query_method()

logical function, public tracer_manager_mod::query_method	(	character(len=*), intent(in)	method_type,
		integer, intent(in)	model,
		integer, intent(in)	n,
		character(len=*), intent(out)	name,
		character(len=*), intent(out), optional	control,
		character(len=*), intent(out), optional	err_msg
	)

A function to query the schemes associated with each tracer.

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

Returns: 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. the name and control strings are provided by that routine.

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 |profile |surface_value = X, bottom_value = Y |(ocean)

Parameters

[in]	method_type	The requested method
[in]	model	Model the function is being called from
[in]	n	Tracer number
[out]	name	A string containing the modified name to be used with method_type. i.e. "2nd_order" might be the default advection. One could use "4th_order" to modify behaviour
[out]	control	A string containing the modified parameters that are associated with method_type and name.

Definition at line 1041 of file tracer_manager.F90.

◆ register_tracers()

subroutine, public tracer_manager_mod::register_tracers	(	integer, intent(in)	model,
		integer, intent(out)	num_tracers,
		integer, intent(out)	num_prog,
		integer, intent(out)	num_diag,
		integer, intent(out), optional	num_family
	)

Not necessary to call, only needed for backward compatability.

Returns the total number of valid, prognostic and diagnostic tracers.

Parameters

[in]	model	A parameter to identify which model is being used.
[out]	num_tracers	The total number of valid tracers within the component model.
[out]	num_prog	The number of prognostic tracers within the component model.
[out]	num_diag	The number of diagnostic tracers within the component model.

Definition at line 578 of file tracer_manager.F90.

◆ set_tracer_atts()

subroutine, public tracer_manager_mod::set_tracer_atts	(	integer, intent(in)	model,
		character(len=*), intent(in)	name,
		character(len=*), intent(in), optional	longname,
		character(len=*), intent(in), optional	units
	)

A subroutine to allow the user set the tracer longname and units from the tracer initialization routine.

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.

Parameters

[in]	model	A parameter representing component model in use
[in]	name	Tracer name
[in]	longname	Long name of the tracer
[in]	units	Units for the tracer

Definition at line 1114 of file tracer_manager.F90.

◆ set_tracer_method()

subroutine, public tracer_manager_mod::set_tracer_method	(	integer, intent(in)	model,
		character(len=*), intent(in)	name,
		character(len=*), intent(in)	method_type,
		character(len=*), intent(in)	method_name,
		character(len=*), intent(in)	method_control
	)

A subroutine to allow the user to set some tracer specific methods.

Parameters

[in]	model	A parameter representing component model in use
[in]	name	Tracer name
[in]	method_type	type of method to be set
[in]	method_name	name of method to be set
[in]	method_control	control parameters of the given method

Definition at line 1162 of file tracer_manager.F90.

◆ tracer_manager_init()

subroutine, public tracer_manager_mod::tracer_manager_init

Not necessary to call, only needed for backward compatability.

Writes version to logfile and sets init flag for this module

Definition at line 193 of file tracer_manager.F90.

Data Types

Functions/Subroutines

Variables

Detailed Description

Data Type Documentation

◆ tracer_manager_mod::get_tracer_index

Private Member Functions

Member Function/Subroutine Documentation

◆ get_tracer_index_integer()

◆ get_tracer_index_logical()

◆ tracer_manager_mod::inst_type

Private Attributes

◆ tracer_manager_mod::tracer_name_type

Private Attributes

◆ tracer_manager_mod::tracer_type

Private Attributes

Function/Subroutine Documentation

◆ check_if_prognostic()

◆ get_number_tracers()

◆ get_tracer_index_integer()

◆ get_tracer_index_logical()

◆ get_tracer_indices()

◆ get_tracer_meta_data()

◆ get_tracer_name()

◆ get_tracer_names()

◆ print_tracer_info()

◆ query_method()

Tracer profile setup

|method_type |method_name |method_control |

|profile_type |profile |surface_value = X, bottom_value = Y |(ocean)

◆ register_tracers()

◆ set_tracer_atts()

◆ set_tracer_method()

◆ tracer_manager_init()