ortools-clone/ortools/math_opt/model_update.proto

// Copyright 2010-2025 Google LLC
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Updates an existing Model proto.
syntax = "proto3";

package operations_research.math_opt;

import "ortools/math_opt/model.proto";
import "ortools/math_opt/sparse_containers.proto";

option java_package = "com.google.ortools.mathopt";
option java_multiple_files = true;

// Updates to existing variables in a ModelProto.
//
// Applies only to existing variables in a model, for new variables, see
// ModelUpdateProto.new_variables.
message VariableUpdatesProto {
  // Updates ModelProto.variables.lower_bounds.
  //
  // Requirements:
  //  * lower_bounds.ids must be from ModelProto.variables.ids.
  //  * lower_bounds.values must be < infinity.
  //  * Unset values are unchanged.
  SparseDoubleVectorProto lower_bounds = 1;

  // Updates ModelProto.variables.upper_bounds.
  //
  // Requirements:
  //  * upper_bounds.ids must be from ModelProto.variables.ids.
  //  * upper_bounds.values must be > -infinity.
  //  * Unset values are unchanged.
  SparseDoubleVectorProto upper_bounds = 2;

  // Updates ModelProto.variables.integers.
  //
  // Requirements:
  //  * integers.ids must be from ModelProto.variables.ids.
  //  * Unset values are unchanged.
  SparseBoolVectorProto integers = 3;
}

// Updates the objective of a Model, both for existing and new variables.
message ObjectiveUpdatesProto {
  // Not set indicates no change, false is minimize, true is maximize.
  optional bool direction_update = 1;
  // Not set indicates not change, otherwise the new offset.
  optional double offset_update = 2;

  // Updates ObjectiveProto.linear_coefficients.
  //
  // Requirements:
  //  * linear_coefficients.ids must be variable ids, either existing one (from
  //    ModelProto.variables.ids) or new ones (from
  //    ModelUpdateProto.new_variables.ids).
  //  * linear_coefficients.values must be finite
  //  * Unset values are unchanged.
  //  * The value 0.0 removes a variable from the linear objective. This
  //    value should only be used for existing variables.
  SparseDoubleVectorProto linear_coefficients = 3;

  // Updates ObjectiveProto.quadratic_coefficients
  //
  // Requirements in addition to those on SparseDoubleMatrixProto messages:
  //  * Each element of quadratic_coefficients.row_ids and each element of
  //    quadratic_coefficients.column_ids must be a variable id, either an
  //    existing one (from ModelProto.variables.ids) or a new one (from
  //    ModelUpdateProto.new_variables.ids).
  //  * The matrix must be upper triangular: for each i,
  //    quadratic_coefficients.row_ids[i] <=
  //    quadratic_coefficients.column_ids[i].
  //
  // Notes:
  //  * Unset values are unchanged.
  //  * The value 0.0 removes a quadratic term (i.e. product of two variables)
  //    from the quadratic objective. This value should only be used for
  //    existing quadratic terms appearing in the objective.
  SparseDoubleMatrixProto quadratic_coefficients = 4;

  // Not set indicates no change, otherwise the new priority. If set, the value
  // must be nonnegative. Furthermore, each objective priority must be distinct
  // at solve time; this condition is not validated at the proto level, so
  // models may temporarily have objectives with the same priority.
  optional int64 priority_update = 5;
}

// Updates the auxiliary objectives of a Model, both for existing and new
// variables. Auxiliary objectives can be deleted, added, or modified in place.
message AuxiliaryObjectivesUpdatesProto {
  // Removes auxiliary objectives from the model.
  //
  // Each value must be in [0, max(int64)). Values must be in strictly
  // increasing order. Applies only to existing auxiliary objective IDs that
  // have not yet been deleted.
  repeated int64 deleted_objective_ids = 1;

  // Add new auxiliary objectives to the model. All keys must be in
  // [0, max(int64)), and must be greater than any ids used in the initial model
  //  and previous updates. All nonempty names should be distinct from existing
  // names for the primary and other auxiliary objectives.
  map<int64, ObjectiveProto> new_objectives = 2;

  // Updates existing auxiliary objectives in the model. All key IDs must be
  // existing in the model and not included in `deleted_objective_ids`.
  map<int64, ObjectiveUpdatesProto> objective_updates = 3;
}

// Updates to existing linear constraints in a ModelProto.
message LinearConstraintUpdatesProto {
  // Updates ModelProto.linear_constraints.lower_bounds.
  //
  // Requirements:
  //  * lower_bounds.ids must be from ModelProto.linear_constraints.ids.
  //  * lower_bounds.values must be < infinity.
  //  * Unset values are unchanged.
  SparseDoubleVectorProto lower_bounds = 1;
  // Updates ModelProto.linear_constraints.upper_bounds.
  //
  // Requirements:
  //  * upper_bounds.ids must be from ModelProto.linear_constraints.ids.
  //  * upper_bounds.values must be > -infinity.
  //  * Unset values are unchanged.
  SparseDoubleVectorProto upper_bounds = 2;
}

// Updates to quadratic constraints; only addition and deletion, no support for
// in-place constraint updates.
message QuadraticConstraintUpdatesProto {
  // Removes quadratic constraints from the model.
  //
  // Each value must be in [0, max(int64)). Values must be in strictly
  // increasing order. Applies only to existing quadratic constraint ids that
  // have not yet been deleted.
  repeated int64 deleted_constraint_ids = 1;

  // Add new quadratic constraints to the model. All keys must be in
  // [0, max(int64)), and must be greater than any ids used in the initial model
  // and previous updates. All nonempty names should be distinct from existing
  // names and each other.
  map<int64, QuadraticConstraintProto> new_constraints = 2;
}

