Merge pull request #17 from samply/develop

limiting the domain

Author: enola-dkfz

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Samply.Laplace v0.6.0 2025-11-26
+
+## Major changes
+
+* Option to limit the domain of the distribution used for obfuscation

Cargo.toml

@@ -1,15 +1,13 @@
 [package]
 name = "laplace_rs"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2021"
 license = "Apache-2.0"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 thiserror = "2.0.3"
-
-
 statrs = "0.18.0"
 rand = "0.8.5"
 anyhow = "1.0.69"

README.md

@@ -5,6 +5,8 @@ The values are obfuscated by perturbing them with random values sampled from a l
 
 Optionally, true zero values can be returned unperturbed. While lowering the privacy level slightly, this can vastly improve subsequent processes for data access control.
 
+If the optional parameter limiting the domain of the Laplace distribution is used, restricting the perturbation to the interval `[-domain_limit, domain_limit]`, the security properties change: the mechanism is no longer $`(\epsilon,0)`$-differentially private but instead only fulfills $`(\epsilon,\delta)`$-differential privacy. The parameter can be calculated as $`\delta(\epsilon,\Delta)=\sup_S\left(Pr[Z\in S]-e^\epsilon Pr[Z\in S-\Delta]\right)_+`$.
+
 ## Dependencies
 
 The dependencies Samply.Laplace Rust library requires are:
@@ -36,6 +38,7 @@ const DELTA: f64 = 1.;
 const EPSILON: f64 = 0.1;
 const MU: f64 = 0.;
 const ROUNDING_STEP: usize = 10;
