Crate oximo

Expand description

§oximo

oximo is a Rust algebraic modeling library for mathematical optimization. It provides a compact modeling API for variables, indexed domains, algebraic constraints, objectives, nonlinear expressions, and multiple solver backends.

use oximo::prelude::*;
use oximo::solvers::Highs;

let demand = [4.0, 6.0, 5.0];

let m = Model::new("production");
variable!(m, production[p in 0..2, t in 0..3] >= 0.0);
constraint!(m, meet[t in 0..3],
    sum!(production[p, t] for p in 0..2) >= demand[t]);
objective!(m, Min, sum!(production[p, t] for p in 0..2, t in 0..3));

let mut solver = Highs;
let result = solver.solve(&m, &HighsOptions::default())?;
println!("objective = {:?}", result.objective());

Expressions use standard Rust operators. Variable domains and bounds are declared directly in the model:

variable!(m, x >= 0.0);       // continuous
variable!(m, y, Bin);         // binary
variable!(m, z >= 0.0, Int);  // integer

constraint!(m, capacity, 2.0 * x + y <= 10.0);
objective!(m, Max, 3.0 * x + 4.0 * y);

Quadratic, nonlinear, and second-order-cone expressions are also available:

objective!(m, Min, (1.0 - x).powi(2) + 100.0 * (y - x.powi(2)).powi(2));
constraint!(m, disk, x.powi(2) + y.powi(2) <= 1.0);
soc_constraint!(m, cone, [x, y] <= t);

§Problem types

oximo supports the following algebraic problem classes. Which classes can be solved depends on the selected backend:

Linear programming (LP)
Quadratic programming and quadratically constrained programming (QP/QCP)
Nonlinear programming (NLP)
Mixed-integer linear programming (MILP)
Mixed-integer quadratic and quadratically constrained programming (MIQP/MIQCP)
Mixed-integer nonlinear programming (MINLP)
Second-order cone programming (SOCP/MISOCP)

§Solver features

Feature	Backend / capability	Default
`highs`	HiGHS - LP/MILP/QP (bundled, requires a C/C++ compiler)	no
`io`	NL, MPS, and LP readers and writers	yes
`gurobi`	Gurobi v13+ (requires licensed install)	no
`mosek`	MOSEK 11.2 - convex LP/MIP/QP/QCP/SOCP	no
`gams`	GAMS bridge - capability depends on the selected sub-solver	no
`baron`	BARON - global non-convex solver (requires licensed install)	no
`clarabel`	Clarabel - LP/QP/SOCP (pure Rust, no install)	no
`clarabel-faer`	Clarabel with the faer sparse linear-algebra backend	no
`pounce`	POUNCE - pure-Rust LP/QP/QCP/NLP backend	no
`pounce-enzyme`	POUNCE with exact Enzyme derivatives (nightly)	no

For example, use HiGHS for a bundled LP/MILP/QP solver:

[dependencies]
oximo = { version = "0.7", features = ["highs"] }

Licensed or external backends may require an installed solver, environment variables, and a valid license. See the backend documentation and the webdocs for setup details.

§Results

SolverResult provides the termination status, objective value, variable values, duals, reduced costs, and (where supported) bounds, gaps, and solution pools.

§License

MIT OR Apache-2.0

§API map

The most commonly used modeling and solver types are re-exported at the crate root and by prelude:

Build models with Model, variable!, constraint!, and objective!.
Create indexed families with Set, IndexedVar, and IndexedParam.
Compose algebraic expressions with Expr, sum!, min!, and max!.
Select a backend from solvers and solve through the Solver trait.
Inspect termination, primal, and dual information in SolverResult.
Read or write optimization formats through the io module when that feature is enabled.

Lower-level modeling, expression, and solver APIs remain available through core, expr, and solver, respectively.

Re-exports§

pub use oximo_core as core;
pub use oximo_expr as expr;
pub use oximo_solver as solver;
pub use oximo_io as io;io

Modules§

gamsgams: GAMS backend types: sub-solver selection and per-solver option structs.
pouncepounce: POUNCE backend options, algorithm selection, and persistent solver types.
prelude: Glob-import target. Brings the modeling and solver surface into scope.
solvers: Concrete solver backends, gated by cargo features.

Macros§

