Clean headers, fix typos, and verify parameter names against Atlantis source#33
Clean headers, fix typos, and verify parameter names against Atlantis source#33jacobkasper wants to merge 23 commits into
Conversation
…ing errors in all sections.
…d 15 and part 2 15, 16, 17. updated css and added a missing image
…capes - Replace all prose ` -- ` with proper em-dash across 15 chapters - Fix page range 733--746 to en-dash in fishing mortality chapter - Remove backslash escapes from numbered list markers (1\. and 1\)) across 7 files - Remove \$ escape characters from economics chapter (25 instances)
PowerShell Set-Content added a UTF-8 BOM to 15 chapter files, causing Pandoc to fail heading recognition and breaking chapter titles site-wide.
…es note Background ---------- The previous commit added a conventions note listing parameter names that contain typos baked into the Atlantis C source code, warning users they must match the typo'd spelling exactly. That note included MICROPHTYBENTHOS as one of the four "confirmed" cases. Why MICROPHTYBENTHOS is different ---------------------------------- Grepping the entire Atlantis trunk (all .c and .h files) finds zero occurrences of MICROPHYT* in any form. The group code is not read by the C parser at all — it is a user-defined string in functional_groups.csv, which users create and name themselves. The C code never checks for this specific string, so there is no code-enforced spelling. One occurrence of the correctly-spelled MICROPHYTOBENTHOS already existed on line 152 of chapter 10 (written by a different author), confirming it is free to change. The other three names (temp_ampltiude, isLightEffected, isNoiseEffected) ARE hardcoded in the parser: atphysics.c:312 readkeyprm_d(pfp, "temp_ampltiude", ...) atUtilGroupIO.c Util_XML_Get_Value_Integer(..., "isLightEffected", ...) atUtilGroupIO.c Util_XML_Get_Value_Integer(..., "isNoiseEffected", ...) Those must stay typo'd in the manual. Changes in this commit ---------------------- 1. 02-introduction.qmd — conventions note: removed MICROPHTYBENTHOS from the list and changed "parameter and group names" back to "parameter names", since the note now only covers code-enforced parameter typos. 2. 07-definitions-of-functional-groups.qmd — all 3 occurrences of MICROPHTYBENTHOS renamed to MICROPHYTOBENTHOS. 3. 10-primary-producer-processes.qmd — all remaining occurrences of MICROPHTYBENTHOS renamed to MICROPHYTOBENTHOS (the one instance already correctly spelled on line 152 was unaffected).
…nvention The parameter is stored in the code as "feed_while_spawn" (atUtil.c:253) and appears in real biology.prm files as feed_while_spawnSCR, feed_while_spawnCAP, etc. — no underscore between "spawn" and the species code. This is an unusual Atlantis naming pattern but it is what the parser reads and what users must type. The manual already used the correct feed_while_spawnXXX form in two places (ch. 11 line 468, ch. 12 line 105). One occurrence on ch. 12 line 111 was missing the XXX suffix entirely; corrected here for consistency. The proposed rename to feed_while_spawn_XXX (with underscore) was considered and rejected after checking NoBa param files: adding an underscore would silently break every existing model setup.
Verified against atlantisboxmodel.h lines 809-837: all integers 1-30 are defined except 19 (intentional gap in the code). The table already correctly skipped 19; value 30 (debug_external, used in atexternalpop.c) was the only missing entry.
There was a problem hiding this comment.
I can't really comment on (1) Parameter name changes or (2) conventions note ... Not sure how i would go about checking this. If you can supply more info i will check
Regarding (3) the debug table. I am assuming these debug flags have been added over time and that debug = 30 is only available in later versions of the code base. My model is running 6681, so unsure if this flag is an option. Maybe these flags (in the documentation table) should have version numbers next to them to indicate they are available from version xxx onward.
I have looked in the atexternalpop.c file. There is only one fprintf that is not commented out and a quit statement follows it!! Not sure @jacobkasper what the expected output should be when debug = 30 is set! Saying this the model runs with debug = 30.
Regarding (4) Rendered output: i see the footnotes in the rendered manual. While they are functional, Quarto duplicates the footnotes because its underlying engine, Pandoc, does not support multiple in-text pointers to a single footnote definition. This results in multiple distinct footnotes, all being the same! Not ideal but it works. As an alternative you could just create the superscript but not hyperlink it. Most people know to look at the bottom of the page for these
|
An fprintf before a quit is so people who batch run can have a clue as to why their run quit before tstop. We could version the debug flags but it would be a stcakc of work to dig out when some of the earlier ones were added, perhaps do it going forward or havea. simple catch all of "prior to version XXXX" for a stack of them? Also if someone has a list of all the params I have messed up we could recreate a correction script to run over prm files for them and I/we could fix them in the code if that is less infuriating going forward. Sorry my spelling sucks so lucky there isn't more :) |
|
it would be great if some other folks could please take a look at this @erlasturl @jcaracappa1 @cecilieha @hmorzaria @somros |
3 participants
cd "e:\Atlantis\AtlantisManual" && gh pr create --title "Clean headers, fix typos, and verify parameter names against Atlantis source" --body "$(cat <<'EOF'
Justification
The Atlantis Manual is the primary reference document for 30+ modelling teams worldwide. This PR is a systematic clean-up pass motivated by a simple concern: errors in this document have real consequences. A wrong parameter name means a user writes an incorrect parameter file and spends days debugging a run that silently misbehaves. A broken heading or rendering artefact erodes trust in the document as a whole. This PR addresses accumulated issues across four categories.
1. General prose typos and content errors (throughout all chapters)
An initial sweep fixed prose-level typos, grammatical errors, heading errors, and formatting issues across all Part 1 and Part 2 chapters, the appendix, and references. This includes restoration of a section of the ecological overview that was accidentally deleted in a prior commit.
2. Systematic formatting sweep (15 chapters, CSS)
A set of formatting artefacts introduced during earlier editing passes were corrected programmatically across all affected chapters:
\<,\>) rendered as literals rather than as markup=signs in orange-styled parameter spans (355 instances)biology.prm,force.prm,harvest.prm,physics.prm,run.prm,functional_groups.csv,migrations.csv,output.nc,initial_conditions.nc) were not consistently italicised in prose3. Parameter names verified against the Atlantis trunk source code
Several parameter names were inconsistent or unverified. Each was resolved by grepping
AtlantisTrunk/trunk/atlantis:flagmicronutin table (ch. 10)flagmicro— the actual string the XML parser reads (atBiologyXMLParamIO.c)MICROPHTYBENTHOSthroughout (ch. 7, 10)MICROPHYTOBENTHOS— this group name does not appear in the C source and is user-defined, so it is free to correcteddy_S1toeddy_S2range (ch. 10)eddy_S1toeddy_S4feed_while_spawnXXXvsfeed_while_spawn_XXXatUtil.cboth use the no-underscore form; adding one would break existing setupstemp_ampltiude,isLightEffected,isNoiseEffected4. Documentation completeness
debugparameter table (@tbl-debug-values, ch. 8) was missing value 30 (debug_external— external population model), which is actively used inatexternalpop.c. Added.<sup>footnote markers in the optional tracers table (ch. 6) were converted to portable Pandoc[^name]footnote syntax.5. Table formatting
**6. References **
fixes #31
Reviewer instructions
@eafulton Please look this over too.
Key things to check:
flagmicro(notflagmicronut) is what users should type in biology.prm; confirmMICROPHYTOBENTHOSis acceptable as the standard group code going forward02-introduction.qmd) — check that the listed code-level typos (temp_ampltiude,isLightEffected,isNoiseEffected) are accurate and the wording is appropriateatexternalpop.cproduces in the log outputEOF
)"