operations_research::math_opt::IncrementalSolver Class Reference

#include <incremental_solver.h>

Inheritance diagram for operations_research::math_opt::IncrementalSolver:

Public Member Functions
	IncrementalSolver ()=default
	IncrementalSolver (const IncrementalSolver &)=delete
IncrementalSolver &	operator= (const IncrementalSolver &)=delete
virtual	~IncrementalSolver ()=default
virtual absl::StatusOr< SolveResult >	Solve (const SolveArguments &arguments)=0
absl::StatusOr< SolveResult >	Solve ()
virtual absl::StatusOr< ComputeInfeasibleSubsystemResult >	ComputeInfeasibleSubsystem (const ComputeInfeasibleSubsystemArguments &arguments)=0
absl::StatusOr< ComputeInfeasibleSubsystemResult >	ComputeInfeasibleSubsystem ()
virtual absl::StatusOr< UpdateResult >	Update ()=0
virtual absl::StatusOr< SolveResult >	SolveWithoutUpdate (const SolveArguments &arguments) const =0
absl::StatusOr< SolveResult >	SolveWithoutUpdate () const
virtual absl::StatusOr< ComputeInfeasibleSubsystemResult >	ComputeInfeasibleSubsystemWithoutUpdate (const ComputeInfeasibleSubsystemArguments &arguments) const =0
absl::StatusOr< ComputeInfeasibleSubsystemResult >	ComputeInfeasibleSubsystemWithoutUpdate () const
virtual SolverType	solver_type () const =0
	Returns the underlying solver used.

Detailed Description

Interface for incrementally solving of a model.

This is a feature for advance users. Most users should only use the non-incremental Solve(), SubprocessSolve(),... functions.

Here incremental means that the we try to reuse the existing underlying solver internals between each solve. There is no guarantee though that the solver supports all possible model changes. Hence there is not guarantee that performances will be improved when using this class; this is solver dependent. Typically LPs have more to gain from incremental solve than MIPs. In both cases, even if the solver supports the model changes, incremental solve may actually be slower.

Implementation of this interface are returned by factories that can be found next to non-incremental solve functions. See NewIncrementalSolver() in solve.h and NewSubprocessIncrementalSolver() in subprocess_solve.h for example.

Those factories function instantiates the solver, setup it from the current state of the Model and register on it to listen to changes. Calling Solve() will update the underlying solver with latest model changes and solve this model.

Usage: Model model = ...; ASSIGN_OR_RETURN( const std::unique_ptr<IncrementalSolver> incremental_solve, NewIncrementalSolver(&model, SolverType::kXxx));

ASSIGN_OR_RETURN(const SolveResult result1, incremental_solve->Solve());

model.AddVariable(...); ...

ASSIGN_OR_RETURN(const SolveResult result2, incremental_solve->Solve());

...

Lifecycle: The IncrementalSolver is only keeping a std::weak_ref on Model's internal data and thus it returns an error if Update() or Solve() are called after the Model has been destroyed. It is fine to destroy the IncrementalSolver after the associated Model though.

Thread-safety: The New(), Solve() and Update() methods must not be called while modifying the Model() (adding variables...). The user is expected to use proper synchronization primitives to serialize changes to the model and the use of this object. Note though that it is safe to call methods from different IncrementalSolver instances on the same Model concurrently. Same for calling factories of IncrementalSolver. The destructor is thread-safe and can be called even during a modification of the Model.

There is no problem calling SolveWithoutUpdate() concurrently on different instances of IncrementalSolver or while the model is being modified (unless of course the underlying solver itself is not thread-safe and can only be called from a single-thread).

Note

Solve(), Update() and SolveWithoutUpdate() are not reentrant so they should not be called concurrently on the same instance of IncrementalSolver.

Some solvers may add more restrictions regarding threading. Please see SolverType::kXxx documentation for details.

Definition at line 92 of file incremental_solver.h.

Constructor & Destructor Documentation

IncrementalSolver() [1/2]

operations_research::math_opt::IncrementalSolver::IncrementalSolver ( )

default

IncrementalSolver() [2/2]

operations_research::math_opt::IncrementalSolver::IncrementalSolver ( const IncrementalSolver & )

delete

~IncrementalSolver()

virtual operations_research::math_opt::IncrementalSolver::~IncrementalSolver ( )

virtualdefault

Member Function Documentation

ComputeInfeasibleSubsystem() [1/2]

