README file for the KARINE program.

Introduction
------------

KARINE stands for "K-distribution Atmospheric Radiation:
Infrared Net Exchanges". It is a based on the Monte-Carlo
method, and will compute atmospheric radiative transfer
(radiative budgets, radiative fluxes and all Net Exchange
Rates) in the infrared part of the spectrum. KARINE uses
a k-distribution spectral model, along with the CK
hypothesis for taking into account inhomogeneities.


Features
--------

* Radiative budgets, fluxes and Net Exchange Rates analysis
* Radiative budgets can be decomposed as follows:
  - part of the budget due to exchanges with the ground
  - part of the budget due to exchanges with space
  - part of the budget due to exchanges with the rest of the
    atmosphere
* All results can be computed for each spectral narrowband
* The user can use many options to tweak the behaviour of the
  Monte-Carlo algorith, increase the accuracy of the results, etc.
* Possibility to compute only the analytical results (faster)
* Possibility to resume an interrupted computation.


Teams
-----

KARINE is a collaborative project started by the Laboratoire
d'Enrgetique (Toulouse), the Ecole des Mines d'Albi-Carmaux
(EMAC) and the Laboratoire de Mtorologie Dynamique (Jussieu,
 Paris). Contributors to the project include
Richard Fournier (LE), Stphane Blanco (LE), Jean-Louis
Dufresne (LMD), Amaury de Lataillade (EMAC), Patrice Perez (EMAC),
David Jospeh (EMAC), Maxime Roger (EMAC), Cyril Caliot (EMAC),
Mouna El Hafi (EMAC).


Requirements
------------

* a fortran 77 compiler
* basic unix/linux commands
* the software "grads", which is freely downlodable
  for every linux, unix and windows platform
  (see http://www.grads.iges.org); it is needed
  only for data and results visualization, but not
  for running karine by itself.


Platforms
---------

This program has already been used on:
* fedora core linux
* mandrake 10.1 linux
* windows XP with cygwin

It should be able to work on most unix platforms with a
fortran 77 compiler.


Installation
------------

Once the initial karine.tgz file has been uncompressed, a
directory named "karine" (the directory that contains this
file) is created. No installation is required: the user
should be able to compile the main executable file using
the command 'make all' (used in directory "karine"). Once the
compilation is complete, the executable file "ray.exe" should
appear.
Before running "ray.exe", the user should create at least one
spectral data file. By default, this file has to be created in
"karine/data". Follow the following quick steps to test
the procedure:
* go into "karine/data" (type 'cd data' in directory "karine")
* compile the fortran program "make_data.exe" (type 'f0')
  -> the executable file "create_data.exe" should be created
* make a symbolic link for the default k-coefficient file: type
  'ln -s kcoef_atm2_dn20_k16_1co2.dat kcoef_atm2_dn20_k16.dat'
* run "make_data.exe" (type './make_data.exe')
  -> the file "atmos_data.txt" should now appear

The next step is to go back into the main directory ("karine")
and use the command './ray.exe' in order to run karine for
the first time.

Consider reading the user manual ("karine/Doc/manual.pdf") for
more detailed information.


Use
--

karine uses the data file "/data/atmos_data.txt" as input. This
file contains all the necessary information for atmospheric
radiative transfer computations. Information about this file,
the data it contains and the format it has to be written into
is described in the user manual. Also, the user has the ability
to visualize the data contained into "atmos_data.txt", using
a number of scripts that use "Grads" (see the user manual
for more details).

Before running karine, the user should also consider editing
files "karine/data.in" and "karine/options.in". These files
are very useful for tweaking the bahaviour of the Monte-Carlo
algorithm. A full description of these files is also included in
the user manual.

After a successfull run, the results can be visualized using
a number of scripts located into "karine/Grads". Software "Grads"
needs to be installed for this.


Licence
-------

karine is distributed under the General Public Licence. See COPYING.


Contact
-------

The web page for karine is at
http://energetique.ups-tlse.fr/~eymet/karine.html

If you find bugs, or if you want to contribute to the code, please
contact the author: Vincent Eymet, eymet@energetique.ups-tlse.fr
