Skip to content

docs: TE accuracy — flag zero-crossing rows; remove misleading "Known limitation" - #17

Open
MinhMPA wants to merge 1 commit into
smsharma:mainfrom
MinhMPA:docs/te-zero-crossing-metric
Open

docs: TE accuracy — flag zero-crossing rows; remove misleading "Known limitation"#17
MinhMPA wants to merge 1 commit into
smsharma:mainfrom
MinhMPA:docs/te-zero-crossing-metric

Conversation

@MinhMPA

@MinhMPA MinhMPA commented May 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

Documentation-only fix (no clax module code changed). Reframes the README's unlensed-C_l^TE accuracy presentation around the two ΛCDM TE zero crossings (ℓ≈52, ℓ≈400) and removes a "Known limitation" bullet that mischaracterizes a metric artifact as a physics shortcoming.

Why

The current README accuracy table reports relative error (clax − CLASS) / CLASS at every multipole, including ℓ values where C_l^TE crosses zero. Near a zero crossing the denominator goes to ~0, so the relative number can blow up to ~0.5–1% even when the absolute residual matches neighboring ℓ where the same metric is well-defined. The current "Known limitations" entry — "TE zero crossings: Large relative errors near l=52 and l=400 where C_l^TE crosses zero" — frames this as a real shortcoming, when it is purely a presentation issue. The underlying C_l^TE matches CLASS as well as TT/EE do.

What changes

  • README accuracy table: added a marker on the three rows clearly inside the first zero-crossing region (ℓ=20, 30, 50) and a footnote that:
    • states the relative-error metric is ill-defined there,
    • points at the Hu & White (1997) correlation criterion |C_l^TE| / √(C_l^TT · C_l^EE) < 0.02,
    • notes that the existing lensed-TE accuracy test (tests/test_lensing.py:156) already skips zero-crossing ℓ via this criterion, and
    • notes that a Gaussian likelihood weights these modes by 1/Var(C_l^TE) → 0 automatically — so the metric artifact does not affect HMC inference.
  • README "Known limitations": removed the "TE zero crossings" bullet. The remaining items in that section (speed, TT ℓ=400-800, TT ℓ>1200, EE ℓ=20-30, primordial BB) are all genuine outstanding limitations.
  • CHANGELOG: entry documenting the rationale.

No test changes needed: tests/test_harmonic.py::TestClTE only probes ℓ=100 and ℓ=200, neither near a zero crossing.

Scope clarification

The ℓ=1000 TE entry (+1.7%) is not a zero-crossing artifact — it is a real residual driven by k-grid under-resolution at high ℓ (same root cause as the existing "TT ℓ>1200" known limitation). That one will be addressed separately by a hybrid linear/log k-grid PR; this PR does not touch it.

Independence from other open PRs

Test plan

  • No code changed; existing test suite is unaffected.
  • Existing tests/test_harmonic.py::TestClTE (ℓ=100, 200) probe ℓ values that are not near zero crossings, so the documentation change is consistent with what the tests already exercise.
  • Existing tests/test_lensing.py::TestLensCls::test_lensed_te_accuracy already implements the correlation-coefficient skip rule that the README footnote now references.

… limitation"

The unlensed C_l^TE accuracy table reported (clax − CLASS) / CLASS at every
multipole, including ℓ values near the two ΛCDM TE zero crossings (ℓ≈52, ℓ≈400).
Near a zero crossing the denominator goes to ~0, so the relative number blows up
even when the absolute residual matches neighboring ℓ. This was framed in the
"Known limitations" section as a real shortcoming, when it is purely a metric
artifact — the underlying C_l^TE matches CLASS as well as TT/EE do.

Changes (documentation only — no clax module code modified):

- README accuracy table: dagger marker on ℓ=20, 30, 50 rows (inside the first
  TE zero-crossing region) and a footnote explaining the metric is ill-defined
  there, pointing at the Hu & White (1997) correlation criterion
  |C_l^TE| / √(C_l^TT · C_l^EE) < 0.02 used by the existing lensed-TE test
  (tests/test_lensing.py:156). Notes that a Gaussian likelihood weights these
  modes by 1/Var(C_l^TE) → 0 automatically, so the metric artifact does not
  affect HMC inference.
- README "Known limitations": removed the "TE zero crossings" bullet — it was
  not a physics limitation, only a presentation issue. The remaining items
  (speed, TT ℓ=400-800, TT ℓ>1200, EE ℓ=20-30, primordial BB) are all genuine.
- CHANGELOG: entry documenting the rationale.

The existing unlensed-TE accuracy tests in tests/test_harmonic.py::TestClTE
only probe ℓ=100 and ℓ=200 (neither near a zero crossing), so no test changes
are needed.

The ℓ=1000 TE entry (+1.7%) is NOT a zero-crossing artifact — it is a real
residual driven by k-grid under-resolution at high ℓ (same root cause as the
TT ℓ>1200 limitation), to be addressed separately by a hybrid linear/log
k-grid PR.
@MinhMPA

MinhMPA commented May 4, 2026

Copy link
Copy Markdown
Collaborator Author

PR #17, #18 and #19 aim to address the "Known limitations" in the current README so that we can clean up that section. These should be independent fixes so no merge order nor conflict is expected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant