ecearth3/sources/tm5mp/proj/ecearth/README

This directory contains the files for running TM5-MP coupled to EC-Earth 3. The standard
package for EC-Earth v3 consists of:

 - meteo.F90        : Has specific order of met fields' setup to match EC-Earth
                       order of received fields. And no check_pressure done in
                       meteo_setup_mass, because of the artificial lag b/w TM
                       and PRISM.

 - prism_putget.F90 : interface to push all required fields to OASIS3/prism
                       (a/k/a 'put'). 'Get' is dummy for now.

 - tm5_prism.F90    : general prism-related routines (read specific rc keys, 
                       prism grid and partition, remapping of spectral fields)

 - tmm_mf_prism.F90 : Met Field object and its methods to fill it (readrecord)


To include the feedback of aerosol optical properties from TM5 to IFS, the cpp
flag "with_ecearth_optics" must be used in the rc-file and the following file
is added (automatically done in tm5-expert.rc) to the sources:

 - ecearth_optics.F90

Note that "prism_putget.F90, tm5.F90, and initexit.F90" (the last two in the
TM5/base/) also includes parts related to aerosol optics (check for
"with_ecearth_optics").

Now, the "with_ecearth_optics" flag is on by default if not running the CO2-only
config. See <EC-Earth top dir>/sources/config-build.xml of ECE-3.2 for the CO2
flag, and <EC-Earth top dir>/sources/tm5mp/rc/main-config-ecearth3.rc.tmpl for
the setting of the flag.

merging info ECE3MCT
--------------------

erepo=https://svn.ec-earth.org/ecearth3

#parent branch
export pb3='https://svn.ec-earth.org/ecearth3/branches/development/2014/r1225-cplng-mct'

cd ECEARTH-3 ; or whatever is the directory name you used at checkout

svn mergeinfo ${pb3}
svn mergeinfo ${pb3} --show-revs eligible 

svn merge ${pb3} --dry-run
svn merge ${pb3}


--------------------------------------------------------------
TM5-MP 1.0 -- ECEARTH v3
--------------------------------------------------------------

=== compilation

    cd ${ECEARTH}/sources
    
    ec-conf -p <your-platform> config-build.xml

    cd TM5

    setup_tm5 [-c|--clean] [-n|--new] [-v|--verbose] [-j N | --jobs=N] ecconfig-ecearth3.rc

              --new : means realclean
              --jobs=N : N processes to compile (make), default value is 8

              by default, setup_tm5 gathers source code from relevant sub dirs
              (defined by "my.source.dirs" key) into ${my.project.dir}/build,
              then compiles in the later

              compilation log : setup_tm5.comp.log

    NOTE:
    - IFS nlevels is hardcoded and required for compilation.
    - unlike IFS and NEMO, TM5 resolution is set at compilation, and
      hardcoded in the template file. See below.

    - that resolution limits the number of processors that can run TM5. For
      the default 3x2 resolution, it is 45 proc in the Y direction, 60 in the
      X direction. In the config-run.xml file, increase NUMPROC_Y as much as
      you can first leaving NUMPROC_X to 1, and then you may try NUMPROC_X to
      2 or 3 (the performance of the model quickly deteriorates when NUMPROC_X
      increases).

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

To switch TM5 resolution from 3x2 to 6x4, you need to change the
following lines (with their 6x4 equivalent) in these 3 files (first
one for compilation):

(1) <root-distribution>/sources/TM5/rc/pycasso-config-ecearth3.rc.tmpl

my.region1 :  glb300x200

(2) <root-distribution>/runtime/ctrl/namcouple.sh

ctm_grid=CTM3
ctm_nx=120
ctm_ny=90

(3) <root-distribution>/runtime/ctrl/tm5-config-run.rc.tmpl

my.region1 :  glb300x200


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

To add grid info from TM5:

This is done in file
    <root-distribution>/sources/TM5/proj/ecearth/branches/mp-ecearth3/src/tm5_prism.F90,
    in routine TM5_Prism_Init2:

    Set write_grid=.true.
    Set correct point_name for region_glb (comment code for region_sfc
    and/or spectral grid if their gridinfo is already available)  





=== setup

** directories
Within EC-Earth, restart.read.dir must be the same as restart.write.dir.
Following IFS and NEMO, we use the rundir. If first chunk starts from a
restart, then you must ensure that it is present. This is done in the script now.

TM5 hackers: If restart.*.dir is not the rundir, you must create that
directory if needed. This is not done in the script.

Other directories that TM5 usually creates and that may need to be created
differently within EC-Earth: output.dir, timing.output.subdir,
settings.output.subdir, and tmm.output.

Like for restart dir, we default to rundir for now, and deals with any pre/post
processing in the script.


** run config
TM5 does not use namelist, but instead rely on a rc file argument. This rcfile
is obtained by calling:

        setuptm5 --no-compile                 \
                 --time-start=${TIME_START}   \
                 --time-final=${TIME_FINAL}   \
                 --istart=${ISTART}           \
                 RAW_RCFILE

This call creates a runtime rc file argument in the ECEARTH_RUNDIR, by:
    - expanding env variable
    - unraveling the various included rc files
    - evaluate python snippets
    - update keys with command line options (basically those that changes with each leg)

(It will also put an unneeded submit_tm5 script in the rundir. Script must
delete it for sake of completion)

We could skip the call to setup_tm5, but that would require quite a bit of
editing, and lost of flexibility, since many keys would be harcoded. We want
to keep a flexible setup, to be able to drive TM5 without chemistry but with
inactive tracers for example.

The input RAW_RCFILE is based on a template. To set the key (those that remain
the same with every leg) in the template, there is three possibilities:

(1) use ec-conf: config-run.xml must include a translation to set the
    leg-independent keys
(2) use shell variables, which must be exported before, and can be set from
    the xml tags and/or with the config keys at the top of the templates scripts 
(3) or a mixture of both

Option (3) is currently used.