Originally posted by: andriy155

Hi everyone,

I am curious, is there any way to obtain documentation on the cplexp() function. Specifically, I am curious about the values of the exitflag output parameter. I was able to find html files that come with ILOG studio that contain quite a good man-page dedicated to the cplex function. However, there is no information regarding what values are assigned to exitflag and under which conditions.

Thank you very much in advance!

Andriy
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: John Cui

Sorry for late reply.

The meanings of exitflag is the same as matlab toolbox function.
So you can go to here to take a look what exitflag mean.
http://www.mathworks.com/help/toolbox/optim/ug/bqnk0r0.html

For cplexlp's exitflag:

exitflag
Integer identifying the reason the algorithm terminated. The following lists the values of exitflag and the corresponding reasons the algorithm terminated.

1:Function converged to a solution x.
0:Number of iterations exceeded options.MaxIter.
-2:No feasible point was found.
-3:Problem is unbounded.
-4:NaN value was encountered during execution of the algorithm.
-5:Both primal and dual problems are infeasible.
-7:Search direction became too small. No further progress could be made.

John Cui
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: andriy155

Thank you very much for the answer!

By the way, I have noticed that the Matlab interface with CPLEX seems to be slow (slower than cplexint for instance). This has also been noted in this discussion http://www.ibm.com/developerworks/forums/thread.jspa?threadID=328560&tstart=-1 Do you have any solutions to this? (I ran both toolkit function and called Cplex as an object)
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: John Cui

You are welcome.

Yes, the current version matlab connector is slower than cplexint as the thread said.
We have improved a lot, will be in the next release.

John Cui
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: andriy155

Sounds good!

When are you planning to release the next version?

Andriy
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: SystemAdmin

Sorry, we are not allowed to/can not answer questions about release dates of future versions.
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: PingLiu

but I also got the values of '5' &'-8' for exitflag
how could you explain those values?
thanks .
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: John Cui

Actually, you can take a look the output.status and output.statusstring, which is the meaning of the related exitflag.

John Cui
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: RayZ

I have a solution from cplexqp() (version 12.5) where exitflag = 5 and output.cplexstatus = 6.

I assume the meaning of the output.cplexstatus values are what we find documented here: http://pic.dhe.ibm.com/infocenter/cosinfoc/v12r5/topic/ilog.odms.cplex.help/refcallablelibrary/html/optim.cplex.solutionstatus/group.html

But where can I find documentation for exitflag?
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: SystemAdmin

The exitflag output argument should be the same as for standard matlab toolbox functions. You can find documentation for that for example here.
You can also look at the file cplexqcp.m which is part of the CPLEX matlab connector. There you can directly see how CPLEX solution statuses are mapped to exitflag values.
#CPLEXOptimizers
#DecisionOptimization

Originally posted by: RayZ

It's a year later and ran into this problem again ... and I still haven't been able to find any complete listing of the possible exitflag values for cplexlp() or cplexqp(). A value of 5 is not included in the documentation for the standard Matlab toolbox functions, and the *.m files in the CPLEX distribution do not contain the actual implementations (those are in the *.p files), so I wasn't able to find any help there either.

I have a wrapper function from which I need to return a simple success flag. I was using a simple exitflag > 0 condition to define success, but it seems when the exitflag is 5 the solution can be infeasible. I just need to know if there are other positive values of exitflag that I should consider as unsuccessful.

#CPLEXOptimizers
#DecisionOptimization

exitflag=5 means 'Solution with numerical issues'. You should be able to see that my looking at the 'message' field of the 'output' output argument.

'Solution with numerical issues' may well mean that the solution is infeasible for the problem. You can get this status for example if CPLEX automatically scales your problem, finds a solution for the scaled problem but also finds that after unscaling the solution it turns out to be infeasible for the original problem.

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: RayZ

Thanks, but this doesn't really solve my problem. The issue is not with determining the reason for some undocumented positive value of exitflag for which I have an example. As I mentioned in earlier posts, there is the cplexstatus field (or message field, etc.) that I can use to track down the reason, if I have an example in hand. The issue is that this list of possible values does not seem to be documented anywhere, so I don't know how to write my wrapper code.

According to the documentation, if exitflag is positive, I should be able to assume the solution is fine. But I discovered by experience that exitflag can be 5 and the solution is not fine. So, my real question is, are there other undocumented positive values of exitflag that can be returned that I should be checking for?

Unfortunately, since it isn't documented anywhere and the source code isn't available, the best I can do is raise some kind of warning if an undocumented value is returned, to let my users know that their solution may or may not be good. I consider this to be a bug in my code that I can't fix without complete exitflag documentation from CPLEX.

#CPLEXOptimizers
#DecisionOptimization

Hm, functions like fmincon (which I think is kind of similar to cplexacp()) document an exit flag value of 5. So it is not completely undocumented. We will still try to improve our documentation.

