Adding new features to WRF scripting and tutorial

[braczka]

Description:

This adds several new important features when running WRF-DART. This imposes a mandatory fix which should improve forecasting skill, but also adds features requested by users regarding commonly used scientific setups and diagnostics.

1. Generalizes scripting to apply to multiple domain (nested) WRF DA setups.
2. Adds a new scientific tutorial example with nested setup (Kansas Derecho), which is also back-compatible with prior CONUS severe storm tutorial example. Tutorial designed to be less computationally expensive (than CONUS tutorial) for ease of use.
3. Imposes mandatory terrain-following atmospheric coordinate setup (opposed to default sigma-hybrid) to eliminate boundary condition bug during perturbation step. This fix has shown to improve forecasting skill.
4. Scripting includes built-in downscaling technique to pass perturbations from parent domain to nested domain.
5. Adds full work through of the generation of perturbations using WRFDA CV3. Prior tutorial skipped through this step and required the user to download perturbations manually.
6. Makes bash scripting the default scripting language. Prior csh language is limited in functionality and many users systems do not support csh (e.g. problems with loading modules etc.) This PR includes csh nested scripting as a backup reference.
7. Adds full description of switching between "assimilation mode" and "forecast mode" using namelist settings. Most WRF users apply forecasting after the assimilation period for scientific applications.

Fixes issue

Fixes issues #807 and imposes Kansas Derecho example as described in that issue.

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.
  This change requires new documentation for the Kansas Derecho tutorial that supplants the prior CONUS tutorial example. The documentation parallels the prior documentation, but will add important new features such as 1) perturbation downscaling, 2) forecast mode, 3) expanded diagnostics.

Tests

I have tested the default bash scripting on the Kansas Derecho WRF-DART example. Completed example is located here: /glade/derecho/scratch/bmraczka/WRFv4.5_kansas.
I have tested csh nested scripting (backup) here: /glade/derecho/scratch/bmraczka/WRFv4.5_nested_hybridopt_0

Testing for backcompatibility of the CONUS tutorial example is here:

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

The Kansas Derecho tutorial example requires NCEP observation (obs_seq) files for the application. For now these are located here: /glade/work/bmraczka/DART/observations/obs_converters/NCEP/ascii_to_obs/work Existing prep_bufr obs converter documentation was used to create these obs.

[braczka]

The bash and csh scripting designed for a nested WRF DA setup included in this PR seems robust as it has been tested for Kansas Derecho and CONUS examples. This PR still requires tutorial documentation for Kansas Derecho tutorial example. Seemed relevant to add this PR now as a draft considering the number of WRF-DART users who are converting csh to bash on their own, which could lead to problems. Better to provide a vetted bash scripting version now to help reduce support issues.

[braczka]

Backcompatiblity for the new multi-domain shell scripting tested for the original (old) CONUS single WRF domain setup here: /glade/derecho/scratch/bmraczka/WRFv4.5_conus/. Produces similar scientific results.

[mgharamti]

@braczka, I'm done going through the tutorial material. Big effort for sure!

I've made a lot of suggestions and comments. For the major scripts such as the driver and the initial ensemble, I think they would benefit from a restructuring using functions. I provided some examples on my scratch if you would like to take a look or adapt them. I find it easier to debug things when operations are itemized within functions that have specific usage.

There is I believe an issue in the current form of init_ensemble_var right before downscaling. I left some comments to address the issue (has to do with domain numbering). At the beginning of the driver, I saw a duplicate use of loops when calling prep_ic. Have a look at my comments for more details. And by the way, I ended up running prep_ic in the shell myself (without having to submit those). I understand maybe in bigger domains, this may not be possible. I also made few comments of the old csh files, particularly when using multiple domains (specifically, more than 2).

The new forecast and diagnostic parts are a great addition. Just make sure we're putting everything in forecast mode (for instance not creating inflation directory) before we run the driver. I like the explanation of the diags; it reminded me of the CLM tutorial.

[braczka]

@braczka, I'm done going through the tutorial material. Big effort for sure!

I've made a lot of suggestions and comments. For the major scripts such as the driver and the initial ensemble, I think they would benefit from a restructuring using functions. I provided some examples on my scratch if you would like to take a look or adapt them. I find it easier to debug things when operations are itemized within functions that have specific usage.

There is I believe an issue in the current form of init_ensemble_var right before downscaling. I left some comments to address the issue (has to do with domain numbering). At the beginning of the driver, I saw a duplicate use of loops when calling prep_ic. Have a look at my comments for more details. And by the way, I ended up running prep_ic in the shell myself (without having to submit those). I understand maybe in bigger domains, this may not be possible. I also made few comments of the old csh files, particularly when using multiple domains (specifically, more than 2).

The new forecast and diagnostic parts are a great addition. Just make sure we're putting everything in forecast mode (for instance not creating inflation directory) before we run the driver. I like the explanation of the diags; it reminded me of the CLM tutorial.

@mgharamti Appreciate this thorough review. I adopted and tested the function based refactor code you made. Just had to make a few changes to preserve the proper transfer of inflation files as to not break the filter functionality. Vast majority of suggestions have been included in latest commits, but I still need to run through a few more, then test on single domain example. Will get back to this next week.

[braczka]

@mgharamti I have completed making all changes based on your review. This includes the adoption of your function-based shell scripting for driver.sh and init_ensemble_var.sh, as well as addressing all of your general comments. At your suggestion I also simplified the bash scripting to remove all non-functional double quotes to help readability. I tested these scripts on both the WRF nested domain kansas example (included as part of this PR), and the CONUS single domain (the old WRF-DART tutorial example). These examples all ran to completion, and the DA diagnostics appeared reasonable to my benchmark runs. This looks to be ready to merge into an upcoming release. Please take a look as needed.

@mjs2369 @hkershaw-brown I realize the timing is not ideal given Helen's current travel. It would be good for Helen to give this a peak prior to release. We also have several WRF-DART user's currently working with nested DA examples, so I think it will be helpful to get this out there soon....

[mgharamti]

Looks good to me. Good stuff Brett !

[mjs2369]

@braczka sounds good, unless you let me know differently, we will wait for Helen to get back before releasing.

[jlaucar]

Yes, please wait on Helen. Jeff

…

On Tue, Mar 31, 2026 at 4:09 PM Marlena Smith ***@***.***> wrote: *mjs2369* left a comment (NCAR/DART#1030) <#1030?email_source=notifications&email_token=ANDHUIWU4VUHKGPMZX4UJK34TQ6Z7A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJWGU4DQNJZHA42M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOS2XA4S7MNXW23LFNZ2F633QMVXF6Y3MNFRWW#issuecomment-4165885989> @braczka <https://github.com/braczka> sounds good, unless you let me know differently, we will wait for Helen to get back before releasing. — Reply to this email directly, view it on GitHub <#1030?email_source=notifications&email_token=ANDHUIWU4VUHKGPMZX4UJK34TQ6Z7A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJWGU4DQNJZHA42M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOS2XA4S7MNXW23LFNZ2F633QMVXF6Y3MNFRWW#issuecomment-4165885989>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ANDHUISZFZBXGSOH2UAYFOD4TQ6Z7AVCNFSM6AAAAACQ3A72F2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCNRVHA4DKOJYHE> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[hkershaw-brown]

Hi @braczka,

The branch needs to be up-to-date with main, and @mgharamti needs to click approve.

Update CHANGELOG.rst and conf.py (with version number v11.22.0 or whatever version number is is appropriate).
Then merge!

Here is the info on creating a release:
https://ncar.github.io/dart-developers-guide/releases.html

Cheers,
Helen