(last edit : oct. 3rd, 2012)

---------------------------------------------------------------
A) setup the experiments (incl. llc90 and cs32 core2.cnyf runs) 
---------------------------------------------------------------

0) get MITgcm as explained @ http://mitgcm.org/public/source_code.html
1) the following assumes that you are in directory MITgcm/verification/
   i.e., after checkout of the model repository, do:
      cd MITgcm/verification/
   from here, get the MITgcm_contrib/gael/verification/setup_these_exps.csh
   c-shell setup script e.g. by typing
      cvs co MITgcm_contrib/gael/verification/setup_these_exps.csh
      mv MITgcm_contrib/gael/verification/setup_these_exps.csh .
   Unless you already had something in MITgcm_contrib you may want 
   to remove that directory. Hereafter we wont need it anymore.
2) execute the setup script by typing
      source ./setup_these_exps.csh
   A pre-requisite is that you are logged in to the MITgcm 
   cvs server. If you completed step1, you indeed already are.
   If otherwise, see http://mitgcm.org/public/source_code.html
3) step2 creates a directory global_oce_tmp_download that 
   contains the experiments directories. Move them (incl. 
   global_oce_input_fields) to MITgcm/verification and cd to 
   that location. Once you have done this succesfully you may want 
   to remove global_oce_tmp_download. We wont need it anymore. 
4) exectute MITgcm with testreport. Two examples from one machine.
   To run the cs32 test on one cpu :
       ./testreport -t global_oce_cs32
   And to run the llc90 test on 12 cpus, using mpi
      ./testreport -match 6 -of=../tools/build_options/linux_amd64_gfortran -MPI 12 -command 'mpirun -np TR_NPROC ./mitgcmuv' -t global_oce_llc90
   The optfile may be swaped for one that better suits your machine.
5) for llc90 experiment testreport should show something like
    Y Y Y Y> 6<16 16 12 12 16 16 13 11 12 11 11 11 12 13 10 11  .  . pass  global_oce_llc90
    Y Y Y N .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..  .  . N/O   global_oce_llc90.core2
    Y Y Y N .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..  .  . N/O   global_oce_llc90.ecco_v4
    Y Y Y N .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..  .  . N/O   global_oce_llc90.ecmwf
   implying that the main experiment ran as expected in global_oce_llc90/run. In contrast
   the sub-experiments, by default, fail by omission of surface forcing fields. This 
   omission saves disk space and download time. In case you want to run the sub-experiments, 
   you will need to obtain additional inputs. Contact us about this if applies.

-----------------------------------------------------------------------
B) in case you want to change stuff on your end, or for troubleshooting
-----------------------------------------------------------------------

0) to run the core2, ecmwf, and ecco_v4 subexperiments you will need 
   extra stuff in global_oce_input_fields. Contact us if need be.
   As a side note, for the verification experiment purpose, you 
   do not want to link the large ecco data sets (RADS etc).

1) In linking the experiments to one another we rely on 'build/genmake_local' and 
'input*/prepare_run' which may be worth a special mention, at least to new MITgcm users.

  1.1) most importantly : if you remove these files, the exps wont run or even compile.
  1.2) build/genmake_local specifies the use of xmakedepend (since the default 
       cant handle so many files) and in global_oce_cs32 it points to 
       "../../global_oce_llc90/code/" If you move global_oce_llc90 away from 
       global_oce_cs32 you will need to edit that path in genmake_local.
  1.3) in analogy input*/prepare_run are a set of instructions that "testreport"
       will execute before running MITgcm, to link all of the proper inputs. 
       And again the experiments form a self-consistent group, such that
       e.g. global_oce_cs32 will get shared files from global_oce_llc90. If you move
       the directories appart, you will need to edit the paths in input*/prepare_run
  1.4) the logic we followed in linking exps to one another :
           - forward subexperiments : get local namelists then run input/prepare_run
           - adjoint subexperiments : get input_ad.x/namelists then run corresponding forward 
           subexperiment input.x/prepare_run (that itself ultimately runs input/prepare_run)

2) In a couple .h files (that you find in the build directory after compiling)
   small size parameters are used as a default (to save memory of course)
   and they can become limiting in certain cases :
   - you may want to integrate the model beyond a few time steps. You will need to 
     edit ecco_cost.h, increase nchklev_1, nchklev_2, nchklev_3 and recompile.
   - you may want to use pkg/profiles (i.e. process insitu data via data.profiles). 
     You will need to edit profiles.h to increase NOBSGLOB, and recompile.

3) To run the adjoint subexperiments you need the taf/tamc software/license.


---------------------------------------------------------------
Cheers,
Gael
---------------------------------------------------------------