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

[bbbales2]

that it has now changed and instead a new initial point is drawn?

Yeah so that change is here:

https://github.com/stan-dev/math/pull/1891

So instead of throwing an error that stops the program, it now throws an error that is recoverable (and then whatever stage errors there will try to recover however it recovers)

[jtimonen]

Ok, so I didn't realize that it's possible to recover after an error. Anyway, I would like to understand what the rules are how to recover.

[yizhang-yiz]

I would like to understand what the rules are how to recover.

I'd like to know that too. In particular, why we only catch "TOO_MUCH_WORK" flag(there's many other error flags and this one is not even the one I encounter most)? And why this change was made in variadic ODE PR? Does "flag -1" affect the variadic interface? I can't think of any reason. @bbbales2 @wds15

[bbbales2]

why we only catch "TOO_MUCH_WORK" flag

Yeah so you mean catching other flags and making the error messages here more informative? I'd like that for sure.

And why this change was made in variadic ODE PR?

This change was separate from the variadic ODEs I think: https://github.com/stan-dev/math/pull/1891, or is there a different thing?

[yizhang-yiz]

This change was separate from the variadic ODEs I think: stan-dev/math#1891, or is there a different thing?

@wds15 made comment that the improved error message was made in variadic PR. I wonder why there.

[bbbales2]

Oh. I forget what those were, but it doesn't seem impossible we improved some but not all. More improvement good though, especially in terms of getting informative ODE errors.