Differences between revisions 1 and 2
⇤ ← Revision 1 as of 2008-11-06 12:05:16 →
Size: 80
Editor: NicoleThomas
Comment:
← Revision 2 as of 2008-11-27 16:20:25 → ⇥
Size: 24160
Editor: GebhardGuenther
Comment: Text aus http://icg012/icgIwiki/IsentropicPreprocessor kopiert
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
 1. ''What is the isentropic package?''

 The isentropic package was developed at the Institute for Stratospheric Chemistry of the Research Center Jülich. It succeeds the formerly used isentropic program of the PP package originally developed at the UK Meteorological Office. Its purpose is to convert four-dimensional data sets containing atmospheric parameters from pressure coordinates to theta coordinates, theta being the potential temperature.

 Currently, it is possible to convert five types of data sets: assimilated data by the UK Meteorological Offices Unified Model (UKMO data), and ECMWF data sets originating from the German Center for Climatological Research, hereafter called DKRZ, from the NILU data center(NILU), from KNMI (KNMI) and Meteo France (METEO_FRANCE). In order to be processed by the programs of the isentropic package all of the above mentioned data sets have to be converted to netCDF data format first!

 1. ''How to get the source code''

 The source code of the isentropic package is under the control of the CVS ('''C'''oncurrent '''V'''ersion '''S'''ystem) utility. To get the source code first make sure that the environment variable CVSROOT is set to {{{/usr/local/icg/icg1/archive}}}, then just type

 {{{
 cvs co isentropic}}}

 This command creates a subdirectory {{{./isentropic}}} in your current working directory and afterwards checks out the source code to subdirectories of this directory. Change your working directory to the new {{{./isentropic}}} subdirectory. A directory listing will look like this:

 {{{
 insgesamt 2216
 drwxr-xr-x 9 icg134 icg1 1024 Jul 7 09:30 ./
 drwxr-xr-x 18 icg134 icg1 512 Jul 4 10:44 ../
 -r--r--r-- 1 icg134 icg1 51 Apr 22 08:26 .cvsignore
 drwxr-xr-x 3 icg134 icg1 512 Jul 5 14:17 CVS/
 -r--r----- 1 icg134 icg1 7317 Jul 5 14:17 Makefile
 -r--r----- 1 icg134 icg1 651 Jul 4 11:25 RELEASE.tags
 drwxr-xr-x 3 icg134 icg1 512 Jul 21 10:19 doc/
 -r--r--r-- 1 icg134 icg1 6323 Apr 19 15:40 gauss_grid.dat
 drwxr-xr-x 3 icg134 icg1 512 Jul 5 16:24 mod/
 drwxr-xr-x 3 icg134 icg1 512 Jul 5 16:24 obj/
 drwxr-xr-x 3 icg134 icg1 512 Jul 7 09:25 scripts/
 drwxr-xr-x 3 icg134 icg1 512 Jul 20 12:29 source/
 drwxr-xr-x 3 icg134 icg1 512 Jul 3 14:51 templates/
 }}}

 The isentropic package consists of several files, the most important being described below. Please note that the {{{*.f90}}} files in {{{./isentropic/source}}} (and other files) are checked out write-protected. This is done by default to avoid unintentionally changing of the source code. If you want to change the source code, run the

 {{{
 cvs edit ''filename'' }}}

 command instead of just changing the file permissions with {{{chmod}}}. When you are finished with editing, please use the command
        
 {{{
 cvs unedit ''filename''}}}

 to make the file read-only again. This will abandon your changes and revert to the old version of the file in the repository again. Therefore make sure to commit your changes, if you want to have them applied to the repository. Using the {{{cvs}}} commands {{{edit}}} and {{{unedit}}} notifies a possibly running cvs watching process.

 After having checked out the source code, just type the command

 {{{
 make ''target''}}}

 to have the specified part of the package be compiled. Using the target {{{all}}} will result in a compilation of the whole package, the targets {{{add_pv_isobar}}}, {{{add_theta}}}, {{{isentropic}}}, {{{read_ecmwf}}} and {{{add_eqlat}}} will cause the {{{ make}}} command to create the belonging parts of the package. The targets {{{clean}}} and {{{tidy}}} will lead to a removal of all object and executable files or {{{core}}} files, respectively. Target {{{new}}} is a combination of {{{clean}}} and {{{all}}} and will lead to a complete recompilation of the package. Another helpful feature will be introduced by the completing the target TAGS, which creates a tag table for emacs. For a detailed description of the targets please refer to the target section of the {{{Makefile}}}. Please note, that {{{Makefile}}} relies on the {{{mkincl}}} package. If you have not done already check this package out as well.

 1. ''The utilities''

 There are a lot of utility programs, which help to convert or add data to given data sets, thus preparing data files for the subsequent use of {{{isentropic}}} itself or other procedures like plotting routines. Almost all of these utilities and the program {{{isentropic}}} use the modules {{{types}}}, {{{nc_routines}}} and {{{isen_module}}}. These files contain the declaration of all used global variables and structures together with a lot of different subroutines, which read or write netCDF formatted data, help recognizing and creating common used structures, compute diagnostic physical variables and much more. These module files are described in more detail in section 1.5. Another often used module is {{{dateconv.f90}}}, which contains a lot of date and time converting routines. Although {{{dateconv.f90}}} is shipped along with the isentropic package, it is not a part of this package and is just supplied for reasons of consistency. The {{{dateconv}}} module is described elsewhere.

 There are several other routines (basically shell scripts) which help to run the package on the Cray. These are {{{job_add}}}, {{{job_isen}}} and {{{job_read}}}.

  i. ''add_theta''

  The program {{{add_theta}}} is designed to add the diagnostic variable THETA (potential temperature) to data sets of the above described kind. This addition can only be performed if the data set already contains the variable TEMP (temperature). If the data set already contains THETA, the program will stop. If the data set contains a variable named TEMP_DOT (the time derivative of temperature), then the time derivative of theta THETA_DOT will also be computed and added to the data set.

  The program {{{add_theta}}} reads the following values from the input file {{{add_theta.inp}}}: the user name, which should conform to the mail-address name conventions of the Research Center, the class of the files to be modified, e. g. ''UKMO'', ''DKRZ'' or ''NILU'', and the names of the files. The program will check the data sets global parameters ''data_description'' and ''data_origin'' for their contents. The class name will be overwritten by the values found in the data set. If there are no values found in the data set, the given class name will be used. '''Giving a wrong class name in the latter case will lead to wrong results!''' Multiple file names can be added to the input file, each one on a single line. Make sure that the last line is completed by a carriage return/line feed!


  i. ''add_eqlat''

  The program {{{add_eqlat}}} calculates equivalent latitudes for UKMO data sets in isobaric or isentropic coordinates and adds it to the data set. Equivalent and normalized latitudes are computed according to the method of L. Lait. {{{add_eqlat}}} reads from {{{add_eqlat.inp}}} the filename of the input data set and the name of the directory, where it resides.

  i. ''add_pv_isobar''
 
  The program {{{add_pv_isobar}}} computes the variable PV_ISOBAR (potential vorticity on isobaric surfaces) for UKMO and ECMWF data sets and adds the variable to the data set. This variable is computed in a different way from the variable PV in {{{isentropic}}}. Nevertheless, if {{{add_pv_isobar}}} is applied to a data set before {{{isentropic}}}, the resulting variables PV_ISOBAR and PV should at least show similar if not identical results. {{{add_pv_isobar}}} reads from {{{add_pv_isobar.inp}}} the user name, the class of the files to be read in and the filename of the input data set. The details for specification of input parameters described for {{{add_theta}}}, e. g. the class names, hold true for {{{add_pv_isobar}}}!


  i. ''read_ecmwf''

  The program {{{read_ecmwf}}} is used for conversion of ECMWF data originating from the DKRZ, which contain data for a whole month. It reads in the output from the {{{afterburner}}} program supplied by the DKRZ, which converts the original data file written in GRIB format to binary format. This format is read in by {{{read_ecmwf}}} and converted to netCDF format. For more information about the {{{afterburner}}} program please refer to its manual.

  {{{read_ecmwf}}} reads in from {{{read_ecmwf.inp}}} the user name, the name of the input data set and the numerical values for the days of the month to be extracted. The output filenames are generated automatically from the date and the hour of the requested days, e. g. ''ecmwf_97021412.nc'' contains data for the 14^^th^^ of February 1997 noon.

  Since the output data files of {{{afterburner}}} can be very big with file sizes larger than 2 GB, it is recommended to use {\tt afterburner} and {{{read_ecmwf}}} on the Cray. This is due to the fact that files with file sizes larger than 2 GB are currently not supported on the AIX cluster.


 1. ''The main program: isentropic''

 The program {{{isentropic}}} reads in four-dimensional data sets in netCDF format and converts the data to be on requested isentropic surfaces rather than on isobaric surfaces. This can only be done, if the input data set contains THETA. Therefore the program first checks for the existence of THETA. If this parameter is not contained in the data set, the program will stop with a corresponding message. You should then apply {{{add_theta}}} to the data set to complete it with the desired variable.

 If THETA is contained and the requested theta levels are not completely outside the range of the data set (which will cause the program to stop with a corresponding error message), {{{isentropic}}} will start to convert all variables of the data set into values on isentropic levels. This is done by interpolating all variables onto a maximum of 30 theta levels. If more theta levels are needed, just change the parameter ''max_tlevel'' in the file {{{isen_module.f90}}} and recompile.

 Additionally the program adds the diagnostic variables PV (potential vorticity) and M (Montgomery stream function) to the output file. The addition of PV can only be performed, if the variables U and V (horizontal wind fields) or RELVOR (relative vorticity) are contained in the input data set. The same holds true for the addition of M, which is only possible when the values for GPH and TEMP are known. If the mentioned requirements are not met, the program will notify you with corresponding messages.

 The program {{{isentropic}}} reads the following values from the input file {{{isentropic.inp}}}: the user name, the class of the files to be read in, number and value of the desired isentropic surfaces and the names of the input and output data sets. The names of the input and the corresponding output data sets must occur on the same line.

 The details for specification of input parameters described for {{{add_theta}}}, e. g. the class names, hold true for {{{isentropic}}}!

 1. ''The module: types.f90,nc_routines.f90 and isen_module.f90''

 The f90-module {{{types.f90}}} contains the declaration of all global variables and structures that are shared by most of the above mentioned utilities and programs. The most important are described in the following subsections without going to much into detail.

  i. ''Variables''

  The most important variables used in the isentropic package are listed in the table below.

  || '''Variable''' || '''Type''' || '''Description''' ||
  || max_tlevel || integer || maximum number of theta levels ||
  || max_coord || integer || maximum number of coordinate variables ||
  || anzahl_theta || integer || number of requested theta levels ||
  || status || integer || contains the status value of netCDF functions ||
  || ncid || integer || id of currently used input netCDF file ||
  || nc_out || integer || id of currently used output netCDF file ||
  || anz_dim || integer || number of dimensions in netCDF file ||
  || anz_var || integer || number of variables in netCDF file ||
  || anz_att || integer || number of attributes in netCDF file ||
  || dim_id || integer || id of currently used dimension ||
  || unlimdimid|| integer || id of unlimited dimension in netCDF file||
  || att_id || integer || id of currently used attribute ||
  || laenge || integer || length of currently used attribute (character string) ||
  || xtype || integer || type of currently used variable (see netCDF manual for further reference) ||
  || temperatur_index || integer || index of variable TEMP in current netCDF file ||
  || theta_index || integer || index of variable THETA in current netCDF file ||
  || temp_dot_index || integer || index of variable TEMP_DOT in current netCDF file ||
  || u_index || integer || index of variable U in current netCDF file ||
  || v_index || integer || index of variable V in current netCDF file ||
  || phi_index || integer ||& index of variable GPH in current netCDF file ||
  || rv_index || integer || index of variable RELVOR in current netCDF file ||
  || ex_input || logical || .true., if input file *.inp exists ||
  || pv_berechnet || logical || .true., if PV has been computed ||
  || m_berechnet || logical || .true., if M has been computed ||
  || file_in || character*60 || name of input data file ||
  || file_out || character*60 || name of output data file ||
  || datensatz || character*10 || name of file class ||
  || daten_herkunft || character*512 || origin of data ||
  || daten_beschreibung || character*512 || data description ||
  || pi_name || character*60 || name of principal investigator ||

  i. ''Arrays''

  The most important arrays used in the isentropic package are listed in the table below.

  || '''Array''' || ''' Type''' || '''Dimension''' || '''Description''' ||
  || var_dim || integer || max_coord || dimensions of current variable ||
  || var_dim_isen || integer || max_coord || dimensions of current variable in isentropic coordinates ||
  || var_dim_rr || integer || max_coord || dimensions of current variable on regular grid ||
  || coord_id || integer || max_coord || ids of coordinates of current netCDF file ||
  || att_int || integer || anz_att || global integer attributes ||
  || elements || integer || 8 || time parameters ||
  || anfang || integer || 4 || starting time levels for output ||
  || zaehler || integer || 4 || counter of time levels for output ||
  || att_name || character*30 || anz_char || global attribute names ||
  || att_text || character*512 || anz_char || contents of global attributes ||
  || params || character*30 || anzahl_parameter_attribute || name of global attributes ||
  || inhalt_params || character*60 || anzahl_parameter_attribute || contents of global attributes ||
  || theta_alloc || real || 1 || requested theta levels ||
  || position || real || 4 || pressure field in isentropic coordinates ||
  || dthetaoverdp || real || 3 || array containing d Theta/d p in isobaric coordinates ||
  || d_theta_over_d_p || real || 3 || array containing d Theta/d p in isentropic coordinates ||
  || dthetaoverdz || real || 3 || array containing d Theta/d z in geometrical height coordinates ||


  i. ''Derived Types''

  Most of the information read in from the data files and written to the output is stored in form of complex structures, the so-called derived types. These are made up of scalars and allocatable arrays and various kinds of pointers. In {{{isentropic}}} three different derived types are used. First of all there is the type ''daten'', in which all information concerning the variables such as PV are stored. The structure looks like

  {{{
  type daten
     character :: name*30 ! variable name
     integer :: var_id ! variablen id
     integer :: anz_dim ! number of dimensions
     integer, pointer :: dim_id(:) ! dimensionen ids
     integer, pointer :: dim_len(:) ! dimensions
     integer :: var_type ! variable type
     integer :: anz_att ! total number of attributes
     integer :: anz_char_att ! number of character attributes
     integer :: anz_int_att ! number of integer attributes
     integer :: anz_float_att ! number of real attributes
     integer :: anz_double_att ! number of double attributes
     integer, pointer :: xtype_vektor(:) ! contains sequence of attribute types
     character, pointer :: var_attname(:) *30 ! character attribute names
     character, pointer :: var_atttext(:) *512 ! character attribute contents
     character, pointer ::var_iattname(:) *30 ! integer attribute names
     integer, pointer :: var_iatttext(:) ! integer attribute contents
     character, pointer :: var_fattname(:) *30 ! real attribute names
     real, pointer :: var_fatttext(:) ! real attribute contents
     character, pointer :: var_dattname(:) *30 ! double attribute names
     double precision, pointer :: var_datttext(:) ! double attribute contents
     real, pointer :: analyse(:,:,:,:) ! data
  end type daten
  }}}

  All variables of the input data are stored in an array with this type of structure named ''ecmwf'', which is allocated during runtime. In the case of ECMWF input data, which reside on a horizontal gaussian grid, the variables are first interpolated onto a regular equidistant horizontal grid. The result is stored in the structure ''ecmwf_rr''.

  As for the UKMO data, only THETA_DOT is interpolated onto a different horizontal grid. This is done because the variables in the UKMO data sets are defined on two separate, staggered grids. All other variables are just copied from ''ecmwf'' to ''ecmwf_rr''.

  After interpolating the data onto the requested isentropic levels, the results are stored in the structure ''ecmwf_isen'', which contains all variables from ''ecmwf'' but THETA, which is substituted by PRESS. Additionally the new structure contains the new variables PV and M, if all conditions above mentioned are met.

  The other structures used are the derived types ''koordinaten'', for the spatial coordinate variables, and ''zeit_koordinaten'', for the time coordinate variable. They only differ from one another in the pointer ''feld'', which is a real pointer in ''koordinaten'' and a double precision pointer in ''zeit_koordinaten''.

  {{{
  type koordinaten
     character :: name*30 ! coordinate name
     integer :: coord_id ! coordinate id
     integer :: dim_len ! dimension
     integer :: anz_att ! total number of attributes
     integer :: anz_char_att ! number of character attributes
     integer :: anz_int_att ! number of integer attributes
     integer :: anz_float_att ! number of real attributes
     integer :: anz_double_att ! number of double attributes
     integer, pointer :: xtype_vektor(:) ! contains sequence of attribute types
     character, pointer :: coord_attname(:)*30 ! character attribute names
     character, pointer :: coord_atttext(:)*60 ! character attribute contents
     character, pointer :: coord_iattname(:)*30 ! integer attribute names
     integer, pointer :: coord_iatttext(:) ! integer attribute contents
     character, pointer :: coord_fattname(:)*30 ! real attribute names
     real, pointer :: coord_fatttext(:) ! real attribute contents
     character, pointer :: coord_dattname(:)*30 ! double attribute names
     double precision, pointer :: coord_datttext(:)! double attribute contents
     real, pointer :: feld(:) ! data
  end type koordinaten
  }}}

  The coordinate variables are ''latitude'', ''longitude'', ''pressure'' and ''time'' for ECMWF input files and ''latitude1'', ''latitude2'', ''longitude1'', ''longitude2'', ''pressure'' and ''time'' for UKMO data sets. This is due to the fact that UKMO data are on a staggered grid.

  i. ''The Subroutines''

  The modules {{{nc_routines}}} and {{{isen_module}}} contain a multitude of subroutines for different purposes. From version isentropic-2.2 (Tag isentropic-rel-2.2) on some of the subroutines have been moved from the modules to the files containig the main routines of the utilities if they were only used by that specific program. They can still be found using the tag tabel (e. g. from within emacs). In the following they are listed with a short description.

  || '''Subroutine''' || '''Description'''||
  || abfrage_global || Inquires the input data file for global attributes ||
  || kopiere_global || Copies global attributes from input to output file ||
  || aendere_global || Changes global parameters in output file ||
  || lese_koordinaten || Reads allcoordinate variables from ECMWF input data ||
  || lese_ukmo_koordinaten || Reads all coordinate variables from UKMO input data ||
  || lese_variablen || Reads all variables from ECMWF input data ||
  || lese_ukmo_variablen || Reads all variables from UKMO input data ||
  || diagnostic || Prints diagnostics like minval and maxval ||
  || neue_koordinaten || Creates new coordinate variables for ECMWF data sets ||
  || neue_ukmo_koordinaten || Creates new coordinate variables for UKMO data sets ||
  || neue_variablen || Creates output for ECMWF data sets ||
  || neue_ukmo_variablen || Creates output for UKMO data sets ||
  || erzeuge_variablen || Obsolete ||
  || erzeuge_struktur || Creates new variables for ECMWF data sets ||
  || erzeuge_ukmo_struktur || Creates new variables for UKMO data sets ||
  || erzeuge_regulaeres_gitter || Horizontal interpolation from gaussian to UKMO grid using splines ||
  || erzeuge_regulaeres_t106 || Horizontal interpolation from gaussian to equidistant grid with T106 resolution using splines ||
  || erzeuge_regulaere_struktur_nilu || Creates new variables for ECMWF data sets from NILU ||
  || erzeuge_ukmo_arakawa_b || Horizontal Interpolation from Arakawa-C to Arakawa-B grid (only for THETA_DOT) ||
  || interpolation_auf_thetaflaechen || Vertical interpolation on theta levels using splines. ||
  || druckhoehen || Vertical interpolation of requested theta levels on pressure using splines. ||
  || druckhoehen_linear || Vertical interpolation of requested theta levels on pressure using logarithmic interpolation. ||
  || intpol_auf_thetaflaechen_lin || Vertical interpolation on theta levels using logarithmic interpolation. ||
  || grid2_to_grid1 || Utility of erzeuge_regulaeres_t106 ||
  || berechne_pv || Calculation of PV (straight forward) ||
  || anfuegen_pv || Adds PV to output file ||
  || berechne_dthetaoverdp || Calculation of d Theta/d p on isentropic surfaces ||
  || berechne_dthetaoverdz || Calculation of d Theta/d p in geometrical height coordinates||
  || berechne_montgomery || Calculation of Montgomery stream function on isentropic surfaces ||
  || anfuegen_montgomery || Adds M to output file ||
  || berechne_pv_isobar || Calculation of PV on isobaric surfaces ||
  || berechne_pv_aus_rv || Calculation of PV with RELVOR for ECMWF data sets (DKRZ) ||
  || berechne_pv_pp || Calculation of PV as in PP package on isentropic surfaces ||
  || freigabe || releases allocated memory before reading next input file ||
  || berechne_pv_isobar_pp || Calculation of PV as in PP package on isobaric surfaces ||
  || berechne_pv_nilu || Calculation of PV for ECMWF data sets (NILU) ||
  || ueberpruefe_herkunft || Checks data_origin ||

