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,110 @@
+# Step 7: local-stiffness-kernel
+
+## 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`
+
+Also read any files created by previous steps in this phase.
+
+## Task
+
+Use TDD to create the local 12x12 stiffness kernel for the 3D Euler-Bernoulli beam.
+
+Create:
+
+- `/src/fesa/elements/euler_beam_3d.hpp`
+- `/src/fesa/elements/euler_beam_3d.cpp`
+- `/tests/unit/euler_beam_3d_local_stiffness_test.cpp`
+
+Required API:
+
+```cpp
+namespace fesa::elements {
+
+using Vector12 = std::array<double, 12>;
+using Matrix12 = std::array<double, 144>;
+
+struct EulerBeam3DSection {
+    double young_modulus;
+    double shear_modulus;
+    double area;
+    double torsion_constant;
+    double second_moment_y;
+    double second_moment_z;
+};
+
+Matrix12 euler_beam_3d_local_stiffness(double length, const EulerBeam3DSection& section);
+Vector12 euler_beam_3d_local_end_forces(double length,
+                                        const EulerBeam3DSection& section,
+                                        const Vector12& local_displacements);
+
+} // namespace fesa::elements
+```
+
+Implementation rules:
+
+- Matrix storage is row-major: index `(row, col)` is `row * 12 + col`.
+- Validate `length > 0` and all section constants are positive; throw `std::invalid_argument` otherwise.
+- Use only C++17 standard library.
+- Do not introduce an external linear algebra dependency.
+- Do not edit CMake files; source and test globs should pick up new files.
+
+## Tests To Write First
+
+Create `/tests/unit/euler_beam_3d_local_stiffness_test.cpp` before production code.
+
+Test behavior:
+
+- For `L = 2.0`, `E = 210.0`, `G = 80.0`, `A = 3.0`, `J = 4.0`, `Iy = 5.0`, `Iz = 6.0`, verify representative matrix entries:
+  - axial: `K(0,0) = EA/L`, `K(0,6) = -EA/L`, `K(6,6) = EA/L`
+  - torsion: `K(3,3) = GJ/L`, `K(3,9) = -GJ/L`, `K(9,9) = GJ/L`
+  - local `x-y` bending uses `EIz`: `K(1,1) = 12*E*Iz/L^3`, `K(1,5) = 6*E*Iz/L^2`, `K(5,5) = 4*E*Iz/L`
+  - local `x-z` bending uses `EIy`: `K(2,2) = 12*E*Iy/L^3`, `K(2,4) = -6*E*Iy/L^2`, `K(4,4) = 4*E*Iy/L`
+- Verify all entries are symmetric within `1.0e-10`.
+- Verify `euler_beam_3d_local_end_forces` returns `K * u` for a displacement vector with at least three nonzero components.
+- Verify invalid length and nonpositive section constants throw `std::invalid_argument`.
+
+RED command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test
+```
+
+Expected RED: test executable missing or compile failure because the header/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_local_stiffness_test
+```
+
+## Acceptance Criteria
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_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 no parser, assembly, or results writer code was changed.
+3. Update `phases/euler-beam-3d/index.json` step 7:
+   - success: `"status": "completed"`, `"summary": "local 3D Euler beam stiffness and local end-force kernel added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not add shear deformation or Timoshenko terms.
+- Do not modify reference artifacts.