calcs/wood-joist/PROJECT_STATE.md

Project State: Wood Joist Analysis

Last updated: 2026-08-20

Overview

New hybrid (Typst + Python) calculation at calcs/wood-joist/ that analyzes an existing wood joist under uniform gravity loads per NDS 2018 Allowable Stress Design (ASD). Four checks are covered:

1. Flexure (bending) — NDS 3.3 (beam stability factor C_L)
2. Shear — NDS 3.4
3. Bearing (compression perpendicular to grain) — NDS 3.10
4. Serviceability (deflection) — NDS 3.5, limits L/240 (total) and L/360 (live)

The default input.yaml reproduces a reference worked example ("Analysis for existing wood joists under shoring loads", Conemco Engineering, project "Pompano Beach") exactly. The pytest suite locks those numbers.

Architecture decisions

• Hybrid pattern (same as steel-beam): input.yaml (Pint unit-bearing quantities) → calc.py (computes, writes results.json) → beam.typ (presents only, no recomputation) → compiled PDF.
• results.json shape (unchanged contract): {tool, version, project, prepared_by, values, checks}. tool = "wood_joist", version = "0.1".
• Pint units: quantities are quoted strings in YAML (e.g. "25 psf", "9 ft"). calc.py converts with a quantity() helper identical in spirit to steel-beam/calc.py. Dimensionless adjustment factors are plain floats.
• calc.py CLI mirrors steel-beam: --input, --output, --stdout flags; runnable as python calcs/wood-joist/calc.py with no args.
• NDS 2018 is the governing standard and edition. All clause references are to NDS 2018.
• beam.typ imports from ../../lib/sheet.typ and reads results.json (no recomputation). Compiled with --root . from the worksheets root so the shared logo resolves.

2026-08-20 change: load determination moved to Typst (user-approved)

This change moves wood-joist gravity-load determination from Python to Typst, mirroring the steel-beam pattern. No engineering equations changed — only where load determination lives. The Pompano Beach benchmark values are unchanged.

• beam.typ determines loads inline. It binds DL = 25 psf, LL = 50 psf, span L = 9 ft, spacing B = 13 ft as Typst #let values, then derives w = (DL + LL)·B, wL = LL·B, M = w·L²/8, V = w·L/2, R = V. These are emitted as a Typst metadata label <wood-joist-loads> with fields w_plf, wL_plf, M_ftlbf, V_lbf, R_lbf. beam.typ presents both the Typst load-derived values and the Python-checked values (like steel-beam's M_u,load vs M_u,design), and the test suite reconciles them via the metadata query.
• New input.yaml contract. DL, LL, and spacing are removed. The checked demands are supplied as Pint-quantity strings: w: "975 plf", wL: "650 plf", M: "9871.875 ft * lbf", V: "4387.5 lbf", R: "4387.5 lbf". span is kept (Python needs it for the L/240 and L/360 deflection limits). All other keys are unchanged (width, depth, bearing_length, bearing_end_distance, unbraced_length, species_grade, NDS reference values, adjustment factors, project, prepared_by).
• calc.py reads demands. It no longer performs load-path arithmetic. w_plf, wL_plf, M_ftlbf, V_lbf, R_lbf come from quantity() on the YAML demand keys. Section properties, all NDS 2018 ASD checks, and the {tool, version, project, prepared_by, values, checks} contract are unchanged (tool = "wood_joist"). values no longer includes DL_psf, LL_psf, or spacing_ft.
• check_service added to lib/sheet.typ as a sibling of check. Signature check_service(label, acting, allowed, unit: "", ok: auto). Identical layout (label, OK/NOT OK badge, colored box, ratio) but the left column reads Acting / Allowed (instead of Demand / Capacity) and the ratio is labeled Utilization (instead of D/C). Used only by the two deflection checks in calcs/wood-joist/beam.typ; flexure, shear, and bearing keep check.
• Convention change. The inherited "lib/sheet.typ must not be modified" convention is superseded by this explicit user request. The change is additive only: check is unchanged and no other sheet (steel-beam, concrete-beam, concrete-beam2, shore-post) is modified.

Pinned benchmark (unchanged): w 975 plf, wL 650 plf, M 9871.88 ft·lbf (exact 9871.875), V 4387.5 lbf, R 4387.5 lbf; flexure util 0.938, shear util 0.66, bearing util 0.772, Δ_total 0.339 in, Δ_live 0.226 in.

Engineering decisions (pinned for the builder)

The equations are fully pinned by the reference worked example (every intermediate value and formula is supplied). No separate engineering specifier pass was required; the equations reproduce NDS 2018 directly and the clause references are recorded here and in tasks/001. The reviewer task (tasks/005) still verifies the engineering specification.

Section properties (rectangular joist)

• A = b·d
• I_x = b·d³ / 12
• S_x = b·d² / 6 (= 2·I_x / d)

Check 1 — Flexure (NDS 3.3)

• Slenderness: R_B = sqrt(l_e · d / b²) (NDS 3.3.3.7). Require R_B < 50. If R_B >= 50, calc.py raises ValueError (member needs lateral bracing; the C_L equation is out of scope).
• F*_b = F_b · C_D · C_M · C_t · C_F · C_i · C_r (all factors except C_L, C_fu).
• F_bE = 1.20 · E'_min / R_B²
• C_L = (1 + F_bE/F*_b)/1.9 − sqrt(((1 + F_bE/F*_b)/1.9)² − (F_bE/F*_b)/0.95) (NDS 3.3.3, c_b = 0.95 for sawn lumber). Formula yields C_L ≤ 1.0.
• F'_b = F*_b · C_L · C_fu
• f_b = M / S_x (M in lbf·in)
• Allowable moment M_a = S_x · F'_b (reported in ft·lbf).

