# 3D Euler-Bernoulli Beam UEL Numerical Review

## Metadata
- feature_id: uel-3d-euler-beam
- source_requirement: `docs/requirements/uel-3d-euler-beam.md`
- source_research: `docs/research/uel-3d-euler-beam-research.md`
- source_formulation: `docs/formulations/uel-3d-euler-beam.md`
- status: pass-for-interface-definition
- owner_agent: numerical-review-agent
- date: 2026-06-11

## Review Verdict

- verdict: pass-for-interface-definition
- implementation_readiness: not blocked by formulation, but not approved for production implementation until the interface and no-Abaqus test-model gates are complete
- reason: The formulation has a complete linear static Euler-Bernoulli beam stiffness, consistent local/global transformation, no persistent state requirement, and explicit numerical validity checks. Remaining open items are Abaqus-facing interface decisions and downstream test-model obligations, not formulation blockers.

## Critical Findings

No blocking numerical findings were identified.

No `needs-change` finding is raised against `docs/formulations/uel-3d-euler-beam.md`. The items that remain unresolved are already assigned to the I/O Definition Agent or Reference Model Agent.

## Finding Register

| id | status | review target | finding | required follow-up |
| --- | --- | --- | --- | --- |
| NR-001 | pass | `Local Element Stiffness Matrix` | The 12-by-12 local stiffness includes axial `EA/L`, torsion `GJ/L`, local 2 bending with `E*Iy`, and local 3 bending with `E*Iz`. The matrix is complete for the first-scope linear elastic beam. | Reference Model Agent must test each subblock independently. |
| NR-002 | pass | `Local Element Stiffness Matrix` | The matrix is symmetric by construction. A scratch numerical check gave `maxabs(k-k^T)=0.0` for representative positive properties. | No-Abaqus tests should include scale-aware symmetry checks. |
| NR-003 | pass | `Local Element Stiffness Matrix` | The free element is positive semidefinite before boundary conditions. A representative eigenvalue check found six small modes and six positive deformational modes; tiny negative values were roundoff scale. | No-Abaqus tests should check six rigid-body modes using a relative threshold tied to the largest stiffness eigenvalue. |
| NR-004 | pass | `Primary Variables and DOFs`, `Local Element Stiffness Matrix` | The `Iy` and `Iz` association is internally consistent: `Iy` is bending about local 2 and couples `w/th2`; `Iz` is bending about local 3 and couples `v/th3`. The signs are consistent with `th2=-dw/dx` and `th3=dv/dx`. | Test-model gate must include separate local 2 and local 3 bending cases to catch axis swaps. |
| NR-005 | pass | `Local Frame and Transformation to Global Coordinates` | The transform convention `q_local=T*q_global` and `K_global=T^T*k_local*T` is consistent with virtual work and Abaqus global matrix responsibility. | Interface gate must preserve the same ordering for translation and rotation blocks. |
| NR-006 | pass | `Local Frame and Transformation to Global Coordinates` | The orientation construction gives an orthonormal right-handed frame when the reference vector has a nonzero perpendicular component. Scratch check: `maxabs(R*R^T-I)=2.22e-16`, `det(R)=0.9999999999999998`. | Interface gate must define the source and units/meaning of the orientation reference. |
| NR-007 | pass | `Local Frame and Transformation to Global Coordinates` | Reversed node order is numerically consistent when interpreted with swapped nodal DOF ordering. Scratch check: `K_reversed = P^T*K_forward*P` to roundoff for a representative element. | Reference Model Agent should include a reversed-node or equivalent orientation permutation test. |
| NR-008 | pass | `Element Equations and Residual Convention` | `RHS=-K_global*U` follows the researched Abaqus residual convention external minus internal for no element-generated loads. The formulation correctly keeps exact Abaqus fill behavior assigned to the I/O Definition Agent. | Interface gate must confirm the `RHS` array fill convention and no-Abaqus tests must lock the sign. |
| NR-009 | pass | `AMATRX and RHS Contribution Rules by Supported LFLAGS` | The supported `LFLAGS(3)=1,2,5` contribution split is numerically coherent for static requests. Unsupported mass, damping, dynamics, and large-displacement paths are explicitly out of scope. | Interface gate must define exact behavior for unsupported requests. |
| NR-010 | pass | `Numerical Tolerances and Validity Checks` | Zero-length, nonfinite inputs, nonpositive properties, near-parallel orientation, orthonormality, determinant, and symmetry checks are present. The `1.0e-8` near-parallel threshold is conservative enough for first implementation. | Test-model gate must include invalid length, invalid property, zero orientation, and near-parallel orientation negative cases. |
| NR-011 | pass | `State Variables, Energy, and Output Recovery` | No persistent `SVARS` are needed for a linear elastic, path-independent static element. Energy expression is correct but not required for first scope. | Interface gate should keep `SVARS` and `ENERGY` unused unless it adds an explicit output contract. |
| NR-012 | pass | `Mapping and Numerical Integration` | Analytical stiffness avoids integration-order and hourglass risks. The straight two-node centerline mapping is adequate for first-scope prismatic members. | Do not introduce reduced numerical integration in implementation planning. |

