lockkernel 1.1.1__tar.gz → 1.3.0__tar.gz

{lockkernel-1.1.1/src/lockkernel.egg-info → lockkernel-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lockkernel
-Version: 1.1.1
+Version: 1.3.0
 Summary: Locking kernel universality: exact thresholds and exponents of synchronization transitions, and fits of measured branches with error bars and refusals
 Author: Tanvir Mahmud Mahim
 License: Apache-2.0
@@ -59,10 +59,13 @@ The collective motion must be the one the oscillators themselves
 produce (the "self-consistency condition"); one substitution turns
 that condition into an exact formula (a "parametric solution") valid
 for any frequency spread and any kernel. The exponent depends only on how fast the kernel falls off
-far from the centre (its **tail**). The **lab half** (`lockkernel.measured`)
+far from the center (its **tail**). The **lab half** (`lockkernel.measured`)
 works the other way round: it fits measured points for the threshold
 and the exponent, reads the kernel's tail back off the exponent, and
-plans how many points a target error bar costs. When the data cannot
+plans how many points a target error bar costs. It also tests whether
+the data are consistent with the power law at their stated noise, and
+carries the uncertainties of the measured couplings and of calibration
+scales into the error bars. When the data cannot
 support the number asked for, it stops with an error message that says
 why, rather than returning a number that looks fine but is not.
 
@@ -119,7 +122,12 @@ why, rather than returning a number that looks fine but is not.
   `beta = 1/(s-1)` for `1 < s < 3` and `beta = 1/2` for `s >= 3` or
   for a kernel with no algebraic tail. So a measured `beta` above 1/2
   names the tail, `s = 1 + 1/beta`, while `beta = 1/2` only says
-  "`s >= 3`" and cannot name one value.
+  "`s >= 3`" and cannot name one value. The value 1/2 needs a line
+  with a rounded top at its centre (`p''(0) < 0`, true for every
+  shipped line except `box`). On a line that is flat at the centre,
+  such as `box`, a tail gives `beta = 1/(s-1)` for every `s > 1`
+  (so below 1/2 once `s > 3`), and a kernel with no tail gives a jump
+  instead of a power law (see [Limits](#limits)).
 - **Order of the onset** -- for the conservative kernel, the sign of
   one number `c` (an integral over the line shape) decides it:
   `c > 0` gives a smooth (continuous) onset, `c < 0` a jump with
@@ -144,7 +152,10 @@ and mpmath 1.2 or newer, and nothing else.
 - **Precision.** The theory half (`parametric`, `kernels`,
   `lineshapes`) works in mpmath's arbitrary precision and returns
   mpmath numbers. Set the working precision with `mpmath.mp.dps`
-  (decimal digits). The lab half and the dynamics work in ordinary
+  (decimal digits). The reduced coupling `eps` keeps that precision
+  however close to the threshold it is (since 1.2.0), so the working
+  precision does not need to exceed the number of decades you step
+  towards the onset. The lab half and the dynamics work in ordinary
   floating point with NumPy.
 - **Line shapes** are normalised probability densities; `lorentzian`
   and `gaussian` take a full width at half maximum, `box` a half
@@ -153,8 +164,9 @@ and mpmath 1.2 or newer, and nothing else.
 ## Examples
 
 Each example below runs as written, and the output shown is what it
-printed with lockkernel 1.1.1. Line widths, couplings and noise levels
-are illustrative values, not taken from any experiment.
+printed with lockkernel 1.3.0 (examples 1 to 9 print the same as with
+1.2.0). Line widths, couplings and noise levels are illustrative
+values, not taken from any experiment.
 
 ### 1. Threshold and exponent from the theory
 
@@ -253,9 +265,12 @@ For conservative spins the exponent is 1, so near the onset
 `R = A eps`, with `A = pi p(0)^2 / c`. This example runs at mpmath's
 default 15 digits; before version 1.1.1 `amplitude` and
 `c_coefficient` needed about 30 digits to be right (see
-[Corrections](#corrections-in-earlier-versions)). The two-peaked line
-is not covered by the tests; the sign rule it illustrates is the one
-derived in the `parametric` module.
+[Corrections](#corrections-in-earlier-versions)). For two unit-width
+Gaussian peaks at `+-a`, `c = (1 - 2x D(x))/pi` with `x = a/sqrt(2)`
+and `D` Dawson's function, and the tests hold `c_coefficient` to this
+formula. So the onset turns first order when the peaks are more than
+2.61386 widths apart, where Dawson's function has its maximum.
+Example 8 follows the first-order case through its hysteresis loop.
 
 ### 4. Fit a measured branch
 
@@ -289,7 +304,7 @@ print(f"kernel tail s = {s:.2f} +- {s_err:.2f}   (true 2.5)")
 ```
 
 ```
-threshold chi_c = 0.59441 +- 3.5e-09   (exact 0.59441)
+threshold chi_c = 0.59441 +- 3.8e-09   (exact 0.59441)
 exponent  beta  = 0.673 +- 0.003   (exact 0.667)
 amplitude A     = 0.652 +- 0.019
 eps range 1.56e-07 .. 1.09e-03, rms log residual 0.011
@@ -302,7 +317,9 @@ couplings and order parameters, and a `reference` that says where
 they come from (it is required). The error bars are the standard
 asymptotic ones of a least-squares fit: they are right when the power
 law holds over the fitted range and `sigma_r` is right. Without
-`sigma_r`, the scatter of the points sets them. Here the fitted
+`sigma_r`, the scatter of the points sets them. Since 1.2.0 they are
+built from exact derivatives; 1.1.1 printed `3.5e-09` for the
+threshold here (see [Corrections](#corrections-in-earlier-versions)). Here the fitted
 exponent is 2.4 of its own error bars from the exact 2/3; the tests
 allow four (see [How the results are checked](#how-the-results-are-checked)).
 `kernel_tail_from_beta` turns the exponent into the kernel's tail
@@ -311,7 +328,8 @@ exponent `s = 1 + 1/beta`, with error `sigma_beta / beta^2`.
 ### 5. Plan the measurement, and a refusal
 
 ```python
-from lockkernel import beta_relative_sigma, points_for_beta, kernel_tail_from_beta
+from lockkernel import (beta_relative_sigma, points_for_beta, kernel_tail_from_beta,
+                        plan_fit, points_for_fit)
 
 # How many points, spread evenly in log(eps) over 2 decades, with 5 %
 # scatter in R, for an error bar of 0.01 on beta (threshold known)?
@@ -319,6 +337,15 @@ n, achieved = points_for_beta(0.01, decades=2.0, sigma_log=0.05)
 print(f"points needed: {n} (error bar {achieved:.5f}); "
       f"with {n - 1}: {beta_relative_sigma(n - 1, 2.0, 0.05):.5f}")
 
+# The same range (eps = 1e-4 .. 1e-2), but with the threshold fitted too,
+# as fit_branch does it:
+plan = plan_fit(n, 1e-4, 1e-2, beta=2/3, sigma_log=0.05)
+print(f"{n} points, threshold fitted: beta +- {plan.sigma_beta:.4f}, "
+      f"chi_c +- {plan.sigma_chi_c_rel:.1e} (relative)")
+n_fit, plan = points_for_fit(0.01, 1e-4, 1e-2, beta=2/3, sigma_log=0.05)
+print(f"points needed with the threshold fitted: {n_fit} "
+      f"(error bar {plan.sigma_beta:.5f})")
+
 # A fitted beta = 0.52 +- 0.02 cannot name a kernel tail:
 try:
     kernel_tail_from_beta(0.52, 0.02)
@@ -328,15 +355,28 @@ except ValueError as err:
 
 ```
 points needed: 12 (error bar 0.00999); with 11: 0.01035
+12 points, threshold fitted: beta +- 0.0197, chi_c +- 1.4e-05 (relative)
+points needed with the threshold fitted: 57 (error bar 0.00995)
 refused: beta = 0.52 +- 0.02 is consistent with 1/2, which identifies only the CLASS s >= 3 (compact support or decay faster than |u|^-3); no single tail exponent can be named from it
 ```
 
 `beta_relative_sigma` gives the error bar of a straight-line slope on a
 log-log plot. Despite its name, the result is the absolute error of
-`beta`, not a relative one. It assumes the threshold is known, while
-`fit_branch` also fits the threshold, which is harder, so plan with
-some margin. `points_for_beta` finds the smallest number of points
-that meets the target.
+`beta`, not a relative one. It assumes the threshold is known, and
+`points_for_beta` finds the smallest number of points that meets the
+target on that assumption.
+
+`fit_branch` fits the threshold as well, and that costs precision:
+the same 12 points give an error bar about twice as large. `plan_fit`
+gives the error bars `fit_branch` will report (for `beta`, and
+relative ones for `chi_c` and `A`), before any data are taken, from
+the planned range of `eps` and the expected `beta`. `points_for_fit`
+turns that into a number of points: 57 instead of 12 here. How much
+fitting the threshold costs depends on how many decades the points
+span: for 12 points the error bar grows about 2.0 times over two
+decades, 1.6 over three, and 1.3 over five. These are the standard
+asymptotic error bars, held in the tests against 300 seeded simulated
+fits (within 12 %).
 
 ### 6. A spread of coupling strengths changes the exponent
 
@@ -369,7 +409,86 @@ oscillator's own kernel has none: `s = min(s0, (gamma-2)/eta)`, with
 `s0` the tail of the single-oscillator kernel (infinite for Kuramoto).
 Here `s = 1.8`, so `beta = 1/(s-1) = 1.25`, which is `1/(gamma-3)`.
 
-### 7. The quantum spin model against exact diagonalisation
+### 7. The amplitude when beta = 1/2
+
+```python
+import mpmath as mp
+from lockkernel.lineshapes import lorentzian, gaussian
+from lockkernel.kernels import kuramoto, gaussian_kernel
+from lockkernel.parametric import amplitude_curvature, branch_point
+
+mp.mp.dps = 20
+for line, kern in [(lorentzian(1.0), kuramoto()), (gaussian(1.0), kuramoto()),
+                   (gaussian(1.0), gaussian_kernel())]:
+    A = amplitude_curvature(line, kern)
+    _, R, eps = branch_point(line, kern, mp.mpf("1e-6"))
+    print(f"{kern.name:9s} kernel, {line.name:10s} line: A = {mp.nstr(A, 12)}, "
+          f"R/sqrt(eps) at Omega = 1e-6: {mp.nstr(R / mp.sqrt(eps), 12)}")
+print("sqrt(pi) =", mp.nstr(mp.sqrt(mp.pi), 12))
+```
+
+```
+kuramoto  kernel, lorentzian line: A = 1.0, R/sqrt(eps) at Omega = 1e-6: 0.999999999999
+kuramoto  kernel, gaussian   line: A = 1.77245385091, R/sqrt(eps) at Omega = 1e-6: 1.7724538509
+gaussian  kernel, gaussian   line: A = 1.41421356237, R/sqrt(eps) at Omega = 1e-6: 1.41421356237
+sqrt(pi) = 1.77245385091
+```
+
+For a kernel with no tail, or a tail `s > 3`, the onset is
+`R = A eps^(1/2)`. The first correction to the self-consistency then
+comes from the curvature of the line at its centre, `p''(0)`, and
+`amplitude_curvature` returns
+`A = G0^(3/2) sqrt(2 / (-p''(0) M2))`, where `G0 = p(0) m` and
+`M2 = integral u^2 W(u) du` is the kernel's second moment
+(`Kernel.second_moment()`). For the Kuramoto kernel on a Lorentzian
+line this is 1, the closed form `R = sqrt(1 - chiN_c/chiN)`. On a
+Gaussian line the width cancels, which leaves `sqrt(pi)` (Kuramoto
+kernel) and `sqrt(2)` (Gaussian kernel) at any width. The branch
+approaches these values with corrections of relative size
+`Omega^2`, or `Omega^(s-3)` for a tail `3 < s < 5`.
+
+### 8. A first-order onset: the hysteresis loop
+
+```python
+import mpmath as mp
+from lockkernel.lineshapes import bimodal_gaussian
+from lockkernel.kernels import conservative
+from lockkernel.parametric import fold_interval, threshold, extract_beta
+
+line = bimodal_gaussian(4.0)      # two Gaussian peaks (width 1) at -2 and +2
+f = fold_interval(line, n=30, lo=-2, hi=1)
+print("threshold             :", mp.nstr(threshold(line, conservative()), 10))
+print("hysteresis from chiN =", mp.nstr(f["chiN_lo"], 10), "to", mp.nstr(f["chiN_hi"], 10))
+print("R jumps from 0 to      :", mp.nstr(f["R_jump"], 10))
+print("R where the high branch ends:", mp.nstr(f["R_high_at_lo"], 10))
+try:
+    extract_beta(line, conservative(), [-3, -4, -5])
+except ValueError as err:
+    print("refused:", str(err)[:72], "...")
+```
+
+```
+threshold             : 5.89561378
+hysteresis from chiN = 3.493404803 to 5.89561378
+R jumps from 0 to      : 0.8480505911
+R where the high branch ends: 0.3342759883
+refused: eps = -0.0016464 <= 0 at Omega = 10^-3: the branch is at or below the th ...
+```
+
+With the peaks 4 widths apart `c < 0` (example 3). The branch leaves
+the threshold backwards, then turns round at `chiN = 3.4934`. In the
+usual reading of such a fold (the package computes where the
+solutions are, not whether they are stable), raising the coupling
+keeps the unsynchronized state up to the threshold, where `R` jumps to
+0.848; lowering it again keeps the synchronized state down to
+`chiN = 3.4934` (where `R = 0.334`) before it collapses. `fold_interval` samples the branch on `n` points
+between `Omega = 10^lo` and `10^hi` and then finds the turning points
+and the jump exactly. The tests check every number it returns against
+an independent closed form (the Voigt profile). There is no exponent
+on such a branch, and `extract_beta` says so instead of returning
+one.
+
+### 9. The quantum spin model against exact diagonalisation
 
 ```python
 import numpy as np
@@ -410,6 +529,98 @@ should. `xi^2` is the **Wineland spin-squeezing parameter**:
 1 for uncorrelated spins, below 1 when the spins are entangled in a way
 that improves phase measurements.
 
+### 10. Are the data consistent with the power law?
+
+```python
+import numpy as np
+from lockkernel import fit_branch
+
+# Conservative spins on a Lorentzian line of FWHM 1: chi_c = 1/2 and,
+# exactly, R = eps/(1+eps). 14 points from eps = 1e-4, 1 % seeded noise.
+rng = np.random.default_rng(4)
+for eps_max in (0.01, 0.1, 0.5):
+    eps = np.geomspace(1e-4, eps_max, 14)
+    r = eps / (1 + eps) * np.exp(rng.normal(0.0, 0.01, eps.size))
+    fit = fit_branch(0.5 * (1 + eps), r, sigma_r=0.01 * r,
+                     reference="illustrative: closed form + 1 % noise")
+    print(f"eps up to {eps_max:4}: beta = {fit.beta:.4f} +- {fit.sigma_beta:.4f}, "
+          f"chi2 = {fit.chi2:5.1f} for {fit.dof} dof, p = {fit.p_value:.2g}")
+```
+
+```
+eps up to 0.01: beta = 1.0001 +- 0.0037, chi2 =  11.1 for 11 dof, p = 0.44
+eps up to  0.1: beta = 0.9833 +- 0.0019, chi2 =  48.3 for 11 dof, p = 1.3e-06
+eps up to  0.5: beta = 0.9546 +- 0.0014, chi2 = 584.2 for 11 dof, p = 3.4e-118
+```
+
+The true exponent is 1. When the points reach far above the threshold,
+the branch bends away from the power law, and the fit returns a biased
+exponent with a small error bar: 0.9833 +- 0.0019 is 9 error bars from
+1. The error bar alone does not show this. The chi-square test does.
+When `sigma_r` is given, `fit_branch` also returns `chi2` (the weighted
+sum of squared misfits in `log R`), its degrees of freedom `dof`
+(points minus 3) and `p_value`, the chance of a misfit at least this
+large if the law and the stated errors were right. A very small
+`p_value` means one of the two is wrong: drop the points farthest from
+the threshold, or check `sigma_r`. Without `sigma_r` the scatter of the
+points sets the error scale, so there is nothing to test, and `chi2`
+and `p_value` are `None`.
+
+### 11. Errors in the couplings, and calibration
+
+```python
+import numpy as np
+from lockkernel import fit_branch, with_calibration
+
+# Stand-in measurement: R = 0.65 eps^(2/3) above chi_c = 0.5, at 14
+# recorded couplings. Each true coupling differs from the recorded one by
+# a seeded error of 5e-6 (a tenth of the distance to the threshold at the
+# first point), and R carries 1 % seeded noise.
+rng = np.random.default_rng(2)
+chi = 0.5 * (1 + np.geomspace(1e-4, 1e-1, 14))
+sigma_chi = np.full(chi.size, 5e-6)
+chi_true = chi + rng.normal(0.0, 1.0, chi.size) * sigma_chi
+r = 0.65 * (chi_true / 0.5 - 1) ** (2 / 3) * np.exp(rng.normal(0.0, 0.01, chi.size))
+
+ref = "illustrative: power law + seeded noise"
+plain = fit_branch(chi, r, ref, sigma_r=0.01 * r)
+full = fit_branch(chi, r, ref, sigma_r=0.01 * r, sigma_chi=sigma_chi)
+for name, f in (("errors of R only:", plain), ("errors of R and chi:", full)):
+    print(f"{name:20s} beta = {f.beta:.4f} +- {f.sigma_beta:.4f}, "
+          f"chi_c = {f.chi_c:.7f} +- {f.sigma_chi_c:.1e}, p = {f.p_value:.2g}")
+
+# The couplings share a 2 % calibration uncertainty, R a 5 % one:
+cal = with_calibration(full, chi_scale_rel=0.02, r_scale_rel=0.05)
+print(f"with calibration:    chi_c +- {cal.sigma_chi_c:.1e}, "
+      f"A = {cal.amplitude:.3f} +- {cal.sigma_amplitude:.3f}, "
+      f"beta +- {cal.sigma_beta:.4f} (unchanged)")
+```
+
+```
+errors of R only:    beta = 0.6698 +- 0.0020, chi_c = 0.4999987 +- 1.2e-06, p = 0.00051
+errors of R and chi: beta = 0.6658 +- 0.0026, chi_c = 0.5000034 +- 3.7e-06, p = 0.15
+with calibration:    chi_c +- 1.0e-02, A = 0.649 +- 0.033, beta +- 0.0026 (unchanged)
+```
+
+Near the threshold `R` rises steeply with the coupling, so a small
+error in the coupling moves `R` a lot: by `beta sigma_chi / (chi -
+chi_c)` in `log R`. Pass the coupling errors as `sigma_chi` and
+`fit_branch` adds this term to each point's error (to first order, and
+repeats the fit until the weights settle). Here, without it, the error
+bars are too small and the chi-square test says so (`p = 0.00051`).
+With it the fit is consistent (`p = 0.15`) and the exponent lands within
+its error bar of 2/3. `fit_branch` refuses `sigma_chi` larger than a
+quarter of `chi - chi_c` at any point, where first order is not enough.
+
+`with_calibration` adds the uncertainty of an overall scale factor: one
+common to all couplings (for example the conversion of a laser power
+into `chiN`), and one common to all `R` (for example a detection
+efficiency). Scaling every coupling scales the fitted threshold by the
+same factor and leaves `beta` and `A` exactly as they were; scaling
+`R` scales only `A`. So the two calibrations add to the error bars of
+`chi_c` and `A` in quadrature, and the exponent is immune to both. The
+tests check both statements by refitting scaled data.
+
 ## What is in the package
 
 The top level imports the `measured` names below and the submodules
@@ -424,12 +635,14 @@ directly.
   Makers: `lorentzian`, `gaussian`, `student_t`, `box`,
   `bimodal_gaussian`; `LINESHAPES` maps names to them.
 - `Kernel` -- an even kernel with `W(0) = 1`, its tail exponent, its
-  support, and `mass()`. Makers: `conservative`, `kuramoto`,
+  support, `mass()` and `second_moment()` (the integral of
+  `u^2 W(u)`, finite only for compact support, fast decay or `s > 3`).
+  Makers: `conservative`, `kuramoto`,
   `power_tail(s)`, `gaussian_kernel`; `KERNELS` maps names to them.
 - `heterogeneous(base, degree_exponent, eta=1, k_min=1)` -- the kernel
   averaged over a power-law spread of coupling strengths (example 6).
 - `predicted_beta(s)` -- the exponent the rule gives for tail `s`
-  (`None` meaning no algebraic tail).
+  (`None` meaning no algebraic tail), for a line with a rounded top.
 
 **The exact solution** (`lockkernel.parametric`, mpmath precision)
 
@@ -439,27 +652,45 @@ directly.
 - `threshold`, `branch_point`, `sweep`, `extract_beta` -- the
   threshold, one point `(chiN, R, eps)` of the branch, the branch at
   `Omega = 10^e` for a list of `e`, and the local exponents along it.
+  `eps` is computed from `G(0) - G(Omega)` directly, so it keeps the
+  working precision however small it is.
 - `c_coefficient`, `amplitude` -- for the conservative kernel, the
   number `c` whose sign sets the order of the onset, and the amplitude
   `A = pi p(0)^2 / c`.
 - `tail_integral`, `amplitude_general` -- the amplitude for a kernel
   with tail exponent `1 < s < 3`.
+- `amplitude_curvature` -- the amplitude when `beta = 1/2` (no tail,
+  or a tail `s > 3`, on a line with a rounded top; example 7).
 - `fold_interval` -- samples the branch and, if it folds back, returns
-  the coupling range of the hysteresis and the jump in `R`
-  (`None` if the branch does not fold). Not covered by the tests.
+  the coupling range of the hysteresis, the turning points and the
+  jump in `R` (`None` if the branch does not fold; example 8).
 
 **Fitting measured data** (`lockkernel.measured`, also at the top level)
 
-- `fit_branch(chi, r, reference, sigma_r=None, min_decade=1.0)` --
-  returns a `BranchFit` with `chi_c`, `beta`, `amplitude`, their
-  errors, `n_points`, `eps_range`, `residual_rms_log` (the
-  root-mean-square misfit in `log R`) and `reference`.
+- `fit_branch(chi, r, reference, sigma_r=None, min_decade=1.0,
+  sigma_chi=None)` -- returns a `BranchFit` with `chi_c`, `beta`,
+  `amplitude`, their errors, `n_points`, `eps_range`,
+  `residual_rms_log` (the root-mean-square misfit in `log R`) and
+  `reference`. Since 1.3.0 it also has `dof`, `chi2` and `p_value`
+  (the last two `None` without `sigma_r`; example 10),
+  `sigma_chi_used` and `calibration_rel`. `sigma_chi` gives the errors
+  of the couplings (example 11).
+- `with_calibration(fit, chi_scale_rel=0, r_scale_rel=0)` -- the same
+  fit with the relative uncertainties of an overall coupling scale and
+  an overall `R` scale added to the error bars of `chi_c` and `A`
+  (example 11).
 - `kernel_tail_from_beta(beta, sigma_beta=0, n_sigma=2)` -- the tail
   exponent `s` and its error.
 - `beta_relative_sigma(n_points, decades, sigma_log)`,
   `points_for_beta(target_sigma_beta, decades, sigma_log)` -- the
-  error bar of `beta` for a planned measurement, and the number of
-  points for a target error bar.
+  error bar of `beta` for a planned measurement with the threshold
+  known, and the number of points for a target error bar.
+- `plan_fit(n_points, eps_min, eps_max, beta, sigma_log,
+  fit_threshold=True)`, `points_for_fit(target_sigma_beta, eps_min,
+  eps_max, beta, sigma_log)` -- the same for the fit `fit_branch`
+  actually does, with the threshold fitted: `plan_fit` returns a
+  `FitPlan` with `sigma_beta`, `sigma_chi_c_rel` and
+  `sigma_amplitude_rel` (example 5).
 
 **Quantum spin dynamics** (`lockkernel.cumulant`, `lockkernel.ensemble`,
 `lockkernel.exact`)
@@ -479,7 +710,7 @@ directly.
 - `symmetric_exact` (all detunings equal, any number of emitters),
   `full_exact` (full quantum problem, up to about twelve emitters) and
   `class_exact` (emitters grouped by detuning, a few tens) -- exact
-  references. `class_exact` is not covered by the tests.
+  references. `class_exact` is tested against `full_exact` since 1.3.0.
 
 Each function's docstring (`help(lockkernel.fit_branch)`, for example)
 gives its inputs and conventions.
@@ -492,12 +723,19 @@ gives its inputs and conventions.
   saying where they come from;
 - fewer than 6 points are given, or `chi` and `r` differ in length
   (three parameters with error bars need more);
-- the couplings are not finite and strictly increasing, or an order
-  parameter is not finite and positive (points below the threshold,
-  `R = 0`, carry no exponent information; drop them);
-- `sigma_r` is not positive or not on the same grid as `r`;
+- the couplings are not finite, positive and strictly increasing, or
+  an order parameter is not finite and positive (points below the
+  threshold, `R = 0`, carry no exponent information; drop them);
+- `sigma_r` is not finite and positive, or not on the same grid as `r`;
 - the fit does not converge, or its covariance is singular (the data
   cannot pin down the three parameters separately);
+- the fitted exponent runs into the limits of the search, 0.05 or 20
+  (new in 1.3.0; the data are not a power law of this kind, for
+  example because `R` hardly changes, as at a jump);
+- `sigma_chi` is given without `sigma_r`, is negative, or is larger
+  than a quarter of `chi - chi_c` at some point (new in 1.3.0);
+- `with_calibration` gets a negative uncertainty, or a fit that
+  already includes one;
 - the fitted threshold is indistinguishable from the smallest
   coupling: the data do not reach the onset;
 - the fitted points span less than `min_decade` decades of `eps`
@@ -506,13 +744,32 @@ gives its inputs and conventions.
 - a fitted `beta` is consistent with 1/2 (only the class `s >= 3` is
   identified), clearly below 1/2 (no kernel gives that; the fit has
   probably left the near-threshold range), or not positive;
-- a planned measurement has fewer than 3 points, non-positive range or
-  scatter, a non-positive target, or would need more than 10^7 points;
-- `power_tail(s)` is asked for `s <= 1` (the kernel mass would be
-  infinite), or `heterogeneous` for `gamma <= 2` or a resulting tail
-  `s <= 1`;
+- a planned measurement has fewer than 3 points (6 with the threshold
+  fitted, as `fit_branch` needs), a number of points that is not a
+  whole number, a non-positive or reversed range, a non-positive
+  scatter or `beta`, a non-positive target, or would need more than
+  10^7 points;
+- `extract_beta` meets a point with `eps <= 0`: the branch is at or
+  below the threshold there, because it bends back (a first-order
+  onset, example 8) or is flat (`R` jumps at the threshold), and there
+  is no exponent to measure;
+- `amplitude_curvature` is asked for a line with `p''(0) >= 0` (a flat
+  top or a dip at the centre) or a kernel with tail `s <= 3`, and
+  `second_moment` for a kernel with tail `s <= 3` (it diverges);
+- `fold_interval` finds a fold on a line with compact support (`box`),
+  which it cannot refine, or cannot bracket a turning point on its
+  grid;
+- `power_tail(s)` or `predicted_beta(s)` is asked for `s <= 1` (the
+  kernel mass would be infinite), or `heterogeneous` for `gamma <= 2`,
+  a non-positive `eta` or `k_min`, or a resulting tail `s <= 1`;
+- a line shape is given a width that is not finite and positive;
 - `tail_integral` is asked for `s` outside `1 < s < 3`, where it
   diverges;
+- `amplitude_general` is asked for a kernel without a tail in
+  `1 < s < 3`, or (new in 1.3.0) its default tail amplitude `C`, read
+  off the kernel at `|u| = 10^6`, differs by more than a relative 1e-6
+  from the value at `10^9` (pass `C` yourself then);
+- `class_exact` gets class populations that are not whole numbers;
 - a line shape without a floating-point distribution
   (`bimodal_gaussian`) is asked for `cdf`, `ppf` or a class table;
 - the solver of the differential equations fails in `evolve` or
@@ -520,7 +777,7 @@ gives its inputs and conventions.
 
 ## How the results are checked
 
-65 automated tests run on every push and pull request, on Python 3.9
+128 automated tests run on every push and pull request, on Python 3.9
 to 3.14, and once more on Python 3.10 with the oldest NumPy (1.22.0),
 SciPy (1.8.0) and mpmath (1.2.1) the package allows. The numerical
 checks compare the package with something independent of it: a closed
@@ -549,6 +806,79 @@ the package does not import matplotlib. The main checks:
   `Omega` = 1e-6 and 2e-6 to a relative 1e-9, on four lines; `R/eps` at `Omega = 1e-6` is
   within a relative 1e-5 of the amplitude.
 
+**New in 1.2.0** (15 digits unless stated; the references are closed
+forms evaluated separately from the package's integrals)
+
+- `eps`, `chiN` and `R` on the Lorentzian line match `eps = Omega/a`,
+  `chiN = a + Omega`, `R = Omega/(a + Omega)` to a relative 1e-13 for
+  `Omega` from 1e-6 to 1e-14, and to 1e-28 at 30 digits down to
+  `Omega` = 1e-20.
+- Box line, kernels `1/(1+|u|^s)` with `s` = 1.5, 2.5, 4 and 6: `G`
+  and `eps` match the closed form `G = X 2F1(1, 1/s; 1+1/s; -X^s)`,
+  `X = 1/Omega`, to a relative 1e-13 at `Omega` = 1e-1, 1e-3 and 1e-5
+  (down to `eps` of about 1e-26). On this flat-topped line
+  `extract_beta` gives `1/(s-1)` = 1/3 and 1/5 for `s` = 4 and 6, within
+  1e-6.
+- Two-peaked line: `c_coefficient` matches `(1 - 2x D(x))/pi` to 1e-13
+  for separations 1, 2 and 4; the sign of `c` flips across the
+  separation 2.61386 (the maximum of Dawson's function, located by root
+  finding); `G` matches the Voigt closed form to a relative 1e-13.
+- `fold_interval`: every number it returns (couplings, order
+  parameters, `Omega` of the turning points and of the jump) matches
+  the Voigt closed form, with turning points found by root finding on
+  its derivative, to a relative 1e-12, for a branch that leaves the
+  threshold backwards (two peaks 4 widths apart) and for an S-shaped
+  branch (a three-peak line); it returns `None` for a monotonic branch.
+- `extract_beta` refuses the backward branch and the flat one (box
+  line, Kuramoto kernel, where `eps` is exactly 0).
+- `second_moment` matches `pi/8` (Kuramoto), `sqrt(pi)/2` (Gaussian
+  kernel) and `2 (pi/s)/sin(3 pi/s)` (`s` = 4, 6) to 1e-12.
+  `amplitude_curvature` is 1 for the Kuramoto kernel on a Lorentzian
+  line and `sqrt(pi)`, `sqrt(2)` on Gaussian lines of two widths, to
+  1e-12; at 20 digits it matches `R/sqrt(eps)` at `Omega = 1e-6` to a
+  relative 1e-10 for three kernel-line pairs, and to 2e-6 for `s = 4`.
+
+**New in 1.3.0** (15 digits unless stated; every reference is a closed
+form or a calculation done another way)
+
+- Kernel masses for slow tails, `power_tail(s)` with `s` = 1.05, 1.1,
+  1.25 and 1.5, against `2 (pi/s)/sin(pi/s)` to a relative 1e-14, and
+  1e-28 at 30 digits. The averaged Kuramoto kernel of example 6 with
+  `gamma` = 3.4, 3.8 and 4.4 against its mass
+  `(pi/2)(gamma-2)/(gamma-3)` to 1e-13. `second_moment` for `s` = 3.1,
+  3.25 and 3.5 against `2 (pi/s)/sin(3 pi/s)` to 1e-13.
+- For `s = 1.1` on a Lorentzian line the threshold equals
+  `s sin(pi/s)/4` to 1e-13, and `chiN/chiN_c - 1` on the branch equals
+  `eps` from its separate integral to 1e-10.
+- `tail_integral` against the closed forms on Lorentzian and Gaussian
+  lines of widths 0.001, 1 and 1000, for `s` from 1.1 to 2.99, to a
+  relative 1e-13 (and 1e-27 at 30 digits). `amplitude_general` against
+  its closed form on the Lorentzian line for `s` = 1.1, 1.5, 2.5 and
+  2.9, to 1e-12.
+- `amplitude_general` refuses the conservative kernel averaged over
+  coupling strengths, whose tail amplitude (a closed form, also checked
+  by quadrature) is not reached at `|u| = 10^6`, and accepts the
+  averaged Kuramoto kernel, whose tail is an exact power law (its
+  default `C` matches the closed form `(gamma-2) B(s/2, 3/2)/2` to give
+  the same amplitude to 1e-12).
+- `class_exact` matches `full_exact` (8 emitters, two sets of classes)
+  to 1e-10 in `R` and 1e-9 in `xi^2`, with the times in any order.
+- `fit_branch`: `chi2` matches the sum recomputed from the returned
+  parameters; over 300 seeded fits under the model the p-values pass a
+  Kolmogorov-Smirnov test for uniformity and `chi2` averages to `dof`
+  within four standard errors; on the exact conservative branch with
+  1 % noise, points up to `eps = 0.01` give `p > 0.05` and `beta`
+  within 3 error bars of 1, points up to `eps = 0.5` give
+  `p < 1e-10` and `beta` more than 10 error bars off.
+- With coupling noise of a tenth of `chi - chi_c` at the first point,
+  the error bars of `chi_c`, `beta` and `A` with `sigma_chi` match the
+  scatter of 300 seeded fits within 12 %, while without it `sigma_beta`
+  is more than 15 % too small. `sigma_chi = 0` gives exactly the plain
+  fit. A fit refuses data generated with `beta` = 0.02, 0.04 and 25.
+- Refitting data with all couplings scaled by 1.07 scales `chi_c` by
+  1.07 to 1e-9 and leaves `beta` and `A` unchanged to 1e-7; scaling `R`
+  scales only `A`. `with_calibration` adds in quadrature to 1e-12.
+
 **The exponent rule** (25 digits, Gaussian line, `Omega` down to 1e-6)
 
 - `beta = 1/(s-1)` or 1/2 for the kernel family with `s` = 1.5, 1.8,
@@ -577,6 +907,17 @@ the package does not import matplotlib. The main checks:
 - The planning formula matches 6000 seeded simulated fits within 5 %,
   and `points_for_beta` returns the smallest `n` that meets the target
   (checked on both sides).
+- (New in 1.2.0) On noiseless data reaching `eps = 1e-7`, the error
+  bars `fit_branch` reports, and those `plan_fit` predicts, equal the
+  ones built from mpmath's numerical derivatives at 30 digits to a
+  relative 1e-6. With the threshold known, `plan_fit` equals
+  `beta_relative_sigma` to 1e-12. Over 300 seeded noisy fits (1 %
+  scatter), the scatter of `chi_c`, `beta` and `A` matches `plan_fit`,
+  and the median reported error bar matches the scatter, within 12 %.
+  `points_for_fit` is checked on both sides, and the error bar is
+  checked to fall with every added point from 6 to 400. `sigma_beta`
+  and `sigma_A` from `plan_fit` do not depend on `beta` and
+  `sigma_chi_c` scales as `1/beta` (to 1e-12).
 
 **Dynamics and discretisation**
 
@@ -596,11 +937,80 @@ the package does not import matplotlib. The main checks:
   within 5e-3 for couplings `r` = 1.2, 2 and 3 times the threshold,
   and stays below 0.05 at 0.6 times the threshold.
 
-Not covered by tests: `fold_interval`, `bimodal_gaussian`,
-`class_exact`, `physicality` and `valid_window`.
+Not covered by tests: `physicality` and `valid_window`.
 
 ## Corrections in earlier versions
 
+**1.3.0 fixed five silent errors.** Numbers are at mpmath's default 15
+digits unless stated.
+
+- `Kernel.mass()` integrated a slow tail directly out to infinity. For
+  `power_tail(1.1)` the mass was 20.0312 instead of 20.2745 (1.2 % low;
+  3.7e-4 at 30 digits), so the threshold on a Lorentzian line of FWHM 1
+  was 0.0784174 instead of 0.0774765, and did not match the branch's own
+  `eps`. `second_moment()` had the same problem just above `s = 3`
+  (19.7910 instead of 20.0343 for `s = 3.1`). The tail is now mapped
+  onto a finite interval, as `G(Omega)` already was, and both match
+  their closed forms to the working precision.
+- `tail_integral` integrated a singularity `delta^(2-s)` at the center
+  directly. On a Lorentzian line of FWHM 1, `I_s` was 47.063 instead
+  of 47.715 at `s = 2.9` and 86.97 instead of 98.49 at `s = 2.95`. A
+  change of variables now removes the singularity.
+- Through these two, `amplitude_general` was wrong at the edges of
+  `1 < s < 3`, where the power `1/(s-1)` amplifies errors: on a
+  Gaussian line 8.4219 instead of 9.6179 for `s = 1.1`, and 0.45574
+  instead of 0.45258 for `s = 2.9`. Its default tail amplitude was also
+  used without a check: for the conservative kernel averaged over
+  coupling strengths (`gamma = 3.8`) it was 6.2 % low, and the
+  amplitude 8.3 % high. It now refuses such a kernel unless `C` is
+  given.
+- `fit_branch` returned the limit of its search as the exponent when
+  the best fit lay beyond it: for `R = 0.8 eps^0.04` it reported
+  `beta = 0.0500 +- 0.0040`, and for `eps^25`, `beta = 20 +- 1.5`. It
+  now refuses.
+- `class_exact` skipped a time earlier than the one before it and
+  returned the later state: for times `[1.0, 0.2]` (the system of
+  example 9) both entries gave `R = 0.677579`; the right value at
+  `t = 0.2` is 0.984316. It now accepts times in any order.
+
+All earlier tests pass unchanged, and examples 1 to 9 print the same
+as with 1.2.0.
+
+**1.2.0 fixed four silent inaccuracies.** Numbers below are at
+mpmath's default 15 digits unless stated.
+
+- `branch_point` formed `eps` as `chiN/chiN_c - 1` and lost about
+  `log10(1/eps)` digits: on the Lorentzian line `eps` was 2e-4
+  (relative) off at `Omega = 1e-9` and wrong by a factor of about 220 at
+  `1e-12`. `G_of_Omega` itself was 4e-10 off at `Omega = 1e-12`,
+  because a segment spanning many decades was integrated on a linear
+  scale. On the box line with `s = 4`, `extract_beta` quoted 0.3194
+  instead of 1/3, and with `s = 6` it raised `ZeroDivisionError`. Both
+  quantities now keep the working precision (see the new checks above).
+  The earlier tests and examples ran at 20 to 30 digits with `eps` no
+  smaller than about 1e-12, where the loss did not show: all of them
+  still pass unchanged, and README examples 1, 2, 3, 6 and 9 print the
+  same as before.
+- `extract_beta` returned slopes close to 1 (1.0016, 1.00016, 1.000016
+  for `Omega` = 1e-3 down to 1e-6, at 20 digits) for the backward
+  branch of the two-peaked line (a first-order onset, `eps < 0`), and
+  raised `ZeroDivisionError` on a flat branch. It now refuses both.
+- `fit_branch` took its derivatives by finite differences, which near
+  the threshold are not small steps: with points down to `eps = 1e-7`
+  it reported `sigma_chi_c` about 17 % and `sigma_beta` about 2 % too
+  small, and on example 4's data the fit stopped marginally short of
+  the least-squares minimum. It now uses exact derivatives. In example 4 the threshold
+  error bar goes from 3.5e-9 to 3.8e-9 (beta 0.67322 -> 0.67325, its
+  error bar 0.00275 -> 0.00279).
+- `fold_interval`, for a branch that leaves the threshold backwards,
+  returned the first grid point instead of the threshold as the end of
+  the low branch (5.89464 instead of 5.89561 in example 8, and so a
+  jump to 0.84800 instead of 0.84805). A turning point it could not
+  refine was silently replaced by a grid point; it now raises. It is
+  also much faster: on the line of example 8 with `n = 60` and the
+  default range it took 79 s in 1.1.1 and takes 3.5 s now (17 s at the
+  default `n = 400`).
+
 **1.1.1 fixed the amplitude at ordinary precision.**
 `c_coefficient` (and so `amplitude`) lost about 40 digits to a
 cancellation near the centre of the line. At mpmath's default 15
@@ -626,6 +1036,16 @@ CI did not run Python 3.10. The full history is in
   right when the power law holds and the noise estimate is right.
 - `extract_beta` converges slowly near `s = 3`, where the exponent
   carries logarithmic corrections.
+- The rule `beta = 1/2` for `s >= 3` (and `predicted_beta`,
+  `kernel_tail_from_beta`, `amplitude_curvature`) assumes a line with a
+  rounded top, `p''(0) < 0`. On a line that is flat at the centre, as
+  `box` is, a tail gives `beta = 1/(s-1)` for every `s > 1`, and a
+  kernel without a tail gives a jump. A measured `beta` below 1/2 is
+  refused by `kernel_tail_from_beta`, although a flat-topped line can
+  produce one.
+- `plan_fit` gives the asymptotic error bars, exact to first order in
+  the noise. They were checked against simulated fits at 1 % scatter;
+  at much larger scatter the real fit can do worse.
 - In the undamped spin model the truncated cumulant equations become
   unstable at long times; check `physicality` / `valid_window` before
   trusting a long run. The time-averaged kernel is an assumption,
@@ -635,9 +1055,23 @@ CI did not run Python 3.10. The full history is in
   digits at most, however high `mp.dps` is set: the integral leaves
   out the first 1e-20 line widths next to the centre, a piece of
   relative size about 1e-20.
-- `fold_interval` is slow (each branch point is a high-precision
-  integral, and it takes 400 by default) and is not covered by the
-  tests.
+- `fold_interval` finds a fold only if its grid shows it: structure
+  below `Omega = 10^lo` or narrower than the grid spacing is missed, and
+  with several folds only the first and last turning points are used.
+  It needs a differentiable line. It costs `n` plus about 40
+  high-precision integrals (about 17 s at the default `n = 400` on the
+  two-peaked line).
+- `fit_branch` propagates coupling errors `sigma_chi` to first order.
+  The tests check this at a tenth of `chi - chi_c`, and hand checks
+  with 1000 seeded fits held to within 6 % up to three tenths. It is
+  refused above a quarter.
+- `with_calibration` treats calibration as one scale factor for all
+  couplings and one for all `R`. An offset (a zero error) is not a
+  scale: it changes `eps` and so the exponent, and is not covered.
+- The default tail amplitude of `amplitude_general` is read off the
+  kernel at `|u| = 10^6`; for `power_tail(s)` it is low by a relative
+  `10^(-6 s)`, which the power `1/(s-1)` multiplies (2.5e-6 in `A` for
+  `s = 1.1`). Pass `C` for more digits.
 - `build_system`'s docstring refers to a convergence check in
   `scripts/vlasov_check.py`; that script belongs to the research
   repository and is not part of this package.
@@ -651,8 +1085,11 @@ concept DOI
 [10.5281/zenodo.22696369](https://doi.org/10.5281/zenodo.22696369)),
 whose scripts, archived run records and figures remain with the
 study. The core modules were carried over unchanged in v1.1.0 (1.1.1
-changes only `c_coefficient`); the `measured` module and the
-packaging are new here. Copyright as in [NOTICE](NOTICE).
+changes only `c_coefficient`; 1.2.0 changes how `G`, `eps` and the
+fold are computed, and adds `amplitude_curvature` and
+`Kernel.second_moment`; 1.3.0 changes how the kernel mass, the second
+moment and `tail_integral` are integrated, and how `class_exact` steps
+through time); the `measured` module and the packaging are new here. Copyright as in [NOTICE](NOTICE).
 
 ## Citing, support and license