RPN standard files

The RPN standard file format is a file format developed by "Le Centre de recherche en prévision numérique" (RPN) to store weather and climate related data. Usually, there is one 2-D (latitude and longitude) record for each level, variable and timestep.

...

The maximum size of RPN file is a little more than 8 GB!!! If you are trying to write a file larger than the maximum size the file will not get closed. Meaning no application will be able to open it and it can be considered as "corrupted". The usual error message one get when trying to open such a file is "file (unit=...) currently used by another application in write mode".

Looking at RPN files

vl3, vl4, vl5 -> list variable with description

At UQAM, there is also a set of 'vl' (variable list) commands (one for each model version) which will give you a list of all the variables in an RPN file. The first description is always correct, but rarely contains the unit. For physics fields take the second description with a grain of salt. If it matches the first one, it's unit is correct as well. If it doesn't match, ignore it. However, to all units of accumulators a 'per second' needs to get added, for example:

    precipitation is not in [m] but in [m/s]
    radiation fields are not in [J/m²] but in [J/s/m²] so in [W/m²]

Usage:

voir -> list the content of an RPN file

'voir' is the most simple way to list the content of an RPN file (also xvoir)
It prints the headers for all of the records of the given RPN standard file:

...

xrec -> graphical visualization tool

xrec is a X-window visualization program used to display 2D (horizontal or vertical) meteorological fields stored in FST files. Usage:

...

Do not trust the wind direction for any other vectors but 'UU' and 'VV'!!!

Usage

Among other things, xrec can get used to :

...

Check the full documentation (xrec-documentation) about how to do this or just click on the buttons and look at the menus.

Dictionary

xrec is using a dictionary to define the title, unit (including a multiplication factor) and contour intervals for each variable.
The name of the dictionary is:
      ~/.recrc
It needs to have exactly this name and it needs to be in your home. To have a dictionary to start from you are welcome to take a copy of mine ( cp ~winger/.recrc ~/. ) or ask a college if you can copy hers/his.
You can find more information about this dictionary by clicking on the following link: xrec-dictionary

Remove default contour lines

The first time you open any field with xrec you will see there are "Colors" and "Contours". If you do not want to have "Contours" by default (you can always add or remove them later) do the following:

...

The next time you open xrec the default contour lines should be back and the background should be white again.

High resolution geography

If you want to use high resolution geography on our UQAM servers you need to export:

...

Set min/max

You can use the Min-Max tool to fix a minimum and maximum value for a specific field.

    1) Open the Min-Max menu window by clicking on "Options" in the Control Panel and select "Min-Max / Missing values...".
    2) In the "Code" box search for and select the field for which you want to fix min/max.
    3) In the "Max" box replace "Auto" with your maximum value. Do the same for "Min".
    4) Now click on "Fixed"

Full documentation

You can find the full xrec documentation by clicking on the following link: xrec-documentation

r.fstliste -> list the content of an RPN file

r.fstliste is available if you need a bit more information than what is provided by voir.
It can be used in batch mode to extract specific or all of the record parameters of a RPN standard file record(s) based on a criteria given through the selection keys:

  r.fstliste -izfst RPN-file [-datev -vdatev -ip1 -typvar -nomvar -col ...]

Code/Decode levels

In RPN files levels are coded. The different types of levels are:

• 0 - height [m] (metres)
• 1 - sigma [sg] (0.0->1.0)
• 2 - pressure [mb] (millibars)
• 3 - arbitrary code
• 4 - height [M] (metres) with respect to ground level
• 5 - hybrid coordinates [hy] (0.0->1.0)
• 6 - theta [th]

r.ip1 (Shell)

r.ip1 is a shell command that can be used to code and decode RPN levels as coded in RPN standard files. For more information click on the following link (login/password are the usual 'science'):

...

Or simply execute the following command in a terminal:

      r.ip1 -h

convertIp  (Python)

'convertIp' is a function of the RPN Python module to code and decode RPN levels. To get access to it you first have to import the module, for example with:

...

Answer:
      Decoded value of 41394464 is: 500.0 mb

