@@ -181,29 +181,23 @@ class CheckLossConvergence(Callback):
181181 Allowance per step, in units of the scale that standardizes ``delta``. Must
182182 exceed what a stalled trace spends on noise alone (0.3 to 0.4); see Notes.
183183 h : float
184- CUSUM decision threshold. Larger values trade detection delay for a
185- lower false-alarm rate.
184+ CUSUM decision threshold, trading detection delay against false alarms.
186185 halflife : float
187186 Half-life, in steps, of the exponentially-weighted scale estimate.
188187 min_steps : int
189- Number of steps before the CUSUM is armed. Must be large enough for
190- the scale estimate to stabilize (a few half-lives). Also the number of
191- consecutive non-finite losses tolerated before the fit is stopped:
188+ Steps before the CUSUM is armed; needs a few half-lives for the scale to
189+ settle. Also the number of consecutive non-finite losses tolerated:
192190 ``pm.fit`` aborts on NaN but runs to completion on ``+inf``.
193191
194192 Notes
195193 -----
196- The defaults fix a *rate*: the per-step improvement of the loss over its per-step
197- noise sd. A fit improving more slowly than that is stopped however long it would
198- have gone on improving, so the figures below hold at a stated rate, not in general.
199-
194+ The defaults fix a *rate*, the per-step improvement over the per-step noise sd, so
195+ a fit improving more slowly is stopped however long it would have kept improving.
200196 Calibrated on 1000 traces per cell of ``loss[t] = f(t) + sigma[t] * eps[t]``, 6000
201- steps, in four families -- linear, power law, alternating ``sigma``, and Student-t
202- noise with ``df=3``. At a rate of 1.0 the defaults stopped none of the 4000
203- still-improving traces; the stall boundary sits between 0.6 and 0.7, and ``kappa``
204- is what moves it. On the same families frozen to a plateau after improving at a
205- rate of 1.0, every trace was stopped and none before the plateau, with median
206- delays of 25 to 54 steps and p95 at most 86.
197+ steps, four families (linear, power law, alternating ``sigma``, Student-t ``df=3``):
198+ at rate 1.0 none of the 4000 still-improving traces stopped, the stall boundary sits
199+ between 0.6 and 0.7, and ``kappa`` moves it. Frozen to a plateau after improving at
200+ rate 1.0, every trace stopped, none early, median delay 25 to 54 steps, p95 at most 86.
207201
208202 Examples
209203 --------
@@ -213,19 +207,15 @@ class CheckLossConvergence(Callback):
213207 approx = pm.fit(100_000, callbacks=[monitor]) # stops early if converged
214208 """
215209
216- # Scales mean |successive difference| into the standardizer for delta. The z it
217- # produces is unit-variance only when the loss increments are independent , so kappa
218- # and h are calibrated against it as it stands rather than derived from it.
210+ # Scales mean |successive difference| into the standardizer for delta. Its z is
211+ # unit-variance only for independent increments, so kappa and h are calibrated
212+ # against it as it stands rather than derived from it.
219213 _SCALE_TO_SIGMA = float (np .sqrt (np .pi ) / 2.0 )
220214 # Winsorization bound on z, applied to the scale update too so one spike cannot
221215 # inflate the scale for hundreds of steps.
222216 _Z_CLIP = 4.0
223- # Additive floor on the standardizing scale: an exactly-constant stretch of loss
224- # drives the successive-difference scale to zero, and dividing by it raises. A divide
225- # guard, not a tuning knob -- the counterpart of the eps in `relative` above, and no
226- # more a constructor parameter than that one is. It is inert until the per-step
227- # increments fall below about 1e-9, so a caller cannot improve on it without first
228- # having rescaled the objective; one that must can override it in a subclass.
217+ # Divide guard, not a knob: an exactly-constant stretch of loss drives the
218+ # successive-difference scale to zero, and dividing by it raises.
229219 _SIGMA_FLOOR = 1e-12
230220
231221 def __init__ (self , kappa = 0.5 , h = 10.0 , halflife = 200.0 , min_steps = 1000 ):
0 commit comments