manual_todo.txt

Editors

 Overall       - JM, AM, PH, CNH, EH3

 Front content - EH3

 Chapter 1     - CNH

 Chapter 2     - JMC

 Chapter 3     -  AM

 Chapter 4     - CNH

 Chapter 5     -  PH

 Chapter 6     -  AM

 Chapter 7     - EH3

 Chapter 8     -  PH

 Chapter 9     - CNH (Applications)

 Chapter 10    - JMC (Under development chapter)

 Biblio        - EH3


Rebuild and set to do cron build - DONE on hugo

To do

  - where to put under development links?
    JMC would like to have some mention of unfinished things (checked in 
     but not that tested e.g. AB3)
    Add an "Under development, chapter" - shortish description of what
    is available (last chapter)

  - add in example latex for formatting author names in different pieces.
    this aknowledges peoples contributions and gives ref for who
    to talk to.

o HTML, scripts and front content

  - pick a URL:  mitgcm.org/r2  <-- EH3's preferred base URL

  - mitgcm.org/r2_web_testing/latest
    
    o --DONE--  add another short-cut for quick download

    o --DONE--  add another short-cut
                  About
                  Installation
                  Contents
                  Overview
                  Tutorials (broken)
                  Browse Code

    o --DONE--  words on http://mitgcm.org/r2_web_testing/latest change to 

    o --DONE--  finite-volume doesn't leap to FV figure

    o -- DONE ??? --  have another go at pnmcrop et al.

         I've tried making a small change in latex2html which fixes
         the oddball-lower-alignment issue that we were seeing with
         most in-line expressions (that is, math embedded in text).
         The fix results in some things being slightly raised but I
         thin this is more asthetically pleasing than being somewhat
         lowered as before. --EH3

	 To view the altered alignment, see:

            http://eddy.csail.mit.edu/r2/latest/

    o Need an empty package as part of distribution. Check out atm_common


