Crate ommx

Source
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
AcyclicAssignments
Represents a set of assignment rules (VariableID -> Function) that has been validated to be free of any circular dependencies.
BinaryIdPair
ID pair for QUBO problems
BinaryIds
Bound
Bound of a decision variable
Coefficient
Coefficient of polynomial terms.
Constraint
ommx.v1.Constraint with validated, typed fields.
ConstraintHints
ConstraintID
ID for constraint
ConstraintIDParameters
ConstraintMetadata
Auxiliary metadata for constraints (excluding essential id and equality)
DecisionVariable
The decision variable with metadata.
DecisionVariableAnalysis
The result of analyzing the decision variables in an instance.
DecisionVariableMetadata
Auxiliary metadata for decision variables (excluding essential id, kind, bound, substituted_value)
Degree
DuplicatedSampleIDError
EvaluatedConstraint
Single evaluation result using the new design
EvaluatedDecisionVariable
Single evaluation result with data integrity guarantees
Instance
Instance, represents a mathematical optimization problem.
InvalidDegreeError
KindParameters
LinearParameters
MonomialDyn
A sorted list of decision variable and parameter IDs
OneHot
ParametricInstance
Optimization problem instance with parameters
PolynomialBase
Base struct for Linear and other polynomials
PolynomialParameters
QuadraticParameters
RemovedConstraint
SampleID
SampleSet
Multiple sample solution results with deduplication
Sampled
SampledConstraint
Multiple sample evaluation results with deduplication
SampledDecisionVariable
Multiple sample evaluation results with deduplication
Solution
Single solution result with data integrity guarantees
Sos1
Term
UnknownSampleIDError
VariableID
ID for decision variable and parameter.
VariableIDPair

Enums§

BoundError
CoefficientError
DecisionVariableError
Equality
Constraint equality.
Function
A real-valued function of decision variables used for objective and constraint functions.
InfeasibleDetected
Error type for when the instance is proofed to be infeasible
InstanceError
Violation of the Instance invariants.
Kind
LinearMonomial
Linear function only contains monomial of degree 1 or constant
LogEncodingError
QuadraticMonomial
QuadraticParseError
SampleSetError
Error occurred during SampleSet validation
Sense
SolutionError
Error occurred during Solution validation
StateValidationError
SubstitutionError
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
SampleIDSet
VariableIDSet

Derive Macros§

Message