Documentation for soil moisture deficit calculation is incorrect.

[yanyanchengHydro]

Brief summary of bug

As indicated in page 247 of the CLM5 documentation, the soil moisture deficit to calculate irrigation should be equal to “soil moisture threshold - available moisture". But in IrrigationMod.F90, it uses “irrigation target soil moisture” rather than “soil moisture threshold” to minus the “available moisture”. Then this situation is equal to that the irrigation threshold fraction is always equal to 1.

General bug information

CTSM version you are using: ctsm1.0.dev080
Does this bug cause significantly incorrect results in the model's science? [No]

Details of bug

Soil moisture deficit calculation in CLM5 documentation

Bug in the source code IrrigationMod.F90

@ekluzek @swensosc @dlawrenncar @huangmy

[billsacks]

Thank you for bringing this to our attention. I have been looking at this code, and I agree that the code differs from the documentation. However, I think that the code is right and the documentation is wrong here.

I haven't taken the time to get my head 100% back into this, but I think that h2osoi_liq_target is truly supposed to give the target soil moisture value that we're shooting for whenever irrigation happens; then the deficit gives the difference between this target value and the current soil moisture. h2osoi_liq_at_threshold, on the other hand, gives a threshold at which we decide to do any irrigation at all. The way this is written allows for the possibility that you may not want to irrigate every time there becomes even a tiny soil moisture deficit. Instead, you may want to wait until the deficit is larger before initiating irrigation; at that point, you don't want to just irrigate up to the "threshold" but instead up to the higher "target". The target should always be greater than or equal to the threshold.

Regarding this:

Then this situation is equal to that the irrigation threshold fraction is always equal to 1.

Note that the threshold fraction is still relevant for the conditional just above your proposed change; it just isn't invoked (nor should it be) in actually calculating the deficit.

Unless someone thinks I'm misunderstanding something here, I believe the course of action is that we should fix the documentation to be consistent with the (correct) code.

(Also including @danicalombardozzi in this discussion.)

[dlawrenncar]

@swensosc may also have thoughts about this.

[swensosc]

I think bill's assessment is correct. 2.26.13 should be modified to include w_target. And some of bill's explanation of the definition and purpose of f_thresh should be added; this would help reduce confusion going forward. Noting that the motivation for including f_thresh (that can be less than one) is to avoid irrigating for small deficits might help clarify its intended purpose. Perhaps changing its name to 'irrig_initiation_threshold' or something like that might also highlight its use?

…

On Sat, Dec 21, 2019 at 2:18 PM Bill Sacks ***@***.***> wrote: Thank you for bringing this to our attention. I have been looking at this code, and I agree that the code differs from the documentation. However, I think that the code is right and the documentation is wrong here. I haven't taken the time to get my head 100% back into this, but I think that h2osoi_liq_target is truly supposed to give the target soil moisture value that we're shooting for whenever irrigation happens; then the deficit gives the difference between this target value and the current soil moisture. h2osoi_liq_at_threshold, on the other hand, gives a threshold at which we decide to do any irrigation at all. The way this is written allows for the possibility that you may not want to irrigate every time there becomes even a tiny soil moisture deficit. Instead, you may want to wait until the deficit is larger before initiating irrigation; at that point, you don't want to just irrigate up to the "threshold" but instead up to the higher "target". The target should always be greater than or equal to the threshold. Regarding this: Then this situation is equal to that the irrigation threshold fraction is always equal to 1. Note that the threshold fraction is still relevant for the conditional just above your proposed change; it just isn't invoked (nor should it be) in actually calculating the deficit. Unless someone thinks I'm misunderstanding something here, I believe the course of action is that we should fix the documentation to be consistent with the (correct) code. (Also including @danicalombardozzi <https://github.com/danicalombardozzi> in this discussion.) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#872?email_source=notifications&email_token=AGRN57A5LYUXVJ6BT6WE7ILQZ2B2FA5CNFSM4J6BXIJ2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEHPDZTY#issuecomment-568212687>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGRN57HXCCP67YOOBW2VWTLQZ2B2FANCNFSM4J6BXIJQ> .

[danicalombardozzi]

@billsacks and @swensosc: @yanyanchengHydro also pointed out that this code results in the irrigation threshold fraction always being equal to 1. Is that the correct behavior? Or should it be able to vary?

[billsacks]

@billsacks and @swensosc: @yanyanchengHydro also pointed out that this code results in the irrigation threshold fraction always being equal to 1. Is that the correct behavior? Or should it be able to vary?

I'm not sure exactly what is meant by this. As written, the deficit is based on h2osoi_liq_target_tot, which is equal to h2osoi_liq_at_threshold if irrig_threshold_fraction is 1. So maybe that's what @yanyanchengHydro is referring to? But I still believe that the code is written as intended.

I'll wait to move ahead with this until hearing back from @yanyanchengHydro

[yanyanchengHydro]

@billsacks @swensosc @danicalombardozzi @dlawrenncar Thank you Bill for the clarification. Yes, I mean the deficit is based on h2osoi_liq_target_tot, which is equal to h2osoi_liq_at_threshold if irrig_threshold_fraction is 1.

I did not correctly understand the purpose of irrig_threshold_fraction at the very beginning. Since the motivation for irrig_threshold_fraction is to avoid irrigating for small deficits, I agree with Bill that the code is correct rather than the documentation.

[samsrabin]

@billsacks We talked about this in the CTSM SE meeting yesterday, and @olyson mentioned he'd be willing to fix the docs if indeed the code is correct. If that's the case, would you be okay with him taking this on as the new assignee?

[billsacks]

@billsacks We talked about this in the CTSM SE meeting yesterday, and @olyson mentioned he'd be willing to fix the docs if indeed the code is correct. If that's the case, would you be okay with him taking this on as the new assignee?

Sounds great - thank you!