From 13cf2af8992abacea9775f8f85b14fb03b48a4c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EA=B2=BD=EC=A2=85?= Date: Fri, 12 Jun 2026 17:26:01 +0900 Subject: [PATCH] docs: add 3d euler beam phase --- phases/euler-beam-3d/index.json | 99 ++++++++++++++++++++++++++++ phases/euler-beam-3d/step0.md | 63 ++++++++++++++++++ phases/euler-beam-3d/step1.md | 60 +++++++++++++++++ phases/euler-beam-3d/step10.md | 60 +++++++++++++++++ phases/euler-beam-3d/step2.md | 63 ++++++++++++++++++ phases/euler-beam-3d/step3.md | 56 ++++++++++++++++ phases/euler-beam-3d/step4.md | 68 ++++++++++++++++++++ phases/euler-beam-3d/step5.md | 75 ++++++++++++++++++++++ phases/euler-beam-3d/step6.md | 79 +++++++++++++++++++++++ phases/euler-beam-3d/step7.md | 110 ++++++++++++++++++++++++++++++++ phases/euler-beam-3d/step8.md | 97 ++++++++++++++++++++++++++++ phases/euler-beam-3d/step9.md | 57 +++++++++++++++++ phases/index.json | 4 ++ 13 files changed, 891 insertions(+) create mode 100644 phases/euler-beam-3d/index.json create mode 100644 phases/euler-beam-3d/step0.md create mode 100644 phases/euler-beam-3d/step1.md create mode 100644 phases/euler-beam-3d/step10.md create mode 100644 phases/euler-beam-3d/step2.md create mode 100644 phases/euler-beam-3d/step3.md create mode 100644 phases/euler-beam-3d/step4.md create mode 100644 phases/euler-beam-3d/step5.md create mode 100644 phases/euler-beam-3d/step6.md create mode 100644 phases/euler-beam-3d/step7.md create mode 100644 phases/euler-beam-3d/step8.md create mode 100644 phases/euler-beam-3d/step9.md diff --git a/phases/euler-beam-3d/index.json b/phases/euler-beam-3d/index.json new file mode 100644 index 0000000..b430e82 --- /dev/null +++ b/phases/euler-beam-3d/index.json @@ -0,0 +1,99 @@ +{ + "project": "FESA Structural Solver", + "phase": "euler-beam-3d", + "steps": [ + { + "step": 0, + "name": "requirements-baseline", + "status": "pending", + "allowed_paths": [ + "docs/requirements/euler-beam-3d.md" + ] + }, + { + "step": 1, + "name": "research-evidence", + "status": "pending", + "allowed_paths": [ + "docs/research/euler-beam-3d-research.md" + ] + }, + { + "step": 2, + "name": "formulation-spec", + "status": "pending", + "allowed_paths": [ + "docs/formulations/euler-beam-3d-formulation.md" + ] + }, + { + "step": 3, + "name": "numerical-review", + "status": "pending", + "allowed_paths": [ + "docs/numerical-reviews/euler-beam-3d-review.md" + ] + }, + { + "step": 4, + "name": "io-reference-contract", + "status": "pending", + "allowed_paths": [ + "docs/io-definitions/euler-beam-3d-io.md", + "docs/reference-models/euler-beam-3d-reference-models.md" + ] + }, + { + "step": 5, + "name": "implementation-plan", + "status": "pending", + "allowed_paths": [ + "docs/implementation-plans/euler-beam-3d-implementation-plan.md" + ] + }, + { + "step": 6, + "name": "model-beam-topology", + "status": "pending", + "allowed_paths": [ + "src/fesa/model/element.hpp", + "src/fesa/model/element.cpp", + "tests/unit/model_element_test.cpp" + ] + }, + { + "step": 7, + "name": "local-stiffness-kernel", + "status": "pending", + "allowed_paths": [ + "src/fesa/elements/", + "tests/unit/euler_beam_3d_*_test.cpp" + ] + }, + { + "step": 8, + "name": "global-transform-recovery", + "status": "pending", + "allowed_paths": [ + "src/fesa/elements/", + "tests/unit/euler_beam_3d_*_test.cpp" + ] + }, + { + "step": 9, + "name": "build-test-report", + "status": "pending", + "allowed_paths": [ + "docs/build-test-reports/euler-beam-3d-build-test.md" + ] + }, + { + "step": 10, + "name": "release-readiness-note", + "status": "pending", + "allowed_paths": [ + "docs/releases/euler-beam-3d-release.md" + ] + } + ] +} diff --git a/phases/euler-beam-3d/step0.md b/phases/euler-beam-3d/step0.md new file mode 100644 index 0000000..341f4e2 --- /dev/null +++ b/phases/euler-beam-3d/step0.md @@ -0,0 +1,63 @@ +# Step 0: requirements-baseline + +## Read These Files First + +Read the following files before editing: + +- `/AGENTS.md` +- `/docs/PRD.md` +- `/docs/ARCHITECTURE.md` +- `/docs/ADR.md` +- `/docs/requirements/README.md` + +## Task + +Create `/docs/requirements/euler-beam-3d.md` for a kernel-first 3D Euler-Bernoulli beam feature. + +Scope the first implementable increment narrowly: + +- two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element +- six mechanical DOFs per node in this order: `ux, uy, uz, rx, ry, rz` +- linear elastic section constants: `E`, `G`, `A`, `J`, `Iy`, `Iz` +- local and global 12x12 stiffness matrix support +- local and global element end-force recovery from nodal displacement vectors +- no shear deformation, warping, end releases, offsets, distributed loads, mass matrix, geometric stiffness, nonlinear kinematics, dynamics, or thermal coupling in this increment +- no Abaqus reference CSV generation in this increment +- no full Abaqus compatibility claim + +The document must contain: + +- metadata: `feature_id: euler-beam-3d`, owner agent, status +- explicit assumptions and non-goals +- `must` requirements with stable IDs such as `EB3D-REQ-001` +- verification quantities: displacement DOFs, reactions/end forces, stiffness symmetry, rigid body modes, local/global transformation consistency +- acceptance criteria that distinguish kernel completion from full solver release readiness +- open issues for parser integration, reference artifact availability, and full end-to-end assembly + +Do not create C++ files in this step. + +## Tests To Write First + +- No C++ test is required in this documentation-only step. +- Still run the harness validation commands in the acceptance criteria. + +## Acceptance Criteria + +```powershell +python -m unittest discover -s scripts -p "test_*.py" +python scripts/validate_workspace.py +``` + +## Verification Notes + +1. Confirm the requirements do not claim full Abaqus compatibility. +2. Confirm each `must` requirement has an acceptance criterion or a downstream verification hook. +3. Update `phases/euler-beam-3d/index.json` step 0: + - success: `"status": "completed"`, `"summary": "3D Euler beam kernel requirements baseline added"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not create or modify reference CSV files. +- Do not modify source or test files. diff --git a/phases/euler-beam-3d/step1.md b/phases/euler-beam-3d/step1.md new file mode 100644 index 0000000..b102f91 --- /dev/null +++ b/phases/euler-beam-3d/step1.md @@ -0,0 +1,60 @@ +# Step 1: research-evidence + +## 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/README.md` + +## Task + +Create `/docs/research/euler-beam-3d-research.md`. + +Summarize the evidence needed to implement the approved kernel-first 3D Euler-Bernoulli beam increment. The document must be implementation-oriented and must include: + +- supported theory: straight prismatic Euler-Bernoulli beam, axial, torsion, and two uncoupled bending planes +- assumptions and applicability limits +- local DOF ordering and sign convention used by the planned matrix +- source reliability classification +- benchmark-style checks that do not require external reference solver execution: + - local stiffness symmetry + - axial-only response + - torsion-only response + - bending about local `y` + - bending about local `z` + - rigid body translation/rotation zero internal forces in local coordinates + - global transform identity for an axis-aligned beam +- risks: orientation vector parallel to element axis, near-zero length, nonpositive section constants, ill-conditioning for very slender elements + +If internet access or a FEM wiki is used, cite sources briefly. Do not include long copyrighted excerpts. + +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 research document ties each source or theory point to a planned implementation check. +2. Confirm unresolved items are listed as risks or open issues instead of silently assumed. +3. Update `phases/euler-beam-3d/index.json` step 1: + - success: `"status": "completed"`, `"summary": "3D Euler beam research evidence added"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not modify source, test, reference, or I/O contract files. diff --git a/phases/euler-beam-3d/step10.md b/phases/euler-beam-3d/step10.md new file mode 100644 index 0000000..a14356a --- /dev/null +++ b/phases/euler-beam-3d/step10.md @@ -0,0 +1,60 @@ +# Step 10: release-readiness-note + +## Read These Files First + +Read the following files before editing: + +- `/AGENTS.md` +- `/docs/PRD.md` +- `/docs/ADR.md` +- `/docs/releases/README.md` +- `/docs/requirements/euler-beam-3d.md` +- `/docs/io-definitions/euler-beam-3d-io.md` +- `/docs/reference-models/euler-beam-3d-reference-models.md` +- `/docs/build-test-reports/euler-beam-3d-build-test.md` + +## Task + +Create `/docs/releases/euler-beam-3d-release.md`. + +This is a readiness note, not a release approval. It must state: + +- status: `not-release-ready-kernel-increment-complete` unless all upstream gates and reference artifacts somehow exist +- completed scope: local/global stiffness and end-force kernel for two-node 3D Euler-Bernoulli beam +- missing for full feature release: + - parser implementation for the approved Abaqus subset + - section/property semantic model integration + - assembler/static solver integration + - HDF5 result emission for beam quantities + - stored Abaqus reference artifacts + - reference comparison report + - physics sanity report +- known limitations from requirements +- next recommended phase or phase dependencies + +Do not change source or tests 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 note does not claim full release readiness. +2. Confirm all missing gates are explicit. +3. Update `phases/euler-beam-3d/index.json` step 10: + - success: `"status": "completed"`, `"summary": "3D Euler beam release readiness note added"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not create or modify reference artifacts. +- Do not modify source, tests, requirements, formulations, or I/O contracts. diff --git a/phases/euler-beam-3d/step2.md b/phases/euler-beam-3d/step2.md new file mode 100644 index 0000000..769cd14 --- /dev/null +++ b/phases/euler-beam-3d/step2.md @@ -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": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not modify requirements, source, tests, or reference artifacts. diff --git a/phases/euler-beam-3d/step3.md b/phases/euler-beam-3d/step3.md new file mode 100644 index 0000000..3589123 --- /dev/null +++ b/phases/euler-beam-3d/step3.md @@ -0,0 +1,56 @@ +# Step 3: numerical-review + +## 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/euler-beam-3d-formulation.md` +- `/docs/numerical-reviews/README.md` + +## Task + +Create `/docs/numerical-reviews/euler-beam-3d-review.md`. + +Review the formulation for implementation readiness. The review must include: + +- dimension and units check for each stiffness coefficient +- symmetry and rigid body mode expectations +- local axis construction risks +- positive semi-definite local stiffness expectation before constraints +- test obligations before production code +- known numerical limits for slender beams and very small section constants +- pass/fail verdict for kernel implementation planning + +If the formulation is not ready, mark the document status as `needs-upstream-decision` and update this phase step as blocked with a concrete reason. + +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 review does not change requirements or formulation. +2. Confirm implementation-owned risks are turned into concrete tests. +3. Update `phases/euler-beam-3d/index.json` step 3: + - success: `"status": "completed"`, `"summary": "3D Euler beam numerical review added"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not modify requirements, formulation, source, tests, or reference artifacts. diff --git a/phases/euler-beam-3d/step4.md b/phases/euler-beam-3d/step4.md new file mode 100644 index 0000000..c50137b --- /dev/null +++ b/phases/euler-beam-3d/step4.md @@ -0,0 +1,68 @@ +# Step 4: io-reference-contract + +## 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/formulations/euler-beam-3d-formulation.md` +- `/docs/numerical-reviews/euler-beam-3d-review.md` +- `/docs/io-definitions/README.md` +- `/docs/reference-models/README.md` + +## Task + +Create two documents: + +- `/docs/io-definitions/euler-beam-3d-io.md` +- `/docs/reference-models/euler-beam-3d-reference-models.md` + +The I/O contract must describe the planned Abaqus subset without claiming it is implemented in this kernel increment: + +- element keyword mapping candidate: two-node beam topology equivalent to Abaqus `B31` +- section keyword candidate: beam section constants sufficient for `A`, `J`, `Iy`, `Iz`, `E`, and `G` +- orientation data requirement for constructing local axes +- boundary/load DOFs: `1..6` map to `ux, uy, uz, rx, ry, rz` +- HDF5 output quantities expected after solver integration: nodal displacement, reaction, element internal force, stress placeholders if stress recovery is later approved +- unsupported input cases and diagnostics + +The reference model contract must list required future models without generating artifacts: + +- axial cantilever bar-as-beam +- torsion cantilever +- bending cantilever about local `y` +- bending cantilever about local `z` +- skew-oriented beam transform check + +For each future model, specify expected files under `reference//` and which CSV quantities are required. State that Abaqus reference CSVs must not be generated or modified in this phase. + +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 reference artifacts are specified, not created. +2. Confirm unsupported parser or solver paths are explicit open issues. +3. Update `phases/euler-beam-3d/index.json` step 4: + - success: `"status": "completed"`, `"summary": "3D Euler beam I/O and reference model contracts added"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not create or modify files under `/reference/`. +- Do not modify source or tests. diff --git a/phases/euler-beam-3d/step5.md b/phases/euler-beam-3d/step5.md new file mode 100644 index 0000000..8c1bd42 --- /dev/null +++ b/phases/euler-beam-3d/step5.md @@ -0,0 +1,75 @@ +# Step 5: implementation-plan + +## Read These Files First + +Read the following files before editing: + +- `/AGENTS.md` +- `/docs/PRD.md` +- `/docs/ARCHITECTURE.md` +- `/docs/ADR.md` +- `/docs/SOLVER_AGENT_DESIGN.md` +- `/docs/implementation-plans/README.md` +- `/docs/requirements/euler-beam-3d.md` +- `/docs/research/euler-beam-3d-research.md` +- `/docs/formulations/euler-beam-3d-formulation.md` +- `/docs/numerical-reviews/euler-beam-3d-review.md` +- `/docs/io-definitions/euler-beam-3d-io.md` +- `/docs/reference-models/euler-beam-3d-reference-models.md` +- `/src/fesa/model/element.hpp` +- `/tests/unit/model_element_test.cpp` + +## Task + +Create `/docs/implementation-plans/euler-beam-3d-implementation-plan.md`. + +The implementation plan must be ready for C++ TDD work and must include: + +- readiness check for requirements, research, formulation, numerical review, I/O, reference model contract +- explicit kernel-first implementation scope +- tasks matching the remaining phase steps: + - model beam topology + - local stiffness kernel + - global transform and end-force recovery + - build/test report + - release readiness note +- test IDs and RED/GREEN conditions for each production change +- candidate files: + - `src/fesa/model/element.hpp` + - `src/fesa/model/element.cpp` + - `tests/unit/model_element_test.cpp` + - `src/fesa/elements/euler_beam_3d.hpp` + - `src/fesa/elements/euler_beam_3d.cpp` + - `tests/unit/euler_beam_3d_local_stiffness_test.cpp` + - `tests/unit/euler_beam_3d_transform_recovery_test.cpp` +- CTest commands: + - `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test` + - `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test` + - `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test` +- acceptance traceability from requirements to tests + +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 every production file named in the plan has a related test. +2. Confirm the plan does not ask Implementation Agent to change requirements, formulation, I/O contracts, reference artifacts, or tolerance policies. +3. Update `phases/euler-beam-3d/index.json` step 5: + - success: `"status": "completed"`, `"summary": "3D Euler beam implementation plan added"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not modify source, tests, reference artifacts, or CMake files. diff --git a/phases/euler-beam-3d/step6.md b/phases/euler-beam-3d/step6.md new file mode 100644 index 0000000..f992f48 --- /dev/null +++ b/phases/euler-beam-3d/step6.md @@ -0,0 +1,79 @@ +# Step 6: model-beam-topology + +## Read These Files First + +Read the following files before editing: + +- `/AGENTS.md` +- `/docs/ARCHITECTURE.md` +- `/docs/ADR.md` +- `/docs/implementation-plans/euler-beam-3d-implementation-plan.md` +- `/src/fesa/model/element.hpp` +- `/src/fesa/model/element.cpp` +- `/tests/unit/model_element_test.cpp` + +## Task + +Use TDD to add a semantic model topology for a two-node 3D beam. + +Required production behavior: + +- Add `beam2` to `fesa::model::ElementTopology`. +- Preserve existing `truss2`, `bar2`, and `unknown` behavior. +- Do not store equation IDs on `Element`. +- Do not add section constants to `Element` in this step. + +## Tests To Write First + +Modify `/tests/unit/model_element_test.cpp` first. + +Add a failing assertion that constructs an element with: + +- id `ElementId{10}` +- topology `ElementTopology::beam2` +- node ids `{NodeId{1}, NodeId{2}}` +- property id `PropertyId{7}` + +The test must verify: + +- `element.topology() == ElementTopology::beam2` +- `element.node_ids().size() == 2` +- existing `bar2` behavior still works or the test still covers it + +RED command: + +```powershell +ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test +``` + +Expected RED: compile failure because `ElementTopology::beam2` is not defined. + +Then implement the minimal enum addition. + +GREEN command: + +```powershell +ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test +``` + +## Acceptance Criteria + +```powershell +ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test +python -m unittest discover -s scripts -p "test_*.py" +python scripts/validate_workspace.py +``` + +## Verification Notes + +1. Confirm the test failed before editing production code. +2. Confirm no unrelated model refactor was made. +3. Update `phases/euler-beam-3d/index.json` step 6: + - success: `"status": "completed"`, `"summary": "beam2 model topology added with unit test"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not create parser code. +- Do not add beam stiffness code in this step. diff --git a/phases/euler-beam-3d/step7.md b/phases/euler-beam-3d/step7.md new file mode 100644 index 0000000..31d26dd --- /dev/null +++ b/phases/euler-beam-3d/step7.md @@ -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; +using Matrix12 = std::array; + +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": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not add shear deformation or Timoshenko terms. +- Do not modify reference artifacts. diff --git a/phases/euler-beam-3d/step8.md b/phases/euler-beam-3d/step8.md new file mode 100644 index 0000000..426c76c --- /dev/null +++ b/phases/euler-beam-3d/step8.md @@ -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; + +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": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not add assembly or solver integration in this step. +- Do not modify reference artifacts. diff --git a/phases/euler-beam-3d/step9.md b/phases/euler-beam-3d/step9.md new file mode 100644 index 0000000..00a470a --- /dev/null +++ b/phases/euler-beam-3d/step9.md @@ -0,0 +1,57 @@ +# Step 9: build-test-report + +## Read These Files First + +Read the following files before editing: + +- `/AGENTS.md` +- `/docs/build-test-reports/README.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` +- `/tests/unit/euler_beam_3d_transform_recovery_test.cpp` + +## Task + +Create `/docs/build-test-reports/euler-beam-3d-build-test.md`. + +The report must record: + +- feature id +- changed files observed for this phase +- command log summary with exit codes and short evidence tails +- validation results for: + - harness self-test + - CMake configure/build + - CTest + - feature-specific tests +- failure classification if anything failed +- explicit statement that this report does not approve reference verification or release readiness + +Do not change source or tests in this step. + +## Tests To Write First + +- No C++ test is required in this documentation-only step. + +## Acceptance Criteria + +```powershell +ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "model_element_test|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. Record actual command exit codes and concise output evidence. +2. If validation fails for an environment reason, mark the report `needs-environment-fix` and update this phase step as blocked. +3. Update `phases/euler-beam-3d/index.json` step 9: + - success: `"status": "completed"`, `"summary": "3D Euler beam build/test report added"` + - failure after retries: `"status": "error"`, `"error_message": ""` + - blocked: `"status": "blocked"`, `"blocked_reason": ""` + +## Forbidden + +- Do not modify source, tests, requirements, formulations, I/O contracts, or reference artifacts. diff --git a/phases/index.json b/phases/index.json index ac29268..7a0cc74 100644 --- a/phases/index.json +++ b/phases/index.json @@ -3,6 +3,10 @@ { "dir": "solver-core-skeleton", "status": "completed" + }, + { + "dir": "euler-beam-3d", + "status": "pending" } ] }