fastalp 0.1.41

World's fastest and highest-ratio lossless floating-point compression / 全球最快、压缩比最高的通用时序浮点无损压缩
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

use crate::{constants::BITS_U64, float::AlpFloat, sampler::BestParams};

/// Packed parameters bitfield masks and shift constants.
/// 参数位域掩码与位移常量
pub(crate) const EXP_MASK: u16 = 0x001F;
pub(crate) const FAC_SHIFT: u16 = 5;
pub(crate) const FAC_MASK: u16 = 0x000F;
pub(crate) const BIT_WIDTH_SHIFT: u16 = 9;
pub(crate) const BIT_WIDTH_MASK: u16 = 0x007F;

/// Packs exponent (5b), factor (4b), and bit width (7b) into a 2-byte unsigned integer.
/// 将 exp (5b), fac (4b), bit_width (7b) 打包进 2 字节 u16
#[inline(always)]
pub(crate) const fn pack_params(exp: u8, fac: u8, bit_width: u8) -> u16 {
  ((exp as u16) & EXP_MASK)
    | (((fac as u16) & FAC_MASK) << FAC_SHIFT)
    | (((bit_width as u16) & BIT_WIDTH_MASK) << BIT_WIDTH_SHIFT)
}

/// Unpacks (exponent, factor, bit width) from a 2-byte unsigned integer.
/// 从 2 字节 u16 解包 (exp, fac, bit_width)
#[inline(always)]
pub(crate) const fn unpack_params(params: u16) -> (u8, u8, u8) {
  let exp = (params & EXP_MASK) as u8;
  let fac = ((params >> FAC_SHIFT) & FAC_MASK) as u8;
  let bit_width = ((params >> BIT_WIDTH_SHIFT) & BIT_WIDTH_MASK) as u8;
  (exp, fac, bit_width)
}

/// Calculates minimum bit width required to represent an unsigned integer (0..=64).
/// 快速计算表示数值所需的最少比特位数 (0..=64，无分支实现)
#[inline(always)]
pub(crate) const fn bits_needed(max_val: u64) -> u8 {
  (u64::BITS - max_val.leading_zeros()) as u8
}

/// Computes lower bitmask for a given bit width (0..=64).
/// 快速计算 0..=64 比特宽度的低位掩码
#[inline(always)]
pub(crate) const fn bit_mask(bit_width: u8) -> u64 {
  if bit_width >= BITS_U64 as u8 {
    u64::MAX
  } else {
    (1u64 << bit_width).wrapping_sub(1)
  }
}

/// Compact ALP encoding and decoding parameters.
/// 封装 ALP 核心参数 (exp, fac, bit_width, use_div)，消除多参数冗余传递并统一头部打包与类型判断
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct AlpParams {
  pub exp: u8,
  pub fac: u8,
  pub bit_width: u8,
  pub use_div: bool,
}

impl AlpParams {
  #[inline(always)]
  pub const fn new(exp: u8, fac: u8, bit_width: u8, use_div: bool) -> Self {
    Self {
      exp,
      fac,
      bit_width,
      use_div,
    }
  }

  #[inline(always)]
  pub const fn from_best_params(best: BestParams, bit_width: u8) -> Self {
    Self {
      exp: best.exp,
      fac: best.fac,
      bit_width,
      use_div: best.use_div,
    }
  }

  #[inline(always)]
  pub const fn pack(&self) -> u16 {
    pack_params(self.exp, self.fac, self.bit_width)
  }

  #[inline(always)]
  pub const fn from_packed(packed: u16, use_div: bool) -> Self {
    let (exp, fac, bit_width) = unpack_params(packed);
    Self {
      exp,
      fac,
      bit_width,
      use_div,
    }
  }

  #[inline(always)]
  pub const fn standard_type<F: AlpFloat>(&self) -> u8 {
    if self.use_div {
      F::TYPE_DEC_BYTE
    } else {
      F::TYPE_BYTE
    }
  }

  #[inline(always)]
  pub const fn delta_type<F: AlpFloat>(&self) -> u8 {
    if self.use_div {
      F::TYPE_DEC_DELTA_BYTE
    } else {
      F::TYPE_DELTA_BYTE
    }
  }

  #[inline(always)]
  pub const fn validate<F: AlpFloat>(&self) -> bool {
    self.exp <= F::MAX_EXPONENT
      && self.fac <= F::MAX_FAC
      && self.fac <= self.exp
      && self.bit_width <= F::MAX_BIT_WIDTH
  }

  /// Computes decoding float factors (exp_factor, fac_int, frac_flt) for floating-point reconstruction.
  /// 计算浮点重构所需的放大因子、整型因子与负幂小数因子
  #[inline(always)]
  pub fn factors<F: AlpFloat>(&self) -> (F, i64, F) {
    (
      F::exp_factor(self.exp, self.fac),
      F::fac_int(self.fac),
      F::frac_exp(self.exp),
    )
  }
}