absl::StatusOr< ComputeInfeasibleSubsystemResult > operations_research::math_opt::IncrementalSolver::ComputeInfeasibleSubsystem ( )

inline

Definition at line 127 of file incremental_solver.h.

ComputeInfeasibleSubsystem() [2/2]

virtual absl::StatusOr< ComputeInfeasibleSubsystemResult > operations_research::math_opt::IncrementalSolver::ComputeInfeasibleSubsystem ( const ComputeInfeasibleSubsystemArguments & arguments )

pure virtual

Updates the underlying solver with latest model changes and runs the computation.

Same as Solve() but compute the infeasible subsystem.

Implemented in operations_research::math_opt::internal::IncrementalSolverImpl.

ComputeInfeasibleSubsystemWithoutUpdate() [1/2]

absl::StatusOr< ComputeInfeasibleSubsystemResult > operations_research::math_opt::IncrementalSolver::ComputeInfeasibleSubsystemWithoutUpdate ( ) const

inline

Definition at line 166 of file incremental_solver.h.

ComputeInfeasibleSubsystemWithoutUpdate() [2/2]

virtual absl::StatusOr< ComputeInfeasibleSubsystemResult > operations_research::math_opt::IncrementalSolver::ComputeInfeasibleSubsystemWithoutUpdate ( const ComputeInfeasibleSubsystemArguments & arguments ) const

pure virtual

Same as ComputeInfeasibleSubsystem() but does not update the underlying solver with the latest changes to the model.

This is an advanced API, most users should use ComputeInfeasibleSubsystem().

Implemented in operations_research::math_opt::internal::IncrementalSolverImpl.

operator=()

IncrementalSolver & operations_research::math_opt::IncrementalSolver::operator= ( const IncrementalSolver & )

delete

Solve() [1/2]

absl::StatusOr< SolveResult > operations_research::math_opt::IncrementalSolver::Solve ( )

inline

Definition at line 117 of file incremental_solver.h.

Solve() [2/2]

virtual absl::StatusOr< SolveResult > operations_research::math_opt::IncrementalSolver::Solve ( const SolveArguments & arguments )

pure virtual

Updates the underlying solver with latest model changes and runs the solve.

A Status error will be returned if inputs are invalid or there is an unexpected failure in an underlying solver or for some internal math_opt errors. Otherwise, check SolveResult::termination.reason to see if an optimal solution was found.

Memory model: the returned SolveResult owns its own memory (for solutions, solve stats, etc.), EXPECT for a pointer back to the model. As a result:

• Keep the model alive to access SolveResult,
• Avoid unnecessarily copying SolveResult,
• The result is generally accessible after mutating this, but some care is needed if variables or linear constraints are added or deleted.

See callback.h for documentation on arguments.callback and arguments.callback_registration.

Implemented in operations_research::math_opt::internal::IncrementalSolverImpl.

solver_type()

virtual SolverType operations_research::math_opt::IncrementalSolver::solver_type ( ) const

pure virtual

Returns the underlying solver used.

Implemented in operations_research::math_opt::internal::IncrementalSolverImpl.

SolveWithoutUpdate() [1/2]

absl::StatusOr< SolveResult > operations_research::math_opt::IncrementalSolver::SolveWithoutUpdate ( ) const

inline

Definition at line 153 of file incremental_solver.h.

SolveWithoutUpdate() [2/2]

virtual absl::StatusOr< SolveResult > operations_research::math_opt::IncrementalSolver::SolveWithoutUpdate ( const SolveArguments & arguments ) const

pure virtual

Same as Solve() but does not update the underlying solver with the latest changes to the model.

This is an advanced API, most users should use Solve().

Implemented in operations_research::math_opt::internal::IncrementalSolverImpl.

Update()

virtual absl::StatusOr< UpdateResult > operations_research::math_opt::IncrementalSolver::Update ( )

pure virtual

Updates the model to solve.

This is an advanced API, most users should use Solve() above that does the update and before calling the solver. Calling this function is only useful for users that want to access to update data or users that need to use SolveWithoutUpdate() (which should not be common).

The returned value indicates if the update was possible or if the solver had to be recreated from scratch (which may happen when the solver does not support this specific update or any update at all). It also contains the attempted update data.

A status error will be returned if the underlying solver has an internal error.

Implemented in operations_research::math_opt::internal::IncrementalSolverImpl.

---

The documentation for this class was generated from the following file:

• ortools/math_opt/cpp/incremental_solver.h