convip (Fortran)

'convip' is a Fortran function to code and decode RPN levels. 'convip' is part of the RPN Fortran library. To get access to it you need to load the library 'librmn.a' when creating the executable. You can do that by added the key '-lrmn' to the compile command. For example:

...

      'convip' documentation

Code/Decode time stamps

Dates and times are coded in RPN files. This also means that it is not possible to have any times in RPN files:

• Between 1900 01 01 and 1980 01 01 the time resolution is 1 hour.
• Between 1980 01 01 and 2236 01 01 the time resolution is 5 seconds.
  
• Outside these time periods the time resolution is 3 hours.

r.date (Shell)

'r.date' is a shell command that can be used to code and decode RPN dates/times as coded in RPN standard files. For more information click on the following link (login/password are the usual 'science'):

...

Or simply execute the following command in a terminal:

      r.date -h

newdate (Python)

'newdate' is a Python function to code and decode RPN dates/times. To get access to it you first have to import the module, for example with:

...

Answer:
   Decoded value of timestamp 477041750 is: 20241106 at 13300000

newdate (Fortran)

'newdate' is a Fortran function to code and decode RPN dates/times. 'newdate' is part of the RPN Fortran library. To get access to it you need to load the library 'librmn.a' when creating the executable. You can do that by added the key '-lrmn' to the compile command. For example:

...

      'newdate' documentation

Manipulating RPN files

The two main tools to modify FST files are called editfst and r.diag. And of course, you can also write your own C or Fortran programs.

editfst

editfst (also called editfst2000) is a utility used for editing and copying records from RPN standard files into a new or existing RPN standard file. It can do a straight (complete) copy of the input file or it can copy records selectively as indicated from the standard input or from a file of directives named in the "-i" key. One can select (via desire), exclude (via exclure) or zap records by their:

...

Example:
You could use it to select i.e. temperature (TT) and winds (UU,VV) at 500 hPa:

  echo "desire (-1,['UU','VV'], -1 ,-1 ,[500.,MBAR])" | editfst -s input_file -d output_file

Note:
editfst appends to its output file. This means that if editfst is used more than once writing into the same output file, the output of the second set of commands will be appended to the output of the first set.

r.diag

r.diag (also called r.diag2000) is a toolkit used to manipulate FST or CCCma files. As editfst, it can be used to select or exclude specific records but in addition to this it also contains a large set of functions which can be used to manipulate the files.

'r.diag' is always used in the way:

...

• r.diag generally overwrites its output files. There are a few functions, eg. select, which have an option to append to the output file instead of overwriting it.
• By default, output files will be written under ${TMPDIR}!!!
  If there is no path written in front of the output file name and if the output file does not yet exist in the local directory, it will be written in one of the ${BIG_TMPDIR} or ${TMPDIR} directories. Also, if the input file is not in the local directory, r.diag will look for it in the ${BIG_TMPDIR} and ${TMPDIR} directories.
  So if you want to have the output file in a certain directory you have to specify said directory name before the file name. Fir the current directory you can just preceed the file name by './'.

Examples:

'select' - Select fields according to name and level

For example, temperature (TT) and winds (UU,VV) at 500 hPa can get selected with 'select' with the following command:

  r.diag select input_file output_file_tt output_file_uu  output_file_vv  -name TT UU VV -lv1 500

'gsapl' - Interpolate model to pressure levels

Fields on model levels can get interpolated to a set of pressure levels with 'gsapl'.

...

The file 'pres_lev' should now contain the same fields and timesteps as the input file 'mod_lev' but on the pressure level set in 'niveau.dat'.

Writing your own C and Fortran programs

There is a number of functions which can be called in a C or Fortran program to read and write FST files, and they are documented in the RPN Standard File Functions. These functions are part of the library 'librmn'.

There are functions to:

...

Have a look here on how to compile.

Conversion: RPN ↔ NetCDF format

The tool 'cdf2rpn' which can get used to convert RPN to NetCDF format and vice versa. You can get the documentation of cdf2rpn by simply executing the command in a terminal:

...