Notes for installing and running the NWP SAF Radiance Simulator.

----------------------
1. System requirements
----------------------

- Unix or Linux operating system
- Fortran 90 compiler that supports a small number of F2003 features
- 10 MB free disk space for installation (considerably more required for output
  data files)

The code has been tested successfully in one or more standard configurations
after installation with each of the following compilers.

ifort     v12.0.4
pgfortran v11.7-0
gfortran  v4.4.6
xlf       v12.1.0.9

It may work with some older versions of these compilers but these have not been
tested and will not be supported. The NAG compiler has not been tested due to
incompatibility problems with the GRIB API library. Support for it will be added
once this is resolved.

Note on compiler options:

All currently supported input profile datasets are written in big-endian byte
order (with the exception of GRIB which is portable). It is assumed in the case
of the first 3 compilers listed that these will be used on a little-endian
platform and therefore byte-swapping for I/O has been included as a compiler
flag in each case. For the ifort compiler, the F_UFMTENDIAN environment
variable may be used to override this behaviour.

------------
2. Libraries
------------

The following libraries are required. Each can be downloaded from the given
locations if not already available.

- RTTOV

http://nwpsaf.eu/index.html

Note: You may also need to download coefficient files

- GRIB API

https://software.ecmwf.int/wiki/display/GRIB/Home

- netCDF

http://www.unidata.ucar.edu/software/netcdf/

------------

The following libraries may also be required but this is system dependent. Note
that if you have the above libraries installed then these should be present on
the system already.

- HDF5 (used by netCDF and RTTOV)

http://www.hdfgroup.org/HDF5/

- Jasper (used by GRIB API)

---------------
3. Installation
---------------

All Radiance Simulator code is contained in the single tar file radsim.tar.gz.
Users will also need access to some external libraries (see above).

Installation consists of the following steps.

1) Unpack the tar file in your installation directory

tar -xzf radsim.tar.gz

- The directory should now contain the following files

build/*
etc/*
src/*
radsim_install
readme.txt      # this file
user.cfg

2) Edit the user.cfg file to supply paths to external libraries. Also set the
   name of the compiler you wish to use (one of ifort, gfortran or pgfortran).

3) Run the install script.

radsim_install

- The directory should now contain, in addition, the following files

bin/radsim.exe
bin/run_radsim  # Wrapper script for radsim.exe

-------------------
4. Running the code
-------------------

A Fortran namelist configuration file is required to drive the Radiance
Simulator. An example file radsim_cfg_example.nl can be found in the etc
subdirectory of the installation directory. As a minimum, users will need to
specify the following in that file

- Path to profile dataset
- Path to directory containing RTTOV coefficient files
- Satellite instrument identifiers

Most other settings are optional but it's recommended that the output directory
is specified as output files can be large. See User's Guide for more details.

Run the simulations by issuing the following command (assumes your namelist
file is called radsim_cfg.nl, but you are free to rename it)

bin/radsim_run radsim_cfg.nl

----------
5. Outputs
----------

Output data is written to a netCDF file with the following naming convention.

radsim-<platform>_<satid>_<instrument>-<datatime>.nc

e.g.,

radsim-metop_2_amsua-2014010100.nc

The datatime is an optional suffix (of the form YYYYMMDDHH) and will be omitted,
along with the last '-' separator, if the profile dataset is not related to a
single validity time (e.g., the NWP SAF datasets).

Most output data are floating point arrays with the first dimension the number
of simulated observations (labelled dimension 'obs' in the file). Other
dimensions may be levels and channels.