oximo-solver

Solver trait, result types, status codes, and shared option building blocks for oximo.

This crate defines the contract that backend crates implement. End users interact with concrete backends (Highs, Gurobi, Gams) exposed by the umbrella oximo crate, they do not depend on this crate directly unless they are writing a new backend.

Usage

[dependencies]
oximo-solver = "0.3"
oximo-core   = "0.3"

`Solver` trait

pub trait Solver {
    type Options;

    fn name(&self) -> &str;
    fn supports(&self, kind: ModelKind) -> bool;
    fn solve(&mut self, model: &Model, opts: &Self::Options) -> Result<SolverResult, SolverError>;
}

Each backend defines its own Options type. Users get compile-time validation and LSP autocomplete on the options that actually apply to that backend.

`SolverResult`

Populated by the backend on Optimal or Feasible. Sparse maps (FxHashMap) mean backends that don't return duals or reduced costs simply leave those fields empty.

Field	Type	Description
`status`	`SolverStatus`	Outcome of the solve
`solutions`	`Vec<SolutionPoint>`	Primal points, best first (empty if no solution)
`dual`	`FxHashMap<ConstraintId, f64>`	Constraint duals at the best point
`reduced_costs`	`FxHashMap<VarId, f64>`	Variable reduced costs at the best point
`solve_time`	`Duration`	Wall time around the solve call
`iterations`	`u64`	Simplex iteration count (if reported)
`raw_log`	`Option<String>`	Solver stdout/stderr

Each SolutionPoint holds the primal variable values (FxHashMap<VarId, f64>) and that point's objective (Option<f64>). Index 0 is the best/incumbent. Backends with solution pools return the extra points after it.

Accessors

result.objective()           // Option<f64>, best solution's objective
result.value_of(expr)        // Option<f64>, primal value for a Var expr (best solution)
result.value(var_id)         // Option<f64>, primal value by VarId (best solution)
result.dual_of(c_id)         // Option<f64>, dual for a constraint
result.best()                // Option<&SolutionPoint>, same as .solution(0)
result.solution(i)           // Option<&SolutionPoint>, i-th pooled point
result.result_count()        // usize, number of returned points
result.status.has_solution() // true if Optimal or Feasible
result.report(&model)        // Display: model-aware summary (status, vars, duals)

// Indexed variables
result.value_of_idx(&flow, "nyc")                  // Option<f64>, value at a specific index
result.values_of(&flow)                            // Iterator<(&IndexKey, f64)>, all entries with a primal value
result.values_of(&flow).filter(|(_, v)| *v != 0.0) // nonzero only (sparse solutions)

`SolverStatus`

Variant	Meaning
`Optimal`	Proven optimal
`Feasible`	Feasible but not proven optimal (e.g. time limit with incumbent)
`Infeasible`	No feasible solution exists
`Unbounded`	Objective is unbounded
`TimeLimit`	Time limit reached with no feasible solution
`NumericError`	Solver reported numerical difficulties
`NotSolved`	Default, solve not yet called
`Other(String)`	Backend-specific status not covered above

`SolverError`

Variant	Cause
`UnsupportedKind(ModelKind)`	Backend does not support this model kind
`NoObjective`	Model has no objective set
`Nonlinear`	Backend cannot handle nonlinear expressions
`Backend(String)`	Backend-reported error (e.g. license failure, bad option)
`Core(Error)`	Error from `oximo-core`

Universal options

All backend options structs embed UniversalOptions and implement HasUniversal, which enables the UniversalOptionsExt blanket impl:

use oximo_solver::UniversalOptionsExt;
use std::time::Duration;

let opts = MyBackendOptions::default()
    .time_limit(Duration::from_secs(120))
    .threads(4)
    .verbose(true);

Method	Field	Type
`.time_limit(Duration)`	`time_limit`	`Option<Duration>`
`.threads(u32)`	`threads`	`Option<u32>`
`.verbose(bool)`	`verbose`	`Option<bool>`

Implementing `HasUniversal` for a new backend

use oximo_solver::{HasUniversal, UniversalOptions};

#[derive(Default)]
pub struct MyOptions {
    universal: UniversalOptions,
    // backend-specific fields ...
}

impl HasUniversal for MyOptions {
    fn universal(&self) -> &UniversalOptions { &self.universal }
    fn universal_mut(&mut self) -> &mut UniversalOptions { &mut self.universal }
}

Writing a new backend

Mirror the layout of an existing backend crate (oximo-highs, oximo-gurobi, oximo-gams):

lib.rs: public struct + impl Solver. supports() declares which ModelKinds are handled. solve() delegates to translate::solve.
options.rs: converts MyOptions into the backend's native option calls.
translate.rs: Model -> backend conversion and result extraction.

Add an optional dep + feature in oximo/Cargo.toml and re-export the type under oximo::solvers.

License

MIT OR Apache-2.0

oximo-solver 0.3.0

oximo-solver

Usage

Solver trait

SolverResult