o Latex   

    Chapter 1                 - CNH
      o single kernel diagram -
          add reference to MWR paper

      o non-hydro
         add reference to 1995 and 1999 papers
         pdf of 1995 paper

      o FV
         add references to 1997 papers.

      o Tangent linear/adjoint add reference to
        Heimbach papers, Marotzke, 1998 ECMWF, Bugi etc...

      o platforms
         Add reference to SC article and Scientific Programming article

      o List of key papers needs to be updated and reformatted

      o Global atmosphere: `Held Suarez',
        update Adcroft reference
        fix up ingrid link and frame (ingrid movies seem to be broken?)
        Held and Suarez reference is not a link.

      o Ocean Gyres
        fix up frame link
        make "lopped cell" a link to referenced paper.
        add references (ask Steph/Mick)
        online/offline paper

      o Convection and mixing over topography
        add in Legg references for convection and mixing over topography
        and external link to CPT-GCE etc...

      o Boundary forced internal waves
        add in Legg references, obc's reference

      o Parameter sensitivity
        add in Bugnion references, Boyin references, Steph references

      o State estimation
        add in references from Patrick/Carl/Ichiro/Detlef etc...
        update links to point to latest ECCO results
        ECCO ingrid results have been moved
        add forward links to "ECCO state estimation" chapter in manual

      o Ocean biogeochemical cycles
        add in references from Mick/Galen etc...
        fix ingrid link ( date to date thing does not appear to work)
        figure url does not have a "target=idontexist" entry

      o Simulations of laboratory experiments
        reference Wardle and Karsten papers
        update links to include DDDAS "PIAB" page
        cylindrical polar coordinates

      o Continuos equations in ''r'' coordinates
         add references to iso paper
         no mention of z* and p* - forward reference to z*/p* in 2.
         add that coupling also manifests through F, Q
         add tracer transport

      o Kinematic boundary conditions

      o Hydrostatic, Quasi-hydrostatic, Quasi-nonhydrostatic and 
        Non-hydrostatic forms
         need to tidy up discussion of shallow-atmosphere to be
         consistent with the code or change code to be consistent
         with the discussion!
         make references hyperlinks
         add stuff too
         JMC remove QNH atmosphere
         need to sort out calc_gw for deep atmosphere

      o Finding the pressure field
         make references hyperlinks
         add forward references to manual algorithm section
         change Elliptic to "elliptic"

      o Forcing and dissipation
         make "physics packages" refer to chapter 6.
         should we move "external forcing" et. al to a
         generic_forcing_driver package?

        viscosities
         update to mention Smag/Leith (Ah and A4 not constant)
         and to have forward references to numerical section
         tracers
         forward references to numerical section, reddy, GM etc...
         add references to literature

      o 1.3.8 Vector invariant form
        forward references to numerical section

      o 1.3.9 Adjoint
        add a little more here + some hyperlink to chapter 5.

      o 1.4 Appendix ATMOSPHERE

        add some introductory words

      o 1.6 Coordinate systems
        o only has some words on spherical polar. add some brief words
          to cover all of
          - cartesian
          - spherical
          - cylindrical
          - general orthogonal curvilinear (vector invariant)

      o Equation of state options
        add some discussion
        can't remember what we said we were going to do here
        PH to do something


    Change hydrodynamical to "dynamical"

    Examples

        - extra "in action" cases

          o high res ocean with diurnal atmospheric state forcing
            - links to ingrid output
              CNH/Dimitris

          o realistic FIZHI from Andrea
            - links to ingrid output
              from AM

          o with seaice on high res cube
            - links to ingrid output
              CNH/Dimitris

          o coupled aqua, ridge world etc...
            - links to ingrid output
              get stuff from Daniel
              Davids donut movie

          o constrained lab simulation
            - links to ingrid output for model and lab
              fields
              get stuff from Sai/Andrew

          o sensitivity wrt to iron

          o optimization
            - update to link to latest ECCO sites and GF
              related material

          o eddy diffusivity transport application

          o Gas giant?


>>>> from JM


manual, section.2 :

In general: 
- add more refences/links to S/R & variable name
- would be nice to have an active link to the fortran-file 
  for all the S/R & eq.Number in the "calling-tree" boxes
- search for CALC_MOM_RHS and replace it by the appropriate S/R
  (mom_flux_form, mom_vecinv, dynamics) <- DONE
- Problem with notation: in section.1 \vec{\bf v_h} (or \vec{\mathbf{v}}_{h})
was used for the horizontal velocity vector, and the 3.D vector was \vec{\mathbf{v}}
in section.2, \vec{\bf v} is used instead and 3.D velocity vector is 
simply written \vec{v}.
I would suggest to keep the notation as they are (since they are consistent 
inside each section) but may be to move the "notation.tex" piece
at the beginning of section.2 and to mention clearly the changes between 
the 2 sections.

in content: Horizontal Dissipation: 2 times in vector-invariant section
<- DONE

2.1 time-stepping (part2/time_stepping.tex)

- this is not clear to me:

>> In all the above configurations it is also possible to substitute the
>> Adams-Bashforth with an alternative time-stepping scheme for terms
>> evaluated explicitly in time
<- Leave it general.

 o Time-stepping outline
   - what gets called when


2.2 rigid-lid:

- At some point, would be better to replace "g \eta" with "\Phi_s (cg2d_x)"
  to stay closer to the code.
- mention section 2.5 implicit-Time-stepping (for vertical viscosity) <- DONE

2.3 linear free-surface: 
- add ref(+link) to S/R names:
- add ref(+link) to Crank-Nickelson section 2.9.1 <- DONE

2.4 Adams-Bashforth
- add stability diagrams (I have some figures that I can put) <- DONE
- add link for var. forcing_In_AB and epsil_AB <- half DONE
- add S/R link for S/R ADAMS_BASHFORTH2 <-DONE

2.5 Implicit time-stepping 
- add name of S/R: IMPLDIFF, GAD_IMPLICIT_R, MOM_U_IMPLICIT_R
	SOLVE_TRIDIAGONAL, SOLVE_PENTADIAGONAL
- update: also used for vertical advection

2.6 Synchronous time-stepping:
- add link for S/R THERMODYNAMICS, DYNAMCIS, SOLVE_FOR_PRESSURE,  
                   MOMENTUM_CORRECTION_STEP.

2.7 Stagger baroclinic time-stepping
- mention AB(T,S) instead of AB(Gt,Gs) (in development) at the end

2.8 NH
- add link & S/R names: CALC_GW, SOLVE_FOR_PRESSURE, CG3D

2.9 Variants on Free-Surface
- Delta.t mis-written (eq.2.73) <- DONE
- Eq.Num missing <- DONE
- u* is stored in gU (and not in gUnm1) <- DONE
- Phi_nh in NH_VARS.h <- DONE
- add link to S/R file: SOLVE_FOR_PRESSURE, CALC_DIV_GHAT, CG2D, CG3D, 
  INI_CG2D, INI_CG3D

2.9.1 Crank-Nickelson
- link for variable: implicSurfPress, implicDiv2DFlow, useRealFreshWater
 
2.9.2 NLFS
- eq.Nb are wrong in html
- 2.9.2.4 : set of eq. appears wrong in html (but right in .dvi) 
 <- DONE

2.10.1 Notation
- Area definition is not really used like this

>> Ao : Area of the face orthogonal to "o" direction (o=u,v,w)

  Instead, in the following section, Ac,Aw,As,A_zeta (= corresponding to 
  the model variables) are used (e.g., see section 2.10.5)
<- DONE

2.10.5 Horizontal grid:
- fig.2.8 : should use Aw,As consistently in this figure description,
  in the figure itself, as it is in the text. <- DONE
- curvilinear: 
  to add: mention the angle of the grid direction relative to 
  Eastward, Northward direction.
  + mention horizGridFile= in file "data" (PARM04)
- add cylindrical polar grid description
   need to do a better job of relating model variables to this diagram


2.11 Continuity & Horizontal Pressure gradient terms
 - mention that d.Phi/dr|s =g if using z coordinate 
 - eq. 2.90 not clear regarding \delta_k(P-E)
 better to add the free surface eq: d.eta/dt = w_s + P-E

2.12 Hydrostatic balance
 - add ref to Atmosphere Appendix section (1.4) since Adcroft 2002
   is hard to find
 - add ref to section 1.3.4 (Hydrostatic, Quasi-Hydrostatic & Non-H)
    and in section 1.3.4: remove the 1.3.4.3.2 subsection: 
                       Quasi-nonhydrostatic Atmosphere

2.13.2 Coriolis terms
 - note: the discretization used when useEnergyConservingCoriolis=T  
   has no hFac and no Area and is still different from the form 
   described here (with Area & hFac);

2.13.5 Lateral dissipation
 - add description of how to use cosFactor & cosPower
 - add the parameter correspondence: Ah <-> viscAh ; A4 <-> viscA4 
    o need to relate c11, c12 etc.. to COSFAC, USE_COS etc... flags
      in code need to explain why cos()3/2 turns out to be
      scaling (not cos()2)
 - need to reference the smag/leith section.

2.13.6 Vertical dissipation 
 - mention the implicit vertical viscosity option and ref to section 2.5
 - add the parameter correspondence: Av <-> viscAr (and might change also
   the notation to Ar)

2.14 Vector invariant momentum equations
 - indicate that the NH pieces (vertical momentum eq) are not yet coded
   and that the NH code uses the flux form.

2.14.6 Horizontal dissipation -> Horizontal Divergence

2.14.7 Horizontal dissipation
 - add the parameter correspondence: A_D,A_z <-> viscAhD,viscAhZ  
   and A_D4,A_z4 <-> viscA4D,viscA4Z 

2.16 & 2.17 & 2.18 : 
 - add 1rst Order upwind option & DST-2 (Lax-Wendroff) options
 - fix equations 2.202 & 2.203 (thanks to Martin) <- DONE

2.20.2 mercator, non-dimensional Equations:
- does not use std notation
- would be better as an appendix of section 2.20:
(e.g changing the tile to:
- talk to Baylor
 Appendix: non-dimensional Equations on Spherical-Polar grid.)
 <- No (Chris said)


Diagrams of grid locations etc.... and what variables and output files 
and/or netcdf variable names are not very easy to figure out and follow.
It would be good to redo and extend these diagrams and align with GRID.h
content.
 

JM


>>>> From Andrea

Chapter 3
--------

Almost all of the 'math mode' text is dropped down as subscripts

3.11.3.1 - refers to figures and equations, links are broken

3.12.3.2 - line 43: link to equation is broken
         - line 51-53: link to equation is broken
         - there is some mess of text hanging around the end of this section. remove? reformat?

3.13.4.1 - line 34 - link to equation is broken
         - lines 60,61 - 1st (take out the 'r' in the superscript)

3.14.2 - link to theta-equation is broken
3.14.5.4 -- ALL of the bold links to variable names are broken
            line 34: link to equation is broken

 o Update basic intro with one and four layer gyres
   - include advection options
   - conservation analysis
   - diagnostics

 o Four degree adjoint
   - both TAF and OpenAD based.

 o Coupled with biogeo setup
   - based on CCGS setup


>>>> From Ed

Here are the remaining bits for Chap 4 :

 - missing references (if you point me towards URLs, I'll add them
   to the bibliography):
     \ref{ref hoe and hill, ecmwf}
     \ref{magicgarden}
     \ref{IBMLAPI}
     \ref{Memorychannel}
     \ref{hoe-hill:99}

 - There are a few empty sub-sections at the end of Chap 4 that
   should either be commented out or fleshed out.

and thats about it for Chap 4.


Add more to quick links on front page

Chapter 6

   update organigramme
    - include rbcs
    (<- needs an update: e.g. atm2d, salt_plume, shelfice ...)

Master list of packages (add this to beginning of chap 6)
 (<- needs an update: e.g. atm2d, salt_plume, shelfice ...)

admtlm/               - autodiff (chapter 5)
aim/                  - retired
aim_compon_interf/    - 6.6 (no content yet)(Daniel + JM)
aim_ocn_coupler/      - 6.6 (no content yet)
aim_v23/              - 6.4.1 (content needs fixing - JM to do)
atm_common/           - nothing in this package (6.4.1 related)
autodiff/             - autodiff (chapter 5)
bulk_force/           - 6.3.3
cal/                  - 6.3.5
cd_code/              - chapter 2 (JM check add a reference to paper, 
                          mention parameter in data)
cfc/                  - not sure  (CNH to talk to Steph and Helen)
chronos/              - AM to check (not being used - Andrea to kill it)
compon_communic/      - 6.6 (no content yet)(Daniel + JM)
cost/                 - not sure, check with PH
ctrl/                 - not sure, check with PH
debug/                - JM may do something in chapter 7 (utilities)
diagnostics/          - 7.1
dic/                  - 6.7.2
ebm/                  - (check with PH)
ecco/                 - chapter 8
embed_files/          - add something to chapter 7
exch2/                - 6.2.2
exf/                  - 6.3.4
fizhi/                - 6.4.3
 o Including FIZHI doc
   - get things up to date
flt/                  - (PH check)
gchem/                - 6.7.1
generic_advdiff/      - in chapter 2 (JM check)
ggl90/                - nothing, (Martin?)
gmredi/               - in chapter 2 (JM check). also need
                        Ferrari & Mc transition zone stuff (Samar doing this)
                        get dfer to read this
grdchk/               - grdchk (chapter 5 - check with PH)
gridalt/              - 6.2.4
kpp/                  - 6.3.2
land/                 - 6.4.2 (not connected to code Rong's notes - JM to fix)
matrix/               - Samar
mdsio/                - 7.3.1
mnc/                  - 7.2.1
mom_common/           - in chapter 2 (JM check)
mom_fluxform/         - in chapter 2 (JM check)
mom_vecinv/           - in chapter 2 (JM check)
monitor/              - 7.4
my82/                 - nothing, (martin?)
obcs/                 - 6.3 (needs a check - ask PH to read)
ocn_compon_interf/    - 6.6 (no content yet)
offline/              - nothing, tutorials that need work but no package   section entry
                        trivial to document (CNH to do)
opps/                 - nothing, (martin?)
pp81/                 - nothing, (martin?)
profiles/             - GAEL
ptracers/             - JM + SD + Martin to write something (nothing for this
                          at the moment)
                        AM has diagnostics table for this.
rbcs/                 - CNH to talk to steph
runclock/             - runclock - CNH
rw/                   - not sure - going to stay says JMC. quick IO calls
                        JMC to write a quick note for that.
sbo/                  - text in sbo_descruption.tex but not linked into
                        part6 - CNH
seaice/               - 6.5.2 - no equations, dimitris has promised some
shap_filt/            - chapter 2, JM to check
shelfice/             - nothing yet (martin?)
solver/               - empty (go away?)
sphere/               - chapter 5 or 8 (PH to check)
therm_seaice/         - empty (go away?)
thsice/               - 6.5.1 (JM to update?)
timeave/              - retiring......
zonal_filt/           - chapter 2 (JM to check)

 o Cost function packages
   - floats, weights, profiles etc...


list an expeiment which uses package? CNH

6.3.1.7 Tapering: Large, Danabasoglu and Doney, JPO 1997 
 Figure 6.8 is missing


=====  Chapter 7  =====  [EH3 editing] :

 + JMC: please add description of:
	- diagstat
	- new temporal averaging feature

 + update the RW / MDSIO description 
   -> new meta file
   -> list all RW S/R that one should use instead of calling directly MDSIO

 + add Graphix to the list of stuff in utils/matlab (Daniel)

 + get bathymetry pre-processing stuff from Patrick and then describe it

 + add something on spgrid mesh generator
 o Grid generation
   - more explanation and some step-by-step examples
   - plotting grid examples


 + add in gmaze PV calculation scripts plus write up on how it is calculated
     http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/gmaze_pv/


andrea


9. Publications using MITgcm --> "Previous Applications of MITgcm"
   Spall, Gianmaria, Legg, Dewar, Cessi, Cournelle, Follows, Adcroft, etc...
   (check in support for more names)

10. Under development

Constantinos LCML
 o Legend/LCML examples and explanation
   - examples and explanation!



Bibliography

 tidy up from misc - .tex

Also

a link to the new manual
should appear on the front page (even if it's under construction).

updating:
http://mitgcm.org/r2_web_testing/latest/code_reference/callTree.html
which points to a 1.5 years old code. Would be good to generate a
new one, and even better, to try to keep it up-to-date.