Warmup and Adaptation in HMC

Why HMC Needs Warmup

Hamiltonian Monte Carlo (HMC) uses gradients to propose long-distance moves through a posterior distribution. The proposal’s behavior depends on tuning choices, especially the step size and the mass matrix. Poor choices can make exploration inefficient: a step size that is too large can produce inaccurate integration, while an unsuitable mass matrix can leave differently scaled parameters difficult to explore together. Warmup is the period in which a sampler tunes such choices for the model and data at hand.

This matters particularly in hierarchical nonlinear mixed-effects (NLME) models. Population parameters, residual-error parameters, and individual random effects can have very different scales and strong posterior dependencies. The posterior geometry may also depend on the model’s parameterization. The earlier material on centered and noncentered parameterizations and on posterior geometry provides useful context: warmup can adapt to the geometry presented to the sampler, but it does not make every parameterization equally easy to sample.

Definition: Warmup is the initial part of an HMC run used to initialize and adapt sampler settings, such as the step size and mass matrix. Warmup draws are the states visited during this period. They are generally not retained as posterior draws because the sampling procedure is changing while adaptation occurs. Post-warmup draws are generated after adaptation has stopped and the sampling settings have been fixed.

Warmup is not simply a set number of early draws that can be assumed to have reached the posterior. Its key operational distinction is adaptation: during warmup, the transition mechanism may change as the sampler updates its tuning values. In post-warmup sampling, those values are held fixed. Even then, fixed settings alone do not establish that the chain has adequately explored the posterior; assessing chains and their draws requires additional diagnostics.

Two Main Adaptation Tasks

Use \(q\) for the vector of model parameters expressed on the scale sampled by HMC, and \(p\) for its momentum. In the convention used here, the kinetic energy is \(K(p)=\frac{1}{2}p^\mathsf{T}M^{-1}p\), with momentum drawn from a normal distribution with covariance \(M\). The step size controls the spacing of numerical integration steps; the mass matrix \(M\) controls how momentum and movement in parameter space are scaled.

Step-size adaptation seeks a step size that allows efficient integration while keeping numerical error and rejection at acceptable levels. A larger step size usually requires fewer integration steps for a given path length, but it can make the numerical approximation less accurate. A smaller step size can improve accuracy, but may require more steps and more computation. The desired acceptance probability is a tuning target, not an estimate of a posterior probability or a guarantee of efficiency.

Mass-matrix adaptation estimates aspects of the posterior’s scale and dependence so that movement is better scaled across parameters. In the convention above, if a locally Gaussian posterior has covariance \(\Sigma\), an idealized choice is \(M\) proportional to \(\Sigma^{-1}\). Some software reports or adapts an inverse mass matrix, so it is important to check the convention rather than infer the meaning from the word “metric” alone.

q \sim N(\mu,\Sigma), \qquad \ddot q = -M^{-1}\Sigma^{-1}(q-\mu).

The equation gives a short justification for the scaling goal. If \(M=\Sigma^{-1}\), then \(M^{-1}\Sigma^{-1}=I\), so the idealized Gaussian dynamics have the same frequency in every direction. If the posterior has different scales or correlated directions, a mass matrix that does not account for them can produce uneven movement. This argument is local and Gaussian: real NLME posteriors need not have one covariance matrix that works equally well throughout the parameter space.

Phases and Windows in Warmup

Many HMC implementations organize warmup into an initial period, a sequence of adaptation windows, and a final period. The exact schedule and update rules vary by software and configuration; the phase structure is a useful design pattern, not a universal mathematical requirement.

Initial or fast adaptation.
The sampler finds a workable initial step size. This helps avoid spending later adaptation on a step size that is grossly inappropriate for the current parameter scaling.

Slow adaptation windows.
The sampler gathers information across windows to estimate parameter scales and dependence for the mass matrix. Windowing gives each estimate a set of draws and allows later windows to update the estimate as sampling improves.

Final or fast adaptation.
After the mass matrix is updated, the sampler retunes the step size for the resulting integration geometry. This is useful because changing the mass matrix can change which step sizes work well.

