Updated Inflation Documentation #806

mgharamti · 2025-01-23T16:44:40Z

Description:

Completely re-wrote the inflation documentation: docs.dart.ucar.edu/en/latest/guide/inflation.html

Fixes issue

This fixes issues: #775 and #276

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update

Documentation changes needed?

My change requires a change to the documentation.
- I have updated the documentation accordingly.

Tests

Please describe any tests you ran to verify your changes.

Checklist for merging

Updated changelog entry
Documentation updated
Update conf.py

Checklist for release

Merge into main
Create release from the main branch with appropriate tag
Delete feature-branch

Testing Datasets

Dataset needed for testing available upon request
Dataset download instructions included
No dataset needed

hkershaw-brown · 2025-01-23T18:08:06Z

Hi Moha, I'm going to rewrite the history on this branch so it is just your inflation changes.
Sorry for the round-about-ness, I just want to loose the funky merge history.

braczka · 2025-01-23T18:30:12Z

Thanks @mgharamti and @hkershaw-brown . I will take a look at this soon.

hkershaw-brown · 2025-01-27T14:17:32Z

note there is also this section on inflation:
https://docs.dart.ucar.edu/en/latest/guide/important-capabilities-dart.html#data-assimilation-algorithms-available-in-dart

jlaucar · 2025-01-27T15:04:15Z

The inflation information in this section is accurate but limited. The discussion of available filters is out-of-date with the newest QCEFF releases and needs to be updated.

…

On Mon, Jan 27, 2025 at 7:17 AM Helen Kershaw ***@***.***> wrote: note there is also this section on inflation: https://docs.dart.ucar.edu/en/latest/guide/important-capabilities-dart.html#data-assimilation-algorithms-available-in-dart — Reply to this email directly, view it on GitHub <#806 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ANDHUIRIXS7UEDGWCSA3G332MY5ZLAVCNFSM6AAAAABVXZJRYCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMJVHA4DGNRRGQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

hkershaw-brown · 2025-01-27T18:53:44Z

@mgharamti we need to fix your local copy main branch, otherwise you'll just keep committing this merge history:

hkershaw-brown · 2025-01-27T19:23:41Z

I'll rewrite the history, lets get your repo up to date after the standup tomorrow.

mgharamti · 2025-01-27T19:25:16Z

Sounds great. Thanks!

The inflation documentation has been re-written, making it concise and clear to the users. Several recommendations on what type of inflation (and for what reason) to use, are made. I also provide detailed steps on how to test inflation behavior.

Removed old deprecated algorithms and added the supported ones using the QCEF formulation. Also, replaced the old (unclear) localization image.

braczka · 2025-01-30T00:04:27Z

@hkershaw-brown What's the best way for me to push my changes to the inf_docs branch? I am used to a branch being created on the DART repo, where I can check out and make changes locally, however, in this case it looks like inf_docs exists on Moha's repo -- which I can also check out, but given the history rewrite etc, just wanted to be sure what's the best approach here.

hkershaw-brown · 2025-01-30T00:19:09Z

@braczka because this is a pull request, you have write permission to this branch on Moha's fork of DART

Couple of ways you can work with this:

You can clone Moha's fork:

   git clone https://github.com/mgharamti/DART.git DART.Moha
   cd DART.Moha
   git checkout inf_docs
       make your changes
   git push origin inf_docs

Or you can add Moha's fork as a remote to your local DART

   cd DART (a regular clone of DART)
   git remote add moha https://github.com/mgharamti/DART.git 
   git checkout inf_docs
      make your changes
   git push moha inf_docs

hkershaw-brown · 2025-01-30T00:20:37Z

git remote -v to see what remote you have set up
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork

braczka · 2025-01-30T18:30:55Z

@hkershaw-brown Still having some issue pushing my changes -- when I do a git push moha inf_docs it asks for my username and password information which I provide, but password authentication is deprecated, so I generated a token for my password -- but it still giving me permission errors:

remote: Permission to mgharamti/DART.git denied to braczka.
fatal: unable to access 'https://github.com/mgharamti/DART.git/': The requested URL returned error: 403

