@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/uncertainty-and-units/references/domain-conversions.md

@@ -1,188 +0,0 @@
-# Domain conversions and dimensional blind spots
-
-Values below were produced with pint 0.25.3 and SciPy 1.18.0 (CODATA 2022). Anything
-marked *exact* is fixed by definition and carries zero uncertainty.
-
-## Dimensional analysis does not catch these
-
-Two quantities with the same dimensions convert freely, whether or not the conversion
-means anything.
-
-| Pair | Shared dimension | What pint does | Why it matters |
-| --- | --- | --- | --- |
-| gray and sievert | L²T⁻² | converts 1:1, silently | Sv includes a radiation weighting factor; the numbers coincide only for photons and electrons |
-| newton-metre and joule | ML²T⁻² | converts 1:1, silently | torque is a vector product, energy a scalar; adding them is meaningless |
-| hertz and becquerel | T⁻¹ | converts 1:1, silently | one is periodic, the other stochastic |
-| radian and dimensionless | none | radians vanish | `sin(x)` needs radians; a degrees value that lost its unit is silently wrong |
-| mol/L and mol/kg | different | raises | molarity and molality are genuinely different quantities |
-| mg/L and ppm | different | raises | equal only for dilute aqueous solutions near 1 g/mL |
-
-The last two raise because they *are* dimensionally distinct. The first four are the
-dangerous ones: no tool will warn you.
-
-## Energy ladder
-
-Molecular science quotes the same energy in at least six units, three of which are
-per-mole and therefore need the Avogadro constant.
-
-| From | To | Factor |
-| --- | --- | --- |
-| 1 eV | kJ/mol | 96.48533212331002 |
-| 1 hartree | eV | 27.21138624598103 |
-| 1 hartree | kcal/mol | 627.5094740628942 |
-| 1 cm⁻¹ | eV | 1.2398419843320026e-4 |
-| 1 cm⁻¹ | K (as E/k_B) | 1.4387768775039336 |
-| k_B T at 298.15 K | eV | 0.02569257912108585 |
-| k_B T at 298.15 K | kJ/mol | 2.478957029602389 |
-| 1 cal (thermochemical) | J | 4.184 (exact) |
-| 1 cal_IT | J | 4.1868 (exact) |
-
-Two traps. First, **per-mole and per-particle units are not dimensionally
-interchangeable**: eV is an energy, kJ/mol is an energy per amount of substance, and the
-conversion needs N_A. Pint will refuse `Q(1, "eV").to("kJ/mol")` and accept
-`Q(1, "eV * N_A").to("kJ/mol")`. Second, **there are two calories** and a factor of
-1.00067 between them; thermochemical is the default in chemistry, IT in engineering.
-
-```python
-Q(1, "eV * N_A").to("kJ/mol")            # 96.48533212331002 kilojoule / mole
-Q(1, "1/cm").to("eV", "sp")              # 0.00012398419843320026 electron_volt
-Q(298.15, "K").to("eV", "boltzmann")     # 0.02569257912108585 electron_volt
-```
-
-## Spectroscopy
-
-Wavelength, frequency, wavenumber, and photon energy are related by physics, not by
-dimensional analysis, and the relations are *reciprocal* — an uncertainty does not
-convert by the same factor as the value.
-
-```python
-Q(532, "nm").to("THz", "sp")     # 563.5196578947367 terahertz
-Q(532, "nm").to("1/cm", "sp")    # 18796.992481203004 / centimeter
-Q(532, "nm").to("eV", "sp")      # 2.3305300457368467 electron_volt
-```
-
-Because E = hc/λ, a constant wavelength uncertainty becomes an energy uncertainty that
-scales as 1/λ². Propagate through the relation, do not scale the uncertainty by the
-value's conversion factor. `scripts/convert_units.py --uncertainty` does this with the
-conversion's local derivative.
-
-The `sp` context assumes vacuum unless given a refractive index: `n=1.33` for water
-shifts a 532 nm frequency from 563.5 THz to 423.7 THz.
-
-## Concentration
-
-| Quantity | Unit | Depends on |
-| --- | --- | --- |
-| Molarity | mol/L | temperature, through solution volume |
-| Molality | mol/kg solvent | nothing — preferred for thermodynamics |
-| Mole fraction | dimensionless | nothing |
-| Mass fraction, ppm(m/m) | dimensionless | nothing |
-| Volume fraction, ppm(v/v) | dimensionless | temperature |
-| Mass concentration | mg/L, g/L | temperature |
-
-"ppm" alone is ambiguous: mass/mass, volume/volume, and mol/mol differ by the ratio of
-densities or molar masses. In environmental water chemistry ppm conventionally means
-mg/L, which equals mg/kg only because dilute water is close to 1 kg/L. In gas analysis
-it conventionally means volume/volume. State which.
-
-Pint treats `ppm` and `percent` as plain dimensionless scale factors (1e-6 and 0.01),
-which is right for arithmetic and gives no protection against mixing the three senses.
-Defining `ureg.define("ppm_v = 1e-6 = ppmv")` as a distinct unit does give protection.
-
-Mass and amount of substance need the `chemistry` context and a molar mass:
-
-```python
-Q(1, "g").to("mol", "chemistry", mw=Q(180.156, "g/mol"))   # 0.005550744909966918 mole
-```
-
-## Pressure
-
-| From | To Pa | Note |
-| --- | --- | --- |
-| 1 atm | 101325 | exact |
-| 1 bar | 100000 | exact |
-| 1 torr | 133.32236842105263 | atm/760, exact by definition |
-| 1 psi | 6894.7572931683635 | |
-| 1 mmHg | 133.322387415 | *not* identical to torr, differs in the 8th digit |
-
-**Gauge and absolute pressure are different quantities and no unit library models the
-difference.** "psig" and "psia" have the same dimensions; a gauge reading needs the
-ambient pressure added before it can be used in a gas law. Vacuum work, autoclave
-protocols, and chromatography backpressures are where this bites.
-
-## Radiation, magnetism, rotation
-
-```python
-Q(1, "Ci").to("Bq")               # 37000000000.0 becquerel   (exact by definition)
-Q(1, "gauss").to("T", "Gaussian") # 9.999999999338245e-05 tesla
-Q(1, "rpm").to("rad/s")           # 0.10471975511965977 radian / second
-```
-
-Gauss fails *without* the Gaussian context: CGS electromagnetic units have different
-dimensions from SI ones, not merely different scales. Magnetic field strength H (A/m,
-oersted) and magnetic flux density B (T, gauss) are distinct quantities that literature
-routinely calls "the field".
-
-## Mass spectrometry
-
-The unified atomic mass unit and the dalton are the same thing:
-1 Da = 1.66053906892e-27 kg (CODATA 2022, relative standard uncertainty 3.1e-10).
-
-m/z is conventionally reported as a dimensionless number: the ratio of mass in daltons
-to charge number. The thomson (Th) exists but is not SI and is rarely used. Treating m/z
-as a mass is wrong for any ion with z > 1, which is most of a protein spectrum.
-
-## Logarithmic quantities
-
-pH, pKa, dB, and magnitudes are logarithms of ratios. They do not add, average, or
-propagate like ordinary quantities:
-
-- the mean of pH 5 and pH 7 is not pH 6 — averaging requires converting to
-  concentration, averaging, and converting back;
-- a standard deviation in pH units is a *relative* standard deviation in concentration;
-- adding two dB quantities multiplies the underlying linear quantities (see
-  `pint-recipes.md`);
-- decibel scales differ by reference: dBm references 1 mW, dBW references 1 W, dBV
-  references 1 V, and dB alone references nothing until you say so.
-
-## Temperature
-
-Kelvin and rankine are ratio scales and behave normally. Celsius and Fahrenheit are
-interval scales: 20 degC is not "twice" 10 degC, and their differences live in
-`delta_degC` / `delta_degF`. See `pint-recipes.md` for what pint permits.
-
-Absolute zero is exactly 273.15 K below 0 degC — `scipy.constants.zero_Celsius`.
-
-## Constants: which values, and which uncertainties
-
-The 2019 SI redefinition fixed several constants **exactly**, so their relative standard
-uncertainty is zero and no future CODATA release will change them:
-
-| Constant | Exact value |
-| --- | --- |
-| speed of light in vacuum, c | 299792458 m/s |
-| Planck constant, h | 6.62607015e-34 J/Hz |
-| elementary charge, e | 1.602176634e-19 C |
-| Boltzmann constant, k | 1.380649e-23 J/K |
-| Avogadro constant, N_A | 6.02214076e23 /mol |
-
-Everything else is a measured recommended value that moves between CODATA releases —
-electron mass, the gravitational constant, the fine-structure constant, the Rydberg
-constant, and every derived quantity built from them.
-
-```python
-import scipy.constants as constants
-
-constants.value("electron mass")       # 9.1093837139e-31
-constants.unit("electron mass")        # kg
-constants.precision("electron mass")   # 3.07e-10  relative standard uncertainty
-constants.precision("Planck constant") # 0.0       exact by definition
-```
-
-`scipy.constants` in SciPy 1.18.0 defaults to **CODATA 2022**; SciPy 1.11 and earlier
-served CODATA 2018. Hard-coding a constant pins you to whichever release you copied it
-from and discards its uncertainty entirely. `scripts/audit_units.py` flags literals that
-match a known constant (`CONST001`).
-
-Note also that `constants.precision` returns a *relative* standard uncertainty. The
-absolute standard uncertainty is `value * precision`.