A covariance estimate based on too few draws can be noisy or nearly singular, especially in a high-dimensional model. Windows are therefore not just administrative divisions: they help balance the need for enough information to estimate geometry against the desire to adapt during a finite warmup. Some implementations use regularization or other safeguards when estimating a metric. These details, and the schedule itself, are implementation-specific.

A user may set the total warmup length and, in some software, control or inspect phase lengths. More warmup provides more opportunity to learn the geometry, but does not guarantee success. Increasing it cannot by itself fix an ill-identified model, a poor parameterization, or a posterior with difficult curved geometry. Nor should the final sampling period continue adapting in a way that changes the transition kernel while the retained draws are being treated as draws from one fixed sampling procedure.

Worked Example: Reading a Warmup Schedule

Suppose a hypothetical NLME fit is configured with 1,000 warmup iterations. Its documentation describes 100 iterations of initial adaptation, then mass-matrix estimation in windows totaling 800 iterations, followed by 100 iterations of final step-size adaptation. Explain which iterations provide posterior draws.

The first 100 iterations are used for initial adaptation. The next 800 provide information for mass-matrix estimation across windows. The final 100 tune the step size after the mass-matrix updates. Therefore, all \(1{,}000\) iterations are warmup iterations; none of them should be counted as retained post-warmup draws under this setup. If the fit then runs 2,000 iterations with adaptation fixed, those 2,000 iterations are the post-warmup draws available for subsequent assessment and analysis.

The schedule’s arithmetic is \(100+800+100=1{,}000\). It is a hypothetical configuration, not a recommended default. Whether it is adequate depends on the model’s dimension, scaling, parameterization, and observed adaptation behavior.

Worked Adaptation Examples

Worked Example: Interpreting a Step-Size Update

Consider a hypothetical warmup iteration at which the current step size is \(0.020\), and the observed acceptance statistic is \(0.55\). Suppose the target acceptance probability is \(0.80\). What does this comparison suggest?

The acceptance statistic is below the target by \(0.80-0.55=0.25\). In a typical dual-averaging adaptation scheme, repeated acceptance statistics below the target lead the procedure to reduce the step size, making numerical integration more conservative. The exact next step size cannot be calculated from these three numbers alone: it depends on the adaptation algorithm’s accumulated history and tuning constants.

If subsequent proposals are accepted at a higher rate, that does not prove the fit is satisfactory. The target is one tuning criterion; it does not establish that the chain has explored all relevant posterior regions or that the model is well identified.

Worked Example: A Two-Parameter Mass-Matrix Estimate

Suppose a hypothetical warmup window gives the following estimated covariance for two scaled parameters \(q_1\) and \(q_2\):

\widehat{\Sigma} = \begin{pmatrix} 4.00 & 1.20\\ 1.20 & 1.00 \end{pmatrix}.

Under the convention \(K(p)=\frac{1}{2}p^\mathsf{T}M^{-1}p\), a Gaussian-based mass-matrix estimate is proportional to the inverse of this covariance. The determinant is \(4.00(1.00)-(1.20)^2=2.56\), so

\widehat{M} = \widehat{\Sigma}^{-1} = \frac{1}{2.56} \begin{pmatrix} 1.00 & -1.20\\ -1.20 & 4.00 \end{pmatrix} = \begin{pmatrix} 0.3906 & -0.4688\\ -0.4688 & 1.563 \end{pmatrix}.

The negative off-diagonal entries reflect the inverse-covariance scaling; they are not evidence that the covariance estimate had a negative correlation. Here the original covariance estimate is positive definite because its first diagonal entry is positive and its determinant, \(2.56\), is positive. If an estimate were singular or not positive definite, its inverse would not be a valid mass matrix under this calculation; in practice, the implementation would need a safeguard or the geometry would need investigation.

Choosing Warmup for Hierarchical NLME Models

Warmup settings should reflect the parameterization and the demands of the model, rather than being chosen from the number of observations alone. For example, a model with many subjects may have a large collection of individual random effects, while population-level parameters and residual-error parameters may occupy quite different scales. A diagonal mass matrix can address marginal scale differences but does not represent all cross-parameter dependence. A dense matrix can represent linear correlations, but estimating it reliably can require substantial information and computational effort.

