doc: Relocate pdfs for DART_LAB and DART tutorial.

[hkershaw-brown]

Description:

This pull request relocates pdfs for DART_LAB and the DART tutorial to outside the NCAR/DART repo.

• The pdfs are hosted on https://ncar.github.io/dart-tutorial/ and can be updated on that repo: https://github.com/NCAR/dart-tutorial.
• Note DART tutorial is now one section, DART_LAB part 6. Embedded this in the DART tutorial rst page.
• Deleted old DART tutorial (slides section 1-25)
• Rewrote DART_LAB intro to say it is a Matlab based tutorial
• Reorded the tutorial in the table of contents to have DART_LAB before the DART tutorial
• Added the lorenz_96 input files needed for the tutorial (this is the +450,297 lines)

Note the website has an old-old version of the DART Tutorial. That will be switched out once this pull request is okayed (or not).

Fixes issue

Fixes #725
See #810 for conversation on removing old dart tutorial.
⚠️ Todo add lorenz_96 input files from https://github.com/NCAR/DART/pull/810/files done

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.

Built documentation locally, clicky-click links. Tested pdf embedding: chrome, firefox, safari.

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]

Doc build for this pull request:

https://dart-documentation--985.org.readthedocs.build/en/985/guide/DART_LAB/DART_LAB.html
https://dart-documentation--985.org.readthedocs.build/en/985/theory/readme.html

[hkershaw-brown]

@mjs2369 assigning this to you in case @jlaucar wants to merge this while I am out.

[mjs2369]

Aside from the slides themselves (which I didn't review), this is looking good.

I'm a little unsure about the DART Tutorial now being section 6 of the DART_LAB. I get that it builds on the information from sections 1-5, but it is distinct in that the DART_LAB teaches the fundamentals of DA while the DART Tutorial teaches you to actually use DART. It definitely makes it feel like you would need to go through sections 1-5 first as a new user, even if you are already knowledgeable about the concepts of ensemble DA. Maybe just adding a note to the documentation about how if you do already have this knowledge, you can go ahead and start with section 6?

Finally, do we need the 3 identity_obs_XX.input files in both models/lorenz_96/ and models/lorenz_96/work ?

[hkershaw-brown]

Aside from the slides themselves (which I didn't review), this is looking good.

Kevin reviewed the slides a while ago in pull #810

I'm a little unsure about the DART Tutorial now being section 6 of the DART_LAB. I get that it builds on the information from sections 1-5, but it is distinct in that the DART_LAB teaches the fundamentals of DA while the DART Tutorial teaches you to actually use DART. It definitely makes it feel like you would need to go through sections 1-5 first as a new user, even if you are already knowledgeable about the concepts of ensemble DA. Maybe just adding a note to the documentation about how if you do already have this knowledge, you can go ahead and start with section 6?

I share this concern, however this is how Jeff wants the tutorial to be.

Do you mean add a note in the DART_LAB section https://dart-documentation--985.org.readthedocs.build/en/985/guide/DART_LAB/DART_LAB.html, something like "If you are already familiar with ensemble DA, you can skip straight to using [DART](link to DART_LAB_section6)". Is that enough to direct people to DART who want to skip the Matlab?

Finally, do we need the 3 identity_obs_XX.input files in both models/lorenz_96/ and models/lorenz_96/work ?
Probably not, I will take a look. These files were in the branch used to teach DART_LAB 1-6 at Michigan.

[mjs2369]

Do you mean add a note in the DART_LAB section https://dart-documentation--985.org.readthedocs.build/en/985/guide/DART_LAB/DART_LAB.html, something like "If you are already familiar with ensemble DA, you can skip straight to using [DART](link to DART_LAB_section6)". Is that enough to direct people to DART who want to skip the Matlab?

Yeah I think that will be good

[jlaucar]

Making clear the relation between section 6 and the 5 original sections is a key point. I think Marlee's suggestion makes it work. I think a user that does the first 5 sections themselves will have no confusion about what is going on. The real issue is folks who just want to do the DART part and how they would find this section from the higher level documentation. I don't think we know how many users use DART_LAB without being sent there by a DAReS person or being a participant in a formal tutorial.

The identity_obs... files in both the Lorenz_96 model directory and work directory are required parts of the section 6 tutorial and should be in the repo.

As Helen notes, the slides have been vetted by Kevin and have been used in three live tutorials I've given with nearly 250 total participants including many DA experts. No doubt there are still errors, but I think they do not need any additional review at this time. The one thing that might be needed is for someone other than me to actually go through section 6 and try to do the suggested exercises. That should take less than an hour for a DAReS team member.

[mgharamti]

@jlaucar, I can volunteer to do that unless you think someone other than me should do it (given my DA background).

[jlaucar]

Moha, please go ahead and run through section 6, thanks.

[hkershaw-brown]

@jlaucar, I can volunteer to do that unless you think someone other than me should do it (given my DA background).
Moha, please go ahead and run through section 6, thanks.

Note the pdfs are not in the DART repo, they are here: https://github.com/NCAR/dart-tutorial.
Any review comments should go there or directly to Jeff.

[hkershaw-brown]

@todo add "this breaks bitwise" to release notes for out-of-the-box input.nml lorenz

[jlaucar]

Is the aether_michigan branch where Moha would find the additional low-order model files that are needed to run section6?

[hkershaw-brown]

Is the aether_michigan branch where Moha would find the additional low-order model files that are needed to run section6?

Nope. This branch dartlab-part6 https://github.com/NCAR/DART/pull/985/files

[hkershaw-brown]

I don't think we know how many users use DART_LAB without being sent there by a DAReS person or being a participant in a formal tutorial.

When GitHub insights is not down, we do get some info about this in the referring sites and popular content sections.
Right now only the # visitors & # cloners is available.
https://github.com/NCAR/DART/graphs/traffic

[hkershaw-brown]

Finally, do we need the 3 identity_obs_XX.input files in both models/lorenz_96/ and models/lorenz_96/work ?

The ones in lorenz_96 are input for create_obs_sequence, the ones in lorenz_96/work are input for perfect_model_obs.

lorenz_96
├── identity_obs.input
├── identity_obs_1_20.input
├── identity_obs_1_40_2.input
├── identity_obs_1_40_4.input
└── work
    ├── obs_seq_identity.in
    ├── obs_seq_identity_1_20.in
    ├── obs_seq_identity_1_40_2.in
    ├── obs_seq_identity_1_40_4.in

create_obs_sequence does not seem to be covered in the dart_lab slides part6, maybe covered live.

[mgharamti]

I've gone through section 6 and did all exercises. I found no issues.
Everything runs and works as suggested on the slides.

[hkershaw-brown]

Finally, do we need the 3 identity_obs_XX.input files in both models/lorenz_96/ and models/lorenz_96/work ?

The ones in lorenz_96 are input for create_obs_sequence, the ones in lorenz_96/work are input for perfect_model_obs.

lorenz_96
├── identity_obs.input
├── identity_obs_1_20.input
├── identity_obs_1_40_2.input
├── identity_obs_1_40_4.input
└── work
    ├── obs_seq_identity.in
    ├── obs_seq_identity_1_20.in
    ├── obs_seq_identity_1_40_2.in
    ├── obs_seq_identity_1_40_4.in

create_obs_sequence does not seem to be covered in the dart_lab slides part6, maybe covered live.

@mjs2369 I put a note in commit 366f2ba about what the models/lorenz_96 files are + there are the notes in this pull request, so whoever works with this in the future has some record of what the files are.