package/skills/uncertainty-and-units/references/gum-methodology.md

@@ -1,219 +0,0 @@
-# GUM methodology
-
-The *Guide to the Expression of Uncertainty in Measurement* (JCGM 100:2008, "the GUM")
-and its Supplement 1 (JCGM 101:2008, the Monte Carlo method) define how an uncertainty
-is evaluated, combined, and reported. This file covers the parts that decide whether a
-number is defensible.
-
-## Vocabulary that has to stay straight
-
-| Term | Symbol | Meaning |
-| --- | --- | --- |
-| Measurand | Y | the quantity intended to be measured |
-| Estimate | y | the value obtained for it |
-| Standard uncertainty | u(x) | uncertainty of an input, expressed as a standard deviation |
-| Combined standard uncertainty | u_c(y) | standard uncertainty of the result |
-| Expanded uncertainty | U | k * u_c(y) |
-| Coverage factor | k | multiplier chosen for a stated coverage probability |
-| Coverage probability | p | probability that the interval contains the measurand |
-
-"Error" and "uncertainty" are not synonyms. An error is a single unknowable difference
-from the true value; an uncertainty is a dispersion. "Accuracy" and "precision" are
-qualitative words in the GUM's vocabulary and never carry a number.
-
-## Type A and Type B are methods, not qualities
-
-The distinction is only about *how the uncertainty was evaluated*. Neither is more
-reliable than the other, and both produce a standard uncertainty on the same footing.
-
-**Type A** — evaluated from a statistical analysis of repeated observations.
-
-For n independent readings with experimental standard deviation s(q):
-
-```text
-u(q_bar) = s(q) / sqrt(n)          degrees of freedom: nu = n - 1
-```
-
-The standard uncertainty of the *mean* is what enters the budget when the reported
-value is a mean. Using s(q) itself overstates it by sqrt(n); using `numpy.std` without
-`ddof=1` understates s(q) itself. Both mistakes are common and neither is visible in
-the output.
-
-Pooling repeatability across several runs raises the degrees of freedom and is worth
-doing when the same instrument and procedure produced them.
-
-**Type B** — evaluated by any other means: a calibration certificate, a manufacturer's
-specification, a handbook value, a previous measurement, or documented judgement.
-
-The stated quantity is converted to a standard uncertainty by dividing by a factor that
-depends on what the statement means:
-
-| What the source states | Assumed density | Divisor | u |
-| --- | --- | --- | --- |
-| Expanded uncertainty U with coverage factor k | normal | k | U / k |
-| 95% confidence interval, no k given | normal | 1.96 | half-width / 1.96 |
-| A standard uncertainty | normal | 1 | as stated |
-| Limits ±a, any value equally likely | rectangular | sqrt(3) | a / sqrt(3) |
-| Limits ±a, centre far more likely | triangular | sqrt(6) | a / sqrt(6) |
-| Limits ±a, extremes more likely (sinusoidal drift, cyclic error) | arcsine | sqrt(2) | a / sqrt(2) |
-
-Rectangular is the default when a specification gives limits and says nothing about the
-distribution inside them. Digital resolution of one least significant digit d gives
-half-width a = d/2, so u = d / (2 sqrt(3)).
-
-The most frequent Type B error is treating a certificate's expanded uncertainty as a
-standard uncertainty: it silently doubles the reported interval.
-
-## Law of propagation of uncertainty
-
-For a model Y = f(X_1, ..., X_N) with uncorrelated inputs (JCGM 100:2008 equation 10):
-
-```text
-u_c(y)^2 = sum_i ( df/dx_i )^2 * u(x_i)^2
-```
-
-with correlated inputs (equation 13):
-
-```text
-u_c(y)^2 = sum_i ( df/dx_i )^2 u(x_i)^2
-         + 2 * sum_i sum_{j>i} (df/dx_i)(df/dx_j) u(x_i) u(x_j) r(x_i, x_j)
-```
-
-The partial derivatives are the **sensitivity coefficients** c_i. They carry units, and
-`c_i * u(x_i)` is the contribution of that input expressed in the units of the result.
-Comparing contributions, not raw uncertainties, is what tells you where to spend effort.
-
-Correlation is not exotic. It appears whenever two inputs were calibrated against the
-same standard, corrected with the same reference value, measured with the same
-instrument, or derived from a common fit. Ignoring a positive correlation understates
-u_c; ignoring a negative one overstates it. In a difference of two similar quantities
-measured the same way, the correlation is the whole point — it is what makes the
-difference more precise than either term.
-
-## Degrees of freedom and the coverage factor
-
-k = 2 is a convention, not a law. It corresponds to p ≈ 95% only when the effective
-degrees of freedom are large. The Welch-Satterthwaite formula (JCGM 100:2008 G.2b)
-gives them:
-
-```text
-nu_eff = u_c(y)^4 / sum_i ( (c_i u(x_i))^4 / nu_i )
-```
-
-Components evaluated as Type B from a specification are conventionally assigned
-infinite degrees of freedom and drop out of the denominator. A single Type A component
-from a handful of readings can pull nu_eff low enough that k rises well above 2:
-
-| nu_eff | k for p = 95% |
-| --- | --- |
-| 2 | 4.30 |
-| 5 | 2.57 |
-| 10 | 2.23 |
-| 20 | 2.09 |
-| 50 | 2.01 |
-| infinite | 1.96 |
-
-If the dominant component came from five readings, reporting k = 2 understates the
-interval by about a quarter. The formula assumes uncorrelated inputs; with correlation
-it is an approximation with no established validity.
-
-## When the GUM framework is not applicable
-
-The framework linearizes f about the estimates. That is fine when the model is close to
-linear across the input uncertainties, and wrong when it is not. Specifically, it
-breaks down when:
-
-- the model is significantly nonlinear over ±2u of an input — squares, reciprocals,
-  ratios of comparable quantities, exponentials;
-- a single non-normal component dominates, so the output is not approximately normal
-  and k from a t-distribution does not deliver the claimed coverage;
-- the output distribution is asymmetric, which the symmetric interval y ± U cannot
-  represent;
-- an input's relative uncertainty is large (above roughly 20-30%), where the second-order
-  terms the expansion drops are no longer negligible;
-- the model has a bound the interval crosses — a variance, a concentration, or a
-  squared quantity whose GUM interval extends below zero.
-
-## Monte Carlo propagation (JCGM 101:2008)
-
-The supplement propagates the input distributions rather than their standard
-deviations. The procedure is:
-
-1. assign a probability density to each input, not merely a standard uncertainty;
-2. draw M samples from the joint density, respecting any correlation;
-3. evaluate the model for each draw;
-4. take the mean as the estimate and the standard deviation as u_c;
-5. take a coverage interval from the sorted output.
-
-Two intervals are defined and they differ for an asymmetric output. The
-**probabilistically symmetric** interval cuts (1-p)/2 from each tail. The **shortest**
-interval is the narrowest one containing the fraction p; it is the honest choice when
-the output is skewed, and identical to the other when it is not.
-
-M = 10^6 is the usual starting point for a 95% interval; JCGM 101 also defines an
-adaptive procedure that keeps drawing until the results are stable to within the
-numerical tolerance below. Fewer than 10^4 trials cannot resolve a 95% interval's
-endpoints reliably.
-
-## The validation test that decides which answer to report
-
-JCGM 101 clause 8 is the reason to run both methods rather than choosing one. Write u_c
-from the GUM framework to n_dig significant digits (1 or 2) as c × 10^L. The numerical
-tolerance is half of that last digit:
-
-```text
-delta = 0.5 * 10^L
-```
-
-Compare the endpoints of the two coverage intervals:
-
-```text
-d_low  = | (y - U)      - y_low_MC  |
-d_high = | (y + U)      - y_high_MC |
-```
-
-If both are at or below delta, the linearization is validated and the GUM framework
-result may be reported. If either exceeds delta, the framework is not validated for
-this model, and the Monte Carlo result is what should be reported.
-
-`scripts/propagate_uncertainty.py` runs both methods and applies this test. Two
-outcomes worth understanding:
-
-**Rectangular inputs, linear model.** A model dominated by rectangular contributions
-fails validation even though it is perfectly linear: the true output distribution is
-closer to trapezoidal than normal, and k = 1.96 over-covers. The GUM value and u_c are
-right; the interval is too wide.
-
-**Nonlinear model.** For y = x^2 with x = 1.0 ± 0.5, the framework gives y = 1.0,
-u_c = 1.0, and a 95% interval of [-0.96, 2.96] — an interval that is largely negative
-for a squared quantity. Monte Carlo gives a mean of 1.25, u_c = 1.06, and a shortest
-95% interval of [0, 3.32]. The framework result is not merely imprecise; it is outside
-the range the model can produce.
-
-## Order of operations
-
-1. Write the measurement model explicitly, including every correction, even those whose
-   value is zero. A correction with an estimated value of zero still has an uncertainty,
-   and leaving it out of the model leaves its uncertainty out of the budget.
-2. Assign each input an estimate, a standard uncertainty, a distribution, and degrees of
-   freedom.
-3. Identify correlations before combining anything.
-4. Compute sensitivity coefficients and the budget.
-5. Combine, and check the linearization against Monte Carlo.
-6. Choose k from nu_eff, not by habit.
-7. Round the uncertainty first, then the value (see `reporting-rules.md`).
-
-## Recurring defects
-
-- Reporting a standard deviation of readings as the uncertainty of their mean.
-- Dividing a certificate's expanded uncertainty by nothing, or by 2 when the certificate
-  states a different k.
-- Omitting a correction from the model because its value is negligible, thereby omitting
-  its uncertainty too.
-- Combining relative and absolute uncertainties without converting.
-- Treating resolution and repeatability as independent when the resolution is what
-  limits the repeatability — double counting.
-- Quoting k = 2 with an effective degrees of freedom below 10.
-- Applying the framework to a strongly nonlinear model and never checking.
-- Propagating uncertainty through a fitted model without using the fit's covariance
-  matrix, which discards the correlation between the fitted parameters.

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

