FESADev/docs/requirements/euler-beam-3d.md

# 3D Euler-Bernoulli Beam Kernel Requirements

## Metadata
- feature_id: euler-beam-3d
- title: Kernel-first 3D Euler-Bernoulli beam element
- status: draft
- owner_agent: requirement-agent
- date: 2026-06-12

## Purpose
Define the first implementable requirements baseline for a two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element kernel. This increment is limited to element-level stiffness and end-force recovery so downstream formulation, numerical review, and C++ implementation can proceed without claiming full solver readiness.

## Assumptions
- The element is a two-node straight beam with nonzero length.
- The element uses small-displacement, small-rotation, linear elastic kinematics.
- Each node has six mechanical DOFs in this order: `ux, uy, uz, rx, ry, rz`.
- The element displacement vector order is node 1 DOFs followed by node 2 DOFs, each in `ux, uy, uz, rx, ry, rz` order.
- Section and material constants are constant over the element: `E`, `G`, `A`, `J`, `Iy`, `Iz`.
- `Iy` and `Iz` are second moments of area about the element local principal bending axes, and `J` is the torsional constant about the local beam axis.
- Units are user-consistent; the kernel does not perform unit conversion in this increment.
- The local element basis is right-handed and orthonormal. The local `x` axis follows node 1 to node 2; the source of local `y` and `z` orientation for parser or solver integration remains open.
- Boundary conditions, global equation numbering, sparse assembly, linear solve, HDF5 writing, and reference comparison are downstream solver concerns, not kernel responsibilities in this increment.

## In Scope
- Two-node, straight, prismatic 3D Euler-Bernoulli beam element kernel.
- Six mechanical DOFs per node in `ux, uy, uz, rx, ry, rz` order.
- Linear elastic section constants: `E`, `G`, `A`, `J`, `Iy`, `Iz`.
- Local 12x12 stiffness matrix support.
- Global 12x12 stiffness matrix support when a valid local-to-global transformation is supplied.
- Local and global element end-force recovery from compatible 12-entry nodal displacement vectors.
- Kernel-level verification hooks for stiffness symmetry, rigid body modes, and local/global transformation consistency.

## Out Of Scope
- Shear deformation, Timoshenko beam behavior, shear correction factors, and shear locking treatment.
- Warping DOFs, warping stiffness, restrained warping, or bimoment recovery.
- End releases, offsets, rigid links, eccentric sections, or joint constraints.
- Distributed loads, equivalent nodal load vectors, body forces, or pressure loads.
- Mass matrix, damping matrix, geometric stiffness, buckling, nonlinear kinematics, dynamics, or thermal coupling.
- Abaqus reference CSV generation or modification.
- Full Abaqus compatibility claims.
- Parser integration, end-to-end assembly, solver execution, HDF5 result output, reference comparison, physics sanity, or release readiness.

## Analysis Definition
- analysis_type: linear static kernel only
- element_type: two-node 3D Euler-Bernoulli beam
- nodes_per_element: 2
- dofs_per_node: 6
- dof_order: `ux, uy, uz, rx, ry, rz`
- element_vector_size: 12
- material_model: linear elastic constants `E` and `G`
- section_model: constant section constants `A`, `J`, `Iy`, `Iz`
- coordinate_system: local Cartesian beam frame and global Cartesian frame
- loads: not in this increment
- boundary_conditions: not in this increment
- official_solver_output: not in this increment

## Input Requirements
- The kernel must receive or derive two distinct node positions sufficient to determine element length and local `x` direction.
- The kernel must receive positive finite constants for `E`, `G`, `A`, `J`, `Iy`, and `Iz`.
- The kernel must receive a valid right-handed orthonormal local basis or equivalent transformation data before producing a global stiffness matrix or global end-force vector.
- The kernel must receive 12-entry nodal displacement vectors ordered as node 1 then node 2, with each node using `ux, uy, uz, rx, ry, rz`.

