From 96f73faeff33b30d4871f02eb33e16cc2a60366e Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Wed, 6 May 2026 17:02:51 -0400 Subject: [PATCH] Document new `converged__` column in optimization --- src/cmdstan-guide/optimize_config.qmd | 47 +++++++++++++++++++-------- 1 file changed, 34 insertions(+), 13 deletions(-) diff --git a/src/cmdstan-guide/optimize_config.qmd b/src/cmdstan-guide/optimize_config.qmd index 76d33069b..b00949ba1 100644 --- a/src/cmdstan-guide/optimize_config.qmd +++ b/src/cmdstan-guide/optimize_config.qmd @@ -113,16 +113,16 @@ Following the config information are two lines of output, the CSV headers and the recorded values: ``` -lp__,theta --5.00402,0.200003 +lp__,converged__,theta +-5.00402,31,0.200003 ``` Note that everything is a comment other than a line for the header, and a line for the values. Here, the header indicates the unnormalized -log probability with `lp__` and the model parameter -`theta`. The maximum log probability is -5.0 and the posterior -mode for `theta` is 0.20. The mode exactly matches what we would -expect from the data. +log probability with `lp__`, algorithm status in `converged__`, +and the model parameter `theta`. The maximum log probability is -5.0 +and the posterior mode for `theta` is 0.20. The mode exactly matches what +we would expect from the data. Because the prior was uniform, the result 0.20 represents the maximum likelihood estimate (MLE) for the very simple Bernoulli model. Note that no uncertainty is reported. @@ -141,15 +141,36 @@ Running the example model with option `save_iterations=true`, i.e., the command ``` produces CSV file output rows: ``` -lp__,theta --6.85653,0.493689 --6.10128,0.420936 --5.02953,0.22956 --5.00517,0.206107 --5.00403,0.200299 --5.00402,0.200003 +lp__,converged__,theta +-6.85653,0,0.493689 +-6.10128,0,0.420936 +-5.02953,0,0.22956 +-5.00517,0,0.206107 +-5.00403,0,0.200299 +-5.00402,31,0.200003 ``` +## Meaning of the `converged__` column + +The `converged__` column is used to indicate the status of the algorithm. It can +take on the following values. + +| Numeric value | Meaning | +|---------------|-----------------------------------------------------------------------------------| +| -1 | Line search failed to achieve a sufficient decrease, no more progress can be made | +| 0 | Successful step completed | +| 10 | Convergence detected: absolute parameter change was below tolerance | +| 20 | Convergence detected: absolute change in objective function was below tolerance | +| 21 | Convergence detected: relative change in objective function was below tolerance | +| 30 | Convergence detected: gradient norm is below tolerance | +| 31 | Convergence detected: relative gradient magnitude is below tolerance | +| 40 | Maximum number of iterations hit, may not be at an optima | + +Note that not all algorithms can produce all codes, and some, such as `0`, will +only be observed if `save_iterations` is used. + +A comment explaining the final value (with the same contents as the above table) +is added at the end of the CSV file. ## Jacobian adjustments