calcs/wood-joist/README.md

# Worksheets

Typst-first calculation sheets. Use Python only when the arithmetic is no longer comfortable in Typst.

```text
lib/sheet.typ                 Shared letterhead, calc-line, check, check_service
calcs/shore-post/             Typst-only completed calculation
calcs/concrete-beam/          YAML numbers → Python → JSON → Typst
calcs/concrete-beam2/         YAML quantities → Pint → JSON → Typst
calcs/steel-beam/             YAML quantities → Pint + AISC XLSX → JSON → Typst
calcs/wood-joist/            YAML quantities → Pint → JSON → Typst (NDS 2018 ASD)
calcs/concentric-footing/    YAML quantities → Pint → JSON → Typst (ACI 318-19)
```

Compile every sheet from this folder so the shared logo resolves.

## Typst-only

Edit numbers in `calcs/shore-post/shore-post.typ`.

```bash
typst compile --root . calcs/shore-post/shore-post.typ calcs/shore-post/generated/shore-post.pdf
typst watch --root . calcs/shore-post/shore-post.typ calcs/shore-post/generated/shore-post.pdf
```

## Hybrid

Edit `calcs/concrete-beam/input.yaml`, then:

```bash
python -m pip install -r requirements.txt
python calcs/concrete-beam/calc.py
typst compile --root . calcs/concrete-beam/beam.typ calcs/concrete-beam/generated/beam.pdf
```

Optional output path: `python calcs/concrete-beam/calc.py path/to/input.yaml path/to/results.json`

```bash
python -m pytest calcs/concrete-beam/test_concrete_beam.py
```

`calc.py` writes named numbers. `beam.typ` does not recompute the design.

## Hybrid with units (Pint)

Same calculation pattern with unit-bearing YAML values. Write `span: "16 ft"`
or `span: "192 in"`. Quote every quantity.

```bash
python calcs/concrete-beam2/calc.py
typst compile --root . calcs/concrete-beam2/beam.typ calcs/concrete-beam2/generated/beam.pdf
python -m pytest calcs/concrete-beam2/test_concrete_beam2.py
```

## Templates

Copy one of these folders into `calcs/` and rename it. Compile from the
`worksheets/` directory so the shared logo resolves.

Typst-only:

```bash
typst compile --root . template/typst-only/main.typ template/typst-only/generated/calculation.pdf
```

Typst + Python:

```bash
python template/typst-python/calc.py
typst compile --root . template/typst-python/main.typ template/typst-python/generated/calculation.pdf
python -m pytest template/typst-python/test_template.py
```

## Steel beam

The steel beam sheet reads section properties directly from
`aisc-shapes-database-v15.0.xlsx`. Edit `calcs/steel-beam/input.yaml`, then:

```bash
python calcs/steel-beam/calc.py
typst compile --root . calcs/steel-beam/beam.typ calcs/steel-beam/generated/beam.pdf
python -m pytest calcs/steel-beam/test_steel_beam.py
```

For a standalone JSON result on stdout, use:

```bash
python calcs/steel-beam/calc.py --input calcs/steel-beam/input.yaml --stdout
```

Use `--output path/to/results.json` to select a JSON output path. The reusable
Python function is `compute(input_dict)` in `calcs/steel-beam/calc.py`.

`input.yaml` supplies the checked `Mu` and `Vu` demands. `beam.typ` determines
and displays the gravity loads that produce those demands, and the test suite
queries Typst metadata to verify the values match. The calculation covers
major-axis AISC lateral torsional buckling, web shear, and point-load
deflection. The test fixture locks the supplied `steel-beam.pdf` example for
W6X8.5.

## Wood joist

The wood joist sheet reads reference design values and adjustment factors from
`calcs/wood-joist/input.yaml`, then computes capacity checks per NDS 2018 ASD.

```bash
python calcs/wood-joist/calc.py
typst compile --root . calcs/wood-joist/beam.typ calcs/wood-joist/generated/wood-joist.pdf
python -m pytest calcs/wood-joist/test_wood_joist.py
```

For a standalone JSON result on stdout, use:

```bash
python calcs/wood-joist/calc.py --input calcs/wood-joist/input.yaml --stdout
```

Use `--output path/to/results.json` to select a JSON output path. The reusable
Python function is `compute(input_dict)` in `calcs/wood-joist/calc.py`.

`input.yaml` supplies the checked demands (`w`, `wL`, `M`, `V`, `R` as
Pint-quantity strings), `span`, section dimensions, bearing geometry, NDS
reference design values, and adjustment factors — and no longer supplies `DL`,
`LL`, or `spacing`. `beam.typ` determines the gravity loads inline (`DL = 25
psf`, `LL = 50 psf`, span 9 ft, spacing 13 ft), derives `w`, `wL`, `M`, `V`,
`R`, and presents them beside the Python-checked demands; the test suite
reconciles the two via the `<wood-joist-loads>` metadata query. `calc.py` reads
the demands and computes section properties, flexure (with `C_L`), shear,
bearing, and L/240 + L/360 deflection. The two deflection checks use the shared
`check_service` helper (Acting/Allowed/Utilization); flexure, shear, and
bearing use `check`.

## Concentric footing

Square concentric spread footing under axial load per ACI 318-19 — soil bearing, one-way/two-way shear, flexure, minimum steel, concrete bearing.

```bash
python calcs/concentric-footing/calc.py
typst compile --root . calcs/concentric-footing/footing.typ calcs/concentric-footing/generated/footing.pdf
python -m pytest calcs/concentric-footing/test_concentric_footing.py
```

For a standalone JSON result on stdout, use:

```bash
python calcs/concentric-footing/calc.py --input calcs/concentric-footing/input.yaml --stdout
```

Use `--output path/to/results.json` to select a JSON output path. The reusable
Python function is `compute(input_dict)` in `calcs/concentric-footing/calc.py`.

`input.yaml` supplies checked `Ps`/`Pu` (Pint quantities) and footing geometry/materials; `footing.typ` derives `Ps`/`Pu` inline from `DLr=10psf, LLr=20psf, Br=18.9ft, Lr=27.5ft, column 14in×14ft @145pcf` and reconciles via `<concentric-footing-loads>` query; bearing plate width `bp=6in` governs `A1`.

## New calculation

1. Copy the nearer example.
2. Stay in Typst if it is arithmetic you want to see.
3. If you need branching or iteration, write a small `calc.py` that reads YAML and writes `results.json` (`values` and `checks`).
4. Lock one hand example in a pytest before treating the tool as stable.
5. Extract a shared Python module only the second time you need the same procedure.