## Independent Scratch Checks

The review included a local scratch calculation using representative positive properties, non-axis-aligned coordinates, and a nonparallel orientation reference. This was not committed as a test because step 3 is a documentation-only review gate.

```text
L = 4.69041575982
local_sym = 0.000e+00
global_sym_raw = 7.451e-09
maxabs_K = 5.871224e+07
global_sym_normalized = 1.269e-16
scaled_symmetry_tolerance = 5.871e-05
R_orthonormality_error = 2.220e-16
detR = 0.9999999999999998
eig_small_count = 6
identity_orientation_K_equals_k = 0.000e+00
reversed_node_permuted_diff = 0.000e+00
```

Interpretation:

- The raw transformed symmetry difference is harmless because it is far below the formulation's scale-aware symmetry tolerance.
- Six near-zero eigenvalues match the expected rigid-body modes for a free two-node 3D beam element.
- The identity-orientation and reversed-node checks support the transformation convention.

## Numerical Risk Assessment

| risk | assessment | review result |
| --- | --- | --- |
| rigid_body_modes | Free element must have six rigid-body modes. Formulation states this, and scratch eigenvalue count supports it. | pass |
| patch_test | A constant axial strain, constant torsion rate, and constant curvature bending patch are representable by the interpolation. Multi-element patch expectations still need test-model specification. | pass |
| symmetry | Linear elastic closed-form stiffness and orthonormal transform preserve symmetry to roundoff. | pass |
| positive_definiteness | Free element is semidefinite; constrained models should become positive definite after removing rigid modes. | pass |
| hourglass | Not applicable because no reduced integration is used. | pass |
| shear_locking | Not applicable to this Euler-Bernoulli formulation; shear deformation is excluded. Applicability to deep beams is a modeling-scope risk, not a numerical defect. | pass |
| volumetric_locking | Not applicable. | pass |
| distortion | Curved, distorted, or tapered geometry is out of scope. Straight element validity reduces to nonzero length and valid orientation. | pass |
| singular_jacobian | Zero-length member and near-parallel orientation checks address the relevant singular cases. | pass |
| conditioning | Very short/long members and extreme property ratios can produce ill-conditioned matrices. The formulation flags this; downstream tests should cover scale-aware thresholds. | pass |
| convergence | For supported linear static cases, the tangent is constant and exactly consistent with internal force. Convergence risk is mainly interface sign/fill mistakes. | pass |

## Consistency Checks

