OBJECTIVE: This Readme describes how to use the Make_orchidee_pft.py
script to generate an orchidee_pft.def_xxpft.xxac file. 

BACKGROUND. The model now requires 3 different def files:
1 - run.def contains the settings that are specific for the driver:
    off-line or coupled.
2 - orchidee.def contains the settings that are specific for an
    experiment. The same orchidee.def file can be used in off-line
    and coupled mode
3 - orchidee_pft.def contains the PFT specific settings. The same
    settings can be used across experiments and drivers. Nevertheless,
    different PFT maps may require different orchidee_pft.defs.

SYNTAX: The script Make_orchidee_pft_defs.py is the main script and
should be run in python.
> module load python
> python Make_orchidee_pft_defs.py

The script will ask for a revision number. This revision number can be
provided through the terminal or it can be given through an arguments
at the time the script is ran:
> python Make_orchidee_pft_defs.py -rev XXXX
or 
> python Make_orchidee_pft_defs.py -r XXXX

MAIN SCRIPT: Make_orchidee_pft_defs.py. The main script is currently
set up to make 4 different orchidee_pft.defs All 4 orchidee_pft.defs
will be copied in the 8 experiment folders (ENSEMBLE, OOL_SEC,
OOL_SEC_STO_FG1trans, OOL_SEC_STO_FG2, OOL_SEC_STO_FG3,
OOL_SEC_STO_FG3nd, SPINUP, and SPINUP_ANALYTIC_FG1.

The main script makes use of the processed parameter file. This file
contains an archive of all parameter values used in different versions
of ORCHIDEE-CN-CAN (see PARAMETERS below). Likewise the script
requires files that describe the PFT configuration in terms of the
pfts that should be used and the number of age classes (see
CONFIGURATIONS below).     

If the script has to be extended for other experiments the folder name
has to be added to the variable 'experiments'. If the orchidee_pft.def
needs to be produced for another PFT configuration the configuration
file will have to be prepared and the main script will have to be
adjusted in the section 'Get the configuration of the PFTs'. First
adjuest the rang(0,4) right above this section. Next add another elif
in the section. The rest of the script can be left untouched.

The script will ask you to give the orchidee revision number for which you want
to make the run.defs. The script works of course for the latest ORCHIDEE revision but
if all correctly filled out the different tables, the script was set up to generate
the correct run.defs for previous versions as well. The oldest tested version it can 
go back to is r5800.


PARAMETERS: processes_parameters.py
This tables contain a single line per PFT and per parameter. If a model version 
requires a new parameter value, add a line with the correct date, revision number
and parameter value. When adding new parameters names to the table make a note in
the table called added. If a parameter is no longer needed after a revision than add
that parameetr name and the revision number to the table called
removed. NEVER DELETE OR ADJUST A PARAMETER ENTRY FROM THIS TABLE!
This table is our archive - only add new entries. If a new PFT has
been parameterized, add all parameter values to this table. 


CONFIGURATIONS: configuration.py 
The configuration_template.py contains all the PFTs for which ORCHIDEE-CN-CAN has been
parameterized. Add new PFTs to this table. When making a new configuration file copy the
template and save it as a new file. Delete the PFTs that should not appear in your PFT
configuration. Specify the number of age classes and mark for each PFT whether it
should be run with age classes or not. There is no need to change the current 4
configuration files. New files can be added to the main script (see above) and old
configuration files should no longer be called by the main script. DO
NOT DELETE OR OVERWRITE CONFIGURATION FILES! Those files are part of our archive.