diff --git a/docs/physics-evaluations/linear-static-3d-euler-beam-physics-evaluation.md b/docs/physics-evaluations/linear-static-3d-euler-beam-physics-evaluation.md new file mode 100644 index 0000000..8c8d4a8 --- /dev/null +++ b/docs/physics-evaluations/linear-static-3d-euler-beam-physics-evaluation.md @@ -0,0 +1,268 @@ +# Linear Static 3D Euler Beam Physics Evaluation Report + +## Metadata + +- feature_id: `linear-static-3d-euler-beam` +- model_id: `cantilever-beam-b33` +- evaluated_head: `d76d052456ec134a98bcd5aa3b3c18a6b0ad6ba4` +- source_reference_verification_report: `docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md` +- source_reference_model: `docs/reference-models/linear-static-3d-euler-beam-reference-models.md` +- source_requirement: `docs/requirements/linear-static-3d-euler-beam.md` +- source_formulation: `docs/formulations/3d-isoparametric-euler-beam-formulation.md` +- source_numerical_review: `docs/numerical-reviews/linear-static-3d-euler-beam-review.md` +- source_io_definition: `docs/io-definitions/linear-static-3d-euler-beam-io.md` +- status: `pass-for-release-agent` +- owner_agent: `physics-evaluation-agent` +- date: `2026-08-09` + +This verdict means that the documented physical checks pass and the Release Agent may audit +release readiness. It does not approve release readiness and does not re-evaluate the Step 26 +reference tolerance decision. + +## Input Evidence + +The reference-verification prerequisite has status `pass-for-physics-evaluation`. Its checked +artifact identity was reproduced before the physics checks and again after the targeted CTest. + +| evidence | exact path or identity | status | notes | +| --- | --- | --- | --- | +| reference verification | `docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md` | pass-for-physics-evaluation | Required gate satisfied. | +| solver HDF5 | `.harness/build/reference/cantilever-beam-b33/results.h5` | present and readable | 25,336 bytes; post-acceptance-run SHA-256 `13ECCF68262C14BBDE0F63667C0F10896ACD40EFEC56E8C9121C298333FD9B6D`. | +| comparison evidence | `.harness/build/reference/cantilever-beam-b33/comparison.json` | present and passing | 128,118 bytes; SHA-256 `258347AEA791D981AEA9B2BCAD85DE5344D4859ECA3692DC5E7AA01A848F8E0D`; `passed=true`, 176 rows, 16 metrics. | +| reference input | `reference/cantilever beam/cantilever beam.inp` | exact read-only artifact | SHA-256 `E406EA9560321B791DB829E03BD24593B9875E0195D35B86BD931EDA122EF3`; `TYPE=B33`. | +| reference displacement | `reference/cantilever beam/cantilever beam displacements.csv` | exact read-only artifact | SHA-256 `7B3312FBC8848E81D9A0FD4FF2B56BC1954636A2C14B5C1CBB269CB9477D3C31`. | +| reference reaction | `reference/cantilever beam/cantilever beam reactions.csv` | exact read-only artifact | SHA-256 `BF30CDB0CD50106885DE14D63492737736C587426EBD787DE4F7EE6AA86DAA23`. | +| reference elemental force | `reference/cantilever beam/cantilever beam elemental forces.csv` | exact read-only artifact | SHA-256 `E5E77FEC0FA9482AE018DBF296E74D396335C7C711BD2E9AA2315247A34290BA`. | +| solver CSV views | N/A | not used | No derived FESA CSV was generated or used. | +| stress reference CSV | N/A by approved contract | not applicable | `S11` is evaluated from HDF5 schema, formulation, and analytical/unit evidence only. | +| targeted physics tests | `.harness/build`, MSVC x64 Debug | pass | Exact Step 27 CTest passed 17/17: EulerBeam3D 10, ResultRecovery 6, B33ReferenceComparison 1. | + +Read-only HDF5 inspection confirmed schema `0`, solver `0.1.0`, feature identity, `Step-1` frame +`0`, formulation `B33-3D-Euler-Bernoulli`, source content identity +`fnv1a64:04543464cc970405`, and coordinate convention +`global-cartesian; beam-local=(t,n1,t-cross-n1)`. The file contains 11 nodes at +`(x,y,z)=(0..10,0,0)` m and 10 consecutive one-metre elements. Every element has identity local +axes, so local `(x,y,z)` equals global `(X,Y,Z)` for this model. + +The documented physical model is a 10 m cantilever with node 1 fixed in all six DOFs and a +free-end global/local `FZ=-1.0e6 N` at node 11. The section and material are SI: +`E=2.1e11 Pa`, `Iy=I11=0.0833333 m^4`, and the only expected deformation mode is local-`z` +translation with bending about local `y`. + +## Physics Checks + +All normalized physics criteria below come from the approved `1e-10` residual/equilibrium, +`1e-12` matrix/transform/end-sign, or `1e-9` analytical contracts. They are independent checks of +physical meaning, not a second application of the Abaqus row tolerance. + +### 1. global equilibrium + +In global Cartesian coordinates, force equilibrium is + +`r_F = sum(F_applied) + sum(R)`, + +with criterion + +`||r_F|| / max(||sum(F_applied)||, ||sum(R)||) <= 1e-10`. + +The comparison physics evidence records `sum(F_applied)=[0,0,-1000000] N` and +`sum(R)=[0,0,999999.9999998808] N`. Therefore +`r_F=[0,0,-1.1920928955078125e-7] N`, its norm is +`1.1920928955078125e-7 N`, and the normalized value is +`1.1920928955078125e-13`. Verdict: **pass**. + +Moment equilibrium about the global origin is + +`r_M = sum(M_applied) + sum(X cross F_applied) + sum(M_reaction) + sum(X cross R_force)`. + +The free-end force gives `[0,1.0e7,0] N*m`; the complete HDF5 reaction field gives +`[0,-9999999.999997258,0] N*m`. Thus `r_M=[0,2.7418136596679688e-6,0] N*m`, +with normalized norm `2.7418136596679688e-13` against `1.0e7 N*m`. Verdict: **pass**. + +### 2. reaction consistency and true free residual + +The constrained reaction contract is `R_c=(K*d-F)_c`. At fixed node 1 the observed global row is +`[RF1,RF2,RF3,RM1,RM2,RM3] = [0,0,1000000.0000008196,0,-10000000.000005051,0]` +in `[N,N,N,N*m,N*m,N*m]`. It opposes the applied `-Z` force and balances its positive origin +moment. Differences from the physical closed-form reactions are `8.195638656616211e-7 N` and +`5.0514936447143555e-6 N*m`, normalized to `8.195638656616211e-13` and +`5.0514936447143555e-13`. Verdict: **pass**. + +The reaction dataset intentionally preserves free residuals. The implementation uses + +`rho_f = ||(K*d-F)_f||_2 / max(||K*d||_f, ||F||_f)` + +with no artificial unit floor. The serialized true free residual norm is +`9.356339321107032e-7 N-equivalent`; the physical free scale is `1.0e6 N`, so +`rho_f=9.356339321107032e-13 <= 1e-10`. The largest observed free force-residual component is +`5.9604644775390625e-7 N`, and the largest free moment-residual component is +`2.0861625671386719e-7 N*m`. Verdict: **pass**. + +### 3. displacement direction and rotation sign + +For free-end local `Pz=-1.0e6 N`, the documented Euler-Bernoulli solution is + +`w(L)=Pz*L^3/(3*E*Iy)`, `theta_y(L)=-Pz*L^2/(2*E*Iy)`. + +The expected values are `-0.0190476266666697 m` and `+0.00285714400000046 rad`. +HDF5 gives tip `UZ=-0.019047626666677083 m` and `URY=+0.0028571440000013902 rad`, with relative +errors `3.87e-13` and `3.27e-13`, below the analytical `1e-9` criterion. All non-root `UZ` values +are negative and monotonically increase in magnitude toward the loaded tip; all non-root `URY` +values are positive, as required by `theta_y=-dw/dx`. Verdict: **pass**. + +### 4. expected zero and uncoupled symmetry + +The fixed-root displacement row is exactly zero in all six components. Across all nodes, +`UX`, `UY`, `URX`, and `URZ` are exactly zero. The only nonzero kinematic components are `UZ` and +`URY`, and the only physical constrained reactions are `RF3` and `RM2`. In the element recovery, +`epsilon0`, `kappa_x`, and `kappa_z`, and the corresponding `N`, `T`, and `Mz`, are exactly zero. +This is the documented uncoupled local-`z` bending symmetry, with no axial, torsional, or +cross-plane leakage. Verdict: **pass**. + +### 5. element force, adjacent endpoints, and boundary balance + +The HDF5 `end_force_local` rows are outward endpoint actions in +`[FX,FY,FZ,MX,MY,MZ]`; `section_resultant` rows are positive-local-`x` section cuts in +`[N,T,My,Mz]`. With no distributed load, + +`F_X=n*N`, `M_X=n*T`, `M_Y=n*My`, `M_Z=n*Mz`, +`F_Y=-n*dMz/dx`, and `F_Z=n*dMy/dx`, where `n=-1` at `xi=-1` and `n=+1` at `xi=+1`. + +Observed section `My` is positive and decreases linearly from +`10000000.000005048 N*m` at the root to `2.4286118949223834e-7 N*m` at the free end. The maximum +positive-face `My` mismatch between adjacent unloaded endpoints is +`2.73110345005989e-7 N*m`, normalized to `2.73110345005989e-14` against the model moment scale. +The comparison ledger independently records `endpoint_consistency_passed=true` without averaging. + +Adjacent outward actions cancel. The maximum interior `FZ_right+FZ_left` magnitude is +`5.364418029785156e-7 N` (`5.364418029785156e-13` normalized); the maximum interior +`MY_right+MY_left` magnitude is `2.682209014892578e-7 N*m` +(`2.682209014892578e-14` normalized). Both satisfy the documented end-sign/residual criteria. + +At the root, the first element action is exactly the constrained reaction evidence: +`FZ=+1000000.0000008196 N`, `MY=-10000000.000005051 N*m`. At the free boundary, the last element +has `FZ=-999999.9999998808 N` and `MY=-5.9604644775390625e-8 N*m`, balancing the applied end force +and the zero applied end moment to normalized residual scale. Verdict: **pass**. + +### 6. local/global mapping and section-force signs + +Every stored local-axis matrix is the identity. Therefore the global `-Z` load is local +`Pz=-1.0e6 N`, `UZ=w<0`, `URY=theta_y>0`, and the positive-face section resultant is +`My=-Pz*(L-x)>0`. The observed outward signs are `FZ>0, MY<0` at left endpoints and +`FZ<0, MY>0` at right endpoints, except for the physically zero free-end moment residue. These +values satisfy the documented `theta_y=-w'`, `My=-E*Iy*w''`, outward-normal, and +positive-face-section-cut conventions. Verdict: **pass**. + +### 7. stress location, unit, and sign sanity + +The stress contract is + +`S11(xi,y,z)=E*(epsilon0 + z*kappa_y - y*kappa_z)`, + +where `x1=y`, `x2=z`, the coordinate system is beam local, the unit is `force/length^2`, and the +location is a section point at each of two Gauss points. The reference input has no section +points, so HDF5 correctly contains 20 ordered `fesa-default` centroid rows +`(x1,x2)=(0,0)`, one at each Gauss point of ten elements. This model has pure bending with +`epsilon0=0`; consequently all 20 observed centroid `S11` values are exactly `0 Pa`. + +Nonzero location/sign evidence comes only from the approved analytical/unit portfolio, not from +an Abaqus stress comparison. `EulerBeam3D.RecoversSectionPointAndDefaultCentroidS11` passed with +`epsilon0=0.01`, `kappa_y=0.02 1/m`, `kappa_z=-0.03 1/m`, `E=2.1e11 Pa`: the formula gives +`1.575e9 Pa` at `(y,z)=(0.25,-0.5)`, `8.4e8 Pa` at `(-0.4,0.3)`, and `2.1e9 Pa` at the default +centroid. The test enforces the formula at both Gauss points with normalized `1e-12` evidence. +Abaqus beam stress comparison remains explicitly N/A. Verdict: **pass**. + +### 8. nonfinite, rigid-body, abnormal-magnitude, and energy symptoms + +All mandatory numeric HDF5 rows inspected here are finite; `comparison.json` also records no +nonfinite row among the 176 compared rows and the 20 stress rows are finite. The fixed root is +exactly zero, factorization/solution completed, the normalized free residual is `9.36e-13`, and +the displacement field is smooth, so there is no rigid-body-mode symptom. + +For this one-load linear case, the recoverable strain energy is +`U=0.5*F^T*d=9523.81333333854 N*m`, which is finite and positive. The ratios +`|UZ_tip|/L=0.00190476266666771` and `|URY_tip|=0.00285714400000139 rad` agree with the analytical +solution and show no abnormal magnitude relative to the documented small-displacement/rotation +model. The targeted rank/energy test also passed the six-rigid-mode, rank-six, and positive +deformation-energy checks. Verdict: **pass**. + +### 9. model coverage + +The approved B33 bundle is one identity-axis local-`z` bending cantilever. It directly covers the +end-to-end parser/solver/HDF5 path, global equilibrium, reaction sign, `UZ/URY`, `My/FZ`, endpoint +continuity, and the centroid stress fallback. It does not by itself cover axial, torsion, local-`y` +bending, rotated space, nonzero fiber stress, prescribed displacement, or the formulation-only +line-load kernel. The targeted analytical/unit portfolio supplies the documented complementary +coverage: + +| coverage | targeted passing evidence | criterion | +| --- | --- | --- | +| axial, torsion, both bending planes | `EulerBeam3D.AnalyticalAxialTorsionAndTwoPlaneBendingRecover` and `ResultRecovery.MatchesAxialTorsionAndTwoPlaneEndSigns` | analytical relative `1e-9`; signed recovery contract | +| rotated local/global mapping | `EulerBeam3D.RotatedTransformPreservesWorkAndEnergy` | transform/work/energy normalized `1e-12` | +| constant local line-load kernel | `EulerBeam3D.ConstantLineLoadMatchesAllSignedComponents` | all 12 signed components normalized `1e-12`; `*DLOAD` remains outside CLI scope | +| rigid modes, rank, and energy | `EulerBeam3D.HasSixRigidModesRankSixAndPositiveDeformationEnergy` | rigid residual `1e-10`, rank six, positive deformation energy | +| prescribed displacement and residual | `ResultRecovery.ComputesResidualReactionForNonzeroPrescription`, `ResultRecovery.EnforcesNormalizedFreeResidual` | partition/reaction and normalized residual `1e-10` | +| result identity and continuity | `ResultRecovery.KeepsEndActionSectionAndGaussResultsDistinct`, `ResultRecovery.RequiresInteriorEndpointConsistencyWithoutAveraging` | distinct locations and no-average consistency | +| S11 location/sign/default | `EulerBeam3D.RecoversSectionPointAndDefaultCentroidS11`, `ResultRecovery.OrdersStressPointsAndDefaultCentroid` | formula/schema normalized `1e-12` | + +The exact acceptance command passed all 17 selected tests. The single reference model plus this +analytical portfolio covers every documented physical expectation without attributing unsupported +coverage to the legacy CSV bundle. Verdict: **pass**. + +## Failure Classification + +- classification: `N/A` +- primary_failure: `N/A` +- evidence: all documented physics checks passed; no equilibrium, reaction, displacement, + symmetry, element-force, stress-location, rigid-body, nonfinite, coverage, contract, or + environment failure was found +- correction_handoff: `N/A` + +## Evaluation Verdict + +- verdict: `pass-for-release-agent` +- reason: the exact reference gate and artifact identity are valid; force and origin-moment + equilibrium, constrained reaction consistency, true free residual, deformation signs, expected + zeros, element force balance, local/global and section-force signs, S11 schema/analytical sanity, + finite/energy/mode checks, and complementary model coverage all satisfy their documented criteria +- release_approval: `not granted by this report` + +## Handoff Recommendation + +| target_agent | reason | required_input | +| --- | --- | --- | +| Release Agent | All documented physical checks passed. | This report, the Step 26 reference-verification report, exact build-local HDF5/comparison identities, targeted CTest evidence, and the limitations below. | + +## No-Change Assertion + +- source_files_modified: `false` +- test_files_modified: `false` +- cmake_files_modified: `false` +- requirements_modified: `false` +- formulations_modified: `false` +- numerical_review_modified: `false` +- io_contract_modified: `false` +- reference_model_contract_modified: `false` +- reference_verification_report_modified: `false` +- reference_artifacts_modified: `false` +- tolerance_policies_modified: `false` +- Abaqus_or_other_reference_solver_executed: `false` +- owned_report_created: `true` +- phase_index_step27_modified: `true` +- notes: HDF5, comparison JSON, and legacy reference artifacts were inspected read-only; the only + generated files were the ignored build-local evidence regenerated by the exact approved CTest. + +## Open Issues + +- Non-blocking coverage limitation: the approved Abaqus bundle is one identity-axis local-`z` + bending cantilever. Axial, torsion, local-`y`, rotated, prescribed-displacement, line-load, and + nonzero stress checks rely on the approved analytical/unit portfolio; no broader Abaqus reference + coverage is claimed. +- Non-blocking stress limitation: the B33 bundle has no section points, so its physical `S11` + evidence is the correct zero centroid result. Nonzero fiber location/sign evidence is analytical; + Abaqus beam stress comparison remains N/A. +- Non-blocking output limitation: HDF5 has no strain-energy dataset by contract. The positive energy + value in this report is calculated from `0.5*F^T*d` and is supported by the rank/energy unit test. +- Known formulation limitations remain: Euler-Bernoulli deep-beam applicability, transverse and + torsional shear stress, warping, `I12!=0`, B31/Timoshenko behavior, and CLI `*DLOAD` are outside V0. +- No open issue blocks Release Agent review.