Protocol Documentation

Table of Contents

ommx/v1/linear.proto

Top

Linear

FieldTypeLabelDescription
terms Linear.Term repeated

constant double

Linear.Term

FieldTypeLabelDescription
id uint64

coefficient double

ommx/v1/polynomial.proto

Top

Monomial

A monomial in a multivariate polynomial.

FieldTypeLabelDescription
ids uint64 repeated

coefficient double

Polynomial

Multi­variate polynomial

FieldTypeLabelDescription
terms Monomial repeated

ommx/v1/quadratic.proto

Top

Quadratic

Quadratic function as a COO-style sparse matrix and linear sparse vector.

COOrdinate format, also known as triplet format, is a way to represent sparse matrices as a list of non-zero elements.

It consists of three lists: the row indices, the column indices, and the values of the non-zero elements with following constraints:

- Entries and coordinates sorted by row, then column.

- There are no duplicate entries (i.e. duplicate (i,j) locations)

- Data arrays MAY have explicit zeros.

Note that this matrix is not assured to be symmetric nor upper triangular.

For example, a quadratic function `x1^2 + x2^2 + 2x1*x2` can be represented as:

- `{ rows: [0, 0, 1], columns: [0, 1, 1], values: [1, 2, 1] }`, i.e. an upper triangular matrix `[[1, 2], [0, 1]`

- `{ rows: [0, 0, 1, 1], columns: [0, 1, 0, 1], values: [1, 1, 1, 1] }`, i.e. a symmetric matrix `[[1, 1], [1, 1]]`

or even a non-symmetric, non-trianglar matrix as `x1^2 + 3x1*x2 - x2*x1 + x2^2`:

- `{ rows: [0, 0, 1, 1], columns: [0, 1, 0, 1], values: [1, 3, -1, 1] }`, i.e. a non-symmetric matrix `[[1, 3], [-1, 1]]`

FieldTypeLabelDescription
rows uint64 repeated

columns uint64 repeated

values double repeated

linear Linear optional

ommx/v1/function.proto

Top

Function

Real-valued multivariate function used for objective function and constraints.

FieldTypeLabelDescription
constant double

Constant function like `f(x_1, x_2) = 2`

linear Linear

Linear function like `f(x_1, x_2) = 2 x_1 + 3 x_2`

quadratic Quadratic

Quadratic function like `f(x_1, x_2) = 4 x_1 x_2 + 5 x_2`

polynomial Polynomial

Polynomial like `f(x_1, x_2) = 4 x_1^2 + 5 x_2^3 + 6 x_1 x_2^2 + 7 x_2^2 + 8 x_1 x_2 + 9 x_1 + 10 x_2 + 11`

ommx/v1/constraint.proto

Top

Constraint

FieldTypeLabelDescription
id uint64

