docs: plan 3d euler beam reference models
This commit is contained in:
김경종
+7
-4
@@ -5,8 +5,8 @@
|
|||||||
- Active objective: 3D Euler-Bernoulli beam Abaqus/Standard `UEL`
|
- Active objective: 3D Euler-Bernoulli beam Abaqus/Standard `UEL`
|
||||||
- Active phase: `phases/uel-3d-euler-beam`
|
- Active phase: `phases/uel-3d-euler-beam`
|
||||||
- Active owner: unassigned
|
- Active owner: unassigned
|
||||||
- Current status: completed `phases/uel-3d-euler-beam/step4.md` interface-contract step
|
- Current status: completed `phases/uel-3d-euler-beam/step5.md` test/reference model planning step
|
||||||
- Next action: execute `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
|
## Completed
|
||||||
|
|
||||||
@@ -28,6 +28,9 @@
|
|||||||
- Completed step 4 interface contract for `uel-3d-euler-beam`.
|
- Completed step 4 interface contract for `uel-3d-euler-beam`.
|
||||||
- Created `docs/io-definitions/uel-3d-euler-beam.md`.
|
- Created `docs/io-definitions/uel-3d-euler-beam.md`.
|
||||||
- Updated `phases/uel-3d-euler-beam/index.json` step 4 to `completed`.
|
- 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
|
## In Progress
|
||||||
|
|
||||||
@@ -39,7 +42,7 @@
|
|||||||
|
|
||||||
## Last Verification
|
## Last Verification
|
||||||
|
|
||||||
Latest verification after completing step 4 interface contract:
|
Latest verification after completing step 5 test/reference model planning:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python -m unittest discover -s scripts -p "test_*.py"
|
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`.
|
- Read `AGENTS.md`, `PLAN.md`, `PROGRESS.md`, and `WORKNOTE.md`.
|
||||||
- Confirm no other owner is active in this file.
|
- 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.
|
- Update this file when step status changes or before handing off.
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -35,7 +35,8 @@
|
|||||||
{
|
{
|
||||||
"step": 5,
|
"step": 5,
|
||||||
"name": "test-models",
|
"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,
|
"step": 6,
|
||||||
|
|||||||
Reference in New Issue
Block a user