Add stage "assim" and optional obs_seq write to outline

[kdraeder]

Description:

The "Detailed program execution" in filter.rst is missing the "assim" stage. I also added a line about the optional writing of partial obs_seq file contents.

What difference can there be between the "assim" and "output" stages? It's not the posterior inflation; that's done before "assim".

Fixes issue

#227

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)
• [x] Documentation update

Documentation changes needed?

• [x] My change requires a change to the documentation.
  • [x] I have updated the documentation accordingly.

Tests

I remade the documentation with make html operating on this new branch.

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

[nancycollins]

hi kevin, to answer your question about assim vs output files -- the difference is when filter cycles multiple times without exiting, like for the lower order models. the assim files have a time series of states, while output only has the last model state and can be used as a restart file.

[kdraeder]

hi kevin, to answer your question about assim vs output files -- the difference is when filter cycles multiple times without exiting, like for the lower order models. the assim files have a time series of states, while output only has the last model state and can be used as a restart file.

Thanks! I had just figured that out and was about to comment on it. I've tweaked the rst outline to reflect that 'output' is written after the AdvanceTime loop.

[kdraeder]

Hi Kevin,

I started reviewing this, the changes are ok. I think the observation writing comment is a bit misleading.

But then I read the whole page ...

It looks like I've opened another can-o-worms . . . Tell me which of these things (and ...?) should be fixed in this PR versus opening another.

[hkershaw-brown]

Hi Kevin, I started reviewing this, the changes are ok. I think the observation writing comment is a bit misleading. But then I read the whole page ...

It looks like I've opened another can-o-worms . . . Tell me which of these things (and ...?) should be fixed in this PR versus opening another.

I think if you're fixing "Detailed Program Execution of filter" then it needs fixed in the documentation as a whole.

[hkershaw-brown]

hot take: let's take an hour or so at the CISL in person to sort out the structure of the dart documentation.

[nancycollins]

something to think about before a documentation discussion: best advice i got from a documentation writer at IBM was decide who your audience is when you're writing each part of the docs. new user, power user, developer, manager/funding agent, etc.

[kdraeder]

something to think about before a documentation discussion: best advice i got from a documentation writer at IBM was decide who your audience is when you're writing each part of the docs. new user, power user, developer, manager/funding agent, etc.

Excellent advice! I also find it helpful to have that information in the documentation that I'm reading, as a guide to what I should read. The TeX Book does this extensively using some sort of "hazardous road" sign(s) on sections that go into the weeds.

[kdraeder]

Hi Kevin, I started reviewing this, the changes are ok. I think the observation writing comment is a bit misleading. But then I read the whole page ...

It looks like I've opened another can-o-worms . . . Tell me which of these things (and ...?) should be fixed in this PR versus opening another.

I think if you're fixing "Detailed Program Execution of filter" then it needs fixed in the documentation as a whole.

I started looking into the "If you want to try out a different filter type"... and quickly found that I don't know in detail how the filter type is defined in the new QCEFF framework, so I'm not prepared to fix that section of filter.rst.

[hkershaw-brown]

Hi Kevin, closing this as we chatted about at the CISL in person week