Skip to content

fix: correct scalar KL arithmetic and plot argument handling - #30

Open
aidanmoller wants to merge 1 commit into
mainfrom
fix-scalar-kl-correctness
Open

aidanmoller wants to merge 1 commit into
mainfrom
fix-scalar-kl-correctness

Conversation

@aidanmoller

Copy link
Copy Markdown
Contributor

Numerical fixes and runtime cost

  • Preserve small positive variance ratios that were being lost before taking their logarithm.
  • Recover finite KL signal and dispersion values when an intermediate calculation overflows.
  • These fixes recover valid finite results but with a runtime cost: the scalar helper was 19.5% slower per pair (extra 1.25 microseconds per call) and 9.1% slower on the tested vector workload.

Plots, examples and documentation

  • Allow custom plot labels and limits without duplicate argument errors.
  • Correct the example’s count of anchors whose observation windows reach the record end.
  • Correct range-status explanations, including the unsupported claim that a censored range is necessarily a lower bound.
  • Explain which lag limits apply to streamed results and retained tables.
  • Explain why refining a threshold grid cannot recover contributions outside its integration interval.

Optional precision improvement (not in this commit)

  • The fix: An alternative formula more accurately retains small contributions when two variances are almost identical, as currently rounding can turn a tiny positive KL dispersion value to zero.
  • Why it was deferred: benchmarked 39.2% slower (different baseline to this PR, so it is purely indicative and would need to be remeasured)
  • Let me know if the precision benefit warrants the cost, or if it would help to find a faster method, and I can push the changes here.

Numerical fixes and runtime cost
• Retain small variance ratios before taking logarithms.
• Recover finite signal and dispersion after intermediate overflow.
• These fixes increase ordinary scalar helper time by 19.5% per pair and
  9.1% for the tested vector workload.
• Exclude the slower series calculation for nearly equal variances.

Plots and documentation
• Allow plot labels and limits to override defaults without argument errors.
• Correct the online example's count of anchors reaching the record end.
• Remove the claim that a censored range is necessarily a lower bound.
• Explain streamed/retained lag limits and the finite threshold interval.

Validation
• Add regression tests for small ratios, overflow and plot arguments.
• Pass 7,784 assertions and saved MATLAB comparisons at existing tolerances.
• Local package check: zero errors, zero warnings, one HTML validation note.
@aidanmoller
aidanmoller requested a review from max578 as a code owner November 18, 2026 10:19

@max578 max578 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Aidan,

Thanks, this looks good and I am approving. I graded the scalar kernel on ea66bd0 against a 2000-bit Rmpfr reference on the exact inputs, with inputs chosen to reach each new branch: small and subnormal variance ratios, ratio overflow, and signals across the overflow midpoint. Everything is within 3 ulp, where b0f7141 gave Inf or NaN in each of those sets. Ordinary signals are bit-identical to b0f7141. The new tests fail on b0f7141, and the full suite passes here, as does test-15 with the external MATLAB fixtures.

One nit, not blocking. The plot methods now drop unnamed arguments in ... without a warning, because modifyList() ignores elements without names. On b0f7141, plot(cr, c(0, 5)) passed c(0, 5) to plot.default() as xlim. On ea66bd0 the x-axis stays at the default range. Could you pass unnamed arguments through, or warn when they are dropped?

Best wishes,

Max

This branch has not been deployed

No deployments
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.

2 participants