Field | Type | Label | Description |
terms | Linear.Term | repeated |
|
constant | double |
|
Field | Type | Label | Description |
id | uint64 |
|
|
coefficient | double |
|
A monomial in a multivariate polynomial.
Field | Type | Label | Description |
ids | uint64 | repeated |
|
coefficient | double |
|
Multivariate polynomial
Field | Type | Label | Description |
terms | Monomial | repeated |
|
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]]`
Field | Type | Label | Description |
rows | uint64 | repeated |
|
columns | uint64 | repeated |
|
values | double | repeated |
|
linear | Linear | optional |
|
Real-valued multivariate function used for objective function and constraints.
Field | Type | Label | Description |
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` |
Field | Type | Label | Description |
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. |
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
A constraint evaluated with a state
Field | Type | Label | Description |
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. |
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
Field | Type | Label | Description |
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. |
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
Equality of a constraint.
Name | Number | Description |
EQUALITY_UNSPECIFIED | 0 | |
EQUALITY_EQUAL_TO_ZERO | 1 | |
EQUALITY_LESS_THAN_OR_EQUAL_TO_ZERO | 2 |
A message representing a one-hot constraint.
Field | Type | Label | Description |
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. |
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, ...).
Field | Type | Label | Description |
one_hot_constraints | OneHot | repeated | One-hot constraint: e.g. `x_1 + ... + x_n = 1` for binary variables `x_1, ..., x_n`. |
Upper and lower bound of the decision variable.
Field | Type | Label | Description |
lower | double | Lower bound of the decision variable. |
|
upper | double | Upper bound of the decision variable. |
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.
Field | Type | Label | Description |
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. |
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
Kind of the decision variable
Name | Number | Description |
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. |
Field | Type | Label | Description |
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. |
Field | Type | Label | Description |
key | uint64 |
|
|
value | Function |
|
Field | Type | Label | Description |
name | string | optional |
|
description | string | optional |
|
authors | string | repeated |
|
created_by | string | optional | The application or library name that created this message. |
A set of parameters for instantiating an optimization problem from a parametric instance
Field | Type | Label | Description |
entries | Parameters.EntriesEntry | repeated |
|
Field | Type | Label | Description |
key | uint64 |
|
|
value | double |
|
The sense of this instance
Name | Number | Description |
SENSE_UNSPECIFIED | 0 | |
SENSE_MINIMIZE | 1 | |
SENSE_MAXIMIZE | 2 |
Placeholder of a parameter in a parametrized optimization problem
Field | Type | Label | Description |
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 |
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
Optimization problem including parameter, variables varying while solving the problem like penalty weights or dual variables.
These parameters are not decision variables.
Field | Type | Label | Description |
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. |
Field | Type | Label | Description |
key | uint64 |
|
|
value | Function |
|
The solver proved that the problem is infeasible.
TODO: Add more information about the infeasibility.
Field | Type | Label | Description |
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 with evaluated objective and constraints
Field | Type | Label | Description |
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. |
Name | Option |
feasible_unrelaxed | true |
A set of values of decision variables, without any evaluation, even the
feasiblity of the solution.
Field | Type | Label | Description |
entries | State.EntriesEntry | repeated | The value of the solution for each variable ID. |
Field | Type | Label | Description |
key | uint64 |
|
|
value | double |
|
The solver proved that the problem is unbounded.
TODO: Add more information about the unboundedness.
Name | Number | Description |
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. |
Name | Number | Description |
RELAXATION_UNSPECIFIED | 0 | No relaxation is used. |
RELAXATION_LP_RELAXED | 1 | The solution is obtained by a relaxed linear programming problem. |
Output of the sampling process.
Field | Type | Label | Description |
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 |
Name | Option |
feasible_unrelaxed | true |
Field | Type | Label | Description |
key | uint64 |
|
|
value | bool |
|
Field | Type | Label | Description |
key | uint64 |
|
|
value | bool |
|
Field | Type | Label | Description |
key | uint64 |
|
|
value | bool |
|
Evaluated constraint for samples
Field | Type | Label | Description |
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 |
Field | Type | Label | Description |
key | uint64 |
|
|
value | bool |
|
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
Field | Type | Label | Description |
key | string |
|
|
value | string |
|
A pair of decision variable description and its sampled values
Field | Type | Label | Description |
decision_variable | DecisionVariable |
|
|
samples | SampledValues | optional | Sampled values of decision variable. This becomes `None` if the decision variable is not sampled. |
A map from sample IDs to sampled values
Field | Type | Label | Description |
entries | SampledValues.SampledValuesEntry | repeated |
|
Compressed sampled values, but uncompressed state is also valid. The reader should not assume that every states are distinct.
Field | Type | Label | Description |
value | double |
|
|
ids | uint64 | repeated | IDs of the sample |
A map from sample ID to state
Field | Type | Label | Description |
entries | Samples.SamplesEntry | repeated |
|
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.
Field | Type | Label | Description |
state | State | State of the sample |
|
ids | uint64 | repeated | IDs of the sample |
.proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
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) |