use burn::{
prelude::TensorData,
tensor::{
DType,
Element,
FloatDType,
Tolerance,
bf16,
f16,
},
};
use num_traits::Float;
use serde::{
Deserialize,
Serialize,
};
use crate::{
errors::{
BunsenError,
BunsenResult,
},
prelude::TensorDataCheckExt,
};
pub fn unpack_tolerance<F: Float + Sized>(tolerance: Tolerance<F>) -> (F, F) {
#[repr(C)]
struct ToleranceShim<F> {
pub relative: F,
pub absolute: F,
}
assert_eq!(
std::mem::size_of::<Tolerance<F>>(),
std::mem::size_of::<ToleranceShim<F>>(),
);
let tolerance = std::mem::ManuallyDrop::new(tolerance);
let shim: ToleranceShim<F> =
unsafe { std::mem::transmute_copy::<Tolerance<F>, ToleranceShim<F>>(&tolerance) };
(shim.relative, shim.absolute)
}
#[derive(Default, Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(tag = "kind")]
pub enum TolerancePolicy {
Strict,
#[default]
Balanced,
Permissive,
Relative {
relative: f64,
},
Absolute {
absolute: f64,
},
RelAbs {
relative: f64,
absolute: f64,
},
}
impl TolerancePolicy {
pub fn validate(&self) -> BunsenResult<()> {
let check_relative = |relative: f64| -> BunsenResult<()> {
if !(0.0..=1.0).contains(&relative) {
return Err(BunsenError::InvalidArgument {
msg: format!("relative tolerance ({relative}) is not in 0.0..=1.0"),
});
}
Ok(())
};
let check_absolute = |absolute: f64| -> BunsenResult<()> {
if absolute < 0.0 {
return Err(BunsenError::InvalidArgument {
msg: format!("absolute tolerance ({absolute}) is negative"),
});
}
Ok(())
};
match *self {
Self::Strict | Self::Balanced | Self::Permissive => Ok(()),
Self::Relative { relative } => check_relative(relative),
Self::Absolute { absolute } => check_absolute(absolute),
Self::RelAbs { relative, absolute } => {
check_relative(relative)?;
check_absolute(absolute)
}
}
}
pub fn to_tolerance<F: Float>(&self) -> Tolerance<F> {
match *self {
Self::Strict => Tolerance::strict(),
Self::Balanced => Tolerance::balanced(),
Self::Permissive => Tolerance::permissive(),
Self::Relative { relative } => Tolerance::relative(relative),
Self::Absolute { absolute } => Tolerance::absolute(absolute),
Self::RelAbs { relative, absolute } => Tolerance::rel_abs(relative, absolute),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct ToleranceDesc {
#[serde(with = "crate::burner::descriptors::shims::FloatDTypeShim")]
float_dtype: FloatDType,
policy: TolerancePolicy,
}
impl ToleranceDesc {
pub fn new(
dtype: FloatDType,
policy: TolerancePolicy,
) -> BunsenResult<Self> {
policy.validate()?;
Ok(Self {
float_dtype: dtype,
policy,
})
}
pub fn try_from_dtype(
dtype: DType,
policy: TolerancePolicy,
) -> BunsenResult<Self> {
if !dtype.is_float() {
return Err(BunsenError::InvalidArgument {
msg: format!("dtype ({dtype:?}) is not a float type"),
});
}
Self::new(FloatDType::from(dtype), policy)
}
pub fn of<F: Float + Element>(policy: TolerancePolicy) -> BunsenResult<Self> {
Self::new(FloatDType::from(F::dtype()), policy)
}
pub fn float_dtype(&self) -> FloatDType {
self.float_dtype
}
pub fn dtype(&self) -> DType {
self.float_dtype.into()
}
pub fn policy(&self) -> TolerancePolicy {
self.policy
}
pub fn to_tolerance_as<F: Float>(&self) -> Tolerance<F> {
self.policy.to_tolerance()
}
pub fn try_assert_tensor_data_approx_eq(
&self,
actual: &TensorData,
expected: &TensorData,
strict: bool,
) -> BunsenResult<()> {
match self.float_dtype {
FloatDType::F64 => {
actual.try_assert_approx_eq::<f64>(expected, self.policy.to_tolerance(), strict)
}
FloatDType::F32 | FloatDType::Flex32 => {
actual.try_assert_approx_eq::<f32>(expected, self.policy.to_tolerance(), strict)
}
FloatDType::F16 => {
actual.try_assert_approx_eq::<f16>(expected, self.policy.to_tolerance(), strict)
}
FloatDType::BF16 => {
actual.try_assert_approx_eq::<bf16>(expected, self.policy.to_tolerance(), strict)
}
}
}
}
#[cfg(test)]
mod test {
use super::*;
#[test]
fn test_default_is_balanced() {
assert_eq!(TolerancePolicy::default(), TolerancePolicy::Balanced);
}
#[test]
fn test_strict_depends_on_float_type() {
let policy = TolerancePolicy::Strict;
let half = policy.to_tolerance::<f16>();
let single = policy.to_tolerance::<f32>();
assert!(half.approx_eq(f16::from_f32(1.0), f16::from_f32(1.001)));
assert!(!single.approx_eq(1.0f32, 1.001f32));
}
#[test]
fn test_policies_resolve_to_burn_behaviour() {
assert!(
TolerancePolicy::Permissive
.to_tolerance::<f32>()
.approx_eq(1.0, 1.005)
);
assert!(
!TolerancePolicy::Strict
.to_tolerance::<f32>()
.approx_eq(1.0, 1.005)
);
let rel_abs = TolerancePolicy::RelAbs {
relative: 0.0,
absolute: 0.01,
};
assert!(rel_abs.to_tolerance::<f32>().approx_eq(1.0, 1.005));
assert!(!rel_abs.to_tolerance::<f32>().approx_eq(1.0, 1.05));
let relative = TolerancePolicy::Relative { relative: 0.1 };
assert!(relative.to_tolerance::<f32>().approx_eq(100.0, 105.0));
assert!(!relative.to_tolerance::<f32>().approx_eq(100.0, 120.0));
let absolute = TolerancePolicy::Absolute { absolute: 0.5 };
assert!(absolute.to_tolerance::<f32>().approx_eq(100.0, 100.4));
assert!(!absolute.to_tolerance::<f32>().approx_eq(100.0, 100.6));
}
#[test]
fn test_validate() -> BunsenResult<()> {
TolerancePolicy::Strict.validate()?;
TolerancePolicy::Balanced.validate()?;
TolerancePolicy::Permissive.validate()?;
TolerancePolicy::Relative { relative: 1.0 }.validate()?;
TolerancePolicy::Absolute { absolute: 0.0 }.validate()?;
let err = TolerancePolicy::Relative { relative: 2.0 }
.validate()
.unwrap_err();
assert!(err.to_string().contains("not in 0.0..=1.0"), "{err}");
let err = TolerancePolicy::Absolute { absolute: -1.0 }
.validate()
.unwrap_err();
assert!(err.to_string().contains("is negative"), "{err}");
let err = TolerancePolicy::RelAbs {
relative: 0.5,
absolute: -1.0,
}
.validate()
.unwrap_err();
assert!(err.to_string().contains("is negative"), "{err}");
Ok(())
}
#[test]
fn test_desc_records_the_float_type() -> BunsenResult<()> {
let policy = TolerancePolicy::Balanced;
assert_eq!(
ToleranceDesc::of::<f32>(policy)?.float_dtype(),
FloatDType::F32
);
assert_eq!(
ToleranceDesc::of::<f64>(policy)?.float_dtype(),
FloatDType::F64
);
assert_eq!(
ToleranceDesc::of::<f16>(policy)?.float_dtype(),
FloatDType::F16
);
assert_eq!(
ToleranceDesc::of::<bf16>(policy)?.float_dtype(),
FloatDType::BF16
);
assert_eq!(ToleranceDesc::of::<f32>(policy)?.policy(), policy);
Ok(())
}
#[test]
fn test_desc_equality_includes_dtype() -> BunsenResult<()> {
let policy = TolerancePolicy::Strict;
assert_ne!(
ToleranceDesc::of::<f32>(policy)?,
ToleranceDesc::of::<f16>(policy)?
);
Ok(())
}
#[test]
fn test_new_rejects_non_float_dtype() {
let err = ToleranceDesc::try_from_dtype(DType::I32, TolerancePolicy::Balanced).unwrap_err();
assert!(err.to_string().contains("is not a float type"), "{err}");
}
#[test]
fn test_new_rejects_invalid_policy() {
let err = ToleranceDesc::new(FloatDType::F32, TolerancePolicy::Relative { relative: 2.0 })
.unwrap_err();
assert!(err.to_string().contains("not in 0.0..=1.0"), "{err}");
}
#[test]
fn test_flex32_is_preserved_and_compares_as_f32() -> BunsenResult<()> {
let desc = ToleranceDesc::try_from_dtype(DType::Flex32, TolerancePolicy::Balanced)?;
assert_eq!(desc.float_dtype(), FloatDType::Flex32);
desc.try_assert_tensor_data_approx_eq(
&TensorData::from([1.0f32]),
&TensorData::from([1.001f32]),
true,
)
}
#[test]
fn test_assert_dispatches_at_recorded_dtype() -> BunsenResult<()> {
let a = TensorData::from([1.0f32]);
let b = TensorData::from([1.001f32]);
ToleranceDesc::of::<f16>(TolerancePolicy::Strict)?
.try_assert_tensor_data_approx_eq(&a, &b, true)
}
#[test]
fn test_assert_dispatches_at_recorded_dtype_f32() -> BunsenResult<()> {
let a = TensorData::from([1.0f32]);
let b = TensorData::from([1.001f32]);
let err = ToleranceDesc::of::<f32>(TolerancePolicy::Strict)?
.try_assert_tensor_data_approx_eq(&a, &b, true)
.unwrap_err();
assert!(err.to_string().contains("Position 0: 1 != 1.001"), "{err}");
Ok(())
}
#[test]
fn test_policy_serde_round_trip() -> BunsenResult<()> {
for policy in [
TolerancePolicy::Strict,
TolerancePolicy::Balanced,
TolerancePolicy::Permissive,
TolerancePolicy::Relative { relative: 0.25 },
TolerancePolicy::Absolute { absolute: 1e-5 },
TolerancePolicy::RelAbs {
relative: 0.01,
absolute: 1e-6,
},
] {
let json = serde_json::to_string(&policy).unwrap();
let back: TolerancePolicy = serde_json::from_str(&json).unwrap();
assert_eq!(policy, back, "round trip failed for {json}");
}
assert_eq!(
serde_json::to_string(&TolerancePolicy::Strict).unwrap(),
r#"{"kind":"Strict"}"#
);
Ok(())
}
#[test]
fn test_desc_serde_round_trip() -> BunsenResult<()> {
let desc = ToleranceDesc::of::<f16>(TolerancePolicy::RelAbs {
relative: 0.01,
absolute: 1e-6,
})?;
let json = serde_json::to_string(&desc).unwrap();
let back: ToleranceDesc = serde_json::from_str(&json).unwrap();
assert_eq!(desc, back);
assert!(json.contains("F16"), "{json}");
Ok(())
}
}