Expand description
§Rust SDK for OMMX (Open Mathematics prograMming eXchange)
This crate provides native Rust types and operations for mathematical optimization problems. It offers type-safe, high-performance implementations with convenient macros for expression building.
§Linear
, Quadratic
, Polynomial
, and Function
These types represent mathematical expressions in optimization problems with different degree characteristics:
Linear
: Up to degree 1 polynomials (linear terms + constant)Quadratic
: Up to degree 2 polynomials (may contain only linear terms, no quadratic terms required)Function
: Dynamic degree handling, can represent any polynomial degree at runtime
Use the convenience macros linear!
, quadratic!
, coeff!
, and monomial!
for easy expression building.
use ommx::{Linear, Quadratic, Function, linear, quadratic, coeff};
// Linear expressions: 2*x1 + 3*x2 + 5 (fixed degree 1)
let linear_expr = coeff!(2.0) * linear!(1) + coeff!(3.0) * linear!(2) + coeff!(5.0);
// Quadratic expressions: x1*x2 + 2*x1 + 1 (up to degree 2)
let quad_expr = coeff!(1.0) * quadratic!(1, 2) + coeff!(2.0) * quadratic!(1) + coeff!(1.0);
assert_eq!(quad_expr.degree(), 2);
// Quadratic with only linear terms (no quadratic terms): 3*x1 + 2
let linear_only_quad = coeff!(3.0) * quadratic!(1) + coeff!(2.0);
assert_eq!(linear_only_quad.degree(), 1);
// Functions can dynamically handle any degree
let linear_func = Function::from(linear_expr); // Degree 1
assert_eq!(linear_func.degree(), 1);
let quad_func = Function::from(quad_expr); // Degree 2
assert_eq!(quad_func.degree(), 2);
See also PolynomialBase
which is a base for Linear
, Quadratic
, and Polynomial
.
§Bound
, Kind
, and DecisionVariable
Decision variables define the unknowns in optimization problems. Each variable has a Kind
(continuous, binary, integer, etc.) and Bound
(lower/upper limits).
use ommx::{DecisionVariable, Kind, Bound, VariableID, ATol};
// Binary decision variable with ID 1
let binary_var = DecisionVariable::binary(VariableID::from(1));
assert_eq!(binary_var.kind(), Kind::Binary);
assert_eq!(binary_var.bound(), Bound::new(0.0, 1.0)?); // Default binary bound is [0, 1]
// Integer variable with bound [0, 3]
let integer_var = DecisionVariable::integer(VariableID::from(2))
.with_bound(Bound::new(0.0, 3.0)?, ATol::default())?;
assert_eq!(integer_var.kind(), Kind::Integer);
assert_eq!(integer_var.bound(), Bound::new(0.0, 3.0)?);
// Continuous variable with ID 3
let continuous_var = DecisionVariable::continuous(VariableID::from(3));
assert_eq!(continuous_var.kind(), Kind::Continuous);
assert_eq!(continuous_var.bound(), Bound::unbounded()); // Default is unbounded (-inf, inf)
§Constraint
Constraints define the feasible region of optimization problems. Constraints can be equality or inequality types, and can be temporarily removed while preserving their definition.
use ommx::{Constraint, ConstraintID, Function, Linear, linear, coeff};
// Create constraints: x1 + x2 <= 10 (as x1 + x2 - 10 <= 0)
let constraint_expr = coeff!(1.0) * linear!(1) + coeff!(1.0) * linear!(2) + Linear::from(coeff!(-10.0));
let constraint = Constraint::less_than_or_equal_to_zero(
ConstraintID::from(1),
Function::from(constraint_expr)
);
// Equality constraint: x1 - x2 = 0 (as f(x) = 0)
let eq_expr = coeff!(1.0) * linear!(1) - coeff!(1.0) * linear!(2);
let eq_constraint = Constraint::equal_to_zero(
ConstraintID::from(2),
Function::from(eq_expr)
);
§Instance
The Instance
type represents a complete optimization problem with objective, variables,
and constraints. All variables used in the objective and constraints must be defined in the
decision variables map.
use ommx::{Instance, DecisionVariable, VariableID, Constraint, ConstraintID, Function, Sense, Linear, linear, coeff};
use maplit::btreemap;
// Create decision variables
let decision_variables = btreemap! {
VariableID::from(1) => DecisionVariable::binary(VariableID::from(1)),
VariableID::from(2) => DecisionVariable::continuous(VariableID::from(2)),
};
// Create objective function: minimize x1 + 2*x2
let objective = Function::from(linear!(1) + coeff!(2.0) * linear!(2));
// Create constraints
let constraints = btreemap! {
// x1 + x2 = 1
ConstraintID::from(1) => Constraint::equal_to_zero(
ConstraintID::from(1),
Function::from(linear!(1) + linear!(2) + Linear::from(coeff!(-1.0)))
),
// x2 <= 5
ConstraintID::from(2) => Constraint::less_than_or_equal_to_zero(
ConstraintID::from(2),
Function::from(linear!(2) + Linear::from(coeff!(-5.0)))
),
};
// Create the instance
let instance = Instance::new(
Sense::Minimize,
objective,
decision_variables,
constraints,
)?;
assert_eq!(instance.sense(), Sense::Minimize);
assert_eq!(instance.decision_variables().len(), 2);
assert_eq!(instance.constraints().len(), 2);
The new
method validates that all variable IDs used in the objective function and
constraints are defined in the decision variables map, returning an error if any
undefined variables are referenced.
§Evaluate
trait
The Evaluate
trait allows evaluation of expressions and functions given variable assignments.
This is essential for solution verification and constraint checking.
use ommx::{Evaluate, Function, linear, coeff, ATol};
use ommx::v1::State;
use std::collections::HashMap;
// Create a function: 2*x1 + 3*x2
let func = Function::from(coeff!(2.0) * linear!(1) + coeff!(3.0) * linear!(2));
// Create variable assignments
let state = State::from(HashMap::from([(1, 4.0), (2, 5.0)]));
// Evaluate: 2*4 + 3*5 = 23
let result = func.evaluate(&state, ATol::default())?;
assert_eq!(result, 23.0);
§Solution
and SampleSet
Solutions represent the results of optimization, including variable values, objective value,
and solution metadata. SampleSet
contains multiple solutions for stochastic methods.
use ommx::{Instance, DecisionVariable, VariableID, Constraint, ConstraintID, Function, Sense, Linear, Evaluate, ATol, linear, coeff};
use ommx::v1::State;
use maplit::btreemap;
use std::collections::HashMap;
// Create an instance with variables and constraints
let decision_variables = btreemap! {
VariableID::from(1) => DecisionVariable::continuous(VariableID::from(1)),
VariableID::from(2) => DecisionVariable::continuous(VariableID::from(2)),
};
let objective = Function::from(linear!(1) + coeff!(2.0) * linear!(2));
let constraints = btreemap! {
// x1 + x2 <= 10
ConstraintID::from(1) => Constraint::less_than_or_equal_to_zero(
ConstraintID::from(1),
Function::from(linear!(1) + linear!(2) + Linear::from(coeff!(-10.0)))
),
// x1 >= 1 (as -x1 + 1 <= 0)
ConstraintID::from(2) => Constraint::less_than_or_equal_to_zero(
ConstraintID::from(2),
Function::from(coeff!(-1.0) * linear!(1) + Linear::from(coeff!(1.0)))
),
};
let instance = Instance::new(
Sense::Minimize,
objective,
decision_variables,
constraints,
)?;
// Create a state with variable values that satisfy constraints
let state = State::from(HashMap::from([(1, 3.0), (2, 4.0)]));
// Evaluate the instance to get a solution
let solution = instance.evaluate(&state, ATol::default())?;
// Access solution properties
assert_eq!(*solution.objective(), 11.0); // 3 + 2*4 = 11
assert!(solution.feasible()); // All constraints satisfied
// Check evaluated constraints
let evaluated_constraints = solution.evaluated_constraints();
assert_eq!(evaluated_constraints.len(), 2);
// Constraint 1: x1 + x2 - 10 <= 0, evaluated to 3 + 4 - 10 = -3
let constraint1 = &evaluated_constraints[&ConstraintID::from(1)];
assert_eq!(constraint1.evaluated_value(), &-3.0);
assert!(constraint1.feasible()); // -3 <= 0 ✓
// Constraint 2: -x1 + 1 <= 0, evaluated to -3 + 1 = -2
let constraint2 = &evaluated_constraints[&ConstraintID::from(2)];
assert_eq!(constraint2.evaluated_value(), &-2.0);
assert!(constraint2.feasible()); // -2 <= 0 ✓
§Substitute
trait
The Substitute
trait enables symbolic substitution of variables with expressions,
allowing for problem transformation and preprocessing.
use ommx::{Substitute, Function, Linear, linear, coeff, assign, ATol};
use approx::assert_abs_diff_eq;
// Original expression: 2*x1 + 1
let expr = coeff!(2.0) * linear!(1) + Linear::one();
// Substitute x1 = 0.5*x2 + 1
let assignments = assign! {
1 <- coeff!(0.5) * linear!(2) + Linear::one()
};
let substituted = expr.substitute_acyclic(&assignments)?;
assert_abs_diff_eq!(
substituted,
Function::from(linear!(2) + coeff!(3.0)) // Result: 2*(0.5*x2 + 1) + 1 = x2 + 3
);
Re-exports§
pub use ocipkg;
pub use parse::*;
Modules§
- artifact
- Manage messages as container
- dataset
- Dataset for mathematical programming problems distributed as OMMX Artifact.
- mps
- Parse MPS format
- parse
- qplib
- Parser for the QPLIB format
- random
- Random generation and [
mod@proptest
] support for OMMX Message structs - v1
- Module created from
ommx.v1
proto files
Macros§
- assign
- Creates an
crate::AcyclicAssignments
from assignment expressions. - coeff
- Creates a
crate::Coefficient
from a floating-point expression. - linear
- Creates a
crate::LinearMonomial
from a variable ID expression. - monomial
- Creates a
crate::MonomialDyn
from variable ID expressions. - quadratic
- Creates a
crate::QuadraticMonomial
from variable ID expressions. - variable_
ids - Creates a
crate::VariableIDSet
from variable ID expressions.
Structs§
- ATol
- Absolute tolerance
- Acyclic
Assignments - Represents a set of assignment rules (
VariableID
->Function
) that has been validated to be free of any circular dependencies. - Binary
IdPair - ID pair for QUBO problems
- Binary
Ids - Bound
- Bound of a decision variable
- Coefficient
- Coefficient of polynomial terms.
- Constraint
ommx.v1.Constraint
with validated, typed fields.- Constraint
Hints - ConstraintID
- ID for constraint
- ConstraintID
Parameters - Constraint
Metadata - Auxiliary metadata for constraints (excluding essential id and equality)
- Decision
Variable - The decision variable with metadata.
- Decision
Variable Analysis - The result of analyzing the decision variables in an instance.
- Decision
Variable Metadata - Auxiliary metadata for decision variables (excluding essential id, kind, bound, substituted_value)
- Degree
- Duplicated
SampleID Error - Evaluated
Constraint - Single evaluation result using the new design
- Evaluated
Decision Variable - Single evaluation result with data integrity guarantees
- Instance
- Instance, represents a mathematical optimization problem.
- Invalid
Degree Error - Kind
Parameters - Linear
Parameters - Monomial
Dyn - A sorted list of decision variable and parameter IDs
- OneHot
- Parametric
Instance - Optimization problem instance with parameters
- Polynomial
Base - Base struct for
Linear
and other polynomials - Polynomial
Parameters - Quadratic
Parameters - Removed
Constraint - SampleID
- Sample
Set - Multiple sample solution results with deduplication
- Sampled
- Sampled
Constraint - Multiple sample evaluation results with deduplication
- Sampled
Decision Variable - Multiple sample evaluation results with deduplication
- Solution
- Single solution result with data integrity guarantees
- Sos1
- Term
- Unknown
SampleID Error - VariableID
- ID for decision variable and parameter.
- VariableID
Pair
Enums§
- Bound
Error - Coefficient
Error - Decision
Variable Error - Equality
- Constraint equality.
- Function
- A real-valued function of decision variables used for objective and constraint functions.
- Infeasible
Detected - Error type for when the instance is proofed to be infeasible
- Instance
Error - Violation of the
Instance
invariants. - Kind
- Linear
Monomial - Linear function only contains monomial of degree 1 or constant
- LogEncoding
Error - Quadratic
Monomial - Quadratic
Parse Error - Sample
SetError - Error occurred during SampleSet validation
- Sense
- Solution
Error - Error occurred during Solution validation
- State
Validation Error - Substitution
Error - Error types that can occur during substitution operations.
Traits§
- Evaluate
- Evaluate with a State
- Message
- A Protocol Buffers message.
- Monomial
- Monomial, without coefficient
- Substitute
- A trait for substituting decision variables with other functions in mathematical expressions.
Functions§
- arbitrary_
constraints - arbitrary_
decision_ variables - arbitrary_
unique_ variable_ ids - substitute
- In-place version of
Substitute::substitute
. - substitute_
acyclic - In-place version of
Substitute::substitute_acyclic
. - substitute_
one - In-place version of
Substitute::substitute_one
.
Type Aliases§
- Bounds
- Bound for each decision variable
- Linear
- Polynomial
- Quadratic
- SampleID
Set - VariableID
Set