Google OR-Tools v9.12
a fast and portable software suite for combinatorial optimization
Loading...
Searching...
No Matches
model_solve_parameters.h
Go to the documentation of this file.
1// Copyright 2010-2025 Google LLC
2// Licensed under the Apache License, Version 2.0 (the "License");
3// you may not use this file except in compliance with the License.
4// You may obtain a copy of the License at
5//
6// http://www.apache.org/licenses/LICENSE-2.0
7//
8// Unless required by applicable law or agreed to in writing, software
9// distributed under the License is distributed on an "AS IS" BASIS,
10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11// See the License for the specific language governing permissions and
12// limitations under the License.
13
14// IWYU pragma: private, include "ortools/math_opt/cpp/math_opt.h"
15// IWYU pragma: friend "ortools/math_opt/cpp/.*"
16
17#ifndef OR_TOOLS_MATH_OPT_CPP_MODEL_SOLVE_PARAMETERS_H_
18#define OR_TOOLS_MATH_OPT_CPP_MODEL_SOLVE_PARAMETERS_H_
19
20#include <sys/types.h>
21
22#include <cstdint>
23#include <initializer_list>
24#include <optional>
25#include <vector>
26
27#include "absl/container/flat_hash_set.h"
28#include "absl/status/status.h"
29#include "absl/status/statusor.h"
30#include "absl/time/time.h"
32#include "ortools/math_opt/cpp/map_filter.h" // IWYU pragma: export
36#include "ortools/math_opt/model_parameters.pb.h"
38
39namespace operations_research {
40namespace math_opt {
41
42// Parameters to control a single solve that are specific to the input
43// model (see SolveParametersProto for model independent parameters).
45 // Returns the parameters that empty DualSolution and DualRay, only keep the
46 // values of all variables in PrimalSolution and PrimalRay.
47 //
48 // This is a shortcut method that is equivalent to setting the dual filters
49 // with MakeSkipAllFilter().
51
52 // Returns the parameters that empty DualSolution and DualRay, only keep the
53 // values of the specified variables in PrimalSolution and PrimalRay.
54 //
55 // The input Collection must be usable in a for-range loop with Variable
56 // values. This will be typically a std::vector<Variable> or and
57 // std::initializer_list<Variable> (see the other overload).
58 //
59 // This is a shortcut method that is equivalent to setting the dual filters
60 // with MakeSkipAllFilter() and the variable_values_filter with
61 // MakeKeepKeysFilter(variables).
62 //
63 // Example:
64 // std::vector<Variable> decision_vars = ...;
65 // const auto params =
66 // ModelSolveParameters::OnlySomePrimalVariables(decision_vars);
67 template <typename Collection>
69 const Collection& variables);
70
71 // Returns the parameters that empty DualSolution and DualRay, only keeping
72 // the values of the specified variables in PrimalSolution and PrimalRay.
73 //
74 // See the other overload's documentation for details. This overload is needed
75 // since C++ can't guess the type when using an initializer list expression.
76 //
77 // Example:
78 // const Variable a = ...;
79 // const Variable b = ...;
80 // const auto params =
81 // ModelSolveParameters::OnlySomePrimalVariables({a, b});
83 std::initializer_list<Variable> variables);
84
85 // The filter that is applied to variable_values of both PrimalSolution and
86 // PrimalRay.
88
89 // The filter that is applied to dual_values of DualSolution and DualRay.
91
92 // The filter that is applied to quadratic_dual_values of DualSolution and
93 // DualRay.
95
96 // The filter that is applied to reduced_costs of DualSolution and DualRay.
98
99 // Optional initial basis for warm starting simplex LP solvers. If set, it is
100 // expected to be valid.
101 std::optional<Basis> initial_basis;
102
103 // A suggested starting solution for the solver.
104 //
105 // MIP solvers generally only want primal information (`variable_values`),
106 // while LP solvers want both primal and dual information (`dual_values`).
107 //
108 // Many MIP solvers can work with: (1) partial solutions that do not specify
109 // all variables or (2) infeasible solutions. In these cases, solvers
110 // typically solve a sub-MIP to complete/correct the hint.
111 //
112 // How the hint is used by the solver, if at all, is highly dependent on the
113 // solver, the problem type, and the algorithm used. The most reliable way to
114 // ensure your hint has an effect is to read the underlying solvers logs with
115 // and without the hint.
116 //
117 // Simplex-based LP solvers typically prefer an initial basis to a solution
118 // hint (they need to crossover to convert the hint to a basic feasible
119 // solution otherwise).
121 // Values should be finite and not NaN (otherwise, `Solve()` will return a
122 // `Status` error).
124
125 // Values should be finite and not NaN (otherwise, `Solve()` will return a
126 // `Status` error).
128
129 // Returns a failure if the referenced variables and constraints don't
130 // belong to the input expected_storage (which must not be nullptr).
131 absl::Status CheckModelStorage(const ModelStorage* expected_storage) const;
132
133 // Returns the proto equivalent of this object.
134 //
135 // The caller should use CheckModelStorage() as this function does not check
136 // internal consistency of the referenced variables and constraints.
137 SolutionHintProto Proto() const;
138
139 // Returns the hint corresponding to this proto and the given model.
140 //
141 // This can be useful when loading a hint from another format, e.g. with
142 // MPModelProtoSolutionHintToMathOptHint().
143 static absl::StatusOr<SolutionHint> FromProto(
144 const Model& model, const SolutionHintProto& hint_proto);
145 };
146
147 // Optional solution hints. If the underlying solver only accepts a single
148 // hint, the first hint is used.
149 std::vector<SolutionHint> solution_hints;
150
151 // Optional branching priorities. Variables with higher values will be
152 // branched on first. Variables for which priorities are not set get the
153 // solver's default priority (usually zero).
155
156 // Parameters for an individual objective in a multi-objective model.
158 // Optional objective degradation absolute tolerance. For a hierarchical
159 // multi-objective solver, each objective fⁱ is processed in priority order:
160 // the solver determines the optimal objective value Γⁱ, if it exists,
161 // subject to all constraints in the model and the additional constraints
162 // that fᵏ(x) = Γᵏ (within tolerances) for each k < i. If set, a solution is
163 // considered to be "within tolerances" for this objective fᵏ if
164 // |fᵏ(x) - Γᵏ| ≤ `objective_degradation_absolute_tolerance`.
165 //
166 // See also `objective_degradation_relative_tolerance`; if both parameters
167 // are set for a given objective, the solver need only satisfy one to be
168 // considered "within tolerances".
169 //
170 // If set, must be nonnegative.
172
173 // Optional objective degradation relative tolerance. For a hierarchical
174 // multi-objective solver, each objective fⁱ is processed in priority order:
175 // the solver determines the optimal objective value Γⁱ, if it exists,
176 // subject to all constraints in the model and the additional constraints
177 // that fᵏ(x) = Γᵏ (within tolerances) for each k < i. If set, a solution is
178 // considered to be "within tolerances" for this objective fᵏ if
179 // |fᵏ(x) - Γᵏ| ≤ `objective_degradation_relative_tolerance` * |Γᵏ|.
180 //
181 // See also `objective_degradation_absolute_tolerance`; if both parameters
182 // are set for a given objective, the solver need only satisfy one to be
183 // considered "within tolerances".
184 //
185 // If set, must be nonnegative.
187
188 // Maximum time a solver should spend on optimizing this particular
189 // objective (or infinite if not set).
190 //
191 // Note that this does not supersede the global time limit in
192 // SolveParametersProto.time_limit; both will be enforced when set.
193 //
194 // This value is not a hard limit, solve time may slightly exceed this
195 // value.
196 absl::Duration time_limit = absl::InfiniteDuration();
197
198 // Returns the proto equivalent of this object.
199 absl::StatusOr<ObjectiveParametersProto> Proto() const;
200
201 static absl::StatusOr<ObjectiveParameters> FromProto(
202 const ObjectiveParametersProto& proto);
203 };
204 // Parameters for individual objectives in a multi-objective model.
206
207 // Optional lazy constraint annotations. Included linear constraints will be
208 // marked as "lazy" with supporting solvers, meaning that they will only be
209 // added to the working model as-needed as the solver runs.
210 //
211 // Note that this an algorithmic hint that does not affect the model's
212 // feasible region; solvers not supporting these annotations will simply
213 // ignore it.
214 absl::flat_hash_set<LinearConstraint> lazy_linear_constraints;
215
216 // Returns a failure if the referenced variables and constraints do not belong
217 // to the input expected_storage (which must not be nullptr).
218 absl::Status CheckModelStorage(const ModelStorage* expected_storage) const;
219
220 // Returns the proto equivalent of this object.
221 //
222 // The caller should use CheckModelStorage() as this function does not check
223 // internal consistency of the referenced variables and constraints.
224 absl::StatusOr<ModelSolveParametersProto> Proto() const;
225
226 // Returns the ModelSolveParameters corresponding to this proto and the given
227 // model.
228 static absl::StatusOr<ModelSolveParameters> FromProto(
229 const Model& model, const ModelSolveParametersProto& proto);
230};
231
233// Inline functions implementations.
235
236template <typename Collection>
238 const Collection& variables) {
240 parameters.variable_values_filter = MakeKeepKeysFilter(variables);
241 return parameters;
242}
243
244} // namespace math_opt
245} // namespace operations_research
246
247#endif // OR_TOOLS_MATH_OPT_CPP_MODEL_SOLVE_PARAMETERS_H_
An object oriented wrapper for quadratic constraints in ModelStorage.
Definition gurobi_isv.cc:28
absl::flat_hash_map< Variable, V > VariableMap
absl::flat_hash_map< LinearConstraint, V > LinearConstraintMap
absl::flat_hash_map< Objective, V > ObjectiveMap
Definition objective.h:123
MapFilter< ValueType > MakeKeepKeysFilter(const Collection &keys)
Definition map_filter.h:167
In SWIG mode, we don't want anything besides these top-level includes.
Parameters for an individual objective in a multi-objective model.
static absl::StatusOr< ObjectiveParameters > FromProto(const ObjectiveParametersProto &proto)
absl::StatusOr< ObjectiveParametersProto > Proto() const
Returns the proto equivalent of this object.
static absl::StatusOr< SolutionHint > FromProto(const Model &model, const SolutionHintProto &hint_proto)
absl::Status CheckModelStorage(const ModelStorage *expected_storage) const
absl::Status CheckModelStorage(const ModelStorage *expected_storage) const
MapFilter< QuadraticConstraint > quadratic_dual_values_filter
MapFilter< LinearConstraint > dual_values_filter
The filter that is applied to dual_values of DualSolution and DualRay.
ObjectiveMap< ObjectiveParameters > objective_parameters
Parameters for individual objectives in a multi-objective model.
static ModelSolveParameters OnlySomePrimalVariables(const Collection &variables)
absl::StatusOr< ModelSolveParametersProto > Proto() const
MapFilter< Variable > reduced_costs_filter
The filter that is applied to reduced_costs of DualSolution and DualRay.
static absl::StatusOr< ModelSolveParameters > FromProto(const Model &model, const ModelSolveParametersProto &proto)
absl::flat_hash_set< LinearConstraint > lazy_linear_constraints