Struct AnnotatedRelation 

pub struct AnnotatedRelation<F: Ord, A: Semiring> { /* private fields */ }

Deterministic annotated facts over a semiring-like annotation domain.

AnnotatedRelation<F, A> stores at most one annotation per fact. Repeated insertion of the same fact combines annotations by Semiring::add in insertion order. Only non-zero annotations are stored, so exact support is the set of facts whose current annotation is not zero.

Inserting a zero annotation for an absent fact does nothing. Inserting a zero annotation for a present fact also leaves the stored annotation unchanged because zero is the additive identity. If a custom annotation domain combines to zero, the fact is removed from the annotated relation. Unlike provenance in crate::provenance, the stored value is the annotation itself rather than a witness or explanation set.

This first annotated relation slice focuses on deterministic storage, inspection, and exact support materialization. Annotated set algebra, annotated composition, temporal semantics, and broader uncertainty operators remain later work.

Examples

use relmath::{
    BinaryRelation,
    annotated::{AnnotatedRelation, Semiring},
};

#[derive(Clone, Debug, PartialEq, Eq)]
struct Count(u8);

impl Semiring for Count {
    fn zero() -> Self {
        Self(0)
    }

    fn one() -> Self {
        Self(1)
    }

    fn add(&self, rhs: &Self) -> Self {
        Self(self.0.saturating_add(rhs.0))
    }

    fn mul(&self, rhs: &Self) -> Self {
        Self(self.0.saturating_mul(rhs.0))
    }
}

let mut assignments = AnnotatedRelation::new();

assert!(assignments.insert(("Alice", "Review"), Count(1)));
assert!(assignments.insert(("Alice", "Review"), Count(2)));
assert_eq!(
    assignments.annotation_of(&("Alice", "Review")),
    Some(&Count(3))
);

let support: BinaryRelation<_, _> = assignments.to_binary_relation();
assert_eq!(support.to_vec(), vec![("Alice", "Review")]);

Implementations

impl<F: Ord, A: Semiring> AnnotatedRelation<F, A>

pub fn new() -> Self

Creates an empty annotated relation.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};
use relmath::FiniteRelation;

let relation = AnnotatedRelation::<(&str, &str), BooleanSemiring>::new();

assert!(relation.is_empty());

pub fn from_facts<I>(facts: I) -> Self

where I: IntoIterator<Item = (F, A)>,

Creates an annotated relation from (fact, annotation) entries.

Repeated facts combine annotations by Semiring::add in iterator order. Entries with zero annotations do not create stored support.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let relation = AnnotatedRelation::from_facts([
    (("alice", "read"), BooleanSemiring::TRUE),
    (("alice", "read"), BooleanSemiring::FALSE),
    (("bob", "approve"), BooleanSemiring::FALSE),
]);

assert!(relation.contains_fact(&("alice", "read")));
assert!(!relation.contains_fact(&("bob", "approve")));

Examples found in repository

examples/annotated.rs (lines 30-35)

fn main() {
    let confirmations = AnnotatedRelation::from_facts([
        (("Alice", "Math"), SupportCount(1)),
        (("Alice", "Math"), SupportCount(1)),
        (("Bob", "Physics"), SupportCount(1)),
        (("Cara", "Logic"), SupportCount::zero()),
    ]);

    let exact_completed = confirmations.to_binary_relation();
    let alice = UnaryRelation::singleton("Alice");

    assert_eq!(
        confirmations.annotation_of(&("Alice", "Math")),
        Some(&SupportCount(2))
    );
    assert_eq!(exact_completed.image(&alice).to_vec(), vec!["Math"]);
    assert!(!confirmations.contains_fact(&("Cara", "Logic")));
    assert_eq!(
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>(),
        vec![(("Alice", "Math"), 2), (("Bob", "Physics"), 1)]
    );

    println!(
        "stored support counts: {:?}",
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>()
    );
}

examples/capability_boundaries.rs (lines 27-30)

