Skip to content

feat: mark UnivMon-Q experimental and add evaluation - #86

Merged
GordonYuanyc merged 3 commits into
mainfrom
codex/univmon-q
Aug 10, 2026
Merged

feat: mark UnivMon-Q experimental and add evaluation#86
GordonYuanyc merged 3 commits into
mainfrom
codex/univmon-q

Conversation

@zaoxing

@zaoxing zaoxing commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Fixed UnivMon issues

  • Corrects merge semantics for total stream weight, CountL2HH row norms, and candidate re-estimation from merged counters.
  • Restores per-layer L2 maintenance for standard updates and Joltik terminal-only reconstruction for fast_insert.
  • Tracks candidate completeness and explicit ever_evicted state through updates, merges, and native MessagePack.
  • Makes L1 exact for non-negative streams in UnivMon, UnivMonPyramid, and UnivMon-Q instead of using a noisy generic recurrence.

Experimental UnivMon-Q

  • Adds a mergeable terminal-stratum UnivMon core with coordinated bottom-k occurrence sampling for rank, CDF, and quantiles.
  • Adds adaptive entropy: the original recurrence handles diffuse or complete states; concentrated incomplete states use recovered-heavy entropy plus conditional residual occurrence sampling.
  • Exposes estimate_l1, estimate_entropy_universal, and estimate_entropy_occurrence.
  • Keeps F3 outside the advertised theoretical profile.
  • Adds equal-memory and dedicated entropy-stress evaluators.

UnivMon comparison

Release-scale sweep: 1M observations, 100K domain, seven Zipf skews, five trials, eight-way merges.

Metric (worst p95) UnivMon Compact UnivMon-Q Equal-memory UnivMon-Q
Point-frequency nRMSE 0.378% 0.383% 0.379%
F0 relative error 9.52% 12.04% 6.13%
F2 relative error 4.96% 10.12% 2.63%
Entropy relative error 17.32% 3.05% 3.05%
L1 relative error 0% exact 0% exact 0% exact
Quantile mean rank error n/a 0.45% 0.45%
Maximum CDF error n/a 2.42% 2.42%

The 3.05% entropy result precedes the final heavy/residual variance refinement and is conservative for the current estimator.

Compact UnivMon-Q uses 0.707 MiB estimated memory versus at least 2.188 MiB of UnivMon counters before heap metadata. It is 8–204x faster on updates, 16–52x faster on eight-way merges, and 2.6–4.4x faster for all-metric query batches.

The conservative equal-memory profile fits all UnivMon-Q state within UnivMon's counter bytes alone. It remains 7.4–199x faster on updates, 13.2–18.3x faster on merge, and 1.4–2.2x faster on query batches.

Entropy stress evaluation

The final assisted estimator was evaluated on 144 datasets / 576 sketch runs: four uniform supports, nine Zipf exponents, five 50%–99.99% heavy-head/diffuse-tail mixtures, eight trials, and eight-way merges.

Profile Samples Worst adaptive entropy p95
Compact 512 4.86%
Compact default 4,096 1.75%
Compact large 16,384 1.46%
Equal-memory 4,096 1.36%

A raw occurrence estimator exposed 22.76% p95 error for a 99% heavy head. Computing recovered-heavy entropy directly and sampling only conditional residual entropy reduced it to 0.32%. Entropy was bit-identical across left-fold and balanced merge trees in all 576 evaluations.

Validation

  • cargo test --all-targets: 505 library tests plus all integration/example targets pass
  • cargo test --doc: 20 pass
  • cargo clippy --all-targets -- -D warnings: pass
  • Formatting and diff checks pass
  • Full methodology and guarantee boundaries: docs/univmon_q_evaluation.md and docs/api/api_univmon_q.md

@zaoxing zaoxing assigned zaoxing and unassigned zaoxing Aug 10, 2026
@zaoxing
zaoxing requested a review from GordonYuanyc August 10, 2026 04:38

@GordonYuanyc GordonYuanyc 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.

LGTM!

@GordonYuanyc
GordonYuanyc merged commit 70fb04c into main Aug 10, 2026
3 checks passed
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