use crate::descriptor::TensorDescriptor;
use crate::descriptor::{CompositeMemberDescriptor, MemberRole};
use crate::layout::{CompositionRule, LayoutDescriptor};
use crate::{Error, Result};
pub const MAX_COMPOSITE_DEPTH: u8 = 8;
#[derive(Debug, Clone, PartialEq)]
pub struct CompositeTensor {
pub head: TensorDescriptor,
pub members: Vec<TensorDescriptor>,
}
impl CompositeTensor {
pub fn new(head: TensorDescriptor, members: Vec<TensorDescriptor>) -> Result<Self> {
Self::new_at_depth(head, members, 0)
}
pub(crate) fn new_at_depth(
head: TensorDescriptor,
members: Vec<TensorDescriptor>,
depth: u8,
) -> Result<Self> {
if depth >= MAX_COMPOSITE_DEPTH {
return Err(Error::SubpavingNestingTooDeep);
}
let mut validator = CompositeValidator::new(&head)?;
for member in &members {
if matches!(member.layout, LayoutDescriptor::Composite(_))
&& depth + 1 >= MAX_COMPOSITE_DEPTH
{
return Err(Error::SubpavingNestingTooDeep);
}
validator.push_member(member)?;
}
validator.finish()?;
Ok(Self { head, members })
}
pub fn rule(&self) -> &CompositionRule {
match &self.head.layout {
LayoutDescriptor::Composite(c) => &c.rule,
_ => unreachable!(
"CompositeTensor invariant: head.layout is always LayoutDescriptor::Composite"
),
}
}
pub fn member_count(&self) -> u32 {
match &self.head.layout {
LayoutDescriptor::Composite(c) => c.member_count,
_ => unreachable!(
"CompositeTensor invariant: head.layout is always LayoutDescriptor::Composite"
),
}
}
}
pub struct CompositeValidator {
rule: CompositionRule,
declared_member_count: u32,
head_shape_dims: Vec<u64>,
head_type_tag: u8,
members_seen: usize,
partition_boxes: Vec<(Vec<u64>, Vec<u64>)>,
}
impl CompositeValidator {
pub fn new(head: &TensorDescriptor) -> Result<Self> {
let composite_layout = match &head.layout {
LayoutDescriptor::Composite(c) => c,
other => {
return Err(Error::InvalidLayout(format!(
"composite head's layout_tag must be 0x0B (Composite), got 0x{:02X}",
other.tag()
)))
}
};
let rule = composite_layout.rule.clone();
if !matches!(rule, CompositionRule::Group) && head.shape.has_dynamic() {
return Err(Error::InvalidLayout(
"partition/overlay composite head shape MUST NOT contain a DYNAMIC dimension \
(coverage/volume math requires a fully static shape)"
.to_string(),
));
}
Ok(Self {
rule,
declared_member_count: composite_layout.member_count,
head_shape_dims: head.shape.dims().to_vec(),
head_type_tag: head.element_type.tag(),
members_seen: 0,
partition_boxes: Vec::new(),
})
}
pub fn push_member(&mut self, member: &TensorDescriptor) -> Result<()> {
let index = self.members_seen;
let rule = self.rule.clone();
match rule {
CompositionRule::Partition => {
let shard = self.shard_box(member, index)?;
self.check_member_type(member, index)?;
self.reject_composite_member_flag(member)?;
self.partition_boxes
.push((shard.shard_offset.clone(), member.shape.dims().to_vec()));
}
CompositionRule::Overlay(_) => {
self.shard_box(member, index)?;
self.check_member_type(member, index)?;
self.check_overlay_member_role(member, index)?;
}
CompositionRule::Group => {
self.reject_composite_member_flag(member)?;
}
}
self.members_seen += 1;
Ok(())
}
pub fn finish(self) -> Result<()> {
if self.members_seen as u32 != self.declared_member_count {
return Err(Error::CompositeMemberCountMismatch {
declared: self.declared_member_count,
actual: self.members_seen,
});
}
match self.rule {
CompositionRule::Partition => self.validate_partition_coverage(),
CompositionRule::Overlay(_) => {
if self.members_seen == 0 {
return Err(Error::CompositeOverlayEmpty);
}
Ok(())
}
CompositionRule::Group => Ok(()),
}
}
fn shard_box<'a>(
&self,
member: &'a TensorDescriptor,
index: usize,
) -> Result<&'a crate::descriptor::ShardDescriptor> {
let shard = member
.shard
.as_ref()
.ok_or(Error::CompositeMemberMissingShard { index })?;
if shard.parent_shape.as_slice() != self.head_shape_dims.as_slice() {
return Err(Error::CompositeMemberParentShapeMismatch { index });
}
shard.validate_against_shape(&member.shape)?;
Ok(shard)
}
fn check_member_type(&self, member: &TensorDescriptor, index: usize) -> Result<()> {
if member.quantization.is_some() {
return Ok(());
}
let member_tag = member.element_type.tag();
if member_tag != self.head_type_tag {
return Err(Error::CompositeMemberTypeMismatch {
index,
member: member_tag,
head: self.head_type_tag,
});
}
Ok(())
}
fn check_overlay_member_role(&self, member: &TensorDescriptor, index: usize) -> Result<()> {
let cm: &CompositeMemberDescriptor =
member
.composite_member
.as_ref()
.ok_or(Error::CompositeMemberFlagMismatch {
rule: self.rule.rule_byte(),
has_flag: false,
})?;
if index == 0 {
if cm.member_role != MemberRole::Base {
return Err(Error::CompositeOverlayBaseNotFirst);
}
let shard = member
.shard
.as_ref()
.ok_or(Error::CompositeMemberMissingShard { index })?;
let spans_fully = shard.shard_offset.iter().all(|&o| o == 0)
&& member.shape.dims() == self.head_shape_dims.as_slice();
if !spans_fully {
return Err(Error::CompositeOverlayBaseNotSpanning);
}
} else if cm.member_role != MemberRole::Correction {
return Err(Error::CompositeOverlayBaseNotFirst);
}
Ok(())
}
fn reject_composite_member_flag(&self, member: &TensorDescriptor) -> Result<()> {
if member.composite_member.is_some() {
return Err(Error::CompositeMemberFlagMismatch {
rule: self.rule.rule_byte(),
has_flag: true,
});
}
Ok(())
}
fn validate_partition_coverage(&self) -> Result<()> {
let n = self.partition_boxes.len();
for i in 0..n {
for j in (i + 1)..n {
if boxes_overlap(&self.partition_boxes[i], &self.partition_boxes[j]) {
return Err(Error::CompositePartitionOverlap { a: i, b: j });
}
}
}
let total = self.head_shape_dims.iter().try_fold(1u64, |acc, &d| {
if d == crate::shape::DYNAMIC {
None
} else {
acc.checked_mul(d)
}
});
if let Some(total) = total {
let mut covered: Option<u64> = Some(0);
for (_, member_shape) in &self.partition_boxes {
let vol = member_shape.iter().try_fold(1u64, |acc, &d| {
if d == crate::shape::DYNAMIC {
None
} else {
acc.checked_mul(d)
}
});
covered = match (covered, vol) {
(Some(c), Some(v)) => c.checked_add(v),
_ => None,
};
}
if let Some(covered) = covered {
if covered != total {
return Err(Error::CompositePartitionGap);
}
}
}
Ok(())
}
}
fn boxes_overlap(a: &(Vec<u64>, Vec<u64>), b: &(Vec<u64>, Vec<u64>)) -> bool {
let (a_off, a_shape) = a;
let (b_off, b_shape) = b;
a_off
.iter()
.zip(a_shape)
.zip(b_off.iter().zip(b_shape))
.all(|((&ao, &asz), (&bo, &bsz))| {
ao < bo.saturating_add(bsz) && bo < ao.saturating_add(asz)
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::layout::{CombineOp, CompositeLayout};
use crate::{BufferHandle, DeviceTag, Error, Shape, ShardDescriptor, SyncMode};
fn buf(byte_size: u64) -> BufferHandle {
BufferHandle::new(
byte_size,
crate::MIN_BUFFER_ALIGNMENT,
DeviceTag::Cpu,
SyncMode::ProducerSynced,
)
.unwrap()
}
fn composite_head(
rule: CompositionRule,
member_count: u32,
shape: Vec<u64>,
ty: crate::ElementType,
) -> TensorDescriptor {
let layout = LayoutDescriptor::Composite(CompositeLayout::new(rule, member_count).unwrap());
TensorDescriptor::new(
1,
0,
ty,
Shape::new(shape).unwrap(),
0,
layout,
vec![],
None,
None,
None,
None,
)
.unwrap()
}
fn dense_member(
ty: crate::ElementType,
shape: Vec<u64>,
shard: Option<ShardDescriptor>,
) -> TensorDescriptor {
TensorDescriptor::new(
1,
0,
ty,
Shape::new(shape).unwrap(),
0,
LayoutDescriptor::RowMajor,
vec![buf(64)],
None,
shard,
None,
None,
)
.unwrap()
}
fn shard(parent: Vec<u64>, offset: Vec<u64>) -> ShardDescriptor {
ShardDescriptor::new(parent, offset).unwrap()
}
#[test]
fn partition_exact_tiling_accepted() {
let head = composite_head(
CompositionRule::Partition,
2,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Float32,
vec![8, 4],
Some(shard(vec![8, 8], vec![0, 0])),
);
let m1 = dense_member(
crate::ElementType::Float32,
vec![8, 4],
Some(shard(vec![8, 8], vec![0, 4])),
);
let composite = CompositeTensor::new(head, vec![m0, m1]).unwrap();
assert_eq!(composite.member_count(), 2);
assert_eq!(*composite.rule(), CompositionRule::Partition);
}
#[test]
fn partition_four_way_tiling_accepted() {
let head = composite_head(
CompositionRule::Partition,
4,
vec![8, 8],
crate::ElementType::Float32,
);
let members = [(0u64, 0u64), (0, 4), (4, 0), (4, 4)]
.into_iter()
.map(|(r, c)| {
dense_member(
crate::ElementType::Float32,
vec![4, 4],
Some(shard(vec![8, 8], vec![r, c])),
)
})
.collect::<Vec<_>>();
let composite = CompositeTensor::new(head, members).unwrap();
assert_eq!(composite.member_count(), 4);
}
#[test]
fn partition_gap_rejected() {
let head = composite_head(
CompositionRule::Partition,
2,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Float32,
vec![8, 3],
Some(shard(vec![8, 8], vec![0, 0])),
);
let m1 = dense_member(
crate::ElementType::Float32,
vec![8, 3],
Some(shard(vec![8, 8], vec![0, 3])),
);
let err = CompositeTensor::new(head, vec![m0, m1]).unwrap_err();
assert!(matches!(err, Error::CompositePartitionGap));
}
#[test]
fn partition_overlap_rejected() {
let head = composite_head(
CompositionRule::Partition,
2,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Float32,
vec![8, 5],
Some(shard(vec![8, 8], vec![0, 0])),
);
let m1 = dense_member(
crate::ElementType::Float32,
vec![8, 5],
Some(shard(vec![8, 8], vec![0, 3])),
);
let err = CompositeTensor::new(head, vec![m0, m1]).unwrap_err();
assert!(matches!(
err,
Error::CompositePartitionOverlap { a: 0, b: 1 }
));
}
#[test]
fn partition_member_missing_shard_rejected() {
let head = composite_head(
CompositionRule::Partition,
1,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(crate::ElementType::Float32, vec![8, 8], None);
let err = CompositeTensor::new(head, vec![m0]).unwrap_err();
assert!(matches!(
err,
Error::CompositeMemberMissingShard { index: 0 }
));
}
#[test]
fn partition_member_parent_shape_mismatch_rejected() {
let head = composite_head(
CompositionRule::Partition,
1,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Float32,
vec![8, 8],
Some(shard(vec![10, 10], vec![0, 0])),
);
let err = CompositeTensor::new(head, vec![m0]).unwrap_err();
assert!(matches!(
err,
Error::CompositeMemberParentShapeMismatch { index: 0 }
));
}
#[test]
fn partition_member_out_of_bounds_rejected() {
let head = composite_head(
CompositionRule::Partition,
1,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Float32,
vec![8, 8],
Some(shard(vec![8, 8], vec![0, 4])),
);
let err = CompositeTensor::new(head, vec![m0]).unwrap_err();
assert!(matches!(err, Error::ShardOutOfBounds { .. }));
}
#[test]
fn partition_member_type_mismatch_rejected() {
let head = composite_head(
CompositionRule::Partition,
1,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Int8,
vec![8, 8],
Some(shard(vec![8, 8], vec![0, 0])),
);
let err = CompositeTensor::new(head, vec![m0]).unwrap_err();
assert!(matches!(
err,
Error::CompositeMemberTypeMismatch { index: 0, .. }
));
}
#[test]
fn partition_quantized_member_type_mismatch_not_rejected() {
let head = composite_head(
CompositionRule::Partition,
1,
vec![8, 8],
crate::ElementType::Float16,
);
let m0 = TensorDescriptor::new(
1,
0,
crate::ElementType::Int4,
Shape::new(vec![8u64, 8]).unwrap(),
0,
LayoutDescriptor::RowMajor,
vec![buf(64)],
Some(vec![0x01, 0x00, 0x00, 0x00]),
Some(shard(vec![8, 8], vec![0, 0])),
None,
None,
)
.unwrap();
let composite = CompositeTensor::new(head, vec![m0]).unwrap();
assert_eq!(composite.member_count(), 1);
}
#[test]
fn partition_member_illegal_composite_member_flag_rejected() {
let head = composite_head(
CompositionRule::Partition,
1,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Float32,
vec![8, 8],
Some(shard(vec![8, 8], vec![0, 0])),
)
.with_composite_member(CompositeMemberDescriptor::new(MemberRole::Base));
let err = CompositeTensor::new(head, vec![m0]).unwrap_err();
assert!(matches!(
err,
Error::CompositeMemberFlagMismatch { has_flag: true, .. }
));
}
#[test]
fn partition_member_count_mismatch_rejected() {
let head = composite_head(
CompositionRule::Partition,
2,
vec![8, 8],
crate::ElementType::Float32,
);
let m0 = dense_member(
crate::ElementType::Float32,
vec![8, 8],
Some(shard(vec![8, 8], vec![0, 0])),
);
let err = CompositeTensor::new(head, vec![m0]).unwrap_err();
assert!(matches!(
err,
Error::CompositeMemberCountMismatch {
declared: 2,
actual: 1,
}
));
}
#[test]
fn partition_dynamic_head_shape_rejected() {
let layout = LayoutDescriptor::Composite(
CompositeLayout::new(CompositionRule::Partition, 0).unwrap(),
);
let head = TensorDescriptor::new(
1,
0,
crate::ElementType::Float32,
Shape::new(vec![crate::shape::DYNAMIC, 8]).unwrap(),
0,
layout,
vec![],
None,
None,
None,
None,
)
.unwrap();
let err = CompositeTensor::new(head, vec![]).unwrap_err();
assert!(matches!(err, Error::InvalidLayout(_)));
}
fn base_member(ty: crate::ElementType, head_shape: Vec<u64>) -> TensorDescriptor {
let offset = vec![0u64; head_shape.len()];
dense_member(ty, head_shape.clone(), Some(shard(head_shape, offset)))
.with_composite_member(CompositeMemberDescriptor::new(MemberRole::Base))
}
fn correction_member(
ty: crate::ElementType,
head_shape: Vec<u64>,
shape: Vec<u64>,
offset: Vec<u64>,
) -> TensorDescriptor {
dense_member(ty, shape, Some(shard(head_shape, offset)))
.with_composite_member(CompositeMemberDescriptor::new(MemberRole::Correction))
}
#[test]
fn overlay_base_and_correction_replace_accepted() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Replace),
2,
vec![4, 4],
crate::ElementType::Float32,
);
let base = base_member(crate::ElementType::Float32, vec![4, 4]);
let correction = correction_member(
crate::ElementType::Float32,
vec![4, 4],
vec![2, 2],
vec![0, 0],
);
let composite = CompositeTensor::new(head, vec![base, correction]).unwrap();
assert_eq!(composite.member_count(), 2);
assert_eq!(
*composite.rule(),
CompositionRule::Overlay(CombineOp::Replace)
);
}
#[test]
fn overlay_base_and_correction_add_accepted() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Add),
2,
vec![4, 4],
crate::ElementType::Float32,
);
let base = base_member(crate::ElementType::Float32, vec![4, 4]);
let correction = correction_member(
crate::ElementType::Float32,
vec![4, 4],
vec![2, 2],
vec![1, 1],
);
let composite = CompositeTensor::new(head, vec![base, correction]).unwrap();
assert_eq!(*composite.rule(), CompositionRule::Overlay(CombineOp::Add));
}
#[test]
fn overlay_base_not_first_rejected() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Replace),
1,
vec![4, 4],
crate::ElementType::Float32,
);
let correction = correction_member(
crate::ElementType::Float32,
vec![4, 4],
vec![4, 4],
vec![0, 0],
);
let err = CompositeTensor::new(head, vec![correction]).unwrap_err();
assert!(matches!(err, Error::CompositeOverlayBaseNotFirst));
}
#[test]
fn overlay_base_appears_second_rejected() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Replace),
2,
vec![4, 4],
crate::ElementType::Float32,
);
let correction = correction_member(
crate::ElementType::Float32,
vec![4, 4],
vec![4, 4],
vec![0, 0],
);
let base = base_member(crate::ElementType::Float32, vec![4, 4]);
let err = CompositeTensor::new(head, vec![correction, base]).unwrap_err();
assert!(matches!(err, Error::CompositeOverlayBaseNotFirst));
}
#[test]
fn overlay_base_not_spanning_rejected() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Replace),
1,
vec![4, 4],
crate::ElementType::Float32,
);
let base = dense_member(
crate::ElementType::Float32,
vec![2, 2],
Some(shard(vec![4, 4], vec![0, 0])),
)
.with_composite_member(CompositeMemberDescriptor::new(MemberRole::Base));
let err = CompositeTensor::new(head, vec![base]).unwrap_err();
assert!(matches!(err, Error::CompositeOverlayBaseNotSpanning));
}
#[test]
fn overlay_zero_members_rejected() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Replace),
0,
vec![4, 4],
crate::ElementType::Float32,
);
let err = CompositeTensor::new(head, vec![]).unwrap_err();
assert!(matches!(err, Error::CompositeOverlayEmpty));
}
#[test]
fn overlay_corrections_may_overlap() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Replace),
3,
vec![4, 4],
crate::ElementType::Float32,
);
let base = base_member(crate::ElementType::Float32, vec![4, 4]);
let c0 = correction_member(
crate::ElementType::Float32,
vec![4, 4],
vec![2, 2],
vec![0, 0],
);
let c1 = correction_member(
crate::ElementType::Float32,
vec![4, 4],
vec![2, 2],
vec![0, 0],
);
let composite = CompositeTensor::new(head, vec![base, c0, c1]).unwrap();
assert_eq!(composite.member_count(), 3);
}
#[test]
fn overlay_correction_missing_composite_member_flag_rejected() {
let head = composite_head(
CompositionRule::Overlay(CombineOp::Replace),
2,
vec![4, 4],
crate::ElementType::Float32,
);
let base = base_member(crate::ElementType::Float32, vec![4, 4]);
let bad_correction = dense_member(
crate::ElementType::Float32,
vec![2, 2],
Some(shard(vec![4, 4], vec![0, 0])),
);
let err = CompositeTensor::new(head, vec![base, bad_correction]).unwrap_err();
assert!(matches!(
err,
Error::CompositeMemberFlagMismatch {
has_flag: false,
..
}
));
}
#[test]
fn group_heterogeneous_members_accepted() {
let head = composite_head(
CompositionRule::Group,
2,
vec![1],
crate::ElementType::Float32,
);
let m0 = dense_member(crate::ElementType::Int8, vec![100], None);
let m1 = dense_member(crate::ElementType::Float64, vec![3, 3, 3], None);
let composite = CompositeTensor::new(head, vec![m0, m1]).unwrap();
assert_eq!(composite.member_count(), 2);
assert_eq!(*composite.rule(), CompositionRule::Group);
}
#[test]
fn group_member_count_mismatch_rejected() {
let head = composite_head(
CompositionRule::Group,
2,
vec![1],
crate::ElementType::Float32,
);
let m0 = dense_member(crate::ElementType::Int8, vec![100], None);
let err = CompositeTensor::new(head, vec![m0]).unwrap_err();
assert!(matches!(
err,
Error::CompositeMemberCountMismatch {
declared: 2,
actual: 1,
}
));
}
#[test]
fn max_composite_depth_constant_is_8() {
assert_eq!(MAX_COMPOSITE_DEPTH, 8);
}
#[test]
fn new_at_depth_7_is_accepted() {
let head = composite_head(
CompositionRule::Group,
1,
vec![1],
crate::ElementType::Float32,
);
let m0 = dense_member(crate::ElementType::Int8, vec![4], None);
let result = CompositeTensor::new_at_depth(head, vec![m0], 7);
assert!(result.is_ok(), "depth 7 should be accepted");
}
#[test]
fn new_at_depth_8_is_rejected() {
let head = composite_head(
CompositionRule::Group,
0,
vec![1],
crate::ElementType::Float32,
);
let err = CompositeTensor::new_at_depth(head, vec![], 8).unwrap_err();
assert!(matches!(err, Error::SubpavingNestingTooDeep));
}
#[test]
fn new_at_depth_6_with_nested_composite_member_accepted() {
let head = composite_head(
CompositionRule::Group,
1,
vec![1],
crate::ElementType::Float32,
);
let nested_head = composite_head(
CompositionRule::Group,
0,
vec![1],
crate::ElementType::Float32,
);
let result = CompositeTensor::new_at_depth(head, vec![nested_head], 6);
assert!(
result.is_ok(),
"a nested composite member at depth 6 (effective depth 7) should be accepted"
);
}
#[test]
fn new_at_depth_7_with_nested_composite_member_rejected() {
let head = composite_head(
CompositionRule::Group,
1,
vec![1],
crate::ElementType::Float32,
);
let nested_head = composite_head(
CompositionRule::Group,
0,
vec![1],
crate::ElementType::Float32,
);
let err = CompositeTensor::new_at_depth(head, vec![nested_head], 7).unwrap_err();
assert!(matches!(err, Error::SubpavingNestingTooDeep));
}
#[test]
fn validator_rejects_non_composite_head_layout() {
let head = dense_member(crate::ElementType::Float32, vec![4], None);
let result = CompositeValidator::new(&head);
assert!(matches!(result, Err(Error::InvalidLayout(_))));
}
}