--- manual/manual_todo.txt 2006/04/06 19:54:06 1.9 +++ manual/manual_todo.txt 2006/04/07 02:35:23 1.28 @@ -14,11 +14,6 @@ - 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 @@ -30,16 +25,6 @@ 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 @@ -207,125 +192,154 @@ o Gas giant? -Master list of packages +>>>> from JM -admtlm/ - autodiff (chapter 5) -aim/ - 6.4.1 (content needs fixing - JM to do) -aim_compon_interf/ - 6.6 (no content yet) -aim_ocn_coupler/ - 6.6 (no content yet) -aim_v23/ - retired -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 +manual, section.2 : -Need to get packages to contain their available diagnostics (i.e. calls to DIAGNOSTICS_ADD). these are listed in stdout when pacakages are started. +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. -Figure 6.8 is missing +in content: Horizontal Dissipation: 2 times in vector-invariant section +2.1 time-stepping (part2/time_stepping.tex) ->>>> From Ed +- this is not clear to me: -Here are the remaining bits for Chap 4 : +>> 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 - - 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} +2.2 rigid-lid: - - There are a few empty sub-sections at the end of Chap 4 that - should either be commented out or fleshed out. +- 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) -and thats about it for Chap 4. +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 -Add more to quick links on front page +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 -Chapter 6 +2.6 Synchronous time-stepping: +- add link for S/R THERMODYNAMICS, DYNAMCIS, SOLVE_FOR_PRESSURE, + MOMENTUM_CORRECTION_STEP. - the master package diagram does not appear in the document +2.7 Stagger baroclinic time-stepping +- mention AB(T,S) instead of AB(Gt,Gs) (in development) at the end - pkg/ptracers doesn't seem to have any documentation (see packages list below) +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 ->>>> From Andrea +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) -to do list for chap 7: +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) -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 + Instead, in the following section, Ac,Aw,As,A_zeta (= corresponding to + the model variables) are used (e.g., see section 2.10.5) -7.5.1 - add Graphix to the list of stuff in utils/matlab -7.5.2 - empty +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 polar grid description + need to do a better job of relating model variables to this diagram -andrea +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 + +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.) + + +JM + >>>> From Andrea @@ -337,6 +351,7 @@ 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?) +[DONE] 3.1 - don't need a link to the outside of the document (remove it) - link to htdig is broken @@ -422,153 +437,199 @@ offline - duplicate inputs, what is it, tidy up cfc v. other offline. JM thinks these need tidying up. ->>>> 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) +Which of the following are which tutorial? +! MLAdjust +adjust_nlfs.cs-32x32x1 +aim.5l_XZ_Equatorial_Slice +biogeo +aim.5l_zon-ave +coupled_ucla +cfc_offline +exp3 +global2x2_tot +global1x1_tot +global_ocean.cubed_wEXF +global_with_CFC11 +goz +gop +natl_box_obcs +natl_box_forward +spinup_optim +tutorial_held_suarez_cs +vero +inverted_barometer +global_ocean.cubed32x32x30 +exp1 +advect_cs +dic_example +fizhi-gridalt-hs +global_ocean_pressure +matrix_example +exp4 +solid-body.cs-32x32x1 +cfc_example +flt_example +adjustment.cs-32x32x1 +advect_xz +rotating_tank +ideal_2D_oce +global_ocean.90x40x15 +front_relax +aim.5l_LatLon +lab_sea +hs94.cs-32x32x5 +global_with_exf +exp2 +tidal_basin_2d +fizhi-cs-32x32x10 +exp5 +global_ocean.cs32x15 +OpenAD +hs94.1x64x5 +fizhi-cs-aqualev10 +exp0 +dome +aim.5l_Equatorial_Channel +aim.5l_cs +hs94.128x64x5 +prm +carbon +plume_on_slope +natl_box_adjoint +vermix +cpl_aim+ocn +global_ocean_ebm +internal_wave +advect_xy +natl_box +adjustment.128x64x1 -- 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: +>>>> From Ed -- 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) +Here are the remaining bits for Chap 4 : -2.3 linear free-surface: -- add ref(+link) to S/R names: -- add ref(+link) to Crank-Nickelson section 2.9.1 + - 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} -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 + - There are a few empty sub-sections at the end of Chap 4 that + should either be commented out or fleshed out. -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 +and thats about it for Chap 4. -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 +Add more to quick links on front page -2.8 NH -- add link & S/R names: CALC_GW, SOLVE_FOR_PRESSURE, CG3D +Chapter 6 -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 + the master package diagram does not appear in the document -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) +Master list of packages (add this to beginning of chap 6) -2.10.1 Notation -- Area definition is not really used like this +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 +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) ->> Ao : Area of the face orthogonal to "o" direction (o=u,v,w) +list an expeiment which uses package? CNH - 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]Need to get packages to contain their available diagnostics (i.e. calls to DIAGNOSTICS_ADD). these are listed in stdout when pacakages are started. -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 +6.3.1.7 Tapering: Large, Danabasoglu and Doney, JPO 1997 + Figure 6.8 is missing -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 +>>>> From Andrea -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 +to do list for chap 7: -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) +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 -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) +7.5.1 - add Graphix to the list of stuff in utils/matlab +7.5.2 - empty -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 +andrea -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 +9. Publications using MITgcm --> "Previous Applications of MITgcm" + Spall, Gianmaria, Legg, Dewar, Cessi, Cournelle, Follows, Adcroft, etc... + (check in support for more names) -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.) +10. Under development -JM +Bibliography -9. Model uses - Spall, Gianmaria, Legg, Dewar, Cessi, Cournelle, Follows, Adcroft, etc... - (check in support for more names) + tidy up from misc - .tex