The isentropic package

• == 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! == 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. == 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.

  • === 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! === 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. === 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! === 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.

  === 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! === 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.

  • ==== 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

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

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