Skip to main content

littlebit_core/
binary.rs

1//! Binary activation/weight quantization functions (`STEBinary` and `SmoothSign`).
2
3use candle_core::{CpuStorage, CustomOp1, DType, Layout, Result as CandleResult, Shape, Tensor};
4use half::{bf16, f16};
5
6use crate::config::QuantFunc;
7use crate::error::Result;
8
9/// Binarize a floating-point tensor without tracking gradients:
10/// values `>= 0` map to `+1`, values `< 0` map to `-1`.
11///
12/// Matches PyTorch `y = x.sign(); y[y == 0] = 1`.
13///
14/// # Errors
15/// Returns a [`crate::LittleBitError::Candle`] error if the tensor operation fails.
16pub fn binarize_sign_no_grad(x: &Tensor) -> Result<Tensor> {
17    let x = x.detach();
18    let zero = x.zeros_like()?;
19    let ones = x.ones_like()?;
20    let neg_ones = ones.neg()?;
21    Ok(x.ge(&zero)?.where_cond(&ones, &neg_ones)?)
22}
23
24/// Apply `STEBinary` (`sign` forward with zero mapped to `+1`, clipped identity backward for `|x| < 1`).
25///
26/// # Errors
27/// Returns an error if the tensor dtype is unsupported or an internal Candle op fails.
28pub fn ste_binary(x: &Tensor) -> Result<Tensor> {
29    if x.device().is_cpu() {
30        let contiguous = if x.is_contiguous() {
31            x.clone()
32        } else {
33            x.contiguous()?
34        };
35        Ok(contiguous.apply_op1(SteBinaryOp)?)
36    } else {
37        // Portable straight-through estimator on GPU backends.
38        let y_hard = binarize_sign_no_grad(x)?;
39        let y_soft = x.clamp(-1.0f64, 1.0f64)?;
40        Ok((y_hard.sub(&y_soft)?.detach() + y_soft)?)
41    }
42}
43
44/// Apply `SmoothSign` (`sign` forward with zero mapped to `+1`,
45/// derivative `alpha * (1 - tanh(alpha * x)^2)` backward).
46///
47/// # Errors
48/// Returns an error if the tensor dtype is unsupported or an internal Candle op fails.
49pub fn smooth_sign(x: &Tensor, alpha: f64) -> Result<Tensor> {
50    if x.device().is_cpu() {
51        let contiguous = if x.is_contiguous() {
52            x.clone()
53        } else {
54            x.contiguous()?
55        };
56        Ok(contiguous.apply_op1(SmoothSignOp { alpha })?)
57    } else {
58        let work_dtype = if x.dtype() == DType::F64 {
59            DType::F64
60        } else {
61            DType::F32
62        };
63        let y_hard = binarize_sign_no_grad(x)?;
64        let y_soft = (x.to_dtype(work_dtype)? * alpha)?
65            .tanh()?
66            .to_dtype(x.dtype())?;
67        Ok((y_hard.sub(&y_soft)?.detach() + y_soft)?)
68    }
69}
70
71impl QuantFunc {
72    /// Apply this quantization function to `x`, preserving differentiable gradients.
73    ///
74    /// # Errors
75    /// Returns an error if the tensor dtype or backend operation fails.
76    pub fn apply(&self, x: &Tensor) -> Result<Tensor> {
77        match *self {
78            Self::SteBinary => ste_binary(x),
79            Self::SmoothSign { alpha } => smooth_sign(x, alpha),
80        }
81    }
82}
83
84#[derive(Debug, Clone, Copy)]
85struct SteBinaryOp;
86
87#[derive(Debug, Clone, Copy)]
88struct SmoothSignOp {
89    alpha: f64,
90}
91
92#[inline]
93fn sign_plus_one_f64(v: f64) -> f64 {
94    if v.is_nan() {
95        f64::NAN
96    } else if v < 0.0 {
97        -1.0
98    } else {
99        1.0
100    }
101}
102
103#[inline]
104fn sign_plus_one_f32(v: f32) -> f32 {
105    if v.is_nan() {
106        f32::NAN
107    } else if v < 0.0 {
108        -1.0
109    } else {
110        1.0
111    }
112}
113
114fn strided_offsets(layout: &Layout) -> Vec<usize> {
115    if let Some((start, end)) = layout.contiguous_offsets() {
116        return (start..end).collect();
117    }
118    let dims = layout.dims();
119    let stride = layout.stride();
120    let total = layout.shape().elem_count();
121    let mut offsets = Vec::with_capacity(total);
122    if total == 0 {
123        return offsets;
124    }
125    if dims.is_empty() {
126        offsets.push(layout.start_offset());
127        return offsets;
128    }
129    let mut coords = vec![0usize; dims.len()];
130    for _ in 0..total {
131        let mut idx = layout.start_offset();
132        for (c, &s) in coords.iter().zip(stride.iter()) {
133            idx += c * s;
134        }
135        offsets.push(idx);
136        for d in (0..dims.len()).rev() {
137            coords[d] += 1;
138            if coords[d] < dims[d] {
139                break;
140            }
141            coords[d] = 0;
142        }
143    }
144    offsets
145}
146
147fn cpu_sign_forward(storage: &CpuStorage, layout: &Layout) -> CandleResult<(CpuStorage, Shape)> {
148    let shape = layout.shape().clone();
149    if let Some((start, end)) = layout.contiguous_offsets() {
150        let out = match storage {
151            CpuStorage::F32(vs) => CpuStorage::F32(
152                vs[start..end]
153                    .iter()
154                    .map(|&v| sign_plus_one_f32(v))
155                    .collect(),
156            ),
157            CpuStorage::F64(vs) => CpuStorage::F64(
158                vs[start..end]
159                    .iter()
160                    .map(|&v| sign_plus_one_f64(v))
161                    .collect(),
162            ),
163            CpuStorage::F16(vs) => CpuStorage::F16(
164                vs[start..end]
165                    .iter()
166                    .map(|&v| f16::from_f32(sign_plus_one_f32(v.to_f32())))
167                    .collect(),
168            ),
169            CpuStorage::BF16(vs) => CpuStorage::BF16(
170                vs[start..end]
171                    .iter()
172                    .map(|&v| bf16::from_f32(sign_plus_one_f32(v.to_f32())))
173                    .collect(),
174            ),
175            other => {
176                candle_core::bail!(
177                    "binary quantization requires floating-point storage, got {:?}",
178                    other
179                );
180            }
181        };
182        return Ok((out, shape));
183    }
184
185    let offsets = strided_offsets(layout);
186    let out = match storage {
187        CpuStorage::F32(vs) => {
188            CpuStorage::F32(offsets.iter().map(|&i| sign_plus_one_f32(vs[i])).collect())
189        }
190        CpuStorage::F64(vs) => {
191            CpuStorage::F64(offsets.iter().map(|&i| sign_plus_one_f64(vs[i])).collect())
192        }
193        CpuStorage::F16(vs) => CpuStorage::F16(
194            offsets
195                .iter()
196                .map(|&i| f16::from_f32(sign_plus_one_f32(vs[i].to_f32())))
197                .collect(),
198        ),
199        CpuStorage::BF16(vs) => CpuStorage::BF16(
200            offsets
201                .iter()
202                .map(|&i| bf16::from_f32(sign_plus_one_f32(vs[i].to_f32())))
203                .collect(),
204        ),
205        other => {
206            candle_core::bail!(
207                "binary quantization requires floating-point storage, got {:?}",
208                other
209            );
210        }
211    };
212    Ok((out, shape))
213}
214
215impl CustomOp1 for SteBinaryOp {
216    fn name(&self) -> &'static str {
217        "littlebit_ste_binary"
218    }
219
220    fn cpu_fwd(&self, storage: &CpuStorage, layout: &Layout) -> CandleResult<(CpuStorage, Shape)> {
221        cpu_sign_forward(storage, layout)
222    }
223
224    fn bwd(&self, arg: &Tensor, _res: &Tensor, grad_res: &Tensor) -> CandleResult<Option<Tensor>> {
225        let work_dtype = if arg.dtype() == DType::F64 {
226            DType::F64
227        } else {
228            DType::F32
229        };
230        let x = arg.to_dtype(work_dtype)?;
231        let pos_one = x.ones_like()?;
232        let neg_one = pos_one.neg()?;
233        let mask = x
234            .gt(&neg_one)?
235            .mul(&x.lt(&pos_one)?)?
236            .to_dtype(grad_res.dtype())?;
237        Ok(Some(grad_res.mul(&mask)?))
238    }
239}
240
241impl CustomOp1 for SmoothSignOp {
242    fn name(&self) -> &'static str {
243        "littlebit_smooth_sign"
244    }
245
246    fn cpu_fwd(&self, storage: &CpuStorage, layout: &Layout) -> CandleResult<(CpuStorage, Shape)> {
247        cpu_sign_forward(storage, layout)
248    }
249
250    fn bwd(&self, arg: &Tensor, _res: &Tensor, grad_res: &Tensor) -> CandleResult<Option<Tensor>> {
251        let work_dtype = if arg.dtype() == DType::F64 {
252            DType::F64
253        } else {
254            DType::F32
255        };
256        let x = arg.to_dtype(work_dtype)?;
257        let t = (x * self.alpha)?.tanh()?;
258        let one_minus_t2 = (t.sqr()?.neg()? + 1.0)?;
259        let deriv = (one_minus_t2 * self.alpha)?.to_dtype(grad_res.dtype())?;
260        Ok(Some(grad_res.mul(&deriv)?))
261    }
262}
263
264#[cfg(test)]
265mod tests {
266    use super::*;
267    use candle_core::{Device, Var};
268
269    #[test]
270    fn forward_maps_zero_and_neg_zero_to_plus_one() -> Result<()> {
271        let dev = Device::Cpu;
272        let x = Tensor::from_slice(&[-2.5f32, -1e-6, -0.0, 0.0, 1e-6, 3.0], 6, &dev)?;
273        let y_ste = ste_binary(&x)?.to_vec1::<f32>()?;
274        let y_smooth = smooth_sign(&x, 100.0)?.to_vec1::<f32>()?;
275        let want = vec![-1.0f32, -1.0, 1.0, 1.0, 1.0, 1.0];
276        assert_eq!(y_ste, want);
277        assert_eq!(y_smooth, want);
278        Ok(())
279    }
280
281    #[test]
282    fn ste_binary_backward_clips_outside_unit_interval() -> Result<()> {
283        let dev = Device::Cpu;
284        let x = Var::from_slice(&[-1.5f32, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5], 7, &dev)?;
285        let weights = Tensor::from_slice(&[2.0f32, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], 7, &dev)?;
286        let y = ste_binary(x.as_tensor())?;
287        let loss = (y * weights)?.sum_all()?;
288        let grads = loss.backward()?;
289        let grad = grads
290            .get(x.as_tensor())
291            .expect("x gradient")
292            .to_vec1::<f32>()?;
293        assert_eq!(grad, vec![0.0, 0.0, 4.0, 5.0, 6.0, 0.0, 0.0]);
294        Ok(())
295    }
296
297    #[test]
298    fn smooth_sign_backward_matches_analytical_tanh_derivative() -> Result<()> {
299        let dev = Device::Cpu;
300        let alpha = 5.0_f64;
301        let vals = [-0.8f32, -0.2, 0.0, 0.3, 1.1];
302        let g_out = [1.5f32, -2.0, 0.75, 4.0, -0.5];
303
304        let x = Var::from_slice(&vals, vals.len(), &dev)?;
305        let w = Tensor::from_slice(&g_out, g_out.len(), &dev)?;
306        let y = smooth_sign(x.as_tensor(), alpha)?;
307        let loss = (y * w)?.sum_all()?;
308        let grads = loss.backward()?;
309        let grad = grads
310            .get(x.as_tensor())
311            .expect("x gradient")
312            .to_vec1::<f32>()?;
313
314        for i in 0..vals.len() {
315            let t = (alpha * vals[i] as f64).tanh();
316            let expected = (g_out[i] as f64 * alpha * (1.0 - t * t)) as f32;
317            assert!(
318                (grad[i] - expected).abs() < 1e-5,
319                "idx {i}: got {}, want {expected}",
320                grad[i]
321            );
322        }
323        Ok(())
324    }
325}