MITgcm/manual/manual_todo.txt

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)


o HTML, scripts and front content

  - pick a URL
    TBD

  - mitgcm.org very front page.
    o too many clicks to get to model manual.
      make doc link go to mitgcm.org/r2_web_testing/latest
      and add "HowTo" reference etc... to /latest page 

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

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

    o mitgcm.org (front content) [DONE]
      Get Code (where does this go to?)
      get rid of * CVS current bullet
      make HTML-enabled CVS code browser leap to MITgcm/MITgcm

    o authors
      John, Alistair, Jean-Michel, Patrick, Andrea, Steph, Helen,
      Martin, Baylor, Dimitris, David, Ed, Mick, Chris, Constantinos,
      Gael - others?

    o words on http://mitgcm.org/r2_web_testing/latest
      change to 
       "access on-line Auser manual/A and Atable of contents/A
        and browse the Aoverview section/A"

    o finite-volume doesn't leap to FV figure

    o have another go at pnmcrop et al.

    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

          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)
- 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

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


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)

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

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

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)
- Eq.Num missing (has been fixed since)
- u* is stored in gU (and not in gUnm1)
- Phi_nh in NH_VARS.h
- 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) 

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)

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.
- curvilinear: 
  to add: mention the angle of the grid direction relative to 
  Eastward, Northward direction.
  + mention horizGridFile= in file "data" (PARM04)
- add cylindrical 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)

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

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:
 Appendix: non-dimensional Equations on Spherical-Polar grid.)

JM


>>>> From Andrea

Chapter 3
--------

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

divide chapter 3 more clearly into 2 sections?
   (ie, 3.1-3.6 are more informational, 3.8- 3.18 are examples, and
    then 3.19 and 3.20 are informational again - rearrange subsections?)

3.1 - don't need a link to the outside of the document (remove it)
    - link to htdig is broken

3.2.1 - link at bottom to source code points to section 3.2.1
   (ie, to itself) - link should point to cvs code archive

3.2.2.1  - ('upgrading from an earlier version') belongs under
      the cvs part, ie, should be 3.2.1.1

3.3 - remove reference to 'diags' section under MITgcm
    - remove reference to 'exe' and 'bin' sections also
      (remove the .cvsignore file under these directories in cvs)
    - add a 'jobs' section, and a description as examples of run scripts
    - add 'lsopt', 'optim' and 'tutorial examples' with brief descriptions
    - under 'tools' add a reference to 'build_options'. refer to the 'optfiles'
    - under 'tools' the adjoint points to section 5 - this is now section 8
      (but should be a floating reference)
    - under 'utils' add a reference to exch2 - stuff for different resolutions
    - the description of the pkg section refers directly to
      section 3. should be section 6 (actually should be a floating reference)

3.4 - refer to sections 3.8 - 3.18 (now says 3.8 - 3.10)
3.4.1 - links to the following experiments don't exist or are broken:
          exp2 - should link to section 3.9
          hs94.cs-32x32x5 - link to section 3.12
          add 'convection' to the list, link to section 3.13
          add 'plume on slope` to the list, link to section 3.14
          add '??' link to section 3.15
          add 'dic_example on slope` to the list, link to section 3.16
          add '??' link to section 3.17
          add 'offline' and link to section 3.18
          clean up others and make links where they are needed
3.4.2 - text suggests to see section 2 for details about what is in the 'code'
        and 'input' directories - should refer to the examples in this section
      - add 'build' bullet - this is where the model is compiled and exectuable lives

3.5 - add some little text when talking about 'optfiles' to refer to the tools/build_options
      as the place where they live (add a link?)

3.6.1 - Add some general 'approach' text - ie, output is controlled either by the
        'data' file in the input directory or by the data.[pkg name] file for any
        package running. And there is some default behavior when the 'state' dumps
        are written.
3.6.1.2 - needs to be moved to inside section 3.6.2

3.7 - this section is superfluous - remove it -OR- put the tutorial sections (3.8-3.18)
      underneath this one and leave the text for 3.7 in place

All the 'overview' sections need some reference to the name of the experiment in
the verification directory

3.10 - in title, 4 degrees - degree symbol is a subscript, not a superscript
     - is this experiment in the list from section 3.4???
3.10.3.1 - refers to figures and equations, links are broken

3.11.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.12.4.1 - line 34 - link to equation is broken
         - lines 60,61 - 1st (take out the 'r' in the superscript)

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

