docs: plan 3d euler beam reference models

2026-06-11 13:48:30 +09:00
parent d23b08db8c
commit a07a92ed4b
3 changed files with 538 additions and 5 deletions
@@ -0,0 +1,529 @@
+# 3D Euler-Bernoulli Beam UEL Reference Models
+
+## 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`
+- source_numerical_review: `docs/numerical-reviews/uel-3d-euler-beam.md`
+- source_io_definition: `docs/io-definitions/uel-3d-euler-beam.md`
+- status: ready-for-tdd-test-creation
+- owner_agent: reference-model-agent
+- date: 2026-06-11
+
+## Reference Strategy
+
+- verification_scope: first-scope two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam Abaqus/Standard `UEL`
+- code_verification: no-Abaqus Fortran drivers must verify local stiffness, transformation, rigid modes, residual sign, ABI array mapping, and invalid-input diagnostics before production Fortran is implemented
+- solution_verification: future user-generated Abaqus reference bundles must compare nodal displacement and reaction CSVs for straight and rotated beam cases
+- benchmark_reference_comparison: native Abaqus beam comparison is planned only after the user creates external artifacts on an Abaqus PC
+- excluded_validation_scope: no physical experiment validation, no direct ODB parsing, no repository-run Abaqus jobs, no fake reference CSV generation
+
+This document is a test and artifact plan. It does not create Fortran source, test files, manifest files, input decks, CSVs, or reference artifacts.
+
+## Planned Production and Test Source Layout
+
+The next implementation gates should use this planned layout unless a later approved implementation plan changes it.
+
+Production source paths planned for later steps:
+
+| path | purpose | no-Abaqus test role |
+| --- | --- | --- |
+| `src/fortran/uel_3d_euler_beam_kernel.f90` | pure/testable beam geometry, local stiffness, transform, residual, and validation logic | compiled by all no-Abaqus kernel and ABI adapter tests |
+| `src/fortran/uel_3d_euler_beam_abi_adapter.f90` | Abaqus-array adapter logic without the literal Abaqus `UEL` entry point | compiled by no-Abaqus ABI mapping tests |
+| `src/fortran/uel_3d_euler_beam_uel.for` | thin Abaqus/Standard fixed-form `UEL` wrapper preserving the manual signature and `ABA_PARAM.INC` include | not required for no-Abaqus compile in first RED tests; later wrapper smoke can be added when an Abaqus-compatible include environment is available |
+
+Planned test source paths for step 6:
+
+| path | purpose |
+| --- | --- |
+| `tests/fortran/manifest.json` | Intel Fortran no-Abaqus validation manifest consumed by `scripts/validate_fortran.py` |
+| `tests/fortran/uel_3d_euler_beam/test_support.f90` | simple assertion, tolerance, vector/matrix comparison helpers |
+| `tests/fortran/uel_3d_euler_beam/test_kernel_stiffness.f90` | local stiffness and analytical response tests |
+| `tests/fortran/uel_3d_euler_beam/test_kernel_transform_modes.f90` | transformation, symmetry, reversed node order, and rigid-body mode tests |
+| `tests/fortran/uel_3d_euler_beam/test_abi_static.f90` | no-Abaqus ABI adapter tests for `RHS`, `AMATRX`, `ENERGY`, dimensions, and `LFLAGS` |
+| `tests/fortran/uel_3d_euler_beam/test_invalid_inputs.f90` | validation diagnostics and unsupported-request tests |
+
+Step 6 RED expectation:
+
+- After `tests/fortran/manifest.json` and the planned test drivers are created, `python scripts/validate_fortran.py` should fail before production implementation because planned production sources are missing or unimplemented.
+- If step 6 creates temporary stubs to reach executable assertions, the targeted assertions must fail for missing stiffness, transformation, residual, or validation behavior before step 7 implementation.
+
+## Planned `tests/fortran/manifest.json`
+
+The current `scripts/validate_fortran.py` manifest schema is:
+
+```json
+{
+  "tests": [
+    {
+      "name": "test_name",
+      "sources": ["path/to/source.f90"]
+    }
+  ]
+}
+```
+
+Step 6 should create this planned manifest:
+
+```json
+{
+  "tests": [
+    {
+      "name": "uel_3d_euler_beam_kernel_stiffness",
+      "sources": [
+        "tests/fortran/uel_3d_euler_beam/test_support.f90",
+        "src/fortran/uel_3d_euler_beam_kernel.f90",
+        "tests/fortran/uel_3d_euler_beam/test_kernel_stiffness.f90"
+      ]
+    },
+    {
+      "name": "uel_3d_euler_beam_kernel_transform_modes",
+      "sources": [
+        "tests/fortran/uel_3d_euler_beam/test_support.f90",
+        "src/fortran/uel_3d_euler_beam_kernel.f90",
+        "tests/fortran/uel_3d_euler_beam/test_kernel_transform_modes.f90"
+      ]
+    },
+    {
+      "name": "uel_3d_euler_beam_abi_static",
+      "sources": [
+        "tests/fortran/uel_3d_euler_beam/test_support.f90",
+        "src/fortran/uel_3d_euler_beam_kernel.f90",
+        "src/fortran/uel_3d_euler_beam_abi_adapter.f90",
+        "tests/fortran/uel_3d_euler_beam/test_abi_static.f90"
+      ]
+    },
+    {
+      "name": "uel_3d_euler_beam_invalid_inputs",
+      "sources": [
+        "tests/fortran/uel_3d_euler_beam/test_support.f90",
+        "src/fortran/uel_3d_euler_beam_kernel.f90",
+        "src/fortran/uel_3d_euler_beam_abi_adapter.f90",
+        "tests/fortran/uel_3d_euler_beam/test_invalid_inputs.f90"
+      ]
+    }
+  ]
+}
+```
+
+## No-Abaqus Test Inventory
+
+| test_id | manifest_test | category | purpose | expected RED before implementation | primary requirements |
+| --- | --- | --- | --- | --- | --- |
+| NOA-K-STIFF-001 | `uel_3d_euler_beam_kernel_stiffness` | analytical unit | verify exact `12x12` local stiffness entries for axial, torsion, `Iy`, and `Iz` subblocks | compile failure from missing kernel or assertion failure on zero/unimplemented matrix | REQ-002, REQ-005, REQ-008 |
+| NOA-K-STIFF-002 | `uel_3d_euler_beam_kernel_stiffness` | analytical unit | verify axial response `EA/L` under `u2-u1` displacement | same as above | REQ-002, REQ-008 |
+| NOA-K-STIFF-003 | `uel_3d_euler_beam_kernel_stiffness` | analytical unit | verify torsional response `GJ/L` under `th1_2-th1_1` rotation | same as above | REQ-002, REQ-008 |
+| NOA-K-BEND2-001 | `uel_3d_euler_beam_kernel_stiffness` | analytical unit | verify local 2 bending using `w/th2` and `E*Iy` terms | same as above | REQ-002, REQ-005, REQ-008 |
+| NOA-K-BEND3-001 | `uel_3d_euler_beam_kernel_stiffness` | analytical unit | verify local 3 bending using `v/th3` and `E*Iz` terms | same as above | REQ-002, REQ-005, REQ-008 |
+| NOA-K-SYM-001 | `uel_3d_euler_beam_kernel_transform_modes` | matrix invariant | verify `K_global` symmetry with scale-aware tolerance | compile failure or symmetry assertion failure | REQ-008, REQ-015 |
+| NOA-K-RBM-001 | `uel_3d_euler_beam_kernel_transform_modes` | matrix invariant | verify six rigid-body displacement vectors produce near-zero internal force for an identity-frame beam | compile failure or nonzero rigid-mode residual | REQ-002, REQ-012 |
+| NOA-K-ROT-001 | `uel_3d_euler_beam_kernel_transform_modes` | transformation | verify identity orientation gives `K_global=k_local` and arbitrary rotation gives `K_global=T^T*k_local*T` | compile failure or transform mismatch | REQ-007, REQ-008 |
+| NOA-K-REVNODE-001 | `uel_3d_euler_beam_kernel_transform_modes` | regression | verify reversed node order is equivalent to permuting nodal DOFs with the documented local axis convention | compile failure or permutation mismatch | REQ-004, REQ-007 |
+| NOA-A-RHS-001 | `uel_3d_euler_beam_abi_static` | ABI/residual | verify `RHS(1:12,1)=-K_global*U(1:12)` for `LFLAGS(3)=1` and `5` | compile failure or wrong sign | REQ-009 |
+| NOA-A-AMATRX-001 | `uel_3d_euler_beam_abi_static` | ABI/stiffness | verify `AMATRX=K_global` for `LFLAGS(3)=1` and `2` and zeroed matrix for residual-only requests | compile failure or mapping mismatch | REQ-003, REQ-004, REQ-008 |
+| NOA-A-PROPS-001 | `uel_3d_euler_beam_abi_static` | ABI/property mapping | verify `PROPS(1:9)` maps to `E,G,A,Iy,Iz,J,a_ref_1,a_ref_2,a_ref_3` exactly | compile failure or property permutation mismatch | REQ-005, REQ-007 |
+| NOA-A-ENERGY-001 | `uel_3d_euler_beam_abi_static` | ABI/output policy | verify `ENERGY(1:8)=0.0`, `NSVARS=0`, and `PNEWDT` is not changed for valid supported calls | compile failure or output policy mismatch | REQ-010 |
+| NOA-I-SHAPE-001 | `uel_3d_euler_beam_invalid_inputs` | negative | verify diagnostics for `NDOFEL`, `NNODE`, `MCRD`, `NPROPS`, `NJPROP`, `NSVARS`, `NRHS`, `MLVARX` violations | compile failure or missing diagnostic | REQ-003, REQ-006 |
+| NOA-I-PHYS-001 | `uel_3d_euler_beam_invalid_inputs` | negative | verify diagnostics for nonfinite coordinates/properties, nonpositive `E,G,A,Iy,Iz,J`, zero length, zero orientation, and near-parallel orientation | compile failure or missing diagnostic | REQ-006, REQ-007 |
+| NOA-I-LFLAGS-001 | `uel_3d_euler_beam_invalid_inputs` | negative | verify diagnostics for unsupported `LFLAGS(2)`, unsupported `LFLAGS(3)`, and `NDLOAD /= 0` | compile failure or missing diagnostic | REQ-010 |
+
+Default no-Abaqus tolerances:
+
+- stiffness absolute tolerance: `1.0e-10` after scale-aware normalization
+- stiffness relative tolerance: `1.0e-10`
+- vector absolute tolerance: `1.0e-10` after scale-aware normalization
+- vector relative tolerance: `1.0e-10`
+- symmetry normalized tolerance: `1.0e-12`
+- exact validation diagnostics: string or integer status identity match
+
+## Wrapper or Smoke-Test Strategy Without Abaqus
+
+The production `UEL` wrapper itself should remain a thin Abaqus ABI entry point. No-Abaqus smoke testing should target `uel_3d_euler_beam_abi_adapter.f90`, which receives arrays shaped like the Abaqus `UEL` arguments but does not require Abaqus to call it.
+
+The ABI adapter tests must verify:
+
+- `NDOFEL=12`, `NNODE=2`, `MCRD>=3`, `NPROPS=9`, `NJPROP=0`, `NSVARS=0`, `NRHS=1`, and `MLVARX>=12`
+- `COORDS(1:3,1:2)` maps to `X1`, `X2`
+- `U(1:12)` maps to the global kernel vector without permutation
+- `PROPS(1:9)` maps exactly to the interface contract
+- `LFLAGS(3)=1`, `2`, and `5` select the expected `AMATRX` and `RHS` outputs
+- non-requested `AMATRX` or `RHS` storage is deterministically zeroed by the no-Abaqus adapter
+- `ENERGY(1:8)` is zeroed and `SVARS` is unused
+
+## Future External Abaqus Reference Model Inventory
+
+All external models are future user-generated evidence and start with `artifact_status=needs-reference-artifacts`.
+
+| model_id | category | purpose | status | required_artifacts |
+| --- | --- | --- | --- | --- |
+| `ext-uel-smoke-static` | smoke | one UEL element with supported keyword subset, basic convergence, and nonzero stiffness path | needs-reference-artifacts | `model.inp`, metadata, log tails, `nodal_displacements.csv`, `reactions.csv` |
+| `ext-cantilever-axial` | analytical/reference | straight cantilever axial extension against nodal `U1` and support `RF1` | needs-reference-artifacts | same |
+| `ext-cantilever-torsion` | analytical/reference | straight cantilever torsion against nodal `UR1` and support `RM1` | needs-reference-artifacts | same |
+| `ext-cantilever-bend-local2` | analytical/reference | local 2 bending, `w/th2` response, displacement/reaction/moment sanity | needs-reference-artifacts | same |
+| `ext-cantilever-bend-local3` | analytical/reference | local 3 bending, `v/th3` response, displacement/reaction/moment sanity | needs-reference-artifacts | same |
+| `ext-rotated-cantilever` | orientation regression | non-axis-aligned element with explicit `PROPS(7:9)` orientation vector | needs-reference-artifacts | same |
+| `ext-two-element-collinear` | patch/regression | two collinear UEL elements with continuous displacement field and equilibrium reactions | needs-reference-artifacts | same |
+
+No element-force CSV is required for first-scope external comparison. Element-level force comparison remains deferred until a later `SVARS` or output-recovery contract is approved.
+
+## External Model Records
+
+### `ext-uel-smoke-static`
+
+- category: smoke
+- purpose: verify supported Abaqus keyword subset and UEL call path using a single static element
+- verified_requirements: REQ-001, REQ-003, REQ-004, REQ-005, REQ-008, REQ-009, REQ-011, REQ-013, REQ-014, REQ-015
+- analysis_type: linear static small-displacement
+- element_type: `TYPE=U1`, two-node UEL
+- material/section data: `PROPS(1:9)` per interface contract
+- boundary_conditions: node 1 fixed in DOFs 1-6; node 2 constrained as needed to prevent unintended mechanisms for the chosen load
+- loads: one small nodal concentrated load or moment within the supported `*CLOAD` scope
+- expected_physical_quantities: nodal displacement, reaction, convergence/log status
+- tolerance: external displacement absolute `1.0e-8`; reaction relative `1.0e-6` plus model-specific near-zero absolute floor
+- artifact_status: needs-reference-artifacts
+
+### `ext-cantilever-axial`
+
+- category: analytical/reference
+- purpose: isolate axial stiffness and global `U1/RF1` behavior for a straight beam aligned with global x
+- verified_requirements: REQ-002, REQ-005, REQ-008, REQ-009, REQ-013, REQ-014, REQ-015
+- boundary_conditions: node 1 fixed in DOFs 1-6; node 2 constrained to allow only axial extension when needed by the benchmark
+- loads: nodal force in global `U1` direction at node 2
+- expected_physical_quantities: node 2 `U1`, node 1 `RF1`, global equilibrium
+- artifact_status: needs-reference-artifacts
+
+### `ext-cantilever-torsion`
+
+- category: analytical/reference
+- purpose: isolate torsional stiffness and rotational reaction about local/global 1 for a straight beam aligned with global x
+- verified_requirements: REQ-002, REQ-005, REQ-008, REQ-009, REQ-013, REQ-014, REQ-015
+- boundary_conditions: node 1 fixed in DOFs 1-6; node 2 constrained to isolate `UR1` rotation when needed
+- loads: nodal moment about global `UR1` at node 2
+- expected_physical_quantities: node 2 `UR1`, node 1 `RM1`, global moment equilibrium
+- artifact_status: needs-reference-artifacts
+
+### `ext-cantilever-bend-local2`
+
+- category: analytical/reference
+- purpose: verify local 2 bending using `E*Iy` with `w/th2` response
+- verified_requirements: REQ-002, REQ-005, REQ-007, REQ-008, REQ-009, REQ-013, REQ-014, REQ-015
+- boundary_conditions: node 1 fixed in DOFs 1-6
+- loads: nodal force or moment at node 2 selected to activate local 1-3 plane bending
+- expected_physical_quantities: node 2 global displacement component corresponding to local `w`, node 2 rotation component, support force and moment
+- artifact_status: needs-reference-artifacts
+
+### `ext-cantilever-bend-local3`
+
+- category: analytical/reference
+- purpose: verify local 3 bending using `E*Iz` with `v/th3` response
+- verified_requirements: REQ-002, REQ-005, REQ-007, REQ-008, REQ-009, REQ-013, REQ-014, REQ-015
+- boundary_conditions: node 1 fixed in DOFs 1-6
+- loads: nodal force or moment at node 2 selected to activate local 1-2 plane bending
+- expected_physical_quantities: node 2 global displacement component corresponding to local `v`, node 2 rotation component, support force and moment
+- artifact_status: needs-reference-artifacts
+
+### `ext-rotated-cantilever`
+
+- category: orientation regression
+- purpose: verify global coordinate transformation and explicit `PROPS(7:9)` orientation vector for a non-axis-aligned element
+- verified_requirements: REQ-004, REQ-007, REQ-008, REQ-009, REQ-013, REQ-014, REQ-015
+- boundary_conditions: node 1 fixed in DOFs 1-6
+- loads: nodal load at node 2 with a component that exercises transformed bending
+- expected_physical_quantities: global nodal displacement, support reaction, coordinate-system labels
+- artifact_status: needs-reference-artifacts
+
+### `ext-two-element-collinear`
+
+- category: patch/regression
+- purpose: verify two-element collinear assembly behavior, continuity, and equilibrium for the UEL input subset
+- verified_requirements: REQ-002, REQ-003, REQ-004, REQ-008, REQ-009, REQ-013, REQ-014, REQ-015
+- boundary_conditions: one end fixed; middle node free; end node loaded
+- loads: axial or bending load chosen by the external reference model author
+- expected_physical_quantities: displacements at free nodes and reactions at constrained node
+- artifact_status: needs-reference-artifacts
+
+## Abaqus Input Requirements
+
+Every external `model.inp` must stay within the supported keyword subset from `docs/io-definitions/uel-3d-euler-beam.md`:
+
+- `*HEADING`
+- `*NODE`
+- `*ELEMENT`
+- `*ELSET`
+- `*NSET`
+- `*USER ELEMENT, TYPE=U1, NODES=2, COORDINATES=3, PROPERTIES=9, VARIABLES=0`
+- active DOF line: `1, 2, 3, 4, 5, 6`
+- `*UEL PROPERTY, ELSET=<uel_element_set>` with data order `E,G,A,Iy,Iz,J,a_ref_1,a_ref_2,a_ref_3`
+- `*BOUNDARY`
+- `*CLOAD`
+- `*STEP`
+- `*STATIC`
+- `*OUTPUT`
+- `*NODE OUTPUT`
+- `*END STEP`
+
+Unsupported keywords remain unsupported for these reference models, including distributed loads, density/mass/dynamics, native beam section keywords for the UEL, `*ORIENTATION` as UEL orientation input, nonlinear geometry, thermal, plasticity, damage, and element output claims.
+
+Required output requests:
+
+- nodal displacement output sufficient to populate `extracted/nodal_displacements.csv`
+- nodal reaction output sufficient to populate `extracted/reactions.csv`
+- log/status outputs through Abaqus `.msg`, `.dat`, `.log`, and `.sta` files
+
+## Artifact Bundle Contract
+
+Future user-provided reference artifacts must use this structure:
+
+```text
+references/
+  uel-3d-euler-beam/
+    <model-id>/
+      README.md
+      model.inp
+      metadata.json
+      job.msg.tail.txt
+      job.dat.tail.txt
+      job.log.tail.txt
+      job.sta.tail.txt
+      result.odb.sha256
+      extraction/
+        extract_odb_to_csv.py
+      extracted/
+        nodal_displacements.csv
+        reactions.csv
+```
+
+Required for `ready-for-comparison`:
+
+- `README.md`
+- `model.inp`
+- `metadata.json`
+- `job.msg.tail.txt`
+- `job.dat.tail.txt`
+- `job.log.tail.txt`
+- `job.sta.tail.txt`
+- all CSV files declared in `metadata.json`
+- source hash entries for the exact user subroutine source files used after implementation exists
+- Abaqus version, precision, compiler vendor/name/version, extraction provenance, units, coordinate system, and tolerance policy
+
+Optional:
+
+- `result.odb.sha256` when the ODB is not stored but the result database identity must be tracked
+- `extraction/extract_odb_to_csv.py` when the user can provide the extraction script
+- extra notes files that do not replace required metadata
+
+Reference artifacts must remain `needs-reference-artifacts` until the user supplies all required files. This repository must not fabricate CSVs or log tails.
+
+## Metadata JSON Contract
+
+Each `metadata.json` must use schema version `abaqus-user-subroutine-artifact-v1` and include at least:
+
+```json
+{
+  "schema_version": "abaqus-user-subroutine-artifact-v1",
+  "feature_id": "uel-3d-euler-beam",
+  "model_id": "<model-id>",
+  "artifact_status": "needs-reference-artifacts | ready-for-comparison | blocked",
+  "abaqus": {
+    "version": "<Abaqus version>",
+    "precision": "single | double"
+  },
+  "compiler": {
+    "vendor": "Intel oneAPI",
+    "name": "ifx | ifort",
+    "version": "<compiler version>"
+  },
+  "subroutine": {
+    "entry_points": ["UEL"],
+    "source_files": [
+      {
+        "path": "src/fortran/uel_3d_euler_beam_kernel.f90",
+        "language": "Fortran",
+        "sha256": "<sha256 after implementation exists>"
+      },
+      {
+        "path": "src/fortran/uel_3d_euler_beam_abi_adapter.f90",
+        "language": "Fortran",
+        "sha256": "<sha256 after implementation exists>"
+      },
+      {
+        "path": "src/fortran/uel_3d_euler_beam_uel.for",
+        "language": "Fortran",
+        "sha256": "<sha256 after implementation exists>"
+      }
+    ]
+  },
+  "input_file": "model.inp",
+  "units": {
+    "length": "<declared length unit>",
+    "force": "<declared force unit>",
+    "stress": "<declared stress unit>",
+    "moment": "<declared force*length unit>",
+    "rotation": "radian"
+  },
+  "coordinate_system": "GLOBAL",
+  "analysis_type": "linear static small-displacement",
+  "element_types": ["U1"],
+  "outputs": {
+    "tails": {
+      "msg": "job.msg.tail.txt",
+      "dat": "job.dat.tail.txt",
+      "log": "job.log.tail.txt",
+      "sta": "job.sta.tail.txt"
+    },
+    "csv": {
+      "nodal_displacements": "extracted/nodal_displacements.csv",
+      "reactions": "extracted/reactions.csv"
+    }
+  },
+  "extraction": {
+    "source_odb": "job.odb",
+    "tool": "Abaqus Python",
+    "extracted_at": "<ISO-8601 datetime>",
+    "csv_directory": "extracted",
+    "script": "extraction/extract_odb_to_csv.py",
+    "odb_sha256_file": "result.odb.sha256"
+  },
+  "comparisons": {
+    "nodal_displacements": {
+      "reference_csv": "extracted/nodal_displacements.csv",
+      "required_columns": ["step", "frame", "time", "instance", "node_label", "quantity", "component", "coordinate_system", "unit", "value"],
+      "key_columns": ["step", "frame", "instance", "node_label", "quantity", "component"],
+      "value_column": "value",
+      "unit_column": "unit",
+      "coordinate_system_column": "coordinate_system",
+      "tolerance": {
+        "absolute": 1.0e-8,
+        "relative": 1.0e-8,
+        "relative_floor": 1.0e-12
+      }
+    },
+    "reactions": {
+      "reference_csv": "extracted/reactions.csv",
+      "required_columns": ["step", "frame", "time", "instance", "node_label", "quantity", "component", "coordinate_system", "unit", "value"],
+      "key_columns": ["step", "frame", "instance", "node_label", "quantity", "component"],
+      "value_column": "value",
+      "unit_column": "unit",
+      "coordinate_system_column": "coordinate_system",
+      "tolerance": {
+        "absolute": "<model-specific near-zero floor>",
+        "relative": 1.0e-6,
+        "relative_floor": 1.0e-12
+      }
+    }
+  }
+}
+```
+
+The `absolute` reaction tolerance must be set per external model using a declared load or moment scale. A recommended policy is:
+
+```text
+reaction_absolute_floor = 1.0e-10 * max(1.0, abs(total_applied_force_or_moment_in_matching_unit))
+```
+
+## Reference CSV Requirements
+
+### `extracted/nodal_displacements.csv`
+
+Required columns:
+
+| column | type | rule |
+| --- | --- | --- |
+| `step` | string | Abaqus step name or stable step index |
+| `frame` | integer | frame or increment index |
+| `time` | float | step time or total time |
+| `instance` | string | Abaqus instance name or `ASSEMBLY` |
+| `node_label` | integer | Abaqus node label |
+| `quantity` | string | `U` or `UR` |
+| `component` | string | `U1`, `U2`, `U3`, `UR1`, `UR2`, or `UR3` |
+| `coordinate_system` | string | must be `GLOBAL` |
+| `unit` | string | declared length unit for `U`; `radian` for `UR` |
+| `value` | float | extracted numeric value |
+
+Required components:
+
+- `U1`, `U2`, `U3` for all compared output nodes
+- `UR1`, `UR2`, `UR3` when rotational displacement is part of the model comparison
+
+### `extracted/reactions.csv`
+
+Required columns are the same as `nodal_displacements.csv`.
+
+Required components:
+
+- `RF1`, `RF2`, `RF3` for constrained translational DOFs used in equilibrium checks
+- `RM1`, `RM2`, `RM3` for constrained rotational DOFs used in moment equilibrium checks
+
+If Abaqus extraction uses a different raw rotational reaction label, metadata must map the raw name to `RM1`, `RM2`, and `RM3`.
+
+### Optional CSVs
+
+No optional CSV is required for first-scope comparison. The following remain out of scope unless a later gate approves `SVARS` or element output:
+
+- `element_forces.csv`
+- `stresses.csv`
+- `strains.csv`
+- `energy_or_residual.csv`
+
+## Coverage Matrix
+
+| requirement_id | planned_model_or_test | compared_quantity | artifact_or_test_file | tolerance | verification_method | status |
+| --- | --- | --- | --- | --- | --- | --- |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-001 | `NOA-A-AMATRX-001`, `ext-uel-smoke-static` | entry point and UEL-only input subset | `test_abi_static.f90`, `model.inp` | exact contract inspection | no-Abaqus; external artifact review | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-002 | `NOA-K-STIFF-001`, `NOA-K-BEND2-001`, `NOA-K-BEND3-001`, external cantilevers | axial, torsion, bending response | `test_kernel_stiffness.f90`, external CSVs | no-Abaqus rel `1.0e-10`; external per metadata | no-Abaqus; external comparison | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-003 | `NOA-A-AMATRX-001`, `NOA-I-SHAPE-001` | `NDOFEL=12`, two 6-DOF nodes | `test_abi_static.f90`, `test_invalid_inputs.f90` | exact | no-Abaqus | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-004 | `NOA-A-AMATRX-001`, `NOA-K-REVNODE-001` | DOF order and node permutation | `test_abi_static.f90`, `test_kernel_transform_modes.f90` | exact mapping; rel `1.0e-10` | no-Abaqus | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-005 | `NOA-A-PROPS-001`, `NOA-K-STIFF-002`, `NOA-K-STIFF-003`, bending tests | property mapping and stiffness terms | `test_abi_static.f90`, `test_kernel_stiffness.f90` | exact mapping; rel `1.0e-10` | no-Abaqus | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-006 | `NOA-I-PHYS-001` | invalid properties and nonfinite inputs | `test_invalid_inputs.f90` | exact diagnostic | no-Abaqus | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-007 | `NOA-K-ROT-001`, `NOA-I-PHYS-001`, `ext-rotated-cantilever` | orientation transform and invalid orientation | `test_kernel_transform_modes.f90`, `test_invalid_inputs.f90`, external CSVs | rel `1.0e-10`; external per metadata | no-Abaqus; external comparison | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-008 | `NOA-K-STIFF-001`, `NOA-A-AMATRX-001`, all external models | `AMATRX`, stiffness response, reactions | Fortran tests, `reactions.csv` | no-Abaqus rel `1.0e-10`; external reaction rel `1.0e-6` | no-Abaqus; external comparison | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-009 | `NOA-A-RHS-001`, external cantilevers | residual sign, displacement/reaction consistency | `test_abi_static.f90`, external CSVs | no-Abaqus vector rel `1.0e-10`; external displacement abs `1.0e-8` | no-Abaqus; external comparison | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-010 | `NOA-I-LFLAGS-001`, document inspection | unsupported features rejected or absent | `test_invalid_inputs.f90`, source review later | exact diagnostic | no-Abaqus; source review | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-011 | `ext-*` metadata contract | no repository-run Abaqus or ODB parsing | `metadata.json`, log tails, extracted CSVs | exact provenance | artifact review | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-012 | planned manifest RED | no-Abaqus evidence before production source | `tests/fortran/manifest.json` | RED then GREEN evidence | validation-command | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-013 | all external models | artifact bundle completeness | `references/uel-3d-euler-beam/<model-id>/` | schema exact | reference-artifact-validation | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-014 | all external models | CSV identity, units, coordinate system, components | `nodal_displacements.csv`, `reactions.csv` | schema exact | schema-validation | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-015 | all no-Abaqus and external models | explicit tolerances | manifest tests and metadata comparisons | documented tolerances | test-review; validation-review | planned |
+| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-016 | phase gate artifacts | separation of gate outputs | docs and phase index | not applicable | document inspection | planned |
+
+## Artifact Acceptance Checklist
+
+Before any external model is marked `ready-for-comparison`:
+
+- `model.inp` uses only the supported keyword subset.
+- `metadata.json` uses `abaqus-user-subroutine-artifact-v1`.
+- Abaqus version, precision, compiler vendor/name/version, source hashes, units, coordinate system, extraction provenance, and tolerance policy are present.
+- `job.msg.tail.txt`, `job.dat.tail.txt`, `job.log.tail.txt`, and `job.sta.tail.txt` exist and correspond to the same run.
+- Declared CSV files exist under `extracted/`.
+- CSVs include required columns, accepted component labels, declared units, and `GLOBAL` coordinate system.
+- Artifact status remains `needs-reference-artifacts` until the user provides externally generated files.
+- No ODB parsing or Abaqus job execution is required by this repository.
+
+## Open Issues and Downstream Handoff
+
+### I/O Definition Agent
+
+- No blocking interface issue remains for test planning.
+- If future extraction shows Abaqus rotational reaction labels differ from `RM1/RM2/RM3`, update the interface mapping before comparison tooling relies on those labels.
+
+### TDD Test Agent
+
+- Create the planned `tests/fortran/manifest.json` and test driver files exactly as listed.
+- Run `python scripts/validate_fortran.py` after adding tests to capture RED evidence before production source is added.
+- Do not add production Fortran source in step 6 unless that step is explicitly changed to include implementation; current phase reserves implementation for step 7.
+
+### Implementation Planning Agent
+
+- Use the planned source layout and keep `uel_3d_euler_beam_uel.for` as a thin wrapper around a no-Abaqus-testable kernel and ABI adapter.
+- Preserve the `PROPS(1:9)`, `NDOFEL=12`, `NNODE=2`, and `RHS=-K_global*U` contracts.
+
+### Reference Verification Agent
+
+- Treat external artifacts as absent until user-generated bundles are added.
+- Validate artifact metadata and CSV schema before comparing values.
+- Compare only nodal displacement and reaction CSVs for first-scope external evidence.
+
+### Physics Evaluation Agent
+
+- For future external artifacts, check displacement direction, support reaction sign, global equilibrium, moment equilibrium for torsion/bending cases, and rotated-frame plausibility before release readiness.