Crate ommx

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)
);

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
ConstraintHintsError: Error that can occur when working with ConstraintHints
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

Crate ommxCopy item path

§Rust SDK for OMMX (Open Mathematics prograMming eXchange)

§Linear, Quadratic, Polynomial, and Function

§Bound, Kind, and DecisionVariable

§Constraint

§Instance

§Evaluate trait

§Solution and SampleSet

§Substitute trait