## Output Requirements
- The kernel must produce a local 12x12 stiffness matrix in the documented element DOF order.
- The kernel must produce a global 12x12 stiffness matrix in the documented global DOF order when supplied with a valid local-to-global transformation.
- The kernel must recover local element end forces from a compatible local nodal displacement vector.
- The kernel must recover global element end forces from a compatible global nodal displacement vector when supplied with the same transformation used for the global stiffness matrix.
- This increment must not write `results.h5` and must not create deterministic CSV views or Abaqus reference CSV files.

## Verification Quantities
| quantity | required_for_kernel | verification intent | downstream owner |
| --- | --- | --- | --- |
| displacement DOFs | yes | Confirm 12-entry vectors use the required `ux, uy, uz, rx, ry, rz` per-node ordering. | Implementation Planning Agent |
| reactions / end forces | yes | Confirm local and global end-force recovery is consistent with the corresponding stiffness matrix and displacement vector. | Formulation Agent; Implementation Planning Agent |
| stiffness symmetry | yes | Confirm local and global 12x12 stiffness matrices are symmetric within the formulation-defined numeric tolerance. | Numerical Review Agent; Implementation Planning Agent |
| rigid body modes | yes | Confirm an unconstrained isolated element has six zero-energy rigid body modes within the formulation-defined numeric tolerance. | Formulation Agent; Numerical Review Agent |
| local/global transformation consistency | yes | Confirm transformed stiffness and force recovery are mutually consistent for the same basis and displacement vector. | Formulation Agent; Implementation Planning Agent |
| stress | no | Stress recovery is not part of this kernel increment. | Future requirements |
| strain | no | Strain recovery is not part of this kernel increment. | Future requirements |
| energy or residual | downstream hook | Strain energy consistency may be added as a kernel verification hook after formulation review. | Numerical Review Agent |

## Tolerance Policy
- absolute_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent
- relative_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent
- norm_based_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent
- Units: user-consistent structural units; no unit conversion in this increment.
- Coordinate system: local and global Cartesian frames with a right-handed orthonormal element basis.
- Rule: any numerical kernel test added later must state the tolerance source and whether it checks component-wise values, matrix norms, eigenvalue/residual norms, or force vector norms.

## Reference Artifact Requirements
Reference artifacts are not required for kernel completion in this increment.

Future end-to-end solver verification may use a bundle under `reference/<model-id>/`, but this requirements baseline does not authorize creating, modifying, or regenerating Abaqus reference CSV files.

| artifact | kernel increment status | future solver-release status |
| --- | --- | --- |
| `model.inp` | not required | required after parser and assembly scope is approved |
| `metadata.json` | not required | required with provenance for approved reference artifacts |
| `<model-id>_displacements.csv` | not required | required for reference comparison |
| `<model-id>_reactions.csv` | not required | required for reaction/end-force comparison |
| `<model-id>_internalforces.csv` | not required | required when internal force comparison scope is approved |
| `<model-id>_stresses.csv` | not required | not required until stress recovery is in scope |

