we’ve been discussing better names for some of the CmdStan sampler arguments here: add logic to `sample` function to handle dense HMC metric · Issue #28 · stan-dev/cmdstanpy · GitHub
the warmup epochs are described here: 14.2 HMC Algorithm Parameters | Stan Reference Manual
and in the “Adaptation Parameters Table” (same section).
these parameters are currently specified as number of iterations, and the total should be less than or equal to the specified number of warmup iterations. under CmdStan’s default of 1000 warmup iterations, the defaults will match the diagram because phase I “init_buffer” is 75 iterations, phase II “window” is 25 + 50 + 100 + 200 + 400 iterations (a series of expanding windows) and phase III “term_buffer” is 50 iterations.
It’s difficult to see from the name “window” and default value 25 that actually most of the time during adaptation is spent tuning the metric.
If these numbers don’t add up, the sampler logger message says:
Reducing each adaptation stage to 15%/75%/10% the given number of warmup iterations
I think that this formulation is more in line with how a user sees the problem - as pct of warmup iterations spent in each phase, and so I’d like to propose that the CmdStanPy sample function takes a parameter named warmup_adapt (or?) which takes of triple of pcts which sum to <= , or else a trio of parameters “warmup_phase_1”, or “adapt_phase_1” … “phase_3” where the user can specify 2 out of 3 of them.
CmdStanPy’s argument parser will translate percentages into iterations, given the specified number of warmup iterations.
Your feedback welcome!