Optimization return code is misleading

Summary:

In do_bfgs_optimize, the return code is still positive even if the algorithm stops because it reaches max iterations. That leads stan to return stan::servicse::error_codes::OK even though the algorithm did not meet stopping criteria. I don't think this is necessarily wrong but it is misleading.

Description:

The return code (ret below) will be positive even if the algorithm terminates because it reaches max iterations. I don't think Stan should treat that the same as meeting convergence diagnostics. Relevant snippet from do_bfgs.hpp:

        if (ret >= 0) {
          info("Optimization terminated normally: ");
          return_code = stan::services::error_codes::OK;
        } else {
          info("Optimization terminated with error: ");
          return_code = stan::services::error_codes::SOFTWARE;
        }
info("  " + bfgs.get_code_string(ret));

Reproducible Steps:

It's pretty clear from the code. Did not try to make an example. Probably a model like the following would do it.

parameters {
  real x;
}
model {
  target += log(x);
}

Current Output:

The message that the algorithm terminated because it reached max iterations is only written on a side-channel ("info"), the Stan return value is still stan::services::error_codes::OK

Expected Output:

Terminating because the algorithm runs out of iterations should give some return value other than "OK"

Current Version:

v2.14.0

Start in do_bfgs.hpp at do_bfgs_optimize and trace how ret is converted into Stan's error_codes::OK or SOFTWARE when maximum iterations are reached. Reproduce the shown optimization scenario if useful, then verify that termination from exhausting iterations produces a non-OK return value rather than being treated as successful convergence.