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

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.