docs: add 3d euler beam phase

2026-06-12 17:26:01 +09:00
parent 825e03dbaf
commit 13cf2af899
13 changed files with 891 additions and 0 deletions
@@ -0,0 +1,63 @@
+# Step 2: formulation-spec
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/requirements/euler-beam-3d.md`
+- `/docs/research/euler-beam-3d-research.md`
+- `/docs/formulations/README.md`
+
+## Task
+
+Create `/docs/formulations/euler-beam-3d-formulation.md`.
+
+The formulation must define the implementation contract for the C++ kernel. Include:
+
+- local coordinate system: local `x` from node 1 to node 2; local `y` from the user orientation vector projected normal to local `x`; local `z = x cross y`
+- local DOF order: `[u1, v1, w1, rx1, ry1, rz1, u2, v2, w2, rx2, ry2, rz2]`
+- section constants: `E`, `G`, `A`, `J`, `Iy`, `Iz`
+- local 12x12 stiffness matrix terms for:
+  - axial: `EA/L`
+  - torsion: `GJ/L`
+  - bending in local `x-y` using `EIz`
+  - bending in local `x-z` using `EIy`
+- transformation matrix convention and global stiffness equation `K_global = T^T K_local T`
+- end-force recovery equation `f_local = K_local u_local`
+- validation tolerances for unit tests, using deterministic double comparisons
+- singular and invalid input handling:
+  - zero or near-zero length throws `std::invalid_argument`
+  - nonpositive `E`, `G`, `A`, `J`, `Iy`, or `Iz` throws `std::invalid_argument`
+  - orientation vector parallel to beam axis throws `std::invalid_argument`
+
+Use compact matrices and named scalar coefficients so the implementation step can transcribe directly.
+
+Do not create C++ files in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm the matrix is symmetric by construction.
+2. Confirm local/global transformation convention is unambiguous.
+3. Update `phases/euler-beam-3d/index.json` step 2:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam formulation contract added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not modify requirements, source, tests, or reference artifacts.