@pikaa-ai/pikaa 0.3.0 → 0.3.4

package/skills/uncertainty-and-units/references/plausibility-scales.md

@@ -1,168 +0,0 @@
-# Plausibility: dimensionless groups, characteristic scales, and magnitude bands
-
-Dimensional analysis proves a calculation is *consistent*. It cannot prove the answer is
-*possible*. A cell 2 m across, a Reynolds number of 4×10⁷ in a capillary, and a diffusion
-time of 300 years across a lipid bilayer are all dimensionally impeccable, and a
-unit-checking library will pass every one of them.
-
-The three checks below close that gap. `scripts/check_plausibility.py` runs all of them
-and verifies dimensional consistency of each formula before reporting a number.
-
----
-
-## 1. Choose the characteristic length first
-
-The single most common error in this whole area is not an arithmetic slip — it is using
-the wrong length. The dimensionless groups are only meaningful with the length the
-correlation was fitted against.
-
-| Geometry | Characteristic length |
-| --- | --- |
-| Flow in a circular pipe | inside **diameter**, not radius |
-| Flow in a non-circular duct | hydraulic diameter `4A/P` |
-| External flow over a plate | distance from the leading edge |
-| Flow past a sphere or cylinder | diameter |
-| Conduction in an irregular body (Biot) | volume / surface area |
-| Packed bed | particle diameter |
-| Open channel | hydraulic radius `A/P` — note: radius, not diameter |
-
-Using radius where the correlation wants diameter puts every threshold out by a factor of
-two, which is exactly the size of error that survives review.
-
-## 2. Dimensionless groups and what they gate
-
-Each threshold is a *modelling decision boundary*: past it, an assumption in your
-analysis stops holding.
-
-| Group | Definition | Threshold | What stops being true past it |
-| --- | --- | --- | --- |
-| Reynolds `Re` | `ρvL/μ` | 2300 / 4000 (pipe) | laminar solutions; above 4000 you need a turbulence model |
-| Péclet `Pe` | `vL/D` | ≈ 1 | below 1 diffusion dominates, so stirring will not help |
-| Damköhler `Da_I` | `kL/v` | 0.1 / 10 | above 10 the reagent is consumed at the inlet, so the reactor is transport-limited |
-| Knudsen `Kn` | `λ/L` | 0.01 | the no-slip boundary condition, then the continuum assumption itself |
-| Mach `Ma` | `v/c` | 0.3 | incompressibility, at about 5% density change |
-| Womersley `Wo` | `R√(ωρ/μ)` | 1 / 10 | the parabolic (Poiseuille) profile; above 10 the core moves as a plug |
-| Capillary `Ca` | `μv/σ` | ≈ 10⁻³ | an interface whose shape is set by surface tension alone |
-| Weber `We` | `ρv²L/σ` | ≈ 12 | drop integrity — above it, aerodynamic breakup |
-| Bond `Bo` | `Δρ g L²/σ` | 1 | surface tension holding a drop against gravity |
-| Stokes `Stk` | `ρ_p d² v / (18 μ L)` | 0.1 | the tracer assumption behind PIV and aerosol sampling |
-| Biot `Bi` | `hL/k` | 0.1 | lumped-capacitance (uniform internal temperature) |
-| Fourier `Fo` | `αt/L²` | 0.05 / 1 | the semi-infinite solution; above 1 the body has equilibrated |
-| Schmidt `Sc` | `μ/(ρD)` | — | ≈ 1 for gases, ≈ 10³ for small molecules in water |
-| Deborah `De` | `t_relax/t_obs` | 1 | whether the material is a liquid or a solid *on your timescale* |
-
-**Womersley takes angular frequency.** Pass `2πf`, not `f`. A resting human heart at
-1.2 Hz gives `ω ≈ 7.5 rad/s`, and in the aorta `Wo ≈ 20` — firmly plug-like, which is why
-Poiseuille's law is the wrong model for arterial flow and the right one for a capillary.
-
-**The Reynolds thresholds are pipe-flow values.** Transition over a flat plate is around
-`Re ≈ 5×10⁵`; for flow past a sphere the wake becomes unsteady near `Re ≈ 100`. The tool
-reports the pipe classification and says so.
-
-## 3. Characteristic scales
-
-| Scale | Formula | Sanity anchor |
-| --- | --- | --- |
-| Diffusion time | `L²/D` | 10 µm at 10⁻⁹ m²/s → 0.1 s |
-| Thermal diffusion time | `L²/α` | same form, thermal diffusivity |
-| Thermal energy | `k_B T` | 4.14×10⁻²¹ J at 300 K |
-| Molar thermal energy | `RT` | 2.49 kJ/mol at 300 K |
-| Stokes settling velocity | `Δρ g d²/(18μ)` | 1 µm bead in water → ≈ 0.5 µm/s |
-| Mean free path (gas) | `k_BT/(√2 π d² p)` | air at 1 atm → ≈ 68 nm |
-| Debye length | `√(ε₀ε_r k_B T / (2 N_A e² I))` | 100 mM → 0.96 nm |
-| Capillary length | `√(σ/(ρg))` | water → 2.7 mm |
-
-**The L² in diffusion time is the whole story of cell biology.** Ten micrometres takes
-0.1 s; one millimetre takes 1000 s; one centimetre takes 10⁵ s ≈ 28 hours. This is why
-cells are small, why tissue thicker than ~200 µm needs a blood supply, and why a claim
-that a molecule "diffuses across the tissue in seconds" is worth checking.
-
-**Stokes settling is valid only while the particle Reynolds number stays below ≈ 0.1.**
-Compute the settling velocity, then feed it back into the `reynolds` group with the
-particle diameter as the length. If `Re_p > 0.1`, the drag law is wrong and the velocity
-is an overestimate.
-
-## 4. Magnitude bands
-
-These are deliberately generous observed ranges. A value outside one is worth a second
-look, not automatically wrong — the tool reports `questionable` inside one decade and
-`implausible` beyond it.
-
-| Band | Range | Source |
-| --- | --- | --- |
-| Bacterial cell diameter | 0.2–10 µm | Milo & Phillips, *Cell Biology by the Numbers*, ch. 1 |
-| Eukaryotic cell diameter | 5–100 µm | Milo & Phillips, ch. 1 |
-| Cell membrane thickness | 3–5 nm | Alberts et al., *MBoC* 7th ed., ch. 10 |
-| DNA base-pair rise | 0.32–0.36 nm | Bloomfield et al., *Nucleic Acids* |
-| Ribosome diameter | 20–30 nm | Milo & Phillips, ch. 1 |
-| Protein molar mass | 5–1000 kDa | Milo & Phillips, ch. 1 |
-| Human capillary diameter | 5–10 µm | Guyton & Hall, 14th ed., ch. 16 |
-| Mammalian body temperature | 306–315 K | Guyton & Hall, ch. 74 |
-| Resting heart rate | 0.7–3 Hz | Guyton & Hall, ch. 9 |
-| Blood plasma osmolarity | 275–300 mol/m³ | Guyton & Hall, ch. 25 |
-| Small-molecule diffusivity in water | 3×10⁻¹⁰–3×10⁻⁹ m²/s | Cussler, *Diffusion* 3rd ed., app. A |
-| Protein diffusivity in water | 10⁻¹¹–1.5×10⁻¹⁰ m²/s | Cussler, app. A |
-| Dynamic viscosity of water | 0.5–1.5 mPa·s | IAPWS R12-08 |
-| Surface tension of water | 0.06–0.08 N/m | IAPWS R1-76 |
-| Speed of sound in water | 1400–1560 m/s | Del Grosso & Mader, *JASA* 52:1442 (1972) |
-| Speed of sound in air | 320–350 m/s | Cramer, *JASA* 93:2510 (1993) |
-| Sea-level atmospheric pressure | 95–105 kPa | ISO 2533 |
-| Earth surface gravity | 9.76–9.84 m/s² | WGS 84 normal gravity |
-| Visible wavelength | 380–750 nm | CIE S 017:2020 |
-| Non-covalent bond energy | 1–40 kJ/mol | Israelachvili 3rd ed., ch. 2 |
-| Covalent bond energy | 150–1000 kJ/mol | Atkins & de Paula 12th ed. |
-| ATP hydrolysis free energy | 40–60 kJ/mol | Milo & Phillips, ch. 4 |
-
-**Compare binding energies against `RT`, not against zero.** At 300 K, `RT` is 2.5 kJ/mol.
-A reported binding free energy of 1 kJ/mol is not a weak interaction; it is
-indistinguishable from thermal noise.
-
-## 5. The three errors this catches
-
-**A quantity of the wrong kind.** Kinematic viscosity (m²/s) where the formula needs
-dynamic (Pa·s) is the classic. Both are called "viscosity", both are tabulated for water,
-and they differ by a factor of ρ ≈ 1000. The dimensionality check refuses it before any
-number is computed:
-
-```
-error: viscosity must have dimensionality [mass] / ([length] * [time]),
-       but m²/s is [length] ** 2 / [time]
-```
-
-**A unit prefix slip.** Micro for milli is three decades. The magnitude bands catch it
-whenever the quantity is one the table knows.
-
-**An assumption used outside its regime.** Applying Poiseuille's law at `Wo = 20`, the
-lumped-capacitance model at `Bi = 5`, or Stokes drag at `Re_p = 30` all produce a number.
-The group tells you the number is meaningless.
-
-## 6. Caveats
-
-- The thresholds are **conventions with soft edges**, not physical constants. `Re = 2400`
-  in a very smooth pipe can stay laminar; `Re = 2000` with a disturbed inlet may not.
-- Every group assumes the geometry its correlation was fitted for. Check §1 before
-  trusting a classification.
-- The bands describe **typical observed values**, not physical limits. Extremophiles,
-  engineered materials, and pathological states legitimately sit outside them — which is
-  why the tool warns rather than refuses.
-- A `plausible` verdict means nothing contradicted the tables. It is not a correctness
-  proof, and it says nothing about whether the *measurement* was any good — for that,
-  see `references/gum-methodology.md`.
-
-## Sources
-
-Checked 2026-07-26:
-
-- White, *Fluid Mechanics*, 8th ed. — Reynolds, Mach, pipe-flow transition.
-- Deen, *Analysis of Transport Phenomena*, 2nd ed. — Péclet, Schmidt, boundary layers.
-- Incropera et al., *Fundamentals of Heat and Mass Transfer* — Biot, Fourier.
-- Bruus, *Theoretical Microfluidics* — capillary number, low-Reynolds flow.
-- Berg, *Random Walks in Biology* — diffusion times, the L² scaling.
-- Phillips et al., *Physical Biology of the Cell*, 2nd ed. — `k_BT` as the biological
-  energy scale.
-- Milo & Phillips, *Cell Biology by the Numbers* — biological magnitude bands;
-  [bionumbers.hms.harvard.edu](https://bionumbers.hms.harvard.edu/).
-- Israelachvili, *Intermolecular and Surface Forces*, 3rd ed. — Debye length, bond energies.
-- Cussler, *Diffusion*, 3rd ed. — diffusivity tables.
-- [CODATA internationally recommended values](https://physics.nist.gov/cuu/Constants/) —
-  reached through `scipy.constants`, never typed as literals.

package/skills/uncertainty-and-units/references/reporting-rules.md

@@ -1,133 +0,0 @@
-# Reporting rules
-
-A number without its uncertainty and without a statement of what that uncertainty means
-cannot be checked, compared, or reused. This file covers what has to accompany a
-reported result.
-
-## Round the uncertainty first
-
-JCGM 100:2008 7.2.6. The uncertainty is rounded to one or two significant digits, and
-the value is then rounded to that same decimal place — never the other way round, and
-never independently.
-
-```text
-12.34567 +/- 0.02345    ->    12.346 +/- 0.023
-12.34567 +/- 0.1        ->    12.35  +/- 0.10        (two digits, since 1 leads)
-1234     +/- 250        ->    1230   +/- 250
-```
-
-Two digits are the safe default. One digit is acceptable when the leading digit is 3 or
-more; rounding 0.14 to 0.1 changes it by 29%, which is why a leading 1 or 2 should keep
-two digits. `scripts/format_result.py` applies the rule and warns on that case.
-
-Trailing zeros in the uncertainty are significant and must be kept: `0.10`, not `0.1`.
-
-## Notations
-
-| Notation | Example | Where it is used |
-| --- | --- | --- |
-| Plus-minus | 12.346 ± 0.023 mm | prose, tables |
-| Concise / parenthetic | 12.346(23) mm | physics, CODATA, high-precision tables |
-| Scientific | (9.1093837139 ± 0.0000000028)e-31 kg | very large or small values |
-| Concise scientific | 9.1093837139(28)e-31 kg | constants |
-
-In concise notation the digits in parentheses apply to the last digits of the quoted
-value, so `12.346(23)` is 12.346 ± 0.023 and `1234(25)` is 1234 ± 25. When the
-uncertainty's last significant digit falls left of the decimal point the notation is
-ambiguous and the scientific form must be used instead.
-
-## What has to be stated alongside
-
-A bare `±` is ambiguous. Readers cannot tell a standard uncertainty from an expanded
-one, a standard deviation from a standard error, or a 95% interval from a 68% one. State:
-
-1. **Which quantity the number is** — combined standard uncertainty u_c, expanded
-   uncertainty U, standard deviation of a sample, standard error of a mean, or a
-   confidence interval.
-2. **The coverage factor k**, when U is reported.
-3. **The coverage probability** and how it was arrived at — from a normal assumption or
-   from effective degrees of freedom.
-4. **The effective degrees of freedom**, when they are small enough to matter (below
-   about 30).
-5. **The method** — GUM framework, Monte Carlo, or both with the validation outcome.
-
-The two standard forms:
-
-> m = 100.02147 g with a combined standard uncertainty of u_c = 0.35 mg.
-
-> m = (100.02147 ± 0.00079) g, where the number following the symbol ± is the numerical
-> value of an expanded uncertainty U = k·u_c with U determined from a combined standard
-> uncertainty u_c = 0.35 mg and a coverage factor k = 2.26 based on the t-distribution
-> for ν_eff = 9 degrees of freedom, and defines an interval estimated to have a level of
-> confidence of 95%.
-
-The second is verbose because it has to be. `scripts/format_result.py --coverage-factor`
-generates the sentence.
-
-## SD, SEM, and CI in figures
-
-An error bar is uninterpretable unless the caption says what it is, and the three
-common choices differ by more than a factor of two for typical n:
-
-| Bar | Answers | Shrinks with n |
-| --- | --- | --- |
-| Standard deviation | how much do individual observations scatter | no |
-| Standard error of the mean | how precisely is the mean located | yes, as 1/√n |
-| 95% confidence interval | plausible range for the population mean | yes |
-
-Choosing SEM because it looks tighter is a misrepresentation when the question is about
-spread. Every caption needs the bar's identity, n, and whether n counts biological or
-technical replicates. Two SEM bars that do not overlap do not establish a significant
-difference, and two 95% CIs that overlap slightly do not establish the absence of one.
-
-## Relative and absolute
-
-State which. A relative standard uncertainty is dimensionless and is written
-`u_r(y) = 0.0035` or `0.35%`; multiplying it by the value gives the absolute one. Mixing
-them in a single budget without conversion is a common arithmetic error — a "1%"
-component and a "0.2 mg" component cannot be combined until they are in the same form.
-
-For a product or quotient of independent quantities, relative uncertainties combine in
-quadrature; for a sum or difference, absolute ones do. Using the wrong one is the single
-most common propagation mistake, and it is why deriving the budget from sensitivity
-coefficients rather than from remembered rules is worth the extra step.
-
-## Results near zero or below a detection limit
-
-- Do not report a value with an uncertainty larger than itself as though it were a
-  measurement. Report the estimate and its uncertainty, and state that it is consistent
-  with zero.
-- Do not substitute zero, LOD, or LOD/2 for a non-detect without saying so; each choice
-  biases downstream statistics differently.
-- A negative estimate of a non-negative quantity is a legitimate measurement outcome and
-  should be reported as measured, not truncated. Truncating biases any subsequent
-  average.
-- LOD and LOQ are defined by a stated procedure (typically 3σ and 10σ of the blank).
-  Quote the procedure with the number.
-
-## Significant figures in intermediate work
-
-Round only at the point of reporting. Carrying rounded intermediates through a
-calculation accumulates error that the uncertainty budget does not account for, and it
-can shift the final digit. Keep full precision internally; apply
-`scripts/format_result.py` at the end.
-
-The same applies to constants: use `scipy.constants`, not a value typed from memory to
-four digits.
-
-## Conformity statements
-
-Deciding whether a result passes a specification is a separate step from measuring it,
-because a result within tolerance but with an uncertainty straddling the limit has not
-demonstrated conformity. ISO/IEC 17025 requires a documented decision rule; ILAC-G8
-describes guard-banded acceptance, where the acceptance limit is pulled inside the
-specification limit by a multiple of u_c chosen for the false-accept risk you will
-tolerate. Report the rule alongside the verdict.
-
-## Sources
-
-- JCGM 100:2008 (GUM), clause 7 — reporting uncertainty.
-- JCGM 101:2008 (GUM Supplement 1), clause 8 — numerical tolerance and validation.
-- NIST Technical Note 1297, *Guidelines for Evaluating and Expressing the Uncertainty of
-  NIST Measurement Results* — the source of the two standard sentence forms above.
-- ISO/IEC 17025:2017 clause 7.8.6 and ILAC-G8:09/2019 — decision rules and guard bands.

package/skills/uncertainty-and-units/references/uncertainties-recipes.md

@@ -1,167 +0,0 @@
-# uncertainties recipes
-
-Verified against uncertainties 3.2.3 with NumPy 2.5.1 and SciPy 1.18.0. The package
-performs first-order (linear) propagation with analytic derivatives, tracking
-correlations automatically through every operation. Everything it does is the GUM
-uncertainty framework; it does not perform Monte Carlo propagation and does not check
-whether linearization was appropriate.
-
-## Variables and the correlation they carry
-
-```python
-from uncertainties import ufloat
-
-x = ufloat(1.0, 0.1)
-x - x                    # 0.0+/-0        the same variable, perfectly correlated
-x - ufloat(1.0, 0.1)     # 0.00+/-0.14    two independent variables
-```
-
-That pair of lines is the whole design. A `ufloat` is an *identity*, not a number with
-an attached error bar, and the difference of a variable with itself is exactly zero.
-This is the correct answer, and it is why arithmetic on ufloats beats manual quadrature
-in any expression where a quantity appears more than once.
-
-The corollary is the most common defect:
-
-```python
-copy = ufloat(x.nominal_value, x.std_dev)   # a NEW, independent variable
-x - copy                                    # 0.00+/-0.14, not 0
-```
-
-Rebuilding a variable from `.nominal_value` and `.std_dev` throws away every correlation
-it carried. So does serializing to JSON and back, storing in a DataFrame column of
-floats, or passing through any interface that speaks in pairs of numbers.
-`scripts/audit_units.py` flags this construction as `UNC004`.
-
-## Correlated inputs
-
-```python
-import numpy as np
-from uncertainties import correlated_values, correlation_matrix, covariance_matrix
-
-cov = np.array([[0.04, 0.012],
-                [0.012, 0.09]])
-a, b = correlated_values([1.0, 2.0], cov)
-
-a + b                            # 3.0+/-0.4
-correlation_matrix([a, b])[0][1] # 0.19999999999999987
-```
-
-`correlated_values` is how a fit's covariance matrix enters the calculation intact.
-`correlation_matrix` returns a NumPy array; `covariance_matrix` returns a nested list —
-index it as `[i][j]`, not `[i, j]`.
-
-`correlated_values_norm` takes `[(value, std_dev), ...]` plus a *correlation* matrix
-instead of a covariance matrix, which is usually what a paper reports.
-
-## Functions
-
-Ordinary `math` and `numpy` functions have no derivative rule for these objects and
-fail, loudly on scalars and inside the ufunc loop on arrays:
-
-```python
-import math, numpy as np
-from uncertainties import umath, unumpy
-
-math.sqrt(a)   # TypeError: can't convert an affine function ... to float
-np.sqrt(a)     # TypeError: loop of ufunc does not support argument 0 of type AffineScalarFunc
-umath.sqrt(a)  # 1.00+/-0.10
-```
-
-`umath` mirrors `math`: sqrt, exp, log, log10, log1p, expm1, the trigonometric and
-hyperbolic functions and their inverses, atan2, hypot, degrees, radians, fabs, erf.
-
-For arrays, `unumpy` provides the wrapped versions plus constructors and accessors:
-
-```python
-arr = unumpy.uarray([1.0, 2.0], [0.1, 0.2])
-unumpy.sqrt(arr)             # [1.0+/-0.05 1.4142135623730951+/-0.07071067811865475]
-unumpy.nominal_values(arr)   # [1. 2.]
-unumpy.std_devs(arr)         # [0.1 0.2]
-np.mean(arr)                 # 1.50+/-0.11    -- works: object-array reduction
-np.sqrt(arr)                 # TypeError      -- fails: ufunc loop
-```
-
-The split is worth internalizing: reductions written in terms of Python arithmetic
-(`mean`, `sum`, `dot`) work on object arrays, while ufuncs do not. When in doubt use
-`unumpy`.
-
-## Formatting
-
-The format spec extends the standard one. `u` counts significant digits *in the
-uncertainty*, and the value is rounded to match:
-
-```python
-from uncertainties import ufloat
-v = ufloat(12.3456, 0.0234)
-
-f"{v:.2u}"    # 12.346+/-0.023
-f"{v:.2uS}"   # 12.346(23)          concise notation
-f"{v:.1uP}"   # 12.35±0.02          pretty Unicode
-f"{v:.2uL}"   # 12.346 \pm 0.023    LaTeX
-f"{ufloat(0.00012345, 0.0000023):.2ue}"   # (1.234+/-0.023)e-04
-```
-
-This handles the GUM rounding rule for you. `scripts/format_result.py` covers the cases
-this does not: an expanded uncertainty with a stated k, the accompanying sentence, and
-the warnings about reporting one digit when the leading digit is 1 or 2.
-
-## Where the uncertainty came from
-
-```python
-result = a**2 + b
-result.derivatives[a]        # 2.0 -- the sensitivity coefficient
-result.error_components()    # {variable: contribution} for every input
-```
-
-`error_components` is the uncertainty budget, keyed by the original variables. Sorting
-it descending tells you which input to improve.
-
-## Fitted parameters
-
-The covariance matrix from a fit is the correlation between parameters, and discarding
-it is a routine error:
-
-```python
-import numpy as np
-from scipy.optimize import curve_fit
-from uncertainties import correlated_values
-
-popt, pcov = curve_fit(model, x, y, sigma=sigma, absolute_sigma=True)
-slope, intercept = correlated_values(popt, pcov)   # keeps the correlation
-```
-
-Taking `np.sqrt(np.diag(pcov))` and building independent ufloats discards it, and for a
-straight-line fit the slope-intercept correlation is strongly negative — predictions
-near the centroid of the data come out far too uncertain.
-
-`absolute_sigma` decides what `pcov` means, and the default is not what most users
-assume:
-
-```python
-popt, pcov = curve_fit(f, x, y, sigma=sigma, absolute_sigma=False)  # default
-# pcov is rescaled by the reduced chi-square: parameter uncertainties absorb the
-# goodness of fit, and are identical to what you get by passing no sigma at all.
-
-popt, pcov = curve_fit(f, x, y, sigma=sigma, absolute_sigma=True)
-# pcov reflects the standard uncertainties you supplied.
-```
-
-On one synthetic straight-line fit the two give parameter standard deviations of
-`[0.0364, 0.2154]` and `[0.0477, 0.2820]` — a 31% difference, with no warning. Pass
-`absolute_sigma=True` whenever `sigma` holds real standard uncertainties;
-`scripts/audit_units.py` flags the omission as `UNC001`.
-
-## Limits
-
-- **First order only.** For a strongly nonlinear model the reported std_dev is the
-  linearized one, and the package cannot tell you that. Cross-check with
-  `scripts/propagate_uncertainty.py`, which runs Monte Carlo alongside.
-- **No distribution.** A ufloat carries a standard deviation, not a shape. Rectangular
-  and normal inputs with the same u are indistinguishable to it.
-- **No degrees of freedom.** Coverage factors are your problem; use
-  `scripts/uncertainty_budget.py`.
-- **`float()` fails**, deliberately, on anything with an uncertainty. Comparison
-  operators compare nominal values.
-- **Object arrays are slow.** For large arrays, propagate analytically or by Monte Carlo
-  rather than element-wise.