I thought I had permission given its a PR on the DART repo -- but maybe I need permission on Moha's repo as well?

hkershaw-brown · 2025-01-30T18:44:43Z

bummer, maintainers (including you) are allowed edit this pull request.

I've been pushing to this branch with wild abandon.

mgharamti · 2025-01-30T18:48:43Z

@braczka, if it becomes too complicated could you provide your input as comments in the changed files? I'll update the files then according to your suggestions.

Otherwise, @hkershaw-brown please let me know if I need to do any permission changes on my end.

braczka · 2025-01-30T18:51:05Z

I feel like its just complicated enough, where suggesting changes in the comments is difficult and tedious. I can do that if necessary -- I must be messing something up on the git command process......

braczka · 2025-01-30T19:18:13Z

There we go ! I was using a 'fine-grained' token instead of the general use token, which was messing me up I think. In addition to the commits, I need to add some comments too..... will finish in a bit.

braczka

@mgharamti This is fantastic -- thank you so much for updating this. This was very helpful for me to understanding inflation a lot better. Sorry, if I was a little heavy-handed with my commit changes -- it just expands on the distinction between the update of inflation versus the application of inflation, and also more detail on how the obs_impact_tool interacts with inflation. Really, just a bit more hand-holding and warnings for non-inflation experts like myself who could easily make a mistake in implementation or understanding of inflation.

braczka · 2025-01-30T19:26:55Z

guide/inflation.rst

+	:math:`\widetilde{\mathbf{x}}_k^i = \sqrt{\lambda} \left( \mathbf{x}_k^i -
+ 	\overline{\mathbf{x}}_k \right) + \overline{\mathbf{x}}_k, \quad
+	i = 1, 2, ..., N_e`
+


Does the subscript 'k' serve any purpose here? It's not defined and I wasn't sure if 'k' was the the same thing as 'e' the total ensemble members.

The 'k' is there because of habit. I am just used to writing variables with their time index. I think there is no need for it here. I will remove it and will also set the ensemble size to 'N' rather than 'N_e'

braczka · 2025-01-30T19:33:08Z

guide/inflation.rst

+1. Start without any inflation; i.e., ``inf_flavor = 0, 0`` and assess the performance. For a healthy ensemble
+DA system, one expects the prior RMSE and the total spread to be of the same order. We often use the ensemble


Shouldn't this say the RMSE and tot_spread should be roughly the same 'value' or 'magnitude'? If you say they should be roughly the same 'order' this might suggest to me 'order of magnitude' which means even a 4-5x difference could be acceptable -- but I think we don't want the RMSE/tot_spread ratio being outside of 0.5 to 1.5 range.... correct? Could you clarify this for me ?

The term that is often used in the literature is 'order'. Overall, I think you want to avoid insanely large consistency values but sometimes 4-5x could actually be acceptable especially if it doesn't persist over long assimilation windows. So, I wouldn't be so stringent on the range of the ensemble consistency values. Clearly, a consistency of 1 is what we're after but this may not be even possible in systems where error growth is limited. Yet, I'm going to use the word 'magnitude' because it provides a better guidance for the users.

mgharamti · 2025-01-30T20:25:22Z

guide/inflation.rst

@@ -83,21 +83,32 @@ DART includes advanced adaptive inflation algorithms that allow inflation
 to vary dynamically in both space and time. These algorithms treat inflation
 as a random variable characterized by a probability density function (PDF).
 The mean (or mode) of the PDF is used as the inflation value, while the standard
-deviation reflects the level of confidence in that value.
+deviation reflects the level of confidence in that value. In this way, the 
+inflation parameters (mean, standard deviation) are prognostic variables and


I am going to omit the term 'prognostic variables'. This is typically used to describe a variable that the model predicts through integrating a physical equation. To me, a prognostic variable is a variable that has a partial derivative with respect to time in the model PDEs. Inflation mean and standard deviation is like a physical model parameter. I'll reword and push the change.

mgharamti · 2025-01-30T20:53:02Z

