================================
GENIEfication of ATCHEM & BIOGEM
RELEASE NOTES: 07/01/17
================================


WARNING: Currently, ATCHEM & BIOGEM are unlikely to work in conjunction with the IGCM compiled at real*4 precision.
         you must compile the IGCM and GENIE @ real*8 to have any chance of having a happy BIOGEM.
         (These are the default compile settings in genie_eb_go_gs_ac_bg.config.)
NOTE: the following notation assumes you are in the directory in which the root genie directory lives
      (which will probably be your home directory)


PREAMBLE
--------

The template configuration for genie_eb_go_gs_ac_bg is
genie_eb_go_gs_ac_bg
(and can be found in genie/genie-main/configs/ alongside all 10^15 other alternative (non-biogeochem) flavors)
It contains settings such as:
   * selection of ATCHEM and BIOGEM modules
   * default number of ocean tracers (2):
     GOLDSTEINNTRACSOPTS='-DGOLDSTEINNTRACS=2'
   * the genie_eb_go_gs climate model parameter values as per the EnKF calibration of C-GODLSTEIN [Ridgwell et al., 2006]
   * and at the very end, whether the genie_eb_go_gs climate model is allowed to respond to atmospheric CO2 as calculated by ATCHEM ('n' or 'y'):
     ea_36=n

However, it is not recommended that this configuration is used directly in the 'normal' mode of running GENIE, i,e,:
$ ./genie_example.job -f configs/genie_eb_go_gs_ac_bg.config
because it has been designed to act as a 'template' for generating more specific biogeochem configurations.

In addition, there are a number of biogeochem parameter and configuration files that must be located in their various little baskets, e.g.,:
genie/genie-atchem/data/input
genie/genie-biogem/data/input
genie/genie-main/data/input
While you might drag-and-drop or copy-and-paste the files appropriately, this odious task it more likely to cause you to roll-over-and-die.

Thus, I have written a script to complete the configuration and run the genie_eb_go_gs_ac_bg chicken vindaloo flavor of GENIE (i.e., CB-GOLDSTEIN).

Obtain the BASH script
rungenie_eb_go_gs_ac_bg

from my website
http://mygenie.seao2.org

Copy it into the same directory in which the root genie directory lives (which will probably be your home directory).
Make it excutable by you: i.e.,
$ chmod 744 rungenie_eb_go_gs_ac_bg

Also create a directory called genie_input, i.e.:
$ mkdir genie_input
(and which will contain different the definitions of all the different biogoechem runs you want to do, each in their own seperate sub-directory)

Your main (home?) directory should include all the following items:
genie
genie_input
genie_output
rungenie_eb_go_gs_ac_bg
...
(genie_output may not be present if you have not run GENIE in any shape or form yet - don't worry if is not present at this point)


RUNNING genie_eb_go_gs_ac_bg
----------------------------

You run GENIE (flavor genie_eb_go_gs_ac_bg) as follows:

$ ./rungenie_eb_go_gs_ac_bg OPTIONS

Now pay attention: there are 4 (FOUR) parameters that MUST be passed to the script as OPTIONS:
    #1 whether you want climate feedbacks on the carbon cycle
       (i.e., whether the EMBM is allowed to respond to greenhouse gas concentrations calculated in ATCHEM)
    #2 the start year of the experiment
    #3 the run length of the experiment in years
    #4 the name of the experiment
       - there must be a subdirectory in genie_input with this name (and some parameter files witbin would be helpful)
There is also one optional (5th) parameter:
    #5 is the name of any restart - (there must be a subdirectory in genie_output with this name)

If the 5th optional parameter is not passed then genie_eb_go_gs_ac_bg will run from 'cold' (i.e., no re-start).
if the 5th parameter is present then genie_eb_go_gs_ac_bg will attempt to run from a previously generated re-start state

[Refer to examples at the bottom for option usage]

The script will create a new configuration file in genie/genie-main/configs called
genie_eb_go_gs_ac_bg.$EXP.config
which is derived from the genie_eb_go_gs_ac_bg.config template file.
The new configuration file will contain additional settings such as:
    * the number of time-steps in the model in order to exactly achieve your requested run length
    * whether a re-start file is to be used or not

The script will also do helpful things for you, such as:
    * copy the biogeochem parameter and configuration files from genie_input/EXP to their relevant baskets
    * delete the contents of genie_output/EXP if it exists to remove the results of any previous run of EXP
and at the end of the run will:
    * move the genie_eb_go_gs_ac_bg.$EXP.config config file from genie/genie-main/configs (where they are all starting to clutter)
      to your results directory (genie_input/EXP)
    * tar a gzip the contents of genie_input/EXP:
      genie_eb_go_gs_ac_bg.$EXP.config.tar.gz
    * remove all the configuration files from their various baskets
      (it would be helpful if no-one would commit on CVS random config files to these directories)

The script will also try and determine whether you have selected a different number of ocean tracers compared to the last time that the model is run.
This is important because the model must be built fromn scratch (i.e., following a make cleanall) if the number of tracers is changed.
By default, the number of tracers in genie_eb_go_gs_ac_bg.config is set to 2.
Thus, the first time that genie_eb_go_gs_ac_bg is run, it will first be compiled from clean.
The script will then modify the template config file genie_eb_go_gs_ac_bg.config to record the new number of tracers.
If you don't subsequently change the number of tracers, then the model will not have to be re-built from scratch, and will execute much faster :)

NOTE: If when the biogeochem models start up everything goes nuts and haywire, try starting from scratch, i.e.:
$ make cleanall
(from the genie/genie-main directory)
before invoking ./rungenie_eb_go_gs_ac_bg again

NOTE: Screw-ups are also possible if the script for whatever reason does not correctly update the number of tracers in genie_eb_go_gs_ac_bg.config
      => it is possible to end up with the relevant line looking like:
         GOLDSTEINNTRACSOPTS='-DGOLDSTEINNTRACS='
         in which case simply insert the digit 2 after -DGOLDSTEINNTRACS='-, (save) and try again ...


EXAMPLES
--------

For example, you can find the set-up for a simple example genie_eb_go_gs_ac_bg experiment on
http://mygenie.seao2.org
and called spin_example.zip (so you will need to un-zip first of course ...).
This will spin up (from cold) genie_eb_go_gs_ac_bg as described in Ridgwell et al. [2006] (or close ...).
You can run it for as many years as you like, such as:

$ ./rungenie_eb_go_gs_ac_bg n 0 11 spin_example
-> an 11-year long run starting from year zero with no climate feedback

$ ./rungenie_eb_go_gs_ac_bg n 0 1765 spin_historical
-> a 1765-year long run (spin_historical) starting from year zero with no climate feedback

$ ./rungenie_eb_go_gs_ac_bg y 1765 335 run_climatechange spin_example
-> a 335-year long run (run_climatechange) starting from year 1765 (with climate feedback and starting from a re-start (spin_historical)
   (note that this run will end in year 2100)


Enjoy!


&e