diff --git a/PROGRESS.md b/PROGRESS.md index 7d291a5..483bd11 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -5,8 +5,8 @@ - Active objective: 3D Euler-Bernoulli beam Abaqus/Standard `UEL` - Active phase: `phases/uel-3d-euler-beam` - Active owner: unassigned -- Current status: completed `phases/uel-3d-euler-beam/step2.md` formulation step -- Next action: execute `phases/uel-3d-euler-beam/step3.md` numerical-review step +- Current status: completed `phases/uel-3d-euler-beam/step3.md` numerical-review step +- Next action: execute `phases/uel-3d-euler-beam/step4.md` interface-contract step ## Completed @@ -22,6 +22,9 @@ - Completed step 2 formulation for `uel-3d-euler-beam`. - Created `docs/formulations/uel-3d-euler-beam.md`. - Updated `phases/uel-3d-euler-beam/index.json` step 2 to `completed`. +- Completed step 3 numerical review for `uel-3d-euler-beam`. + - Created `docs/numerical-reviews/uel-3d-euler-beam.md`. + - Updated `phases/uel-3d-euler-beam/index.json` step 3 to `completed`. ## In Progress @@ -33,7 +36,7 @@ ## Last Verification -Latest verification after completing step 2 formulation: +Latest verification after completing step 3 numerical review: ```bash python -m unittest discover -s scripts -p "test_*.py" @@ -50,5 +53,5 @@ Result: all passed. - Read `AGENTS.md`, `PLAN.md`, `PROGRESS.md`, and `WORKNOTE.md`. - Confirm no other owner is active in this file. -- Start `phases/uel-3d-euler-beam/step3.md`. +- Start `phases/uel-3d-euler-beam/step4.md`. - Update this file when step status changes or before handing off. diff --git a/docs/numerical-reviews/uel-3d-euler-beam.md b/docs/numerical-reviews/uel-3d-euler-beam.md new file mode 100644 index 0000000..8785d24 --- /dev/null +++ b/docs/numerical-reviews/uel-3d-euler-beam.md @@ -0,0 +1,162 @@ +# 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//`. + +## 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. diff --git a/phases/uel-3d-euler-beam/index.json b/phases/uel-3d-euler-beam/index.json index 144f5ba..683435a 100644 --- a/phases/uel-3d-euler-beam/index.json +++ b/phases/uel-3d-euler-beam/index.json @@ -23,7 +23,8 @@ { "step": 3, "name": "numerical-review", - "status": "pending" + "status": "completed", + "summary": "Created docs/numerical-reviews/uel-3d-euler-beam.md with a pass-for-interface-definition verdict, pass/needs-change/blocked finding register, independent stiffness/transform/rigid-mode scratch checks, numerical risk assessment, verification readiness, and downstream handoff." }, { "step": 4,