3.15.1 - reference to 'fourth experiment' should be removed

3.16.4 - strange formatting, presence of '>' symbols - remove them

3.17.3 - unknown verification directory pointed to - also: no link from list in sec 3.4
3.17.3.1 - nothing filled in under file input/data - needs description

3.18.2 - point to section 2 for details - need hyperlink

3.19.1 - text (2 places) says that section 3.5 called for compile in 'input' directory - not true!
         section 3.5 has the 'build' directory in the example

3.20.1 - link to doc at end of section points to this section
3.20.2 - link to doc at end of section points to this section

     offline - duplicate inputs, what is it, tidy up cfc v.
               other offline. JM thinks these need tidying up.
>>>> From Ed

Here are the remaining bits for Chap 4 :

 - The grammar/flow could still use some work.  Boo was an English
   major and has experience editing/proofing technical papers.  I
   could print out a copy and ask her to read it and suggest
   improvements.

 - 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

   the master package diagram does not appear in the document

   pkg/ptracers doesn't seem to have any documentation (see packages list below)


Master list of packages (add this to beginning of chap 6)

admtlm/               - autodiff (chapter 5)
aim/                  - retired
aim_compon_interf/    - 6.6 (no content yet)
aim_ocn_coupler/      - 6.6 (no content yet)
aim_v23/              - 6.4.1 (content needs fixing - JM to do)
atm_common/           - 6.6 (no content yet)
autodiff/             - autodiff (chapter 5)
bulk_force/           - 6.3.3
cal/                  - 6.3.5
cd_code/              - chapter 2 (JM check)
cfc/                  - not sure
chronos/              - AM to check
compon_communic/      - 6.6 (no content yet)
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/                  - not sure
ecco/                 - chapter 8
embed_files/          - add something to chapter 7
ex3/                  - rename to exch3
exch2/                - 6.2.2
exf/                  - 6.3.4
fizhi/                - 6.4.3
flt/                  - in chapter 2 (JM 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 tapering
grdchk/               - grdchk (chapter 5 - check with PH)
gridalt/              - 6.2.4
kpp/                  - 6.3.2
land/                 - 6.4.2 (not connected to code - 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)
ocn_compon_interf/    - 6.6 (no content yet)
offline/              - nothing, tutorials that need work but no package   section entry
opps/                 - nothing, (martin?)
pp81/                 - nothing, (martin?)
profiles/             - GAEL
ptracers/             - JM + SD to write something
rbcs/                 - talk to steph
runclock/             - runclock
rw/                   - not sure
sbo/                  - text in sbo_descruption.tex but not linked into
                        part6
seaice/               - 6.5.2 - no equations, dimitris has promised some
shap_filt/            - chapter 2, JM to check
shelfice/             - nothing yet (martin?)
solver/               - empty
sphere/               - chapter 5 or 8 (PH to check)
therm_seaice/         - empty
thsice/               - 6.5.1 (JM to update?)
timeave/              - retiring......
zonal_filt/           - chapter 2 (JM to check)

Possible for chap 7 - Daniels grafix/ stuff

Need to get packages to contain their available diagnostics (i.e. calls to DIAGNOSTICS_ADD). these are listed in stdout when pacakages are started.

Figure 6.8 is missing

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


>>>> From Andrea

to do list for chap 7:


7.1.1 - links to section 7.1.4: the text of the first one should read "see MITgcm Kernel Diagnostics Menu"
        the links are pointing to the proper place

7.5.1 - add Graphix to the list of stuff in utils/matlab
7.5.2 - empty


andrea


9. Model uses
   Spall, Gianmaria, Legg, Dewar, Cessi, Cournelle, Follows, Adcroft, etc...
   (check in support for more names)
1	cnh	1.4	Rebuild and set to do cron build - DONE on hugo
2	cnh	1.1
3			To do
4
5			- where to put under development links?
6	cnh	1.6	JMC would like to have some mention of unfinished things (checked in
7			but not that tested e.g. AB3)
8	cnh	1.8	Add an "Under development, chapter" - shortish description of what
9			is available (last chapter)
10	cnh	1.7
11	cnh	1.9
12			o HTML, scripts and front content
13
14	cnh	1.8	- pick a URL
15			TBD
16	cnh	1.1
17			- mitgcm.org very front page.
18			o too many clicks to get to model manual.
19			make doc link go to mitgcm.org/r2_web_testing/latest
20			and add "HowTo" reference etc... to /latest page
21
22			- mitgcm.org/r2_web_testing/latest
23			o add another short-cut for quick download
24
25			o add another short-cut
26			About
27			Installation
28			Contents
29			Overview
30			Tutorials (broken)
31			Browse Code
32	cnh	1.9
33			o mitgcm.org (front content) [DONE]
34	cnh	1.1	Get Code (where does this go to?)
35	cnh	1.9	get rid of * CVS current bullet
36			make HTML-enabled CVS code browser leap to MITgcm/MITgcm
37	cnh	1.1
38			o authors
39			John, Alistair, Jean-Michel, Patrick, Andrea, Steph, Helen,
40			Martin, Baylor, Dimitris, David, Ed, Mick, Chris, Constantinos,
41			Gael - others?
42
43	cnh	1.9	o words on http://mitgcm.org/r2_web_testing/latest
44			change to
45			"access on-line Auser manual/A and Atable of contents/A
46			and browse the Aoverview section/A"
47	cnh	1.1
48			o finite-volume doesn't leap to FV figure
49
50	cnh	1.9	o have another go at pnmcrop et al.
51	cnh	1.1
52	cnh	1.9	o Need an empty package as part of distribution. Check out atm_common
53	cnh	1.1
54	cnh	1.9	o Latex
55	cnh	1.1
56	cnh	1.9	Chapter 1 - CNH
57	cnh	1.1	o single kernel diagram -
58			add reference to MWR paper
59
60			o non-hydro
61			add reference to 1995 and 1999 papers
62			pdf of 1995 paper
63
64			o FV
65			add references to 1997 papers.
66
67			o Tangent linear/adjoint add reference to
68			Heimbach papers, Marotzke, 1998 ECMWF, Bugi etc...
69
70			o platforms
71			Add reference to SC article and Scientific Programming article
72
73			o List of key papers needs to be updated and reformatted
74
75
76			o Global atmosphere: `Held Suarez',
77			update Adcroft reference
78			fix up ingrid link and frame (ingrid movies seem to be broken?)
79			Held and Suarez reference is not a link.
80
81			o Ocean Gyres
82			fix up frame link
83			make "lopped cell" a link to referenced paper.
84			add references (ask Steph/Mick)
85			online/offline paper
86
87			o Convection and mixing over topography
88			add in Legg references for convection and mixing over topography
89			and external link to CPT-GCE etc...
90
91			o Boundary forced internal waves
92			add in Legg references, obc's reference
93
94			o Parameter sensitivity
95			add in Bugnion references, Boyin references, Steph references
96
97			o State estimation
98			add in references from Patrick/Carl/Ichiro/Detlef etc...
99			update links to point to latest ECCO results
100			ECCO ingrid results have been moved
101			add forward links to "ECCO state estimation" chapter in manual
102
103			o Ocean biogeochemical cycles
104			add in references from Mick/Galen etc...
105			fix ingrid link ( date to date thing does not appear to work)
106			figure url does not have a "target=idontexist" entry
107
108			o Simulations of laboratory experiments
109			reference Wardle and Karsten papers
110			update links to include DDDAS "PIAB" page
111			cylindrical polar coordinates
112
113			o Continuos equations in ''r'' coordinates
114			add references to iso paper
115			no mention of z* and p* - forward reference to z/p in 2.
116			add that coupling also manifests through F, Q
117			add tracer transport
118
119			o Kinematic boundary conditions
120
121	cnh	1.9	o Hydrostatic, Quasi-hydrostatic, Quasi-nonhydrostatic and
122			Non-hydrostatic forms
123			need to tidy up discussion of shallow-atmosphere to be
124			consistent with the code or change code to be consistent
125			with the discussion!
126			make references hyperlinks
127			add stuff too
128			JMC remove QNH atmosphere
129			need to sort out calc_gw for deep atmosphere
130	cnh	1.1
131			o Finding the pressure field
132	cnh	1.9	make references hyperlinks
133			add forward references to manual algorithm section
134			change Elliptic to "elliptic"
135	cnh	1.1
136			o Forcing and dissipation
137	cnh	1.9	make "physics packages" refer to chapter 6.
138			should we move "external forcing" et. al to a
139			generic_forcing_driver package?
140	cnh	1.1
141			viscosities
142	cnh	1.9	update to mention Smag/Leith (Ah and A4 not constant)
143			and to have forward references to numerical section
144			tracers
145			forward references to numerical section, reddy, GM etc...
146			add references to literature
147	cnh	1.1
148			o 1.3.8 Vector invariant form
149			forward references to numerical section
150
151			o 1.3.9 Adjoint
152			add a little more here + some hyperlink to chapter 5.
153
154			o 1.4 Appendix ATMOSPHERE
155
156			add some introductory words
157
158			o 1.6 Coordinate systems
159			o only has some words on spherical polar. add some brief words
160			to cover all of
161			- cartesian
162			- spherical
163			- cylindrical
164			- general orthogonal curvilinear (vector invariant)
165
166			o Equation of state options
167			add some discussion
168			can't remember what we said we were going to do here
169			PH to do something
170
171
172			Change hydrodynamical to "dynamical"
173
174			Examples
175
176			- extra "in action" cases
177
178			o high res ocean with diurnal atmospheric state forcing
179			- links to ingrid output
180			CNH/Dimitris
181
182			o realistic FIZHI from Andrea
183			- links to ingrid output
184			from AM
185
186			o with seaice on high res cube
187			- links to ingrid output
188			CNH/Dimitris
189
190			o coupled aqua, ridge world etc...
191			- links to ingrid output
192			get stuff from Daniel
193
194			o constrained lab simulation
195			- links to ingrid output for model and lab
196			fields
197			get stuff from Sai/Andrew
198
199			o sensitivity wrt to iron
200
201			o optimization
202			- update to link to latest ECCO sites and GF
203			related material
204
205			o eddy diffusivity transport application
206
207			o Gas giant?
208
209
210	cnh	1.10	>>>> from JM
211
212
213			manual, section.2 :
214
215			In general:
216			- add more refences/links to S/R & variable name
217			- would be nice to have an active link to the fortran-file
218			for all the S/R & eq.Number in the "calling-tree" boxes
219			- search for CALC_MOM_RHS and replace it by the appropriate S/R
220			(mom_flux_form, mom_vecinv, dynamics)
221			- Problem with notation: in section.1 \vec{\bf v_h} (or \vec{\mathbf{v}}_{h})
222			was used for the horizontal velocity vector, and the 3.D vector was \vec{\mathbf{v}}
223			in section.2, \vec{\bf v} is used instead and 3.D velocity vector is
224			simply written \vec{v}.
225			I would suggest to keep the notation as they are (since they are consistent
226			inside each section) but may be to move the "notation.tex" piece
227			at the beginning of section.2 and to mention clearly the changes between
228			the 2 sections.
229
230			in content: Horizontal Dissipation: 2 times in vector-invariant section
231
232			2.1 time-stepping (part2/time_stepping.tex)
233
234			- this is not clear to me:
235
236			>> In all the above configurations it is also possible to substitute the
237			>> Adams-Bashforth with an alternative time-stepping scheme for terms
238			>> evaluated explicitly in time
239
240
241			2.2 rigid-lid:
242
243			- At some point, would be better to replace "g \eta" with "\Phi_s (cg2d_x)"
244			to stay closer to the code.
245			- mention section 2.5 implicit-Time-stepping (for vertical viscosity)
246
247			2.3 linear free-surface:
248			- add ref(+link) to S/R names:
249			- add ref(+link) to Crank-Nickelson section 2.9.1
250
251			2.4 Adams-Bashforth
252			- add stability diagrams (I have some figures that I can put)
253			- add link for var. forcing_In_AB
254			- add S/R link for S/R ADAMS_BASHFORTH2
255
256			2.5 Implicit time-stepping
257			- add name of S/R: IMPLDIFF, GAD_IMPLICIT_R, MOM_U_IMPLICIT_R
258			SOLVE_TRIDIAGONAL, SOLVE_PENTADIAGONAL
259			- update: also used for vertical advection
260
261			2.6 Synchronous time-stepping:
262			- add link for S/R THERMODYNAMICS, DYNAMCIS, SOLVE_FOR_PRESSURE,
263			MOMENTUM_CORRECTION_STEP.
264
265			2.7 Stagger baroclinic time-stepping
266			- mention AB(T,S) instead of AB(Gt,Gs) (in development) at the end
267
268			2.8 NH
269			- add link & S/R names: CALC_GW, SOLVE_FOR_PRESSURE, CG3D
270
271			2.9 Variants on Free-Surface
272			- Delta.t mis-written (eq.2.73)
273			- Eq.Num missing (has been fixed since)
274			- u* is stored in gU (and not in gUnm1)
275			- Phi_nh in NH_VARS.h
276			- add link to S/R file: SOLVE_FOR_PRESSURE, CALC_DIV_GHAT, CG2D, CG3D,
277			INI_CG2D, INI_CG3D
278
279			2.9.1 Crank-Nickelson
280			- link for variable: implicSurfPress, implicDiv2DFlow, useRealFreshWater
281
282			2.9.2 NLFS
283			- eq.Nb are wrong in html
284			- 2.9.2.4 : set of eq. appears wrong in html (but right in .dvi)
285
286			2.10.1 Notation
287			- Area definition is not really used like this
288
289			>> Ao : Area of the face orthogonal to "o" direction (o=u,v,w)
290
291			Instead, in the following section, Ac,Aw,As,A_zeta (= corresponding to
292			the model variables) are used (e.g., see section 2.10.5)
293
294			2.10.5 Horizontal grid:
295			- fig.2.8 : should use Aw,As consistently in this figure description,
296			in the figure itself, as it is in the text.
297			- curvilinear:
298			to add: mention the angle of the grid direction relative to
299			Eastward, Northward direction.
300			+ mention horizGridFile= in file "data" (PARM04)
301			- add cylindrical grid description
302			need to do a better job of relating model variables to this diagram
303
304
305			2.11 Continuity & Horizontal Pressure gradient terms
306			- mention that d.Phi/dr\|s =g if using z coordinate
307			- eq. 2.90 not clear regarding \delta_k(P-E)
308			better to add the free surface eq: d.eta/dt = w_s + P-E
309
310			2.12 Hydrostatic balance
311			- add ref to Atmosphere Appendix section (1.4) since Adcroft 2002
312			is hard to find
313			- add ref to section 1.3.4 (Hydrostatic, Quasi-Hydrostatic & Non-H)
314			and in section 1.3.4: remove the 1.3.4.3.2 subsection:
315			Quasi-nonhydrostatic Atmosphere
316
317			2.13.2 Coriolis terms
318			- note: the discretization used when useEnergyConservingCoriolis=T
319			has no hFac and no Area and is still different from the form
320			described here (with Area & hFac);
321
322			2.13.5 Lateral dissipation
323			- add description of how to use cosFactor & cosPower
324			- add the parameter correspondence: Ah <-> viscAh ; A4 <-> viscA4
325			o need to relate c11, c12 etc.. to COSFAC, USE_COS etc... flags
326			in code need to explain why cos()3/2 turns out to be
327			scaling (not cos()2)
328
329			2.13.6 Vertical dissipation
330			- mention the implicit vertical viscosity option and ref to section 2.5
331			- add the parameter correspondence: Av <-> viscAr (and might change also
332			the notation to Ar)
333
334			2.14 Vector invariant momentum equations
335			- indicate that the NH pieces (vertical momentum eq) are not yet coded
336			and that the NH code uses the flux form.
337
338			2.14.6 Horizontal dissipation -> Horizontal Divergence
339
340			2.14.7 Horizontal dissipation
341			- add the parameter correspondence: A_D,A_z <-> viscAhD,viscAhZ
342			and A_D4,A_z4 <-> viscA4D,viscA4Z
343
344			2.16 & 2.17 & 2.18 :
345			- add 1rst Order upwind option & DST-2 (Lax-Wendroff) options
346
347			2.20.2 mercator, non-dimensional Equations:
348			- does not use std notation
349			- would be better as an appendix of section 2.20:
350			(e.g changing the tile to:
351			Appendix: non-dimensional Equations on Spherical-Polar grid.)
352
353			JM
354
355	cnh	1.11
356			>>>> From Andrea
357
358			Chapter 3
359			--------
360
361			Almost all of the 'math mode' text is dropped down as subscripts
362
363			divide chapter 3 more clearly into 2 sections?
364			(ie, 3.1-3.6 are more informational, 3.8- 3.18 are examples, and
365			then 3.19 and 3.20 are informational again - rearrange subsections?)
366
367			3.1 - don't need a link to the outside of the document (remove it)
368			- link to htdig is broken
369
370			3.2.1 - link at bottom to source code points to section 3.2.1
371			(ie, to itself) - link should point to cvs code archive
372
373			3.2.2.1 - ('upgrading from an earlier version') belongs under
374			the cvs part, ie, should be 3.2.1.1
375
376			3.3 - remove reference to 'diags' section under MITgcm
377			- remove reference to 'exe' and 'bin' sections also
378			(remove the .cvsignore file under these directories in cvs)
379			- add a 'jobs' section, and a description as examples of run scripts
380			- add 'lsopt', 'optim' and 'tutorial examples' with brief descriptions
381			- under 'tools' add a reference to 'build_options'. refer to the 'optfiles'
382			- under 'tools' the adjoint points to section 5 - this is now section 8
383			(but should be a floating reference)
384			- under 'utils' add a reference to exch2 - stuff for different resolutions
385			- the description of the pkg section refers directly to
386			section 3. should be section 6 (actually should be a floating reference)
387
388			3.4 - refer to sections 3.8 - 3.18 (now says 3.8 - 3.10)
389			3.4.1 - links to the following experiments don't exist or are broken:
390			exp2 - should link to section 3.9
391			hs94.cs-32x32x5 - link to section 3.12
392			add 'convection' to the list, link to section 3.13
393			add 'plume on slope` to the list, link to section 3.14
394			add '??' link to section 3.15
395			add 'dic_example on slope` to the list, link to section 3.16
396			add '??' link to section 3.17
397			add 'offline' and link to section 3.18
398			clean up others and make links where they are needed
399			3.4.2 - text suggests to see section 2 for details about what is in the 'code'
400			and 'input' directories - should refer to the examples in this section
401			- add 'build' bullet - this is where the model is compiled and exectuable lives
402
403			3.5 - add some little text when talking about 'optfiles' to refer to the tools/build_options
404			as the place where they live (add a link?)
405
406			3.6.1 - Add some general 'approach' text - ie, output is controlled either by the
407			'data' file in the input directory or by the data.[pkg name] file for any
408			package running. And there is some default behavior when the 'state' dumps
409			are written.
410			3.6.1.2 - needs to be moved to inside section 3.6.2
411
412			3.7 - this section is superfluous - remove it -OR- put the tutorial sections (3.8-3.18)
413			underneath this one and leave the text for 3.7 in place
414
415			All the 'overview' sections need some reference to the name of the experiment in
416			the verification directory
417
418			3.10 - in title, 4 degrees - degree symbol is a subscript, not a superscript
419			- is this experiment in the list from section 3.4???
420			3.10.3.1 - refers to figures and equations, links are broken
421
422			3.11.3.2 - line 43: link to equation is broken
423			- line 51-53: link to equation is broken
424			- there is some mess of text hanging around the end of this section. remove? reformat?
425
426			3.12.4.1 - line 34 - link to equation is broken
427			- lines 60,61 - 1st (take out the 'r' in the superscript)
428
429			3.13.2 - link to theta-equation is broken
430			3.13.5.4 -- ALL of the bold links to variable names are broken
431			line 34: link to equation is broken
432
433			3.15.1 - reference to 'fourth experiment' should be removed
434
435			3.16.4 - strange formatting, presence of '>' symbols - remove them
436
437			3.17.3 - unknown verification directory pointed to - also: no link from list in sec 3.4
438			3.17.3.1 - nothing filled in under file input/data - needs description
439
440			3.18.2 - point to section 2 for details - need hyperlink
441
442			3.19.1 - text (2 places) says that section 3.5 called for compile in 'input' directory - not true!
443			section 3.5 has the 'build' directory in the example
444
445			3.20.1 - link to doc at end of section points to this section
446			3.20.2 - link to doc at end of section points to this section
447
448			offline - duplicate inputs, what is it, tidy up cfc v.
449			other offline. JM thinks these need tidying up.
450	cnh	1.10	>>>> From Ed
451
452			Here are the remaining bits for Chap 4 :
453
454			- The grammar/flow could still use some work. Boo was an English
455			major and has experience editing/proofing technical papers. I
456			could print out a copy and ask her to read it and suggest
457			improvements.
458
459			- missing references (if you point me towards URLs, I'll add them
460			to the bibliography):
461			\ref{ref hoe and hill, ecmwf}
462			\ref{magicgarden}
463			\ref{IBMLAPI}
464			\ref{Memorychannel}
465			\ref{hoe-hill:99}
466
467			- There are a few empty sub-sections at the end of Chap 4 that
468			should either be commented out or fleshed out.
469
470			and thats about it for Chap 4.
471
472
473			Add more to quick links on front page
474
475			Chapter 6
476
477			the master package diagram does not appear in the document
478
479			pkg/ptracers doesn't seem to have any documentation (see packages list below)
480
481
482			Master list of packages (add this to beginning of chap 6)
483	cnh	1.1
484			admtlm/ - autodiff (chapter 5)
485	cnh	1.10	aim/ - retired
486	cnh	1.1	aim_compon_interf/ - 6.6 (no content yet)
487			aim_ocn_coupler/ - 6.6 (no content yet)
488	cnh	1.10	aim_v23/ - 6.4.1 (content needs fixing - JM to do)
489	cnh	1.1	atm_common/ - 6.6 (no content yet)
490			autodiff/ - autodiff (chapter 5)
491			bulk_force/ - 6.3.3
492			cal/ - 6.3.5
493			cd_code/ - chapter 2 (JM check)
494			cfc/ - not sure
495			chronos/ - AM to check
496			compon_communic/ - 6.6 (no content yet)
497			cost/ - not sure, check with PH
498			ctrl/ - not sure, check with PH
499			debug/ - JM may do something in chapter 7 (utilities)
500			diagnostics/ - 7.1
501			dic/ - 6.7.2
502			ebm/ - not sure
503			ecco/ - chapter 8
504			embed_files/ - add something to chapter 7
505			ex3/ - rename to exch3
506			exch2/ - 6.2.2
507			exf/ - 6.3.4
508			fizhi/ - 6.4.3
509			flt/ - in chapter 2 (JM check)
510			gchem/ - 6.7.1
511			generic_advdiff/ - in chapter 2 (JM check)
512			ggl90/ - nothing, (Martin?)
513			gmredi/ - in chapter 2 (JM check). also need
514			Ferrari & Mc tapering
515			grdchk/ - grdchk (chapter 5 - check with PH)
516			gridalt/ - 6.2.4
517			kpp/ - 6.3.2
518			land/ - 6.4.2 (not connected to code - JM to fix)
519			matrix/ - Samar
520			mdsio/ - 7.3.1
521			mnc/ - 7.2.1
522			mom_common/ - in chapter 2 (JM check)
523			mom_fluxform/ - in chapter 2 (JM check)
524			mom_vecinv/ - in chapter 2 (JM check)
525			monitor/ - 7.4
526			my82/ - nothing, (martin?)
527			obcs/ - 6.3 (needs a check)
528			ocn_compon_interf/ - 6.6 (no content yet)
529			offline/ - nothing, tutorials that need work but no package section entry
530			opps/ - nothing, (martin?)
531			pp81/ - nothing, (martin?)
532			profiles/ - GAEL
533			ptracers/ - JM + SD to write something
534			rbcs/ - talk to steph
535			runclock/ - runclock
536			rw/ - not sure
537			sbo/ - text in sbo_descruption.tex but not linked into
538			part6
539			seaice/ - 6.5.2 - no equations, dimitris has promised some
540			shap_filt/ - chapter 2, JM to check
541			shelfice/ - nothing yet (martin?)
542			solver/ - empty
543			sphere/ - chapter 5 or 8 (PH to check)
544			therm_seaice/ - empty
545			thsice/ - 6.5.1 (JM to update?)
546			timeave/ - retiring......
547			zonal_filt/ - chapter 2 (JM to check)
548
549			Possible for chap 7 - Daniels grafix/ stuff
550
551			Need to get packages to contain their available diagnostics (i.e. calls to DIAGNOSTICS_ADD). these are listed in stdout when pacakages are started.
552
553			Figure 6.8 is missing
554
555	cnh	1.10	6.3.1.7 Tapering: Large, Danabasoglu and Doney, JPO 1997
556			Figure 6.8 is missing
557	cnh	1.9
558	cnh	1.1
559			>>>> From Andrea
560
561			to do list for chap 7:
562
563
564	molod	1.2	7.1.1 - links to section 7.1.4: the text of the first one should read "see MITgcm Kernel Diagnostics Menu"
565	cnh	1.1	the links are pointing to the proper place
566
567			7.5.1 - add Graphix to the list of stuff in utils/matlab
568			7.5.2 - empty
569
570
571			andrea
572
573	cnh	1.9
574			9. Model uses
575			Spall, Gianmaria, Legg, Dewar, Cessi, Cournelle, Follows, Adcroft, etc...
576			(check in support for more names)