source: trunk/LMDZ.MARS/util/README @ 2435

This directory contains source codes of utilities (programs) that can be
used to process the LMD Mars GCM output files (like "diagfi" or
"stats"). 
In addition most output file from one of these program can then be
processed by another.

See script "compile" for instructions and recommendations to compile
the utilities. Once adequately modified, that script can be used to
compile each utility; e.g. to build the zrecast.e utility program:
> compile zrecast

Note that inputs can be provided by (1) replying to questions on screen or
(2) filling the corresponding  *.def and redirecting the input of these *.def
files instead. For example :
> concatnc.e < concatnc.def
> zrecast.e < zrecast.def

--------------------------------------------------------------------
1) concatnc.e : concatenate successive GCM output files 
--------------------------------------------------------------------

This program is used to concatenate consecutive
output files ("diagfi", and even "stats") for a selection of 
variable, in order to obtain one single big file. The time dimension can
be "sols" or "Ls" (in that last case, Ls will not be linear, and
software like Grads may not be able to use it. To have a linear "Ls"
timescale, you can use "Ls_Linear.e" (see below).
You can also add a "Ls" variable corresponding solar longitude for each
timestep by using the "adls" option.

Output file is : concat.nc

--------------------------------------------------------------------
2) zrecast.e : put GCM data in physical vertical coordinate
--------------------------------------------------------------------

GCM outputs are in GCM hybrid coordinate which do not correspond to any
physical vertical coordinate ! zrecast is NECESSARY to make any publishable
scientific figure.

This program reads 4D (lon-lat-alt-time) fields from GCM output files
(ie: diagfi.nc time series or concat.nc or stats.nc files) and, by
integrating the hydrostatic equation, recasts data along the vertical
direction.
The vertical coordinate can be either 1) pressure, 2) above areoid
altitudes, 3) above local surface altitudes or 4) distance to center of
the planet. Some interpolation along the vertical direction is also
done, following instructions given by user (levels may be specified
or given as minimu,maximum and number of levels).
For "above areoid altitudes" output, Atmospheric pressure is added to
output dataset; for "pressure coordinate" outputs, the above areoid
altitude of pressure is added to output dataset.

Minimal requirements and dependencies:
The dataset must include the following data:
- surface pressure
- atmospheric temperature
- hybrid coordinates aps() and bps(), or sigma levels() 
- ground geopotential (in input file; if not found, it is sought
  in a 'diagfi.nc' file. If not found there, it is then sought in
  a 'phisinit.nc' file  (see section 1.3.3 of program)

- When integration the hydrostatic equation, we assume that R, the
molecular Gas Constant, may not be constant, so it is computed as
R=P/(rho*T) (P=Pressure, rho=density, T=temperature)
If 'rho' is not available, then we use a constant R (see section
2.2 in source file)

- Vertical interpolation : note that density (kg.m-3) and species density 
(e.g. in molecules.cm-3) must be vertically interpolated in log-space. For
that purpose, these variables names must start with "rho" (exemple : rho for
density, rho_co2, rho_o2, etc....)

output file is : 
name_of_input_file_P.nc with pressure coordinate 
name_of_input_file_A.nc with altitude above areoid coordinate 
name_of_input_file_S.nc with altitude above local surface coordinate 
name_of_input_file_R.nc with altitude as distance to center of planet 

--------------------------------------------------------------------
3) localtime.e : put GCM data in local time coordinate
--------------------------------------------------------------------

Program to redistribute and interpolate the variable a the same
local times everywhere (useful to mimic satellite observations, or
analyse day to day variations at a given local time). 
input : diagfi.nc  / concat.nc / stats.nc kind of files

output file is : name_of_input_file_LT.nc

--------------------------------------------------------------------
4) lslin.e : redistribute and AVERAGE gcm output in Ls coordinate.
--------------------------------------------------------------------

This program has been designed to interpol data in Solar Longitude (Ls)
linear time coordinate (usable with grads) from Netcdf diagfi or concatnc  
files and to AVERAGE the instantaneous data in Ls period (for comparison with
binned dataset, for instance).

