Stan's machine-readable return types (as opposed to its free-form messages) conflict.

Summary:

Stan defines machine-readable return types (error codes, exceptions, ....??) in a variety of places and they don't necessarily agree.

Description:

1. [stan::services::error_codes](

namespace stan {
  namespace services {

    struct error_codes {
      // defining error codes to follow FreeBSD sysexits conventions
      // http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=sysexits
      enum {
        OK = 0,
        USAGE = 64,
        DATAERR = 65,
        NOINPUT = 66,
        SOFTWARE = 70,
        CONFIG = 78
      };
    };
  }

2. (stan::optimization::TerminationCondition)[https://github.com/stan-dev/stan/blob/develop/src/stan/optimization/bfgs.hpp]

namespace stan {
  namespace optimization {
    typedef enum {
      TERM_SUCCESS = 0,
      TERM_ABSX = 10,
      TERM_ABSF = 20,
      TERM_RELF = 21,
      TERM_ABSGRAD = 30,
      TERM_RELGRAD = 31,
      TERM_MAXIT = 40,
      TERM_LSFAIL = -1
    } TerminationCondition;

3. The stan::mcmc code seems to use exceptions not error codes.
4. stan::variational seems to use free-form messages (?) and some stan::services::errror_codes.

Expected Output:

Writing a suggestion below but I'd be fine with a variety of solutions. We could just always return 0 and throw on all clear errors. Figuring out if the output is good enough to use is a little more advanced than typical error codes should be used to classify.

• Return codes are fine for typical operation (the output may be useful) and exceptions for atypical conditions (output probably not what you were looking for, no clear way for the algorithm to continue).
• We should define return codes in one place stan::services::return_codes or similar. We should not standardize on FreeBSD sysexits conventions (as stan::services::error_codes currently does) since those conventions are for command-line programs and they understandably do not cover the variety of possible return conditions Stan produces.
• Return codes should be kept in a single file (so they don't conflict) but they should be algorithm-specific. I'd be fine with something simple like saving 0XX for later use, 1XX for optimization, 2XX for NUTS, 3XX for NUTS with adaptation, 4XX for HMC, 5XX for variational inference, something like that. If you plan on having more than 99 error codes for one algorithm you're doing it wrong.
• There should only be a few return codes per algorithm, stan::optimization seems to get this right (?)
• It would be fine to continue to provide stan::services::error_codes following FreeBSD sysexit conventions for command-line programs written with stan but that's a separate issue.
• optimization should throw for the case currently handled by TERM_LSFAIL (line search failed) and generally be changed to use exceptions for error.

Current Version:

v2.14.0

Compare stan::services::error_codes with stan::optimization::TerminationCondition in src/stan/optimization/bfgs.hpp, then inspect the mentioned stan::mcmc and stan::variational paths. The issue proposes several incompatible return-code and exception strategies, so first establish the intended design; done would mean the affected components use an agreed, non-conflicting convention.