FESADev/docs/implementation-plans/euler-beam-3d-implementation-plan.md

# 3D Euler-Bernoulli Beam Kernel Implementation Plan

## Metadata
- feature_id: euler-beam-3d
- source_requirement: docs/requirements/euler-beam-3d.md
- source_research: docs/research/euler-beam-3d-research.md
- source_formulation: docs/formulations/euler-beam-3d-formulation.md
- source_numerical_review: docs/numerical-reviews/euler-beam-3d-review.md
- source_io_definition: docs/io-definitions/euler-beam-3d-io.md
- source_reference_models: docs/reference-models/euler-beam-3d-reference-models.md
- status: ready-for-implementation
- owner_agent: implementation-planning-agent
- date: 2026-06-12

## Readiness Check

| input | required_status | observed_status | decision |
| --- | --- | --- | --- |
| requirement | sufficient draft | draft, kernel scope explicit | proceed |
| research | ready-for-formulation | ready-for-formulation | proceed |
| formulation | ready-for-numerical-review | ready-for-numerical-review | proceed |
| numerical_review | pass-for-implementation-planning | pass-for-implementation-planning | proceed |
| io_definition | ready-for-implementation-planning or explicit future scope | ready-for-implementation-planning | proceed |
| reference_models | planned artifacts or future gate | needs-reference-artifacts | proceed for kernel only |

## Implementation Scope
- included_behavior:
  - semantic `beam2` model topology.
  - local 12x12 stiffness for a two-node 3D Euler-Bernoulli beam.
  - local end-force recovery as `K_local * u_local`.
  - local/global basis construction, global stiffness transform, and global end-force recovery.
- excluded_behavior:
  - parser integration, assembly, solver integration, HDF5 output, reference CSV generation, reference comparison, stress recovery, distributed loads, mass, geometric stiffness, releases, offsets, warping, shear deformation, nonlinear and dynamic behavior.
- non_goals:
  - no external linear algebra dependency.
  - no CMake edits unless the existing source/test globs fail to pick up new files.

## Work Breakdown

| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
| --- | --- | --- | --- | --- | --- |
| EB3D-TASK-001 | 1 | Add `ElementTopology::beam2` semantic topology. | EB3D-REQ-001, EB3D-REQ-002 | none | EB3D-TEST-001 |
| EB3D-TASK-002 | 2 | Add local stiffness and local end-force kernel. | EB3D-REQ-004, EB3D-REQ-005, EB3D-REQ-007, EB3D-REQ-009 | EB3D-TASK-001 | EB3D-TEST-002 |
| EB3D-TASK-003 | 3 | Add global transform and global end-force recovery. | EB3D-REQ-006, EB3D-REQ-008, EB3D-REQ-010, EB3D-REQ-011 | EB3D-TASK-002 | EB3D-TEST-003 |
| EB3D-TASK-004 | 4 | Record build/test evidence. | project validation policy | EB3D-TASK-003 | N/A |
| EB3D-TASK-005 | 5 | Record release-readiness note with limitations. | EB3D-REQ-012 through EB3D-REQ-015 | EB3D-TASK-004 | N/A |

## TDD Test Plan

| test_id | order | test_type | red_condition | green_condition | linked_task | command |
| --- | --- | --- | --- | --- | --- | --- |
| EB3D-TEST-001 | 1 | unit | compile fails because `ElementTopology::beam2` is missing | model element test passes with `beam2` and existing topologies preserved | EB3D-TASK-001 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test` |
| EB3D-TEST-002 | 2 | unit | compile fails because `euler_beam_3d.hpp` API is missing | local stiffness entries, symmetry, `K*u`, and invalid inputs pass | EB3D-TASK-002 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test` |
| EB3D-TEST-003 | 3 | unit | compile fails because global transform API is missing | identity transform, rotated symmetry, rigid translation, axial force, and invalid orientation pass | EB3D-TASK-003 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test` |

## CMake/CTest Plan
- target_candidates: existing FESA library target and unit-test executable pattern.
- add_test_needs: only if existing test globs do not register new tests.
- labels: unit.
- msvc_config: Debug.
- expected_feature_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`
- workspace_validation: `python scripts/validate_workspace.py`.

