Add documentation examples

src/distinguishers/cpa.rs

@@ -8,6 +8,39 @@ use std::{iter::zip, ops::Add};
 
 /// Compute the [`Cpa`] of the given traces using [`CpaProcessor`].
 ///
+/// # Examples
+/// ```
+/// use muscat::distinguishers::cpa::cpa;
+/// use muscat::leakage::sbox;
+/// use ndarray::array;
+///
+/// let traces = array![
+///     [77, 137, 51, 91],
+///     [72, 61, 91, 83],
+///     [39, 49, 52, 23],
+///     [26, 114, 63, 45],
+///     [30, 8, 97, 91],
+///     [13, 68, 7, 45],
+///     [17, 181, 60, 34],
+///     [43, 88, 76, 78],
+///     [0, 36, 35, 0],
+///     [93, 191, 49, 26],
+/// ];
+/// let plaintexts = array![
+///     [1usize, 2],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+/// ];
+/// let cpa = cpa(traces.view(), plaintexts.view(), 256, 0, |key, guess| sbox((key ^ guess) as u8) as usize, 2);
+/// ```
+///
 /// # Panics
 /// - Panic if `traces.shape()[0] != plaintexts.shape()[0]`
 /// - Panic if `batch_size` is 0.

src/distinguishers/cpa_normal.rs

@@ -6,6 +6,39 @@ use crate::distinguishers::cpa::Cpa;
 
 /// Compute the [`Cpa`] of the given traces using [`CpaProcessor`].
 ///
+/// # Examples
+/// ```
+/// use muscat::distinguishers::cpa_normal::cpa;
+/// use muscat::leakage::sbox;
+/// use ndarray::array;
+///
+/// let traces = array![
+///     [77, 137, 51, 91],
+///     [72, 61, 91, 83],
+///     [39, 49, 52, 23],
+///     [26, 114, 63, 45],
+///     [30, 8, 97, 91],
+///     [13, 68, 7, 45],
+///     [17, 181, 60, 34],
+///     [43, 88, 76, 78],
+///     [0, 36, 35, 0],
+///     [93, 191, 49, 26],
+/// ];
+/// let plaintexts = array![
+///     [1usize, 2],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+/// ];
+/// let cpa = cpa(traces.map(|&x| x as f32).view(), plaintexts.view(), 256, |key, guess| sbox((key[0] ^ guess) as u8) as usize, 2);
+/// ```
+///
 /// # Panics
 /// - Panic if `traces.shape()[0] != plaintexts.shape()[0]`
 /// - Panic if `batch_size` is 0.

src/distinguishers/dpa.rs

@@ -6,6 +6,50 @@ use crate::util::{argmax_by, argsort_by, max_per_row};
 
 /// Compute the [`Dpa`] of the given traces using [`DpaProcessor`].
 ///
+/// # Examples
+/// ```
+/// use muscat::distinguishers::dpa::dpa;
+/// use muscat::leakage::sbox;
+/// use ndarray::{array, Array1};
+///
+/// let traces = array![
+///     [77, 137, 51, 91],
+///     [72, 61, 91, 83],
+///     [39, 49, 52, 23],
+///     [26, 114, 63, 45],
+///     [30, 8, 97, 91],
+///     [13, 68, 7, 45],
+///     [17, 181, 60, 34],
+///     [43, 88, 76, 78],
+///     [0, 36, 35, 0],
+///     [93, 191, 49, 26],
+/// ];
+/// let plaintexts = array![
+///     [1, 2],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+/// ];
+/// let dpa = dpa(
+///     traces.map(|&x| x as f32).view(),
+///     plaintexts
+///         .rows()
+///         .into_iter()
+///         .map(|x| x.to_owned())
+///         .collect::<Array1<Array1<u8>>>()
+///         .view(),
+///     256,
+///     |key: Array1<u8>, guess| sbox(key[0] ^ guess as u8) & 1 == 1,
+///     2
+/// );
+/// ```
+///
 /// # Panics
 /// Panic if `batch_size` is not strictly positive.
 pub fn dpa<M, T, F>(

src/leakage_detection.rs

@@ -8,6 +8,38 @@ use std::{iter::zip, ops::Add};
 ///
 /// `get_class` is a function returning the class of the given trace by index.
 ///
+/// # Examples
+/// ```
+/// use muscat::leakage_detection::snr;
+/// use ndarray::array;
+///
+/// let traces = array![
+///     [77, 137, 51, 91],
+///     [72, 61, 91, 83],
+///     [39, 49, 52, 23],
+///     [26, 114, 63, 45],
+///     [30, 8, 97, 91],
+///     [13, 68, 7, 45],
+///     [17, 181, 60, 34],
+///     [43, 88, 76, 78],
+///     [0, 36, 35, 0],
+///     [93, 191, 49, 26],
+/// ];
+/// let plaintexts = array![
+///     [1usize, 2],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+///     [1, 2],
+///     [1, 2],
+///     [2, 1],
+///     [2, 1],
+/// ];
+/// let snr = snr(traces.view(), 256, |i| plaintexts.row(i)[0].into(), 2);
+/// ```
+///
 /// # Panics
 /// - Panic if `batch_size` is 0.
 pub fn snr<T, F>(
@@ -147,6 +179,28 @@ impl Add for SnrProcessor {
 
 /// Compute the Welch's T-test of the given traces using [`TTestProcessor`].
 ///
+/// # Examples
+/// ```
+/// use muscat::leakage_detection::ttest;
+/// use ndarray::array;
+///
+/// let traces = array![
+///     [77, 137, 51, 91],
+///     [72, 61, 91, 83],
+///     [39, 49, 52, 23],
+///     [26, 114, 63, 45],
+///     [30, 8, 97, 91],
+///     [13, 68, 7, 45],
+///     [17, 181, 60, 34],
+///     [43, 88, 76, 78],
+///     [0, 36, 35, 0],
+///     [93, 191, 49, 26],
+/// ];
+/// let trace_classes =
+///     array![true, false, false, true, false, false, true, false, false, true];
+/// let ttest = ttest(traces.view(), trace_classes.view(), 2);
+/// ```
+///
 /// # Panics
 /// - Panic if `traces.shape()[0] != trace_classes.shape()[0]`
 /// - Panic if `batch_size` is 0.