18. Exitflags

The FORCESPRO solver can identify issues that occur during its execution (whether they are of technical or of numerical nature) and notify the user of these issues. The solver is reporting these issues in the form of exit status codes called exitflags. Usages of the exitflags:

• The user can identify and fix configuration errors and mistakes with calling the solver.

• Certain exitflags can provide hints about issues to the problem formulation. By consulting the returned exitflags the user can perform improvements to the problem formulation which can lead to a more robust problem formulation.

• The user can identify issues occurring during execution on the fly. This can be used to prepare a strategy with exitflag-based decisions in order to achieve a more robust execution (handling both normal scenarios and edge cases).

18.1. Exitflags and quality of the result

The FORCESPRO solver returns 3 output elements in order to report the status and result of the execution:

• output: contains the solution to the problem given to the solver to be solved

• exitflag: contains the exitflag status code returned by the solver

• info: contains further information about the execution and solution of the problem

The standard format of an execution of the FORCESPRO solver is shown below:

MatlabPython

[output, exitflag, info] = FORCESNLPsolver(problem);

The possible exitflags are documented in Table 18.1. The exitflag should always be checked before continuing with program execution to avoid using spurious solutions later in the code. Check whether the solver has exited without an error before using the solution. For example, we suggest to use an assert statement:

MatlabPython

assert(exitflag == 1, 'Some issue with FORCESPRO solver');

Table 18.1 Exitflag values

Exitflag	Description
1	Locally optimal solution found (i.e. the point satisfies the KKT optimality conditions to the requested accuracy).
2	(for binary branch-and-bound) A feasible point has been identified for which the objective value is no more than codeoptions.mip.mipgap*100 per cent worse than the global optimum. (for all other solvers) Specified timeout set for the solver execution has been reached. Best non-optimal point found during execution will be returned. You can examine the value of optimality conditions returned inside the info struct by FORCESPRO to decide whether the point returned is acceptable.
3	Solver execution has been terminated as the termination parameter has been set by the user. Best non-optimal point found during execution will be returned. You can examine the value of optimality conditions returned inside the info struct by FORCESPRO to decide whether the point returned is acceptable.
11	This exitflag is not returned for a solver call. It is returned when calling the external callbacks of the solver (see Calling the nonlinear functions from MATLAB or Python). This exitflag indicates that the execution of the integrator in the external callbacks was successful.
12	This exitflag is not returned for a solver call. It is returned when calling the external callbacks of the solver (see Calling the nonlinear functions from MATLAB or Python). This exitflag indicates that the number of steps set by the user for the integrator exceeded the maximum number of steps allowed.
0	(for binary branch-and-bound) maximum computation time of codeoptions.mip.timeout reached. The returned solution is the best one found so far. (for all other solvers) Maximum number of iterations reached. You can examine the value of optimality conditions returned inside the info struct by FORCESPRO to decide whether the point returned is acceptable.
-1	(only binary branch-and-bound) Infeasible problem (issues solving the root relaxation to desired accuracy).
-2	(only binary branch-and-bound) Out of memory – cannot fit branch and bound nodes into pre-allocated memory.
-3	Deprecated.
-4	Wrong number of inequalities input to solver.
-5	Error occurred during matrix factorization.
-6	NaN or INF occurred during functions evaluations in external callbacks or due to an internal error of the nonlinear solver.
-7	The solver could not proceed. Most likely cause is that the problem is infeasible.Try formulating a problem with slack variables (soft constraints) to avoid this error. For low-level formulations, see also Debugging a formulation.
-8	The internal QP solver could not proceed. This exitflag can only occur when using the Sequential quadratic programming algorithm. The most likely cause is that an infeasible QP or a numerical unstable QP was encountered. Try increasing the Hessian regularization parameter reg_hessian (see SQP specific codeoptions).
-9	The internal QP solver could not proceed. This exitflag can only occur when using the Sequential quadratic programming algorithm. The most likely cause is that an infeasible QP or a numerical unstable QP was encountered. Try increasing the hessian regularization parameter reg_hessian if this exitflag is encountered (see SQP specific codeoptions).
-10	NaN or INF occurred during evaluation of functions and derivatives or due to an internal error of the convex solver. The problem might be infeasible. If this occurs at iteration zero, try changing the initial point. For example, for a cost function \(1/\sqrt{x}\) with an initialization \(x_0=0\), this error would occur. For low-level formulations, see also Debugging a formulation.
-11	Invalid values in problem parameters.
-12	Specified timeout set for the solver was too small to find any point (optimal or non-optimal).
-13	An error occurred in the solver while performing a linesearch.
-98	Thread failure. This can only happen if the solver is executing in parallel and an error occurred while managing the threads for parallel execution.
-99	Lock mechanism failure. This can only happen if the solver is executing in parallel and the lock mechanism used to ensure data consistency returned an error.
-100	License error. This typically happens if you are trying to execute code that has been generated with a Simulation license of FORCESPRO on another machine. Regenerate the solver using your machine. Additionally, this may occur in a HW machine that has not been properly enabled yet for a FORCESPRO solver execution. For more information see Licensing.
-101	Invalid memory error. The FORCESPRO solver uses memory provided by the user. This mechanism is usually opaque in the various available interfaces and is mainly operated by the user when using the C or C++ interface of FORCESPRO. This error indicates that the memory provided was invalid. For more information see C interface: memory allocations.
-102	Invalid number of threads specified. The solver can be configured during code generation to support up to a maximum number of threads for efficiency and data consistency reasons. This error indicates that the number of the thread specified by the user during runtime exceeds the maximum number of threads allowed. For more information see Multicore parallelization.
-200	Invalid return value (<= -100) of external functions occurred (only if codeoptions.callback_check_status = 1).
-201, ..., -299	a negative return value ret from external function evaluation occurred (only if codeoptions.callback_check_status = 1). Exitflag is calculated as ret - 200.

Note

Certain exitflags might not apply for all solve methods that can be selected for FORCESPRO. The available exitflags for a solver can also be found in the generated solver files, in the header file (under the include folder) as well as in the help section of the solver for the available interfaces (e.g. MATLAB, Simulink or Python).

18.2. Mixed integer Nonlinear Programming exitflags

The FORCESPRO MINLP solver returns a different set of status code exitflags which are available in the info output element of the FORCESPRO solver. The available exitflags for the MINLP solver can found below in Table 18.2.:

Table 18.2 MINLP exitflag values

Exitflag	Description
0	Local optimum found. Final tolerance on integrality gap satisfied.
1	Integer feasible solution found.
2	No integer feasible found.
3	Relaxation solve failed at root node.
4	Unexpected error occurred.
5	Search failed to converge.