+const domain_limit = None;
 
 
 fn obfuscate -> Result<u64, LaplaceError> {
@@ -53,6 +56,7 @@ fn obfuscate -> Result<u64, LaplaceError> {
 	    false, // A flag indicating whether zero counts should be obfuscated.
 	    ObfuscateBelow10Mode::Ten, // 0 - return 0, 1 - return 10, 2 - obfuscate using Laplace distribution and rounding
 	    ROUNDING_STEP, // The granularity of the rounding.
+			domain_limit, // Optional limitation to the domain of the Laplace distributions
 	    &mut rng, // A secure random generator for seeded randomness.
 	)?;
 

src/errors.rs

@@ -5,6 +5,8 @@ use thiserror::Error;
 pub enum LaplaceError {
     #[error("Unable to create Laplace distribution: {0}")]
     DistributionCreationError(StatsError),
+    #[error("Invalid domain limit. Must be None or a positive non-zero number")]
+    InvalidDomain,
     #[error("Rounding step zero not allowed")]
     InvalidArgRoundingStepZero,
     #[error("Rounding step error: {0}")]

src/lib.rs

@@ -39,6 +39,7 @@ pub enum ObfuscateBelow10Mode {
 /// * obfuscate_zero - A flag indicating whether zero counts should be obfuscated.
 /// * below_10_obfuscation_mode: 0 - return 0, 1 - return 10, 2 - obfuscate using Laplace distribution and rounding
 /// * rounding_step - The granularity of the rounding.
+/// * domain_limit - optional parameter limiting the distribution to [-domain_limit, domain_limit]
 /// * rng - A secure random generator for seeded randomness.
 ///
 /// # Returns
@@ -54,10 +55,11 @@ pub fn get_from_cache_or_privatize(
     obfuscate_zero: bool,
     obfuscate_below_10_mode: ObfuscateBelow10Mode,
     rounding_step: usize,
+    domain_limit: Option<f64>,
     rng: &mut rand::rngs::ThreadRng,
 ) -> Result<u64, LaplaceError> {
     let obfuscated: u64 = match obf_cache_option {
-        None => privatize(value, delta, epsilon, rounding_step, rng).unwrap(),
+        None => privatize(value, delta, epsilon, rounding_step, domain_limit, rng)?,
         Some(obf_cache) => {
             if !obfuscate_zero && value == 0 {
                 return Ok(0);
@@ -78,7 +80,7 @@ pub fn get_from_cache_or_privatize(
                 Some(obfuscated_reference) => *obfuscated_reference,
                 None => {
                     let obfuscated_value =
-                        privatize(value, delta, epsilon, rounding_step, rng).unwrap();
+                        privatize(value, delta, epsilon, rounding_step, domain_limit, rng)?;
 
                     obf_cache
                         .cache
@@ -101,6 +103,7 @@ pub fn get_from_cache_or_privatize(
 /// * `sensitivity` - Sensitivity of query.
 /// * `epsilon` - Privacy budget parameter.
 /// * `rounding_step` - Rounding to the given number is performed.
+/// * `domain_limit` - optional parameter limiting the distribution to [-domain_limit, domain_limit]
 /// * rng - A secure random generator for seeded randomness.
 ///
 /// # Returns
@@ -111,9 +114,25 @@ pub fn privatize(
     sensitivity: f64,
     epsilon: f64,
     rounding_step: usize,
+    domain_limit: Option<f64>,
     rng: &mut rand::rngs::ThreadRng,
 ) -> Result<u64, LaplaceError> {
-    let obfuscated_value = value as f64 + laplace(0.0, sensitivity / epsilon, rng).unwrap();
+    let permutation = match domain_limit {
+        Some(f64::INFINITY) | None => laplace(0.0, sensitivity / epsilon, rng)?,
+        Some(boundary) if boundary <= 0. => Err(LaplaceError::InvalidDomain)?,
+        // Resample, if clamped to a specific domain
+        Some(boundary) => {
+            let mut sample: f64;
+            loop {
+                sample = laplace(0.0, sensitivity / epsilon, rng)?;
+                if sample >= -boundary && sample <= boundary {
+                    break;
+                }
+            }
+            sample
+        }
+    };
+    let obfuscated_value = value as f64 + permutation;
     round_parametric(obfuscated_value, rounding_step)
 }
 
@@ -140,14 +159,13 @@ fn round_parametric(value: f64, step_parameter: usize) -> Result<u64, LaplaceErr
 ///
 /// * `mu` - the mean of the distribution.
 /// * `b` - the scale parameter of the distribution, often equal to `sensitivity`/`epsilon`.
-/// /// * `rng` - random generator.
+/// * `rng` - random generator.
 ///
 /// # Returns
 ///
 /// Returns a random sample from the Laplace distribution with the given `mu` and `b`, or an error if the distribution creation failed.
 fn laplace(mu: f64, b: f64, rng: &mut rand::rngs::ThreadRng) -> Result<f64, LaplaceError> {
-    let dist =
-        Laplace::new(mu, b).map_err(|e| LaplaceError::DistributionCreationError(e))?;
+    let dist = Laplace::new(mu, b).map_err(LaplaceError::DistributionCreationError)?;
     Ok(dist.sample(rng))
 }
 
@@ -219,28 +237,74 @@ mod test {
         let sensitivity = 10.0;
         let epsilon = 0.5;
         let rounding_step = 10;
+        let domain_limit = None;
         let result = privatize(
             value,
             sensitivity,
             epsilon,
             rounding_step,
+            domain_limit,
             &mut rng,
         );
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn test_privatize_within_domain() {
+        let mut rng = rand::thread_rng();
+        let value = 27;
+        let sensitivity = 10.0;
+        let epsilon = 0.5;
+        let rounding_step = 1;
+        let domain_limit = 10;
+        for _ in 0..10000 {
+            let result = privatize(
+                value,
+                sensitivity,
+                epsilon,
+                rounding_step,
+                Some(domain_limit as f64),
+                &mut rng,
+            )
+            .unwrap();
+            assert!(result <= (value + domain_limit) && result >= (value - domain_limit));
+        }
+    }
+
     #[test]
     fn test_obfuscate_value_zero() {
         let mut rng = rand::thread_rng();
-        let result = get_from_cache_or_privatize(0, 1.0, 1.0, 1, None, true, ObfuscateBelow10Mode::Obfuscate, 1, &mut rng);
+        let result = get_from_cache_or_privatize(
+            0,
+            1.0,
+            1.0,
+            1,
+            None,
+            true,
+            ObfuscateBelow10Mode::Obfuscate,
+            1,
+            None,
+            &mut rng,
+        );
 
         assert!(result.is_ok());
     }
 
     #[test]
     fn test_obfuscate_value_non_zero() {
         let mut rng = rand::thread_rng();
-        let result = get_from_cache_or_privatize(10, 1.0, 1.0, 1, None, true, ObfuscateBelow10Mode::Obfuscate, 1, &mut rng);
+        let result = get_from_cache_or_privatize(
+            10,
+            1.0,
+            1.0,
+            1,
+            None,
+            true,
+            ObfuscateBelow10Mode::Obfuscate,
+            1,
+            None,
+            &mut rng,
+        );
 
         assert!(result.is_ok());
     }
@@ -252,17 +316,37 @@ mod test {
             cache: HashMap::new(),
         };
 
-        let result =
-            get_from_cache_or_privatize(10, 1.0, 1.0, 1, Some(&mut obf_cache), true, ObfuscateBelow10Mode::Obfuscate, 1, &mut rng);
+        let result = get_from_cache_or_privatize(
+            10,
+            1.0,
+            1.0,
+            1,
+            Some(&mut obf_cache),
+            true,
+            ObfuscateBelow10Mode::Obfuscate,
+            1,
+            None,
+            &mut rng,
+        );
         assert!(result.is_ok());
 
         let obfuscated_value = obf_cache.cache.get(&(1, 10, 1));
         assert!(obfuscated_value.is_some());
         let result_ok = result.unwrap();
         assert_eq!(result_ok.clone(), *obfuscated_value.unwrap());
 
-        let result2 =
-            get_from_cache_or_privatize(10, 1.0, 1.0, 1, Some(&mut obf_cache), true, ObfuscateBelow10Mode::Obfuscate, 1, &mut rng);
+        let result2 = get_from_cache_or_privatize(
+            10,
+            1.0,
+            1.0,
+            1,
+            Some(&mut obf_cache),
+            true,
+            ObfuscateBelow10Mode::Obfuscate,
+            1,
+            None,
+            &mut rng,
+        );
         assert!(result2.is_ok());
         assert_eq!(result_ok, result2.unwrap());
     }