## Must Requirements
| id | requirement |
| --- | --- |
| EB3D-REQ-001 | The beam kernel must model only a two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element in this increment. |
| EB3D-REQ-002 | The beam kernel must use six mechanical DOFs per node ordered as `ux, uy, uz, rx, ry, rz`. |
| EB3D-REQ-003 | The beam kernel must use a 12-entry element vector ordered as all node 1 DOFs followed by all node 2 DOFs. |
| EB3D-REQ-004 | The beam kernel must accept linear elastic constants `E` and `G` and section constants `A`, `J`, `Iy`, and `Iz`. |
| EB3D-REQ-005 | The beam kernel must produce a local 12x12 stiffness matrix in the documented local DOF order. |
| EB3D-REQ-006 | The beam kernel must produce a global 12x12 stiffness matrix when supplied with a valid right-handed orthonormal local-to-global transformation. |
| EB3D-REQ-007 | The beam kernel must recover local element end forces from a compatible local nodal displacement vector. |
| EB3D-REQ-008 | The beam kernel must recover global element end forces from a compatible global nodal displacement vector and the same transformation convention used for global stiffness. |
| EB3D-REQ-009 | The local and global stiffness matrices must be symmetric within the formulation-defined tolerance. |
| EB3D-REQ-010 | The unconstrained isolated element stiffness must preserve six rigid body modes within the formulation-defined tolerance. |
| EB3D-REQ-011 | The local and global stiffness and end-force recovery paths must be mutually consistent under the same transformation. |
| EB3D-REQ-012 | The kernel increment must not include shear deformation, warping, end releases, offsets, distributed loads, mass matrix, geometric stiffness, nonlinear kinematics, dynamics, or thermal coupling. |
| EB3D-REQ-013 | The kernel increment must not create, modify, or regenerate Abaqus reference CSV files. |
| EB3D-REQ-014 | The requirements and downstream implementation must not claim full Abaqus compatibility for this feature. |
| EB3D-REQ-015 | The kernel completion criteria must be separate from full solver release readiness. |

## Requirement Verification Matrix
| id | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
| --- | --- | --- | --- | --- | --- | --- | --- |
| EB3D-REQ-001 | user step scope | must | formulation review; C++ unit tests in later implementation steps | Formulation and implementation address only the scoped Euler-Bernoulli beam kernel and do not add excluded behaviors. | not numeric | Formulation Agent; Implementation Planning Agent | draft |
| EB3D-REQ-002 | user step scope | must | unit test; code review | Tests or implementation checks demonstrate the exact per-node DOF order `ux, uy, uz, rx, ry, rz`. | not numeric | Implementation Planning Agent | draft |
| EB3D-REQ-003 | user step scope | must | unit test; code review | Tests or implementation checks demonstrate the 12-entry node 1 then node 2 vector order. | not numeric | Implementation Planning Agent | draft |
| EB3D-REQ-004 | user step scope | must | input validation test in later implementation steps | Nonpositive or nonfinite constants are rejected or diagnosed according to the downstream implementation contract. | not numeric for this baseline | I/O Definition Agent; Implementation Planning Agent | draft |
| EB3D-REQ-005 | user step scope | must | formulation review; local stiffness unit test | Local stiffness is 12x12, uses the documented local DOF order, and matches formulation-specified benchmark values. | formulation-defined | Formulation Agent; Numerical Review Agent; Implementation Planning Agent | draft |
| EB3D-REQ-006 | user step scope | must | transformation unit test | Global stiffness is 12x12 and matches the formulation-specified transformation of the local matrix. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft |
| EB3D-REQ-007 | user step scope | must | local force recovery unit test | Local end-force output is consistent with the local stiffness matrix and local displacement vector. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft |
| EB3D-REQ-008 | user step scope | must | global force recovery unit test | Global end-force output is consistent with global stiffness, global displacement, and the local/global transformation convention. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft |
| EB3D-REQ-009 | user verification notes | must | matrix symmetry unit test | Local and global stiffness matrices satisfy symmetry checks within the selected matrix tolerance. | needs-downstream-decision | Numerical Review Agent; Implementation Planning Agent | draft |
| EB3D-REQ-010 | user verification notes | must | rigid body mode unit test; numerical review | Six rigid body modes produce zero or tolerance-bounded internal force/energy for an unconstrained isolated element. | needs-downstream-decision | Formulation Agent; Numerical Review Agent | draft |
| EB3D-REQ-011 | user verification notes | must | transformation consistency unit test | Stiffness transformation and end-force transformation use one consistent convention for the same local basis. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft |
| EB3D-REQ-012 | user exclusions | must | scope review; code review | No excluded behavior appears in requirements, formulation, or kernel implementation for this increment. | not numeric | Coordinator Agent; Implementation Planning Agent | draft |
| EB3D-REQ-013 | user forbidden list | must | git diff review | No file under `reference/` and no Abaqus reference CSV is created or modified in this increment. | not numeric | Reference Model Agent; Coordinator Agent | draft |
| EB3D-REQ-014 | ADR-003; user verification notes | must | documentation review; I/O contract review | Documentation states this is a limited feature subset and does not claim full Abaqus compatibility. | not numeric | I/O Definition Agent; Coordinator Agent | draft |
| EB3D-REQ-015 | project acceptance gates | must | release gate review | Kernel completion can be marked separately, while full solver release remains blocked until parser, assembly, HDF5 output, reference comparison, physics sanity, and release readiness gates pass. | not numeric | Release Agent; Coordinator Agent | draft |

