rust-api-guide.md

Rust API Guide

This guide shows the main Rust usage patterns.

Basic Combination View

use ucce_core::prelude::*;

let universe = UniverseBuilder::new()
    .with_ids((0..100).collect())
    .build();

let view = universe.view_combinations(5);

let mut out = [0u32; 5];
view.get_into(&Idx::from(42u64), &mut out).unwrap();

Materializing IDs

Coordinates are positions into the filtered universe. To get IDs:

let coord = Coordinate::from_slice(&out);
let ids = universe.materialize_ids(&coord).unwrap();

Row Filters

use ucce_core::prelude::*;
use ucce_core::universe::CompareOp;

let universe = UniverseBuilder::new()
    .with_ids((0..100).collect())
    .with_i64_column("active", vec![1; 100])
    .with_i64_column("risk", vec![20; 100])
    .with_compare_filter("active", CompareOp::Eq, 1)
    .with_compare_filter("risk", CompareOp::Lte, 50)
    .build();

Constrained Combinations

use ucce_core::mdd::LinearSumConstraint;
use ucce_core::prelude::*;

let universe = UniverseBuilder::new()
    .with_ids((0..10).collect())
    .with_i64_column("score", vec![10; 10])
    .build();

let parent = universe.view_combinations(3);
let constrained = parent
    .constrained_linear(
        LinearSumConstraint::new()
            .term("score", 1)
            .exact(30),
    )
    .unwrap();

let mut out = [0u32; 3];
constrained.get_into(&Idx::zero(), &mut out).unwrap();

A compiled view can also be attached from a validated mapped image, which keeps the graph in its buffer instead of decoding it into a FlatMdd:

use ucce_core::universe::ConstrainedCombinationView;

let constraint = LinearSumConstraint::new().term("score", 1).exact(30);
let owned = universe
    .view_combinations(3)
    .constrained_linear(constraint.clone())
    .unwrap();
let bytes = owned.mdd().unwrap().to_mapped_bytes().unwrap();

let mapped = ConstrainedCombinationView::from_mapped_bytes(
    universe.clone(),
    3,
    bytes,
    &constraint,
)
.unwrap();

let mut out = [0u32; 3];
mapped.get_into(&Idx::zero(), &mut out).unwrap();

mdd() returns Option<&FlatMdd>: a mapped view has no owned diagram. Use diagram() for whichever representation is in use and to_flat() to materialize an owned one. With the mmap feature, from_mapped_file maps a file read-only and lets the operating system page it in as queries touch it.

Streaming

let mut count = 0usize;

view.stream_into(&Idx::zero(), &Idx::from(100u64), |_coord| {
    count += 1;
}).unwrap();

Parent Index of a Constrained Result

let filtered_index = Idx::from(10u64);
let parent_index = constrained.parent_index_of(&filtered_index).unwrap();

Use this when you need to map a valid constrained subset back to the original unconstrained combination space.

Monotone Cover Combinations

use ucce_core::cover::{MonotoneCoverConstraint, RequirementMask};
use ucce_core::prelude::*;

let universe = UniverseBuilder::new()
    .with_ids((0..4).collect())
    .build();

let all = RequirementMask::all(3);
let item_masks = vec![
    RequirementMask::from(0b001),
    RequirementMask::from(0b010),
    RequirementMask::from(0b101),
    RequirementMask::from(0b100),
];

let view = universe
    .view_combinations(2)
    .constrained_monotone_cover(
        MonotoneCoverConstraint::from_item_masks(all, item_masks),
    )
    .unwrap();

The selected item masks must OR to all.

State-Contingent Verified Stream

use ucce_core::state_feasibility::{
    FeasibilityBuildConfig, StateContingentFeasibilityBuilder, StatePayoffMatrix,
};

let matrix = StatePayoffMatrix::from_state_rows(&[
    vec![200, 50, 80],
    vec![50, 200, 80],
]).unwrap();

let mut stream = StateContingentFeasibilityBuilder::new()
    .arity(2)
    .target(100)
    .payoff_matrix(matrix)
    .build_config(FeasibilityBuildConfig::verified_stream())
    .build_verified_stream()
    .unwrap();

stream.stream_verified(|combo| {
    let _positions = &combo.positions;
}).unwrap();

Use this when you need safe budgeted outputs, not exact len/get.

Exact Pair Feasibility From Compiled Masks

use ucce_core::cover::CompatibilityPolicy;
use ucce_core::state_feasibility::{
    CompiledStateContingentPairFeasibilityView, FeasibilityError, PairWeightCert,
};

let miss_words_by_item = vec![
    vec![0b01],
    vec![0b10],
    vec![0b00],
];

let view = CompiledStateContingentPairFeasibilityView::build_from_miss_words(
    3,
    2,
    miss_words_by_item,
    1_000_000,
    &CompatibilityPolicy::None,
    |left, right| {
        let _ = (left, right);
        Ok::<_, FeasibilityError>(Some(PairWeightCert {
            weight_left_ppm: 500_000,
            min_payoff: 120,
            worst_state: 0,
        }))
    },
).unwrap();

Use this k=2 path when the caller already has exact missing masks and a specialized pair oracle.