fn main() {
    let evidence = ProvenanceRelation::from_facts([
        (("alice", "review"), "directory"),
        (("bob", "approve"), "policy"),
    ]);
    let permissions = AnnotatedRelation::from_facts([
        (("alice", "review"), BooleanSemiring::TRUE),
        (("bob", "approve"), BooleanSemiring::TRUE),
    ]);
    let schedule = ValidTimeRelation::from_facts([
        (
            ("alice", "review"),
            Interval::new(1, 3).expect("expected valid interval"),
        ),
        (
            ("bob", "approve"),
            Interval::new(2, 4).expect("expected valid interval"),
        ),
    ]);

    let exact_evidence = exact_pairs(&evidence);
    let exact_permissions = exact_pairs(&permissions);
    let exact_schedule = exact_pairs(&schedule);

    assert_eq!(
        exact_evidence.to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(exact_permissions.to_vec(), exact_evidence.to_vec());
    assert_eq!(exact_schedule.to_vec(), exact_evidence.to_vec());

    assert_eq!(
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        vec!["directory"]
    );
    assert_eq!(
        permissions.annotation_of(&("alice", "review")),
        Some(&BooleanSemiring::TRUE)
    );
    assert_eq!(
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        vec![Interval::new(1, 3).expect("expected valid interval")]
    );

    println!(
        "witness={:?}, annotation={:?}, interval_support={:?}, exact_support={:?}",
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        permissions.annotation_of(&("alice", "review")),
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        exact_schedule.to_vec()
    );
}

pub fn insert(&mut self, fact: F, annotation: A) -> bool

Inserts one annotation for a fact.

Returns true when the stored support or stored annotation changes.

Repeated facts combine as current.add(&annotation). Facts whose resulting annotation is zero are removed from the relation.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let mut relation = AnnotatedRelation::new();

assert!(!relation.insert(("alice", "read"), BooleanSemiring::FALSE));
assert!(relation.insert(("alice", "read"), BooleanSemiring::TRUE));
assert!(!relation.insert(("alice", "read"), BooleanSemiring::FALSE));
assert!(relation.contains_fact(&("alice", "read")));

pub fn contains_fact(&self, fact: &F) -> bool

Returns true when the relation contains the given fact with a non-zero annotation.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let relation = AnnotatedRelation::from_facts([
    (("alice", "read"), BooleanSemiring::TRUE),
    (("bob", "approve"), BooleanSemiring::FALSE),
]);

assert!(relation.contains_fact(&("alice", "read")));
assert!(!relation.contains_fact(&("bob", "approve")));

Examples found in repository

examples/annotated.rs (line 45)

fn main() {
    let confirmations = AnnotatedRelation::from_facts([
        (("Alice", "Math"), SupportCount(1)),
        (("Alice", "Math"), SupportCount(1)),
        (("Bob", "Physics"), SupportCount(1)),
        (("Cara", "Logic"), SupportCount::zero()),
    ]);

    let exact_completed = confirmations.to_binary_relation();
    let alice = UnaryRelation::singleton("Alice");

    assert_eq!(
        confirmations.annotation_of(&("Alice", "Math")),
        Some(&SupportCount(2))
    );
    assert_eq!(exact_completed.image(&alice).to_vec(), vec!["Math"]);
    assert!(!confirmations.contains_fact(&("Cara", "Logic")));
    assert_eq!(
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>(),
        vec![(("Alice", "Math"), 2), (("Bob", "Physics"), 1)]
    );

    println!(
        "stored support counts: {:?}",
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>()
    );
}

pub fn annotation_of(&self, fact: &F) -> Option<&A>

Returns the stored annotation for one fact.

When a fact is absent, this returns None. Zero annotations are not stored, so None also means there is no stored exact support for that fact. Unlike crate::provenance::ProvenanceRelation::why, this returns the stored annotation value itself rather than a witness set.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let relation = AnnotatedRelation::from_facts([
    (("alice", "read"), BooleanSemiring::TRUE),
    (("bob", "approve"), BooleanSemiring::FALSE),
]);

assert_eq!(
    relation.annotation_of(&("alice", "read")),
    Some(&BooleanSemiring::TRUE)
);
assert_eq!(relation.annotation_of(&("bob", "approve")), None);

Examples found in repository

examples/annotated.rs (line 41)

fn main() {
    let confirmations = AnnotatedRelation::from_facts([
        (("Alice", "Math"), SupportCount(1)),
        (("Alice", "Math"), SupportCount(1)),
        (("Bob", "Physics"), SupportCount(1)),
        (("Cara", "Logic"), SupportCount::zero()),
    ]);

    let exact_completed = confirmations.to_binary_relation();
    let alice = UnaryRelation::singleton("Alice");

    assert_eq!(
        confirmations.annotation_of(&("Alice", "Math")),
        Some(&SupportCount(2))
    );
    assert_eq!(exact_completed.image(&alice).to_vec(), vec!["Math"]);
    assert!(!confirmations.contains_fact(&("Cara", "Logic")));
    assert_eq!(
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>(),
        vec![(("Alice", "Math"), 2), (("Bob", "Physics"), 1)]
    );

    println!(
        "stored support counts: {:?}",
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>()
    );
}

examples/capability_boundaries.rs (line 61)

fn main() {
    let evidence = ProvenanceRelation::from_facts([
        (("alice", "review"), "directory"),
        (("bob", "approve"), "policy"),
    ]);
    let permissions = AnnotatedRelation::from_facts([
        (("alice", "review"), BooleanSemiring::TRUE),
        (("bob", "approve"), BooleanSemiring::TRUE),
    ]);
    let schedule = ValidTimeRelation::from_facts([
        (
            ("alice", "review"),
            Interval::new(1, 3).expect("expected valid interval"),
        ),
        (
            ("bob", "approve"),
            Interval::new(2, 4).expect("expected valid interval"),
        ),
    ]);

    let exact_evidence = exact_pairs(&evidence);
    let exact_permissions = exact_pairs(&permissions);
    let exact_schedule = exact_pairs(&schedule);

    assert_eq!(
        exact_evidence.to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(exact_permissions.to_vec(), exact_evidence.to_vec());
    assert_eq!(exact_schedule.to_vec(), exact_evidence.to_vec());

    assert_eq!(
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        vec!["directory"]
    );
    assert_eq!(
        permissions.annotation_of(&("alice", "review")),
        Some(&BooleanSemiring::TRUE)
    );
    assert_eq!(
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        vec![Interval::new(1, 3).expect("expected valid interval")]
    );

    println!(
        "witness={:?}, annotation={:?}, interval_support={:?}, exact_support={:?}",
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        permissions.annotation_of(&("alice", "review")),
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        exact_schedule.to_vec()
    );
}

pub fn iter(&self) -> impl Iterator<Item = (&F, &A)>

Returns an iterator over facts and annotations in deterministic fact order.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let relation = AnnotatedRelation::from_facts([
    (("alice", "admin"), BooleanSemiring::TRUE),
    (("bob", "reviewer"), BooleanSemiring::TRUE),
]);

assert_eq!(
    relation
        .iter()
        .map(|(fact, annotation)| (*fact, *annotation))
        .collect::<Vec<_>>(),
    vec![
        (("alice", "admin"), BooleanSemiring::TRUE),
        (("bob", "reviewer"), BooleanSemiring::TRUE),
    ]
);

Examples found in repository

examples/annotated.rs (line 48)

fn main() {
    let confirmations = AnnotatedRelation::from_facts([
        (("Alice", "Math"), SupportCount(1)),
        (("Alice", "Math"), SupportCount(1)),
        (("Bob", "Physics"), SupportCount(1)),
        (("Cara", "Logic"), SupportCount::zero()),
    ]);

    let exact_completed = confirmations.to_binary_relation();
    let alice = UnaryRelation::singleton("Alice");

    assert_eq!(
        confirmations.annotation_of(&("Alice", "Math")),
        Some(&SupportCount(2))
    );
    assert_eq!(exact_completed.image(&alice).to_vec(), vec!["Math"]);
    assert!(!confirmations.contains_fact(&("Cara", "Logic")));
    assert_eq!(
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>(),
        vec![(("Alice", "Math"), 2), (("Bob", "Physics"), 1)]
    );

    println!(
        "stored support counts: {:?}",
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>()
    );
}

pub fn support(&self) -> UnaryRelation<F>

where F: Clone,

Returns the exact support relation of stored facts as a unary relation.

This materialization forgets annotation values and keeps only which facts are currently present with a non-zero annotation. Generic code can access the same relation-level boundary through crate::ExactSupport::exact_support.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let relation = AnnotatedRelation::from_facts([
    (("alice", "admin"), BooleanSemiring::TRUE),
    (("bob", "reviewer"), BooleanSemiring::TRUE),
    (("bob", "reviewer"), BooleanSemiring::FALSE),
]);

assert_eq!(
    relation.support().to_vec(),
    vec![("alice", "admin"), ("bob", "reviewer")]
);

impl<T: Ord + Clone, A: Semiring> AnnotatedRelation<T, A>

pub fn to_unary_relation(&self) -> UnaryRelation<T>

Converts scalar facts into a unary relation support set.

Generic code can access the same unary materialization boundary through crate::ToExactUnaryRelation.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let concepts = AnnotatedRelation::from_facts([
    ("Closure", BooleanSemiring::TRUE),
    ("Relations", BooleanSemiring::TRUE),
]);

assert_eq!(
    concepts.to_unary_relation().to_vec(),
    vec!["Closure", "Relations"]
);

impl<A0: Ord + Clone, B0: Ord + Clone, A: Semiring> AnnotatedRelation<(A0, B0), A>

pub fn to_binary_relation(&self) -> BinaryRelation<A0, B0>

Converts pair facts into a binary relation support set.

Generic code can access the same binary materialization boundary through crate::ToExactBinaryRelation.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let permissions = AnnotatedRelation::from_facts([
    (("Alice", "read"), BooleanSemiring::TRUE),
    (("Bob", "approve"), BooleanSemiring::TRUE),
]);

assert_eq!(
    permissions.to_binary_relation().to_vec(),
    vec![("Alice", "read"), ("Bob", "approve")]
);

Examples found in repository

examples/annotated.rs (line 37)

fn main() {
    let confirmations = AnnotatedRelation::from_facts([
        (("Alice", "Math"), SupportCount(1)),
        (("Alice", "Math"), SupportCount(1)),
        (("Bob", "Physics"), SupportCount(1)),
        (("Cara", "Logic"), SupportCount::zero()),
    ]);

    let exact_completed = confirmations.to_binary_relation();
    let alice = UnaryRelation::singleton("Alice");

    assert_eq!(
        confirmations.annotation_of(&("Alice", "Math")),
        Some(&SupportCount(2))
    );
    assert_eq!(exact_completed.image(&alice).to_vec(), vec!["Math"]);
    assert!(!confirmations.contains_fact(&("Cara", "Logic")));
    assert_eq!(
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>(),
        vec![(("Alice", "Math"), 2), (("Bob", "Physics"), 1)]
    );

    println!(
        "stored support counts: {:?}",
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>()
    );
}

impl<T: Ord + Clone, A: Semiring> AnnotatedRelation<Vec<T>, A>

pub fn to_nary_relation<I, S>( &self, schema: I, ) -> Result<NaryRelation<T>, NaryRelationError>

where I: IntoIterator<Item = S>, S: Into<String>,

Converts row facts into an n-ary relation with the given schema.

The explicit schema preserves the current exact n-ary boundary where row values do not themselves encode column names. This method reuses the current NaryRelation validation rules, so duplicate or blank column names and row-arity mismatches return NaryRelationError. Generic code can access the same n-ary materialization boundary through crate::ToExactNaryRelation.

Examples

use relmath::annotated::{AnnotatedRelation, BooleanSemiring};

let completion = AnnotatedRelation::from_facts([
    (vec!["Alice", "Math", "passed"], BooleanSemiring::TRUE),
    (vec!["Bob", "Physics", "passed"], BooleanSemiring::TRUE),
]);

let relation = completion
    .to_nary_relation(["student", "course", "status"])
    .expect("expected valid support relation");

assert_eq!(
    relation.to_rows(),
    vec![
        vec!["Alice", "Math", "passed"],
        vec!["Bob", "Physics", "passed"],
    ]
);

Trait Implementations

impl<F: Clone + Ord, A: Clone + Semiring> Clone for AnnotatedRelation<F, A>

fn clone(&self) -> AnnotatedRelation<F, A>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: Debug + Ord, A: Debug + Semiring> Debug for AnnotatedRelation<F, A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: Ord, A: Semiring> Default for AnnotatedRelation<F, A>

fn default() -> Self

Returns the “default value” for a type.

impl<F: Ord + Clone, A: Semiring> ExactSupport<F> for AnnotatedRelation<F, A>

fn exact_support(&self) -> UnaryRelation<F>

Returns the exact support of stored facts in deterministic fact order.

impl<F: Ord, A: Semiring> Extend<(F, A)> for AnnotatedRelation<F, A>

fn extend<I: IntoIterator<Item = (F, A)>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<F: Ord, A: Semiring> FiniteRelation for AnnotatedRelation<F, A>

fn len(&self) -> usize

Returns the number of stored tuples in the relation.

fn is_empty(&self) -> bool

Returns true when the relation contains no tuples.

impl<F: Ord, A: Semiring> FromIterator<(F, A)> for AnnotatedRelation<F, A>

fn from_iter<I: IntoIterator<Item = (F, A)>>(iter: I) -> Self

Creates a value from an iterator.

impl<F: PartialEq + Ord, A: PartialEq + Semiring> PartialEq for AnnotatedRelation<F, A>

fn eq(&self, other: &AnnotatedRelation<F, A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<F: Eq + Ord, A: Eq + Semiring> Eq for AnnotatedRelation<F, A>

impl<F: Ord, A: Semiring> StructuralPartialEq for AnnotatedRelation<F, A>