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