# Quickstart: a verified calculation

```bash
pip install noodlelab        # or: uv add noodlelab
```

```python
# drop.py
import noodlelab.verify as nv

with nv.record("drop test") as rec:
    h = rec.input("h", "2.00 ± 0.01 m", source="tape measure, lab book p. 4")
    g = rec.input("g", "9.81 ± 0.02 m/s^2", source="local gravity survey")
    t = rec.result("fall time", (2 * h / g) ** 0.5)  # (0.6386 ± 0.0017) s
    v = rec.result("impact speed", (2 * g * h) ** 0.5)  # (6.264 ± 0.017) m/s

    rec.require("""
        DRP-001 fall_time <= 1 s [Analysis]      # The drop shall take at most 1 s
        DRP-002 impact_speed <= 7 m/s [Analysis] # The part shall land below 7 m/s
    """)
    rec.verify("DRP-001", t)
    rec.verify("DRP-002", v)
    rec.close_to("v = g·t", v, g * t, rtol=1e-9)  # two routes to the same answer

print(rec.summary())
```

```console
$ noodlelab verify drop.py
✓ drop.py
  ✓ drop test: passed
    ✓ DRP-001: 0.6386 s meets ≤ 1 s (margin +0.3614 s, +36.1 %)
    ✓ DRP-002: 6.264 m/s meets ≤ 7 m/s (margin +0.7358 m/s, +10.5 %)
    ✓ v = g·t: (6.264 ± 0.017) m/s agrees with (6.264 ± 0.017) m/s (|Δ| = 0 m/s, ...)
    record: runs/20260926-101500-drop-test-1a2b3c4d/provenance.json
1 of 1 passed
```

## What you get

- **Units**: `h / g` is in s², and `(2 * h / g) ** 0.5` is in seconds. Adding
  metres to seconds raises an error. Convert with `.to("ms")`.
- **Uncertainty**: GUM propagation, with correlations kept (`t` and `v` both
  depend on `g` and `h`). `nv.budget(t)` shows each input's share, and
  `nv.fmt(t)` rounds as GUM 7.2.6 says.
- **Requirements with margins**: each check says how far inside or outside the
  limit the result is, in the requirement's unit and as a percentage.
- **A record**: `runs/<time>-drop-test-<id>/provenance.json` holds the inputs
  and their sources, the results, requirements, checks, the script's SHA-256,
  its git commit and whether it was dirty, the Python version and platform,
  and every installed package.
- **An audit**: `noodlelab verify` exits with 1 when a check failed or a
  requirement was never verified. It warns about results without units or
  uncertainty, inputs without a source, and code that was not committed.
  `--strict` makes those warnings fail too. `--json` gives the same verdict in
  a form an agent can parse.

## More

```python
nv.q("3 dB"), nv.q(12, "W")  # exact quantities
nv.measure(9.81, 0.02, "m/s^2", name="g")  # measured, labelled for budgets
nv.measure("1.2 ± 0.1 mm", distribution="rectangular")  # Type B, for Monte Carlo
nv.const.c, nv.constant("g0")  # named constants, with units (G, m_e...: CODATA ±)
g0 = rec.constant("g0")  # recorded as an input, its source filled in
nv.define_constant("rho_w", "998.2 kg/m^3", source="CRC Handbook")  # your own


@nv.traced  # calls recorded inside a record
def drag(rho, v, cd, area): ...


mc = nv.monte_carlo(lambda: 1 / nv.measure("1.0 ± 0.4"), 20_000)
mc.agrees, mc.message  # is the linear GUM result good enough?

rec.expect(0 < eff.m < 1, "efficiency is a fraction")  # a sanity check
rec.read("data/calibration.csv")  # its SHA-256 goes in the record
rec.output("plot.png")  # a path in the record's folder
rec.note("assumes small angles")  # caveats for the reader
nv.audit(nv.load("runs/.../provenance.json"))  # re-check a record later
```