| check | result | notes |
| --- | --- | --- |
| units | pass | `EA/L`, `12EI/L^3`, `6EI/L^2`, `4EI/L`, and `GJ/L` have the expected force, force/length, force, moment, and moment/radian roles under self-consistent units. |
| dimensions | pass | `AMATRX` is 12-by-12; `RHS`, `U`, local force, and residual vectors are length 12. |
| signs | pass | Bending signs are consistent with `th2=-dw/dx` and `th3=dv/dx`; residual sign remains an interface confirmation item. |
| dof_ordering | pass | Local ordering is consistent with Abaqus six-DOF node order after local/global projection. |
| coordinate_transforms | pass | `q_local=T*q_global`, `f_global=T^T*f_local`, and `K_global=T^T*k_local*T` preserve virtual work. |
| matrix_vector_dimensions | pass | All matrix-vector products in the algorithm pseudocode are dimensionally valid. |
| integration_weights | pass | Analytical closed-form stiffness avoids numerical quadrature ambiguity. |
| output_locations | pass | External comparison is limited to nodal global `U` and `RF`; element force output is deferred until an interface output path exists. |
| state_update | pass | No history state is needed for path-independent linear elasticity. |
| consistent_tangent | pass | `K_global` is the exact derivative of `f_int=K_global*U` for the first-scope linear static element. |

## Verification Readiness

Downstream no-Abaqus tests should include:

- `BM-NOA-AXIAL-001`: axial extension/compression checks for `EA/L`.
- `BM-NOA-TORSION-001`: torsion checks for `GJ/L`.
- `BM-NOA-BEND-Y-001`: local 2 bending with `w/th2` and `E*Iy`.
- `BM-NOA-BEND-Z-001`: local 3 bending with `v/th3` and `E*Iz`.
- `BM-NOA-RBM-001`: six free-element rigid-body modes and matrix symmetry.
- `BM-NOA-ROT-001`: arbitrary rotated element and identity-orientation transform checks.
- `BM-NOA-REVNODE-001`: reversed node order or equivalent nodal permutation check.
- `BM-NOA-RHS-001`: residual sign check for `RHS=-K_global*U` under the approved interface convention.
- invalid-input tests for zero length, nonfinite coordinates, nonpositive properties, zero orientation reference, and near-parallel orientation reference.

Patch/regression tests should include:

- one-element constant axial strain patch
- one-element pure torsion patch
- cantilever end-force bending about local 2 and local 3
- two-element collinear patch to catch assembly-order or transform mismatches
- rotated cantilever with non-axis-aligned local frame

External Abaqus reference comparison should remain limited to user-generated artifacts:

- nodal displacement `U`
- support reaction `RF`
- convergence/log tail evidence
- coordinate-system labels and units in extracted CSVs

No MMS case is required for this first linear structural element; closed-form beam benchmarks and matrix invariants are more direct.

## Required Revisions

### Formulation Agent

- None.

### Research Agent

- None.

### I/O Definition Agent

- Confirm the exact Abaqus `UEL` `RHS` fill convention for static `NRHS=1`.
- Define the `PROPS`/`JPROPS` or alternate mapping for `E`, `G`, `A`, `Iy`, `Iz`, `J`, and the orientation reference.
- Define the exact behavior for invalid inputs and unsupported `LFLAGS` requests.
- Define whether `ENERGY` remains untouched/zeroed or is populated in a later approved scope.
- Keep `SVARS` unused unless an explicit diagnostic output route is approved.

### Reference Model Agent

- Convert the verification readiness list above into no-Abaqus test cases before any production Fortran source changes.
- Define external Abaqus reference bundles only as user-generated `model.inp`, extracted CSV, tail logs, and metadata under `references/uel-3d-euler-beam/<model-id>/`.

## Downstream Handoff

### I/O Definition Agent

The formulation is numerically coherent enough to proceed to interface definition. Preserve the documented local DOF order, `Iy/Iz` axis mapping, transformation convention, and static residual physics.

### Implementation Planning Agent

Do not start production Fortran implementation from this review alone. Implementation planning may use this formulation after the interface contract and no-Abaqus test model plan are complete.

### Reference Model Agent

Use the `Verification Readiness` section as the minimum no-Abaqus regression set. Treat reversed-node behavior and residual sign as required tests, not optional checks.