In general exit flags follow the "philosophy" outlined here: An exitflag>0 means that a solution is available. The smaller the exitflag, the higher the quality of the solution. exitflag=5 means that there are some tolerance or scaling problems with the solution that CPLEX found.

CPLEX may also terminate with exitflag=6 if it found a feasible solution but hit a limit (node, time, memory, ... limit).

it might be better to check the CPLEX status code instead of the more general exitflag. Status codes carry more information than exitflag and therefore allow to make better decisions.

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: Mark L. Stone

Is the CPLEX status code only available form the C API?  Is there any way of getting this info from MATLAB Toolbox functions?  If not, why not?

I'm thinking of a scenario in which MATLAB Toolbox functions are called as part of some larger algorithm I write, in which, perhaps similar to RayZ, the more detailed information I can have on function outcome, the better, in terms of supporting the higher level algorithm.

#CPLEXOptimizers
#DecisionOptimization

Replying only to the first question. Maybe you can delete the duplicate posts?

• C API: CPXXgetstat()
• matlab
  • Toolbox functions: see the output.cplexstatus field in the reference documentation for the various toolbox functions
  • Class API: see the Solution.status field of the Cplex class.

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: Mark L. Stone

Sorry about all the now deleted duplicate posts.  They occurred due to a poorly implemented "exitflag" for the posting (save button) function, in which the exitflag appeared to indicate failure, and indeed posts did not show up until later.

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: RayZ

Thanks. The description of the "philosophy" is helpful. And yes, I do eventually plan to switch to the object interface where I'd be using the status codes directly. Just wondering, is there a corresponding "philosophy" for the numerical status codes? I couldn't discern any.

#CPLEXOptimizers
#DecisionOptimization

No, there is no such "philosophy" for the CPLEX status codes. Many of them are historical and several were added only later.

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: Mark L. Stone

12.6.1 still doesn't seem to provide documentation of possible exitflag values.  Is it safe to assume that if cplexqp returns a positive exitflag value other than 5, that the solution is feasible (even if not necessarily optimal)? 

The context for this is calling cplexqp within an outer algorithm, so no human is there to interpret the results in a non-automated way.  Alternatively, if I knew all possible numerical values for output.cplexstatus which could correspond to an infeasible solution, or all possible text values for output.cplexstatusstring which could correspond to an infeasible solution, that would work as well.  Basically, I want the calling algorithm to know whether or not a feasible solution has been returned (even if it may not be optimal).

I am currently assuming that if exitflag is positive and not equal to 5, that I have a usable (feasible) solution.

exitflag can also return 'Unknown status', which seems to be what I get with solutiontarget = 2 when an indefinite QP is solved, and  it has output.cplexstatus = 24 and output.cplexstatusstring =  'satisfies first order optimality conditions'.  When a convex QP is solved (also with solutiontarget = 2), I seem to get exitflag = 1, with output.cplexstatus = 1 and output.cplexstatusstring =  ''optimal'.  What are the possible reasons for 'Unknown status'?  Am I safe in assuming that exitflag = 'Unknown status' returns a solution which is feasible?

It seems to me that satisfying first order optimal conditions for a non-convex QP should merit a "better" exitflag value than 'Unknown status'.

 

Thanks.

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: RWunderling

The documentation of the exitflag values can be found here: http://www-01.ibm.com/support/knowledgecenter/SSSA5P_12.6.1/ilog.odms.cplex.help/refmatlabcplex/html/cplexmiqcp-m.html?lang=en
You already found the preferred way of getting more specific information about the solution via output.cplexstatus, which provides the most detailled information available.  We will consider a better exitflag for a first-order solution status; thanks for pointing this out.

Roland

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: Mark L. Stone

Roland,

 

Thanks for the link.  I suggest that exitflag values should be documented for each MATLAB toolbox function (or at least a link provided).

The exitflag table in the link is not complete, and therefore inadequate, since it does not contain 'Unknown status'. Since this appears to be the "best" exitflag value available in the case of a non-convex problem (for cplexqp anyhow, as I haven't tried cplexmiqcp), it's not even just an obscure case (such as a catch all code for some crazy thing which happened which the developers could never have anticipated).

Maybe you could have something like exitflag = 1 for provably globally optimal solution, and exitflag = 2 for "satisfies first order optimality conditions".

 

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: RWunderling

I see a link in the other toolbox functions near the end of a page in a line such as:

See cplexmiqcp for a description of exitflag values.

See for example: http://www-01.ibm.com/support/knowledgecenter/SSSA5P_12.6.1/ilog.odms.cplex.help/refmatlabcplex/html/cplexqcp-m.html?lang=en

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: Mark L. Stone

Roland, right you are. Somehow I missed that link - senior moment perhaps.  But my critique of the exitflag 'Unknown status' for finding first order optimal solution of a non-convex QP stands, and that 'Unknown status' is not listed in the list of exitflag values.

#CPLEXOptimizers
#DecisionOptimization

Originally posted by: RWunderling

Indeed.  Let me reiterate my thanks for pointing this out.

#CPLEXOptimizers
#DecisionOptimization