Skip to content

updated BVOC documentation#3909

Open
lkemmons wants to merge 16 commits into
ESCOMP:b4b-devfrom
lkemmons:lkemmons-docs-bvocs
Open

updated BVOC documentation#3909
lkemmons wants to merge 16 commits into
ESCOMP:b4b-devfrom
lkemmons:lkemmons-docs-bvocs

Conversation

@lkemmons
Copy link
Copy Markdown

@lkemmons lkemmons commented Apr 3, 2026

Description of changes

Updated BVOC documentation

Specific notes

Contributors other than yourself, if any:
Input provided by Hui Wang (UC-Irvine), @HuiWangWanderInGitHub

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

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

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

Does this create a need to change or add documentation? Did you do so?

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).

lkemmons added 4 commits April 1, 2026 18:07
Added detailed information on the impact of drought on isoprene emissions, including mathematical formulations and references to recent studies.
This updates the description of the BVOC emissions model with the new drought impact and high-latitude isoprene emissions factors.
Describes new drought impact and high-latitude isoprene emissions parameterization
Added new references related for BVOC drought impact and high-latitude isoprene emissions
@wwieder wwieder linked an issue May 13, 2026 that may be closed by this pull request
8 tasks
@wwieder wwieder requested a review from slevis-lmwg May 13, 2026 16:47
@wwieder wwieder added documentation additions or edits to user-facing documentation or its infrastructure docs:update Significant update or fix needed to existing documentation labels May 13, 2026
@slevis-lmwg slevis-lmwg moved this from Todo to In Progress in LMWG: Sprint Planning Board May 13, 2026
@slevis-lmwg slevis-lmwg added b4b bit-for-bit docs-loc:tech-note Relates to Technical Note (science) labels May 13, 2026
@slevis-lmwg slevis-lmwg changed the base branch from master to b4b-dev May 14, 2026 00:00
Copy link
Copy Markdown
Contributor

@slevis-lmwg slevis-lmwg left a comment

Choose a reason for hiding this comment

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

@lkemmons thank you for your work in this section! My review is thorough, but mostly it involves adding links to the references when each one first appears. To make things easier, I will try committing the simple suggestions if github will allow me, and I will leave only a few issues for you to resolve. Thanks again.

Comment thread doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst Outdated
Comment thread doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst Outdated
Comment thread doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst Outdated
Comment thread doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst Outdated
Comment thread doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst Outdated
Comment thread doc/source/tech_note/References/CLM50_Tech_Note_References.rst Outdated
Comment thread doc/source/tech_note/References/CLM50_Tech_Note_References.rst Outdated
.. math::
:label: C3 arctic grass parameter

C_{C3AG} = 95 + 9.5 e^{0.53 (288.15-T_{240})}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
C_{C3AG} = 95 + 9.5 e^{0.53 (288.15-T_{240})}
C_{C3AG} = 95 + 9.49 e^{0.53 (288.15-T_{240})}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Ok, done committing the "obvious" ones. Here's one of the constants that I could not find in the code, but that had a likely counterpart. Did I pick the correct value?

.. math::
:label: C3 arctic grass adjustment factor

E_{opt\_C3AG} = e^{0.22 (T_{240}-288.15)}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
E_{opt\_C3AG} = e^{0.22 (T_{240}-288.15)}
E_{opt\_C3AG} = e^{0.217 (T_{240}-288.15)}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Here's another constant that I could not find in the code. Did I pick the correct value from the code?

.. math::
:label: C3 arctic grass leaf temperature factor

\gamma_{T\_C3AG} = E_{opt\_C3AG} e^{(C_{C3AG}/R (1/303.15 - 1/T_{leaf}))}
Copy link
Copy Markdown
Contributor

@slevis-lmwg slevis-lmwg May 14, 2026

Choose a reason for hiding this comment

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

This formula is a bit difficult to read the way that it renders. You can download to your laptop my copy of this PR's built documentation /glade/derecho/scratch/slevis/preview_docs_pr.ESCOMP.CTSM.pr-3909/ESCOMP-CTSM-a074bdb/doc/_build/html and then click on index.html to view. Here are my concerns:

  • Pls confirm that the formula agrees with what's in the code

  • See if you can format it to make easier to read

  • Has the constant R been defined?

  • Looking at this formula made me notice that several param values in this doc file didn't match the code. I have pointed out that ones that I caught. Pls confirm that I replaced them with the correct values because I mostly guessed. Also pls check that I didn't miss any. To explain, we prefer to report exact param values in the documentation to make it easier to follow the documentation alongside the code, as well as to facilitate the ability to reproduce results if one were to rewrite the model starting from the documentation.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@lkemmons pls ping me here in the PR when you feel the rest can be resolved, and I will approve the PR and merge to the b4b-dev branch.

Add links when references first appear and distinguish what's new in CLM5 versus CLM6
Remove "now" which made sense when this part was new
@github-actions

This comment was marked as resolved.

Correct a1 and b1 values; also another reference link
Add a reference link for two sequential references
@github-actions

This comment was marked as resolved.

Corrected the shorthand notation for three new references
Corrected the shorthand notation for another new reference
@github-actions

This comment was marked as resolved.

@github-actions

This comment was marked as resolved.

@github-actions

This comment was marked as resolved.

Comment thread doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

b4b bit-for-bit docs:update Significant update or fix needed to existing documentation docs-loc:tech-note Relates to Technical Note (science) documentation additions or edits to user-facing documentation or its infrastructure

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

Review 2.30. Biogenic Volatile Organic Compounds (BVOCs)

3 participants