## Candidate Files and Ownership

| file_candidate | purpose | owner_boundary | notes |
| --- | --- | --- | --- |
| `src/fesa/model/element.hpp` | add semantic topology enum value | model semantic layer | No equation IDs or section constants. |
| `src/fesa/model/element.cpp` | only if topology string/conversion exists | model semantic layer | Preserve existing behavior. |
| `tests/unit/model_element_test.cpp` | topology unit test | test-first for model change | Must be edited before production enum change. |
| `src/fesa/elements/euler_beam_3d.hpp` | kernel declarations and small value types | element kernel layer | C++17 standard library only. |
| `src/fesa/elements/euler_beam_3d.cpp` | local/global stiffness and recovery implementation | element kernel layer | No parser, assembly, or HDF5 code. |
| `tests/unit/euler_beam_3d_local_stiffness_test.cpp` | local kernel tests | test-first for local kernel | Covers representative entries and invalid inputs. |
| `tests/unit/euler_beam_3d_transform_recovery_test.cpp` | transform/recovery tests | test-first for global transform | Covers identity, rotation, rigid translation, axial force, invalid orientation. |

## Acceptance Traceability Matrix

| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
| --- | --- | --- | --- | --- | --- |
| EB3D-REQ-001 | EB3D-TASK-001 | EB3D-TEST-001 | N/A | semantic topology exists for two-node beam | planned |
| EB3D-REQ-002 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | local DOF order matches formulation entries | planned |
| EB3D-REQ-004 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | section constants are used and invalid constants rejected | planned |
| EB3D-REQ-005 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | local 12x12 stiffness entries match formulation | planned |
| EB3D-REQ-006 | EB3D-TASK-003 | EB3D-TEST-003 | `eb3d-skew-transform` future | global stiffness uses documented transform | planned |
| EB3D-REQ-007 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | local end forces equal `K*u` | planned |
| EB3D-REQ-008 | EB3D-TASK-003 | EB3D-TEST-003 | `eb3d-skew-transform` future | global end forces use consistent transform | planned |
| EB3D-REQ-009 | EB3D-TASK-002/003 | EB3D-TEST-002/003 | N/A | local and global stiffness matrices are symmetric | planned |
| EB3D-REQ-010 | EB3D-TASK-003 | EB3D-TEST-003 | N/A | rigid global translation has near-zero end forces | planned |
| EB3D-REQ-011 | EB3D-TASK-003 | EB3D-TEST-003 | `eb3d-skew-transform` future | transform and recovery conventions are consistent | planned |
| EB3D-REQ-012 | EB3D-TASK-002/003 | EB3D-TEST-002/003 | N/A | excluded behaviors are not implemented | planned |
| EB3D-REQ-013 | EB3D-TASK-004 | N/A | all future models | no `reference/` artifacts are modified | planned |
| EB3D-REQ-014 | EB3D-TASK-005 | N/A | N/A | no full Abaqus compatibility claim | planned |
| EB3D-REQ-015 | EB3D-TASK-005 | N/A | N/A | kernel completion remains separate from full solver release | planned |

## Validation Commands

```powershell
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
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
```

## Risks and Downstream Handoff

### Implementation Agent
- Follow `RED -> GREEN -> VERIFY` for each production change.
- Keep matrix storage row-major with index `row * 12 + col`.
- Throw `std::invalid_argument` for invalid length, section constants, and orientation.

### Build/Test Executor Agent
- Record CTest and workspace validation evidence after the C++ steps.

### Correction Agent
- Compile failures are likely missing CMake glob registration or signature mismatch.
- Test failures are likely sign convention, transform convention, or tolerance mistakes.

### Reference Verification Agent
- No reference comparison is expected until future HDF5 and reference artifact work is approved.

## Open Issues
- Exact parser keyword subset and HDF5 schema are future integration work.
- Reference artifacts remain unavailable by design in this kernel phase.