# Annotation of /manual/manual_todo.txt

foo

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