Struct Set 

pub struct Set<K = IndexKey> { /* private fields */ }

A finite, ordered index set, parameterized by the type K its keys decode to.

K is a phantom marker: the runtime representation is the same erased payload regardless of K, so carrying the key type costs nothing at runtime. It exists so the variable!/constraint!/sum! macros can infer the closure parameter type from the set instead of requiring an annotation.

Supports integer ranges (K = usize), string lists (K = String), and arbitrary tuple lists (built via Set::product / the &a * &b operator.

axes is Some exactly when the set is a dense integer grid and records the per-axis extents. It is None for string sets, sparse/from_ints sets, and any filtered set.

Implementations

impl<K> Set<K>

pub fn tuples<I, T>(iter: I) -> Set<K>

where I: IntoIterator<Item = T>, T: Into<Box<[IndexKey]>>,

Build a tuple set directly from an iterator of keys.

pub fn filter<F>(&self, f: F) -> Set<K>

where F: FnMut(&IndexKey) -> bool,

Filter keys with a predicate. Preserves the original variant where possible.

pub fn into_filter<F>(self, f: F) -> Set<K>

where F: FnMut(&IndexKey) -> bool,

Filter keys with a predicate, consuming the set.

pub fn filter_typed<F>(&self, pred: F) -> Set<K>

where K: FromIndexKey, F: FnMut(K) -> bool,

Filter keys with a predicate over the typed, by-value decoded key.

Unlike Self::filter (which hands the closure a raw IndexKey), the key is decoded to K first, so a product set yields native tuples and no manual as_tuple().unwrap() unpacking is needed. The receiver’s K pins the closure parameter, so it usually needs no annotation.

use oximo_core::Set;
let plants = Set::strings(["seattle", "san-diego"]);
// No-self-loop arcs; keys decoded to `(String, String)`.
let arcs = (&plants * &plants).filter_typed(|(p, q)| p != q);
assert_eq!(arcs.len(), 2);

pub fn filter_ref<F>(&self, f: F) -> Set<K>

where F: FnMut(IndexKeyRef<'_>) -> bool,

Borrowed-key filter that passes IndexKeyRef to the predicate. Use when the set is borrowed and the filtered fraction is small or tuple arity is large.

pub fn into_filter_ref<F>(self, f: F) -> Set<K>

where F: FnMut(IndexKeyRef<'_>) -> bool,

Consuming variant of Self::filter_ref.

pub fn into_filter_typed<F>(self, pred: F) -> Set<K>

where K: FromIndexKey, F: FnMut(K) -> bool,

Consuming typed filter that moves the set (see Self::into_filter).

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn is_range(&self) -> bool

Whether the backing representation is the integer-range variant.

pub fn is_strings(&self) -> bool

Whether the backing representation is the string-list variant.

pub fn is_tuples(&self) -> bool

Whether the backing representation is the tuple-list variant.

pub fn product<B>(a: &Set<K>, b: &Set<B>) -> Set<<K as KeyCat<B>>::Out>

where K: KeyCat<B>,

Cartesian product of two sets. Inner tuple keys are flattened so a product (a * b) * c yields 3-element tuples, not nested 2-tuples.

Panics

Panics if a.len() * b.len() overflows usize.

impl Set<usize>

pub fn range<T>(r: Range<T>) -> Set<usize>

where T: PrimInt,

Build an integer index set from a range over any primitive integer type. Accepts Range<i64>, Range<i32>, Range<usize>, etc.

The keys decode to usize. Negative elements are accepted into the payload but panic when decoded to usize.

Panics

Panics if either range bound does not fit in i64.

Examples found in repository

examples/resource_investment_scheduling.rs (line 177)

    fn new(grid_size: usize) -> Self {
        Self {
            tests: Set::range(0..N_TESTS),
            resources: Set::range(0..N_RESOURCES),
            products: Set::range(0..N_PRODUCTS),
            grid_points: Set::range(0..grid_size),
            income_segments: Set::range(0..INCOME_BREAKPOINTS.len()),
            new_units: Set::range(0..NEW_RESOURCES.len()),
        }
    }

examples/lot_sizing.rs (line 68)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    const T: usize = 12;

    let demand: [f64; T] =
        [120.0, 90.0, 80.0, 140.0, 160.0, 200.0, 220.0, 190.0, 150.0, 130.0, 100.0, 170.0];
    let prod_cost: [f64; T] = [5.0, 5.0, 5.0, 5.5, 6.0, 6.5, 6.5, 6.0, 5.5, 5.0, 5.0, 5.5];
    let setup_cost = 500.0;
    let hold_cost = 2.0;
    let capacity = 300.0;
    let initial_inventory = 50.0;
    let safety_stock = 30.0;

    let m = Model::new("lot_sizing");
    let periods = Set::range(0..T);

    variable!(m, 0.0 <= x[t in periods] <= capacity);
    variable!(m, h[t in periods] >= 0.0);
    variable!(m, s[t in periods], Bin);

    constraint!(m, inv_bal0, h[0] - x[0] == initial_inventory - demand[0]);
    constraint!(m, inv_bal[t in 1..T], h[t] - h[t - 1] - x[t] == -demand[t]);
    constraint!(m, setup[t in periods], x[t] <= capacity * s[t]);
    constraint!(m, safety_stock, h[T - 1] >= safety_stock);

    objective!(
        m,
        Min,
        sum!(prod_cost[t] * x[t] + setup_cost * s[t] + hold_cost * h[t] for t in periods)
    );

    #[cfg(feature = "gurobi")]
    let result = {
        let opts = GurobiOptions::default()
            .time_limit(std::time::Duration::from_secs(60))
            .mip_gap(1e-4)
            .verbose(true);
        Gurobi.solve(&m, &opts)?
    };

    #[cfg(all(feature = "highs", not(feature = "gurobi")))]
    let result = {
        let opts = HighsOptions::default()
            .time_limit(std::time::Duration::from_secs(60))
            .mip_gap(1e-4)
            .verbose(true);
        Highs.solve(&m, &opts)?
    };

    println!("\nLot-Sizing Result");
    println!("Status    : {:?}", result.termination);
    if let Some(obj) = result.objective() {
        println!("Total cost: {obj:.2}");
    }

    println!(
        "\n{:<8} {:>10} {:>10} {:>8} {:>12}",
        "Period", "Produce", "Inventory", "Active", "Period cost"
    );
    println!("{}", "-".repeat(55));

    let mut total_check = 0.0;
    for t in 0..T {
        let xt = result.value_of(x[t])?.unwrap_or(0.0);
        let ht = result.value_of(h[t])?.unwrap_or(0.0);
        let st = result.value_of(s[t])?.unwrap_or(0.0);
        let period_cost = prod_cost[t] * xt + setup_cost * st + hold_cost * ht;
        total_check += period_cost;
        println!(
            "{:<8} {:>10.1} {:>10.1} {:>8} {:>12.2}",
            t + 1,
            xt,
            ht,
            if (st - 1.0).abs() < 1e-6 { "Yes" } else { "No" },
            period_cost
        );
    }
    println!("{}", "-".repeat(55));
    println!("{:<8} {:>10} {:>10} {:>8} {:>12.2}", "TOTAL", "", "", "", total_check);

    Ok(())
}

examples/gradostat_multiperiod_socp.rs (line 91)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use oximo::ClarabelOptions;
    use oximo::prelude::*;
    use oximo::solvers::Clarabel;

    // Problem data
    const N: usize = 4; // tanks
    const TAU: usize = 1000; // time periods

    // Forced-flow + diffusion matrix M + L.
    const ML: [[f64; N]; N] = [
        [-2.3, 0.3, 0.0, 0.0],
        [1.3, -3.9, 0.3, 1.3],
        [0.0, 2.3, -3.6, 0.3],
        [0.0, 0.3, 1.3, -2.6],
    ];

    // C = diag(Qin), the external water inflow at each tank.
    const QIN: [f64; N] = [2.0, 1.0, 1.0, 1.0];

    // Total biomass mass allowed in the tanks per period: 1' Qin X(t) <= BUDGET.
    const BUDGET: f64 = 3.0;

    // Substrate inflow profiles Sin_i(t), indexed sin[i][p] with paper time t=p+1.
    #[expect(clippy::needless_range_loop, clippy::cast_precision_loss)]
    let sin: Vec<Vec<f64>> = {
        let pi = std::f64::consts::PI;
        let tau = TAU as f64;
        let mut sin = vec![vec![0.0f64; TAU]; N];
        for p in 0..TAU {
            let t = (p + 1) as f64;
            let ti = p + 1;
            sin[0][p] = 1.0 + (4.0 * pi * t / tau).sin();
            sin[1][p] = 0.0;
            sin[2][p] = if ti > TAU / 4 && ti <= 3 * TAU / 4 { 0.5 } else { 0.0 };
            sin[3][p] = 1.0 + (4.0 * pi * t / tau).cos();
        }
        sin
    };

    let m = Model::new("gradostat_multiperiod");
    let tanks = Set::range(0..N);
    let periods = Set::range(0..TAU);

    variable!(m, s[i in tanks, p in periods] >= 0.0); // substrate  S
    variable!(m, x[i in tanks, p in periods] >= 0.0); // biomass    X
    variable!(m, kin[i in tanks, p in periods] >= 0.0); // kinetics T
    variable!(m, xin[i in tanks, p in periods] >= 0.0); // biomass inflow Xin (decision)

    // Dynamic substrate and biomass balances (25a, 25b), Euler-explicit, V=y=1.
    constraint!(m, s_bal[i in tanks, p in periods],
        s[i, (p + 1) % TAU] - s[i, p]
            == -kin[i, p] + sum!(ML[i][j] * s[j, p] for j in tanks) + QIN[i] * sin[i][p]);
    constraint!(m, x_bal[i in tanks, p in periods],
        x[i, (p + 1) % TAU] - x[i, p]
            == kin[i, p] + sum!(ML[i][j] * x[j, p] for j in tanks) + QIN[i] * xin[i, p]);

    // Contois growth as a second-order cone (eq. 9, mu_max = K = 1).
    soc_constraint!(m, growth[i in tanks, p in periods],
        [s[i, p], kin[i, p], x[i, p]] <= x[i, p] + s[i, p] - kin[i, p]);
    constraint!(m, st_diff[i in tanks, p in periods], s[i, p] - kin[i, p] >= 0.0);

    // Per-period biomass-inflow budget, 1' Qin Xin(t) <= BUDGET.
    constraint!(m, bio_budget[p in periods], sum!(QIN[i] * xin[i, p] for i in tanks) <= BUDGET);

    // Maximize cumulative biogas, sum_{i,t} V_ii T_i with V = I (eq. 24, undiscounted).
    objective!(m, Max, sum!(kin[i, p] for i in tanks, p in periods));

    assert_eq!(m.kind(), ModelKind::SOCP);

    let res = Clarabel.solve(&m, &ClarabelOptions::default())?;
    assert_eq!(res.termination, TerminationStatus::Optimal);

    // Exactness metric E = max_{i,t} |r(S,X)-T|/r(S,X), with the Contois
    // kinetics r(S,X) = mu_max S X/(K X + S) evaluated at the solution.
    let mut e_max = 0.0f64;
    for i in 0..N {
        for p in 0..TAU {
            let sv = res.value_of(s[(i, p)])?.unwrap();
            let xv = res.value_of(x[(i, p)])?.unwrap();
            let tv = res.value_of(kin[(i, p)])?.unwrap();
            let denom = sv + xv;
            if denom > 1e-9 {
                let r = sv * xv / denom;
                if r > 1e-9 {
                    e_max = e_max.max((r - tv).abs() / r);
                }
            }
        }
    }

    println!("Results:");
    println!("Termination: {:?}", res.termination);
    println!("Objective: {:.4}", res.objective().unwrap());
    println!("Exactness E: {e_max:.3e}");
    println!("Iterations: {}", res.iterations);
    println!("Solve time: {:.3} s", res.solve_time.as_secs_f64());

    Ok(())
}

pub fn from_ints<T, I>(iter: I) -> Set<usize>

where T: PrimInt, I: IntoIterator<Item = T>,

Build an integer index set from an iterator of any primitive integer type. Useful when keys are sparse or computed.

Panics

Panics if any element does not fit in i64.

impl Set<String>

pub fn strings<I, S>(iter: I) -> Set<String>

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

Examples found in repository

examples/reaction_path.rs (line 90)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 34 chemicals: index = yXX - 1 (y01 -> 0, ..., y34 -> 33).
    const CHEMICALS: [&str; 34] = [
        "y01", "y02", "y03", "y04", "y05", "y06", "y07", "y08", "y09", "y10", "y11", "y12", "y13",
        "y14", "y15", "y16", "y17", "y18", "y19", "y20", "y21", "y22", "y23", "y24", "y25", "y26",
        "y27", "y28", "y29", "y30", "y31", "y32", "y33", "y34",
    ];

    // (reaction label, product index, reactant indices) - all 0-based.
    // Transcribed from logicc set in GAMS REACTION model (SEQ=121).
    let logicc: &[(&str, usize, &[usize])] = &[
        ("rxn01", 3, &[0, 1, 2]),      // y04 <- y01 + y02 + y03
        ("rxn02", 5, &[3, 4]),         // y06 <- y04 + y05
        ("rxn03", 6, &[3, 4]),         // y07 <- y04 + y05
        ("rxn04", 2, &[3, 4]),         // y03 <- y04 + y05
        ("rxn05", 10, &[7, 8, 9]),     // y11 <- y08 + y09 + y10
        ("rxn06", 5, &[10, 11, 12]),   // y06 <- y11 + y12 + y13
        ("rxn07", 14, &[13, 8, 9, 4]), // y15 <- y14 + y09 + y10 + y05
        ("rxn08", 5, &[14, 15, 16]),   // y06 <- y15 + y16 + y17
        ("rxn09", 5, &[17, 18, 11]),   // y06 <- y18 + y19 + y12
        ("rxn10", 19, &[17, 18, 11]),  // y20 <- y18 + y19 + y12
        ("rxn11", 8, &[20, 21]),       // y09 <- y21 + y22
        ("rxn12", 23, &[8, 22]),       // y24 <- y09 + y23
        ("rxn13", 17, &[23, 16]),      // y18 <- y24 + y17
        ("rxn14", 20, &[24, 25]),      // y21 <- y25 + y26
        ("rxn15", 26, &[24, 25]),      // y27 <- y25 + y26
        ("rxn16", 13, &[2, 27, 28]),   // y14 <- y03 + y28 + y29
        ("rxn17", 31, &[29, 30, 11]),  // y32 <- y30 + y31 + y12
        ("rxn18", 7, &[29, 30, 11]),   // y08 <- y30 + y31 + y12
        ("rxn19", 29, &[24, 32]),      // y30 <- y25 + y33
        ("rxn20", 12, &[24, 32]),      // y13 <- y25 + y33
        ("rxn21", 0, &[33, 2]),        // y01 <- y34 + y03
        ("rxn22", 33, &[13, 27]),      // y34 <- y14 + y28
    ];

    // y02, y03, y05, y10, y12, y13, y17, y22, y25, y26, y28, y31, y33: fixed to 1.
    let available: &[usize] = &[1, 2, 4, 9, 11, 12, 16, 21, 24, 25, 27, 30, 32];
    // y16, y19: fixed to 0.
    let unavailable: &[usize] = &[15, 18];

    let m = Model::new("reaction_path");
    let chemicals = Set::strings(CHEMICALS);

    variable!(m, y[v in chemicals], Bin);
    // Fix availability: raw materials/catalysts to 1, unavailable chemicals to 0.
    for &i in available {
        m.fix(y[CHEMICALS[i]], 1.0)?;
    }
    for &i in unavailable {
        m.fix(y[CHEMICALS[i]], 0.0)?;
    }

    // sum_vv (1 - y[vv]) >= 1 - y[v]
    //    <=>  y[v] - sum_vv y[vv] >= 1 - |reactants|
    for &(_rx, prod, reactants) in logicc {
        let n = reactants.len() as f64;
        constraint!(m, y[CHEMICALS[prod]] - sum!(y[CHEMICALS[vv]] for vv in reactants) >= 1.0 - n);
    }

    objective!(m, Min, y["y06"]); // acetone

    #[cfg(feature = "gams")]
    let result = {
        let opts = GamsOptions::default()
            .time_limit(std::time::Duration::from_secs(60))
            .solver(GamsSolverConfig::Cplex(GamsCplexOptions::default()))
            .verbose(true);
        let mut solver = Gams::new();
        solver.solve(&m, &opts)?
    };

    #[cfg(all(feature = "highs", not(feature = "gams")))]
    let result = Highs.solve(&m, &HighsOptions::default().verbose(true))?;

    println!("Status : {:?}", result.termination);
    if let Some(obj) = result.objective() {
        println!(
            "Acetone (y06, ch3coch3): {}",
            if (obj - 1.0).abs() < 1e-6 { "Synthesizable" } else { "Not synthesizable" }
        );
    }

    let synthesizable: Vec<&str> = CHEMICALS
        .iter()
        .copied()
        .filter(|name| (result.value_of(y[*name]).unwrap().unwrap_or(0.0) - 1.0).abs() < 1e-6)
        .collect();
    if !synthesizable.is_empty() {
        println!("Synthesizable chemicals: {}", synthesizable.join(", "));
    }

    Ok(())
}

impl<K> Set<K>

pub fn iter(&self) -> SetIter<'_>

pub fn par_iter(&self) -> impl ParallelIterator<Item = IndexKey>

Trait Implementations

impl<K> Clone for Set<K>

fn clone(&self) -> Set<K>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K> Debug for Set<K>

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

Formats the value using the given formatter.

impl<'a, K> IntoIterator for &'a Set<K>

type Item = IndexKey

The type of the elements being iterated over.

type IntoIter = SetIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a Set<K> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<A, B> Mul<&Set<B>> for &Set<A>

where A: KeyCat<B>,

type Output = Set<<A as KeyCat<B>>::Out>

The resulting type after applying the * operator.

fn mul(self, rhs: &Set<B>) -> <&Set<A> as Mul<&Set<B>>>::Output

Performs the * operation.

impl<K> SumDomain<K> for Set<K>

where K: FromIndexKey,

fn keys(&self) -> impl Iterator<Item = K>