namelist defaults and documentation

[eclare108213]

Clarify or fix this confusing issue: ‘default’ namelist values in the documentation do not necessarily match those in the default namelist file because the documented default namelist values are suggested for production runs, and with our greatly expanded tests, more than one value is often tested. We need to define what we mean by "default," e.g. whether they are values set in the main ice_in file, or in the production namelist option, or the code's last resort when all other options are exhausted. I think we have a mix of these now.

[eclare108213]

#390 is related to this, I think

[apcraig]

I think the documented defaults should be the values defined within the code. They can, of course, be changed in namelist. If there is a different recommendation for production runs, then we should document that as a separate column in the namelist table or via some other process.

[apcraig]

I am working on this now. In CICE, we have a column in the namelist table called "recommended value". I propose to change this to "default value" and then update the values to indicate the default value within the CICE code (which can/will be overidden by namelist). Do we want another column indicated "recommended value" or "production recommendation" or something? I think it's important to document the internal default, not sure about anything else. Unless someone disagrees, I'll proceed with this approach.

[eclare108213]

It makes sense to document the values defined in the code, in case a namelist value is not set. I think that 'recommended value' is more useful, however that value might not be the best one for all configurations. This is a tricky issue. Optimally, we'd document various values used in various configurations, with citations to relevant papers, but that's a lot of work (so let's not, unless someone has already done it and it's handy). Alternatively, we could add a footnote or a comment to the table that points to the gx1 production -s option, and explain that those were the recommended values for stand-alone configurations in v5, which depended somewhat on the forcing data used at that time (and cite relevant papers if appropriate).

[apcraig]

#459 addressed this issue. internal code defaults are now documented in the namelist tables. we may need to add a new section to the documentation, "model configuration recommendations". if so, we should create a new issue for that.