# LivePlotting_10: Trick Out Your Instrument
> [!abstract] The project in one line
> Take the plotting-and-root-finding script our class built live over nine sessions, harden it into an instrument that states what it promises and proves it on demand, then extend it toward a goal you choose and defend with evidence.
## Introduction
For multiple lectures, you watched one script grow. `LivePlotting_1` sampled a function and drew it. By `LivePlotting_5` it had anonymous functions, a quadratic Taylor root finder, and a title. By `LivePlotting_9` it carried finite-difference derivatives, [Newton's method](https://en.wikipedia.org/wiki/Newton%27s_method) with a stopping rule built on [machine epsilon](https://en.wikipedia.org/wiki/Machine_epsilon), and nine layers of commented-out history. It works. It is also a pile, and, quietly, it is wrong: run the Day-2 sign-change detector on our own class function $f(x) = x^2(x+1)(x-1)^3$ and it reports two roots. The function has three. Run the same scan on $f'$ and it finds three critical points. There are four.
Professional numerical software does not get to be a pile, and it does not get to be quietly wrong. A library like the one behind `fzero` or `scipy.optimize` is an *instrument*: it states a contract (what it finds, to what accuracy, with what evidence), it ships with a [test suite](https://en.wikipedia.org/wiki/Unit_testing) that would catch the two failures above, and its figure output is a claim backed by numbers, not decoration. The gap between `LivePlotting_9` and an instrument is not more mathematics. It is engineering: [invariants](https://en.wikipedia.org/wiki/Invariant_(computer_science)), tests, honest reporting, and a design that survives functions it has never seen.
This project closes that gap, then hands you the wheel. Everyone brings the class script up to the same base contract against a shipped test suite. Then you pick a direction and trick it out: a smarter seeding algorithm, a hardened multiplicity-aware core, a two-dimensional version, a performance pass, or an interface a stranger could use, or you pitch your own goal. The project is deliberately more programming and systems logic than derivation. The mathematics you need, you mostly already own.
## Project Description
The work moves in the usual four passes, worn engineering-style. First, the contract: three short results (why the sign scan goes blind, how Newton's step ratio reveals [multiplicity](https://en.wikipedia.org/wiki/Multiplicity_(mathematics)), where the finite-difference width should sit) worked by hand to checkable numbers. Second the mirror: your code reproduces those hand numbers, including the documented failures of the naive baseline. Third the build: the class script becomes `analyzeFunction(f, a, b)`, brought up to the contract against the shipped test suite. Fourth, your goal: a trick-out track chosen from the menu (or proposed in the open lane), scoped at Milestone 1, delivered with evidence.
**Foundation task:** derive the three contract results by hand (blindness product, contraction ratios $\tfrac12$ and $\tfrac23$, the width $h^*$), then verify that your code reproduces every hand number through the `same()` helper, failures included.
**Application task:** refactor the arc code into the instrument, meet the base contract on the shipped test suite (13 catalogued zeros across four functions: completeness 13/13, soundness PASS), and render the dashboard figure in which every marker is backed by a diagnostics row.
**Key deliverable:** your trick-out. One track from the menu below or an approved proposal of your own, delivered as working code plus the evidence that its stated contract holds, and defended in your write-up from the diagnostics, not from effort.
Two companions support the milestone forms: the [[MATH307Su26 - LivePlotting - Trick Out Your Instrument (Milestone Map)|Milestone Map]] says which artifact from this handout answers each form field, and the [[MATH307Su26 - LivePlotting_10 - Trick Out Your Instrument (Verification Table)|Verification Table]] is filled in as you verify and submitted with Milestone 2.
## Mathematical Background: the contract, and the three small results it needs
**Idea.** An instrument is trustworthy when it states what it promises and can prove, on demand, that the promise held. For a zero-finder the promise has two halves, borrowed from logic: [soundness](https://en.wikipedia.org/wiki/Soundness) (everything reported is real) and [completeness](https://en.wikipedia.org/wiki/Completeness_(logic)) (everything real is reported). "It ran" is neither.
$\boxed{\begin{aligned}
&\textbf{The base contract for } \texttt{analyzeFunction}(f, a, b):\\[2pt]
&\text{I1 (sound): every reported location } r \text{ satisfies } a \le r \le b \text{ and } |f(r)| \le \tau_{\text{res}},\\
&\qquad\ \text{and every marker on the figure has a row in the diagnostics table.}\\
&\text{I2 (complete): every catalogued zero in } [a,b] \text{ is reported within } \tau_{\text{loc}} = 10^{-3}.\\
&\text{I3 (honest): every report carries its evidence: residual, iteration count,}\\
&\qquad\ \text{step ratio, multiplicity estimate } \hat m, \text{ and a classification or an explicit "inconclusive".}
\end{aligned}}$
The suite ships with the catalogs, so I2 is checkable. Three small results, each one Taylor-series long, tell you what the instrument is up against.
**Result 1 (why the Day-2 scan goes blind).** Near a zero $r$ of multiplicity $m$, Taylor gives $f(x) \approx C\,(x-r)^m$ with $C = f^{(m)}(r)/m!$. If $m$ is odd, $f$ changes sign across $r$ and the [intermediate value theorem](https://en.wikipedia.org/wiki/Intermediate_value_theorem) scan sees it. If $m$ is even, $f$ has the *same* sign on both sides and the scan sees nothing. Our class function has $f(x) \approx -x^2$ near $0$ (take $x^2 \cdot (x+1)(x-1)^3 \to x^2 \cdot 1 \cdot (-1)$), so by hand
$f(-0.1) = -0.011979, \qquad f(0.1) = -0.008019, \qquad f(-0.1)\,f(0.1) = 9.606 \times 10^{-5} > 0,$
and the scan walks straight past a root. The same argument applied to $f'$ explains the missing critical point: $x=1$ is a *double* zero of $f'$ (because it is a triple zero of $f$), so the critical-point scan is blind there too. One cause, two failures.
**Result 2 (Newton's step ratio reads the multiplicity).** Apply Newton to the pure power $f(x) = C(x-r)^m$. The update is
$x_{k+1} = x_k - \frac{C(x_k-r)^m}{mC(x_k-r)^{m-1}} = x_k - \frac{x_k - r}{m}, \qquad\text{so}\qquad e_{k+1} = \Big(1 - \frac{1}{m}\Big)\,e_k$
exactly, where $e_k = x_k - r$. Simple roots ($m=1$) collapse superlinearly, the quadratic cliff from Day 7. Multiple roots tiptoe in *linearly* with ratio $1 - 1/m$: a double root contracts by $\tfrac12$ per step, a triple root by $\tfrac23$. Reading the measured ratio $\rho$ backwards gives a multiplicity meter,
$\boxed{\;\hat m = \operatorname{round}\!\Big(\frac{1}{1-\rho}\Big),\;}$
and knowing $m$ repairs the tiptoe: the modified step $x_{k+1} = x_k - m\,f(x_k)/f'(x_k)$ lands the pure power in one step and restores fast convergence in general. There is a hard limit, though. Near a multiple root $|f| \approx |C|\,e^m$ sinks below the roundoff floor $\tau_f \approx 10^{-14}$ while $e$ is still large, so *no* method can locate the root better than
$e_{\text{floor}} \approx \Big(\frac{\tau_f}{|C|}\Big)^{1/m},$
about $10^{-7}$ for our double root ($C=-1$) and $1.7 \times 10^{-5}$ for our triple root ($f \approx 2(x-1)^3$ near $1$, so $C=2$). Invariant I3 exists precisely so the instrument admits this instead of printing sixteen confident digits.
**Result 3 (where the stencil width should sit).** The 3-point stencil's total error balances truncation against roundoff, exactly as on Day 8:
$E(h) \approx \frac{M_3}{6}h^2 + \frac{2\epsilon\,|f|}{h}, \qquad E'(h^*) = 0 \;\Rightarrow\; \boxed{\;h^* = \Big(\frac{6\,\epsilon\,|f|}{M_3}\Big)^{1/3}\;}$
with $M_3$ a bound on $|f'''|$ and $\epsilon \approx 2.22 \times 10^{-16}$. At $x = 0.5$ our class function has $|f(0.5)| = 0.046875$ and $M_3 = |f'''(0.5)| = |15 - 30 + 12| = 3$, so $h^* = 2.751 \times 10^{-6}$. The `h = 10^-6` that sat in the live code all arc was in the right decade the whole time; now you can prove it.
> [!note] Where this comes from
> Nothing here is new machinery. Result 1 is the Day-2 scan read through Taylor's lens, Result 2 is the Day-7 convergence analysis pushed one case further, and Result 3 is the Day-8 truncation-vs-roundoff balance. The new content is the contract wrapped around them.
### Worked example, run to completion
Collect the hand numbers your code must reproduce in Step 1:
1. Blindness product: $f(-0.1)\,f(0.1) = (-0.011979)(-0.008019) = 9.606 \times 10^{-5} > 0$; the scan misses $x=0$.
2. Predicted contraction ratios: $m=2 \Rightarrow \rho = 0.5$; $m=3 \Rightarrow \rho = 0.6667$. Multiplicity meter check: $\rho = 0.5 \Rightarrow \hat m = \operatorname{round}(1/0.5) = 2$; $\rho = 0.6667 \Rightarrow \hat m = \operatorname{round}(1/0.3333) = 3$.
3. Accuracy floors: double root $e_{\text{floor}} \approx (10^{-14}/1)^{1/2} = 10^{-7}$; triple root $e_{\text{floor}} \approx (10^{-14}/2)^{1/3} = 1.7 \times 10^{-5}$.
4. Stencil width: $h^* = \big(6 \cdot 2.22 \times 10^{-16} \cdot 0.046875 / 3\big)^{1/3} = 2.751 \times 10^{-6}$.
Every one of these appears in a code step below, checked through `same()`.
## Implementation Guidelines
The workflow is the same in every language, so we state it once and then implement it step by step.
> [!abstract] The workflow (state it once, run it in any language)
> Given $f$ on $[a,b]$ and the contract (I1, I2, I3):
> 1. **Warm up**: define `same()`, then reproduce the four hand numbers from the worked example.
> 2. **Stencils and polisher**: port `fPrime`/`fPrimePrime` as $D_h f(x) = \frac{f(x+h)-f(x-h)}{2h}$ and the 5-point second difference; wrap Newton with the $\text{eps}(x)$ stopping rule into `newton_polish`; mirror two class runs and measure the ratios $\rho$.
> 3. **The detector**: seeds = sign-change midpoints PLUS the $n$ grid points of smallest $|f|$ (the LivePlotting_7 rescue; this is what catches even multiplicity); polish every seed; gate by window and residual (I1); deduplicate; estimate $\hat m = \operatorname{round}(1/(1-\rho))$; classify critical points by $f''$ with an explicit "inconclusive" branch (I3).
> 4. **The test suite**: score completeness and soundness against the shipped catalogs (I2); score the naive baseline too, and watch it fail.
> 5. **The width sweep**: measure $E(h)$ across twelve decades and confirm the minimum sits in $h^*