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,97 @@
+# Step 8: global-transform-recovery
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/formulations/euler-beam-3d-formulation.md`
+- `/docs/numerical-reviews/euler-beam-3d-review.md`
+- `/docs/implementation-plans/euler-beam-3d-implementation-plan.md`
+- `/src/fesa/elements/euler_beam_3d.hpp`
+- `/src/fesa/elements/euler_beam_3d.cpp`
+- `/tests/unit/euler_beam_3d_local_stiffness_test.cpp`
+
+## Task
+
+Use TDD to add local/global transformation and global end-force recovery to the 3D Euler-Bernoulli beam kernel.
+
+Extend the API in `/src/fesa/elements/euler_beam_3d.hpp`:
+
+```cpp
+using Vector3 = std::array<double, 3>;
+
+struct EulerBeam3DGeometry {
+    Vector3 node1;
+    Vector3 node2;
+    Vector3 orientation;
+};
+
+Matrix12 euler_beam_3d_global_stiffness(const EulerBeam3DGeometry& geometry,
+                                        const EulerBeam3DSection& section);
+Vector12 euler_beam_3d_global_end_forces(const EulerBeam3DGeometry& geometry,
+                                         const EulerBeam3DSection& section,
+                                         const Vector12& global_displacements);
+```
+
+Implementation rules:
+
+- local `x` is normalized `node2 - node1`
+- local `y` is the normalized projection of `orientation` onto the plane normal to local `x`
+- local `z = x cross y`
+- use the same 3x3 rotation block for translational and rotational DOFs
+- compute `K_global = T^T K_local T`
+- compute global end forces by transforming global displacements to local, recovering local forces, then transforming forces back to global
+- throw `std::invalid_argument` for zero-length element, zero orientation vector, or orientation parallel to the beam axis
+
+## Tests To Write First
+
+Create `/tests/unit/euler_beam_3d_transform_recovery_test.cpp` before production code.
+
+Test behavior:
+
+- Axis-aligned beam from `(0,0,0)` to `(2,0,0)` with orientation `(0,1,0)` gives global stiffness equal to local stiffness.
+- A rotated beam preserves stiffness symmetry.
+- A rigid global translation vector produces near-zero global end forces.
+- A simple global axial extension on the axis-aligned beam produces equal and opposite axial end forces.
+- Parallel orientation vector throws `std::invalid_argument`.
+
+RED command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test
+```
+
+Expected RED: test executable missing or compile failure because the transform API does not exist.
+
+Then implement the minimal API.
+
+GREEN command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test
+```
+
+## Acceptance Criteria
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "euler_beam_3d_(local_stiffness|transform_recovery)_test"
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm RED failed before production code was added.
+2. Confirm local stiffness tests still pass.
+3. Update `phases/euler-beam-3d/index.json` step 8:
+   - success: `"status": "completed"`, `"summary": "global transform and global end-force recovery added for 3D Euler beam"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not add assembly or solver integration in this step.
+- Do not modify reference artifacts.