Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions crates/accuracy/src/guarantee/cardinality.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ use super::*;
/// The smallest `k` `asap_sketchlib`'s KMV estimate `(k-1)/U` is defined for.
const KMV_MIN_K: u32 = 2;
/// The largest `k` sizing returns.
#[cfg(test)]
const KMV_MAX_K: u32 = 1 << 26;

pub(super) fn guarantee(
Expand Down Expand Up @@ -81,6 +82,7 @@ pub(crate) fn kmv_failure_probability(k: u32, eps: f64) -> f64 {
/// The smallest `k` whose KMV failure probability at relative error `eps`
/// is at most `delta` ([`kmv_failure_probability`]), up to `2^26`; a
/// degenerate `eps` or `delta` saturates to `2^26`.
#[cfg(test)]
pub(crate) fn kmv_k(eps: f64, delta: f64) -> u32 {
if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) {
return KMV_MAX_K;
Expand Down
1 change: 1 addition & 0 deletions crates/accuracy/src/guarantee/cms.rs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ pub(super) fn guarantee(
}

/// CMS: over-count ≤ ε·N with width `w = ⌈e/ε⌉` columns.
#[cfg(test)]
pub(crate) fn cms_width(eps: f64) -> u32 {
saturating_ceil(std::f64::consts::E / eps, 2, 1 << 26)
}
Expand Down
2 changes: 2 additions & 0 deletions crates/accuracy/src/guarantee/count_sketch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,14 @@ fn count_sketch_failure_probability(width: u32, depth: u32) -> Option<f64> {
}

/// CountSketch `L2` point-query width: ε = sqrt(3/w).
#[cfg(test)]
pub(crate) fn count_sketch_width(eps: f64) -> u32 {
saturating_ceil(3.0 / (eps * eps), 2, 1 << 26)
}

/// The smallest positive odd depth whose binomial median failure
/// probability at `width` is at most `delta`, capped at 255.
#[cfg(test)]
pub(crate) fn count_sketch_depth(width: u32, delta: f64) -> u32 {
if !(delta.is_finite() && delta > 0.0 && delta < 1.0) {
return 255;
Expand Down
1 change: 1 addition & 0 deletions crates/accuracy/src/guarantee/ddsketch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ pub(super) fn guarantee(
))
}

#[cfg(test)]
pub(super) fn size_params(epsilon: f64) -> SketchParams {
SketchParams::DDSketch { alpha: epsilon }
}
1 change: 1 addition & 0 deletions crates/accuracy/src/guarantee/hll.rs
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,7 @@ pub fn min_precision(
/// bound up to `⌈1/ε⌉` (18 when none up to 18 does). Pass 1 then raises
/// the precision by the same rule ([`min_precision`]) when the source's own
/// bound or a smaller failure probability needs it.
#[cfg(test)]
pub(crate) fn hll_precision(eps: f64, delta: f64) -> u8 {
if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) {
return 18;
Expand Down
2 changes: 2 additions & 0 deletions crates/accuracy/src/guarantee/kll.rs
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ pub(crate) fn kll_rank_error_99(k: u32) -> f64 {
/// normalized rank-error fit: `epsilon = 2.296 / k^0.9723`. Capped at
/// [`KLL_MAX_K`], the largest `k` `asap_sketchlib` builds; an `eps` that
/// needs more gets that `k`, whose guarantee then misses the target.
#[cfg(test)]
pub(crate) fn kll_k(eps: f64) -> u32 {
saturating_ceil(
(KLL_RANK_ERROR_COEFFICIENT_99 / eps).powf(1.0 / KLL_RANK_ERROR_EXPONENT_99),
Expand Down Expand Up @@ -133,6 +134,7 @@ fn normal_quantile(p: f64) -> f64 {
/// `k` for rank error `eps` at failure probability `delta`: the empirical
/// 99% calibration for `delta >= 0.01`; below, the calibration at
/// `eps / delta_scale(delta)`, recording `delta` so the guarantee reports it.
#[cfg(test)]
pub(crate) fn size_params(eps: f64, delta: f64) -> SketchParams {
if delta.is_nan() || delta <= 0.0 || delta >= KLL_CALIBRATED_FAILURE_PROBABILITY {
return SketchParams::Kll { k: kll_k(eps) };
Expand Down
109 changes: 108 additions & 1 deletion crates/accuracy/src/guarantee/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ use asap_types::summary_type::{SketchAlgorithm, SketchParams, SketchStatistic};

#[cfg(test)]
use crate::requirements::meets;
#[cfg(test)]
use asap_types::ir::operator::AggIntent;
use asap_types::summary_type::SummaryTypeCapability;

Expand Down Expand Up @@ -87,7 +88,10 @@ pub fn theoretical_guarantee(
}
}

#[allow(dead_code)] // Read again for the predefined θ lists (`parameter_list`), in #1207 PR 1.
/// Today's sizing: the parameters of algorithm `kind` for error `eps` at failure
/// probability `delta`. Test-only: the predefined lists (`parameter_list`)
/// are this sizing over an error grid, which a test keeps equal.
#[cfg(test)]
pub(crate) fn size_params(
kind: SketchAlgorithm,
intent: &AggIntent,
Expand Down Expand Up @@ -192,6 +196,7 @@ pub(crate) fn binomial_upper_tail(n: u32, p: f64, k: u32) -> f64 {

/// Accuracy-dependent candidate budget, not a completeness theorem. The
/// membership model must still certify the selected set independently.
#[cfg(test)]
pub(crate) fn topk_capacity(k: usize, eps: f64) -> u32 {
u32::try_from(k)
.unwrap_or(u32::MAX)
Expand All @@ -211,6 +216,108 @@ pub(crate) fn saturating_ceil(x: f64, lo: u32, hi: u32) -> u32 {
mod tests {
use super::*;

/// Each algorithm's predefined list (`parameter_list`) is today's sizing
/// over the error grid ε = 0.1 … 0.001 at failure probability 0.01,
/// smallest first, without repeats; KMV's and UnivMon's distinct counts
/// stop at ε = 0.01. Count-Min lists each sized width with depths 5, 7,
/// 10 and 12, Count Sketch with 47, 81, 117 and 155, and a heap variant
/// each of those with
/// every heap size of the 1-2-5 series 10 … 10 000. UnivMon's list also
/// combines each L2 shape with each distinct-count shape (28 entries).
#[test]
fn parameter_list_is_the_sizing_over_the_error_grid() {
use asap_types::ir::operator::agg_intent::{default_cardinality, default_quantile};
use asap_types::summary_type::parameter_list;
let full_grid = [0.1, 0.05, 0.02, 0.01, 0.005, 0.002, 0.001];
let distinct_grid = [0.1, 0.05, 0.02, 0.01];
let cms_depths = [5, 7, 10, 12];
let count_sketch_depths = [47, 81, 117, 155];
let heap_sizes = [10, 20, 50, 100, 200, 500, 1_000, 2_000, 5_000, 10_000];
let l2 = AggIntent::FrequencyL2 { col: None };
let top_1 = AggIntent::TopK { k: 1 };
let quantile = default_quantile(0.5);
let distinct = default_cardinality();
for (algorithm, intents) in [
(SketchAlgorithm::Kll, vec![&quantile]),
(SketchAlgorithm::DDSketch, vec![&quantile]),
(SketchAlgorithm::Hll, vec![&distinct]),
(SketchAlgorithm::Kmv, vec![&distinct]),
(SketchAlgorithm::Cms, vec![&distinct]),
(SketchAlgorithm::CountSketch, vec![&distinct]),
(SketchAlgorithm::CmsWithHeap, vec![&top_1]),
(SketchAlgorithm::CountSketchWithHeap, vec![&top_1]),
(SketchAlgorithm::UnivMon, vec![&l2, &distinct, &quantile]),
] {
let mut sized: Vec<SketchParams> = Vec::new();
for intent in intents {
let grid: &[f64] = match (algorithm, intent) {
(
SketchAlgorithm::Kmv | SketchAlgorithm::UnivMon,
AggIntent::Cardinality { .. },
) => &distinct_grid,
_ => &full_grid,
};
for &eps in grid {
let listed: Vec<SketchParams> = match size_params(algorithm, intent, eps, 0.01)
{
SketchParams::Cms { width, .. } => cms_depths
.iter()
.map(|&depth| SketchParams::Cms { width, depth })
.collect(),
SketchParams::CountSketch { width, .. } => count_sketch_depths
.iter()
.map(|&depth| SketchParams::CountSketch { width, depth })
.collect(),
SketchParams::CmsWithHeap { width, .. } => cms_depths
.iter()
.flat_map(|&depth| {
heap_sizes
.iter()
.map(move |&heap_size| SketchParams::CmsWithHeap {
width,
depth,
heap_size,
})
})
.collect(),
SketchParams::CountSketchWithHeap { width, .. } => count_sketch_depths
.iter()
.flat_map(|&depth| {
heap_sizes.iter().map(move |&heap_size| {
SketchParams::CountSketchWithHeap {
width,
depth,
heap_size,
}
})
})
.collect(),
other => vec![other],
};
for params in listed {
if !sized.contains(&params) {
sized.push(params);
}
}
}
}
let list = parameter_list(algorithm);
let (listed_sized, combined): (Vec<_>, Vec<_>) =
list.iter().partition(|params| sized.contains(params));
assert_eq!(
format!("{listed_sized:?}"),
format!("{:?}", sized.iter().collect::<Vec<_>>()),
"{algorithm:?}"
);
let expected_combined = if algorithm == SketchAlgorithm::UnivMon {
28
} else {
0
};
assert_eq!(combined.len(), expected_combined, "{algorithm:?}");
}
}

/// Classic HLL's precision grows until its failure probability over the
/// source's distinct bound meets the target, up to 18.
#[test]
Expand Down
10 changes: 10 additions & 0 deletions crates/accuracy/src/guarantee/univmon.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,22 @@
//! (OctoSketch aggregators fed promoted deltas) are not covered: the
//! executor rejects them.
use super::*;
#[cfg(test)]
use asap_types::ir::operator::AggIntent;

/// Layers `asap_sketchlib` builds: layer `i` hashes at seed index `i`, and
/// seed 19 picks the layers a key reaches.
#[cfg(test)]
pub(crate) const MAX_LAYERS: u8 =
asap_sketchlib::sketch_framework::univmon::UNIVMON_MAX_LAYERS as u8;
/// The most rows an L2 sketch is sized with: the deepest odd shape within
/// the 20 rows the executor builds ([`hash_independent`]), so the row median
/// is one row's estimate, and within the hash budget at the more than 20
/// columns an L2 guarantee needs (5 column bits: 19 · 6 = 114 ≤ 128).
#[cfg(test)]
const MAX_L2_ROWS: u32 = 19;
/// Each row of a layer reads its column and sign bits from one hash.
#[cfg(test)]
const HASH_BITS: u32 = 128;
/// The per-row failure probability the L2 guarantee fixes: a row misses by
/// more than `ε₂ F2` with probability at most `2q/ε₂² = 0.1`. Fixing it
Expand All @@ -39,6 +43,7 @@ const L2_ROW_FAILURE: f64 = 0.1;
const DISTINCT_VARIANCE: f64 = 1.35;
/// The smallest heap the distinct-count variance bound holds for.
const DISTINCT_MIN_HEAP: u32 = 8;
#[cfg(test)]
const CARD_CAP: u32 = 1 << 26;

const L2_CONTRACT: &str = "univmon_layer0_f2_median_chebyshev_binomial_v1";
Expand All @@ -50,6 +55,7 @@ const MAX_DISTINCT: &str = "max_distinct";

/// The shape baseline for readouts without a size model: the total (exact
/// whatever the shape) and entropy (uncertified).
#[cfg(test)]
const BASELINE: SketchParams = SketchParams::UnivMon {
heap_size: 256,
sketch_rows: 5,
Expand Down Expand Up @@ -147,6 +153,7 @@ fn l2_failure_probability(rows: u32) -> f64 {
/// clamped to the hash budget: with more rows than [`MAX_L2_ROWS`], or more
/// columns than `rows` leave bits for, the shape is the largest one built
/// and its guarantee misses the target.
#[cfg(test)]
fn l2_shape(eps: f64, delta: f64) -> (u32, u32) {
let rows = (1..=MAX_L2_ROWS)
.find(|&rows| l2_failure_probability(rows) <= delta)
Expand Down Expand Up @@ -186,6 +193,7 @@ fn incomplete_top_layer_bound(heap_size: u32) -> f64 {

/// The Chebyshev share of the distinct count's failure probability at
/// heap `k` and relative error `eps`: `1.35/(k ε²)`.
#[cfg(test)]
fn distinct_chebyshev(heap_size: u32, eps: f64) -> f64 {
DISTINCT_VARIANCE / (f64::from(heap_size) * eps * eps)
}
Expand All @@ -194,6 +202,7 @@ fn distinct_chebyshev(heap_size: u32, eps: f64) -> f64 {
/// `eps · F0` with probability at most `delta`, top-layer completeness
/// included: `1.35/(k ε²) + (e/4)^(k/2) ≤ δ`. Capped; a capped heap's
/// guarantee misses the target.
#[cfg(test)]
fn distinct_heap(eps: f64, delta: f64) -> u32 {
if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) {
return CARD_CAP;
Expand Down Expand Up @@ -320,6 +329,7 @@ pub(crate) fn distinct_guarantee(
/// counter;
/// - total and entropy: the baseline shape (the total is exact; entropy
/// has no certified bound).
#[cfg(test)]
pub(super) fn size_params(intent: &AggIntent, eps: f64, delta: f64) -> SketchParams {
match intent {
AggIntent::FrequencyL2 { .. } => {
Expand Down
Loading
Loading