lslin also creates a lslin.ctl file that can be read
directly by grads (>xdfopen lsllin.ctl) to plot in Ls coordinate to
avoid some problem with grads when grads think that "the time interval
is too small"...

Output file is : name_of_input_file_LS.nc

--------------------------------------------------------------------
5) solzenangle.e : select GCM data at a given solar zenith angle
--------------------------------------------------------------------

Program to redistribute and interpolate the variable a the same
solar zenith angle (notably useful to mimic satellite observations and in particular
SOLAR OCCULTATIONS by choosing solar zenith angle = 90°)
The user choose between Morning and Evening side. 

input : diagfi.nc  / concat.nc / stats.nc kind of files

On the morning side output file (1 output per sol per grid point) is :
 name_of_input_file_MO.nc  

On the evening side output file is (1 output per sol per grid point):
 name_of_input_file_EV.nc  

--------------------------------------------------------------------
6) hrecast.e : interpolate data at another horizontal grid resolution.
--------------------------------------------------------------------

This program can interpolate GCM output on any horizontal grid (regular
lat - lon) as long as it cover all the planet.
The grid can be given points by points. The best way is to use the 
redirected input hrecast.def

hrecast.e < hrecast.def


--------------------------------------------------------------------
7) expandstartfi.e : to plot data in a startfi.nc file
--------------------------------------------------------------------

In startfi.nc file, data are not plotable because the horizontal coordinate
in only a 1D list of all atmospheric columns on the planets.
This program takes a physics start file ("startfi.nc") and recasts it
on the corresponding  lonxlat grid (so it contents may easily be displayed
using Python, Grads, Ferret, etc.)

Simply run expandstartfi.e as a command line with arguments:

expandstartfi.e  [infile.nc] [outfile.nc]

     (if infile is not specified, "startfi.nc" is used as default)
     (if outfile is not specified, it is built as "infile_ex.nc")

--------------------------------------------------------------------
8) extract.e : get data at specific coordinates for comparison with observations
--------------------------------------------------------------------

This program extracts (ie: interpolates) pointwise values of an atmospheric 
variable from a 'zrecast'ed diagfi file (works if altitude is geometrical 
height or a pressure vertical coordinates)
user has to specify:
- name of input file
- date (in sols) offset wrt the input file (e.g. if the input file "begins"
  at Ls=0, then the offset is 0; if the input file begins at Ls=30, the
  offset date corresponding to the first 3 months is 61+66+66=193 sols, etc.)
- the "extraction mode": 
     1: extract individual values; user will specify values of
        lon lat alt Ls LT (all on a same line)
        on as many lines as there are sought values
     2: extract a profile: user will specify on a first line the values of
        lon lat Ls LT (all on a same line)
        and then only specify values of altitudes (m or Pa depending on the
        coordinate in the input file), one per line, at which values are
        sought
 - output values are sent to (ASCII) output file 'infile_var_.dat', where
   'infile' is the input file name (without trailing '.nc') and
   'var' is the sought variable, for extraction mode 1 as
   lines of "lon lat alt Ls LT value" and for a profile (extraction mode 2)
   as lines of "alt value"

  NB: If there is no data to do an appropriate interpolation to extract
      the sought value, then a "missing_value" (taken from the variable's
      attribute in the input file, most likely -9.99E33) is returned.

See files "extract.points.def" and "extract.profile.def" for examples of
input format that would simply need to be redirected to extract.e, e.g.:

extract.e < extract.points.def

--------------------------------------------------------------------
9) aeroptical.e : compute aerosol opacities at a given wavelength
--------------------------------------------------------------------

Program to compute opacities [1/km] of all aerosols from dust, water ice
and stormdust present in the input file, at a wavelength given by the user.
Computation is made from the aerosol mass mixing ratios and effective radius,
associated with air density (rho) and files containing the aerosol 
optical properties (generally present in the GCM datadir/ directory).

NB : water ice effective radius is known to be a bit inaccurate in the GCM,
so reffwice can be prescribed by the user.

input : diagfi.nc  / concat.nc / stats.nc kind of files

output file is : name_of_input_file_OPA.nc
aeroptical.e < aeroptical.def