// Updates to second-order cone constraints; only addition and deletion, no
// support for in-place constraint updates.
message SecondOrderConeConstraintUpdatesProto {
  // Removes second-order cone constraints from the model.
  //
  // Each value must be in [0, max(int64)). Values must be in strictly
  // increasing order. Applies only to existing second-order cone constraint ids
  // that have not yet been deleted.
  repeated int64 deleted_constraint_ids = 1;

  // Add new second-order cone constraints to the model. All keys must be in
  // [0, max(int64)), and must be greater than any ids used in the initial model
  // and previous updates. All nonempty names should be distinct from existing
  // names and each other.
  map<int64, SecondOrderConeConstraintProto> new_constraints = 2;
}

// Data for updates to SOS1 and SOS2 constraints; only addition and deletion, no
// support for in-place constraint updates.
message SosConstraintUpdatesProto {
  // Removes SOS constraints from the model.
  //
  // Each value must be in [0, max(int64)). Values must be in strictly
  // increasing order. Applies only to existing SOS constraint ids that have not
  // yet been deleted.
  repeated int64 deleted_constraint_ids = 1;

  // Add new SOS constraints to the model. All keys must be in [0, max(int64)),
  // and must be greater than any ids used in the initial model and previous
  // updates. All nonempty names should be distinct from existing names and each
  // other.
  map<int64, SosConstraintProto> new_constraints = 2;
}

// Data for updates to indicator constraints; only addition and deletion, no
// support for in-place constraint updates.
message IndicatorConstraintUpdatesProto {
  // Removes indicator constraints from the model.
  //
  // Each value must be in [0, max(int64)). Values must be in strictly
  // increasing order. Applies only to existing indicator constraint ids that
  // have not yet been deleted.
  repeated int64 deleted_constraint_ids = 1;

  // Add new indicator constraints to the model. All keys must be in
  // [0, max(int64)), and must be greater than any ids used in the initial model
  // and previous updates. All nonempty names should be distinct from existing
  // names and each other.
  map<int64, IndicatorConstraintProto> new_constraints = 2;
}

// Updates to a ModelProto.
message ModelUpdateProto {
  // Removes variables from the model.
  //
  // Values must be in strictly increasing order. Apply only to existing
  // variable ids that have not yet been deleted. The ids of deleted variables
  // should not appear in other fields (e.g. variable_updates,
  // objective_updates, linear_constraint_matrix_updates).
  repeated int64 deleted_variable_ids = 1;

  // Removes linear constraints from the model.
  //
  // Values must be in strictly increasing order. Apply only to existing
  // linear constraint ids that have not yet been deleted. The ids of deleted
  // linear constraints should not appear in other fields (e.g.
  // linear_constraint_updates, linear_constraint_matrix_updates).
  repeated int64 deleted_linear_constraint_ids = 2;

  // Updates properties of existing variables. Should not contain any deleted
  // variable ids.
  VariableUpdatesProto variable_updates = 3;

  // Updates properties of existing linear constraints. Should not contain any
  // deleted linear constraints ids.
  LinearConstraintUpdatesProto linear_constraint_updates = 4;

  // Add new variables to the model. All new_variables.ids must be greater than
  // any ids used in the initial model and previous updates. All nonempty names
  // should be distinct from existing names.
  VariablesProto new_variables = 5;

  // Add new linear constraints to the model. All new_linear_constraints.ids
  // must be greater than any ids used in the initial model and previous
  // updates. All nonempty names should be distinct from existing names.
  LinearConstraintsProto new_linear_constraints = 6;

  // Updates the primary objective, both for existing and new variables.
  ObjectiveUpdatesProto objective_updates = 7;

  // Updates the auxiliary objectives, both for existing and new variables.
  AuxiliaryObjectivesUpdatesProto auxiliary_objectives_updates = 13;

  // Updates the linear constraint matrix, both for existing and new
  // variables/linear constraints.
  //
  // Requirements:
  //  * linear_constraint_matrix_updates.row_ids are linear constraint ids,
  //    either existing or new.
  //  * linear_constraint_matrix_updates.column_ids are variables ids, either
  //    existing or new.
  //  * Matrix entries are unchanged if the (constraint, variable) pair is
  //    existing and unset.
  //  * Matrix entries are zero if either the constraint or variable is new and
  //    the (constraint, variable) pair is unset.
  //  * Zero values delete existing entries, and have no effect for new entries.
  //  * linear_constraint_matrix.values must all be finite.
  SparseDoubleMatrixProto linear_constraint_matrix_updates = 8;

  // Updates the quadratic constraints (addition and deletion only).
  QuadraticConstraintUpdatesProto quadratic_constraint_updates = 9;

  // Updates the second-order cone constraints (addition and deletion only).
  SecondOrderConeConstraintUpdatesProto second_order_cone_constraint_updates =
      14;

  // Updates the general constraints (addition and deletion only).
  SosConstraintUpdatesProto sos1_constraint_updates = 10;
  SosConstraintUpdatesProto sos2_constraint_updates = 11;
  IndicatorConstraintUpdatesProto indicator_constraint_updates = 12;
}