calcs/wood-joist/codemap.md

# Codemap: worksheets

Typst-first structural calculation sheets. Hybrid calculations parse YAML inputs
through Pint, compute design values in Python, and present them in Typst.

Generated: 2026-08-19
Files indexed: 24

## Layout

```
worksheets/
├── README.md                           [doc]       — project conventions, template usage, hybrid pattern docs.
├── aisc-shapes-database-v15.0.xlsx     [asset]     — AISC section-property workbook consumed by steel-beam.
├── requirements.txt                    [config]    — Python deps: pyyaml, pytest, pint.
├── steel-beam.pdf                      [doc]       — reference worked example for the W6X8.5 lock case.
├── WOOD-JOISTS-BENDING-SHEAR-BEARING-DEFLECTION.pdf [doc]  — reference sheet for the new wood-joist calculation.
├── assets/
│   └── logo.png                        [asset]     — shared letterhead image resolved from the worksheets root.
├── lib/
│   └── sheet.typ                       [doc]       — shared letterhead, calc-line, check, check_service helpers; no calculation logic.
├── template/
│   ├── typst-only/
│   │   ├── README.md                   [doc]       — pure-Typst template instructions.
│   │   └── main.typ                    [logic]     — pure-Typst sample: arithmetic shown inline, no results.json.
│   └── typst-python/
│       ├── README.md                   [doc]       — hybrid template instructions.
│       ├── calc.py                     [logic]     — minimal YAML-driven compute(); writes results.json with values+checks.
│       ├── test_template.py            [test]      — locks one hand example with pytest.approx.
│       └── input.yaml                  [config]    — template fixture inputs.
├── calcs/
│   ├── shore-post/                     — pure-Typst reference calculation.
│   │   ├── shore-post.typ              [logic]     — tributary area, axial demand, AS550 shore-post capacity check.
│   │   ├── assets/tributary-areas.png  [asset]     — figure used by shore-post.typ.
│   │   └── generated/shore-post.pdf    [doc]       — last compiled artefact (regenerable).
│   ├── concrete-beam/                  — hybrid YAML numbers → Python → JSON → Typst.
│   │   ├── calc.py                     [logic]     — span, demand, Whitney block, phiMn, phiVc, min steel.
│   │   ├── test_concrete_beam.py       [test]      — locks example demands and capacities.
│   │   ├── input.yaml                  [config]    — plain-number inputs.
│   │   ├── beam.typ                    [logic]     — presents calc.py values; embeds beam sketch.
│   │   └── results.json                [state]     — last calc.py output (regenerable).
│   ├── concrete-beam2/                 — hybrid YAML quantities + Pint unit conversion.
│   │   ├── calc.py                     [logic]     — Pint-parses quantities; same procedure as concrete-beam.
│   │   ├── test_concrete_beam2.py       [test]      — locks Pint-parsed demands and capacities.
│   │   ├── input.yaml                  [config]    — unit-bearing inputs ("16 ft", "3000 psi").
│   │   ├── beam.typ                    [logic]     — presents calc.py values; embeds beam sketch.
│   │   └── results.json                [state]     — last calc.py output (regenerable).
│   ├── wood-joist/                     — hybrid YAML quantities + Pint → JSON → Typst (NDS 2018 ASD).
│   │   ├── calc.py                     [logic]     — section props, flexure (C_L), shear, bearing, deflection; reads YAML demands.
│   │   ├── test_wood_joist.py          [test]      — locks Pompano Beach example; queries <wood-joist-loads> and <wood-joist-results>.
│   │   ├── input.yaml                  [config]    — Pint-quantity checked demands (w, wL, M, V, R), span, geometry, NDS design values.
│   │   ├── beam.typ                    [logic]     — derives gravity loads (w, wL, M, V, R) and presents Python-checked values.
│   │   ├── results.json                [state]     — last calc.py output (regenerable).
│   │   └── generated/wood-joist.pdf    [doc]       — last compiled artefact (regenerable).
│   └── steel-beam/                     — hybrid YAML quantities + Pint + AISC XLSX loader.
│       ├── calc.py                     [logic]     — loads section from XLSX; AISC LTB, web shear, point-load deflection.
│       ├── test_steel_beam.py          [test]      — runs typst query(<load-demands>); locks W6X8.5 ground truth.
│       ├── input.yaml                  [config]    — Pint-quantity inputs (span, Mu, Vu, section label).
│       ├── beam.typ                    [logic]     — load determination shown in Typst; LTB/shear/deflection from Python.
│       └── results.json                [state]     — last calc.py output (regenerable).
└── tasks/                              [doc]       — Architect-written task specifications; one per builder task.
```

## Hot Spots

- `lib/sheet.typ` — shared by every sheet. Changing `calculation-sheet`, `calc-line`, or `check` breaks every compiled PDF.
- `aisc-shapes-database-v15.0.xlsx` — steel-beam fixture; column mapping in `calc.py:load_section` is brittle to schema changes.
- `calcs/steel-beam/calc.py` — single-source of truth for the steel-beam capacity numbers; test suite asserts exact values.
- `calcs/wood-joist/calc.py` — single source of truth for the NDS wood-joist capacity numbers; the test suite asserts the locked Pompano Beach values.
- `README.md` — documents the hybrid contract (Python computes, Typst presents). Keep the contract consistent across new sheets.

## Conventions

- Hybrid calculations: `input.yaml` (units via Pint) → `calc.py` (computes) → `results.json` (values + checks) → `beam.typ` (presents only). Wood-joist now derives loads in Typst (like steel-beam) while `calc.py` reads the checked demands. `check_service` is a presentation helper.
- Pure-Typst sheets are reserved for arithmetic the engineer wants to see inline; calculations with branching or iteration move to Python.
- The shared logo resolves only when sheets are compiled with `--root .` from the worksheets directory.