constraint: constraint!(model, [name|name[idx]], lhs <op> rhs), register a constraint, an auto-named anonymous constraint, or an indexed family of constraints.
indicator_constraint: Register a native binary-triggered affine constraint. indicator_constraint!(model, [name|name[idx]], binary == 0|1 => relation).
max: max!(body for pat in domain[, pat in domain ...][ if cond]), an indexed maximum.
min: min!(body for pat in domain[, pat in domain ...][ if cond]), an indexed minimum.
objective: objective!(model, Min|Max, expr), set the model objective and sense. objective!(model, Feasibility) (also feasibility/feas) declares a feasibility problem with no objective to optimize.
param: param!(model, name = value), declare a re-bindable scalar parameter and bind it to a local of the same name.
set: set!(name = domain), bind a local to an index Set. A plain right side (0..5, a * b) is normalized to an owned set (a top-level * is a borrowing Cartesian product). A pat in domain[ if cond] comprehension builds (and optionally filters) the set. See the crate docs.
soc_constraint: soc_constraint!(model, [name|name = expr|name[idx]], [terms] <= bound), register the second-order cone constraint ||terms||_2 <= bound (every term and the bound must be affine), an auto-named anonymous cone, or an indexed family of cones.
sos_constraint: sos_constraint!(model, [name|name[idx]], SOS1|SOS2, [var, ...]). Explicit weights can be supplied as [(var, weight), ...]. The short form assigns consecutive weights starting at one.
sum: sum!(body for pat in domain[, pat in domain ...]), algebraic summation, lowered to nested sum_over folds. To allow an empty domain (or an empty filter), anchor the sum to its model: sum!(model, body for pat in domain). Sums written inside constraint!, soc_constraint!, objective!, or an anchored sum inherit its expression context automatically. Selected terms must belong to that model. Standalone unanchored sums require a first term.
variable: variable!(model, spec), declare a decision variable (or an indexed family) and bind it to a local of the same name. See the crate docs for the grammar.

Structs§

BaronOptionsbaron: BARON-specific solver options.
ClarabelOptionsclarabel: Clarabel-specific solver options.
Constraint: A single algebraic constraint, canonicalized as the interval lower <= lhs <= upper with numeric bounds. RHS expressions are folded into lhs during construction, so backends only ever see this canonical shape.
ConstraintEvaluation: Activity and feasibility information for an algebraic constraint.
ConstraintExpr: In-progress constraint produced by Relate::le / Relate::ge / Relate::eq. Registered through the constraint! macro.
ConstraintHandle: A model-bound handle to an algebraic constraint.
ConstraintId
Expr: Lightweight handle to a node in an ExprArenaCell.
ExprId
GamsOptionsgams: GAMS-specific solver options.
HighsOptionshighs: HiGHS-specific solver options.
Iis: An irreducible infeasible subsystem (IIS).
IisReport: A printable, model-aware listing of an Iis. Created by Iis::report.
IndexedConstraint: Owned handle returned by an indexed single-relation constraint! declaration.
IndexedIndicatorConstraint: Owned handles returned by an indexed single-relation indicator declaration.
IndexedRangeConstraint: Owned handle returned by an indexed two-sided range constraint! declaration.
IndexedRangeIndicatorConstraint: Owned handles returned by an indexed two-sided indicator declaration.
IndexedVarBuilder
IndicatorConstraint: A binary-triggered affine row, stored canonically as trigger == active_value => lower <= lhs <= upper.
IndicatorConstraintHandle: Model-bound handle returned by a scalar indicator declaration.
IndicatorConstraintId: Stable identifier for a native indicator constraint.
IndicatorReformulationArtifacts: IDs appended while replacing one source indicator.
IndicatorReformulationOptions: Settings for explicit indicator-to-MILP reformulation.
Model: The optimization model. Owns the expression arena, variable/parameter registries, constraints, and (optional) objective.
ModelConstraints: Unified borrowed view of every constraint declared on a Model.
ModelId: Stable identity shared by a model, its expression handles, and its results.
ModelMismatchError: An expression, indexed family, model, or result came from another model.
ModelReport: A printable, model-aware summary of a SolverResult. Created by SolverResult::report.
Objective: The model’s objective: an expression to optimize and the direction.
ParamId
Parameter: Parameter identity (id + name). Parameters are scalars referenced symbolically in expressions and re-bound between solves.
PounceOptionspounce: POUNCE-specific solver options.
ReformulatedModel: An independent transformed model plus source-to-generated provenance.
Set: A finite, ordered index set, parameterized by the type K its keys decode to.
SetIter
SocConstraint: An explicit second-order cone constraint ||terms||_2 <= bound.
SocConstraintHandle: A model-bound handle to an explicit second-order-cone constraint.
SocConstraintId
SocEvaluation: Activity and feasibility information for an explicit second-order cone.
SocForm: Normalized second-order cone data: || A x + a ||_2 <= b'x + beta, one LinearTerms per row of A x + a plus one for the bound side. Produced by shared solver preparation for algebraic and explicit cones.
SolutionPoint: A single primal point returned by a solver.
SolverResult: A solver’s final result on a model.
SosConstraint: An explicit SOS1 or SOS2 constraint.
SosConstraintHandle: A model-bound handle to an SOS constraint.
SosConstraintId
SosMember
SosReformulationArtifacts: IDs appended while replacing one source SOS constraint.
SosReformulationOptions: Settings for an SOS-to-MILP reformulation.
UniversalOptions: Options valid for every solver, including NLP backends. Each backend’s options struct embeds this via HasUniversal; the UniversalOptionsExt blanket impl then provides typed builder setters.
VarBuilder: Builder backing the variable! macro. Configure bounds / domain, then call Self::build to register the variable and obtain an Expr handle.
VarId
Variable: Variable metadata held by the Model. Users do not construct this directly, they get an Expr back from VarBuilder::build and look up solution values via crate::Model / oximo_solver::SolverResult.

