Crate ommx

Expand description

Rust SDK for OMMX (Open Mathematics prograMming eXchange)

§OMMX Messages

OMMX defines several messages in protobuf schema, and their Rust bindings are in the v1 module.

§Examples

Create v1::Linear message in Rust, and serialize/deserialize it

use ommx::v1::{Linear, linear::Term};
use prost::Message; // For `encode` and `decode` methods

// Create a linear function `x1 + 2 x2 + 3`
let linear = Linear::single_term(1, 1.0) + Linear::single_term(2, 2.0) + 3.0;

// Serialize the message to a byte stream
let mut buf = Vec::new();
linear.encode(&mut buf).unwrap();

// Deserialize the byte stream back into a linear function message
let decoded_linear = Linear::decode(buf.as_slice()).unwrap();

// Print the deserialized message
println!("{:?}", decoded_linear);

Evaluate a v1::Linear with v1::State into f64

use ommx::{Evaluate, v1::{Linear, State, linear::Term}};
use maplit::{hashmap, btreeset};

// Create a linear function `x1 + 2 x2 + 3`
let linear = Linear::single_term(1, 1.0) + Linear::single_term(2, 2.0) + 3.0;

// Create a state `x1 = 4`, `x2 = 5`, and `x3 = 6`
let state: State = hashmap! { 1 => 4.0, 2 => 5.0, 3 => 6.0 }.into();

// Evaluate the linear function with the state, and get the value and used variable ids
let value = linear.evaluate(&state, ommx::ATol::default()).unwrap();

assert_eq!(value, 1.0 * 4.0 + 2.0 * 5.0 + 3.0);

§OMMX Artifact

OMMX Artifact is an OCI Artifact, i.e. a container image with arbitrary content, storing the OMMX Messages. It is useful for storing messages on local disk or sharing with others via container registry.

§Examples

Create an artifact as a file with an instance created by random::random_deterministic function

use ocipkg::ImageName;
use ommx::{artifact::{Builder, InstanceAnnotations}, random::{random_deterministic, InstanceParameters}};

// Create random LP instance to be saved into an artifact
let lp = random_deterministic(InstanceParameters::default());

// Builder for creating an artifact as a file (e.g. `random_lp_instance.ommx`)
let mut builder = Builder::new_archive_unnamed("random_lp_instance.ommx".into())?;

// Add the instance with annotations
let mut annotations = InstanceAnnotations::default();
annotations.set_title("random_lp".to_string());
annotations.set_created(chrono::Local::now());
builder.add_instance(lp, annotations)?;

// Build the artifact
let _artifact = builder.build()?;

Create an artifact on local registry, and then push it to remote registry (e.g. GitHub Container Registry)

use ocipkg::ImageName;
use ommx::{artifact::{Builder, InstanceAnnotations}, random::{random_deterministic, InstanceParameters}};

// Create random LP instance to be saved into an artifact
let lp = random_deterministic(InstanceParameters::default_lp());

// Builder for creating an artifact in local registry
let mut builder = Builder::new(
    ImageName::parse("ghcr.io/jij-inc/ommx/random_lp_instance:testing")?
)?;

// Add annotations for the artifact
builder.add_source(&url::Url::parse("https://github.com/Jij-Inc/ommx")?);
builder.add_description("Test artifact".to_string());

// Add the instance with annotations
let mut annotations = InstanceAnnotations::default();
annotations.set_title("random_lp".to_string());
annotations.set_created(chrono::Local::now());
builder.add_instance(lp, annotations)?;

// Build the artifact
let mut artifact = builder.build()?;

// Push the artifact to remote registry
artifact.push()?;

Pull an artifact from remote registry, and load the instance message

use ocipkg::ImageName;
use ommx::artifact::{Artifact, media_types};

let image_name = ImageName::parse("ghcr.io/jij-inc/ommx/random_lp_instance:testing")?;

// Pull the artifact from remote registry
let mut remote = Artifact::from_remote(image_name)?;
let mut local = remote.pull()?;

// List the digest of instances
for desc in local.get_layer_descriptors(&media_types::v1_instance())? {
    println!("{}", desc.digest());
}

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
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 literal.
linear: Creates a crate::LinearMonomial from a variable ID literal.
monomial: Creates a crate::MonomialDyn from variable ID literals.
quadratic: Creates a crate::QuadraticMonomial from variable ID literals.

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

Crate ommxCopy item path

§OMMX Messages

§Examples

§OMMX Artifact

§Examples

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Derive Macros§

Crate ommx