A practical choice is to begin with a warmup length that gives enough room for the implementation’s step-size adaptation, metric estimation, and final retuning. More complex or higher-dimensional hierarchical models may need longer windows than a small, well-scaled model. If the model uses a difficult parameterization or the metric estimate appears unstable, revisit model scaling and parameterization as well as increasing warmup. Longer warmup is not a substitute for resolving fundamental modeling or identification problems.

Choose the desired acceptance target with the cost-accuracy tradeoff in mind. A higher target often encourages a smaller step size and more accurate integration, which can require more computation. A lower target may allow larger steps, but does not guarantee efficiency. Use the software’s documented controls and inspect its adaptation summaries; do not assume that the same numeric setting has the same interpretation across implementations.

Assessing Adaptation and Avoiding Common Errors

Useful adaptation checks include whether step-size updates settle rather than moving erratically, whether the estimated metric is numerically usable, and whether the final settings are plausible for the model’s scale. An unusually small step size, repeated rejection, or an unstable metric estimate can indicate that the sampler is struggling. These are prompts to investigate, not standalone proofs of a particular cause. Check parameter scales, model structure, parameterization, and the implementation’s warnings. Warmup summaries should be interpreted alongside later chain diagnostics; they do not replace them.

Counting adaptation draws as posterior draws. The wrong reasoning is that a draw is a posterior draw merely because it was generated by HMC. During warmup, settings can change, so exclude those draws from posterior summaries under the usual workflow.
Assuming more warmup always solves sampling problems. Extra iterations can improve estimates of scales, but cannot guarantee resolution of poor identification or difficult geometry. Investigate the model and parameterization too.
Confusing the covariance and mass-matrix conventions. Under the convention used here, a Gaussian target covariance \(\Sigma\) corresponds to \(M\) proportional to \(\Sigma^{-1}\). Software that reports an inverse metric may present the corresponding covariance-like quantity instead.
Treating the target acceptance as a quality certificate. Meeting a target does not establish adequate exploration or reliable inference. It describes one aspect of sampler tuning only.

Step-size-only adaptation is simpler and may be adequate when parameters are already well scaled, but it cannot learn a multivariate metric. Mass-matrix adaptation can improve scaling and linear dependence, at the cost of estimating more quantities and potentially needing more warmup. Neither is a replacement for thoughtful parameterization or later assessment of the resulting chains.

Key takeaway: Warmup tunes the HMC transition settings; it is not the posterior sample. Step-size adaptation targets integration behavior, while mass-matrix adaptation targets parameter scaling and dependence. Freeze the adapted settings before retaining draws, and treat successful adaptation as necessary preparation rather than proof of reliable inference.

Check Your Understanding

Try each question, then check the solutions below.

A run has 700 warmup iterations and 1,500 iterations after adaptation is fixed. How many iterations are post-warmup draws?
Under the convention in this tutorial, a Gaussian posterior has covariance \(\Sigma\). What mass matrix is suggested by the Gaussian scaling argument?
A warmup procedure repeatedly observes acceptance statistics below its target. What adjustment would typically follow, and why?
A high-dimensional NLME model has an unstable covariance estimate in one adaptation window. Give two reasonable responses and one response that is not guaranteed to solve the problem.

Solutions. (1) There are 1,500 post-warmup iterations; the 700 warmup iterations are not included. (2) The suggested choice is \(M\) proportional to \(\Sigma^{-1}\), given \(K(p)=\frac{1}{2}p^\mathsf{T}M^{-1}p\). (3) A typical dual-averaging scheme reduces the step size, because smaller integration steps tend to reduce numerical error and increase acceptance. (4) Reasonable responses include allowing more information to accumulate in the windows, checking scaling and parameterization, and using the implementation’s documented regularization or metric options. Simply adding warmup is not guaranteed to fix the problem if the model has poor identification or difficult geometry.

What You'll Learn