E3SM-Project / E3SM-Project/zppy
tc_analysis: grids other than ne30/ne120 (e.g. ne256pg2) fail on the hard-coded warm-core threshold
- Dominant language
- Python
- Stars
- 8
- Forks
- 16
- Avg merge
- 3d 21h
- Merged PRs (30d)
- 3
Description
## Summary
`tc_analysis` fails for any grid other than `ne30` or `ne120`. @whannah1 running EAMxx at `ne256pg2` hit this: the task exits with `ERROR (13)` and `ERROR: 256 value not supported`.
## Root cause
There is exactly one resolution-gated block in the whole task, `zppy/templates/tc_analysis.bash:232-243`:
```bash
if [ "${res}" == 120 ]; then
echo "${res}"
temp_threshold_radius=0.30
elif [ "${res}" == 30 ]; then
echo "${res}"
temp_threshold_radius=1.0
else
echo "ERROR: ${res} value not supported"
cd {{ scriptDir }}
echo 'ERROR (13)' > {{ prefix }}.status
exit 13
fi
```
`temp_threshold_radius` feeds the 4th field of the TC `--closedcontourcmd` at `tc_analysis.bash:247`:
```
_AVG(${var_t200},${var_t500}),-0.6,4,${temp_threshold_radius}
```
i.e. TempestExtremes' `minmaxdist` — how far from the SLP minimum to search for the warm-core maximum. It is an empirically tuned number that shrinks with grid spacing (ne30 ≈ 110 km → 1.0°, ne120 ≈ 27 km → 0.30°).
Everything else in the task is already resolution-agnostic:
- `GenerateCSMesh --res ${res}` (`:121`, `:151`)
- `GenerateVolumetricMesh` (`:134`) and `GenerateConnectivityFile`
- `StitchNodes` for TCs (`:274-283`) and AEWs (`:359-370`) — degree- and timestep-based
- `DetectNodes` for AEWs (`:333-343`) and both `HistogramNodes` calls
So `ne256pg2` would run end to end if that single value were defined. Grid parsing already accepts it: `input_grid` is matched with `^ne([0-9]+)(pg2|np4)$` at `tc_analysis.bash:38`, so `res=256` and `pg2=true` are derived correctly — the job only dies later at the threshold lookup.
## Proposed fix
Add an opt-in parameter to `[tc_analysis]` in `zppy/defaults/default.ini`:
```ini
# TempestExtremes warm-core search radius (minmaxdist, degrees) used in the TC
# --closedcontourcmd. Leave empty to use the tuned defaults (ne30 -> 1.0,
# ne120 -> 0.30). Must be set explicitly for other resolutions.
tc_temp_threshold_radius = string(default="")
```
and in the template, use it when set, otherwise fall back to the existing lookup. Since #828 already refactored the two duplicated `DetectNodes` calls into a single call driven by `temp_threshold_radius`, this is a small change confined to that block.
When the parameter is unset and `res` is not a tuned value, I'd keep it a hard error rather than guessing — the threshold directly changes detected TC counts, so zppy should not silently invent a detection threshold for a science metric. The error message should name the parameter, e.g.:
```
ERROR: no tuned warm-core threshold for res=256. Set tc_temp_threshold_radius
in [tc_analysis] (ne30 uses 1.0, ne120 uses 0.30).
```
This is fully backward compatible: existing ne30/ne120 cfgs are unaffected.
## Open question for TC folks
What is the appropriate `minmaxdist` for `ne256pg2` (~13 km)? Reusing ne120's `0.30` is a reasonable starting point — it is still roughly 2.5 grid cells at that spacing, and it is the finest value tuned for E3SM so far — but it has not been validated at ne256, and we need to quantify how TC counts are sensitive to it. Input from the TC analysis developers would be welcome, both for the recommended value and for whether the AEW block's fixed thresholds (`VORT,-5.e-6,4,0`, `--mergedist 2.0`) also need resolution-dependent tuning at this scale.
Reported against `main` at `8c4a4afc`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with zppy/templates/tc_analysis.bash:232-247 and the [tc_analysis] section of zppy/defaults/default.ini; trace how tc_temp_threshold_radius would reach the --closedcontourcmd minmaxdist field. Preserve the existing ne30 and ne120 defaults, require the parameter for other resolutions, and run tc_analysis with supported and unsupported grids to verify the error and fallback behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bash
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100