hv-hologram-rhythm

Tiny NumPy-only hologram + rhythm compression for feature maps with a time axis. No PyTorch, no GPU, no training. Fits in one file.

Given feature maps X of shape (N, C, T) — batch, channels, time — the model learns a shared low-rank channel basis and a per-sample per-time-frame rhythm projection onto that basis.

The time axis is preserved. Only the channel rank is reduced. This is what distinguishes it from global average pooling (GAP), which collapses time and discards temporal structure.

TL;DR

Input	(N, C, T) feature maps
Output	rhythm (N, r, T) at rank r, typically r = 6..16
Dependencies	numpy only
Training	none — closed-form SVD
Device	any CPU
Reported compression	~5–15× on conv4-scale features
Downstream classification	matches or beats raw features at r=8

The algorithm

pooled[n, c]      = mean_t X[n, c, t]                  # pool over time
mu[c]             = mean_n pooled[n, c]                 # per-channel mean
U, S, V^T         = SVD(pooled - mu)                    # rank-r truncation

basis   (C, r)    = V_r                                 # top r right singular vectors
rhythm  (N, r, T) = einsum("cr,nct->nrt", basis, X - mu)
X_hat   (N, C, T) = mu + einsum("cr,nrt->nct", basis, rhythm)

Stored parameters: basis (C·r) + rhythm (N·r·T) + mu (C). Raw size: N·C·T. Compression ratio: N·C·T / (C·r + N·r·T + C).

Why not GAP?

GAP averages over time. It throws away temporal structure — the very thing that distinguishes an audio event, a gesture, or a video clip from a static image. Hologram + rhythm keeps the time axis but at reduced channel rank, so a downstream classifier can still see "what happened when", not just "what happened on average".

Install

pip install numpy

No other dependencies. Runs on any CPU. Fits in ~250 lines.

Usage

import numpy as np
from hv_hologram_rhythm import HVHologramRhythm

# X: (N, C, T) feature maps
model = HVHologramRhythm(rank=12).fit(X)

rhythm = model.transform(X)                # (N, 12, T) — compressed
X_hat  = model.inverse_transform(rhythm)   # (N, C, T) — reconstructed

print(model.reconstruction_error(X))
print(model.summary())
print("compression:", model.compression_ratio(*X.shape), "x")

Automatic rank selection

# smallest rank that captures 99% of pooled variance
model = HVHologramRhythm(energy=0.99).fit(X)

Save / load

model.save_pretrained("./hv-hologram-rhythm")
m2 = HVHologramRhythm.from_pretrained("./hv-hologram-rhythm")

Push to the Hub

huggingface-cli login
huggingface-cli upload zeechimp/hv-hologram-rhythm . .

API

Method	Description
fit(X)	Learn basis + mu from (N, C, T)
transform(X)	(N, C, T) → rhythm (N, r, T)
inverse_transform(R)	rhythm (N, r, T) → (N, C, T)
fit_transform(X)	Fit then transform
reconstruction_error(X)	MSE, explained variance, per-channel NRMSE
compression_ratio(N, C, T)	Raw floats / compressed floats
summary()	Rank, channels, top-5 singular values, pooled energy
save_pretrained(dir)	Writes config.json + model.npz
from_pretrained(dir)	Loads the above

Diagnostics

Two complementary rank estimators are provided as free functions:

from hv_hologram_rhythm import effective_rank, rank_for_energy

er  = effective_rank(M)                 # participation ratio exp(H(p))
r99 = rank_for_energy(S, energy=0.99)   # count of directions for 99% variance

They measure different things:

• effective_rank is the entropy-weighted dimension — it collapses structured variance (e.g. class means) into a small number.
• rank_for_energy is the count of directions needed for a given energy threshold — it recovers the latent rank of the data.

Report both. They answer different questions.

Benchmarks

Synthetic class-conditional features

N=300, n_classes=5, C=64, T=16, true latent rank 6, σ=0.10.

rank	pooled energy	explained variance	rel. Frobenius	compression
2	0.8897	0.8792	0.3474	30.19×
4	0.9973	0.9799	0.1416	15.24×
6	0.9999	0.9993	0.0270	10.19×
8	1.0000	0.9993	0.0265	7.66×
12	1.0000	0.9994	0.0254	5.11×
16	1.0000	0.9994	0.0244	3.84×

The knee is at the true latent rank (6). Beyond it, extra dimensions buy almost nothing.

Downstream linear probe (same features, σ=0.30)

features	dim	accuracy
raw flattened (C·T)	1024	0.4889
rhythm at rank 8 (r·T)	128	1.0000

Compression 7.83×, accuracy delta +0.51.

On real conv4 features the effect is smaller — the rhythm matches raw rather than beating it — because real conv features already concentrate class information in a handful of channels. The synthetic gap is exaggerated by the low-rank generator.

Reference: FSDD conv4 features (3000 × 128 × 64)

method	storage	accuracy
full tensor	98 MB	99.67%
hologram + rhythm rank-12	9.2 MB	99.78%
GAP baseline	—	collapses time

10.66× compression, no accuracy loss.

When to use it

• Yes: audio / video / gesture / sensor features with a genuine time axis, channel rank ≥ r, on-device or CPU-bound inference.
• No: static features with no time axis (use PCA), or tasks where temporal order is irrelevant (GAP is fine and simpler).

Reference

Extracted from the XuanJi-ISA exploratory track (issue #104, "SKILLS — Chapter 5: Simulation Rank"). The original formulation was rank-12 hologram + rhythm on FSDD conv4 features, developed as a GAP replacement that preserves temporal structure at 10× compression.

License

Apache-2.0

---

## 📄 `requirements.txt`

```text
numpy>=1.24

---

📄 .gitattributes

*.npz filter=lfs diff=lfs merge=lfs -text
*.bin filter=lfs diff=lfs merge=lfs -text
*.safetensors filter=lfs diff=lfs merge=lfs -text

---

📄 LICENSE

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

Copyright 2026 Sylv Q (zeechimp)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.