--- MITgcm/doc/tag-index	2011/12/21 12:59:51	1.1556
+++ MITgcm/doc/tag-index	2012/02/07 19:12:06	1.1593
@@ -1,22 +1,236 @@
-$Header: /home/ubuntu/mnt/e9_copy/MITgcm/doc/tag-index,v 1.1556 2011/12/21 12:59:51 mlosch Exp $
+$Header: /home/ubuntu/mnt/e9_copy/MITgcm/doc/tag-index,v 1.1593 2012/02/07 19:12:06 gforget Exp $
 $Name:  $
 
     Notes on tags used in MITgcmUV
     ==============================
 
-o pkg/exf/exf_radiation.F: add the factor ocean_emissivity to lwdown, for 
+o pkg/seaice: turbulent flux term specification via run time params.
+  - replace CPP switches with run time switches to facilitate testing
+  - retired CPPs : MCPHEE_OCEAN_ICE_HEAT_FLUX, GRADIENT_MIXED_LAYER_TURBULENCE_FACTOR
+  - added runtime parameter : SEAICEturbFluxFormula
+  - move Mcphee constants to SEAICE_PARAMS.h
+  - seaice_readparms.F : read turbulent flux term params (SEAICEturbFluxFormula;
+   SEAICE_availHeatFrac/Frz, or SEAICE_gamma_t/_frz if apply); remove
+   seaice_summary call (moved to seaice_init_fixed)
+  - seaice_init_fixed.F : set SEAICE_availHeatFrac/Frz depending on 
+   SEAICEturbFluxFormula, and seaice_summary call (moved from seaice_readparms)
+  - seaice_summary.F : add missing report of read turbulent flux term set up (and SITRACER).
+  - seaice_check.F : check range; inform and stop if retired CPPs are used (incl. SEAICE_AGE).
+  - seaice_growth.F : unified use of SEAICE_availHeatFrac/Frz, without 
+	CPP switch, same computation as before for the different options.
+  - change results at the truncation level.
+o pkg/seaice:
+  - remove un-used parameters LAD & MAX_TICE ; add new run-time parameters:
+    useMaykutSatVapPoly (default=F), postSolvTempIter (default=2) and
+    SEAICE_wetAlbTemp (default=-1e-3). Remove option SEAICE_SOLVE4TEMP_LEGACY.
+  - update verification/*/input*/data.seaice:
+    to reproduce previous results with former #defined SEAICE_SOLVE4TEMP_LEGACY
+    code, set useMaykutSatVapPoly=T & postSolvTempIter=0 ;
+    and to reproduce previous results with former non-SOLVE4TEMP_LEGACY code,
+    set SEAICE_wetAlbTemp=0 & SEAICE_snowThick=0.
+o pkg/seaice/seaice_solve4temp.F (SOLVE4TEMP_LEGACY):
+  - remove LEGACY code for solving for tsurf (A1,A2,A3) but maintain the same
+    algorithm (same choice: useMaykutPolySatVap=T, postSolvTempIter=0);
+    difference in results only due to machine truncation.
+  - remove MAX_TICE (tsurf is always =< TMELT anyway); keep MIN_TICE if using
+    MaykutPolySatVap; keep MIN_LWDOWN.
+  - adapt SEAICE_MODIFY_GROWTH_ADJ code (untested) to non-legacy formulation.
+  - update output of verification exp. lab_sea (4 fwd: 11 cg2d digits except hb87,
+    + 3 AD: 6 digits except evp) and offline_exf_seaice.seaice (12 digits).
+o pkg/salt_plume:
+  - isolate saltPlumeFlux array exch into a specific S/R called from
+    do_oceanic_phys.F
+  - add interface to pkg/salt_plume (filling of saltPlumeFlux) in pkg/thsice.
+o verification:
+  - move untested set-up to MITgcm_contrib/verification_other.
+o pkg/seaice:
+  - retire old way of SEAICE_AGE. Now replaced with ALLOW_SITRACER.
+o pkg/seaice:
+  - seaice_solve4temp.F (keeping results unchanged):
+    * add 2 future run-time params to select which saturation vapor pressure
+      formula is used and how post-iteration fluxes are set.
+      Temporary set these 2 params according to option SOLVE4TEMP_LEGACY;
+    * New piece of code (not used) to update surf. atmos. heat flux F_ia using
+      the linearized expression to stay consistent with tsurf finding.
+  - seaice_freedrift.F avoid floating exception in sqrt(y) since y=sqrt(x*x)-x
+    can be < 0.
+o pkg/seaice/seaice_solve4temp.F (SOLVE4TEMP_LEGACY undef):
+  - remove from F_ia (and from it's derivative dFiDTs1) the contribution of
+    conductive heat flux F_c , and add it explicitly when updating tsurf as
+    solution of: Fc = Fia + d/dT(Fia - Fc) *delta.tsurf
+    so that now F_ia has a consistent meaning through the entire routine.
+    This causes differences at truncation level: update output of fwd exp.
+    global_ocean.cs32x15.seaice.
+o pkg/seaice:
+  - lots of editing/cleaning in seaice_solve4temp.F + better documentation
+    of arrays, sign/direction of fluxes; no effect on results.
+  - replace hard coded 273.16 (=previous value of celsius2K) by celsius2K
+    in seaice_budget_ocean.F & seaice_solve4temp.F (SOLVE4TEMP_LEGACY part);
+    note: this should have been done before changing celsius2K default.
+  - to keep results unchanged, add back old value of celsius2K in verification
+    exp. input*/data : lab_sea (AD), offline_exf_seaice (fwd+AD) & seaice_obcs
+  - replace hard coded seawater freezing temp in seaice_solve4temp.F (part
+    SOLVE4TEMP_LEGACY) of 271.20 (=previous value of celsius2K + default
+    value of SEAICE_freeze) by celsius2K+SEAICE_freeze so that seawater
+    freezing temp is consistent with value in seaice_growth.F ; this causes
+    differences at machine truncation level: update lab_sea AD output (3/4).
+o pkg/seaice:
+  - mask (in exf_init_fixed.F) atemp,aqh,evap,precip,runoff,lwflx,areamask
+    and climsst/sss even when using seaice (to prevent calculation that might
+    use SST on land); does not affect any verification exp.
+  - apply mask to taux,tauy (in seaice_get_dynforcing.F); update output
+    of lab_sea.fd & lab_sea.hb87 and global_ocean.cs32x15.seaice_dynmix.
+o pkg/seaice/seaice_growth.F: add mask to avoid non-zero ice thickness
+  over land (non-legacy code)
+o vectorize salt_plume package:
+  - add extra code to salt_plume_frac and salt_plume_tendency_apply_s
+  - this code computes plumebk everywhere (also over land), thus requires
+    code to avoid divisions by zero and catch the case of kLev=Nr.
+  - efficiency of salt_plume_frac is still sub-optimal
+o tools (genmake2):
+  - fix makefile NAME specification (option: -makefile NAME) by adding
+    "-f $MAKEFILE" in few places where it was missing including makedepend
+    command (contribution from Paul).
+
+checkpoint63i (2012/01/24)
+o model/src:
+  - add factorized versions of some EOS code to find_rho.F,
+    define USE_FACTORIZED_EOS to turn it on (default for TARGET_NEC_SX)
+o model/src:
+  - add celsius2K to namelist PARM01; remove unused recip_rhoNil from PARAMS.h;
+  - change default celsius2K from 273.16 to 273.15
+  - to keep results unchanged, add back old value of celsius2K in verification
+    exp. input*/data : aim.5l_cs, 1D_ocean_ice_column, lab_sea (fwd),
+     global_ocean.cs32x15(seaice) & cpl_aim+ocn(input_atm).
+o model/src: add a little initialisation trick to find_rho.F and find_alpha.F
+  to make TAF generate vectorizable code
+o pkg/seaice/seaice_evp.F: add code (copied from CICE) that avoids underflows.
+   Turn on by defining SEAICE_EVP_ELIMINATE_UNDERFLOWS. Most compilers
+   have flags that do this more efficiently.
+o pkg/diagnostics/diagstats_calc.F
+  - for TARGET_NEC_SX fix the treatment of the scaling factor tmpFac=scaleFact
+o pkg/obcs (with exch2):
+  - derive OB indices in overlap region from OB-InsideMask (in obcs_init_fixed.F)
+    and remove code (in obcs_readparms.F) which was based on EXCH of indices
+    (through buffer) and did not account for exch2 (e.g., CS-grid) topology.
+o pkg/exf and seaice exp:
+  - change offline_exf_seaice.seaicetd test exp. to use default DIFF1 value (=0)
+    so that switching off area & heff advection flags does not affect results.
+  - change default EXF_LWDOWN_WITH_EMISSIVITY to #define in EXF_OPTIONS.h
+  - keep exp. seaice_obcs & 1D_ocean_ice_column(ad) unchanged (using #undef
+    EXF_LWDOWN_WITH_EMISSIVITY) and, using pkg/exf default emissivities, update
+    results of verification experiments: 1D_ocean_ice_column(fwd),
+    global_ocean.cs32x15.seaice(fwd+ad) & seaice_dynmix(ad), lab_sea (all 8)
+    and offline_exf_seaice (all 4).
+o pkg/seaice:
+  - remove array YNEG, RIVER, TMIX (replaced by local var) from common block;
+    remove also areaNm1 & hEffNm1 when SEAICE_GROWTH_LEGACY is undef.
+  - fix bug: areaNm1 & hEffNm1 are needed in seaice_growth (SEAICE_GROWTH_LEGACY)
+    but were not filled when resp. SEAICEadvArea=F & SEAICEadvHeff=F and
+    not multi-dim advection;
+  - fix seaice_growth.F to compile with both SEAICE_GROWTH_LEGACY and
+    SHORTWAVE_HEATING #undef.
+o optim: make Makefile more robust (?)
+o pkg/obcs:
+  * fix treatment of obcs_read_pickup for TAF
+o pkg/shelfice:
+  * add missing initialisation of num_shifwflx
+  * new adjoint verification exp. for isomip
+  * change Prandtl and Schmidt numbers from generic formulations
+    (in terms of model diffus. and visc.) to separate runtime
+    parameters, with Holland and Jenkins (1999) default values.
+o pkg/exf (interpolation):
+  - extended input field (2 rows) near the N & S poles:
+    * fill in with the symetric value (when even Nb of data in longitude)
+    * add average value at the poles only for scalar quantities ; for vector
+      component interpolation, skip the averaging and keep duplicated values,
+      unless the 2 components have same location (uvInterp=T) in which case
+      interpolate the 2 components together using S/R EXF_INTERP_UV.
+  - new S/R EXF_INTERP_UV to interpolate the 2 components of a vector field
+    together: this allows to account properly for local orientation when
+    averaging at N & S pole.
+  - add CPP option EXF_USE_OLD_INTERP_POLE to recover old results regarding
+    exf-interpolation near N & S poles. Undef by default.
+  - add debug check/print on 1rst iter if debugLevel >=2.
+o pkg/exf:
+  - change masking flags definition (no longer "parameter"), put them in
+    common block and set them in S/R EXF_INIT_FIXED.
+  - change recognized masking flag from s,u,v to c,w,s since the mask
+    to use (maskC,W,S) depends on position on model grid and has little to
+    do with scalar/vector difference; fix masking if using P-coordinates.
+  - fix masking of wind-stress (was wrong if interpolated or read on A-grid)
+    and update results of exp. global_with_exf (x2).
+  - fix setting of zenith-angle table when SHORTWAVE_HEATING is undef.
+o pkg/obcs
+  - S/R obcs_calc_stevens: fix a small bug (gammat -> gammas where appropriate)
+o pkg/exf (interpolation):
+  - assume periodicity in X only if input field cover full longitude range.
+  - improve search for lat. index (supposed to be faster, in ~log2(ny) steps,
+    and should vectorise).
+  - fix input lat of the 2 added row (in case we provide N.pole data).
+
+checkpoint63h (2011/12/30)
+o pkg/seaice:
+  - change declaration of UVM from _RL to _RS in order to get B-grid
+    uIce,vIce monitor when _RS = real*4
+o pkg/offline:
+  - new S/R OFFLINE_RESET_PARMS for resetting main-model params (switch off flags);
+  - compute vertical velocity if not read from file (switch on exactConserv
+    & staggerTimeStep);
+  - fix output of ptracer monitor iter & time for default PTRACERS_monitorFreq.
+o verification:
+  - update grid-files (in tutorial_held_suarez_cs/input and fizhi-cs-32x32x40/input)
+    with grid-angle generated using "utils/matlab/cs_grid/cubeCalcAngle.m":
+    fix Pb in yG definition @ 2 missing corners (previously yG was averaged);
+  - update output of exp. global_ocean.cs32x15.viscA4 after changing
+    grid-file angles (used here for coriolis-3d);
+  - remove (or gzip) few files not needed to run fizhi-cs experiments.
+o pkg/exf (vector interpolation):
+  - rotate vector component toward local grid-axis orientation using grid-angles
+    (stored in GRID.h) instead of locally computed rotation angle; keep old code
+    available with exf option EXF_USE_OLD_VEC_ROTATION (undef by default).
+o pkg/seaice:
+  - allow to compile with exf options ALLOW_ATM_TEMP or ALLOW_DOWNWARD_RADIATION
+    undefined. Fix and remove the stop when ALLOW_RUNOFF is undefined.
+o pkg/PKG_OPTIONS.h files:
+  - move #include "CPP_OPTIONS.h" just after #include "PACKAGES_CONFIG.h",
+    outside of the #ifdef ALLOW_THISPKG / #endif block.
+  - update verification/*/code/PKG_OPTIONS.h files.
+o add a verification experiment (offline_exf_seaice/input.seaice) that test
+  the B-grid LSOR solver
+o pkg/seaice: sort out emissivity and long wave radiation step 2:
+  - add emissivity for snow and ice as new run-time parameters
+    (unfortunately) that default to the corresponding exf values; this
+    changes results in most verification experiments so that for backward
+    compatibility these parameter have to be set explicitly to inconsistent
+    values (ugly);
+  - the exf-flag EXF_LWDOWN_WITH_EMISSIVITY then gets rid off the hard-wired
+    emissivities of 0.97 associated with lwdownloc in S/R seaice_solve4temp
+    until we agree how to handle this bug properly
+o pkg/exf (interpolation):
+  - add a set of run-time param ({inputfield}_interpMethod), one for
+    each interpolated input field, to select the interpolation method
+    with a value of zero switching off the interpolation;
+  - print interpolation parameters to standard output;
+  - refine exf_check.F accordingly ; stop if USE_NO_INTERP_RUNOFF is defined
+    (to use instead runoff_interpMethod=0 in data.exf).
+  - simplify default setting of interpolation parameters (for all fields,
+    set position to match model grid cell-center position, leading to trivial
+    interpolation in case of regular Lat-Lon grid) and fix for the case of
+    non-uniform delY.
+o pkg/exf/exf_radiation.F: add the factor ocean_emissivity to lwdown, for
    within #ifdef EXF_LWDOWN_WITH_EMISSIVITY/#endif. Unless ocean_emissivity=1.
-   this factor is absolutely required, because the lw exitance (= out-going 
-   long wave radiation) is emissivity*stefanBoltzmann*T^4 + rho*lwdown, 
+   this factor is absolutely required, because the lw exitance (= out-going
+   long wave radiation) is emissivity*stefanBoltzmann*T^4 + rho*lwdown,
    where the reflectivity rho = 1-emissivity for conservation reasons. Once
    this is established, we can remove the CPP-Flag (if we want to).
-o pkg/seaice: 
+o pkg/seaice:
   - qualify a stop statement in S/R seaice_check: EXF_READ_EVAP and
     ALLOW_BULKFORMULAE are only required if SEAICE_EXTERNAL_FLUXES is defined
   - sort out emissivity and long wave radiation, step 1: make SEAICE_emissivity
     what the name implies (and not emissivity*BoltzmannConstant), this means
-    the old default value of 5.5e-8 now means 
-    5.5e-8/5.670e-8 = 0.97001763668430343479 as ocean_emissivity in 
+    the old default value of 5.5e-8 now means
+    5.5e-8/5.670e-8 = 0.97001763668430343479 as ocean_emissivity in
     S/R exf_readparms
   - FV-discretization of the B-grid LSOR solver, turn on with
     SEAICE_LSRBNEW. This new solver also involves a slight re-organization
@@ -40,8 +254,8 @@
 o pkg/seaice/seaice_model.F:
   Remove this patholigical case treatment in evolution branch,
   where it is un-necessary and breaks conservation.
-  Update global_ocean.cs32x15/results accordingly for 
-  output.seaice.txt output_adm.seaice.txt and output_adm.seaice_dynmix.txt 
+  Update global_ocean.cs32x15/results accordingly for
+  output.seaice.txt output_adm.seaice.txt and output_adm.seaice_dynmix.txt
 o model/src:
   useRealFreshWaterFlux: remove masking of EmPmP (using maskInC) in
   external_forcing_surf.F and apply mask directly in S/R SOLVE_FOR_PRESSURE.