#acl ClamsUserGroup:read,write,delete,revert All:read <> = 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 ('''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. == 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 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. === 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 || ---- [[IsentropicChanges|History of Changes]]