--- manual/manual_todo.txt 2006/04/06 19:10:53 1.7 +++ manual/manual_todo.txt 2006/04/06 20:03:45 1.10 @@ -5,10 +5,14 @@ - 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" + Add an "Under development, chapter" - shortish description of what + is available (last chapter) - - pick a URL (whine whine whine whine whine whine - whine whine whine whine whine whine ...........) + +o HTML, scripts and front content + + - pick a URL + TBD - mitgcm.org very front page. o too many clicks to get to model manual. @@ -25,32 +29,31 @@ 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 Tutorials side bar link is broken - - o words - change to "access on-line Auser manual/A and Atable of contents/A - and browse the Aoverview section/A" + 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 the src and equation links don't come through to - the html when they are in figures - see chapter 2 for some - examples. - - o degree symbols keep getting "dropped down" - problem with - pnmcrop et al. + o have another go at pnmcrop et al. + o Need an empty package as part of distribution. Check out atm_common -Contents +o Latex - Intro - CNH + Chapter 1 - CNH o single kernel diagram - add reference to MWR paper @@ -115,29 +118,32 @@ 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 + 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" + 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? + 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 + 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 @@ -163,140 +169,228 @@ PH to do something - Discretization and alg - JMC+CNH + Change hydrodynamical to "dynamical" - Tutorials - AM - 3.1 "Where to find" - o link to Pelican not needed - o mailman twice (why?) - o no htdig (gone? - I liked it) + Examples - intro part - individual experiments + - extra "in action" cases - offline - duplicate inputs, what is it, tidy up cfc v. - other offline. + o high res ocean with diurnal atmospheric state forcing + - links to ingrid output + CNH/Dimitris - Software - EH to review + o realistic FIZHI from Andrea + - links to ingrid output + from AM - some to be done on resource estimates at the end - needs sorting. + o with seaice on high res cube + - links to ingrid output + CNH/Dimitris - Automatic Diff - CE + o coupled aqua, ridge world etc... + - links to ingrid output + get stuff from Daniel - Physical Packages - ??? + o constrained lab simulation + - links to ingrid output for model and lab + fields + get stuff from Sai/Andrew - Diags and tools - ??? + o sensitivity wrt to iron - Interface with ECCO - ??? + o optimization + - update to link to latest ECCO sites and GF + related material - Model uses - ??? + o eddy diffusivity transport application - Building document - ??? - via cron - tweaking latex2html etc.. + o Gas giant? - Src Code tree (rename - examples etc..) - ??? -Documentation +>>>> from JM -1. Introduction -2. Discretization and Algorithm +manual, section.2 : - 2.13.5 Lateral dissipation - 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) +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. - 2.13.6 Vertical dissipation - o update to have reference to Baylors section - reference to implicit discussion in time-stepping part of manual +in content: Horizontal Dissipation: 2 times in vector-invariant section +2.1 time-stepping (part2/time_stepping.tex) +- this is not clear to me: -3. Tutorials - reorg'd into - intro part - individual experiments +>> 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 -4. Software Architecture -5. Automatic Differentiation +2.2 rigid-lid: -6. Physical Parameterization and Packages +- 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) -7. Diagnostics and tools +2.3 linear free-surface: +- add ref(+link) to S/R names: +- add ref(+link) to Crank-Nickelson section 2.9.1 -8. Interface with ECCO +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 -9. Model uses - Spall, Gianmaria, Legg, Dewar, Cessi, Cournelle, Follows, Adcroft, etc... - (check in support for more names) +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 - Need an empty package as part of distribution +2.6 Synchronous time-stepping: +- add link for S/R THERMODYNAMICS, DYNAMCIS, SOLVE_FOR_PRESSURE, + MOMENTUM_CORRECTION_STEP. - latex2html equation formatting is still a bit weird in places. Need to have another go if we have a chance - especially the degree symbol seems to jump around somewhat! +2.7 Stagger baroclinic time-stepping +- mention AB(T,S) instead of AB(Gt,Gs) (in development) at the end -Chapter 1 +2.8 NH +- add link & S/R names: CALC_GW, SOLVE_FOR_PRESSURE, CG3D - Change hydrodynamical to "dynamical" +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 - Examples +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) - - extra "in action" cases +2.10.1 Notation +- Area definition is not really used like this - o high res ocean with diurnal atmospheric state forcing - - links to ingrid output - CNH/Dimitris +>> Ao : Area of the face orthogonal to "o" direction (o=u,v,w) - o realistic FIZHI from Andrea - - links to ingrid output - from AM + Instead, in the following section, Ac,Aw,As,A_zeta (= corresponding to + the model variables) are used (e.g., see section 2.10.5) - o with seaice on high res cube - - links to ingrid output - CNH/Dimitris +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 - 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 +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 - o sensitivity wrt to iron +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 - o optimization - - update to link to latest ECCO sites and GF - related material +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); - o eddy diffusivity transport application +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) - o Gas giant? +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) -Chapter 6 +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. - the master package diagram does not appear in the document +2.14.6 Horizontal dissipation -> Horizontal Divergence - pkg/ptracers doesn't seem to have any documentation (see packages list below) +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.) -2.10.5 Horizontal grid +JM - need to do a better job of relating model variables to this diagram +>>>> 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 +Master list of packages (add this to beginning of chap 6) admtlm/ - autodiff (chapter 5) -aim/ - 6.4.1 (content needs fixing - JM to do) +aim/ - retired aim_compon_interf/ - 6.6 (no content yet) aim_ocn_coupler/ - 6.6 (no content yet) -aim_v23/ - retired +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 @@ -363,31 +457,8 @@ Figure 6.8 is missing - ->>>> 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 +6.3.1.7 Tapering: Large, Danabasoglu and Doney, JPO 1997 + Figure 6.8 is missing >>>> From Andrea @@ -496,144 +567,10 @@ 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 ->>>> 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 - -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 - -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.) + offline - duplicate inputs, what is it, tidy up cfc v. + other offline. JM thinks these need tidying up. -JM +9. Model uses + Spall, Gianmaria, Legg, Dewar, Cessi, Cournelle, Follows, Adcroft, etc... + (check in support for more names)