Skip to content

update hydrology documentation#3954

Open
YifanCheng wants to merge 4 commits into
ESCOMP:b4b-devfrom
YifanCheng:b4b-dev-yifan
Open

update hydrology documentation#3954
YifanCheng wants to merge 4 commits into
ESCOMP:b4b-devfrom
YifanCheng:b4b-dev-yifan

Conversation

@YifanCheng
Copy link
Copy Markdown

@YifanCheng YifanCheng commented Apr 23, 2026

Description of changes

Update the hydrology section documentation.
The following major changes have been made:

  1. undocumented snowcan_unload_wind_fact parameter. The code (CanopyHydrologyMod.F90) multiplies the wind-driven snow unloading by a tunable scalar snowcan_unload_wind_fact (read from the parameter file), which does not appear in the document. Solution: I add it in the updated equation 2.7.14
  2. ambiguity of W_{can} in the f_wet formula. The code (CanopyHydrologyMod.F90) computes h2ocan = snocan + liqcan (total liquid + snow), but the document does not explicitly state that W_{can} in the f_wet formula is the total (liquid + snow) canopy water rather than liquid alone. Solution: I added a new equation 2.7.24.
  3. maximum_leaf_wetted_fraction parameter not mentioned The code caps f_wet using the parameter maximum_leaf_wetted_fraction (read from a parameter file; CanopyHydrologyMod.F90), whereas the document states simply f_wet ≤ 1. Solution: I modified equation 2.7.23. And the default value is 0.05 according to the PPE document (CLM Parameter Table)

Others are minor formatting or typo issues identified in the documentation.

Specific notes

Contributors other than yourself, if any: None

CTSM Issues Fixed (include github issue #): #3853 (comment)

Are answers expected to change (and if so in what way)?
No

Any User Interface Changes (namelist or namelist defaults changes)?
No

Does this create a need to change or add documentation? Did you do so?
Only documentation in the hydrology section gets updated based on existing code changes.

Testing performed, if any:
(List what testing you did to show your changes worked as expected)
(This can be manual testing or running of the different test suites)
(Documentation on system testing is here: https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide)
(aux_clm on derecho for intel/gnu and izumi for intel/gnu/nag/nvhpc is the standard for tags on master)

NOTE: Be sure to check your coding style against the standard
(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
the list of common problems to watch out for
(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).

If this PR changes the CTSM web documentation, please see our contribution guidelines for documentation.

@wwieder wwieder requested a review from samsrabin April 30, 2026 16:34
@samsrabin
Copy link
Copy Markdown
Member

@YifanCheng Could you please fill out the PR template? Make sure to also include a brief description of what you changed. Thanks!

@wwieder
Copy link
Copy Markdown
Contributor

wwieder commented Apr 30, 2026

@YifanCheng is this just a test case of the documentation workflow, an in progress workflow, or ready for review?

@YifanCheng
Copy link
Copy Markdown
Author

@samsrabin @wwieder Sorry, this is solely a practice PR during the second session! Not ready for merging yet! Should I delete it? Or should I leave it here, and later on, I can merge new commits to this PR? Whichever works for me. Please let me know.

@samsrabin
Copy link
Copy Markdown
Member

If the changes you made are ones you intend to keep, please (1) change the title to remove "experiment" and (2) mark it as a draft so we know it's not ready to be reviewed. If you don't intend to keep these changes, then go ahead and delete. Thanks!

@YifanCheng YifanCheng changed the title update hydrology documentation - experiment update hydrology documentation May 1, 2026
@YifanCheng YifanCheng marked this pull request as draft May 1, 2026 14:24
@wwieder wwieder linked an issue May 13, 2026 that may be closed by this pull request
8 tasks
@YifanCheng YifanCheng marked this pull request as ready for review May 28, 2026 22:38
Copy link
Copy Markdown
Member

@samsrabin samsrabin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, @YifanCheng! Looks mostly good; I just have one request.


.. math::
:label: 1.104
:label: 7.89b
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since you're already relabeling equations (here and elsewhere in this file), would you mind changing them to something meaningful as mentioned in the style guide?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Sam,

Thank you for catching this and demonstrating how the labeling should be done! I updated the label for this equation, as well as one for calculating W_can. Please let me know if additional edits are required.

Yifan

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review 2.7. Hydrology

3 participants