feat: impl densitysketch

datasketches/src/common/mod.rs

@@ -23,6 +23,11 @@ mod resize;
 pub use self::num_std_dev::NumStdDev;
 pub use self::resize::ResizeFactor;
 
+pub mod random;
+
+pub use self::random::RandomSource;
+pub use self::random::XorShift64;
+
 // private to datasketches crate
 pub(crate) mod binomial_bounds;
 pub(crate) mod inv_pow2_table;

datasketches/src/common/random.rs

@@ -0,0 +1,71 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+//! Shared random utilities for sketches.
+
+use std::time::SystemTime;
+use std::time::UNIX_EPOCH;
+
+/// Random number source for sketches.
+pub trait RandomSource {
+    /// Returns the next random 64-bit value.
+    fn next_u64(&mut self) -> u64;
+
+    /// Returns a random boolean value.
+    fn next_bool(&mut self) -> bool {
+        (self.next_u64() & 1) != 0
+    }
+}
+
+/// Xorshift-based random generator for sketch operations.
+#[derive(Debug, Clone, Copy)]
+pub struct XorShift64 {
+    state: u64,
+}
+
+impl XorShift64 {
+    /// Creates a new generator using the provided seed.
+    pub fn seeded(seed: u64) -> Self {
+        let state = if seed == 0 { 0x9e3779b97f4a7c15 } else { seed };
+        Self { state }
+    }
+}
+
+impl Default for XorShift64 {
+    fn default() -> Self {
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_nanos();
+        let mut seed = nanos as u64 ^ (std::process::id() as u64);
+        if seed == 0 {
+            seed = 0x9e3779b97f4a7c15;
+        }
+        Self::seeded(seed)
+    }
+}
+
+impl RandomSource for XorShift64 {
+    fn next_u64(&mut self) -> u64 {
+        let mut x = self.state;
+        x ^= x << 13;
+        x ^= x >> 7;
+        x ^= x << 17;
+        self.state = x;
+        x
+    }
+}

datasketches/src/density/mod.rs

@@ -0,0 +1,46 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+//! Density sketch implementation for density estimation from streaming data.
+//!
+//! The sketch maintains a coreset of points using a compaction scheme and
+//! provides density estimates at query points via a kernel function.
+//!
+//! # References
+//!
+//! - Zohar Karnin, Edo Liberty, "Discrepancy, Coresets, and Sketches in Machine Learning".
+//! - Apache DataSketches C++ density sketch implementation (density_sketch.hpp).
+//!
+//! # Usage
+//!
+//! ```rust
+//! # use datasketches::density::DensitySketch;
+//! let mut sketch: DensitySketch<f64> = DensitySketch::new(10, 3);
+//! sketch.update(vec![0.0, 0.0, 0.0]);
+//! sketch.update(vec![1.0, 2.0, 3.0]);
+//! let estimate = sketch.estimate(&[0.0, 0.0, 0.0]);
+//! assert!(estimate > 0.0);
+//! ```
+
+mod serialization;
+mod sketch;
+
+pub use self::sketch::DensityItem;
+pub use self::sketch::DensityKernel;
+pub use self::sketch::DensitySketch;
+pub use self::sketch::DensityValue;
+pub use self::sketch::GaussianKernel;

datasketches/src/density/serialization.rs

@@ -0,0 +1,22 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+pub(super) const PREAMBLE_INTS_SHORT: u8 = 3;
+pub(super) const PREAMBLE_INTS_LONG: u8 = 6;
+pub(super) const SERIAL_VERSION: u8 = 1;
+pub(super) const DENSITY_FAMILY_ID: u8 = 19;
+pub(super) const FLAGS_IS_EMPTY: u8 = 1 << 2;