Improve ODE max_num_steps parameter documentation

[jtimonen]

Summary:

The max_num_steps parameter for ODE solvers and how to set it could be explained more exactly.

Description:

Documentation (Section 13.6) says "… and max_num_steps specifies the maximum number of steps the solver will take between output time points before throwing an error" and “The maximum number of steps can be used to stop a runaway simulation.”

• I think it’s misleading to talk about throwing an error or stopping a simulation, since this doesn't stop a chain, instead it prints the message

Chain 4 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
Chain 4 Exception: Exception: integrate_ode_rk45:  Failed to integrate to next output time (1) in less than max_num_steps steps

at least during warmup. If max_num_steps is reached during sampling, then it seems to be marked as a divergence, and sometimes if I set max_num_steps to a ridiculously low value, I can get Warning: Chain 4 finished unexpectedly!.

• In general, this is confusing and I would really like know what actually happens if max_num_steps is reached, and does it depend on whether the chain is doing warmup or sampling. Or in what case does it just reject and try a new proposal, and when does it actually stop a chain and when mark it as divergence.

• In some earlier version of Stan, an error was actually thrown if max_num_steps was reached when trying to compute log probability for the initial parameter values, but I think @bbbales2 told me that it has now changed and instead a new initial point is drawn?

Additional Information:

See my Discourse post .

Current Version:

v2.25