Last modified: Fri Jan 30 12:02:35 2004.
NAME:
Initialize_IRSSE_Model
PURPOSE:
Function to initialise the sensor emissivity model by allocating and
filling the public emissivity coefficient structure.
CATEGORY:
Emissivity : Sensor_Emissivity_Model
CALLING SEQUENCE:
Error_Status = Initialize_IRSSE_Model( EmisCoeff_File = EmisCoeff_File, & ! Optional input
Path = Path, & ! Optional input
Quiet = Quiet, & ! Optional input
Process_ID = Process_ID, & ! Optional input
Output_Process_ID = Output_Process_ID, & ! Optional input
Message_Log = Message_Log ) ! Error messaging
INPUT ARGUMENTS:
None.
OPTIONAL INPUT ARGUMENTS:
EmisCoeff_File: Character string specifying a file name for the
emissivity coefficient data file. If not
specified, "emissivity_coefficients" is the
default.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Path: Character string specifying a file Path for the
input coefficient file. If not specified, the
current directory is the default.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Quiet: Set this argument to suppress INFORMATION messages
being printed to standard output (or the message
log file if the Message_Log optional argument is
used.) By default, INFORMATION messages are printed.
If QUIET = 0, INFORMATION messages are OUTPUT.
QUIET = 1, INFORMATION messages are SUPPRESSED.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Process_ID: Set this argument to the MPI process ID that this
function call is running under. This value is used
solely for controlling INFORMATIOn message output.
If MPI is not being used, ignore this argument.
This argument is ignored if the Quiet argument is set.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Output_Process_ID: Set this argument to the MPI process ID in which
all INFORMATION messages are to be output. If
the passed Process_ID value agrees with this value
the INFORMATION messages are output.
This argument is ignored if the Quiet argument
is set.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Message_Log: Character string specifying a filename in which any
messages will be logged. If not specified, or if an
error occurs opening the log file, the default action
is to output messages to the screen.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
OUTPUT ARGUMENTS:
None.
OPTIONAL OUTPUT ARGUMENTS:
None.
FUNCTION RESULT:
Error_Status: The return value is an integer defining the error status.
The error codes are defined in the ERROR_HANDLER module.
If == SUCCESS the emissivity model initialisation
was successful.
== FAILURE an error occurred.
UNITS: N/A
TYPE: INTEGER
DIMENSION: Scalar
CALLS:
Display_Message: Subroutine to output messages
SOURCE: ERROR_HANDLER module
Load_Emis_Coefficients: Function to load the emissivity
coefficient data into the public
data structure EC.
SOURCE: IRSSE_COEFFICIENTS module
EXTERNALS:
None
COMMON BLOCKS:
None.
SIDE EFFECTS:
All public data arrays accessed by this module and its dependencies
are overwritten.
RESTRICTIONS:
If specified, the length of the combined path and filename strings
cannot exceed 512 characters.
CREATION HISTORY:
Written by: Paul van Delst, CIMSS/SSEC 01-May-2003
paul.vandelst@ssec.wisc.edu
(See IRSSE_Model.f90)
NAME:
Destroy_IRSSE_Model
PURPOSE:
Function to deallocate the emissivity coefficient shared data structure
created during the model initialisation.
CATEGORY:
Emissivity : Sensor_Emissivity_Model
CALLING SEQUENCE:
Error_Status = Destroy_IRSSE_Model( Process_ID = Process_ID, & ! Optional input
Message_Log = Message_Log ) ! Error messaging
INPUT ARGUMENTS:
None.
OPTIONAL INPUT ARGUMENTS:
Process_ID: Set this argument to the MPI process ID that this
function call is running under. This value is used
solely for controlling message output. If MPI is not
being used, ignore this argument.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Message_Log: Character string specifying a filename in which any
messages will be logged. If not specified, or if an
error occurs opening the log file, the default action
is to output messages to the screen.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
OUTPUT ARGUMENTS:
None.
OPTIONAL OUTPUT ARGUMENTS:
None.
FUNCTION RESULT:
Error_Status: The return value is an integer defining the error status.
The error codes are defined in the ERROR_HANDLER module.
If == SUCCESS the emissivity model destruction was
successful.
== FAILURE an error occurred.
UNITS: N/A
TYPE: INTEGER
DIMENSION: Scalar
CALLS:
Display_Message: Subroutine to output messages
SOURCE: ERROR_HANDLER module
Destroy_IRSSE_Coefficients: Function to deallocate the emissivity
coefficient shared data structure.
SOURCE: IRSSE_COEFFICIENTS module
EXTERNALS:
None
COMMON BLOCKS:
None.
SIDE EFFECTS:
All shared data structures are deallocated.
RESTRICTIONS:
None.
CREATION HISTORY:
Written by: Paul van Delst, CIMSS/SSEC 01-May-2003
paul.vandelst@ssec.wisc.edu
(See IRSSE_Model.f90)
NAME:
Forward_IRSSE
PURPOSE:
Function to compute the infrared (IR) channel sea surface emissivity
(SSE) forward model for the requested channels.
CATEGORY:
Emissivity : Sensor_Emissivity_Model
CALLING SEQUENCE:
Error_Status = Forward_IRSSE( View_Angle, & ! Input, scalar
Wind_Speed, & ! Input, scalar
Channel_Index, & ! Input, L
Emissivity, & ! Output, L
Quiet = Quiet, & ! Optional input
Message_Log = Message_Log ) ! Error messaging
INPUT ARGUMENTS:
View_Angle: Zenith angle from surface to sensor.
Valid range is 0 - 65 degrees.
The ABS() value of the view angle is used so
negative values are accepted.
If ABS(View_Angle) > 65, then 65.0 degrees is
used in the emissivity calculation.
UNITS: Degrees.
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Wind_Speed: Wind speed at sea surface.
Valid range is 0 - 15 m/s.
The ABS() value of the wind speed is used so
negative values are accepted.
If ABS(Wind_Speed) > 15, then 15.0 m/s is used
in the emissivity calculation.
UNITS: metres/second (m/s)
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Channel_Index: Channel index id array. Each element is a unique
index to a supported sensor channel.
UNITS: None
TYPE: INTEGER
DIMENSION: Rank-1; Lx1 where L > 1
ATTRIBUTES: INTENT( IN )
OPTIONAL INPUT ARGUMENTS:
Quiet: Set this argument to suppress input argument WARNING
messages being printed to standard output (or the
message log file if the Message_Log optional argument
is used.) By default, all messages are printed.
If QUIET = 0, input argument WARNING messages are OUTPUT.
QUIET = 1, input argument WARNING messages are SUPPRESSED.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Message_Log: Character string specifying a filename in which any
messages will be logged. If not specified, or if an
error occurs opening the log file, the default action
is to output messages to the screen.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
OUTPUT ARGUMENTS:
Emissivity: Sea surface emissivities for the requested channels
at the passed view angle and wind speed.
UNITS: None
TYPE: REAL( fp_kind )
DIMENSION: Rank-1; Lx1 where L > 1
Same as Channel_Index array.
ATTRIBUTES: INTENT( OUT )
OPTIONAL OUTPUT ARGUMENTS:
None.
FUNCTION RESULT:
Error_Status: The return value is an integer defining the error status.
The error codes are defined in the ERROR_HANDLER module.
If == SUCCESS the emissivity computation was successful.
== WARNING the input view angle or wind speed are
outside their valid ranges. In these cases
the computation continues but using the
the relevant view angle and/or wind speed
boundary value(s).
== FAILURE the argument channel dimensions were
inconsistent.
UNITS: N/A
TYPE: INTEGER
DIMENSION: Scalar
CALLS:
Display_Message: Subroutine to output messages
SOURCE: ERROR_HANDLER module
Check_Input: Function to check common IRSSE model component
input values.
Compute_Theta: Function to compute the normalised view angle.
Theta_Function: Function to compute the view angle dependent
emissivity.
EXTERNALS:
None
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Input restrictions on view angle and wind speed are determined by the
ranges used in generating the coefficients and thus are specified in
the coefficient file data. Typically, though, the view angle, Theta,
must be -65deg < Theta <= 65deg (assumed symmetric about nadir) and
the wind speed, V, must be 0 <= V <= 15m/s.
CREATION HISTORY:
Written by: Paul van Delst, CIMSS/SSEC 01-May-2003
paul.vandelst@ssec.wisc.edu
(See IRSSE_Model.f90)
NAME:
Tangent_Linear_IRSSE
PURPOSE:
Function to compute the infrared (IR) channel sea surface emissivity
(SSE) tangent-linear model for the requested channels.
CATEGORY:
Emissivity : Sensor_Emissivity_Model
CALLING SEQUENCE:
Error_Status = Tangent_Linear_IRSSE( View_Angle, & ! Input, scalar
Wind_Speed, & ! Input, scalar
Wind_Speed_TL, & ! Input, scalar
Channel_Index, & ! Input, L
Emissivity_TL, & ! Output, L
Quiet = Quiet, & ! Optional input
Message_Log = Message_Log ) ! Error messaging
INPUT ARGUMENTS:
View_Angle: Zenith angle from surface to sensor.
Valid range is 0 - 65 degrees.
The ABS() value of the view angle is used so
negative values are accepted.
If ABS(View_Angle) > 65, then 65.0 degrees is
used in the emissivity calculation.
UNITS: Degrees.
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Wind_Speed: Wind speed at sea surface.
Valid range is 0 - 15 m/s.
The ABS() value of the wind speed is used so
negative values are accepted.
If ABS(Wind_Speed) > 15, then 15.0 m/s is used
in the emissivity calculation.
UNITS: metres/second (m/s)
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Wind_Speed_TL: Wind speed perturbation at sea surface.
UNITS: metres/second (m/s)
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Channel_Index: Channel index id array. Each element is a unique
index to a supported sensor channel.
UNITS: None
TYPE: INTEGER
DIMENSION: Rank-1; Lx1 where L > 1
ATTRIBUTES: INTENT( IN )
OPTIONAL INPUT ARGUMENTS:
Quiet: Set this argument to suppress input argument WARNING
messages being printed to standard output (or the
message log file if the Message_Log optional argument
is used.) By default, all messages are printed.
If QUIET = 0, input argument WARNING messages are OUTPUT.
QUIET = 1, input argument WARNING messages are SUPPRESSED.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Message_Log: Character string specifying a filename in which any
messages will be logged. If not specified, or if an
error occurs opening the log file, the default action
is to output messages to the screen.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
OUTPUT ARGUMENTS:
Emissivity_TL: Sea surface emissivity perturbations for the
requested channels for the supplied wind speed
perturbation from the wind speed input at the
passed view angle.
UNITS: None
TYPE: REAL( fp_kind )
DIMENSION: Rank-1; Lx1 where L > 1
Same as Channel_Index array.
ATTRIBUTES: INTENT( OUT )
OPTIONAL OUTPUT ARGUMENTS:
None.
FUNCTION RESULT:
Error_Status: The return value is an integer defining the error status.
The error codes are defined in the ERROR_HANDLER module.
If == SUCCESS the emissivity computation was successful.
== WARNING the input view angle or wind speed are
outside their valid ranges. In these cases
the computation continues but using the
the relevant view angle and/or wind speed
boundary value(s).
== FAILURE the argument channel dimensions were
inconsistent.
UNITS: N/A
TYPE: INTEGER
DIMENSION: Scalar
CALLS:
Display_Message: Subroutine to output messages
SOURCE: ERROR_HANDLER module
Check_Input: Function to check common IRSSE model component
input values.
Compute_Theta: Function to compute the normalised view angle.
Theta_Function_TL: Function to compute the tangent-linear form
of the view angle dependent emissivity.
EXTERNALS:
None
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Input restrictions on view angle and wind speed are determined by the
ranges used in generating the coefficients and thus are specified in
the coefficient file data. Typically, though, the view angle, Theta,
must be -65deg < Theta <= 65deg (assumed symmetric about nadir) and
the wind speed, V, must be 0 <= V <= 15m/s.
CREATION HISTORY:
Written by: Paul van Delst, CIMSS/SSEC 10-Jun-2003
paul.vandelst@ssec.wisc.edu
(See IRSSE_Model.f90)
NAME:
Adjoint_IRSSE
PURPOSE:
Function to compute the infrared (IR) channel sea surface emissivity
(SSE) adjoint model for the requested channels.
CATEGORY:
Emissivity : Sensor_Emissivity_Model
CALLING SEQUENCE:
Error_Status = Adjoint_IRSSE( View_Angle, & ! Input, scalar
Wind_Speed, & ! Input, scalar
Emissivity_AD, & ! In/Output, L
Channel_Index, & ! Input, L
Wind_Speed_AD, & ! Output, Scalar
Quiet = Quiet, & ! Optional input
Message_Log = Message_Log ) ! Error messaging
INPUT ARGUMENTS:
View_Angle: Zenith angle from surface to sensor.
Valid range is 0 - 65 degrees.
The ABS() value of the view angle is used so
negative values are accepted.
If ABS(View_Angle) > 65, then 65.0 degrees is
used in the emissivity calculation.
UNITS: Degrees.
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Wind_Speed: Wind speed at sea surface.
Valid range is 0 - 15 m/s.
The ABS() value of the wind speed is used so
negative values are accepted.
If ABS(Wind_Speed) > 15, then 15.0 m/s is used
in the emissivity calculation.
UNITS: metres/second (m/s)
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Emissivity_AD: Sea surface emissivity adjoints for the requested
channels at the supplied wind speed and view angle.
Typically initialised to ONE on INPUT. Set to ZERO
upon OUTPUT.
UNITS: None
TYPE: REAL( fp_kind )
DIMENSION: Rank-1; Lx1 where L > 1
Same as Channel_Index array.
ATTRIBUTES: INTENT( IN OUT )
Channel_Index: Channel index id array. Each element is a unique
index to a supported sensor channel.
UNITS: None
TYPE: INTEGER
DIMENSION: Rank-1; Lx1 where L > 1
ATTRIBUTES: INTENT( IN )
OPTIONAL INPUT ARGUMENTS:
Quiet: Set this argument to suppress input argument WARNING
messages being printed to standard output (or the
message log file if the Message_Log optional argument
is used.) By default, all messages are printed.
If QUIET = 0, input argument WARNING messages are OUTPUT.
QUIET = 1, input argument WARNING messages are SUPPRESSED.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Message_Log: Character string specifying a filename in which any
messages will be logged. If not specified, or if an
error occurs opening the log file, the default action
is to output messages to the screen.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
OUTPUT ARGUMENTS:
Wind_Speed_AD: Wind speed adjoint at sea surface. Effectively
the dE/dV for the given view angle where,
E == emissivity
V == wind speed
but for ALL input channels.
Typically initialised to ZERO for INPUT
UNITS: (metres/second)^-1 (m/s)^-1
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN OUT )
OPTIONAL OUTPUT ARGUMENTS:
None.
FUNCTION RESULT:
Error_Status: The return value is an integer defining the error status.
The error codes are defined in the ERROR_HANDLER module.
If == SUCCESS the emissivity computation was successful.
== WARNING the input view angle or wind speed are
outside their valid ranges. In these cases
the computation continues but using the
the relevant view angle and/or wind speed
boundary value(s).
== FAILURE the argument channel dimensions were
inconsistent.
UNITS: N/A
TYPE: INTEGER
DIMENSION: Scalar
CALLS:
Display_Message: Subroutine to output messages
SOURCE: ERROR_HANDLER module
Check_Input: Function to check common IRSSE model component
input values.
Compute_Theta: Function to compute the normalised view angle.
Theta_Function_AD: Function to compute the adjoint form
of the view angle dependent emissivity.
EXTERNALS:
None
COMMON BLOCKS:
None.
SIDE EFFECTS:
Emissivity_AD argument is set to ZERO upon output.
RESTRICTIONS:
Input restrictions on view angle and wind speed are determined by the
ranges used in generating the coefficients and thus are specified in
the coefficient file data. Typically, though, the view angle, Theta,
must be -65deg < Theta <= 65deg (assumed symmetric about nadir) and
the wind speed, V, must be 0 <= V <= 15m/s.
CREATION HISTORY:
Written by: Paul van Delst, CIMSS/SSEC 10-Jun-2003
paul.vandelst@ssec.wisc.edu
(See IRSSE_Model.f90)
NAME:
K_Matrix_IRSSE
PURPOSE:
Function to compute the infrared (IR) channel sea surface emissivity
(SSE) K-matrix model for the requested channels.
CATEGORY:
Emissivity : Sensor_Emissivity_Model
CALLING SEQUENCE:
Error_Status = K_Matrix_IRSSE( View_Angle, & ! Input, scalar
Wind_Speed, & ! Input, scalar
Emissivity_K, & ! In/Output, L
Channel_Index, & ! Input, L
Wind_Speed_K, & ! Output, L
Quiet = Quiet, & ! Optional input
Message_Log = Message_Log ) ! Error messaging
INPUT ARGUMENTS:
View_Angle: Zenith angle from surface to sensor.
Valid range is 0 - 65 degrees.
The ABS() value of the view angle is used so
negative values are accepted.
If ABS(View_Angle) > 65, then 65.0 degrees is
used in the emissivity calculation.
UNITS: Degrees.
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Wind_Speed: Wind speed at sea surface.
Valid range is 0 - 15 m/s.
The ABS() value of the wind speed is used so
negative values are accepted.
If ABS(Wind_Speed) > 15, then 15.0 m/s is used
in the emissivity calculation.
UNITS: metres/second (m/s)
TYPE: REAL( fp_kind )
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN )
Emissivity_K: Sea surface emissivity adjoints for the requested
channels at the supplied wind speed and view angle.
Typically initialised to ONE on INPUT. Set to ZERO
upon OUTPUT.
UNITS: None
TYPE: REAL( fp_kind )
DIMENSION: Rank-1; Lx1 where L > 1
Same as Channel_Index array.
ATTRIBUTES: INTENT( IN OUT )
Channel_Index: Channel index id array. Each element is a unique
index to a supported sensor channel.
UNITS: None
TYPE: INTEGER
DIMENSION: Rank-1; Lx1 where L > 1
ATTRIBUTES: INTENT( IN )
OPTIONAL INPUT ARGUMENTS:
Quiet: Set this argument to suppress input argument WARNING
messages being printed to standard output (or the
message log file if the Message_Log optional argument
is used.) By default, all messages are printed.
If QUIET = 0, input argument WARNING messages are OUTPUT.
QUIET = 1, input argument WARNING messages are SUPPRESSED.
UNITS: None
TYPE: INTEGER
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
Message_Log: Character string specifying a filename in which any
messages will be logged. If not specified, or if an
error occurs opening the log file, the default action
is to output messages to the screen.
UNITS: None
TYPE: CHARACTER(*)
DIMENSION: Scalar
ATTRIBUTES: INTENT( IN ), OPTIONAL
OUTPUT ARGUMENTS:
Wind_Speed_K: Wind speed adjoint at sea surface. Effectively
the dE/dV for the given view angle where,
E == emissivity
V == wind speed
but for EACH input channel.
Typically initialised to ZERO for INPUT
UNITS: (metres/second)^-1 (m/s)^-1
TYPE: REAL( fp_kind )
DIMENSION: Rank-1; Lx1 where L > 1
Same as Channel_Index array.
ATTRIBUTES: INTENT( IN OUT )
OPTIONAL OUTPUT ARGUMENTS:
None.
FUNCTION RESULT:
Error_Status: The return value is an integer defining the error status.
The error codes are defined in the ERROR_HANDLER module.
If == SUCCESS the emissivity computation was successful.
== WARNING the input view angle or wind speed are
outside their valid ranges. In these cases
the computation continues but using the
the relevant view angle and/or wind speed
boundary value(s).
== FAILURE the argument channel dimensions were
inconsistent.
UNITS: N/A
TYPE: INTEGER
DIMENSION: Scalar
CALLS:
Display_Message: Subroutine to output messages
SOURCE: ERROR_HANDLER module
Check_Input: Function to check common IRSSE model component
input values.
Compute_Theta: Function to compute the normalised view angle.
Theta_Function_AD: Function to compute the adjoint form
of the view angle dependent emissivity.
EXTERNALS:
None
COMMON BLOCKS:
None.
SIDE EFFECTS:
Emissivity_K argument is set to ZERO upon output.
RESTRICTIONS:
Input restrictions on view angle and wind speed are determined by the
ranges used in generating the coefficients and thus are specified in
the coefficient file data. Typically, though, the view angle, Theta,
must be -65deg < Theta <= 65deg (assumed symmetric about nadir) and
the wind speed, V, must be 0 <= V <= 15m/s.
CREATION HISTORY:
Written by: Paul van Delst, CIMSS/SSEC 10-Jun-2003
paul.vandelst@ssec.wisc.edu
(See IRSSE_Model.f90)