JuliaOpt/Optim.jl — pull request #87 by johnmyleswhite (2014-10-28 16:30:13+00:00)
Title: [WIP] Official API for interacting with optimization results objects

This is a _very_ rough attempt to create an official API of functions that can be used to interact with the results objects returned by `optimize`. I do not like this API much, so I'm creating a WIP issue to elicit some bikeshedding.

Below I list all of the functions in the API while describing both their intent and my view about what's wrong with the names. Checked boxes are those which I think are settled for by existing arguments.

* [ ] `abs_tol`: What was the tolerance of a univariate optimization algorithm in absolute terms? I personally do not like this API and would prefer that we offer something more like `x_tol` (with relative and absolute versions). I'm not sure how hard it would be to change the code we're using, but I'd definitely prefer keeping the exact same interface for univariate and multivariate optimization.
* [ ] `Base.minimum`: The discovered minimum value of the function being minimized. This name matches precedence in the field, although it's a break from our previous names for the internal fields of the results objects.
* [ ] `f_calls`: How many times was the function being minimized called during the algorithm's execution?
* [ ] `f_converged`: Was the algorithm terminated because the values of the function stopped changing by `ftol`?
* [ ] `ftol`: How close must successive function values be to assert that the function converged?
* [ ] `g_calls`: How many times was the gradient of the function being minimized called during the algorithm's execution?
* [ ] `gr_converged`: Was the algorithm terminated because the max-norm of the gradient stopped changing by `grtol`?
* [ ] `grtol`: How close must successive max-norms of the gradient be to assert that the function converged?
* [ ] `history`: Obtain a tracing history of the algorithm's execution if this was requested during execution.
* [ ] `initial_state`: What the starting point of the algorithm?
* [ ] `isconverged`: Did the algorithm converge under any definition?
* [ ] `iteration_converged`: Did the algorithm terminate because it exceeded the maximum allowed number of iterations?
* [ ] `iterations`: How many iterations were completed when the algorithm was terminated?
* [ ] `lower_bound`: For univariate optimization problems, the user must provide a lower bound on the minimizer. This is that user-provided lower bound.
* [ ] `method`: Which algorithm was used to minimize the function?
* [ ] `minimizer`: What is the state at which the function's discovered minimum occurred?
* [ ] `rel_tol`: A relative tolerance on changes in the state of a univariate optimization algorithm. Would like to replace this one along with `abs_tol` or at least make them more separable.
* [ ] `upper_bound`: For univariate optimization problems, the user must provide a upper bound on the minimizer. This is that user-provided upper bound.
* [ ] `x_converged`: Did the algorithm terminate because the state stopped changing by `xtol`?
* [ ] `xtol`: What is the max-norm of the difference between successive states at which the algorithm will terminate?

Closes #76.