Constraint ID - Constraint IDs are managed separately from decision variable IDs. We can use the same ID for both. For example, we have a decision variable `x` with decision variable ID `1`` and constraint `x == 0` with constraint ID `1`. - IDs are not required to be sequential. - IDs must be unique with other types of constraints.

equality Equality

function Function

subscripts int64 repeated

Integer parameters of the constraint. Consider for example a problem constains a series of constraints `x[i, j] + y[i, j] <= 10` for `i = 1, 2, 3` and `j = 4, 5`, then 6 = 3x2 `Constraint` messages should be created corresponding to each pair of `i` and `j`. The `name` field of this message is intended to be a human-readable name of `x[i, j] + y[i, j] <= 10`, and the `subscripts` field is intended to be the value of `[i, j]` like `[1, 5]`.

parameters Constraint.ParametersEntry repeated

Key-value parameters of the constraint.

name string optional

Name of the constraint.

description string optional

Detail human-readable description of the constraint.

Constraint.ParametersEntry

FieldTypeLabelDescription
key string

value string

EvaluatedConstraint

A constraint evaluated with a state

FieldTypeLabelDescription
id uint64

equality Equality

evaluated_value double

The value of function for the state

used_decision_variable_ids uint64 repeated

IDs of decision variables used to evalute this constraint

subscripts int64 repeated

Integer parameters of the constraint.

parameters EvaluatedConstraint.ParametersEntry repeated

Key-value parameters of the constraint.

name string optional

Name of the constraint.

description string optional

Detail human-readable description of the constraint.

dual_variable double optional

Value for the Lagrangian dual variable of this constraint. This is optional because not all solvers support to evaluate dual variables.

removed_reason string optional

Short removed reason of the constraint. This field exists only if this message is evaluated from a removed constraint.

removed_reason_parameters EvaluatedConstraint.RemovedReasonParametersEntry repeated

Detailed parameters why the constraint is removed. This field exists only if this message is evaluated from a removed constraint.

EvaluatedConstraint.ParametersEntry

FieldTypeLabelDescription
key string

value string

EvaluatedConstraint.RemovedReasonParametersEntry

FieldTypeLabelDescription
key string

value string

RemovedConstraint

FieldTypeLabelDescription
constraint Constraint

The removed constraint

removed_reason string

Short reason why the constraint was removed. This should be the name of method, function or application which remove the constraint.

removed_reason_parameters RemovedConstraint.RemovedReasonParametersEntry repeated

Arbitrary key-value parameters representing why the constraint was removed. This should be human-readable and can be used for debugging.

RemovedConstraint.RemovedReasonParametersEntry

FieldTypeLabelDescription
key string

value string

Equality

Equality of a constraint.

NameNumberDescription
EQUALITY_UNSPECIFIED 0

EQUALITY_EQUAL_TO_ZERO 1

EQUALITY_LESS_THAN_OR_EQUAL_TO_ZERO 2

ommx/v1/one_hot.proto

Top

OneHot

A message representing a one-hot constraint.

FieldTypeLabelDescription
constraint_id uint64

The ID of the constraint.

decision_variables uint64 repeated

The list of ids of decision variables that are constrained to be one-hot.

ommx/v1/constraint_hints.proto

Top

ConstraintHints

A constraint hint is an additional inforomation to be used by solver to gain performance.

They are derived from one-or-more constraints in the instance and typically contains information of special types of constraints (e.g. one-hot, SOS, ...).

FieldTypeLabelDescription
one_hot_constraints OneHot repeated

One-hot constraint: e.g. `x_1 + ... + x_n = 1` for binary variables `x_1, ..., x_n`.

ommx/v1/decision_variables.proto

Top

Bound

Upper and lower bound of the decision variable.

FieldTypeLabelDescription
lower double

Lower bound of the decision variable.

upper double

Upper bound of the decision variable.

DecisionVariable

Decison variable which mathematical programming solver will optimize.

It must have its kind, i.e. binary, integer, real or others and unique identifier of 64-bit integer.

It may have its name and subscripts which are used to identify in modeling tools.

FieldTypeLabelDescription
id uint64

Decision variable ID. - IDs are not required to be sequential.

kind DecisionVariable.Kind

Kind of the decision variable

bound Bound optional

Bound of the decision variable If the bound is not specified, the decision variable is considered as unbounded.

name string optional

Name of the decision variable. e.g. `x`

subscripts int64 repeated

Subscripts of the decision variable. e.g. `[1, 3]` for an element of multidimensional deicion variable `x[1, 3]`

parameters DecisionVariable.ParametersEntry repeated

Additional parameters for decision variables

description string optional

Detail human-readable description of the decision variable.

substituted_value double optional

The value substituted by partial evaluation of the instance. Not determined by the solver.

DecisionVariable.ParametersEntry

FieldTypeLabelDescription
key string

value string

DecisionVariable.Kind

Kind of the decision variable

NameNumberDescription
KIND_UNSPECIFIED 0

KIND_BINARY 1

KIND_INTEGER 2

KIND_CONTINUOUS 3

KIND_SEMI_INTEGER 4

Semi-integer decision variable is a decision variable that can take only integer values in the given range or zero.

KIND_SEMI_CONTINUOUS 5

Semi-continuous decision variable is a decision variable that can take only continuous values in the given range or zero.

ommx/v1/instance.proto

Top

Instance

FieldTypeLabelDescription
description Instance.Description

decision_variables DecisionVariable repeated

Decision variables used in this instance - This must constain every decision variables used in the objective and constraints. - This can contains a decision variable that is not used in the objective or constraints.

objective Function

constraints Constraint repeated

Constraints of the optimization problem

sense Instance.Sense

The sense of this problem, i.e. minimize the objective or maximize it. Design decision note: - This is a required field. Most mathematical modeling tools allow for an empty sense and default to minimization. Alternatively, some tools do not create such a field and represent maximization problems by negating the objective function. This project prefers explicit descriptions over implicit ones to avoid such ambiguity and to make it unnecessary for developers to look up the reference for the treatment of omitted cases.

parameters Parameters optional

Parameters used when instantiating this instance

constraint_hints ConstraintHints

Constraint hints to be used by solver to gain performance. They are derived from one-or-more constraints in the instance and typically contains information of special types of constraints (e.g. one-hot, SOS, ...).

removed_constraints RemovedConstraint repeated

Constraints removed via preprocessing. These are restored when evaluated into `ommx.v1.Solution`.

decision_variable_dependency Instance.DecisionVariableDependencyEntry repeated

When a decision variable is dependent on another decision variable as polynomial, this map contains the ID of the dependent decision variable as key and the polynomial as value.

Instance.DecisionVariableDependencyEntry

FieldTypeLabelDescription
key uint64

value Function

Instance.Description

FieldTypeLabelDescription
name string optional

description string optional

authors string repeated

created_by string optional

The application or library name that created this message.

Parameters

A set of parameters for instantiating an optimization problem from a parametric instance

FieldTypeLabelDescription
entries Parameters.EntriesEntry repeated

Parameters.EntriesEntry

FieldTypeLabelDescription
key uint64

value double

Instance.Sense

The sense of this instance

NameNumberDescription
SENSE_UNSPECIFIED 0

SENSE_MINIMIZE 1

SENSE_MAXIMIZE 2

ommx/v1/parametric_instance.proto

Top

Parameter

Placeholder of a parameter in a parametrized optimization problem

FieldTypeLabelDescription
id uint64

ID for the parameter - IDs are not required to be sequential. - The ID must be unique within the instance including the decision variables.

name string optional

Name of the parameter. e.g. `x`

subscripts int64 repeated

Subscripts of the parameter, same usage as DecisionVariable.subscripts

parameters Parameter.ParametersEntry repeated

Additional metadata for the parameter, same usage as DecisionVariable.parameters

description string optional

Human-readable description for the parameter

Parameter.ParametersEntry

FieldTypeLabelDescription
key string

value string

ParametricInstance

Optimization problem including parameter, variables varying while solving the problem like penalty weights or dual variables.

These parameters are not decision variables.

FieldTypeLabelDescription
description Instance.Description

decision_variables DecisionVariable repeated

Decision variables used in this instance

parameters Parameter repeated

Parameters of this instance - The ID must be unique within the instance including the decision variables.

objective Function

Objective function of the optimization problem. This may contain parameters in addition to the decision variables.

constraints Constraint repeated

Constraints of the optimization problem. This may contain parameters in addition to the decision variables.

sense Instance.Sense

The sense of this problem, i.e. minimize the objective or maximize it.

constraint_hints ConstraintHints

Constraint hints to be used by solver to gain performance. They are derived from one-or-more constraints in the instance and typically contains information of special types of constraints (e.g. one-hot, SOS, ...).

removed_constraints RemovedConstraint repeated

Constraints removed via preprocessing. These are restored when evaluated into `ommx.v1.Solution`.

decision_variable_dependency ParametricInstance.DecisionVariableDependencyEntry repeated

When a decision variable is dependent on another decision variable as polynomial, this map contains the ID of the dependent decision variable as key and the polynomial as value.

ParametricInstance.DecisionVariableDependencyEntry

FieldTypeLabelDescription
key uint64

value Function

ommx/v1/solution.proto

Top

Infeasible

The solver proved that the problem is infeasible.

TODO: Add more information about the infeasibility.

Result

FieldTypeLabelDescription
error string

Error information by the solver which cannot be expressed by other messages. This string should be human-readable.

solution Solution

Some feasible or infeasible solution for the problem is found. Most of heuristic solvers should use this value.

infeasible Infeasible

The solver proved that the problem is infeasible, i.e. all solutions of the problem are infeasible. If the solver cannot get the proof of infeasibility, and just cannot find any feasible solution due to the time limit or due to heuristic algorithm limitation, the solver should return its *best* `Solution` message with `feasible` field set to `false`.

unbounded Unbounded

The solver proved that the problem is unbounded.

Solution

Solution with evaluated objective and constraints

FieldTypeLabelDescription
state State

objective double

decision_variables DecisionVariable repeated

evaluated_constraints EvaluatedConstraint repeated

feasible bool

The feasibility of the solution for all, remaining and removed constraints. The feasibility for the remaining constraints is represented by the `feasible_relaxed` field.

feasible_relaxed bool optional

Feasibility of the solution for remaining constraints, ignoring removed constraints. This is optional due to the backward compatibility. If this field is NULL, the `feasible` field represents relaxed feasibility, and the deprecated `feasible_unrelaxed` field represents the feasibility including removed constraints.

feasible_unrelaxed bool

Deprecated. [DEPRECATED] Feasibility of the solution for all constraints. This field has been introduced in Python SDK 1.6.0 and deprecated in 1.7.0. The feasibility in this sense is represented by the `feasible` field after 1.7.0.

optimality Optimality

The optimality of the solution.

relaxation Relaxation

Whether the solution is obtained by a relaxed linear programming solver.

Fields with deprecated option

Name Option
feasible_unrelaxed

true

State

A set of values of decision variables, without any evaluation, even the

feasiblity of the solution.

FieldTypeLabelDescription
entries State.EntriesEntry repeated

The value of the solution for each variable ID.

State.EntriesEntry

FieldTypeLabelDescription
key uint64

value double

Unbounded

The solver proved that the problem is unbounded.

TODO: Add more information about the unboundedness.

Optimality

NameNumberDescription
OPTIMALITY_UNSPECIFIED 0

The solver cannot determine whether the solution is optimal. Most of heuristic solvers should use this value.

OPTIMALITY_OPTIMAL 1

The solver has determined that the solution is optimal.

OPTIMALITY_NOT_OPTIMAL 2

The solver has determined that the solution is not optimal.

Relaxation

NameNumberDescription
RELAXATION_UNSPECIFIED 0

No relaxation is used.

RELAXATION_LP_RELAXED 1

The solution is obtained by a relaxed linear programming problem.

ommx/v1/sample_set.proto

Top

SampleSet

Output of the sampling process.

FieldTypeLabelDescription
objectives SampledValues

decision_variables SampledDecisionVariable repeated

constraints SampledConstraint repeated

feasible SampleSet.FeasibleEntry repeated

Feasibility for *both* remaining and removed constraints of each sample. The meaning of `feasible` field in SDK changes between Python SDK 1.6.0 to 1.7.0. In Python SDK 1.6.0, `feasible` represents the feasibility of remaining constraints of each sample, i.e. removed constraints (introduced in 1.6.0) are not considered. After Python SDK 1.7.0, `feasible` represents the feasibility of all constraints of each sample. The feasibility of 1.6.0 is renamed to `feasible_relaxed` in 1.7.0.

feasible_unrelaxed SampleSet.FeasibleUnrelaxedEntry repeated

Deprecated. [Deprecated] This field has been introduced in Python SDK 1.6.0 to represent the feasibility of all constraints of each sample. The `feasible` field is used in this sense after Python SDK 1.7.0.

feasible_relaxed SampleSet.FeasibleRelaxedEntry repeated

Feasibility for remaining (non-removed) constraints of each sample.

sense Instance.Sense

Minimize or Maximize

Fields with deprecated option

Name Option
feasible_unrelaxed

true

SampleSet.FeasibleEntry

FieldTypeLabelDescription
key uint64

value bool

SampleSet.FeasibleRelaxedEntry

FieldTypeLabelDescription
key uint64

value bool

SampleSet.FeasibleUnrelaxedEntry

FieldTypeLabelDescription
key uint64

value bool

SampledConstraint

Evaluated constraint for samples

FieldTypeLabelDescription
id uint64

Constraint ID

equality Equality

name string optional

Name of the constraint.

subscripts int64 repeated

Integer parameters of the constraint.

parameters SampledConstraint.ParametersEntry repeated

Key-value parameters of the constraint.

description string optional

Detail human-readable description of the constraint.

removed_reason string optional

Short removed reason of the constraint. This field exists only if this message is evaluated from a removed constraint.

removed_reason_parameters SampledConstraint.RemovedReasonParametersEntry repeated

Detailed parameters why the constraint is removed. This field exists only if this message is evaluated from a removed constraint.

evaluated_values SampledValues

Evaluated values of constraint for each sample

used_decision_variable_ids uint64 repeated

IDs of decision variables used to evaluate this constraint

feasible SampledConstraint.FeasibleEntry repeated

Feasibility of each sample

SampledConstraint.FeasibleEntry

FieldTypeLabelDescription
key uint64

value bool

SampledConstraint.ParametersEntry

FieldTypeLabelDescription
key string

value string

SampledConstraint.RemovedReasonParametersEntry

FieldTypeLabelDescription
key string

value string

SampledDecisionVariable

A pair of decision variable description and its sampled values

FieldTypeLabelDescription
decision_variable DecisionVariable

samples SampledValues optional

Sampled values of decision variable. This becomes `None` if the decision variable is not sampled.

SampledValues

A map from sample IDs to sampled values

FieldTypeLabelDescription
entries SampledValues.SampledValuesEntry repeated

SampledValues.SampledValuesEntry

Compressed sampled values, but uncompressed state is also valid. The reader should not assume that every states are distinct.

FieldTypeLabelDescription
value double

ids uint64 repeated

IDs of the sample

Samples

A map from sample ID to state

FieldTypeLabelDescription
entries Samples.SamplesEntry repeated

Samples.SamplesEntry

Sampling processes are likely to generate same samples multiple times. We compress the same samples into one entry.

Note that uncompressed state is also valid. The reader should not assume that every states are distinct.

FieldTypeLabelDescription
state State

State of the sample

ids uint64 repeated

IDs of the sample

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)