diff --git a/PROGRESS.md b/PROGRESS.md index 6260827..4803927 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/step4.md` interface-contract step -- Next action: execute `phases/uel-3d-euler-beam/step5.md` test/reference model planning step +- Current status: completed `phases/uel-3d-euler-beam/step5.md` test/reference model planning step +- Next action: execute `phases/uel-3d-euler-beam/step6.md` RED no-Abaqus test creation step ## Completed @@ -28,6 +28,9 @@ - Completed step 4 interface contract for `uel-3d-euler-beam`. - Created `docs/io-definitions/uel-3d-euler-beam.md`. - Updated `phases/uel-3d-euler-beam/index.json` step 4 to `completed`. +- Completed step 5 test/reference model planning for `uel-3d-euler-beam`. + - Created `docs/reference-models/uel-3d-euler-beam.md`. + - Updated `phases/uel-3d-euler-beam/index.json` step 5 to `completed`. ## In Progress @@ -39,7 +42,7 @@ ## Last Verification -Latest verification after completing step 4 interface contract: +Latest verification after completing step 5 test/reference model planning: ```bash python -m unittest discover -s scripts -p "test_*.py" @@ -56,5 +59,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/step5.md`. +- Start `phases/uel-3d-euler-beam/step6.md`. - Update this file when step status changes or before handing off. diff --git a/docs/reference-models/uel-3d-euler-beam.md b/docs/reference-models/uel-3d-euler-beam.md new file mode 100644 index 0000000..c4438bd --- /dev/null +++ b/docs/reference-models/uel-3d-euler-beam.md @@ -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=` 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/ + / + 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": "", + "artifact_status": "needs-reference-artifacts | ready-for-comparison | blocked", + "abaqus": { + "version": "", + "precision": "single | double" + }, + "compiler": { + "vendor": "Intel oneAPI", + "name": "ifx | ifort", + "version": "" + }, + "subroutine": { + "entry_points": ["UEL"], + "source_files": [ + { + "path": "src/fortran/uel_3d_euler_beam_kernel.f90", + "language": "Fortran", + "sha256": "" + }, + { + "path": "src/fortran/uel_3d_euler_beam_abi_adapter.f90", + "language": "Fortran", + "sha256": "" + }, + { + "path": "src/fortran/uel_3d_euler_beam_uel.for", + "language": "Fortran", + "sha256": "" + } + ] + }, + "input_file": "model.inp", + "units": { + "length": "", + "force": "", + "stress": "", + "moment": "", + "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": "", + "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": "", + "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//` | 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. diff --git a/phases/uel-3d-euler-beam/index.json b/phases/uel-3d-euler-beam/index.json index f009d06..b6b87b8 100644 --- a/phases/uel-3d-euler-beam/index.json +++ b/phases/uel-3d-euler-beam/index.json @@ -35,7 +35,8 @@ { "step": 5, "name": "test-models", - "status": "pending" + "status": "completed", + "summary": "Created docs/reference-models/uel-3d-euler-beam.md with planned no-Abaqus Fortran manifest entries, exact test driver/source paths, RED expectations, kernel and ABI mapping test inventory, future external Abaqus reference model portfolio, artifact bundle and metadata contracts, CSV schemas, and coverage matrix." }, { "step": 6,