Skip to content

Commit 231bd9a

Browse files
Cut the class docstring and two comments down to their point
CheckLossConvergence carried a 56-line docstring next to a 20-line CheckParametersConvergence and a 31-line Tracker. The parameter entries and the calibration paragraph say the same things in fewer words, and the sigma_floor comment argued its own case for six lines when one states it. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent d6164a4 commit 231bd9a

1 file changed

Lines changed: 14 additions & 24 deletions

File tree

pymc/variational/callbacks.py

Lines changed: 14 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)