--- MITgcm/doc/tag-index	2011/10/03 12:48:20	1.1509
+++ MITgcm/doc/tag-index	2011/12/21 12:59:51	1.1556
@@ -1,9 +1,276 @@
-$Header: /home/ubuntu/mnt/e9_copy/MITgcm/doc/tag-index,v 1.1509 2011/10/03 12:48:20 jmc Exp $
+$Header: /home/ubuntu/mnt/e9_copy/MITgcm/doc/tag-index,v 1.1556 2011/12/21 12:59:51 mlosch Exp $
 $Name:  $
 
     Notes on tags used in MITgcmUV
     ==============================
 
+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, 
+   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: 
+  - 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 
+    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
+    of the calling routine dynsolver, so that B and C-grid code look a
+    little more alike.
+  - fix index bugs in ostres.F (B-grid code)
+o pkg/seaice/seaice_ocean_budget.F: change (unused) code to make it look better
+o pkg/seaice/seaice_readparms.F: make ocean_emissivity*stefanBoltzmann the
+  default for SEAICE_emissivity, if useEXF; requires setting a wrong
+  parameter value in global_ocean.cs32x15/input.seaice/data.seaice for
+  backward compatiblity
+o model/src: use sigmaR in calc_ivdc
+
+checkpoint63g (2011/12/16)
+o pkg/seaice/seaice_growth.F:
+  fix heat conservation of the coupled ocean-seaice system.
+  when SEAICE_HEAT_CONSERV_FIX is defined, the mismatch of
+  solid vs liquid water treatment is resolved via QNET.
+o pkg/seaice/seaice_growth.F:
+  add missing term for sublimation in saltFlux, which was breaking conservation.
+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 
+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.
+o pkg/obcs:
+  modify Stevens boundary conditions so that S/R obcs_calc_stevens computes
+  tendency for temperature and salinity that is then applied to update
+  theta and salt in S/R obcs_apply_ts; this requires proper masking of all
+  horizontal advection and diffusion contributions on the boundary (in
+  S/Rs gad_advection, gad_calc_rhs, gmredi_rtransport, gmredi_calc_diff), and
+  removing the mask in S/R timestep_tracer. The advantage of this approach is
+  that the updated tracer values include contributions from the surface
+  forcing and vertical diffusion.
+  This modification changes exp4.stevens because of vertical diffusion.
+o model/src:
+  change non-curvilinear grid setting to also work with exch2 + blank tiles:
+  - move delX,delY to new header file (SET_GRID.h) and adjust length to 1rst
+    face dimensions.
+  - new S/R INI_LOCAL_GRID to define model tile-local grid (using same units
+    as delX,delY) and called from S/R INI_CARTESIAN_GRID, INI_CYLINDER_GRID
+    and INI_SPHERICAL_POLAR_GRID.
+  change test-experiment global_ocean.90x40x15:
+  - split the domain in many more tiles (9x4 tiles of 10x10 each);
+  - switch to exch2 and remove 1 blank-tile (but only for MPI test).
+  - update results of both test (std & dwnslp).
+o pkg/diagnostics/diagstat_calc.F: fix problem with non-initialised halos in
+   tmp-fields for TARGET_NEC_SX at the cost of extra loops and less vectorisation
+o model/src:
+  - take sigma-coords related code out of update_etah.F into new S/R UPDATE_ETAWS
+    and fix initialisation when using sigma-coords.
+o model/src:
+ - improve Gael's changes from Jan 14, 2011 "addition of an 'update' of hfacc etc.
+   to their current value at the beginning of forward_step.F": add a new run-time
+   switch "doResetHFactors" (default=false) and use it to do (or not) the resetting.
+ - set doResetHFactors=T in the following test exp:
+    global_ocean.90x40x15/input (rStar) & input.dwnslp (linFS),
+    global_ocean.cs32x15/input.seaice (rStar), hs94.cs-32x32x5/input.impIGW (linFS)
+    and tutorial_global_oce_in_p (nonLinFS in p)
+o pkg/ecco
+  - added IES cost term
+o verification/advect_xz
+  - scale down the depth by 1/100 (from 200 km to just 2.km)
+  - add secondary test using divergent flow, r-star and implicit vertical advection.
+  - add note (check_conserve_TS.txt) and matlab script to check global
+    conservation of T & S with NonLin-FreeSurf and Adams-Bashforth.
+o pkg/rbcs:
+  - add missing relaxUFile & relaxVFile in namelist (in rbcs_readparms.F).
+o pkg/obcs (Stevens BCs):
+  - fix various problems in the phase speed computations of the Stevens
+    boundary conditions:
+    - sign error for western and southern boundaries,
+    - time tendencies were underestimated by factor of dTracerLev and some just
+      zero (for multidim advection schemes) -> now estimate time tendencies
+      from difference between previous (n) time level and the one before (n-1);
+      this requires storing a field per tracer per boundary, also in the pickup
+      files.
+    - replace deltaTmom in cflMer/Zon computation with dTracerLev
+    - set default phase velocity to cflMer/Zon
+  - update verification experiment exp4.stevens
+o pkg/generic_advdiff (implicit_r):
+  - fix implicit vertical advection conservation with AB and/or NonLin-FreeSurf
+    (remove Tr*d/dz(w) in gad_implicit_r.F and add it in gad_calc_rhs.F);
+  - fix implicit vertical diffusion or advection with NonLin FreeSurf
+    (was using current recip_hFacC instead of future recip_hFacC): set future
+    recip_hFac in thermodynamics.F and pass & use it in all vertical implicit
+    solver S/R ;
+  - fill diagnostics of vertical advective fluxes (computed from tendency)
+    when using implicit vert. advection;
+  - update output of exp that uses NonLin-FreeSurf & implicit vertical diffusion:
+     global_ocean.90x40x15 (fwd+AD), global_ocean.cs32x15 (4 fwd +4 AD),
+     tutorial_global_oce_in_p (fwd), tutorial_tracer_adjsens (AD)
+     and cpl_aim+ocn (used in ocean); to be fixed: bottom_ctrl_5x5.
+o pkg/diagnostics:
+  - add diags for T & S tendency which goes through Adams-Bashforth.
+
+checkpoint63f (2011/11/30)
+o pkg/obcs/obcs_calc_stevens.F:
+  - join some loops to reduce number of if-statements
+  - fix a bug in code for northern and southern boundaries.
+o pkg/seaice/seaice_init_varia.F
+  - undo resetting UVM=0 that has slipped in unnoticed in r1.49 and
+    caused zero ice-velocities for the B-grid code
+o pkg/seaice/seaice_init_fixed.F
+  - fix a bug in the initialisation of the second metric terms
+    k2AtC and k2AtZ: k2AtC was set to the value of k2AtZ and k2AtZ was 0.
+  - this affects all seaice configurations with useCurviLinearGrid = .true.
+    and SEAICEuseDynamics = .true. (default) and SEAICEuseMetricTerms
+    = .true. (default)
+  - the only verification experiment affected is global_ocean.cs32x15:
+    icedyn, seaice, and seaice_dynmix (AD)
+o pkg/thsice/thsice_diagnostics_state.F
+  - only for TARGET_NEC_SX: initialise all of tmpFld, so that overlap does
+    not contain garbage that can lead to surprises in diagstats_calc.F
+o model/src:
+  - move bi,bj loops inside INTEGR_CONTINUITY ;
+  - call INTEGR_CONTINUITY directly from forward_step.F
+    (previously called from momentum_correction_step.F)
+  - call UPDATE_ETAH from integr_continuity.F and update initialise_varia.F,
+    forward_step.F and pkg/ecco/the_main_loop.F
+o model/src/do_oceanic_phys.F:
+  - reset addMass to zero only if useICEFRONT ;
+  - separated k-loop for rhoInSitu calculation ;
+  - add 2 diagnostics for wVel*delta^k(Rho) at constant pressure (= WdRHO_P)
+    and at constant T,S (= WdRHOdP);
+  NOTE: change diagnostics WRHOMASS : this is now simply the Vertical transport
+    of In-Situ Density (Anomaly) (=wVel*rho^bar-k) (previously was Vertical
+    transport of locally-referenced potential density);
+    to recover old diag: (WRHOMASS)_old = (WRHOMASS)_new -1/2 * (WdRHOdP)
+o gluemnc:
+  - replace ncrcat with ncks when adding variables to *.glob.nc
+  - change the way variables without record dimensions are handled so that
+    files that have variables with and without record variables can be glued:
+    add a record dimension with a new unique name to be able to differentiate
+    between variable with and without a-prior record dimensions. Remove
+    this record dimension before adding the variable to the *.glob.nc file.
+    This procedure automatically works also for grid.*.nc files that do not
+    have any record dimension.
+o verification/cpl_aim+ocn:
+  - generate new reference output on baudelaire (gfortran, mpich2) (previously
+    from old aces-grid cluster, ao + ifort) and update 'run_cpl_test' script.
+o pkg/obcs/obcs_calc_stevens.F:
+  - add code for northern and southern boundaries.
+  - reorder some loops to save some operations and so that drFBar can be scalar
+o model/src:
+  - re-arrange extrapolation calculation in Adams-Bashforth S/R (affects machine
+    truncation) and add diagnostics for Adams-Bashforth tendency increment.
+  - update test-exp. AD output:
+    1D_ocean_ice_column, bottom_ctrl_5x5, lab_sea.noseaicedyn, obcs_ctrl;
+  and FWD output: exp4 (x3), fizhi-cs-32x32x40, fizhi-cs-aqualev20,
+    front_relax (x3), global_ocean.90x40x15 (x2), global_ocean.cs32x15 (x5),
+    global_ocean_ebm, ideal_2D_oce, internal_wave, isomip (x3), lab_sea (x4),
+    matrix_example, MLAdjust (x5), natl_box (x2), tutorial_advection_in_gyre,
+    tutorial_global_oce_in_p, tutorial_global_oce_latlon and
+    tutorial_plume_on_slope.
+o pkg/diagnostics/diagstats_calc.F: add special code for TARGET_NEC_SX
+  that vectorises. This code uses 3 extra 2D fields, F90 array assignments
+  and F90 intrinsic routines SUM, MINVAL, MAXVAL, but since TARGET_NEC_SX
+  does not even come with an F77 compiler anymore, this should not be
+  a limitation
+
+checkpoint63e (2011/11/06)
+o pkg/seaice adjoint of LSR:
+  - substantially rework STORE dirs.
+  - add new flag SEAICE_LSR_ADJOINT_ITER and parameter SOLV_MAX_FIXED
+    this flag will do SOLV_MAX_ITERS but only store SOLV_MAX_FIXED fields
+    and only perform SOLV_MAX_FIXED adjoint iters.
+    If flag SEAICE_LSR_ADJOINT_ITER is undef-ined, the store in the iteration
+    always goes to same record, meaning that the last forward field will be
+    the one used in the adjoint - an approximation.
+  - now produces non-zero LSR-related gradients, and acceptable gradients for
+    An's zonal (x-z) test case (to be checked in)
+  - lab_sea: produces acceptable gradients for lab_sea with forward/backward LSR
+    (but these are screwed up by the thermodynamics in the first place);
+    reduce from 4 to 3 timesteps to avoid t.d. issue as temporary solution;
+    output_adm.txt also reflects changes to seaice_lsr
+  - global_ocean.cs32x15:
+    * the "default" input_ad.seaice has been re-defined to always exclude dynamics
+      (output_adm.seaice.txt was updated)
+    * new input_ad.seaice_dynmix tests a forward LSR / backward free-drift
+      (output_adm.seaice_dynmix.txt)
+o test-exp. exp4+stevens:
+  - switch off pTracers and nonHydrostatic (restart problems with NH); update output
+o pkg/seaice (lsr solver):
+  - put coriolis term into FORCEX,Y (as in seaice_evp.F; previously in rhsU,V only);
+    update output (change truncation) of FWD test exp lab_sea & global_ocean.cs32x15
+  - fix SEAICEuseFREEDRIFT for new OBCS version (ndef OBCS_UVICE_OLD)
+  - new parameter "LSR_mixIniGuess" allows (if=2,4) to mix free-drift solution
+    into initial guess for linearised solver; use weight ~ (1/err)^2,4.
+  - compute (with new S/R) and print initial (+ free-driff sol. if available)
+    and final residual of linearised system.
+o pkg/pp81: add diagnostics for vertical eddy viscosity and diffusivity
+  (requires new subroutines pp81_init_fixed.F/pp81_diagnostics_init.F)
+o pkg/obcs: Stevens BCs (still only for east and west)
+  - fix Stevens BCs by using intermediate velocities of previous
+    time step as "baroclinic" contribution rather velocity of one grid cell
+    inside the boundaries; more consistent but makes the entire treatment
+    more complicated, requires new pickup files and two new S/Rs:
+    obcs_copy_uv_n and obcs_save_uv_n
+    keep old version with flag OBCS_STEVENS_USE_INTERIOR_VELOCITY
+    (undefined by default)
+  - silently move computation of some grid factors into separate loops to
+    save some recomputations
+  - add a hack for non-linear free surface
+  - add a verification experiment to exp4 that tests this code
+o make gluemnc/xplodemnc work with (moron) non-GNU shell tools
+
+checkpoint63d (2011/10/25)
+o pkg/obcs + seaice-dynamics:
+  - new implementation calls OBCS_APPLY_UVICE (in seaice_dynsolver.F) before
+    solving for uIce,vIce and prevent SEAICE_LSR or SEAICE_EVP to modify OB
+    values (consistent with an implicit method).
+  - add option OBCS_UVICE_OLD (in OBCS_OPTIONS.h, defined by default) to
+    return to older implementation (same results as before); note that none of
+    the "experimental" OBCS_SEAICE options are implemented in the new version.
+  - switch test exp. seaice_obcs to use new version (update output).
+o pkg/seaice:
+  - add few stop (B-grid & CS-exch, B-grid & obcs, AUTODIFF & SEAICE_maskRHS)
+  - add parenthesis in Water-Ice drag calculations (evp & lsr);
+  - in seaice_lsr.F, simplify and fix AA3 setting in case sNx or sNy=1;
+    and fix case SEAICE_waterDrag=0 (but unstable if no or little seaice)
+  - update output of test exp lab_sea that uses evp or lsr (fwd+ad)
+    and global_ocean.cs32x15 (icedyn & seaice fwd+ad).
+o pkg/layers:
+  - Include potential density as new coordinate (Thanks to David Munday)
+o pkg/dic:
+  - Remove subroutine CALC_PCO2_APPROX_CO3 from carbon_chem.F and add
+    carbonate computation/output to CALC_PCO2_APPROX
+o pkg/generic_advdiff
+  - make TAF generate code that vectorizes:
+    gad_dst3fl_adv_*.F, gad_u3c4_impl_r.F
+o model/src:
+  - improve vectorization also for adjoint code of
+    solve_tridiagonal and solve_pentadiagonal. As this requires up to
+    5 new 3D-fields, this code is only turned on for the combination of
+    ALLOW_AUTODIFF_TAMC and TARGET_NEC_SX. Also remove error message
+    for singular matrix check (only for TARGET_NEC_SX).
+  - remove hard-wiring of CPP-flag ALLOW_SOLVERS_KLOOPINSIDE to
+    ALLOW_AUTODIFF. This flag now needs to be set outside of
+    solve_tri/pentadiagonal.F
+o pkg/exf:
+  - fix previous modif in exf_readparms.F (revision 1.66: treatment of
+    optional namelist EXF_NML_OBCS).
+  - add many debug-print (to trace down where pkg/cal error msg comes from)
+o pkg/mom_vecinv/mom_vi_hdissip.F
+  - rearrange loops so that vectorization is improved and in particular
+    the adjoint routine vectorizes. The code is a little longer now, but I
+    think easier to read.
+    Note: CPP-flag MOM_VI_ORIGINAL_VISCA4 is not tested.
+o pkg/seaice:
+  - allow to specify initial seaice velocity from files (uIceFile,vIceFile)
 o pkg/exch2:
   - alternative code (without tile x tile matrix) for cumulated (global) sum;
     used as default; keep using matrix version in adjustment.cs-32x32x1.