The isentropic package

  1. What is the isentropic package? The isentropic package was developed at the Institute for Stratospheric Chemistry of the Research Center Jülich. It succeeds the formerly used isentropic program of the PP package originally developed at the UK Meteorological Office. Its purpose is to convert four-dimensional data sets containing atmospheric parameters from pressure coordinates to theta coordinates, theta being the potential temperature. Currently, it is possible to convert five types of data sets: assimilated data by the UK Meteorological Offices Unified Model (UKMO data), and ECMWF data sets originating from the German Center for Climatological Research, hereafter called DKRZ, from the NILU data center(NILU), from KNMI (KNMI) and Meteo France (METEO_FRANCE). In order to be processed by the programs of the isentropic package all of the above mentioned data sets have to be converted to netCDF data format first!

  2. How to get the source code

    The source code of the isentropic package is under the control of the CVS (Concurrent Version System) utility. To get the source code first make sure that the environment variable CVSROOT is set to /usr/local/icg/icg1/archive, then just type 

     cvs co isentropic

    This command creates a subdirectory ./isentropic in your current working directory and afterwards checks out the source code to subdirectories of this directory. Change your working directory to the new ./isentropic subdirectory. A directory listing will look like this: 

     insgesamt 2216
 drwxr-xr-x   9 icg134   icg1         1024 Jul  7 09:30 ./
 drwxr-xr-x  18 icg134   icg1          512 Jul  4 10:44 ../
 -r--r--r--   1 icg134   icg1           51 Apr 22 08:26 .cvsignore
 drwxr-xr-x   3 icg134   icg1          512 Jul  5 14:17 CVS/
 -r--r-----   1 icg134   icg1         7317 Jul  5 14:17 Makefile
 -r--r-----   1 icg134   icg1          651 Jul  4 11:25 RELEASE.tags
 drwxr-xr-x   3 icg134   icg1          512 Jul 21 10:19 doc/
 -r--r--r--   1 icg134   icg1         6323 Apr 19 15:40 gauss_grid.dat
 drwxr-xr-x   3 icg134   icg1          512 Jul  5 16:24 mod/
 drwxr-xr-x   3 icg134   icg1          512 Jul  5 16:24 obj/
 drwxr-xr-x   3 icg134   icg1          512 Jul  7 09:25 scripts/
 drwxr-xr-x   3 icg134   icg1          512 Jul 20 12:29 source/
 drwxr-xr-x   3 icg134   icg1          512 Jul  3 14:51 templates/

    The isentropic package consists of several files, the most important being described below. Please note that the *.f90 files in ./isentropic/source (and other files) are checked out write-protected. This is done by default to avoid unintentionally changing of the source code. If you want to change the source code, run the 

     cvs edit ''filename''

    command instead of just changing the file permissions with chmod. When you are finished with editing, please use the command 

     cvs unedit ''filename''

    to make the file read-only again. This will abandon your changes and revert to the old version of the file in the repository again. Therefore make sure to commit your changes, if you want to have them applied to the repository. Using the cvs commands edit and unedit notifies a possibly running cvs watching process. After having checked out the source code, just type the command 

     make ''target''

    to have the specified part of the package be compiled. Using the target all will result in a compilation of the whole package, the targets add_pv_isobar, add_theta, isentropic, read_ecmwf and add_eqlat will cause the  make command to create the belonging parts of the package. The targets clean and tidy will lead to a removal of all object and executable files or core files, respectively. Target new is a combination of clean and all and will lead to a complete recompilation of the package. Another helpful feature will be introduced by the completing the target TAGS, which creates a tag table for emacs. For a detailed description of the targets please refer to the target section of the Makefile. Please note, that Makefile relies on the mkincl package. If you have not done already check this package out as well.

  3. The utilities

    There are a lot of utility programs, which help to convert or add data to given data sets, thus preparing data files for the subsequent use of isentropic itself or other procedures like plotting routines. Almost all of these utilities and the program isentropic use the modules types, nc_routines and isen_module. These files contain the declaration of all used global variables and structures together with a lot of different subroutines, which read or write netCDF formatted data, help recognizing and creating common used structures, compute diagnostic physical variables and much more. These module files are described in more detail in section 1.5. Another often used module is dateconv.f90, which contains a lot of date and time converting routines. Although dateconv.f90 is shipped along with the isentropic package, it is not a part of this package and is just supplied for reasons of consistency. The dateconv module is described elsewhere.

    There are several other routines (basically shell scripts) which help to run the package on the Cray. These are job_add, job_isen and job_read.

    1. add_theta

      The program add_theta is designed to add the diagnostic variable THETA (potential temperature) to data sets of the above described kind. This addition can only be performed if the data set already contains the variable TEMP (temperature). If the data set already contains THETA, the program will stop. If the data set contains a variable named TEMP_DOT (the time derivative of temperature), then the time derivative of theta THETA_DOT will also be computed and added to the data set.

      The program add_theta reads the following values from the input file add_theta.inp: the user name, which should conform to the mail-address name conventions of the Research Center, the class of the files to be modified, e. g. UKMO, DKRZ or NILU, and the names of the files. The program will check the data sets global parameters data_description and data_origin for their contents. The class name will be overwritten by the values found in the data set. If there are no values found in the data set, the given class name will be used. Giving a wrong class name in the latter case will lead to wrong results! Multiple file names can be added to the input file, each one on a single line. Make sure that the last line is completed by a carriage return/line feed!

    2. add_eqlat

      The program add_eqlat calculates equivalent latitudes for UKMO data sets in isobaric or isentropic coordinates and adds it to the data set. Equivalent and normalized latitudes are computed according to the method of L. Lait. add_eqlat reads from add_eqlat.inp the filename of the input data set and the name of the directory, where it resides.

    3. add_pv_isobar

      The program add_pv_isobar computes the variable PV_ISOBAR (potential vorticity on isobaric surfaces) for UKMO and ECMWF data sets and adds the variable to the data set. This variable is computed in a different way from the variable PV in isentropic. Nevertheless, if add_pv_isobar is applied to a data set before isentropic, the resulting variables PV_ISOBAR and PV should at least show similar if not identical results. add_pv_isobar reads from add_pv_isobar.inp the user name, the class of the files to be read in and the filename of the input data set. The details for specification of input parameters described for add_theta, e. g. the class names, hold true for add_pv_isobar!

    4. read_ecmwf

      The program read_ecmwf is used for conversion of ECMWF data originating from the DKRZ, which contain data for a whole month. It reads in the output from the afterburner program supplied by the DKRZ, which converts the original data file written in GRIB format to binary format. This format is read in by read_ecmwf and converted to netCDF format. For more information about the afterburner program please refer to its manual.

      read_ecmwf reads in from read_ecmwf.inp the user name, the name of the input data set and the numerical values for the days of the month to be extracted. The output filenames are generated automatically from the date and the hour of the requested days, e. g. ecmwf_97021412.nc contains data for the 14th of February 1997 noon.

      Since the output data files of afterburner can be very big with file sizes larger than 2 GB, it is recommended to use {\tt afterburner} and read_ecmwf on the Cray. This is due to the fact that files with file sizes larger than 2 GB are currently not supported on the AIX cluster.

  4. The main program: isentropic

    The program isentropic reads in four-dimensional data sets in netCDF format and converts the data to be on requested isentropic surfaces rather than on isobaric surfaces. This can only be done, if the input data set contains THETA. Therefore the program first checks for the existence of THETA. If this parameter is not contained in the data set, the program will stop with a corresponding message. You should then apply add_theta to the data set to complete it with the desired variable.

    If THETA is contained and the requested theta levels are not completely outside the range of the data set (which will cause the program to stop with a corresponding error message), isentropic will start to convert all variables of the data set into values on isentropic levels. This is done by interpolating all variables onto a maximum of 30 theta levels. If more theta levels are needed, just change the parameter max_tlevel in the file isen_module.f90 and recompile. Additionally the program adds the diagnostic variables PV (potential vorticity) and M (Montgomery stream function) to the output file. The addition of PV can only be performed, if the variables U and V (horizontal wind fields) or RELVOR (relative vorticity) are contained in the input data set. The same holds true for the addition of M, which is only possible when the values for GPH and TEMP are known. If the mentioned requirements are not met, the program will notify you with corresponding messages.

    The program isentropic reads the following values from the input file isentropic.inp: the user name, the class of the files to be read in, number and value of the desired isentropic surfaces and the names of the input and output data sets. The names of the input and the corresponding output data sets must occur on the same line.

    The details for specification of input parameters described for add_theta, e. g. the class names, hold true for isentropic!

  5. The module: types.f90,nc_routines.f90 and isen_module.f90

    The f90-module types.f90 contains the declaration of all global variables and structures that are shared by most of the above mentioned utilities and programs. The most important are described in the following subsections without going to much into detail.

    1. Variables The most important variables used in the isentropic package are listed in the table below.

      Variable

      Type

      Description

      max_tlevel

      integer

      maximum number of theta levels

      max_coord

      integer

      maximum number of coordinate variables

      anzahl_theta

      integer

      number of requested theta levels

      status

      integer

      contains the status value of netCDF functions

      ncid

      integer

      id of currently used input netCDF file

      nc_out

      integer

      id of currently used output netCDF file

      anz_dim

      integer

      number of dimensions in netCDF file

      anz_var

      integer

      number of variables in netCDF file

      anz_att

      integer

      number of attributes in netCDF file

      dim_id

      integer

      id of currently used dimension

      unlimdimid

      integer

      id of unlimited dimension in netCDF file

      att_id

      integer

      id of currently used attribute

      laenge

      integer

      length of currently used attribute (character string)

      xtype

      integer

      type of currently used variable (see netCDF manual for further reference)

      temperatur_index

      integer

      index of variable TEMP in current netCDF file

      theta_index

      integer

      index of variable THETA in current netCDF file

      temp_dot_index

      integer

      index of variable TEMP_DOT in current netCDF file

      u_index

      integer

      index of variable U in current netCDF file

      v_index

      integer

      index of variable V in current netCDF file

      phi_index

      integer

      & index of variable GPH in current netCDF file

      rv_index

      integer

      index of variable RELVOR in current netCDF file

      ex_input

      logical

      .true., if input file *.inp exists

      pv_berechnet

      logical

      .true., if PV has been computed

      m_berechnet

      logical

      .true., if M has been computed

      file_in

      character*60

      name of input data file

      file_out

      character*60

      name of output data file

      datensatz

      character*10

      name of file class

      daten_herkunft

      character*512

      origin of data

      daten_beschreibung

      character*512

      data description

      pi_name

      character*60

      name of principal investigator

    2. Arrays The most important arrays used in the isentropic package are listed in the table below.

      Array

      Type

      Dimension

      Description

      var_dim

      integer

      max_coord

      dimensions of current variable

      var_dim_isen

      integer

      max_coord

      dimensions of current variable in isentropic coordinates

      var_dim_rr

      integer

      max_coord

      dimensions of current variable on regular grid

      coord_id

      integer

      max_coord

      ids of coordinates of current netCDF file

      att_int

      integer

      anz_att

      global integer attributes

      elements

      integer

      8

      time parameters

      anfang

      integer

      4

      starting time levels for output

      zaehler

      integer

      4

      counter of time levels for output

      att_name

      character*30

      anz_char

      global attribute names

      att_text

      character*512

      anz_char

      contents of global attributes

      params

      character*30

      anzahl_parameter_attribute

      name of global attributes

      inhalt_params

      character*60

      anzahl_parameter_attribute

      contents of global attributes

      theta_alloc

      real

      1

      requested theta levels

      position

      real

      4

      pressure field in isentropic coordinates

      dthetaoverdp

      real

      3

      array containing d Theta/d p in isobaric coordinates

      d_theta_over_d_p

      real

      3

      array containing d Theta/d p in isentropic coordinates

      dthetaoverdz

      real

      3

      array containing d Theta/d z in geometrical height coordinates

    3. Derived Types

      Most of the information read in from the data files and written to the output is stored in form of complex structures, the so-called derived types. These are made up of scalars and allocatable arrays and various kinds of pointers. In isentropic three different derived types are used. First of all there is the type daten, in which all information concerning the variables such as PV are stored. The structure looks like 

        type daten
     character :: name*30                         ! variable name
     integer :: var_id                            ! variablen id
     integer :: anz_dim                           ! number of dimensions
     integer, pointer :: dim_id(:)                ! dimensionen ids
     integer, pointer :: dim_len(:)               ! dimensions
     integer :: var_type                          ! variable type
     integer :: anz_att                           ! total number of attributes
     integer :: anz_char_att                      ! number of character attributes
     integer :: anz_int_att                       ! number of integer attributes
     integer :: anz_float_att                     ! number of real attributes
     integer :: anz_double_att                    ! number of double attributes
     integer, pointer :: xtype_vektor(:)          ! contains sequence of attribute types
     character, pointer :: var_attname(:) *30     ! character attribute names
     character, pointer :: var_atttext(:) *512    ! character attribute contents
     character, pointer ::var_iattname(:) *30     ! integer attribute names
     integer, pointer :: var_iatttext(:)          ! integer attribute contents
     character, pointer :: var_fattname(:) *30    ! real attribute names
     real, pointer :: var_fatttext(:)             ! real attribute contents
     character, pointer :: var_dattname(:) *30    ! double attribute names
     double precision, pointer :: var_datttext(:) ! double attribute contents
     real, pointer :: analyse(:,:,:,:)            ! data
  end type daten

      All variables of the input data are stored in an array with this type of structure named ecmwf, which is allocated during runtime. In the case of ECMWF input data, which reside on a horizontal gaussian grid, the variables are first interpolated onto a regular equidistant horizontal grid. The result is stored in the structure ecmwf_rr.

      As for the UKMO data, only THETA_DOT is interpolated onto a different horizontal grid. This is done because the variables in the UKMO data sets are defined on two separate, staggered grids. All other variables are just copied from ecmwf to ecmwf_rr.

      After interpolating the data onto the requested isentropic levels, the results are stored in the structure ecmwf_isen, which contains all variables from ecmwf but THETA, which is substituted by PRESS. Additionally the new structure contains the new variables PV and M, if all conditions above mentioned are met.

      The other structures used are the derived types koordinaten, for the spatial coordinate variables, and zeit_koordinaten, for the time coordinate variable. They only differ from one another in the pointer feld, which is a real pointer in koordinaten and a double precision pointer in zeit_koordinaten. 

        type koordinaten
     character :: name*30                          ! coordinate name
     integer :: coord_id                           ! coordinate id
     integer :: dim_len                            ! dimension
     integer :: anz_att                            ! total number of attributes
     integer :: anz_char_att                       ! number of character attributes
     integer :: anz_int_att                        ! number of integer attributes
     integer :: anz_float_att                      ! number of real attributes
     integer :: anz_double_att                     ! number of double attributes
     integer, pointer :: xtype_vektor(:)           ! contains sequence of attribute types
     character, pointer :: coord_attname(:)*30     ! character attribute names
     character, pointer :: coord_atttext(:)*60     ! character attribute contents
     character, pointer :: coord_iattname(:)*30    ! integer attribute names
     integer, pointer :: coord_iatttext(:)         ! integer attribute contents
     character, pointer :: coord_fattname(:)*30    ! real attribute names
     real, pointer :: coord_fatttext(:)            ! real attribute contents
     character, pointer :: coord_dattname(:)*30    ! double attribute names
     double precision, pointer :: coord_datttext(:)! double attribute contents
     real, pointer :: feld(:)                      ! data
  end type koordinaten

      The coordinate variables are latitude, longitude, pressure and time for ECMWF input files and latitude1, latitude2, longitude1, longitude2, pressure and time for UKMO data sets. This is due to the fact that UKMO data are on a staggered grid.

    4. The Subroutines

      The modules nc_routines and isen_module contain a multitude of subroutines for different purposes. From version isentropic-2.2 (Tag isentropic-rel-2.2) on some of the subroutines have been moved from the modules to the files containig the main routines of the utilities if they were only used by that specific program. They can still be found using the tag tabel (e. g. from within emacs). In the following they are listed with a short description.

      Subroutine

      Description

      abfrage_global

      Inquires the input data file for global attributes

      kopiere_global

      Copies global attributes from input to output file

      aendere_global

      Changes global parameters in output file

      lese_koordinaten

      Reads allcoordinate variables from ECMWF input data

      lese_ukmo_koordinaten

      Reads all coordinate variables from UKMO input data

      lese_variablen

      Reads all variables from ECMWF input data

      lese_ukmo_variablen

      Reads all variables from UKMO input data

      diagnostic

      Prints diagnostics like minval and maxval

      neue_koordinaten

      Creates new coordinate variables for ECMWF data sets

      neue_ukmo_koordinaten

      Creates new coordinate variables for UKMO data sets

      neue_variablen

      Creates output for ECMWF data sets

      neue_ukmo_variablen

      Creates output for UKMO data sets

      erzeuge_variablen

      Obsolete

      erzeuge_struktur

      Creates new variables for ECMWF data sets

      erzeuge_ukmo_struktur

      Creates new variables for UKMO data sets

      erzeuge_regulaeres_gitter

      Horizontal interpolation from gaussian to UKMO grid using splines

      erzeuge_regulaeres_t106

      Horizontal interpolation from gaussian to equidistant grid with T106 resolution using splines

      erzeuge_regulaere_struktur_nilu

      Creates new variables for ECMWF data sets from NILU

      erzeuge_ukmo_arakawa_b

      Horizontal Interpolation from Arakawa-C to Arakawa-B grid (only for THETA_DOT)

      interpolation_auf_thetaflaechen

      Vertical interpolation on theta levels using splines.

      druckhoehen

      Vertical interpolation of requested theta levels on pressure using splines.

      druckhoehen_linear

      Vertical interpolation of requested theta levels on pressure using logarithmic interpolation.

      intpol_auf_thetaflaechen_lin

      Vertical interpolation on theta levels using logarithmic interpolation.

      grid2_to_grid1

      Utility of erzeuge_regulaeres_t106

      berechne_pv

      Calculation of PV (straight forward)

      anfuegen_pv

      Adds PV to output file

      berechne_dthetaoverdp

      Calculation of d Theta/d p on isentropic surfaces

      berechne_dthetaoverdz

      Calculation of d Theta/d p in geometrical height coordinates

      berechne_montgomery

      Calculation of Montgomery stream function on isentropic surfaces

      anfuegen_montgomery

      Adds M to output file

      berechne_pv_isobar

      Calculation of PV on isobaric surfaces

      berechne_pv_aus_rv

      Calculation of PV with RELVOR for ECMWF data sets (DKRZ)

      berechne_pv_pp

      Calculation of PV as in PP package on isentropic surfaces

      freigabe

      releases allocated memory before reading next input file

      berechne_pv_isobar_pp

      Calculation of PV as in PP package on isobaric surfaces

      berechne_pv_nilu

      Calculation of PV for ECMWF data sets (NILU)

      ueberpruefe_herkunft

      Checks data_origin

History of Changes

isentropic (last edited 2010-04-30 09:47:20 by NicoleThomas)