Skip to main content

littlebit_core/
config.rs

1//! Quantization configuration, algebraic modes, and bit-budget calculation.
2
3use std::collections::BTreeSet;
4use std::fmt;
5use std::fs;
6use std::path::Path;
7use std::str::FromStr;
8
9use serde::{Deserialize, Deserializer, Serialize, Serializer};
10
11use crate::error::{LittleBitError, Result};
12
13/// Default sharpness hyperparameter `alpha` for [`QuantFunc::SmoothSign`].
14pub const SMOOTH_SIGN_DEFAULT_ALPHA: f64 = 100.0;
15
16/// Binarization function and straight-through gradient estimator.
17#[derive(Debug, Clone, Copy, PartialEq, Default)]
18pub enum QuantFunc {
19    /// Sign forward pass with clipped identity STE (`|x| < 1`), matching `STEBinary`.
20    #[default]
21    SteBinary,
22    /// Sign forward pass with hyperbolic-tangent derivative (`alpha * (1 - tanh(alpha * x)^2)`),
23    /// matching `SmoothSign`.
24    SmoothSign {
25        /// Sharpness scale factor (`100.0` in upstream LittleBit).
26        alpha: f64,
27    },
28}
29
30impl QuantFunc {
31    /// Canonical upstream wire identifier (`"STEBinary"` or `"SmoothSign"`).
32    #[must_use]
33    pub fn as_wire_name(self) -> &'static str {
34        match self {
35            Self::SteBinary => "STEBinary",
36            Self::SmoothSign { .. } => "SmoothSign",
37        }
38    }
39}
40
41impl fmt::Display for QuantFunc {
42    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
43        f.write_str(self.as_wire_name())
44    }
45}
46
47impl FromStr for QuantFunc {
48    type Err = LittleBitError;
49
50    fn from_str(s: &str) -> Result<Self> {
51        match s.trim().to_ascii_lowercase().as_str() {
52            "stebinary" | "ste_binary" | "ste" => Ok(Self::SteBinary),
53            "smoothsign" | "smooth_sign" | "smooth" => Ok(Self::SmoothSign {
54                alpha: SMOOTH_SIGN_DEFAULT_ALPHA,
55            }),
56            other => Err(LittleBitError::InvalidConfig(format!(
57                "unknown quant_func `{other}` (expected `STEBinary` or `SmoothSign`)"
58            ))),
59        }
60    }
61}
62
63impl Serialize for QuantFunc {
64    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
65        serializer.serialize_str(self.as_wire_name())
66    }
67}
68
69impl<'de> Deserialize<'de> for QuantFunc {
70    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
71        let raw = String::deserialize(deserializer)?;
72        raw.parse().map_err(serde::de::Error::custom)
73    }
74}
75
76/// Residual factorization mode for a [`crate::LittleBitLinear`] layer.
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
78pub enum ResidualMode {
79    /// Single latent factorization branch `(U, V, u1, u2, v1, v2)`.
80    Single,
81    /// Dual latent factorization adding a residual branch `(U_R, V_R, u1_R, u2_R, v1_R, v2_R)`.
82    Dual,
83}
84
85impl From<bool> for ResidualMode {
86    fn from(residual: bool) -> Self {
87        if residual {
88            Self::Dual
89        } else {
90            Self::Single
91        }
92    }
93}
94
95/// LittleBit-2 Joint Iterative Quantization (Joint-ITQ) rotation configuration.
96#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
97pub enum ItqMode {
98    /// Original LittleBit SVD-only initialization (`use_itq = false`).
99    Disabled,
100    /// LittleBit-2 internal latent rotation optimizing `min || B - X R ||_F^2` (`use_itq = true`).
101    Joint {
102        /// Number of alternating Procrustes / sign updates.
103        n_iter: usize,
104    },
105}
106
107/// Whether parameters inside a quantized layer hold autograd variables or frozen tensors.
108#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
109pub enum TrainMode {
110    /// Wrap factor parameters in differentiable `candle_core::Var`s for QAT.
111    Train,
112    /// Store frozen `candle_core::Tensor`s for evaluation or inference.
113    Eval,
114}
115
116/// Weight initialization mode when constructing [`crate::LittleBitLinear`].
117#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
118pub enum InitMode {
119    /// Decompose a dense weight matrix via low-rank SVD (+ optional Joint-ITQ).
120    Decompose,
121    /// Allocate zero/empty placeholder factors before loading checkpoint tensors.
122    Empty,
123}
124
125/// Runtime weight representation when loading quantized checkpoints for inference.
126#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
127pub enum InferenceMode {
128    /// Unpack 1-bit matrices into dense float tensors (`{-1, +1}` in target dtype).
129    Unpacked,
130    /// Keep 1-bit weights packed as row-major 32-bit words (`PackedBinaryMatrix`).
131    Packed,
132}
133
134/// Whether a linear layer includes a bias vector.
135#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
136pub enum BiasMode {
137    /// Layer includes a bias vector of length `out_features`.
138    WithBias,
139    /// Layer omits bias.
140    NoBias,
141}
142
143impl From<bool> for BiasMode {
144    fn from(has_bias: bool) -> Self {
145        if has_bias {
146            Self::WithBias
147        } else {
148            Self::NoBias
149        }
150    }
151}
152
153/// Whether factor weights `U`, `V` in a loaded `LittleBitLinear` are already binarized.
154#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
155pub enum WeightState {
156    /// Latent weights are continuous and should pass through `QuantFunc` during forward.
157    Raw,
158    /// Latent weights are already binarized (`{-1, +1}`) and used directly during forward.
159    PreBinarized,
160}
161
162/// Linear layer dimension specification `(in_features, out_features, bias)`.
163#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
164pub struct LayerShape {
165    /// Input feature dimension.
166    pub in_features: usize,
167    /// Output feature dimension.
168    pub out_features: usize,
169    /// Whether the layer includes an output bias.
170    pub bias: BiasMode,
171}
172
173impl LayerShape {
174    /// Construct a layer shape specification.
175    #[must_use]
176    pub const fn new(in_features: usize, out_features: usize, bias: BiasMode) -> Self {
177        Self {
178            in_features,
179            out_features,
180            bias,
181        }
182    }
183}
184
185/// Serialization policy for checkpoint float tensors when saving.
186#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
187pub enum CastPolicy {
188    /// Preserve existing tensor dtypes verbatim.
189    Preserve,
190    /// Cast `F32` scale/norm/head tensors to `BF16` while keeping packed `I32`/`I64` untouched.
191    ToBf16,
192}
193
194/// Quantization configuration matching upstream `littlebit_config.json`.
195#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
196#[serde(default)]
197pub struct LittleBitConfig {
198    /// Binarization estimator (`"STEBinary"` or `"SmoothSign"`).
199    pub quant_func: QuantFunc,
200    /// Target average effective bits per weight (`None` falls back to `split_dim`).
201    pub eff_bit: Option<f64>,
202    /// Optional per-decoder-block effective bit overrides (e.g., `"0-7,27:2.0;12:1.5"`).
203    #[serde(default, skip_serializing_if = "Option::is_none")]
204    pub eff_bit_layers: Option<String>,
205    /// Fallback inner latent rank when `eff_bit` is omitted.
206    pub split_dim: usize,
207    /// Whether to include a second residual latent factorization branch.
208    pub residual: bool,
209    /// Rank multiplier applied to attention `k_proj` and `v_proj` layers.
210    pub kv_factor: f64,
211    /// Minimum inner rank floor (must be positive; rounded in multiples of 8 when computed).
212    pub min_split_dim: usize,
213    /// Quantized module identifier (`"LittleBitLinear"`).
214    pub quant_mod: String,
215    /// Opt-in flag for LittleBit-2 Joint-ITQ initialization.
216    pub use_itq: bool,
217    /// Number of Joint-ITQ iterations when `use_itq` is enabled.
218    pub itq_n_iter: usize,
219}
220
221impl Default for LittleBitConfig {
222    fn default() -> Self {
223        Self {
224            quant_func: QuantFunc::SteBinary,
225            eff_bit: Some(1.0),
226            eff_bit_layers: None,
227            split_dim: 1024,
228            residual: false,
229            kv_factor: 1.0,
230            min_split_dim: 8,
231            quant_mod: "LittleBitLinear".to_string(),
232            use_itq: false,
233            itq_n_iter: 50,
234        }
235    }
236}
237
238/// Optional CLI or API overrides applied with highest priority over config files.
239#[derive(Debug, Clone, Default, PartialEq)]
240pub struct LittleBitConfigOverrides {
241    /// Override `quant_func`.
242    pub quant_func: Option<QuantFunc>,
243    /// Override `eff_bit` (`Some(Some(x))` sets target, `Some(None)` clears target).
244    pub eff_bit: Option<Option<f64>>,
245    /// Override `eff_bit_layers` (`Some(Some(spec))` sets spec, `Some(None)` clears spec).
246    pub eff_bit_layers: Option<Option<String>>,
247    /// Override `split_dim`.
248    pub split_dim: Option<usize>,
249    /// Override `residual`.
250    pub residual: Option<bool>,
251    /// Override `kv_factor`.
252    pub kv_factor: Option<f64>,
253    /// Override `min_split_dim`.
254    pub min_split_dim: Option<usize>,
255    /// Override `quant_mod`.
256    pub quant_mod: Option<String>,
257    /// Override `use_itq`.
258    pub use_itq: Option<bool>,
259    /// Override `itq_n_iter`.
260    pub itq_n_iter: Option<usize>,
261}
262
263impl LittleBitConfig {
264    /// Return the residual factorization mode.
265    #[must_use]
266    pub fn residual_mode(&self) -> ResidualMode {
267        ResidualMode::from(self.residual)
268    }
269
270    /// Return the LittleBit-2 ITQ initialization mode.
271    #[must_use]
272    pub fn itq_mode(&self) -> ItqMode {
273        if self.use_itq {
274            ItqMode::Joint {
275                n_iter: self.itq_n_iter,
276            }
277        } else {
278            ItqMode::Disabled
279        }
280    }
281
282    /// Validate hyperparameter invariants.
283    ///
284    /// # Errors
285    /// Returns [`LittleBitError::InvalidConfig`] when any value is invalid or non-finite.
286    pub fn validate(&self) -> Result<()> {
287        if self.min_split_dim == 0 {
288            return Err(LittleBitError::InvalidConfig(
289                "min_split_dim must be greater than 0".to_string(),
290            ));
291        }
292        if !self.kv_factor.is_finite() || self.kv_factor <= 0.0 {
293            return Err(LittleBitError::InvalidConfig(format!(
294                "kv_factor must be finite and positive, got {}",
295                self.kv_factor
296            )));
297        }
298        if let Some(bit) = self.eff_bit {
299            if !bit.is_finite() || bit <= 0.0 {
300                return Err(LittleBitError::InvalidConfig(format!(
301                    "eff_bit must be finite and positive, got {bit}"
302                )));
303            }
304        } else if self.split_dim == 0 {
305            return Err(LittleBitError::InvalidConfig(
306                "split_dim must be greater than 0 when eff_bit is None".to_string(),
307            ));
308        }
309        if let QuantFunc::SmoothSign { alpha } = self.quant_func {
310            if !alpha.is_finite() || alpha <= 0.0 {
311                return Err(LittleBitError::InvalidConfig(format!(
312                    "smooth_sign alpha must be finite and positive, got {alpha}"
313                )));
314            }
315        }
316        if self.use_itq && self.itq_n_iter == 0 {
317            return Err(LittleBitError::InvalidConfig(
318                "itq_n_iter must be greater than 0 when use_itq is enabled".to_string(),
319            ));
320        }
321        parse_eff_bit_layers(self.eff_bit_layers.as_deref())?;
322        Ok(())
323    }
324
325    /// Resolve the effective bits target for `module_name` by applying matching
326    /// [`LittleBitConfig::eff_bit_layers`] overrides over [`LittleBitConfig::eff_bit`].
327    ///
328    /// # Errors
329    /// Returns [`LittleBitError::InvalidConfig`] if `eff_bit_layers` is malformed.
330    pub fn eff_bit_for_module(&self, module_name: &str) -> Result<Option<f64>> {
331        let mut matched = None;
332        if let Some(after) = module_name
333            .find(".layers.")
334            .map(|idx| &module_name[idx + ".layers.".len()..])
335        {
336            if let Some(seg) = after.split('.').next() {
337                if let Ok(layer_idx) = seg.parse::<usize>() {
338                    for (blocks, bits) in parse_eff_bit_layers(self.eff_bit_layers.as_deref())? {
339                        if blocks.binary_search(&layer_idx).is_ok() {
340                            matched = Some(bits);
341                        }
342                    }
343                }
344            }
345        }
346        Ok(matched.or(self.eff_bit))
347    }
348
349    /// Return a config scoped to `module_name`, applying any per-block `eff_bit_layers` override.
350    ///
351    /// # Errors
352    /// Returns [`LittleBitError::InvalidConfig`] if `eff_bit_layers` is malformed.
353    pub fn effective_for_module(&self, module_name: &str) -> Result<Self> {
354        if self.eff_bit_layers.is_none() {
355            return Ok(self.clone());
356        }
357        let resolved = self.eff_bit_for_module(module_name)?;
358        let mut cloned = self.clone();
359        cloned.eff_bit = resolved;
360        Ok(cloned)
361    }
362
363    /// Load configuration using upstream priority:
364    /// 1. Explicit `overrides`
365    /// 2. `littlebit_config.json` in `dir`
366    /// 3. `config.json` fallback fields for legacy checkpoints
367    /// 4. [`LittleBitConfig::default`]
368    ///
369    /// # Errors
370    /// Returns an error if a present config file cannot be read or parsed, or if the
371    /// resulting configuration fails [`LittleBitConfig::validate`].
372    pub fn load_with_priority(dir: &Path, overrides: &LittleBitConfigOverrides) -> Result<Self> {
373        let default = Self::default();
374        let littlebit_path = dir.join("littlebit_config.json");
375        let mut config = if littlebit_path.exists() {
376            let raw = fs::read_to_string(&littlebit_path)?;
377            serde_json::from_str::<Self>(&raw)?
378        } else {
379            default.clone()
380        };
381
382        let model_cfg_path = dir.join("config.json");
383        if model_cfg_path.exists() {
384            let raw = fs::read_to_string(&model_cfg_path)?;
385            let value: serde_json::Value = serde_json::from_str(&raw)?;
386            if let Some(obj) = value.as_object() {
387                apply_legacy_fallback(&mut config, &default, obj)?;
388            }
389        }
390
391        apply_overrides(&mut config, overrides);
392        config.validate()?;
393        Ok(config)
394    }
395}
396
397fn apply_legacy_fallback(
398    config: &mut LittleBitConfig,
399    default: &LittleBitConfig,
400    obj: &serde_json::Map<String, serde_json::Value>,
401) -> Result<()> {
402    if config.quant_func == default.quant_func {
403        if let Some(v) = obj.get("quant_func").and_then(serde_json::Value::as_str) {
404            config.quant_func = v.parse()?;
405        }
406    }
407    if config.eff_bit == default.eff_bit {
408        if let Some(val) = obj.get("eff_bit") {
409            if val.is_null() {
410                config.eff_bit = None;
411            } else if let Some(b) = val.as_f64() {
412                config.eff_bit = Some(b);
413            }
414        }
415    }
416    if config.eff_bit_layers.is_none() {
417        if let Some(spec) = obj
418            .get("eff_bit_layers")
419            .and_then(serde_json::Value::as_str)
420        {
421            config.eff_bit_layers = Some(spec.to_string());
422        }
423    }
424    if config.split_dim == default.split_dim {
425        if let Some(s) = obj.get("split_dim").and_then(serde_json::Value::as_u64) {
426            config.split_dim = s as usize;
427        }
428    }
429    if config.residual == default.residual {
430        if let Some(r) = obj.get("residual").and_then(serde_json::Value::as_bool) {
431            config.residual = r;
432        }
433    }
434    if config.quant_mod == default.quant_mod {
435        if let Some(m) = obj.get("quant_mod").and_then(serde_json::Value::as_str) {
436            config.quant_mod = m.to_string();
437        }
438    }
439    if (config.kv_factor - default.kv_factor).abs() < f64::EPSILON {
440        if let Some(k) = obj.get("kv_factor").and_then(serde_json::Value::as_f64) {
441            config.kv_factor = k;
442        }
443    }
444    if config.min_split_dim == default.min_split_dim {
445        if let Some(m) = obj.get("min_split_dim").and_then(serde_json::Value::as_u64) {
446            config.min_split_dim = m as usize;
447        }
448    }
449    if config.use_itq == default.use_itq {
450        if let Some(u) = obj.get("use_itq").and_then(serde_json::Value::as_bool) {
451            config.use_itq = u;
452        }
453    }
454    if config.itq_n_iter == default.itq_n_iter {
455        if let Some(n) = obj.get("itq_n_iter").and_then(serde_json::Value::as_u64) {
456            config.itq_n_iter = n as usize;
457        }
458    }
459    Ok(())
460}
461
462fn apply_overrides(config: &mut LittleBitConfig, overrides: &LittleBitConfigOverrides) {
463    if let Some(qf) = overrides.quant_func {
464        config.quant_func = qf;
465    }
466    if let Some(eff_bit) = overrides.eff_bit {
467        config.eff_bit = eff_bit;
468    }
469    if let Some(spec) = &overrides.eff_bit_layers {
470        config.eff_bit_layers = spec.clone();
471    }
472    if let Some(split_dim) = overrides.split_dim {
473        config.split_dim = split_dim;
474    }
475    if let Some(residual) = overrides.residual {
476        config.residual = residual;
477    }
478    if let Some(kv_factor) = overrides.kv_factor {
479        config.kv_factor = kv_factor;
480    }
481    if let Some(min_split_dim) = overrides.min_split_dim {
482        config.min_split_dim = min_split_dim;
483    }
484    if let Some(quant_mod) = &overrides.quant_mod {
485        config.quant_mod = quant_mod.clone();
486    }
487    if let Some(use_itq) = overrides.use_itq {
488        config.use_itq = use_itq;
489    }
490    if let Some(itq_n_iter) = overrides.itq_n_iter {
491        config.itq_n_iter = itq_n_iter;
492    }
493}
494
495/// Parse a per-block effective-bit specification such as `"0-7,27:2.0;12:1.5"`.
496///
497/// Matches `littlebit-bench/patches/mixed-bits.patch::parse_eff_bit_layers`.
498/// Each `;`-delimited group has `<blocks>:<eff_bit>` where `<blocks>` is a comma-separated
499/// list of single indices or inclusive `a-b` ranges. Each group's block indices are
500/// deduplicated and sorted ascending. Returns an empty vector for `None` or blank strings.
501///
502/// # Errors
503/// Returns [`LittleBitError::InvalidConfig`] if any group lacks `:`, contains an invalid or
504/// reversed block range, contains an empty block list, or specifies a non-positive/non-finite bit target.
505pub fn parse_eff_bit_layers(spec: Option<&str>) -> Result<Vec<(Vec<usize>, f64)>> {
506    let Some(raw) = spec else {
507        return Ok(Vec::new());
508    };
509    if raw.trim().is_empty() {
510        return Ok(Vec::new());
511    }
512
513    let mut out = Vec::new();
514    for raw_group in raw.split(';') {
515        let group = raw_group.trim();
516        if group.is_empty() {
517            continue;
518        }
519        let (blocks_s, bits_s) = group.rsplit_once(':').ok_or_else(|| {
520            LittleBitError::InvalidConfig(format!(
521                "invalid eff_bit_layers group `{group}` (expected `<blocks>:<eff_bit>`)"
522            ))
523        })?;
524        let bits: f64 = bits_s.trim().parse().map_err(|_| {
525            LittleBitError::InvalidConfig(format!(
526                "invalid eff_bit value `{bits_s}` in eff_bit_layers group `{group}`"
527            ))
528        })?;
529        if !bits.is_finite() || bits <= 0.0 {
530            return Err(LittleBitError::InvalidConfig(format!(
531                "eff_bit in eff_bit_layers must be finite and positive, got {bits}"
532            )));
533        }
534
535        let mut blocks = BTreeSet::new();
536        for raw_part in blocks_s.split(',') {
537            let part = raw_part.trim();
538            if part.is_empty() {
539                return Err(LittleBitError::InvalidConfig(format!(
540                    "empty block specification in eff_bit_layers group `{group}`"
541                )));
542            }
543            if let Some((a_s, b_s)) = part.split_once('-') {
544                let start: usize = a_s.trim().parse().map_err(|_| {
545                    LittleBitError::InvalidConfig(format!(
546                        "invalid range start `{a_s}` in eff_bit_layers group `{group}`"
547                    ))
548                })?;
549                let end: usize = b_s.trim().parse().map_err(|_| {
550                    LittleBitError::InvalidConfig(format!(
551                        "invalid range end `{b_s}` in eff_bit_layers group `{group}`"
552                    ))
553                })?;
554                if start > end {
555                    return Err(LittleBitError::InvalidConfig(format!(
556                        "invalid descending range `{part}` in eff_bit_layers group `{group}`"
557                    )));
558                }
559                for idx in start..=end {
560                    blocks.insert(idx);
561                }
562            } else {
563                let idx: usize = part.parse().map_err(|_| {
564                    LittleBitError::InvalidConfig(format!(
565                        "invalid block index `{part}` in eff_bit_layers group `{group}`"
566                    ))
567                })?;
568                blocks.insert(idx);
569            }
570        }
571
572        if blocks.is_empty() {
573            return Err(LittleBitError::InvalidConfig(format!(
574                "no block indices found in eff_bit_layers group `{group}`"
575            )));
576        }
577        out.push((blocks.into_iter().collect(), bits));
578    }
579
580    Ok(out)
581}
582
583/// Resolved bit-budget and rank geometry for a single quantized linear layer.
584#[derive(Debug, Clone, Copy, PartialEq)]
585pub struct BitBudget {
586    /// Input feature dimension `a`.
587    pub in_features: usize,
588    /// Output feature dimension `b`.
589    pub out_features: usize,
590    /// Requested effective bits per weight (`None` when fixed `split_dim` was used).
591    pub eff_bit_target: Option<f64>,
592    /// Final quantized inner rank `s` (rounded to a multiple of 8 with `min_split_dim` floor).
593    pub split_dim: usize,
594    /// Actual effective bits per weight achieved by `(in_features, out_features, split_dim, residual)`.
595    pub eff_bit_actual: f64,
596    /// Total bit footprint `eff_bit_actual * in_features * out_features`.
597    pub total_bit_usage: f64,
598    /// Single vs. dual residual factorization mode.
599    pub residual: ResidualMode,
600}
601
602impl BitBudget {
603    /// Compute the exact layer rank and bit budget using the upstream LittleBit formula.
604    #[must_use]
605    pub fn resolve(
606        in_features: usize,
607        out_features: usize,
608        config: &LittleBitConfig,
609        ratio_factor: f64,
610    ) -> Self {
611        let residual = config.residual_mode();
612        let split_calc_float =
613            estimate_split_dim(in_features, out_features, config.eff_bit, residual)
614                .map(|v| v * ratio_factor);
615        let split_dim =
616            finalize_split_dim(split_calc_float, config.split_dim, config.min_split_dim);
617        let eff_bit_actual = compute_eff_bits(in_features, out_features, split_dim, residual);
618        let total_bit_usage = eff_bit_actual * (in_features as f64) * (out_features as f64);
619        Self {
620            in_features,
621            out_features,
622            eff_bit_target: config.eff_bit,
623            split_dim,
624            eff_bit_actual,
625            total_bit_usage,
626            residual,
627        }
628    }
629}
630
631/// Estimate the floating-point latent rank `split_dim` needed to match `eff_bit_target`.
632///
633/// Matches `LittleBitLinear._estimate_split_dim`.
634#[must_use]
635pub fn estimate_split_dim(
636    in_features: usize,
637    out_features: usize,
638    eff_bit_target: Option<f64>,
639    residual: ResidualMode,
640) -> Option<f64> {
641    let target = eff_bit_target?;
642    let a = in_features as f64;
643    let b = out_features as f64;
644    if in_features == 0 || out_features == 0 {
645        return None;
646    }
647
648    let base = a + b + 16.0;
649    let (numerator, denominator) = match residual {
650        ResidualMode::Dual => (a * b * target - 32.0 * (a + b), 2.0 * base),
651        ResidualMode::Single => (a * b * target - 16.0 * (a + b), base),
652    };
653    if denominator == 0.0 {
654        None
655    } else {
656        Some(numerator / denominator)
657    }
658}
659
660/// Round `split_float` (or `split_default`) down to a multiple of 8 with a minimum floor.
661///
662/// Matches `LittleBitLinear._finalize_split_dim`.
663#[must_use]
664pub fn finalize_split_dim(
665    split_float: Option<f64>,
666    split_default: usize,
667    min_split_dim: usize,
668) -> usize {
669    let cand = match split_float {
670        Some(v) => v as isize,
671        None => split_default as isize,
672    };
673    let mut rounded = cand.div_euclid(8) * 8;
674    if rounded == 0 {
675        rounded = min_split_dim as isize;
676    }
677    rounded.max(min_split_dim as isize) as usize
678}
679
680/// Compute actual effective bits per weight for a layer geometry.
681///
682/// Matches `LittleBitLinear._compute_eff_bits`:
683/// - `Single`: `(s * (a + b + 16) + 16 * (a + b)) / (a * b)`
684/// - `Dual`: `(s * 2 * (a + b + 16) + 32 * (a + b)) / (a * b)`
685#[must_use]
686pub fn compute_eff_bits(
687    in_features: usize,
688    out_features: usize,
689    split_dim: usize,
690    residual: ResidualMode,
691) -> f64 {
692    if in_features == 0 || out_features == 0 {
693        return f64::INFINITY;
694    }
695    let a = in_features as f64;
696    let b = out_features as f64;
697    let s = split_dim as f64;
698    let num = match residual {
699        ResidualMode::Dual => s * 2.0 * (a + b + 16.0) + 32.0 * (a + b),
700        ResidualMode::Single => s * (a + b + 16.0) + 16.0 * (a + b),
701    };
702    num / (a * b)
703}
704
705#[cfg(test)]
706mod tests {
707    use super::*;
708    use tempfile::TempDir;
709
710    #[test]
711    fn bit_budget_matches_upstream_llama7b_shapes() {
712        let cfg = LittleBitConfig {
713            eff_bit: Some(0.1),
714            residual: true,
715            min_split_dim: 8,
716            ..Default::default()
717        };
718        // 4096 x 4096 at 0.1 bpw with residual=True
719        let b1 = BitBudget::resolve(4096, 4096, &cfg, 1.0);
720        let raw = (4096.0_f64 * 4096.0 * 0.1 - 32.0 * 8192.0) / (2.0 * (8192.0 + 16.0));
721        let expected_s = ((raw as isize).div_euclid(8) * 8).max(8) as usize;
722        assert_eq!(b1.split_dim, expected_s);
723        assert!(b1.eff_bit_actual <= 0.11);
724
725        // kv_factor scales the rank before rounding
726        let b_kv = BitBudget::resolve(4096, 1024, &cfg, 2.0);
727        assert!(b_kv.split_dim >= 8);
728        assert_eq!(b_kv.split_dim % 8, 0);
729    }
730
731    #[test]
732    fn finalize_split_dim_floors_zero_and_negatives() {
733        assert_eq!(finalize_split_dim(Some(-42.5), 1024, 8), 8);
734        assert_eq!(finalize_split_dim(Some(7.9), 1024, 8), 8);
735        assert_eq!(finalize_split_dim(Some(63.9), 1024, 8), 56);
736        assert_eq!(finalize_split_dim(None, 1024, 8), 1024);
737    }
738
739    #[test]
740    fn config_priority_follows_overrides_then_littlebit_then_legacy() {
741        let dir = TempDir::new().expect("tempdir");
742        fs::write(
743            dir.path().join("config.json"),
744            r#"{"quant_func": "SmoothSign", "split_dim": 512, "use_itq": true}"#,
745        )
746        .expect("write config.json");
747        fs::write(
748            dir.path().join("littlebit_config.json"),
749            r#"{"eff_bit": 0.25, "residual": true}"#,
750        )
751        .expect("write littlebit_config.json");
752
753        let overrides = LittleBitConfigOverrides {
754            split_dim: Some(256),
755            ..Default::default()
756        };
757        let resolved =
758            LittleBitConfig::load_with_priority(dir.path(), &overrides).expect("load config");
759        assert_eq!(
760            resolved.quant_func,
761            QuantFunc::SmoothSign {
762                alpha: SMOOTH_SIGN_DEFAULT_ALPHA
763            }
764        );
765        assert_eq!(resolved.eff_bit, Some(0.25));
766        assert!(resolved.residual);
767        assert!(resolved.use_itq);
768        assert_eq!(resolved.split_dim, 256);
769    }
770}