Check 2 — Shear (NDS 3.4)

• F'_v = F_v · C_D · C_M · C_t · C_vr
• f_v = 3·V / (2·A) (rectangular section, NDS 3.4.1 Eq. 3.4-1)

Check 3 — Bearing (NDS 3.10, compression perpendicular to grain)

• Bearing area factor C_b = (l_b + 0.375) / l_b (NDS 3.10.4; bearing < 6 in and ≥ 3 in from member end).
• F'_c⊥ = F_c⊥ · C_M · C_t · C_i · C_b
• Bearing area A_b = l_b · b
• f_c⊥ = R / A_b (R = w·L/2)

Check 4 — Serviceability (NDS 3.5)

• Δ_total = 5·w·L⁴ / (384·E·I_x)
• Δ_live = 5·w_L·L⁴ / (384·E·I_x)
• Limits L/240 (total) and L/360 (live). Hardcoded constants in calc.py (240, 360) — not YAML inputs — matching the reference.

Reference example (ground truth to lock)

Project "Pompano Beach", prepared_by "Conemco Engineering".

Quantity	Value
DL, LL	25 psf, 50 psf
span L, spacing B	9 ft, 13 ft
w, w_L	975 plf, 650 plf
b × d	3.5 in × 9.5 in
A, I_x, S_x	33.25 in², 250.1 in⁴, 52.6 in³
F_b, F_v, F_c⊥, E, E'_min	2400, 300, 565, 1,700,000, 510,000 psi
All adjustment factors	1.0
M, V, R	9871.88 ft·lbf, 4387.5 lbf, 4387.5 lbf
Flexure util / shear util / bearing util	0.938 / 0.66 / 0.772
Δ_total, Δ_live	0.339 in, 0.226 in

Corrected vs. the source PDF: the shear section label "acting bending stress" becomes "acting shear stress", and the blank page 3 is omitted. Corrections are noted in the sheet's Scope section.

Conventions (inherited)

• lib/sheet.typ is shared. It must not be modified except where an explicit user request authorizes an additive-only change (see the 2026-08-20 change: check_service added; check unchanged).
• No existing calculation (steel-beam, concrete-beam, concrete-beam2, shore-post) may be modified.
• Compile from worksheets/ with --root ..
• Lock the reference example in pytest with pytest.approx before treating the tool as stable.

Milestones

• 2026-08-19 — Task 001 DONE: calc.py + input.yaml + results.json created. All five checks pass for the default "Pompano Beach" input; values match the reference example (flexure 0.938, shear 0.66, bearing 0.772, Δ_total 0.339 in, Δ_live 0.226 in). See TASKS.md.
• 2026-08-19 — Task 002 DONE: test_wood_joist.py created with 10 numerical lock tests; all pass (10 passed).
• 2026-08-19 — Task 003 DONE: beam.typ created, compiled to generated/wood-joist.pdf (206 KB), and the Typst metadata test appended; all 11 tests pass (11 passed).
• 2026-08-19 — Task 004 DONE: README.md and codemap.md refreshed with the wood-joist entry; all 11 tests still pass.
• 2026-08-19 — Task 005 DONE: Reviewer PASS after one fix cycle. Issues found and fixed: (1) C_L ≤ 1.0 now explicitly enforced with regression test; (2) bearing applicability limits enforced (l_b < 6 in, end distance ≥ 3 in) with new bearing_end_distance input and tests. Final state: 14 tests pass, PDF compiles, results.json idempotent. Calculation approved.
• 2026-08-20 — Tasks 006–008 DONE: load determination moved to Typst (mirroring steel-beam), check_service added to lib/sheet.typ (Acting/Allowed/ Utilization) and used for the two deflection checks, input.yaml switched to checked demands (w, wL, M, V, R), tests updated with the <wood-joist-loads> reconciliation test, and README/codemap refreshed. Reviewer PASS (all 8 checklist items, deterministic evidence verified); simplify pass clean. Final state: 15 tests pass, PDF compiles, results.json idempotent, benchmark values unchanged (flexure 0.938, shear 0.66, bearing 0.772, Δ_total 0.339 in, Δ_live 0.226 in).

Final deliverables

• calcs/wood-joist/calc.py — NDS 2018 ASD wood joist analysis (flexure with C_L, shear, bearing, deflection). CLI: --input, --output, --stdout.
• calcs/wood-joist/input.yaml — Pint-quantity inputs; defaults reproduce the "Pompano Beach" reference example.
• calcs/wood-joist/test_wood_joist.py — 14 tests locking the reference values plus validation guards and the Typst metadata query test.
• calcs/wood-joist/beam.typ — presentation sheet (no recomputation), compiled to calcs/wood-joist/generated/wood-joist.pdf.
• README.md, codemap.md — documented and indexed.

Known limitations

• Single-span, uniformly loaded, rectangular-section joist only.
• No repetitive-member live-load reduction beyond the explicit C_r factor.
• No lateral-torsional restraint beyond the single unbraced length l_e.
• Deflection limits hardcoded to L/240 (total) and L/360 (live).

Dependencies

• Python: pyyaml, pytest, pint (already in requirements.txt).
• typst CLI for compile and the metadata-query test.
• No new third-party Python packages beyond requirements.txt.