## Acceptance Criteria
### This Documentation Step
- `docs/requirements/euler-beam-3d.md` exists and contains metadata, assumptions, non-goals, must requirements, verification quantities, acceptance criteria, and open issues.
- The document does not create source, test, or reference artifact files.
- The document does not claim full Abaqus compatibility.
- Every `must` requirement has an acceptance criterion or downstream verification hook in the Requirement Verification Matrix.
- The following validation commands pass:

```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
```

### Kernel Completion
Kernel completion may be claimed only after downstream implementation steps provide C++ tests and implementation evidence for:
- local 12x12 stiffness matrix generation;
- global 12x12 stiffness matrix transformation;
- local and global end-force recovery;
- DOF ordering;
- stiffness symmetry;
- six rigid body modes;
- local/global transformation consistency.

Kernel completion does not require Abaqus reference CSV files, `results.h5`, parser integration, global sparse assembly, or release readiness.

### Full Solver Release Readiness
Full solver release readiness is not in scope for this increment. It requires later evidence for:
- parser and I/O contract approval for the beam feature;
- Domain, AnalysisModel, DofManager, assembly, constraints, solve, and ResultsWriter integration;
- HDF5 result schema coverage;
- approved reference artifacts under `reference/<model-id>/`;
- FESA `results.h5` to Abaqus reference CSV comparison;
- physics sanity review;
- release readiness review with known limitations.

## Open Issues
- Parser integration: define the approved Abaqus keyword subset, beam section mapping, orientation input, and unsupported keyword diagnostics before parser work starts.
- Reference artifact availability: no Abaqus reference CSV files are required or generated in this kernel increment; approved reference artifacts are still needed for later solver-level verification.
- Full end-to-end assembly: global sparse assembly, boundary condition application, reaction recovery, solve flow, and HDF5 output are not covered by this kernel baseline.
- Local orientation convention: downstream formulation and I/O contract must define how local `y` and `z` axes are supplied, derived, validated, and reported.
- Tolerance values: downstream numerical review must select tolerances for matrix symmetry, rigid body mode residuals, transformation consistency, and force recovery.

## Downstream Handoff
### Research Agent
- Confirm authoritative Euler-Bernoulli 3D beam references and benchmark cases for stiffness, transformation, and rigid body checks.

### Formulation Agent
- Define local stiffness, transformation convention, end-force recovery convention, rigid body mode checks, and edge cases for invalid geometry or constants.

### Numerical Review Agent
- Review stiffness symmetry, rank/rigid body modes, sign conventions, transformation convention, conditioning risks, and numerical tolerances.

### I/O Definition Agent
- Define future parser and semantic model mapping for beam geometry, section constants, material constants, and local orientation without claiming full Abaqus compatibility.

### Reference Model Agent
- Define future reference model bundles only after parser and end-to-end solver scope is approved; do not generate reference CSV files in this increment.

### Implementation Planning Agent
- Plan C++ tests before production code for local stiffness, global transformation, end-force recovery, DOF order, symmetry, rigid body modes, and invalid inputs.