Enums§

ClarabelDirectSolveclarabel: Direct linear (KKT) solver method for Clarabel.
ConstraintRef: A borrowed constraint from a Model.
Domain: The domain of a variable, which determines the type of values it can take.
DualStatus: Availability and quality of the dual solution returned by a solver.
Error: Errors that can occur during model construction. These are distinct from backend errors, which are opaque and translated into SolverError.
GamsSolvergams: Named GAMS sub-solver. Use GamsSolver::Custom for any name that isn’t a pre-enumerated variant.
HighsMethodhighs: HiGHS LP / root-relaxation algorithm.
HighsPresolvehighs: HiGHS presolve options.
IndexKey: A serializable index key from a Set.
ModelKind: The kind of mathematical program a Model represents.
MuStrategypounce: mu_strategy values.
ObjectiveSense: Whether the model minimizes or maximizes its objective.
PounceAlgorithmpounce: POUNCE algorithms available through its Rust library API.
PounceOptionValuepounce: A raw POUNCE option value for PounceOptions::extra.
PounceSolverSelectionpounce: POUNCE solver route selected after classifying the oximo model.
PrimalStatus: The status of the primal point held in a crate::SolverResult.
RangeConstraintHandles: Model-bound handles produced by a two-sided range declaration.
RangeConstraintIds: Model row IDs produced by a two-sided range declaration.
RangeIndicatorConstraintHandles: Model-bound handles produced by a two-sided indicator declaration.
RangeIndicatorConstraintIds: IDs produced by a two-sided indicator declaration.
ReformulationError: Why an explicit model reformulation could not be constructed.
Sense: The sense of a constraint: less-than-or-equal, greater-than-or-equal, or equality.
SolverError
SosType: The two standard special ordered set types.
TerminationStatus: Why a solver stopped, independent of whether a usable point was returned.
UnaryOp: Unary scalar functions represented by ExprNode::Unary.
VarBoundKind: Which side of a variable’s bound participates in an infeasibility.

Traits§

FromIndexKey: Typed projection of an IndexKey. Implementations panic when the key’s shape does not match the target type, the same contract as crate::indexed::IndexedVar indexing on a missing key.
HasUniversal: Implemented by every backend-specific options struct. Gives the UniversalOptionsExt blanket impl access to the embedded UniversalOptions.
InfeasibilityDiagnosis: A Solver that can diagnose why a model is infeasible by computing an irreducible infeasible subsystem (Iis).
IntoRhs: What can appear on the right-hand side of a constraint. Numeric scalars stay as the canonical rhs. Expressions get subtracted into the LHS.
PersistentSolver: A Solver that can hand out a stateful handle keeping the built backend model resident across solves.
Relate: Build a constraint from an expression. Lives on Expr itself.
Solver: Concrete solver backend.
SumDomain: Domain over which the sum! macro iterates. Lets a single sum accept either a Set (with typed key decoding via FromIndexKey) or a borrowed slice of Copy keys, without intermediate conversions.
UniversalOptionsExt: Builder setters available on every backend options struct.

Functions§

display_index_key: Public render of an IndexKey’s textual form, used when deriving auto-generated names for indexed-family constraints.
dot: Dot product of expressions with scalar coefficients: sum_{i} c_i * e_i.

Type Aliases§

Children
IndexTuple: Heap-allocated tuple key payload. Immutable after construction.
IndexedParam: Indexed family of re-bindable parameters; see IndexedFamily.
IndexedVar: Indexed family of decision variables; see IndexedFamily.

Crate oximo

Crate oximo Copy item path

§oximo

§Problem types

§Solver features

§Results

§License

§API map

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate oximo