lockkernel 1.1.1__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lockkernel
-Version: 1.1.1
+Version: 1.2.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
@@ -119,7 +119,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 +149,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,7 +161,7 @@ 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
+printed with lockkernel 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 +261,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 +300,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 +313,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 +324,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 +333,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 +351,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 +405,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
@@ -424,12 +539,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,14 +556,18 @@ 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)
 
@@ -458,8 +579,14 @@ directly.
   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`)
@@ -506,8 +633,20 @@ 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;
+- a planned measurement has fewer than 3 points (6 with the threshold
+  fitted, as `fit_branch` needs), 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)` is asked for `s <= 1` (the kernel mass would be
   infinite), or `heterogeneous` for `gamma <= 2` or a resulting tail
   `s <= 1`;
@@ -520,7 +659,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
+97 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 +688,38 @@ 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`.
+
 **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 +748,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 +778,46 @@ 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: `class_exact`, `physicality` and
+`valid_window`.
 
 ## Corrections in earlier versions
 
+**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 +843,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 +862,16 @@ 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).
+- `Kernel.mass()` integrates slow tails numerically: for
+  `power_tail(1.5)` it is about 2e-10 (relative) off at 15 digits and
+  5e-18 at 30. This enters `threshold` (not `eps`, whose integral
+  treats the tail separately).
 - `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 +885,10 @@ 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`); the `measured` module and the packaging are
+new here. Copyright as in [NOTICE](NOTICE).
 
 ## Citing, support and license