Using Solver Sessions

Using solver sessions

The procedures and functions of the GMP::SolverSession namespace are listed in this table. Solver sessions are created implicitly by AIMMS or explicitly by calling the procedure GMP::Instance::CreateSolverSession.

Table 41 : GMP::SolverSession functions and procedures

Execute(solverSession)

AsynchronousExecute(solverSession)

ExecutionStatus(solverSession)\(\to\)AllExecutionStatuses

Interrupt(solverSession)

WaitForCompletion(Objects)

WaitForSingleCompletion(Objects)\(\to\)AllSolverSessionCompletionObjects

CreateProgressCategory(solverSession[, Name][, Size])

GetOptionValue(solverSession, optionName)

SetOptionValue(solverSession, optionName, value)

GetInstance(solverSession)\(\to\)AllGeneratedMathematicalPrograms

GetSolver(solverSession)\(\to\)AllSolvers

GetIterationsUsed(solverSession)

GetMemoryUsed(solverSession)

GetTimeUsed(solverSession)

GetBestBound(solverSession)

GetCandidateObjective(solverSession)

GetObjective(solverSession)

GetProgramStatus(solverSession)\(\to\)AllSolutionStates

GetSolverStatus(solverSession)\(\to\)AllSolutionStates

GetCallbackInterruptStatus(solverSession)\(\to\)AllSolverInterrupts

GenerateCut(solverSession, row[, local][, purgeable])

RejectIncumbent(solverSession)

GetNodeNumber(solverSession)

GetNodeObjective(solverSession)

GetNodesLeft(solverSession)

GetNodesUsed(solverSession)

GetNumberOfBranchNodes(solverSession)

GetIIS(solverSession, rowSet, colSet)

Transfer(solverSession, GMP)

Solving a mathematical program instance

By calling the GMP::SolverSession::Execute procedure, the given solver session will take care of solving the associated mathematical program instance in a blocking manner, i.e. the function will not return until the solver has completed the solution process. This function is called implicitly by the GMP::Instance::Solve function or by the SOLVE statement.

Asynchronous solve

Alternatively, you can solve a mathematical program instance in an non-blocking manner by using the function GMP::SolverSession::AsynchronousExecute. Rather than waiting for the solution process to complete, this function will dispatch the solution process to a separate thread of execution, and return immediately. This allows multiple mathematical program instances to be solved in parallel, assuming your computer has multiple processors or a multi-core processor. Note that requests for a synchronous solve through the SOLVE statement will fail if a AIMMS is still executing an asynchronous solution process.

Session synchronization

To allow your application to synchronize its execution when multiple solver sessions are executed asynchronously, AIMMS offers the following synchronization procedures

• GMP::SolverSession::Interrupt,

• GMP::SolverSession::ExecutionStatus,

• GMP::SolverSession::WaitForCompletion, and

• GMP::SolverSession::WaitForSingleCompletion.

Through the GMP::SolverSession::Interrupt function you can request AIMMS to interrupt a solver session that is executing (asynchronously). You can call the function GMP::SolverSession::ExecutionStatus to check the status of a given solver session.

Waiting for multiple completions

Using the function GMP::SolverSession::WaitForCompletion you can halt the main AIMMS thread of execution to wait until the entire set of solver sessions passed as an argument to the function have completed. You can use this function, for instance, to end the solution phase of your model, prior to moving on to the post-processing phase of your model.

…and for single completion

In addition, AIMMS offers a function GMP::SolverSession::WaitForSingleCompletion which returns as soon as a single solver session from the given set of solver sessions has completed its execution. The return value of the function is the completed solver session that caused the function to return. You can use WaitForSingleCompletion, for instance, to asynchronously solve the next mathematical program instance from a queue of mathematical program instances waiting to be solved.

No solution transfer

Note that neither GMP::SolverSession::Execute and GMP::SolverSession::AsynchronousExecute will copy the initial solution into the solver, or copy the final solution back into solution repository or model identifiers. When you use these functions you always have to explicitly call functions from the GMP::Solution namespace to accomplish these tasks.

Support for callbacks

When callbacks for the mathematical program instance associated with a solver session have been set (see also Managing Generated Mathematical Program Instances), AIMMS will make sure that the specified callback procedures in your model will be called whenever appropriate. If you have specified a single callback procedure for multiple callback reasons, you can call the procedure

• GMP::SolverSession::GetCallbackInterruptStatus

to retrieve the reason why your callback procedure was called. The result is an element in the predeclared set AllSolverInterrupts which contains the elements

• Candidate,

• Incumbent,

• AddCut,

• Iterations,

• Heuristic,

• StatusChange, and

• Finished.

When the solver session has not yet been called, the status is " (empty element). During a callback, you can call the function

• GMP::SolverSession::GetInstance

if you need the mathematical program instance associated with the given solver session, and you can retrieve the current objective values using the functions

• GMP::SolverSession::GetBestBound,

• GMP::SolverSession::GetObjective.

Synchronous nested solves allowed

During any callback you are allowed to generate and solve other mathematical program instances in a synchronous manner. You can use such nested solves, for instance, for finding a heuristic solution during a Heuristic callback. Once you have found a heuristic solution, you can pass it onto the running solver session using the function GMP::Solution::SendToSolverSession. Note that this functionality is currently only supported by CPLEX and Gurobi.

No asynchronous solves

During a callback AIMMS does not allow you to call the function GMP::SolverSession::AsynchronousExecute to solve another mathematical program instance in an asynchronous manner. However, AIMMS offers a special class of synchronization objects called events, which allow you to notify the main thread of execution that some event has occurred and act accordingly. When set during a callback, the main thread of execution may respond, for instance, by generating a mathematical program instance based on solver data set by the callback, and solve that mathematical program instance in an asynchronous manner. Events are discussed in full detail in Synchronization Events.

Adding cuts

During an AddCut callback you may use the procedure GMP::SolverSession::GenerateCut to generate a local or global cut. A local cut will only be added to the current node in the solution process and all its descendant nodes, while a global cut will remain to exist for all nodes onwards. The result of the procedure will be the temporary addition of row to the matrix, as if GMP::Row::Generate had been called. Note that this functionality is currently only supported by CPLEX, Gurobi and ODH-CPLEX.

Rejecting incumbents

During a Candidate callback you can reject the incumbent found by the solver by calling the procedure GMP::SolverSession::RejectIncumbent. Note that this functionality is currently only supported by CPLEX.

Setting options

You can set options for a specific solver session associated through the function GMP::SolverSession::SetOptionValue. These option values override the option values for the associated GMP, set through GMP::Instance::SetOptionValue, which in their turn override the project options.

Retrieving an irreducible infeasible set

If the generated math program appears to be infeasible then the procedure GMP::SolverSession::GetIIS can be used to retrieve an irreducible infeasible set (IIS). This procedure returns the row and column numbers of the rows and columns that are part of the IIS.