Background
Recent user reports highlight that the E3SM run script fails in a non-obvious way for hybrid or branch runs when:
do_case_build=false- No existing executable is present
- The user expects hybrid/branch variables (
GET_REFCASE, RUN_REFDIR, RUN_REFCASE, RUN_REFDATE) to be set in the case XML files
In this scenario, the script aborts at the case_build step, so runtime_options (where these variables are set via xmlchange) is never executed. This leads to default values persisting in the XML files, and users must manually edit them.
Additionally, confusion arises from the expected relationship between CASE_ROOT and build/run directories, which is not documented and can contribute to errors.
Requested Updates
Note that pull requests have to be made for two distinct repositories.
1. Run Script Improvements
These changes should go in E3SM/run_e3sm.template.sh
- Ensure that the script provides a clear, early error message when:
do_case_build=false and no executable is present- Hybrid/branch run options are set, but runtime_options will not be reached
- Consider refactoring the script logic so that
runtime_options can be executed even if case_build is skipped, provided an executable exists (via OLD_EXECUTABLE)
- Add sanity checks or warnings for directory layout mismatches (e.g., when
CASE_ROOT, build, and run directories are not colocated as expected)
2. Documentation Enhancements
These changes should go in E3SM-Project.github.io/docs/running-e3sm-guide/guide-production.md
- Update the README or script header to clearly describe:
- Typical workflows for initial runs, hybrid/branch runs, and reusing executables
- Required and recommended settings for each workflow, including flag combinations (
do_fetch_code, do_create_newcase, do_case_setup, do_case_build, do_case_submit)
- The importance of directory layout and how it affects script behavior
- That hybrid/branch variables are set during
runtime_options, which only runs if the script reaches that stage
- Provide troubleshooting guidance for common pitfalls (e.g., why XML variables may not be set as expected)
References
Summary:
Update both the run script and its documentation to make hybrid/branch workflows less error-prone and more transparent for users. Ensure error handling and guidance are clear, especially around build flag combinations and directory layout.
Background
Recent user reports highlight that the E3SM run script fails in a non-obvious way for hybrid or branch runs when:
do_case_build=falseGET_REFCASE,RUN_REFDIR,RUN_REFCASE,RUN_REFDATE) to be set in the case XML filesIn this scenario, the script aborts at the
case_buildstep, soruntime_options(where these variables are set viaxmlchange) is never executed. This leads to default values persisting in the XML files, and users must manually edit them.Additionally, confusion arises from the expected relationship between
CASE_ROOTand build/run directories, which is not documented and can contribute to errors.Requested Updates
Note that pull requests have to be made for two distinct repositories.
1. Run Script Improvements
These changes should go in E3SM/run_e3sm.template.sh
do_case_build=falseand no executable is presentruntime_optionscan be executed even ifcase_buildis skipped, provided an executable exists (viaOLD_EXECUTABLE)CASE_ROOT, build, and run directories are not colocated as expected)2. Documentation Enhancements
These changes should go in E3SM-Project.github.io/docs/running-e3sm-guide/guide-production.md
do_fetch_code,do_create_newcase,do_case_setup,do_case_build,do_case_submit)runtime_options, which only runs if the script reaches that stageReferences
Summary:
Update both the run script and its documentation to make hybrid/branch workflows less error-prone and more transparent for users. Ensure error handling and guidance are clear, especially around build flag combinations and directory layout.