sshash-lib 0.5.0

Sparse and Skew Hashing of k-mers - Core library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! Constants and configuration for SSHash
//!
//! This module defines compile-time and runtime constants used throughout
//! the library, including valid k-mer sizes and algorithm parameters.

/// Invalid value sentinel (matching C++ behavior)
pub const INVALID_UINT64: u64 = u64::MAX;

/// Default seed for hash functions
pub const DEFAULT_SEED: u64 = 1;

/// Default RAM limit in GiB for construction
pub const DEFAULT_RAM_LIMIT_GIB: usize = 8;

/// For PTHash/PHast MPHF construction
pub const DEFAULT_LAMBDA: f64 = 5.0;
/// Average partition size for MPHF construction
pub const AVG_PARTITION_SIZE: usize = 3_000_000;

/// Bucket size range parameters (for sparse and skew index)
pub const MIN_L: usize = 6;
/// Maximum bucket size parameter
pub const MAX_L: usize = 13;

/// Orientation constants
pub const FORWARD_ORIENTATION: i8 = 1;
/// Backward (reverse complement) orientation
pub const BACKWARD_ORIENTATION: i8 = -1;

/// Version number
pub const VERSION: (u8, u8, u8) = (0, 1, 0);

/// All valid k-mer sizes (odd numbers from 3 to 63)
/// This is the single source of truth for supported K values
pub const VALID_K_VALUES: &[usize] = &[
    3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31, 33, 35, 37, 39, 41, 43, 45, 47, 49,
    51, 53, 55, 57, 59, 61, 63,
];

/// Check if a k-mer size is valid
#[inline]
pub const fn is_valid_k(k: usize) -> bool {
    k >= 3 && k <= 63 && k % 2 == 1
}

/// Maximum k-mer size supported
pub const MAX_K: usize = 63;

/// Minimum k-mer size supported
pub const MIN_K: usize = 3;

/// Compute ceil(log2(x)), matching C++ std::ceil(std::log2(x)).
///
/// Returns 0 for x <= 1, and the minimum number of bits needed to
/// represent values in [0, x) for x >= 2.
#[inline]
pub const fn ceil_log2(x: u64) -> usize {
    if x <= 1 {
        0
    } else {
        64 - (x - 1).leading_zeros() as usize
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_valid_k_values() {
        // Verify all values in VALID_K_VALUES are actually valid
        for &k in VALID_K_VALUES {
            assert!(is_valid_k(k), "k={} should be valid", k);
        }

        // Verify count (31 odd numbers from 3 to 63)
        assert_eq!(VALID_K_VALUES.len(), 31);

        // Verify no duplicates
        let mut sorted = VALID_K_VALUES.to_vec();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), VALID_K_VALUES.len());
    }

    #[test]
    fn test_is_valid_k() {
        // Valid cases
        assert!(is_valid_k(3));
        assert!(is_valid_k(31));
        assert!(is_valid_k(63));
        assert!(is_valid_k(21));

        // Invalid cases (even)
        assert!(!is_valid_k(2));
        assert!(!is_valid_k(4));
        assert!(!is_valid_k(30));
        assert!(!is_valid_k(32));

        // Invalid cases (out of range)
        assert!(!is_valid_k(1));
        assert!(!is_valid_k(65));
        assert!(!is_valid_k(100));
    }
}