Documentation: clamping is applied only when variables are written

[kdraeder]

What's the issue?

Any clamping values are provided in the model_nml in the definition of the state vector,
which implies to me that variables put into the state vector will be clamped.
But clamping happens only during the output of the updated state.

Where did you find the issue?

I discovered it by trying to start an assimilation with state files that had values that were out of bounds
for the QCEFF algorithms I chose, and trying to fix that using clamping.
I didn't find this limitation in the documentation when searching for several variations of "clamp",
so I think that it should be added somewhere easily findable.

What needs to be fixed?

A note in the state_structure page might be enough.
Since users encounter clamping in model_mod and its namelist, the model_mod module page would also be a candidate for a comment.

Suggestions for improvement

It would also be handy if clamping could be applied to the fields as they're read in.
The alternative is to fix the state files before they are read, which can be cumbersome
and another source of mistakes.
Or would it work to put those files through an "assimilation" that did not assimilate or evaluate any obs,
and didn't inflate the ensemble, so that the new fields were identical except for the clamping?
I tried this, but the BNRH algorithm is still finding negatives in the field values and stopping.
I guess it doesn't know that it has no work to do. The case where I tested this is
/glade/derecho/scratch/raeder/Rean_BNRH_debugSST/run and
/glade/work/raeder/Exp/Rean_BNRH_debugSST_git/Rean_BNRH_debugSST

Anything else we should know?

Include any other relevant details, such as references, screenshots, or related discussions.

[hkershaw-brown]

Hi @kdraeder. This is a known issue #477
Is this something you and @jlaucar are working on?
There was some discussion when Ben Gaubert was using QCEFF with CAM Chem about needing to cycle after clamping, (because clamping isn't respecting the distribution in the same way the QCEFF does), rather than just clamping and then using the QCEFF.

[kdraeder]

Huh. I searched for "is:issue clamping" and 477 didn't show up.
Should I move this content to that one?

Yes, I'm setting up a QCEFF version of the CAM6 Reanalysis and using an initial ensemble from it.
It has negative values and I'm looking for a way to fix it that will be reliable and easy to use in the future,
since this seems to be not an isolated use case. But Jeff needs results soon, so I may have to resort
to using NCO tools (or ...) to fix these files.

[hkershaw-brown]

use NCO

[kdraeder]

Full speed ahead!

Is there anything from this issue that would be useful in #477?
If not, go ahead and close it.

[hkershaw-brown]

BNRH encountering negative values (barely; -10^-156)

see #681 (maybe) #709 #717

[hkershaw-brown]

related, model_nml that have clamp_or_fail "fail" is ignored.
#624