uor-foundation 0.2.0

UOR Foundation — typed Rust traits for the complete ontology. Import and implement.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

// @generated by uor-crate from uor-ontology — do not edit manually

//! `carry/` namespace — Carry chain algebra: generate/propagate/kill event classification, carry profiles, encoding configurations, and encoding quality metrics for d_Δ optimization..
//!
//! Space: Kernel

use crate::Primitives;

/// The Boolean function chain c_{k+1} = or(and(x_k, y_k), and(xor(x_k, y_k), c_k)). The carry chain is the algebraic mechanism behind the incompatibility metric d_Δ.
pub trait CarryChain<P: Primitives> {
    /// The number of sites in this carry chain.
    fn chain_length(&self) -> P::NonNegativeInteger;
    /// Bit mask of site positions where carry is generated: and(x_k, y_k) = 1.
    fn generate_mask(&self) -> P::NonNegativeInteger;
    /// Bit mask of site positions where carry propagates: xor(x_k, y_k) = 1.
    fn propagate_mask(&self) -> P::NonNegativeInteger;
    /// Bit mask of site positions where carry is killed: neither generated nor propagated.
    fn kill_mask(&self) -> P::NonNegativeInteger;
}

/// A single carry event at site k. Three kinds: Generate (and(x_k, y_k) = 1), Propagate (xor(x_k, y_k) = 1 and c_k = 1), Kill (neither generate nor propagate).
pub trait CarryEvent<P: Primitives> {
    /// The kind of carry event: Generate, Propagate, or Kill.
    fn event_kind(&self) -> P::NonNegativeInteger;
    /// The site index k at which this carry event occurs.
    fn site_position(&self) -> P::NonNegativeInteger;
}

/// The complete carry pattern for an addition x + y. Aggregates carry events across all sites into counts and position masks.
pub trait CarryProfile<P: Primitives> {
    /// The total number of carry events in this profile.
    fn carry_count(&self) -> P::NonNegativeInteger;
    /// The longest consecutive propagation run in this profile.
    fn max_propagation_length(&self) -> P::NonNegativeInteger;
    /// Associated type for `CarryChain`.
    type CarryChain: CarryChain<P>;
    /// The carry chain that this profile summarizes.
    fn profile_chain(&self) -> &Self::CarryChain;
}

/// A mapping from a finite symbol set S to Z/(2^k)Z where 2^k ≥ |S|. Determines how domain values are represented as ring elements.
pub trait EncodingConfiguration<P: Primitives> {
    /// The cardinality of the symbol set S being encoded.
    fn symbol_set_size(&self) -> P::PositiveInteger;
    /// The number of bits k used for encoding (2^k ≥ |S|).
    fn quantization_bits(&self) -> P::PositiveInteger;
    /// Associated type for `TermExpression`.
    type TermExpression: crate::kernel::schema::TermExpression<P>;
    /// String representation of the mapping from symbols to ring elements.
    fn encoding_map(&self) -> &Self::TermExpression;
}

/// The d_Δ quality metric for an encoding over observed data. Measures how well an encoding minimizes carry-induced metric incompatibility.
pub trait EncodingQuality<P: Primitives> {
    /// The mean d_Δ over observed pairs for this encoding.
    fn mean_delta(&self) -> P::Decimal;
    /// The ratio of distinguishable pairs to total pairs under this encoding.
    fn discrimination_ratio(&self) -> P::Decimal;
    /// Whether this encoding minimizes Σ d_Δ over observed pairs.
    fn is_optimal_encoding(&self) -> P::Boolean;
}