Struct SparseClause 

pub struct SparseClause { /* private fields */ }

Sparse clause representation storing only active literal indices.

Achieves 5-100x memory reduction compared to dense Clause by storing only indices of features that affect evaluation.

Memory Layout

Typical clause with 20 active literals:

• include_indices: 32 × 2 = 64 bytes (inline SmallVec)
• negated_indices: 32 × 2 = 64 bytes (inline SmallVec)
• weight: 4 bytes
• polarity: 1 byte
• Total: ~133 bytes vs ~8000 bytes for dense (1000 features)

Performance

Uses early-exit evaluation: returns false on first violation. For sparse input data, this is often faster than dense bitmask evaluation.

Example

use tsetlin_rs::{Clause, SparseClause};

let mut clause = Clause::new(100, 100, 1);
// ... train clause ...

let sparse = SparseClause::from_clause(&clause);
assert!(sparse.memory_usage() < 200); // vs 800+ bytes dense

Implementations

impl SparseClause

pub fn from_clause(clause: &Clause) -> Self

Creates a sparse clause from a dense Clause by extracting active literals.

Scans automata and records indices where action() == true.

Arguments

• clause - Dense clause to convert

Example

use tsetlin_rs::{Clause, SparseClause};

let clause = Clause::new(100, 100, 1);
let sparse = SparseClause::from_clause(&clause);
assert_eq!(sparse.n_literals(), 0); // Fresh clause has no active literals

pub fn new(include: &[u16], negated: &[u16], weight: f32, polarity: i8) -> Self

Creates a sparse clause from raw components.

Arguments

• include - Feature indices requiring x[k] = 1
• negated - Feature indices requiring x[k] = 0
• weight - Clause weight
• polarity - Vote direction (+1 or -1)

pub const fn polarity(&self) -> i8

Returns clause polarity (+1 or -1).

pub const fn weight(&self) -> f32

Returns clause weight.

pub fn include_indices(&self) -> &[u16]

Returns indices of include literals.

pub fn negated_indices(&self) -> &[u16]

Returns indices of negated literals.

pub fn evaluate(&self, x: &[u8]) -> bool

Evaluates clause with early exit on first violation.

Returns true if all conditions are satisfied:

• For each index in include_indices: x[idx] == 1
• For each index in negated_indices: x[idx] == 0

Arguments

• x - Binary input vector

Safety

Uses unchecked indexing for performance. Caller must ensure all stored indices are within x.len().

pub fn evaluate_checked(&self, x: &[u8]) -> bool

Evaluates clause with bounds checking.

Safe version of evaluate that performs bounds checks.

pub fn evaluate_packed(&self, x: &[u64]) -> bool

Evaluates using packed u64 input (64 features per word).

Optimized for cases where input is already packed. Uses bit extraction instead of array indexing.

Arguments

• x - Binary input packed as u64 words

pub fn vote(&self, x: &[u8]) -> f32

Returns weighted vote: polarity × weight if clause fires, 0.0 otherwise.

pub fn vote_unweighted(&self, x: &[u8]) -> i32

Returns unweighted vote: polarity if clause fires, 0 otherwise.

pub fn memory_usage(&self) -> usize

Returns approximate memory usage in bytes.

Accounts for SmallVec inline vs heap allocation.

pub fn n_literals(&self) -> usize

Returns total number of active literals.

Trait Implementations

impl Clone for SparseClause

fn clone(&self) -> SparseClause

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SparseClause

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

Formats the value using the given formatter.