# Spectral Filtering Accuracy

PyStormTracker currently uses `ducc0` for spherical harmonic transforms in spectral filtering, regridding, and the calculation of kinematic derivatives. `SHTns` was used during early development. The benchmarks below are retained for reference.

## Methodology

The recorded comparisons use root mean square error (RMSE), relative error, and Pearson correlation for ERA5 mean sea level pressure and wind data. Reference fields generated by `tests/data/era5/process_era5.ncl` are checked in under `tests/data/era5` and treated as the expected outputs for ducc0 spectral and kinematic integration tests.

Two spatial resolutions are tested:
- **2.5°x2.5°**: A low-resolution grid (73x144) where T42 truncation (requiring ~85 latitudes) results in aliasing.
- **0.25°x0.25°**: A high-resolution grid (721x1440) where T42 truncation is alias-free.

## Spherical Harmonic Transform (SHT) Engines

### 1. ducc0 (Current)
`ducc0` is the current spherical harmonic transform engine.

*   It is installed as a core dependency.
*   It provides two-dimensional spherical harmonic analysis and synthesis on Clenshaw-Curtis and Gauss-Legendre grids, pseudo-analysis for reduced Gaussian grids, arbitrary-point synthesis, spin-1 vector transforms, and HEALPix geometry used by this project.
*   The tables below report the differences relative to reference fields generated by NCL.

### 2. SHTns
`SHTns` was a spherical harmonic transform engine in earlier versions, but it has been removed from the package code and dependencies.

## Accuracy & Performance Metrics

### Spectral Filtering (MSL)

#### Cross-Engine Accuracy (vs NCL Reference)

**Resolution: 2.5°x2.5° (ERA5)**

*Note: Higher error in this resolution is primarily due to aliasing on the coarse grid.*

| Engine | Truncation | RMSE (Pa) | Rel. Error | Correlation | Time (s) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **SHTns** | T5-42 | 0.45711949 | 6.40e-04 | 0.999999897272 | 0.0350 |
| **ducc0** | T5-42 | 0.05266872 | 7.37e-05 | 0.999999998663 | 0.0030 |
| **SHTns** | T0-42 | 0.45729944 | 4.53e-06 | 0.999999918845 | 0.0009 |
| **ducc0** | T0-42 | 0.05369308 | 5.31e-07 | 0.999999998880 | 0.0019 |

**Resolution: 0.25°x0.25° (ERA5)**

*Note: This resolution satisfies the sampling requirement for the recorded T42 comparison.*

| Engine | Truncation | RMSE (Pa) | Rel. Error | Correlation | Time (s) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **SHTns** | T5-42 | 0.00003643 | 5.16e-08 | 1.000000000000 | 0.0665 |
| **ducc0** | T5-42 | 0.01276583 | 1.81e-05 | 0.999999999928 | 0.0041 |
| **SHTns** | T0-42 | 0.00486497 | 4.81e-08 | 0.999999999994 | 0.0141 |
| **ducc0** | T0-42 | 0.02114745 | 2.09e-07 | 0.999999999831 | 0.0038 |

### Kinematic Derivatives (Vorticity & Divergence)
*Evaluated on 0.25°x0.25° ERA5 grid. Comparison against NCL `uv2vrdvF` reference.*

| Engine | Variable | RMSE (s⁻¹) | Correlation | Time (s) |
| :--- | :--- | :--- | :--- | :--- |
| **SHTns** | Vorticity | 9.05e-06 | 0.9899 | 0.1017 |
| **ducc0** | Vorticity | **1.74e-14** | **1.0000** | **0.0576** |

## SHTns Polar-Optimization

For the recorded 0.25° SHTns run, disabling the polar optimization threshold (`polar_opt=0.0`) produced:
- **Accuracy**: RMSE difference is negligible (~10⁻¹⁵ Pa).
- **Performance**: The default setting is approximately 1.25% faster.