guide/inflation.rst

+                from being applied to a variable when inflation is turned on.  If a variable is
+                not updated by observations because either 1) observation gaps exist in space or time 
+                2)the state is outside the spatial localization distance, or  3) variable localization 
+                was applied through the ``obs_impact_tool``, --the inflation update for that part of the


inflation damping happens whether inflation was updated with observations or not. I am not a fan of the word 'revert', I'll edit the text.

inflation damping happens whether inflation was updated with observations or not. I am not a fan of the word 'revert', I'll edit the text.

Definitely check for this mistake elsewhere, because this was a misunderstanding on my part.

I'm on it. I realize that I needed to provide more clarity so I added a note detailing the order of inflation operations in DART. Will push shortly

braczka

Looks good -- see my suggestion on order of operations.

braczka · 2025-01-30T22:19:07Z

guide/inflation.rst

+	 .. note::
+		 Order of (prior) inflation operations within DART:
+
+		 - Inflation is read from file or namelist
+		 - Inflation damping is applied: :math:`\sqrt{\lambda} \leftarrow 1 + \rho(\sqrt{\lambda} - 1),` where :math:`\rho` is the damping factor
+		 - Damped Inflation is applied to the prior ensemble
+		 - Inflation is updated with observations
+		 - Updated inflation values are written out


I really like this order of operations. It emphasizes that the inflation damping and inflation estimation with observations are performed in series. Could you maybe number the steps, because I think this would emphasize that the updated inflation values from step 5 (updated inflation is written out), are copied back into step 1 (Read in inflation from restart file). Also instead of just saying Inflation is updated with observations in step 4, it would really help if it was stated Inflation is updated with observations using inf_flavor algorithm, or using equation 1 which is defined at the beginning of the section. Something that really distinguishes between the damping update versus the observation update.

Further clarification around inflation damping. Added text detailing the order of operations for inflation.

hkershaw-brown · 2025-01-31T13:48:51Z

guide/inflation.rst

+		Inflation is only applied to the variables that are **updated** by DART
+		by specifying ``UPDATE`` within the ``&model_nml`` section of ``input.nml``.
+		Alternatively, if the variables are not updated (``NO_COPY_BACK``) then inflation
+		will not impact them. ``NO_COPY_BACK`` variables are often used to compute the forward
+		operators, however, they don't take part in the update and as such
+		they will not be inflated.


@mgharamti @braczka
A question on this 'important' section.

NO_COPY_BACK does not prevent the variables being inflated, a user has to set the initial inflation file to have inflation values of 1.0 to have have no inflation #276
Do you have code elsewhere that queries no_copy_back before applying inflation?

Helen, I thought this feature has already been implemented after the science discussions we had. Perhaps, this is something I'll work on in a separate PR (in the near future). We will need to query the variables before applying inflation.

For the sake of this documentation PR, I'll edit the text for the NO_COPY_BACK section and push.

hkershaw-brown

see NO_COPY_BACK cmoment

guide/inflation.rst

Co-authored-by: Helen Kershaw <[email protected]>

hkershaw-brown force-pushed the inf_docs branch from c15600b to 0a39588 Compare January 23, 2025 18:27

hkershaw-brown requested a review from braczka January 23, 2025 18:27

hkershaw-brown mentioned this pull request Jan 27, 2025

doc: data-assimilation-algorithms-available-in-dart is out of date #809

Open

mgharamti added 2 commits January 27, 2025 14:57

Improved Inflation Documentation

f811d73

The inflation documentation has been re-written, making it concise and clear to the users. Several recommendations on what type of inflation (and for what reason) to use, are made. I also provide detailed steps on how to test inflation behavior.

Improved filter algorithms docs

ce3ff86

Removed old deprecated algorithms and added the supported ones using the QCEF formulation. Also, replaced the old (unclear) localization image.

hkershaw-brown force-pushed the inf_docs branch from c655e45 to ce3ff86 Compare January 27, 2025 19:59

braczka added 3 commits January 30, 2025 08:18

Fix inflation table description

f97f7e3

