Documentation of new features needed

[wwieder]

We have a number of new features that have been added to the model recently that should be documented in the tech note and user's guide. I've started a short list of these and tried to suggest people who can help with this. Maybe at an upcoming meeting we can discuss how to efficiently get these contributions into our documentation?

• Crop Calendar, Prescribed sowing date and maturity requirements #1863 @samsrabin
• Excess Ice, Adding excess ground ice to CTSM  #1787 @mvdebolskiy, see Add excess ice user guide documentation #2161
• Roughness Length, Surface roughness modifications (cont'd) #2045 @olyson, see Update to documentation for Meier et al. (2022) roughness length parameterization #2134
• MIMICS, @wwieder
• NEON, @wwieder and @TeaganKing
• Nuopc
• User's guide clean up broken links & formatting

And more that are moving through the queue like:

• SNICAR SNICAR snow albedo scheme updates #1861 @cenlinhe
• Dust, A new physically based dust emission scheme with more aeolian physics (updated) #1897 @dmleung
• Tillage, Add soil tillage for crops #2040 @samsrabin
• Residue removal, Add crop residue removal #2297 @samsrabin
• Time related changes to history files (likely as a wiki)?

I'm sure there are others we need to add to this list...

[mvdebolskiy]

@wwieder Tech note documentation writeup was included in the #1787. See the Snow and Soil Temperatures section at master. If you want a user-guide write-up for the feature, i can make a quick PR with that.

[samsrabin]

Agreed. Should my things go under "Running with special cases," then?

[wwieder]

Thanks @mvdebolskiy, that's excellent! do we just have to 'build' the tech note again for these to changes to show up on the wiki? Is there additional, practical information that should be included in the user's guide for excess ice? I'm not familiar with how to run with this feature?

@samsrabin I'm not sure if the crop calendar work belongs with other crop model documentation or under [special cases in the user's guide]? Are the crop calendars not going to be on by default for CTSM5.1 crop simulations?

[samsrabin]

That's right, @wwieder. All I've done so far is add prescribed static crop calendars, which of course don't allow prognostic seasonal shifts. So "special cases" is probably more appropriate.

[mvdebolskiy]

Thanks @mvdebolskiy, that's excellent! do we just have to 'build' the tech note again for these to changes to show up on the wiki?

Yes.

Is there additional, practical information that should be included in the user's guide for excess ice? I'm not familiar with how to run with this feature?

Might be. I can add an entry to the "Run with special cases" about how initialization works and additional spinup required. However, it's described in the papers linked in the tech note.

[cenlinhe]

@wwieder I am happy to contribute to the documentation for the SNICAR updates. Please let me know how I should proceed (e.g., prepare a word doc and send it to the CTSM team?) and when you will need it. Thanks!

[TeaganKing]

@wwieder Do we want to add a new tech note section (eg, 2.33) for running with NEON? I'm not sure that it would fit under other pre-existing sections. I'd be happy to put something together for run_neon in general, as well as including some PRISM details, and make a PR to update the tech note.

Can you clarify where in the user's guide you would want this?

[dlawrenncar]

I think we need to have a discussion about the crop calendars and how we will be using this feature going forward. Due to the large biases in some regions in crop planting dates in CLM5, I think it is a big priority to include a crop planting calendar for CTSM6, perhaps even if we do not allow prognostic seasonal shifts. Or, maybe a very simple parameterization allowing for a shifting crop planting date could be implemented.

…

On Fri, Aug 18, 2023 at 8:48 AM Sam Rabin ***@***.***> wrote: That's right, @wwieder <https://github.com/wwieder>. All I've done so far is add prescribed static crop calendars, which of course don't allow prognostic seasonal shifts. — Reply to this email directly, view it on GitHub <#2113 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFABYVCG6YIZ3UP6HGJUURLXV56CPANCNFSM6AAAAAA3VOYI6U> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[samsrabin]

Definitely agree, @dlawrenncar. I'll send you et al. an email. For now, I have some ideas for "easy [prognostic] wins" in issue #1928.

[dmleung]

Hi, I can write the dust updates for the tech note too!

[mvdebolskiy]

@wwieder Are you making a PR I can contribute to, or should I just make a separate one?

[wwieder]

You can make a new one, @mvdebolskiy. thanks.

[wwieder]

Good question, @TeaganKing. I think we'll want to update the user's guide for NEON cases in section 1.6. I'd imagine this may be a larger overhaul for running point and regional cases with our new workflows. Does this make sense to others?

[olyson]

@olyson will document the surface roughness parameterization.

[mvdebolskiy]

@samsrabin regarding history fields. links in this section do not work.

[samsrabin]

Marking the tillage and residue removal tasks as done, as I've added documentation to those PRs (#2040, #2297) that will come in once approved.

Also marked the tillage and excess ice tasks as done.

[mvdebolskiy]

• Update Excess Ice descriptions in User Guide after: Fix/excess ice cold start #2465 and Turn excess ice on by default in CESM3 #2466