@@ -1,228 +0,0 @@
-# Pint recipes
-
-Verified against pint 0.25.3 with NumPy 2.5.1. Every output below was produced by
-running the snippet.
-
-## One registry per process
-
-A `Quantity` belongs to the registry that created it. Two registries produce quantities
-that cannot interact, and the failure is a bare `ValueError` far from the cause:
-
-```python
-import pint
-
-first = pint.UnitRegistry()
-second = pint.UnitRegistry()
-first.Quantity(1, "m") + second.Quantity(1, "m")
-# ValueError: Cannot operate with Quantity and Quantity of different registries.
-```
-
-This bites hardest across module boundaries, where each module innocently creates its
-own registry at import time, and after unpickling, because a pickled quantity is
-restored against the *application* registry rather than the one that created it.
-
-Build one registry and share it, or use the application registry everywhere:
-
-```python
-import pint
-
-ureg = pint.UnitRegistry()
-pint.set_application_registry(ureg)
-
-# in every other module
-ureg = pint.get_application_registry()
-```
-
-## Offset units
-
-Degrees Celsius and Fahrenheit measure a point on a scale, not an amount, so
-multiplication and addition are undefined for them. Pint refuses rather than guessing:
-
-```python
-Q = ureg.Quantity
-Q(20, "degC") * 2
-# OffsetUnitCalculusError: Ambiguous operation with offset unit (degree_Celsius).
-Q(20, "degC") + Q(5, "degC")
-# OffsetUnitCalculusError: Ambiguous operation with offset unit (...).
-```
-
-The delta units carry temperature *differences*, and mixed arithmetic works:
-
-```python
-Q(20, "degC") + Q(5, "delta_degC")   # 25 degree_Celsius
-Q(25, "degC") - Q(20, "degC")        # 5 delta_degree_Celsius
-```
-
-Note the second line: subtracting two absolute temperatures yields a delta unit
-automatically, which is correct and often surprising downstream.
-
-An uncertainty on a temperature is always a difference. `u = 0.5 degC` means
-`0.5 delta_degC`; converting it to Fahrenheit multiplies by 9/5 and applies no offset,
-giving `0.9 delta_degF`. Converting the *value* 20 degC to Fahrenheit applies the
-offset and gives 68 degF. Two different conversions on the same line of a report.
-
-`pint.UnitRegistry(autoconvert_offset_to_baseunit=True)` makes arithmetic proceed by
-converting to kelvin first. It removes the exception, not the ambiguity; enable it
-deliberately, not to silence an error.
-
-## Logarithmic units
-
-Pint models dB, dBm, and friends as non-multiplicative units, and `+` on them means
-what it means in log space — multiplication of the underlying linear quantities:
-
-```python
-Q(10, "dBm").to("mW")        # 10.000000000000002 milliwatt
-Q(10, "dBm") + Q(10, "dBm")  # 0.00010000000000000005 kilogram**2 * meter**4 / second**6
-```
-
-The second line is 10 mW × 10 mW = 10^-4 W², not 20 mW and not 13 dBm. Nothing raises.
-Convert to a linear unit, do the arithmetic, convert back.
-
-## Contexts
-
-Some conversions are physical relations rather than dimensional identities. Pint
-performs them only inside a named context, which is a feature: it forces the physics to
-be stated.
-
-```python
-Q(532, "nm").to("THz", "sp")     # 563.5196578947367 terahertz
-Q(532, "nm").to("1/cm", "sp")    # 18796.992481203004 / centimeter
-Q(532, "nm").to("eV", "sp")      # 2.3305300457368467 electron_volt
-Q(532, "nm").to("THz")           # DimensionalityError
-
-Q(1, "g").to("mol", "chemistry", mw=Q(180.156, "g/mol"))   # 0.005550744909966918 mole
-Q(298.15, "K").to("eV", "boltzmann")                       # 0.02569257912108585 electron_volt
-Q(1, "gauss").to("T", "Gaussian")                          # 9.999999999338245e-05 tesla
-```
-
-The registry ships `spectroscopy` (`sp`), `chemistry` (`chem`), `boltzmann`, `energy`,
-`textile`, `Gaussian` (`Gau`), and `ESU` (`esu`). `ureg.enable_contexts("sp")` turns one
-on for every subsequent conversion and `ureg.disable_contexts()` turns it off again;
-prefer passing the context per call so the assumption stays visible at the point of use.
-
-The spectroscopy context accepts a refractive index `n`, defaulting to 1 (vacuum). It
-matters more than it looks:
-
-```python
-Q(532, "nm").to("THz", "sp")            # 563.5196578947367 terahertz
-Q(532, "nm").to("THz", "sp", n=1.33)    # 423.69899089829823 terahertz
-```
-
-Note that `gauss` fails without the Gaussian context: CGS electromagnetic units have
-different *dimensions* from SI ones, not merely different scales.
-
-## Stripping the unit
-
-`.magnitude` returns whatever number the quantity happens to be carrying, in whatever
-unit it happens to be in. That is the single most common way a unit error enters a
-correct-looking program:
-
-```python
-length = (12.7 * ureg.mm).magnitude          # 12.7 -- but of what?
-length = (12.7 * ureg.mm).to("m").magnitude  # 0.0127 metres, stated
-length = (12.7 * ureg.mm).m_as("m")          # same, shorter
-```
-
-Always name the unit at the point of extraction. `m_as` exists precisely so there is no
-excuse.
-
-## Boundary enforcement
-
-Rather than sprinkling conversions through a function, convert once at its boundary:
-
-```python
-@ureg.wraps("J", ("N", "m"))
-def work(force, distance):
-    return force * distance
-
-work(ureg.Quantity(2, "N"), ureg.Quantity(300, "cm"))   # 6.0 joule
-```
-
-`wraps` strips the declared units on the way in and reattaches the result unit on the
-way out, so the body is plain floats and stays fast. It defaults to `strict=True`,
-which rejects bare numbers:
-
-```python
-work(2.0, 3.0)
-# ValueError: A wrapped function using strict=True requires quantity or a string
-# for all arguments with not None units.
-```
-
-`strict=False` accepts bare numbers and assumes they are already in the declared units.
-That is convenient and it is also exactly the assumption that unit tracking exists to
-avoid; use it only at an edge you control.
-
-`check` validates dimensionality without converting:
-
-```python
-@ureg.check("[length]", "[time]")
-def speed(distance, elapsed):
-    return distance / elapsed
-
-speed(ureg.Quantity(10, "kg"), ureg.Quantity(2, "s"))
-# DimensionalityError: Cannot convert from '10 kilogram' ([mass]) to 'a quantity of' ([length])
-```
-
-## NumPy interoperability
-
-A quantity can wrap an array, and most ufuncs and many array functions are supported:
-
-```python
-import numpy as np
-
-a = ureg.Quantity(np.array([1.0, 2.0, 3.0]), "m")
-np.mean(a)                                             # 2.0 meter
-np.concatenate([a, ureg.Quantity(np.array([100.0]), "cm")])   # [1.0 2.0 3.0 1.0] meter
-np.concatenate([a, np.array([1.0])])
-# DimensionalityError: Cannot convert from 'dimensionless' to 'meter'
-```
-
-Note that the mixed concatenation converted centimetres to metres correctly, and the
-bare array was rejected rather than assumed. Both behaviours are what you want.
-
-Wrapped arrays carry per-operation overhead. In an inner loop, convert at the boundary
-with `wraps` or `m_as` and compute on raw arrays.
-
-## Custom units and definitions
-
-```python
-ureg.define("cell = [cell_count] = cells")
-ureg.define("od600 = [optical_density]")
-ureg.define("percent_v_v = 0.01 = %v/v")
-```
-
-Defining a new base dimension in square brackets makes it dimensionally distinct from
-everything else, which is the point: `cells / mL` will then refuse to be added to
-`particles / mL`. Load a whole file of them with `ureg.load_definitions("units.txt")`.
-
-## Formatting
-
-```python
-q = ureg.Quantity(1.2345, "kg*m/s**2")
-f"{q}"          # 1.2345 kilogram * meter / second ** 2
-f"{q:~}"        # 1.2345 kg * m / s ** 2
-f"{q:.3f~P}"    # 1.234 kg·m/s²
-f"{q:~L}"       # 1.2345\ \frac{\mathrm{kg} \cdot \mathrm{m}}{\mathrm{s}^{2}}
-```
-
-`~` gives short unit symbols, `P` pretty Unicode, `L` LaTeX, `C` compact ASCII. Numeric
-format specs come first and behave as usual.
-
-## With uncertainties
-
-The two libraries compose: a `ufloat` magnitude inside a pint quantity converts and
-formats correctly.
-
-```python
-from uncertainties import ufloat
-
-q = ufloat(2.5, 0.1) * ureg.meter
-q.to("cm")         # 250+/-10 centimeter
-f"{q:.2uS}"        # 2.50(10) meter
-```
-
-## Related packages
-
-`pint-pandas` provides a pandas extension dtype so a DataFrame column carries a unit;
-`pint-xarray` does the same for xarray. Both are separate installs and both inherit the
-one-registry rule.