Emphasize obs_impact_tool and inflation

1d4e100

inflation docs syntax correction

68a92c1

braczka reviewed Jan 30, 2025

View reviewed changes

mgharamti commented Jan 30, 2025

View reviewed changes

braczka reviewed Jan 30, 2025

View reviewed changes

braczka approved these changes Jan 30, 2025

View reviewed changes

mgharamti added 2 commits January 30, 2025 14:52

Clarified text

a38a894

Further clarification around inflation damping. Added text detailing the order of operations for inflation.

Improved Text: Inflation Order of Operations

a5ebed9

hkershaw-brown reviewed Jan 31, 2025

View reviewed changes

hkershaw-brown requested changes Jan 31, 2025

View reviewed changes

hkershaw-brown reviewed Jan 31, 2025

View reviewed changes

guide/inflation.rst Outdated Show resolved Hide resolved

mgharamti and others added 2 commits January 31, 2025 09:25

More guidance regarding inflation and no_copy_back

9668692

Some rewording to make thing clear

8c1498f

Co-authored-by: Helen Kershaw <[email protected]>

hkershaw-brown added the release! bundle with next release label Jan 31, 2025

Merge branch 'main' into inf_docs

69e12b2

hkershaw-brown approved these changes Feb 3, 2025

View reviewed changes

hkershaw-brown merged commit b4558ea into NCAR:main Feb 3, 2025
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated Inflation Documentation #806

Updated Inflation Documentation #806

mgharamti commented Jan 23, 2025

hkershaw-brown commented Jan 23, 2025

braczka commented Jan 23, 2025

hkershaw-brown commented Jan 27, 2025

jlaucar commented Jan 27, 2025 via email

hkershaw-brown commented Jan 27, 2025

hkershaw-brown commented Jan 27, 2025

mgharamti commented Jan 27, 2025

braczka commented Jan 30, 2025

hkershaw-brown commented Jan 30, 2025

hkershaw-brown commented Jan 30, 2025

braczka commented Jan 30, 2025

hkershaw-brown commented Jan 30, 2025

mgharamti commented Jan 30, 2025

braczka commented Jan 30, 2025

braczka commented Jan 30, 2025

braczka left a comment

braczka Jan 30, 2025

mgharamti Jan 30, 2025

braczka Jan 30, 2025

mgharamti Jan 30, 2025

mgharamti Jan 30, 2025

mgharamti Jan 30, 2025

braczka Jan 30, 2025

mgharamti Jan 30, 2025 •

edited

Loading

braczka left a comment

braczka Jan 30, 2025

hkershaw-brown Jan 31, 2025

mgharamti Jan 31, 2025

hkershaw-brown left a comment

		1. Start without any inflation; i.e., ``inf_flavor = 0, 0`` and assess the performance. For a healthy ensemble
		DA system, one expects the prior RMSE and the total spread to be of the same order. We often use the ensemble

Updated Inflation Documentation #806

Updated Inflation Documentation #806

Conversation

mgharamti commented Jan 23, 2025

Description:

Fixes issue

Types of changes

Documentation changes needed?

Tests

Checklist for merging

Checklist for release

Testing Datasets

hkershaw-brown commented Jan 23, 2025

braczka commented Jan 23, 2025

hkershaw-brown commented Jan 27, 2025

jlaucar commented Jan 27, 2025 via email

hkershaw-brown commented Jan 27, 2025

hkershaw-brown commented Jan 27, 2025

mgharamti commented Jan 27, 2025

braczka commented Jan 30, 2025

hkershaw-brown commented Jan 30, 2025

hkershaw-brown commented Jan 30, 2025

braczka commented Jan 30, 2025

hkershaw-brown commented Jan 30, 2025

mgharamti commented Jan 30, 2025

braczka commented Jan 30, 2025

braczka commented Jan 30, 2025

braczka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mgharamti Jan 30, 2025 • edited Loading

Choose a reason for hiding this comment

braczka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hkershaw-brown left a comment

Choose a reason for hiding this comment

mgharamti Jan 30, 2025 •

edited

Loading