use crate::{ElementType, Error, Result};
pub(crate) const SCHEME_TAG: u8 = 0x04;
pub(crate) const ENCODED_LEN: usize = 16;
pub(crate) const SUPPORTED_VERSION: u8 = 0x01;
pub const NF4_MIN_BLOCK_SIZE: u32 = 8;
const RESERVED_FLAGS_MASK: u16 = 0xFFFF;
const INVALID_BUF_SENTINEL: u32 = 0xFFFF_FFFF;
const OFFSET_AXIS: usize = 4;
const OFFSET_BLOCK_SIZE: usize = 8;
const OFFSET_SCALE_BUF: usize = 12;
#[allow(clippy::excessive_precision)]
pub const NF4_LUT: [f32; 16] = [
-1.0,
-0.6961928009986877,
-0.5250730514526367,
-0.39491748809814453,
-0.28444138169288635,
-0.18477343022823334,
-0.09105003625154495,
0.0,
0.07958029955625534,
0.16093020141124725,
0.24611230194568634,
0.33791524171829224,
0.44070982933044434,
0.5626170039176941,
0.7229568362236023,
1.0,
];
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Nf4 {
axis: u32,
block_size: u32,
scale_buffer_index: u32,
}
impl Nf4 {
pub fn new(axis: u32, block_size: u32, scale_buffer_index: u32) -> Result<Self> {
validate_block_size(block_size)?;
Ok(Self {
axis,
block_size,
scale_buffer_index,
})
}
#[inline]
pub fn axis(&self) -> u32 {
self.axis
}
#[inline]
pub fn block_size(&self) -> u32 {
self.block_size
}
#[inline]
pub fn scale_buffer_index(&self) -> u32 {
self.scale_buffer_index
}
pub fn num_blocks_per_axis(&self, shape_axis: u64) -> u64 {
if shape_axis == 0 {
return 0;
}
shape_axis.div_ceil(self.block_size as u64)
}
pub fn validate_against_shape_axis(&self, shape_axis: u64) -> Result<()> {
if shape_axis == crate::shape::DYNAMIC {
return Err(Error::QuantizationShapeMismatch {
axis: self.axis,
shape_axis,
block_size: self.block_size,
reason: "shape[axis] must not be the DYNAMIC sentinel (0xFFFFFFFFFFFFFFFF)",
});
}
if shape_axis > 0 && self.block_size as u64 > shape_axis {
return Err(Error::QuantizationShapeMismatch {
axis: self.axis,
shape_axis,
block_size: self.block_size,
reason: "NF4 block_size must not exceed shape[axis] when shape[axis] > 0",
});
}
Ok(())
}
pub fn valid_storage_types() -> &'static [ElementType] {
&[ElementType::Uint4]
}
pub(crate) fn decode_payload(flags: u16, bytes: &[u8]) -> Result<Self> {
if bytes.len() < ENCODED_LEN {
return Err(Error::QuantizationDescriptorTooShort {
found: bytes.len(),
needed: ENCODED_LEN,
});
}
if flags & RESERVED_FLAGS_MASK != 0 {
return Err(Error::ReservedQuantizationFlagsBits {
flags,
mask: RESERVED_FLAGS_MASK,
});
}
let axis = u32::from_le_bytes(
bytes[OFFSET_AXIS..OFFSET_AXIS + 4]
.try_into()
.map_err(|_| Error::InvalidQuantization("axis slice error".into()))?,
);
let block_size = u32::from_le_bytes(
bytes[OFFSET_BLOCK_SIZE..OFFSET_BLOCK_SIZE + 4]
.try_into()
.map_err(|_| Error::InvalidQuantization("block_size slice error".into()))?,
);
let scale_buf = u32::from_le_bytes(
bytes[OFFSET_SCALE_BUF..OFFSET_SCALE_BUF + 4]
.try_into()
.map_err(|_| Error::InvalidQuantization("scale_buffer_index slice error".into()))?,
);
validate_block_size(block_size)?;
if scale_buf == INVALID_BUF_SENTINEL {
return Err(Error::InvalidQuantization(
"NF4 scale_buffer_index must not be 0xFFFFFFFF".into(),
));
}
Ok(Self {
axis,
block_size,
scale_buffer_index: scale_buf,
})
}
pub(crate) fn encode_payload(&self, out: &mut [u8]) {
out[OFFSET_AXIS..OFFSET_AXIS + 4].copy_from_slice(&self.axis.to_le_bytes());
out[OFFSET_BLOCK_SIZE..OFFSET_BLOCK_SIZE + 4]
.copy_from_slice(&self.block_size.to_le_bytes());
out[OFFSET_SCALE_BUF..OFFSET_SCALE_BUF + 4]
.copy_from_slice(&self.scale_buffer_index.to_le_bytes());
}
}
fn validate_block_size(block_size: u32) -> Result<()> {
if !block_size.is_power_of_two() || block_size < NF4_MIN_BLOCK_SIZE {
return Err(Error::InvalidBlockSize {
scheme_tag: SCHEME_TAG,
block_size,
min: NF4_MIN_BLOCK_SIZE,
max: u32::MAX,
});
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::Error;
#[test]
fn nf4_lut_has_16_entries() {
assert_eq!(NF4_LUT.len(), 16);
}
#[test]
fn nf4_lut_all_values_are_finite() {
for (i, &v) in NF4_LUT.iter().enumerate() {
assert!(v.is_finite(), "NF4_LUT[{i}] = {v} is not finite");
}
}
#[test]
fn nf4_lut_values_are_in_ascending_order() {
for i in 1..NF4_LUT.len() {
assert!(
NF4_LUT[i] >= NF4_LUT[i - 1],
"NF4_LUT is not ascending at index {i}: NF4_LUT[{}]={} > NF4_LUT[{}]={}",
i - 1,
NF4_LUT[i - 1],
i,
NF4_LUT[i]
);
}
}
#[test]
#[allow(clippy::assertions_on_constants)]
fn nf4_lut_straddles_zero_at_index_7_8() {
assert!(NF4_LUT[7] <= 0.0, "NF4_LUT[7] should be <= 0.0");
assert!(NF4_LUT[8] >= 0.0, "NF4_LUT[8] should be >= 0.0");
}
#[test]
fn nf4_lut_first_value_approx_neg_one() {
let diff = (NF4_LUT[0] - (-1.0f32)).abs();
assert!(
diff < 0.01,
"NF4_LUT[0] = {} is not within 0.01 of -1.0",
NF4_LUT[0]
);
}
#[test]
fn nf4_lut_last_value_approx_pos_one() {
let diff = (NF4_LUT[15] - 1.0f32).abs();
assert!(
diff < 0.01,
"NF4_LUT[15] = {} is not within 0.01 of 1.0",
NF4_LUT[15]
);
}
#[test]
fn new_block_size_below_min_is_err() {
assert!(matches!(
Nf4::new(0, 4, 1),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_block_size_not_power_of_two_is_err() {
assert!(matches!(
Nf4::new(0, 12, 1),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_block_size_1_is_err() {
assert!(matches!(
Nf4::new(0, 1, 1),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_valid_min_block_size_is_ok() {
assert!(Nf4::new(0, NF4_MIN_BLOCK_SIZE, 1).is_ok());
}
#[test]
fn new_valid_block_size_16_is_ok() {
assert!(Nf4::new(0, 16, 1).is_ok());
}
#[test]
fn new_valid_block_size_64_is_ok() {
assert!(Nf4::new(0, 64, 1).is_ok());
}
#[test]
fn num_blocks_per_axis_zero_shape_returns_zero() {
let q = Nf4::new(0, 64, 1).unwrap();
assert_eq!(q.num_blocks_per_axis(0), 0);
}
#[test]
fn num_blocks_per_axis_exact_divisibility() {
let q = Nf4::new(0, 64, 1).unwrap();
assert_eq!(q.num_blocks_per_axis(128), 2);
}
#[test]
fn num_blocks_per_axis_partial_trailing_block_uses_div_ceil() {
let q = Nf4::new(0, 64, 1).unwrap();
assert_eq!(q.num_blocks_per_axis(65), 2);
}
fn encode_decode(q: &Nf4) -> Nf4 {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[2] = 0;
buf[3] = 0;
q.encode_payload(&mut buf);
Nf4::decode_payload(0, &buf).unwrap()
}
#[test]
fn round_trip_preserves_axis_block_size_scale_buf() {
let original = Nf4::new(2, 64, 5).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded.axis(), original.axis());
assert_eq!(decoded.block_size(), original.block_size());
assert_eq!(decoded.scale_buffer_index(), original.scale_buffer_index());
}
#[test]
fn round_trip_min_block_size() {
let original = Nf4::new(0, NF4_MIN_BLOCK_SIZE, 1).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
#[test]
fn validate_against_shape_axis_ok_when_block_size_le_shape() {
let q = Nf4::new(0, 64, 1).unwrap();
assert!(q.validate_against_shape_axis(64).is_ok());
assert!(q.validate_against_shape_axis(128).is_ok());
}
#[test]
fn validate_against_shape_axis_ok_when_shape_is_zero_adr007() {
let q = Nf4::new(0, 64, 1).unwrap();
assert!(q.validate_against_shape_axis(0).is_ok());
}
#[test]
fn validate_against_shape_axis_err_when_block_size_exceeds_shape() {
let q = Nf4::new(0, 64, 1).unwrap();
assert!(matches!(
q.validate_against_shape_axis(32),
Err(Error::QuantizationShapeMismatch { .. })
));
}
#[test]
fn validate_against_shape_axis_err_for_dynamic_sentinel() {
let q = Nf4::new(0, 64, 1).unwrap();
assert!(matches!(
q.validate_against_shape_axis(u64::MAX),
Err(Error::QuantizationShapeMismatch { .. })
));
}
#[test]
fn decode_payload_too_short_is_err() {
let short = vec![0u8; ENCODED_LEN - 1];
assert!(matches!(
Nf4::decode_payload(0, &short),
Err(Error::QuantizationDescriptorTooShort { .. })
));
}
#[test]
fn decode_payload_nonzero_flags_is_err() {
let q = Nf4::new(0, 64, 1).unwrap();
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
q.encode_payload(&mut buf);
let nonzero_flags: u16 = 0x0002;
assert!(matches!(
Nf4::decode_payload(nonzero_flags, &buf),
Err(Error::ReservedQuantizationFlagsBits { .. })
));
}
#[test]
fn decode_payload_invalid_block_size_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[2] = 0;
buf[3] = 0;
buf[4..8].copy_from_slice(&0u32.to_le_bytes()); buf[8..12].copy_from_slice(&3u32.to_le_bytes());
buf[12..16].copy_from_slice(&1u32.to_le_bytes()); assert!(matches!(
Nf4::decode_payload(0, &buf),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn decode_payload_scale_buf_sentinel_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[2] = 0;
buf[3] = 0;
buf[4..8].copy_from_slice(&0u32.to_le_bytes()); buf[8..12].copy_from_slice(&64u32.to_le_bytes()); buf[12..16].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
assert!(matches!(
Nf4::decode_payload(0, &buf),
Err(Error::InvalidQuantization(_))
));
}
}