Skip to content

Add DynamicSVD demo notebook (Fisher-information validation)#116

Open
cweniger wants to merge 1 commit into
mainfrom
notebook/dynamic-svd-demo
Open

Add DynamicSVD demo notebook (Fisher-information validation)#116
cweniger wants to merge 1 commit into
mainfrom
notebook/dynamic-svd-demo

Conversation

@cweniger

Copy link
Copy Markdown
Owner

Implements the notebook part of #114.

What

A new notebooks/ directory with an idealized, self-contained demo of falcon.embeddings.DynamicSVD — n = 100 data bins, 4-parameter models, exact Fisher-information ground truth from autograd (F = Jᵀ C⁻¹ J), no falcon runs and no estimator training. Four sections, each isolating one capability:

  1. Basics — linear model + white noise: why variance ranking finds the informative subspace; compression 100 → 8 dims is lossless (information ratio ≈ 1).
  2. How many components? — non-linear Gaussian-bump model: information ratio vs. k as a family over prior widths (wider prior ⇒ more components, the static picture of adaptive-round narrowing), multi-fiducial adequacy check, scree plot with unit noise floor, and Wiener shrinkage — explicitly framed as conditioning, not information (Fisher is invariant under it), demonstrated via per-component output variances and reconstruct(). Ends with the σ = 10 case exposing the hard-coded noise floor (DynamicSVD shrinkage assumes unit noise floor; shrinkage=False also disables normalization #113).
  3. Streaming & Procrustes — one continuous prior-narrowing sweep, comparing two views of the same run: raw index-ordered components (sign flips and swaps at eigenvalue crossings) vs. the Procrustes-stabilized frame (smooth deformation), plus a basis-jump trace and the coefficients of a fixed observation across updates.
  4. Colored noise — same model, noise from a non-trivial PSD (Toeplitz covariance): degraded Fisher ellipses and broken noise floor without whitening; ToeplitzWhitener restores both.

Infrastructure

  • notebooks/jupytext.toml pairs every notebook in the directory as ipynb,py:percent. The .py file is the reviewable source of truth; the .ipynb is what GitHub renders and Colab opens.
  • The notebook carries an Open in Colab badge and a pure-Python self-bootstrap cell (installs falcon from GitHub when missing; torch/numpy are preinstalled on Colab). All data is synthetic, seeds are fixed, no repo-relative paths.

Not in this PR (deliberately)

🤖 Generated with Claude Code

https://claude.ai/code/session_01KUwdQQh7Vr9ArkBE9ahZGG

Idealized, self-contained demonstration of falcon.embeddings.DynamicSVD
(n=100 bins, 4-parameter models, exact autograd Fisher ground truth):

1. Basics — linear model, white noise: variance ranking finds the
   informative subspace; compression to 8 components is lossless.
2. How many components? — non-linear bump model: information ratio vs k
   as a function of prior width, multi-fiducial adequacy, scree plot with
   noise floor, Wiener shrinkage (conditioning, not information), and the
   hard-coded unit-noise-floor limitation (#113).
3. Streaming & Procrustes — continuous prior narrowing; raw index-ordered
   basis vs stabilized frame (sign flips/swaps vs smooth drift), basis-jump
   trace, fixed-observation coefficient trace.
4. Colored noise — PSD-sampled Toeplitz noise degrades the embedding;
   ToeplitzWhitener restores Fisher ellipses and the flat noise floor.

The notebook is paired with a py:percent script via jupytext
(notebooks/jupytext.toml); the .py file is the reviewable source of
truth, the .ipynb is what GitHub renders and Colab opens (badge +
self-bootstrap cell included). Outputs not yet committed; CI execution
and docs rendering are tracked in #114.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KUwdQQh7Vr9ArkBE9ahZGG
@codecov

codecov Bot commented Jul 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 10.33%. Comparing base (d3c33ba) to head (76e0a6a).

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #116   +/-   ##
=======================================
  Coverage   10.33%   10.33%           
=======================================
  Files          30       30           
  Lines        3927     3927           
=======================================
  Hits          406      406           
  Misses       3521     3521           
Flag Coverage Δ
unit 10.33% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

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