# Hierarchical Fracture Lab — deliverables

Browser-based generative design and fracture-discovery platform for hierarchical cellular networks derived from the
five supplied reference images, with a validated beam-network fracture solver, a complete computational study
(345 logged runs + 68 archived preliminary runs), publication figures, movies, printable STL geometry, and a compiled
LaTeX report.

## Start here
* **Application**: open `app/HierarchicalFractureLab.html` in a modern browser (Chrome/Edge/Firefox/Safari; no server or
  internet needed — everything is inlined). Generate → Run. Panel 7 runs the validation suite; panel 9 exports data,
  STL, SVG, PNG and movies; the "Study presets" menu in panel 2 loads the designs of the study and the print set.
  URL options: `?preset=<designId>&autorun=1&replay=1&color=util|level|interface|N|disp|state|failOrder|thickness&view=iso&extrude=1`.
* **Report**: `report/report.pdf` (source `report/report.tex`, tables in `report/tables/`, figures in `report/figures/`).
* **Printable designs**: `stl/` — 12 designs × 4 thickening variants (`STL_README.md` explains each design and variant).
* **Manifest**: `manifest.json` — versions, configuration, dates, parameter ranges, seeds and SHA-256 checksums of every file.

## Layout
```
app/HierarchicalFractureLab.html   single-file application (core + Three.js r128 + OrbitControls + reference thumbnails)
app/src/core/*.js                  solver core modules (RNG/geometry, generator, beam solver, fracture driver, metrics, validation, STL/SVG)
app/src/hfx_core.js                built core (used by the app and by the Node study driver)
app/src/ui/*.html|js               application UI (CSS/HTML skeleton, Three.js viewer, application logic)
app/src/build.js                   build script (node build.js --app)
app/SOLVER_DESCRIPTION.md          description of the numerical solver
reference_images/                  the five reference images (originals + 512 px thumbnails used in the app)
validation/                        run_validation.js, validation_results.json, validation_report.md (44 tests, all pass)
study/hfx_batch.js                 parallel study driver (worker threads); plans/ stage 1–5 plan files; study_base.js
study/experiment_log.jsonl         machine-readable log: one JSON line per run (params, seed, reason, hypothesis, metrics, files, checksums)
study/runs/<runId>/                results.json, steps.csv, events.csv, members.csv, member_history.csv, geometry.json, snapshots.json, snapshot.png
study/hypotheses.md                competing hypotheses recorded after stages 1–2 and their outcomes
study/predictions.json|.md         holdout predictions recorded before stage 5 was run
study/prelim/                      archived preliminary family (frame side walls) with its own log and runs
analysis/*.py                      analysis and figure scripts (hfx_analysis, load_sharing, make_figures, make_tables, render_*)
analysis/figures/                  all figures as PDF, SVG and PNG
analysis/processed/                flat experiment table, design summary, load-sharing statistics, holdout comparison, key numbers
analysis/gallery/                  generator gallery (contact sheet)
movies/                            MP4 movies of complete runs (README.md)
stl/                               STL set + stl_manifest.json + STL_README.md
screenshots/                       application screenshots (take_screenshots.py: Playwright script that reproduces them)
task_prompt.md                     the original task statement
```

## Reproducing
```bash
node app/src/build.js --app                 # rebuild hfx_core.js and the single-file app
node validation/run_validation.js           # validation suite (Node)
node study/hfx_batch.js study/plans/stage1_baseline.js   # ... stage2_recon.js, stage3_hypotheses.js, stage4_refine.js, stage5_holdout.js
python3 analysis/load_sharing.py && python3 analysis/make_figures.py && python3 analysis/make_tables.py
python3 analysis/render_run_images.py; bash analysis/render_all_movies.sh
node stl/make_stl_set.js
cd report && pdflatex report.tex (×3)
```
Requirements: Node ≥ 18 (study driver), Python 3 with numpy/pandas/scipy/matplotlib/Pillow (analysis), ffmpeg (movies),
pdflatex (report). The application itself needs only a browser.

## Units
All simulator quantities are normalised (length W = 1, modulus E_s = 1, depth b_z = 1; force in E_s·W·b_z, energy in
E_s·W²·b_z). Panel 5 of the application converts to physical units for a chosen modulus, width and depth.