docs: refresh Abaqus subroutine guidance

2026-08-18 11:27:22 +09:00
parent a3197dc2e3
commit e76c1b96fd
64 changed files with 498 additions and 4560 deletions
@@ -20,11 +20,18 @@ This document maps the project agents and skills to the Abaqus User Subroutine d
 | --- | --- | --- |
 | 1. Subroutine requirements analysis | Requirement Agent, Coordinator Agent | `abaqus-subroutine-requirements` |
 | 2. Books, papers, and research evidence | Research Agent | `abaqus-subroutine-research`, `fem-theory-query` |
-| 3. Finite element formulation for implementation | Formulation Agent, Numerical Review Agent | `abaqus-subroutine-formulation`, `abaqus-subroutine-numerical-review` |
-| 4. Subroutine input/output parameter definition | I/O Definition Agent | `abaqus-subroutine-interface` |
-| 5. TDD test model design | Reference Model Agent, Implementation Planning Agent | `abaqus-subroutine-test-models` |
+| 3. Finite element formulation for implementation | Formulation Agent, Numerical Review Agent | `abaqus-subroutine-formulation`, `abaqus-subroutine-numerical-review`, `fem-theory-query` |
+| 4. Subroutine input/output parameter definition | I/O Definition Agent | `abaqus-subroutine-interface`, `fem-theory-query` |
+| 5. TDD test model design | Reference Model Agent, Implementation Planning Agent | `abaqus-subroutine-test-models`, `fem-theory-query` |
 | 6. Fortran code implementation | Implementation Planning Agent, Implementation Agent, Correction Agent | `abaqus-fortran-tdd` |
-| 7. Subroutine validation | Build/Test Executor Agent, Reference Verification Agent, Physics Evaluation Agent, Release Agent | `abaqus-subroutine-validation`, `abaqus-subroutine-physics-sanity`, `abaqus-subroutine-readiness` |
+| 7. Subroutine validation | Build/Test Executor Agent, Reference Verification Agent, Physics Evaluation Agent, Release Agent | `abaqus-subroutine-validation`, `abaqus-subroutine-physics-sanity`, `abaqus-subroutine-readiness`, `fem-theory-query` |
+
+## Source Selection Contract
+
+- Use `fem-theory-query` for finite element theory, formulation, solver behavior, benchmark selection, and numerical or physics interpretation.
+- For Abaqus User Subroutine ABI and manual facts, read `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`, locate the full record in `INDEX.md`, and then read every listed `source_ranges` span in order.
+- Treat `INDEX.md` summaries as retrieval metadata, not authoritative implementation evidence.
+- Treat user-provided ODB-extracted CSV and provenance artifacts as solver-result inputs; agents do not run Abaqus or parse ODB files in this project.

 ## Gates

@@ -41,4 +48,4 @@ This document maps the project agents and skills to the Abaqus User Subroutine d
 - Default no-Abaqus path: `python scripts/validate_fortran.py`.
 - Reference artifact contract check: `python scripts/validate_reference_artifacts.py`.
 - Workspace gate: `python scripts/validate_workspace.py`.
- Abaqus execution: only through `HARNESS_ABAQUS_VALIDATION=run` with explicit validation commands.
+- Abaqus execution: performed by the user on another Abaqus PC; agents in this project consume the resulting CSV and provenance artifacts.
@@ -67,3 +67,10 @@ Abaqus User Subroutine 개발은 일반 application code 개발보다 ABI, solve
 **이유**: Public example은 bug-free 또는 validation-quality artifact라는 보장이 없다. 이 프로젝트의 acceptance는 requirements, reference artifact metadata, comparison evidence, physics sanity를 통해 판단한다.

 **트레이드오프**: 공개 예제를 빠르게 복사해 시작하는 방식보다 느리다. 대신 장기적으로 source provenance와 verification traceability를 유지할 수 있다.
+
+### ADR-010: FEM 이론과 Abaqus manual 사실의 탐색 경로를 분리한다
+**결정**: 유한요소 정식화, residual/tangent, constitutive integration, benchmark, 수치 검증 지식은 `fem-theory-query`를 통해 탐색한다. Abaqus User Subroutine ABI, argument, product applicability, utility routine은 `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`에서 위치를 찾고, `INDEX.md`의 해당 record와 모든 `source_ranges` 원문을 순서대로 읽어 확인한다.
+
+**이유**: FEM 이론 자료와 Abaqus 제품별 ABI 문서는 서로 다른 근거 체계다. 둘을 한 경로로 취급하면 이론적 일반성과 특정 Abaqus version의 interface 사실이 혼동될 수 있다. Generated index summary만 읽는 방식도 원문 제약이나 다중 파일 section을 놓칠 수 있다.
+
+**트레이드오프**: Agent가 질문을 분류하고 둘 이상의 source path를 읽어야 하므로 조사 단계가 늘어난다. 대신 theory claim, Abaqus-specific claim, inference의 provenance가 분명해진다.
@@ -9,6 +9,8 @@
 - 기본 검증은 Abaqus를 실행하지 않는다.
 - Abaqus 해석 실행과 ODB CSV 추출은 사용자가 외부 Abaqus PC에서 수행한다.
 - 이 프로젝트는 ODB를 직접 파싱하지 않고, 추출된 CSV와 metadata를 검증한다.
+- FEM 이론과 solver 지식은 `fem-theory-query`를 통해 탐색한다.
+- Abaqus User Subroutine manual 사실은 local index로 section을 찾은 뒤 원문 source span에서 확인한다.
 - Requirements, research, formulation, interface, test model, implementation, validation 산출물을 섞지 않는다.

 ## 디렉토리 구조
@@ -18,6 +20,7 @@
 ├── hooks/              # Codex hook scripts
 └── skills/             # Abaqus workflow, review, TDD, validation instructions
 docs/
+├── AbaqusUserSubroutineManual/ # INDEX_MAP, INDEX, and authoritative manual chunks
 ├── requirements/       # Feature requirement specs and verification matrices
 ├── research/           # Source-backed research briefs
 ├── formulations/       # FEM formulation specs
@@ -69,6 +72,22 @@ User request
 - Skill instructions는 `.codex/skills/*/SKILL.md`에 있고, 각 skill은 input, workflow, output contract, quality gate, handoff를 정의한다.
 - Coordinator Agent는 workflow state와 blocker routing만 담당하고 specialist work를 직접 수행하지 않는다.

+## 근거 탐색 구조
+
+```text
+FEM theory or numerical verification question
+-> fem-theory-query
+-> configured FEM wiki evidence
+
+Abaqus User Subroutine ABI or manual question
+-> docs/AbaqusUserSubroutineManual/INDEX_MAP.md
+-> matching record in INDEX.md
+-> every source_ranges span in order
+-> authoritative manual evidence
+```
+
+`INDEX.md`의 summary, keyword, content anchor는 검색을 위한 metadata다. Agent는 이 metadata만으로 ABI, argument, product support, update responsibility를 확정하지 않는다.
+
 ## Fortran TDD 구조
 ```text
 Fortran production change
@@ -84,6 +103,7 @@ Fortran production change
 `scripts/validate_fortran.py`는 `tests/fortran/manifest.json`이 있을 때 Intel oneAPI Fortran compiler를 찾아 test executable을 compile/run한다. Compiler discovery는 `ifx`를 우선하고 `ifort`를 fallback으로 사용한다.

 ## Abaqus ABI 설계
+- Selected entry point의 manual 근거는 `INDEX_MAP.md`와 `INDEX.md`를 거쳐 모든 source span을 읽은 뒤 interface contract에 기록한다.
 - Abaqus ABI wrapper는 manual signature와 include convention을 보존한다.
 - Abaqus/Standard Fortran wrapper는 `aba_param.inc` convention을 따른다.
 - Abaqus/Explicit Fortran wrapper는 `vaba_param.inc` convention을 따른다.
@@ -0,0 +1,119 @@
+# INDEX.md Map
+
+`INDEX.md` Section heading 위치(1-based line).
+
+1.1.1 — CREEP — line 39
+1.1.2 — DFLOW — line 94
+1.1.3 — DFLUX — line 145
+1.1.4 — DISP — line 193
+1.1.5 — DLOAD — line 244
+1.1.6 — FILM — line 292
+1.1.7 — FLOW — line 343
+1.1.8 — FRIC — line 394
+1.1.9 — FRIC_COEF — line 443
+1.1.10 — GAPCON — line 492
+1.1.11 — GAPELECTR — line 543
+1.1.12 — HARDINI — line 591
+1.1.13 — HETVAL — line 633
+1.1.14 — MPC — line 686
+1.1.15 — ORIENT — line 739
+1.1.16 — RSURFU — line 781
+1.1.17 — SDVINI — line 828
+1.1.18 — SIGINI — line 869
+1.1.19 — UAMP — line 920
+1.1.20 — UANISOHYPER_INV — line 966
+1.1.21 — UANISOHYPER_STRAIN — line 1017
+1.1.22 — UCORR — line 1074
+1.1.23 — UCREEPNETWORK — line 1115
+1.1.24 — UDECURRENT — line 1166
+1.1.25 — UDEMPOTENTIAL — line 1220
+1.1.26 — UDMGINI — line 1271
+1.1.27 — UDSECURRENT — line 1325
+1.1.28 — UEL — line 1376
+1.1.29 — UELMAT — line 1431
+1.1.30 — UEXPAN — line 1488
+1.1.31 — UEXTERNALDB — line 1536
+1.1.32 — UFIELD — line 1584
+1.1.33 — UFLUID — line 1626
+1.1.34 — UFLUIDCONNECTORLOSS — line 1679
+1.1.35 — UFLUIDCONNECTORVALVE — line 1730
+1.1.36 — UFLUIDLEAKOFF — line 1781
+1.1.37 — UFLUIDPIPEFRICTION — line 1826
+1.1.38 — UGENS — line 1877
+1.1.39 — UHARD — line 1929
+1.1.40 — UHYPEL — line 1980
+1.1.41 — UHYPER — line 2019
+1.1.42 — UINTER — line 2063
+1.1.43 — UMASFL — line 2116
+1.1.44 — UMAT — line 2167
+1.1.45 — UMATHT — line 2218
+1.1.46 — UMESHMOTION — line 2272
+1.1.47 — UMOTION — line 2323
+1.1.48 — UMULLINS — line 2374
+1.1.49 — UPOREP — line 2425
+1.1.50 — UPRESS — line 2474
+1.1.51 — UPSD — line 2524
+1.1.52 — URDFIL — line 2574
+1.1.53 — USDFLD — line 2619
+1.1.54 — UTEMP — line 2675
+1.1.55 — UTRACLOAD — line 2719
+1.1.56 — UTRS — line 2764
+1.1.57 — UTRSNETWORK — line 2815
+1.1.58 — UVARM — line 2872
+1.1.59 — UWAVE — line 2920
+1.1.60 — UXFEMNONLOCALWEIGHT — line 2964
+1.1.61 — VOIDRI — line 3015
+1.2.1 — VDFLUX — line 3063
+1.2.2 — VDISP — line 3114
+1.2.3 — VDLOAD — line 3165
+1.2.4 — VEXTERNALDB — line 3213
+1.2.5 — VFABRIC — line 3261
+1.2.6 — VFRIC — line 3315
+1.2.7 — VFRIC_COEF — line 3361
+1.2.8 — VFRICTION — line 3410
+1.2.9 — VUAMP — line 3456
+1.2.10 — VUANISOHYPER_INV — line 3505
+1.2.11 — VUANISOHYPER_STRAIN — line 3562
+1.2.12 — VUCHARLENGTH — line 3622
+1.2.13 — VUCREEPNETWORK — line 3666
+1.2.14 — VUEL — line 3714
+1.2.15 — VUEOS — line 3766
+1.2.16 — VUFIELD — line 3815
+1.2.17 — VUFLUIDEXCH — line 3860
+1.2.18 — VUFLUIDEXCHEFFAREA — line 3911
+1.2.19 — VUHARD — line 3960
+1.2.20 — VUINTER — line 4008
+1.2.21 — VUINTERACTION — line 4056
+1.2.22 — VUMAT — line 4109
+1.2.23 — VUMULLINS — line 4162
+1.2.24 — VUSDFLD — line 4210
+1.2.25 — VUTRS — line 4260
+1.2.26 — VUVISCOSITY — line 4311
+1.2.27 — VWAVE — line 4364
+1.3.1 — SMACfdUserPressureBC — line 4417
+1.3.2 — SMACfdUserVelocityBC — line 4466
+2.1.1 — OBTAINING Abaqus ENVIRONMENT VARIABLES — line 4521
+2.1.2 — OBTAINING THE Abaqus JOB NAME — line 4570
+2.1.3 — OBTAINING THE Abaqus OUTPUT DIRECTORY NAME — line 4616
+2.1.4 — OBTAINING PARALLEL PROCESSES INFORMATION — line 4663
+2.1.5 — OBTAINING PART INFORMATION — line 4738
+2.1.6 — OBTAINING MATERIAL POINT INFORMATION IN AN Abaqus/Standard ANALYSIS — line 4796
+2.1.7 — OBTAINING MATERIAL POINT INFORMATION IN AN Abaqus/Explicit ANALYSIS — line 4853
+2.1.8 — OBTAINING MATERIAL POINT INFORMATION AVERAGED AT A NODE — line 4907
+2.1.9 — OBTAINING NODE POINT INFORMATION — line 4964
+2.1.10 — OBTAINING NODE TO ELEMENT CONNECTIVITY — line 5013
+2.1.11 — OBTAINING STRESS INVARIANTS, PRINCIPAL STRESS/STRAIN VALUES AND DIRECTIONS, AND ROTATING TENSORS IN AN Abaqus/Standard ANALYSIS — line 5063
+2.1.12 — OBTAINING PRINCIPAL STRESS/STRAIN VALUES AND DIRECTIONS IN AN Abaqus/Explicit ANALYSIS — line 5129
+2.1.13 — OBTAINING WAVE KINEMATIC DATA IN AN Abaqus/Aqua ANALYSIS — line 5183
+2.1.14 — PRINTING MESSAGES TO THE MESSAGE OR STATUS FILE — line 5240
+2.1.15 — TERMINATING AN ANALYSIS — line 5288
+2.1.16 — OBTAINING SENSOR INFORMATION — line 5330
+2.1.17 — ACCESSING Abaqus MATERIALS — line 5379
+2.1.18 — ACCESSING Abaqus THERMAL MATERIALS — line 5427
+2.1.19 — OBTAINING SCALAR STATE INFORMATION IN AN Abaqus/CFD ANALYSIS — line 5475
+2.1.20 — OBTAINING VECTOR STATE INFORMATION IN AN Abaqus/CFD ANALYSIS — line 5526
+2.1.21 — OBTAINING THE MPI COMMUNICATOR IN AN Abaqus/CFD ANALYSIS — line 5577
+2.1.22 — ENSURING THREAD SAFETY — line 5627
+2.1.23 — ALLOCATABLE ARRAYS — line 5671
+A.1 — User subroutines index — line 5805
+A.2 — User subroutine functions listing — line 5839
@@ -20,7 +20,7 @@

 ## 핵심 워크플로우
 1. Requirement Agent가 feature requirement와 Requirement Verification Matrix를 작성한다.
-2. Research Agent가 Abaqus manual, 책, 논문, benchmark source를 조사하고 verified facts와 inference를 분리한다.
+2. Research Agent가 FEM 이론은 `fem-theory-query`로 조사하고, Abaqus User Subroutine 사실은 로컬 manual index에서 원문 span을 찾아 verified facts와 inference를 분리한다.
 3. Formulation Agent가 finite element formulation, stress update, tangent, state variable, numerical integration을 정의한다.
 4. Numerical Review Agent가 formulation consistency, tangent consistency, stability risk, patch/tangent check 필요성을 검토한다.
 5. I/O Definition Agent가 Abaqus ABI arguments, input/output direction, tensor component order, unit, CSV schema를 정의한다.
@@ -37,6 +37,7 @@
 6. `references/<feature-id>/<model-id>/metadata.json` 기반 reference artifact metadata validation
 7. `model.inp`, extracted CSV, `.msg/.dat/.log/.sta` tail files를 포함한 외부 생성 result artifact validation
 8. Optional CMake/CTest validation path for supporting native code when a CMake project exists
+9. `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`와 `INDEX.md`를 통한 local manual source routing

 ## 대표 Subroutine 범위
 - Primary initial families: `UMAT`, `VUMAT`, `UEL`
@@ -46,6 +47,7 @@
 ## 성공 기준
 - 모든 must requirement가 verification method, acceptance criteria, tolerance 또는 decision owner를 가진다.
 - Research evidence는 source reliability tier와 applicability limit를 가진다.
+- FEM 이론 claim은 `fem-theory-query` evidence에, Abaqus ABI 및 argument claim은 local manual source span에 추적 가능하다.
 - Formulation은 selected entry point가 요구하는 stress update, tangent, residual, state variable, output recovery를 명시한다.
 - Interface contract는 Abaqus ABI argument direction, update responsibility, tensor order, unit, coordinate system, CSV schema를 명시한다.
 - Fortran implementation은 RED -> GREEN -> VERIFY evidence를 남긴다.
@@ -64,5 +66,6 @@

 ## 운영 제약
 - 문서 산출물은 Korean narrative를 기본으로 하되, Abaqus keyword, subroutine name, status value, command, schema key는 English를 유지한다.
+- FEM 관련 지식은 `fem-theory-query`로 탐색한다. Abaqus User Subroutine manual 사실은 `INDEX_MAP.md`에서 위치를 찾고 `INDEX.md` record와 모든 `source_ranges` 원문을 읽어 확인한다.
 - Abaqus version, compiler version, precision, source hash, output tail, CSV schema, ODB extraction provenance는 reference artifact metadata에 기록한다.
 - Abaqus execution은 user가 외부 Abaqus PC에서 수행한다. 이 프로젝트의 validation command는 해석 실행이 아니라 extracted CSV artifact 검증을 수행한다.
@@ -1,151 +0,0 @@
-# Abaqus UEL Subroutines Research Brief
-
-## Metadata
- feature_id: abaqus-uel-subroutines
- related_feature: `uel-3d-euler-beam`
- status: implemented-follow-up
- owner_agent: research-agent
- date: 2026-06-12
-
-## Follow-up Status
-
-The findings below captured the pre-correction state after the initial step 7 implementation. The follow-up correction in `docs/corrections/uel-3d-euler-beam-uel-abi-correction.md` adds the missing Abaqus-callable wrapper, changes the Abaqus-facing state-variable policy to `NSVARS>=1` / `VARIABLES=1`, and adds `LFLAGS(1)` and `LFLAGS(4)` validation.
-
-## Research Questions
- Abaqus/Standard가 실제로 호출하는 `UEL` subroutine의 positional ABI는 무엇인가?
- `RHS`, `AMATRX`, `SVARS`, `ENERGY`, `PNEWDT`, `LFLAGS`의 update 책임은 무엇인가?
- `*USER ELEMENT`와 `*UEL PROPERTY`가 `NDOFEL`, `NNODE`, `MCRD`, `NPROPS`, `NJPROP`, `NSVARS`에 미치는 영향은 무엇인가?
- 공개 GitHub UEL 예제는 Abaqus-facing wrapper와 testable implementation logic을 어떻게 분리하는가?
- 현재 `uel-3d-euler-beam` Fortran 구현이 Abaqus UEL 포맷과 맞지 않는 지점은 무엇인가?
-
-## Source Inventory
-
-| id | source_type | title | author_or_org | URL | access_date | reliability_tier | notes |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| S1 | vendor manual mirror | Abaqus 2016 User Subroutines Reference Guide, user-provided entry URL | Dassault Systemes SIMULIA, mirrored by University of Colorado | https://ceae-server.colorado.edu/v2016/books/sub/default.htm?startat=ch01s01asb44.html | 2026-06-12 | Tier 1 version-specific mirror | The `default.htm?startat=...` frame URL returned a browser fallback in this environment. The `startat=ch01s01asb44.html` target is `UMAT`, not `UEL`. |
-| S2 | vendor manual mirror | Abaqus 2016 User Subroutines Reference Guide, `UEL` section 1.1.28 | Dassault Systemes SIMULIA, mirrored by University of Colorado | https://ceae-server.colorado.edu/v2016/books/sub/ch01s01asb28.html | 2026-06-12 | Tier 1 version-specific mirror | Direct 2016 UEL page. Used as the user-requested manual family. |
-| S3 | vendor manual mirror | Abaqus 2025 User Subroutines Reference Guide, `UEL` | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAESUBRefMap/simasub-c-uel.htm | 2026-06-12 | Tier 1 accessible manual mirror | Used for accessible line-level confirmation of the UEL interface, variables, and `LFLAGS`. Recheck against the target licensed Abaqus installation before release. |
-| S4 | vendor keyword manual mirror | Abaqus 2025 Keywords Reference, `*USER ELEMENT` | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-userelement.htm | 2026-06-12 | Tier 1 accessible manual mirror | Defines user element type declaration, active DOF data lines, properties, coordinates, `VARIABLES`, and `UNSYMM`. |
-| S5 | vendor keyword manual mirror | Abaqus 2025 Keywords Reference, `*UEL PROPERTY` | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-uelproperty.htm | 2026-06-12 | Tier 1 accessible manual mirror | Defines UEL property assignment by `ELSET`, property data order, and optional `ORIENTATION`. |
-| S6 | vendor analysis manual mirror | Abaqus 2025 Analysis User's Guide, User-Defined Elements | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-c-userelem.htm | 2026-06-12 | Tier 1 accessible manual mirror | Defines user element invocation, active DOF ordering, and the global-coordinate responsibility of user element matrices. |
-| S7 | public example repository | `bibekanandadatta/Abaqus-UEL-Elasticity` | Bibekananda Datta | https://github.com/bibekanandadatta/Abaqus-UEL-Elasticity | 2026-06-12 | Tier 3 example repository | Useful implementation-pattern evidence only. The repository is not acceptance evidence for this project. |
-| S8 | public example source | `src/uel_mech.for` | Bibekananda Datta | https://github.com/bibekanandadatta/Abaqus-UEL-Elasticity/blob/main/src/uel_mech.for | 2026-06-12 | Tier 3 example source | Shows a top-level Abaqus `UEL` wrapper outside modules, with calculation delegated to modular subroutines. |
-| S9 | public example license | `LICENSE.md` | Bibekananda Datta | https://github.com/bibekanandadatta/Abaqus-UEL-Elasticity/blob/main/LICENSE.md | 2026-06-12 | Tier 3 license metadata | Source code is under BSD-3-Clause; documentation is CC BY-NC-SA 4.0. Do not copy code without preserving license obligations. |
-
-## Extracted Facts
-
-| fact_id | source | fact | relevance |
-| --- | --- | --- | --- |
-| F-UEL-001 | S2, S3 | Abaqus/Standard calls an external entry point named `UEL` for each general user-defined element when element calculations are needed. | A module-only helper subroutine is not enough; the linked user source must export the expected `UEL` entry point. |
-| F-UEL-002 | S2, S3 | The manual UEL ABI is positional. The argument order is `RHS`, `AMATRX`, `SVARS`, `ENERGY`, element counts, real properties, coordinates, nodal solution arrays, element/procedure metadata, load arrays, predefined fields, `LFLAGS`, dimensions, `PNEWDT`, integer properties, and `PERIOD`. | The wrapper must not add extra arguments such as `status`, and it must not omit manual arguments such as `DU`, `V`, `A`, `JTYPE`, `TIME`, `PARAMS`, load arrays, `PREDEF`, `MDLOAD`, or `PERIOD`. |
-| F-UEL-003 | S2, S3 | The wrapper convention includes `ABA_PARAM.INC` and manual dimensions such as `RHS(MLVARX,*)`, `AMATRX(NDOFEL,NDOFEL)`, `COORDS(MCRD,NNODE)`, `U(NDOFEL)`, `DU(MLVARX,*)`, and `PREDEF(2,NPREDF,NNODE)`. | The Abaqus-facing layer should use explicit Abaqus dimensions. Assumed-shape arrays are suitable for no-Abaqus module tests only when an explicit interface exists. |
-| F-UEL-004 | S2, S3 | `RHS` is the element contribution to the right-hand-side vectors. In the common single-RHS nonlinear/static path it represents residual force, described as external minus internal force. | For a linear static element with no internally generated external load, the expected element residual contribution remains `-K_global * U` under the existing contract. |
-| F-UEL-005 | S2, S3 | `AMATRX` is the element Jacobian, stiffness, damping, mass, or other matrix requested by `LFLAGS`. Nonzero terms should be defined even for symmetric matrices. | The beam UEL should fill the full requested 12-by-12 stiffness matrix. `UNSYMM` is unnecessary for the current symmetric linear scope. |
-| F-UEL-006 | S2, S3 | `SVARS` are element solution-dependent state variables. `ENERGY` has eight element energy slots. `PNEWDT` can suggest automatic time increment changes. | A first-scope linear beam may ignore these physically, but the Abaqus ABI still passes them and the wrapper must handle their allocated sizes safely. |
-| F-UEL-007 | S2, S3 | `LFLAGS` controls procedure and requested contribution. Relevant values include small vs large displacement in `LFLAGS(2)` and residual/Jacobian, stiffness-only, damping-only, mass-only, residual-only, initial-acceleration, and perturbation-output requests in `LFLAGS(3)`. | The wrapper must branch on `LFLAGS` rather than always assuming one static request. |
-| F-UEL-008 | S3 | Static analysis requires `AMATRX`, `RHS`, and state variable update where applicable. The static procedure values are documented under `LFLAGS(1)=1,2`. | The first beam wrapper should at least verify static procedure scope, small displacement, and general-step behavior before filling outputs. |
-| F-UEL-009 | S3, S6 | UEL solution variables are arranged node-major: all active DOFs for node 1, then all active DOFs for node 2, etc. | The current 12-DOF beam ordering is aligned if the input deck declares active DOFs `1,2,3,4,5,6` once for both nodes. |
-| F-UEL-010 | S6 | Abaqus passes user element quantities in the global system; user element stiffness and related matrices should be provided with respect to global nodal directions. | Local beam stiffness must be transformed to global coordinates before assigning `AMATRX` or deriving `RHS`. |
-| F-UEL-011 | S4 | A general user element declaration uses `*USER ELEMENT` with `TYPE=Un`, `NODES`, optional `COORDINATES`, `PROPERTIES`, `I PROPERTIES`, `UNSYMM`, and `VARIABLES`, followed by active DOF data lines. | The input deck is part of the ABI. The subroutine alone cannot define `NDOFEL`, `NNODE`, `NPROPS`, or active DOFs. |
-| F-UEL-012 | S4 | For a general user element, `VARIABLES` declares the number of solution-dependent state variables and must be greater than zero; the default is one. | The existing contract `NSVARS=0` / `VARIABLES=0` is not consistent with this keyword rule. Use at least one state variable or verify a target-version exception before Abaqus-facing implementation. |
-| F-UEL-013 | S5 | `*UEL PROPERTY` requires `ELSET`; when data lines are used, real property values precede integer property values. | A beam property list such as `E, G, A, Iy, Iz, J, a_ref_1, a_ref_2, a_ref_3` is a valid real-property strategy when `PROPERTIES=9` and `I PROPERTIES=0`. |
-| F-UEL-014 | S5 | `*UEL PROPERTY` has an `ORIENTATION` parameter in Abaqus/Standard. The plain `UEL` argument list does not include an orientation matrix argument. | Do not rely on `ORIENTATION` being directly visible inside plain `UEL` unless an Abaqus run proves the intended behavior. Passing orientation through `PROPS` remains the safer first-scope contract. |
-| F-UEL-015 | S7, S8 | The example repository describes `uel_mech.for` as the source implementing the UEL, while the main Abaqus `UEL` wrapper performs checks and delegates calculations to another subroutine. | This supports the project architecture: external `UEL` wrapper plus testable kernel/adapter logic. |
-| F-UEL-016 | S8 | The example source keeps modules and helper subroutines in the same Fortran source path, then defines a top-level `SUBROUTINE UEL` outside those modules, includes `ABA_PARAM.INC`, dimensions all Abaqus arrays, initializes outputs, checks `LFLAGS`, and calls an internal element routine. | The pattern is compatible with Abaqus symbol lookup while preserving modular calculation logic. |
-| F-UEL-017 | S9 | The example code license permits source redistribution under BSD-3-Clause conditions, while documentation is under CC BY-NC-SA 4.0. | The example can inform design, but this project should not copy source text without license handling. |
-
-## Minimum Abaqus-Facing UEL Contract
-
-The Abaqus-facing production source must expose a top-level external subroutine named `UEL` with the manual positional ABI. Local argument names can vary, but the order and shape cannot. For the current 3D beam scope the wrapper should preserve these groups:
-
-| group | required UEL arguments |
-| --- | --- |
-| element outputs | `RHS`, `AMATRX`, `SVARS`, `ENERGY`, `PNEWDT` |
-| element sizes | `NDOFEL`, `NRHS`, `NSVARS`, `NPROPS`, `MCRD`, `NNODE`, `MLVARX`, `MDLOAD`, `NJPROP` |
-| input arrays | `PROPS`, `COORDS`, `U`, `DU`, `V`, `A`, `TIME`, `PARAMS`, `JDLTYP`, `ADLMAG`, `DDLMAG`, `PREDEF`, `LFLAGS`, `JPROPS` |
-| scalar metadata | `JTYPE`, `DTIME`, `KSTEP`, `KINC`, `JELEM`, `NDLOAD`, `NPREDF`, `PERIOD` |
-
-The wrapper should include `ABA_PARAM.INC` and use manual-style dimensions for all Abaqus arrays. A no-Abaqus adapter can keep assumed-shape arrays and a `status` output, but that adapter is not itself an Abaqus-callable UEL.
-
-## Minimum Input Deck Contract for the Current Beam
-
-For the first-scope two-node 3D Euler-Bernoulli beam, the research-supported `.inp` shape is:
-
-| keyword | required policy |
-| --- | --- |
-| `*USER ELEMENT` | use `TYPE=Un`, `NODES=2`, `COORDINATES=3`, `PROPERTIES=9`, and no `UNSYMM` for the symmetric linear scope |
-| active DOF data line | declare `1,2,3,4,5,6` so `NDOFEL=12` for two nodes |
-| `VARIABLES` | use at least `VARIABLES=1` or omit it and accept the default one state variable; do not assume Abaqus accepts zero without target-version evidence |
-| `I PROPERTIES` | omit or set to zero for the first scope |
-| `*ELEMENT` | use the same `TYPE=Un`; node order defines the positive beam axis from node 1 to node 2 |
-| `*UEL PROPERTY` | provide `ELSET` and nine real properties in project-defined order |
-
-The current project interface document should be corrected before an external Abaqus run if it still says `VARIABLES=0` or requires `NSVARS=0`.
-
-## Pattern Observed in `uel_mech.for`
-
-The GitHub example is useful as a layout pattern, not as a source to copy. The relevant pattern is:
-
- helper modules are available before the Abaqus entry point is compiled;
- the actual Abaqus entry is a top-level external `UEL`, not a module procedure;
- the wrapper includes `ABA_PARAM.INC` and manual array dimensions;
- wrapper code initializes Abaqus output arrays before calculation;
- wrapper code checks procedure flags and element type metadata;
- wrapper code delegates the element formulation to a lower-level routine with any extra internal arguments it wants.
-
-This is the missing layer in the current beam implementation. Our project already has a testable kernel and a no-Abaqus adapter, but it still needs the external `UEL` wrapper that Abaqus will actually call.
-
-## Findings Against Current `uel-3d-euler-beam` Implementation
-
-| finding_id | severity | evidence | impact | recommended follow-up |
-| --- | --- | --- | --- | --- |
-| C-UEL-001 | high | `rg` found no `SUBROUTINE UEL` in `src/fortran`; only `uel3deb_abi_static` is public in `src/fortran/uel_3d_euler_beam_abi_adapter.f90`. | Abaqus will not call the current implementation as a UEL unless another wrapper is provided at compile/link time. | Add `src/fortran/uel_3d_euler_beam_uel.for` or equivalent top-level `UEL` wrapper that calls the existing adapter/kernel. |
-| C-UEL-002 | high | `uel3deb_abi_static` adds a `status` output and omits many manual UEL arguments. | The adapter is valid for no-Abaqus tests but is not the Abaqus ABI. | Keep it as test adapter; do not present it as production UEL wrapper. |
-| C-UEL-003 | high | `uel3deb_abi_static` uses assumed-shape arrays such as `rhs(:, :)`, `amatrx(:, :)`, and `props(:)`. | Abaqus calls external user subroutines without an explicit Fortran module interface; assumed-shape dummy arguments are the wrong boundary for the top-level ABI. | The top-level wrapper should use manual explicit dimensions and pass slices to a module helper. |
-| C-UEL-004 | high | Current interface and adapter require `NSVARS=0`; Abaqus `*USER ELEMENT` documentation says `VARIABLES` must be greater than zero and defaults to one. | An Abaqus input deck using `VARIABLES=0` may be rejected before the subroutine runs, or a valid deck may pass `NSVARS=1` and be rejected by the adapter. | Revise the Abaqus-facing contract to accept at least `NSVARS>=1` while ignoring `SVARS(1)` unless diagnostics are later approved. |
-| C-UEL-005 | medium | Current adapter checks `LFLAGS(2)` and `LFLAGS(3)` but not `LFLAGS(1)` or `LFLAGS(4)`. | Non-static or linear perturbation calls could be mishandled by an Abaqus-facing wrapper if forwarded directly. | Wrapper should reject unsupported procedure/general-step states before kernel execution. |
-| C-UEL-006 | medium | Current contract excludes `NDLOAD` and ignores load arrays, which is acceptable for first scope, but the top-level ABI must still receive `JDLTYP`, `ADLMAG`, `DDLMAG`, and `MDLOAD`. | Omitting these arguments breaks the manual ABI even if distributed loads are unsupported. | Preserve all manual load arguments and then enforce `NDLOAD=0` for first scope. |
-
-## Inferences and Design Guidance
-
-| inference_id | basis | inference | downstream owner |
-| --- | --- | --- | --- |
-| I-UEL-001 | F-UEL-001 through F-UEL-003, C-UEL-001 | The next implementation correction should add a real Abaqus wrapper, not replace the tested kernel. | Implementation Agent |
-| I-UEL-002 | F-UEL-012, C-UEL-004 | `NSVARS=0` is a no-Abaqus convenience that conflicts with documented Abaqus keyword constraints. | I/O Definition Agent |
-| I-UEL-003 | F-UEL-010 | The existing kernel's local-to-global matrix transformation remains directionally correct for Abaqus; the problem is the call boundary, not the beam matrix concept. | Formulation Agent |
-| I-UEL-004 | F-UEL-014 | Passing the orientation reference through `PROPS(7:9)` remains an acceptable first-scope strategy. | I/O Definition Agent |
-| I-UEL-005 | F-UEL-016 | A robust wrapper can be fixed-form `.for` for Abaqus compatibility, while calculation modules may remain `.f90` if the Abaqus compile path is made explicit. | Implementation Planning Agent |
-
-## Corrected Handoff for the 3D Beam UEL
-
-### I/O Definition Agent
- Replace `VARIABLES=0` / `NSVARS=0` with an Abaqus-compatible state-variable allocation policy, likely `VARIABLES=1` with unused `SVARS(1)` for first scope.
- Keep `PROPERTIES=9` and `I PROPERTIES=0` unless a later orientation or diagnostic mode requires integer properties.
- Define exact behavior for `LFLAGS(1)` static procedure values and `LFLAGS(4)` general-step requirement.
-
-### Implementation Agent
- Add a top-level external `SUBROUTINE UEL(...)` wrapper with the manual argument order and `ABA_PARAM.INC` include.
- Use manual explicit dimensions at the wrapper boundary.
- Call the existing no-Abaqus adapter or a small wrapper helper after mapping Abaqus arrays to the tested kernel inputs.
- Do not add Abaqus-specific logic into the matrix kernel unless tests require it.
-
-### Test Model Agent
- Add a source-smoke test that scans the production wrapper for `SUBROUTINE UEL`, `ABA_PARAM.INC`, the manual argument groups, and manual array dimensions.
- Update no-Abaqus ABI tests to cover the chosen `NSVARS` policy.
- Keep external Abaqus execution outside this repository; validation still depends on user-generated CSV and log-tail artifacts.
-
-### Numerical Review Agent
- Re-review residual sign only after the actual wrapper maps Abaqus `U` and `RHS` arrays.
- Confirm that accepting `NSVARS>=1` while leaving state values unchanged has no physical side effect for the linear static beam.
-
-## Applicability Limits
- This research did not run Abaqus and did not compile the public GitHub example.
- The accessible 2025 documentation mirror was used for line-level confirmation; final release should be checked against the user's installed Abaqus version and licensed documentation.
- The public GitHub example is Tier 3 evidence. It informs wrapper structure but does not validate this project's beam formulation.
- This document intentionally does not change production Fortran source. It identifies the next correction needed before Abaqus execution evidence can be meaningful.
-
-## Open Issues
- Target Abaqus version for external validation remains unspecified.
- Exact wrapper file extension and Abaqus compile path for mixed `.for` wrapper plus `.f90` modules must be decided before implementation.
- The current no-Abaqus tests assume `NSVARS=0`; they need revision if the production Abaqus wrapper requires `NSVARS>=1`.
- Whether `SVARS(1)` should be left unchanged, zeroed, or used as a diagnostic status slot requires an interface decision.
@@ -1,68 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL GREEN Test Report
-
-## Metadata
- feature_id: uel-3d-euler-beam
- source_red_report: `docs/build-test-reports/uel-3d-euler-beam-red.md`
- source_reference_models: `docs/reference-models/uel-3d-euler-beam.md`
- status: pass-for-workspace-validation
- owner_agent: implementation-agent
- date: 2026-06-11
-
-## Implementation Scope
-
-Post-step ABI correction note: the original step 7 implementation deliberately deferred the fixed-form Abaqus `UEL` wrapper. The follow-up correction report `docs/corrections/uel-3d-euler-beam-uel-abi-correction.md` supersedes that deferred-wrapper status and records the added wrapper, `NSVARS>=1` policy, and `LFLAGS(1)/(4)` checks.
-
-Production source added in this step:
-
- `src/fortran/uel_3d_euler_beam_kernel.f90`
- `src/fortran/uel_3d_euler_beam_abi_adapter.f90`
-
-The implementation covers the approved no-Abaqus scope:
-
- 12-by-12 Euler-Bernoulli local stiffness matrix.
- Local frame construction from node coordinates and `PROPS(7:9)`.
- `K_global = T^T*k_local*T`.
- Static residual `RHS(1:12,1) = -K_global*U(1:12)`.
- `AMATRX` and `RHS` selection for `LFLAGS(3)=1`, `2`, and `5`.
- Shape, property, geometry, orientation, and unsupported-request diagnostics.
- Deterministic zeroing of `RHS`, `AMATRX`, and `ENERGY`; `PNEWDT` unchanged for valid calls.
-
-The fixed-form Abaqus `UEL` wrapper remains deferred because the approved step 7 no-Abaqus tests target the kernel and ABI adapter only.
-
-## Harness Support Changes
-
-Two validation harness fixes were required after the step 6 RED manifest became executable:
-
- `scripts/validate_fortran.py` now creates each `build/fortran-tests/<test-name>/` directory before invoking Intel Fortran.
- `scripts/fortran_toolchain.py` now invokes the oneAPI environment script through `ComSpec` or discovered `cmd.exe` and sets a minimal Windows PATH for the child command shell.
-
-These changes are covered by updated Python harness tests in:
-
- `scripts/test_validate_fortran.py`
- `scripts/test_fortran_toolchain.py`
-
-## Command Log Summary
-
-| order | command | exit_code | result | evidence |
-| --- | --- | --- | --- | --- |
-| 1 | `python scripts/test_validate_fortran.py -k build_commands_create` | 1 then 0 | RED then GREEN | failed before build-dir creation fix; passed after `build_dir.mkdir(...)` |
-| 2 | `python scripts/test_fortran_toolchain.py -k wrap_command` | 1 then 0 | RED then GREEN | failed before absolute `cmd.exe` and minimal PATH wrapper; passed after wrapper update |
-| 3 | `python -m unittest discover -s scripts -p "test_*.py"` | 0 | pass | 57 Python harness tests passed |
-| 4 | `python scripts/validate_reference_artifacts.py` | 0 | pass | reference artifact metadata validation succeeded |
-| 5 | `python scripts/validate_fortran.py` | 0 | pass | all six no-Abaqus Fortran manifest executables compiled and passed with Intel `ifx` through oneAPI env script |
-| 6 | `python scripts/validate_workspace.py` | 0 | pass | reference validation and Fortran validation both succeeded |
-
-## No-Abaqus Fortran Tests Passed
-
-| manifest_test | result |
-| --- | --- |
-| `uel_3d_euler_beam_kernel_stiffness` | pass |
-| `uel_3d_euler_beam_kernel_transform_modes` | pass |
-| `uel_3d_euler_beam_abi_static` | pass |
-| `uel_3d_euler_beam_invalid_inputs` | pass |
-| `uel_3d_euler_beam_kernel_source_smoke` | pass |
-| `uel_3d_euler_beam_abi_adapter_source_smoke` | pass |
-
-## Handoff to Step 8
-
-Step 8 can proceed to validation readiness using the passing no-Abaqus evidence above. External Abaqus reference artifacts remain absent and must still be user-generated before solver-result comparison.
@@ -1,67 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL RED Test Report
-
-## Metadata
- feature_id: uel-3d-euler-beam
- source_reference_models: `docs/reference-models/uel-3d-euler-beam.md`
- status: red-evidence-recorded
- owner_agent: implementation-agent
- date: 2026-06-11
-
-## Scope
-
-This report records the step 6 RED evidence after adding no-Abaqus Fortran tests and `tests/fortran/manifest.json`.
-
-Production Fortran source was not added in this step. The expected RED condition is a compile failure from missing planned production source:
-
- `src/fortran/uel_3d_euler_beam_kernel.f90`
- `src/fortran/uel_3d_euler_beam_abi_adapter.f90`
-
-## Test Files Added Before Production Code
-
-| manifest_test | source file |
-| --- | --- |
-| `uel_3d_euler_beam_kernel_stiffness` | `tests/fortran/uel_3d_euler_beam/test_kernel_stiffness.f90` |
-| `uel_3d_euler_beam_kernel_transform_modes` | `tests/fortran/uel_3d_euler_beam/test_kernel_transform_modes.f90` |
-| `uel_3d_euler_beam_abi_static` | `tests/fortran/uel_3d_euler_beam/test_abi_static.f90` |
-| `uel_3d_euler_beam_invalid_inputs` | `tests/fortran/uel_3d_euler_beam/test_invalid_inputs.f90` |
-| shared support | `tests/fortran/uel_3d_euler_beam/test_support.f90` |
-
-## Command Log Summary
-
-| order | command | exit_code | result | evidence |
-| --- | --- | --- | --- | --- |
-| 1 | `python -m json.tool tests/fortran/manifest.json` | 0 | pass | manifest JSON parsed successfully |
-| 2 | `python -m unittest discover -s scripts -p "test_*.py"` | 0 | pass | 56 Python harness tests passed |
-| 3 | `python scripts/validate_reference_artifacts.py` | 0 | pass | reference artifact metadata validation succeeded |
-| 4 | `python scripts/validate_fortran.py` | 1 | environment failure before RED | current `cmd.exe` child process sees empty `%PATH%`; nested `cmd` command is not found |
-| 5 | `$env:PATH='C:\Windows\System32;C:\Windows;C:\Users\user\miniforge3'; C:\Users\user\miniforge3\python.exe scripts/validate_fortran.py` | 1 | expected RED | `ifx` reached compile and failed because `src/fortran/uel_3d_euler_beam_kernel.f90` does not exist |
-| 6 | `python scripts/validate_workspace.py` | 1 | environment failure before RED | reference validation passed, then Fortran validation hit the same nested `cmd` lookup issue |
-| 7 | `$env:PATH='C:\Windows\System32;C:\Windows;C:\Users\user\miniforge3'; C:\Users\user\miniforge3\python.exe scripts/validate_workspace.py` | 1 | expected RED | reference validation passed, then Fortran validation failed on missing production kernel source |
-| 8 | `$env:HARNESS_FORTRAN_VALIDATION='detect'; python scripts/validate_workspace.py` | 0 | pass | reference validation passed; Fortran manifest/compiler detection mode produced no compile commands |
-
-## RED Failure Classification
-
- classification: `fortran-compile`
- first implementation-owned failure after environment normalization: missing planned production source
- primary evidence tail:
-
-```text
-xfortcom: Severe: No such file or directory
-... file is 'C:\git\AbaqusSubroutineDev\src\fortran\uel_3d_euler_beam_kernel.f90'
-compilation aborted for C:\git\AbaqusSubroutineDev\src\fortran\uel_3d_euler_beam_kernel.f90 (code 1)
-```
-
-The subsequent module import errors in `test_kernel_stiffness.f90` are secondary to the missing kernel module source.
-
-## Environment Note
-
-This Codex process can find `cmd.exe` from PowerShell and Python, but a child `cmd.exe` invoked during `validate_fortran.py` sees an empty `%PATH%` unless a minimal `PATH` is set explicitly. The normalized command above confirms that Intel oneAPI `ifx` is available through the configured oneAPI env script and that the actionable RED failure is the missing production source, not a missing compiler.
-
-## Handoff to Step 7
-
-Implement the minimum production Fortran needed to turn the four manifest tests GREEN:
-
- `src/fortran/uel_3d_euler_beam_kernel.f90`
- `src/fortran/uel_3d_euler_beam_abi_adapter.f90`
-
-The Abaqus fixed-form `UEL` wrapper remains planned for the implementation gate but is not required to satisfy these no-Abaqus RED tests unless the step 7 plan explicitly includes it.
@@ -1,78 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL ABI Correction Report
-
-## Metadata
- feature_id: uel-3d-euler-beam
- source_failure_report: `docs/abaqus-uel-subroutines-research.md`
- source_implementation_report: `docs/build-test-reports/uel-3d-euler-beam-green.md`
- source_implementation_plan: N/A; correction follows the post-review research findings
- status: corrected-for-build-test
- owner_agent: correction-agent
- date: 2026-06-12
-
-## Failure Triage
- classification: upstream-contract plus implementation defect
- first_failed_command: `python -m unittest scripts.test_uel_3d_euler_beam_uel`; `python scripts/validate_fortran.py`
- failed_target_or_test: missing Abaqus `UEL` wrapper; adapter rejected `NSVARS=1`
- evidence_tail: wrapper source-smoke failed because `src/fortran/uel_3d_euler_beam_uel.for` was missing; Fortran ABI test failed with `actual=6 expected=0` for a valid `NSVARS=1` static call
- triage_decision: implementation-owned correction allowed after research clarified the Abaqus manual ABI
-
-## Root Cause Summary
- root_cause_type: implementation boundary defect and stale interface policy
- summary: the step 7 code implemented a testable kernel and no-Abaqus adapter, but did not expose the top-level Abaqus `SUBROUTINE UEL(...)`. The adapter also kept the pre-research `NSVARS=0` policy, conflicting with the documented `*USER ELEMENT, VARIABLES` requirement for a positive allocation.
- why_minimal_fix_is_allowed: the correction preserves the existing kernel formulation and only fixes the Abaqus-facing call boundary, state-variable allocation check, and static-procedure `LFLAGS` validation.
-
-## Correction Scope
-
-| file | change_type | reason | in_scope |
-| --- | --- | --- | --- |
-| `src/fortran/uel_3d_euler_beam_uel.for` | source | add fixed-form Abaqus `UEL` wrapper with manual signature, `ABA_PARAM.INC`, manual dimensions, adapter call, and fatal `XIT` path | true |
-| `src/fortran/uel_3d_euler_beam_abi_adapter.f90` | source | accept `NSVARS>=1`, use explicit/manual-style array bounds, and validate `LFLAGS(1)` / `LFLAGS(4)` | true |
-| `src/fortran/uel_3d_euler_beam_kernel.f90` | source | add status ids for unsupported `LFLAGS(1)` and `LFLAGS(4)` | true |
-| `scripts/test_uel_3d_euler_beam_uel.py` | test | verify wrapper signature, include, dimensions, adapter call, and fatal path without requiring Abaqus include files | true |
-| `tests/test_uel_3d_euler_beam_uel.py` | test | expose a related test path for the production-source TDD guard | true |
-| `tests/fortran/uel_3d_euler_beam/test_abi_static.f90` | test | update valid adapter calls to `NSVARS=1` and explicit static `LFLAGS` values | true |
-| `tests/fortran/uel_3d_euler_beam/test_invalid_inputs.f90` | test | add `NSVARS<1`, `LFLAGS(1)`, and `LFLAGS(4)` diagnostics | true |
-| `tests/fortran/test_uel_3d_euler_beam_abi_adapter.f90` | test | update source-smoke adapter call to the corrected policy | true |
-| `docs/io-definitions/uel-3d-euler-beam.md` | documentation | align current interface contract with the implemented Abaqus-facing policy | true |
-| `docs/reference-models/uel-3d-euler-beam.md` | documentation | align test model and input-deck requirements with `VARIABLES=1` and wrapper source-smoke | true |
-
-Excluded files:
- reference artifacts: unchanged
- tolerances: unchanged
- formulation matrix/residual equations: unchanged
-
-## Verification Evidence
-
-| order | command | exit_code | result | evidence |
-| --- | --- | --- | --- | --- |
-| 1 | `python -m unittest scripts.test_uel_3d_euler_beam_uel` before implementation | 1 | RED | failed because `src/fortran/uel_3d_euler_beam_uel.for` did not exist |
-| 2 | `python scripts/validate_fortran.py` before implementation | 1 | RED | `uel_3d_euler_beam_abi_static` failed because `NSVARS=1` returned `UEL3DEB_E006_NSVARS` |
-| 3 | `python -m unittest scripts.test_uel_3d_euler_beam_uel` after implementation | 0 | pass | wrapper source-smoke passed |
-| 4 | `python scripts/validate_fortran.py` after implementation | 0 | pass | all six no-Abaqus Fortran manifest executables compiled and passed with Intel `ifx` |
-| 5 | `python -m unittest discover -s scripts -p "test_*.py"` | 0 | pass | 60 Python harness/source-smoke tests passed |
-| 6 | `python scripts/validate_workspace.py` | 0 | pass | reference artifact metadata validation and Fortran validation succeeded |
-| 7 | `git diff --check` | 0 | pass | no whitespace errors; line-ending warnings only |
-
-## Traceability
-
-| requirement_or_finding | corrected_file | acceptance_criterion |
-| --- | --- | --- |
-| C-UEL-001 / C-UEL-002 | `src/fortran/uel_3d_euler_beam_uel.for` | top-level external `SUBROUTINE UEL(...)` exists with manual ABI arguments |
-| C-UEL-003 | `src/fortran/uel_3d_euler_beam_uel.for`, `src/fortran/uel_3d_euler_beam_abi_adapter.f90` | Abaqus-facing boundary uses manual dimensions; adapter remains testable |
-| C-UEL-004 | `src/fortran/uel_3d_euler_beam_abi_adapter.f90`, `docs/io-definitions/uel-3d-euler-beam.md` | valid static adapter calls use `NSVARS=1`; `NSVARS<1` returns `UEL3DEB_E006_NSVARS` |
-| C-UEL-005 | `src/fortran/uel_3d_euler_beam_abi_adapter.f90` | unsupported `LFLAGS(1)` and `LFLAGS(4)` return dedicated diagnostics |
-
-## Handoff Recommendation
-
-| target_agent | reason | required_input |
-| --- | --- | --- |
-| Build/Test Executor Agent | run full workspace validation after correction | this report and command evidence |
-| Reference Verification Agent | update external model expectations to `VARIABLES=1` before user-generated Abaqus artifacts are prepared | corrected I/O and reference-model documents |
-| Physics Evaluation Agent | no formulation behavior changed; external CSV physics checks remain pending | future user-provided reference bundles |
-
-## Stop Condition
- repeated_failure: false
- upstream_ambiguity: false
- reference_artifact_gap: true
- environment_blocker: false
- next_required_decision: user must still provide external Abaqus artifacts before solver-result validation can complete
@@ -1,513 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL Formulation
-
-## 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`
- status: ready-for-numerical-review
- owner_agent: formulation-agent
- date: 2026-06-11
-
-## Scope and Assumptions
-
- analysis_type: linear static small-displacement
- Abaqus entry point: `UEL`
- element_type: two-node 3D Euler-Bernoulli beam/frame element
- topology: node 1 to node 2 defines the positive local 1 axis
- deformation: small displacement and small rotation only
- material_model_boundary: linear elastic section stiffness with axial, Saint-Venant torsion, and two principal bending stiffnesses
- coordinate_system: Abaqus global nodal coordinates for `AMATRX` and `RHS`; element local coordinates only for intermediate beam calculations
- units: user-consistent units; no unit conversion inside the element
- loads: no distributed, body, thermal, follower, or element-generated loads in first scope
- dynamics: no mass, damping, inertia, modal, or transient contribution in first scope
-
-This document defines the mathematical element contract. It does not define the final Abaqus ABI signature, `PROPS` ordering, `JPROPS` ordering, source file layout, or Fortran implementation plan.
-
-## Primary Variables and DOFs
-
-The element has two nodes and 12 active DOFs. Global and local element vectors use the same component ordering; the difference is only the coordinate basis.
-
-```text
-q = [
-  u1, v1, w1, th1_1, th2_1, th3_1,
-  u2, v2, w2, th1_2, th2_2, th3_2
-]^T
-```
-
-Where:
-
- `u` is translation along local 1.
- `v` is translation along local 2.
- `w` is translation along local 3.
- `th1` is rotation about local 1.
- `th2` is rotation about local 2.
- `th3` is rotation about local 3.
-
-The Abaqus-facing DOF order remains node 1 `U1, U2, U3, UR1, UR2, UR3`, followed by node 2 `U1, U2, U3, UR1, UR2, UR3`. In the local vector above, each translational or rotational component is the projection of the corresponding Abaqus global vector onto the local frame.
-
-Euler-Bernoulli bending imposes the section-normal constraints:
-
-```text
-th3 =  dv/dx
-th2 = -dw/dx
-```
-
-The sign difference follows the right-handed local 1-2-3 basis: a positive rotation about local 3 changes the centerline tangent in the local 2 direction, while a positive rotation about local 2 changes it in the negative local 3 direction.
-
-## Required Material and Section Parameters
-
-The first-scope formulation requires finite, strictly positive:
-
-| parameter | meaning | stiffness role |
-| --- | --- | --- |
-| `E` | Young's modulus | bending and axial stiffness |
-| `G` | shear modulus for Saint-Venant torsion | torsional stiffness |
-| `A` | cross-sectional area | axial stiffness `E*A/L` |
-| `Iy` | second moment of area about local 2 | bending response in local 1-3 plane, coupled `w` and `th2` DOFs |
-| `Iz` | second moment of area about local 3 | bending response in local 1-2 plane, coupled `v` and `th3` DOFs |
-| `J` | Saint-Venant torsion constant | torsional stiffness `G*J/L` |
-
-The I/O Definition Agent owns the final property source and ordering. This formulation requires only that the implementation receives these six physical quantities with the meanings above.
-
-## Strong Form and Boundary Conditions
-
-Let `x` be the coordinate along the undeformed beam centerline, `0 <= x <= L`.
-
-For constant prismatic section properties and no element-generated distributed loads, the internal generalized resultants are:
-
-```text
-N  = E*A  * du/dx
-T  = G*J  * dth1/dx
-M2 = E*Iy * dth2/dx
-M3 = E*Iz * dth3/dx
-```
-
-The first-scope homogeneous field equilibrium is:
-
-```text
-dN/dx    = 0
-dT/dx    = 0
-d2M2/dx2 = 0 in the work-conjugate Euler-Bernoulli bending statement for w/th2
-d2M3/dx2 = 0 in the work-conjugate Euler-Bernoulli bending statement for v/th3
-```
-
-Essential boundary conditions are prescribed nodal translations and rotations. Natural boundary terms are nodal axial force, shear forces, torsional moment, and bending moments. Applied nodal forces and moments are supplied by Abaqus outside the first-scope `UEL`.
-
-## Weak or Variational Form
-
-The element internal virtual work is:
-
-```text
-delta W_int =
-  integral_0^L [
-    delta eps  * E*A  * eps
-  + delta kap1 * G*J  * kap1
-  + delta kap2 * E*Iy * kap2
-  + delta kap3 * E*Iz * kap3
-  ] dx
-```
-
-with generalized strains:
-
-```text
-eps  = du/dx
-kap1 = dth1/dx
-kap2 = dth2/dx = -d2w/dx2
-kap3 = dth3/dx =  d2v/dx2
-```
-
-The first-scope element does not generate external virtual work internally:
-
-```text
-delta W_ext_element = 0
-```
-
-Therefore the element internal force is derived entirely from `delta W_int`, and solver-applied nodal loads remain outside this formulation.
-
-## Discretization and Kinematics
-
-Use `xi = x/L`, where `0 <= xi <= 1`.
-
-Linear axial and torsional interpolation:
-
-```text
-N1 = 1 - xi
-N2 = xi
-
-u(x)   = N1*u1     + N2*u2
-th1(x) = N1*th1_1  + N2*th1_2
-```
-
-Cubic Hermite interpolation for bending about local 3, using `th3 = dv/dx`:
-
-```text
-H1 = 1 - 3*xi^2 + 2*xi^3
-H2 = L*(xi - 2*xi^2 + xi^3)
-H3 = 3*xi^2 - 2*xi^3
-H4 = L*(-xi^2 + xi^3)
-
-v(x) = H1*v1 + H2*th3_1 + H3*v2 + H4*th3_2
-```
-
-Cubic Hermite interpolation for bending about local 2, using `th2 = -dw/dx`:
-
-```text
-w(x) = H1*w1 - H2*th2_1 + H3*w2 - H4*th2_2
-```
-
-Expected shape-function checks:
-
- Axial and torsion interpolation: `N1 + N2 = 1`.
- Hermite displacement interpolation: `H1(0)=1`, `H3(1)=1`, and the opposite endpoint displacement shape values are zero.
- Hermite slope interpolation recovers `dv/dx = th3` and `dw/dx = -th2` at the corresponding nodes.
-
-## Local Element Stiffness Matrix
-
-Define:
-
-```text
-L  = element length
-EA = E*A
-GJ = G*J
-B2 = E*Iy
-B3 = E*Iz
-
-a  = EA/L
-t  = GJ/L
-b2_12 = 12*B2/L^3
-b2_6  =  6*B2/L^2
-b2_4  =  4*B2/L
-b2_2  =  2*B2/L
-b3_12 = 12*B3/L^3
-b3_6  =  6*B3/L^2
-b3_4  =  4*B3/L
-b3_2  =  2*B3/L
-```
-
-In the local DOF order
-
-```text
-[u1, v1, w1, th1_1, th2_1, th3_1, u2, v2, w2, th1_2, th2_2, th3_2]
-```
-
-the local stiffness matrix is:
-
-```text
-k_local =
-[
- [ a,      0,      0,   0,      0,      0, -a,      0,      0,   0,      0,      0],
- [ 0,  b3_12,      0,   0,      0,  b3_6,  0, -b3_12,      0,   0,      0,  b3_6],
- [ 0,      0,  b2_12,   0, -b2_6,      0,  0,      0, -b2_12,  0, -b2_6,      0],
- [ 0,      0,      0,   t,      0,      0,  0,      0,      0,  -t,      0,      0],
- [ 0,      0, -b2_6,   0,  b2_4,      0,  0,      0,  b2_6,   0,  b2_2,      0],
- [ 0,  b3_6,      0,   0,      0,  b3_4,  0, -b3_6,      0,   0,      0,  b3_2],
- [-a,      0,      0,   0,      0,      0,  a,      0,      0,   0,      0,      0],
- [ 0, -b3_12,     0,   0,      0, -b3_6,  0,  b3_12,      0,   0,      0, -b3_6],
- [ 0,      0, -b2_12,  0,  b2_6,      0,  0,      0,  b2_12,  0,  b2_6,      0],
- [ 0,      0,      0,  -t,      0,      0,  0,      0,      0,   t,      0,      0],
- [ 0,      0, -b2_6,   0,  b2_2,      0,  0,      0,  b2_6,   0,  b2_4,      0],
- [ 0,  b3_6,      0,   0,      0,  b3_2,  0, -b3_6,      0,   0,      0,  b3_4]
-]
-```
-
-Subblock interpretation:
-
- Axial `u1/u2` block: `EA/L * [[1, -1], [-1, 1]]`.
- Torsion `th1_1/th1_2` block: `GJ/L * [[1, -1], [-1, 1]]`.
- Bending about local 2 uses `E*Iy` and couples `w` with `th2`.
- Bending about local 3 uses `E*Iz` and couples `v` with `th3`.
-
-For a valid free element, `k_local` is symmetric positive semidefinite with six rigid-body modes and six deformational modes.
-
-## Local Frame and Transformation to Global Coordinates
-
-Let the original global nodal coordinates be `X1` and `X2`.
-
-```text
-x21 = X2 - X1
-L   = norm(x21)
-e1  = x21 / L
-```
-
-Let `a_ref` be the formulation-level orientation reference vector expressed in global coordinates. The I/O Definition Agent will decide whether `a_ref` comes from properties, an additional point, or another approved Abaqus-facing source. The reference must not be parallel to `e1`.
-
-Project the reference onto the plane normal to the beam axis:
-
-```text
-a_perp = a_ref - dot(a_ref, e1)*e1
-e2     = a_perp / norm(a_perp)
-e3     = cross(e1, e2)
-```
-
-This gives a right-handed frame:
-
-```text
-cross(e1, e2) = e3
-det(R)        = +1
-```
-
-Define the 3-by-3 direction-cosine matrix `R` with local axes as rows:
-
-```text
-R = [
-  e1^T
-  e2^T
-  e3^T
-]
-```
-
-For any global vector `g`, the local vector is:
-
-```text
-l = R*g
-```
-
-The 12-by-12 element transformation is block diagonal:
-
-```text
-T = blockdiag(R, R, R, R)
-```
-
-using the block order: node 1 translations, node 1 rotations, node 2 translations, node 2 rotations.
-
-The local and global element vectors are related by:
-
-```text
-q_local = T*q_global
-```
-
-Virtual work gives:
-
-```text
-f_internal_local  = k_local*q_local
-f_internal_global = T^T*f_internal_local
-K_global          = T^T*k_local*T
-```
-
-`AMATRX` must receive `K_global`, not `k_local`.
-
-## Element Equations and Residual Convention
-
-The first-scope element has no element-generated external load vector:
-
-```text
-p_element = 0
-```
-
-Internal force:
-
-```text
-f_int = K_global*q_global
-```
-
-Using the Abaqus research fact that the static residual is external minus internal, the formulation-level residual contribution is:
-
-```text
-r_element = p_element - f_int = -K_global*q_global
-```
-
-Therefore the first-scope `RHS` mathematical contribution is:
-
-```text
-RHS = -K_global*U
-```
-
-The I/O Definition Agent must confirm the exact Abaqus fill convention and no-Abaqus sign test before implementation. If the interface contract later chooses a different array-fill convention, it must preserve the same physical internal force `f_int = K_global*U` and document the sign mapping explicitly.
-
-## `AMATRX` and `RHS` Contribution Rules by Supported `LFLAGS`
-
-This formulation supports only small-displacement static requests. Exact procedure-code ownership remains with the I/O Definition Agent, but the contribution rules are:
-
-| request condition | formulation contribution |
-| --- | --- |
-| small-displacement static and `LFLAGS(3)=1` | provide `AMATRX = K_global` and `RHS = -K_global*U` |
-| small-displacement static and `LFLAGS(3)=2` | provide `AMATRX = K_global`; no residual contribution is mathematically requested |
-| small-displacement static and `LFLAGS(3)=5` | provide `RHS = -K_global*U`; no stiffness contribution is mathematically requested |
-| large-displacement request | out of scope; interface must reject or report unsupported behavior |
-| mass, damping, perturbation-only, dynamics, or other non-static requests | out of scope; interface must reject or return a documented zero contribution with diagnostics |
-
-The element stiffness is symmetric. `UNSYMM` is not required by this formulation unless the interface contract introduces a non-symmetric behavior in a later approved scope.
-
-## Numerical Tolerances and Validity Checks
-
-The first implementation should use double precision. These formulation tolerances are defaults for no-Abaqus tests and numerical review; the Numerical Review Agent may tighten them with scale-aware justification.
-
-| check | default rule |
-| --- | --- |
-| coordinate finiteness | reject if any coordinate used by the element is NaN or infinite |
-| length scale | `coord_scale = max(1.0, norm(X1), norm(X2))` |
-| zero or near-zero length | reject if `L <= 1.0e-12*coord_scale` |
-| orientation vector finiteness | reject if any `a_ref` component is NaN or infinite |
-| zero orientation vector | reject if `norm(a_ref) <= 1.0e-12` when `a_ref` is supplied as a direction; if supplied as a point offset, apply the length scale rule |
-| near-parallel orientation | reject if `norm(a_perp)/norm(a_ref) <= 1.0e-8` |
-| local frame orthonormality | require `maxabs(R*R^T - I) <= 1.0e-12` after construction |
-| right-handed frame | require `det(R) > 0` and preferably `abs(det(R) - 1) <= 1.0e-12` |
-| physical properties | reject if `E`, `G`, `A`, `Iy`, `Iz`, or `J` is NaN, infinite, zero, or negative |
-| matrix finiteness | reject or report invalid if any `K_global` or residual component is NaN or infinite |
-| matrix symmetry | require `maxabs(K_global - K_global^T) <= 1.0e-12*max(1.0, maxabs(K_global))` |
-
-No positive lower bound is imposed on physical properties beyond `> 0` because units and model scale are user-controlled. Conditioning risks from very small positive values must be caught by no-Abaqus tests and numerical review.
-
-## State Variables, Energy, and Output Recovery
-
-### State Variables
-
-No persistent material or history state is required for the first-scope linear elastic beam. `SVARS` is not used by the formulation.
-
-Optional diagnostic storage of local end forces or section quantities in `SVARS` is not approved by this formulation. It requires an explicit interface contract and reference extraction plan.
-
-### Energy
-
-The elastic strain energy associated with the formulation is:
-
-```text
-Ue = 0.5*q_global^T*K_global*q_global
-   = 0.5*q_local^T*k_local*q_local
-```
-
-Populating Abaqus `ENERGY` is not required in the first scope. If a later interface contract requires energy output, it should use this expression for elastic strain energy and define the exact `ENERGY` slot.
-
-### Output Recovery
-
-Quantities available from the formulation:
-
-```text
-q_local          = T*q_global
-f_local          = k_local*q_local
-f_internal_global = K_global*q_global
-r_element        = -f_internal_global
-Ue               = 0.5*q_global^T*K_global*q_global
-```
-
-Local element end-force component order follows the local DOF order:
-
-```text
-[N1, V2_1, V3_1, T1, M2_1, M3_1, N2, V2_2, V3_2, T2, M2_2, M3_2]
-```
-
-Initial external Abaqus CSV validation should compare:
-
- nodal displacements `U` in global coordinates at selected nodes
- support reactions `RF` in global coordinates at selected constrained nodes
- coordinate-system labels and declared units for every compared CSV value
-
-External element force or section-force CSV comparison is deferred until the interface defines an approved output route, such as diagnostic `SVARS`.
-
-Stress and strain recovery is not part of the first scope.
-
-## Mapping and Numerical Integration
-
-The element is a straight two-node member, so the centerline mapping is:
-
-```text
-X(xi) = (1 - xi)*X1 + xi*X2
-dX/dx = e1
-dx/dxi = L
-```
-
-The stiffness matrix is evaluated analytically from the closed-form axial, torsion, and Hermite bending expressions. No Gauss integration loop is required for the first implementation.
-
-If a later implementation chooses numerical integration internally, it must reproduce the analytical matrix above within the no-Abaqus stiffness tolerances. Reduced integration is not needed and must not be introduced as an hourglass-prone substitute for the closed-form matrix.
-
-## Algorithm Pseudocode
-
-```text
-input:
-  X1, X2
-  orientation reference a_ref
-  E, G, A, Iy, Iz, J
-  global element displacement vector U
-  supported static request flag
-
-validate:
-  finite coordinates and properties
-  positive E, G, A, Iy, Iz, J
-  valid length L
-  valid nonparallel orientation reference
-
-construct local frame:
-  e1 = (X2 - X1)/L
-  e2 = normalized projection of a_ref normal to e1
-  e3 = cross(e1, e2)
-  R  = rows(e1, e2, e3)
-  T  = blockdiag(R, R, R, R)
-
-assemble local stiffness:
-  compute EA/L, GJ/L, E*Iy/L terms, E*Iz/L terms
-  fill symmetric 12 by 12 k_local in the documented local DOF order
-
-transform:
-  K_global = transpose(T) * k_local * T
-
-compute requested contributions:
-  if stiffness requested:
-    AMATRX = K_global
-  if residual requested:
-    RHS = -K_global * U
-
-optional recovery for tests:
-  q_local = T * U
-  f_local = k_local * q_local
-  strain_energy = 0.5 * transpose(U) * K_global * U
-```
-
-## Numerical Risks
-
-| risk | expected check or mitigation |
-| --- | --- |
-| rigid_body_modes | free-element `K_global` must have six rigid-body modes; no-Abaqus tests should check near-zero residual for rigid translations and rotations |
-| matrix symmetry | `K_global` must satisfy the symmetry tolerance; asymmetry indicates transform, fill, or indexing error |
-| positive definiteness | unconstrained element is positive semidefinite; constrained benchmark models should be positive definite after essential BCs remove rigid modes |
-| local axis singularity | zero length and near-parallel orientation references must be rejected before normalization |
-| axis/property swap | separate `Iy` and `Iz` bending tests are required to catch local 2/local 3 mapping mistakes |
-| residual sign error | no-Abaqus test must verify `RHS = -K_global*U` under the approved interface convention |
-| conditioning | very short elements, very long elements, or extreme property ratios can produce ill-conditioned matrices; numerical review should define scale-aware diagnostics |
-| shear locking | not applicable to the element stiffness because Euler-Bernoulli shear deformation is not represented; applicability to deep beams remains out of scope |
-| hourglass | not applicable because the first formulation uses a closed-form stiffness matrix rather than reduced integration |
-| volumetric locking | not applicable |
-| section offset and warping | out of scope; tests must not expect these effects |
-
-## Verification-Relevant Invariants
-
-No-Abaqus verification should be able to check:
-
- identity-orientation `K_global = k_local`
- rotated-orientation `K_global = T^T*k_local*T`
- `maxabs(K_global - K_global^T)` within tolerance
- six free-element rigid-body modes
- axial response proportional to `E*A/L`
- torsional response proportional to `G*J/L`
- local 2 bending response proportional to `E*Iy`
- local 3 bending response proportional to `E*Iz`
- residual consistency with `RHS = -K_global*U`
-
-External Abaqus comparison should initially check nodal displacement and support reaction CSVs only, with explicit units and coordinate-system labels.
-
-## Open Issues and Downstream Handoff
-
-### Numerical Review Agent
-
- Review the local stiffness signs for `th2 = -dw/dx` and `th3 = dv/dx`.
- Review rigid-body mode checks, matrix rank expectations, and symmetry tolerance.
- Review whether `1.0e-8` near-parallel orientation rejection is appropriate for double-precision production use.
- Review conditioning risks for extreme `L`, `Iy/Iz`, `J`, and property-ratio values.
-
-### I/O Definition Agent
-
- Define the exact Abaqus-facing source and order for `E`, `G`, `A`, `Iy`, `Iz`, `J`, and `a_ref`.
- Define whether invalid inputs are reported by `PNEWDT`, message output, hard stop, or another approved Abaqus-compatible mechanism.
- Confirm the exact `RHS` fill convention and static `LFLAGS` behavior before implementation.
- Decide whether `ENERGY` remains unused or receives elastic strain energy in a later approved scope.
- Keep `SVARS` unused unless a diagnostic output contract is explicitly approved.
-
-### Reference Model Agent
-
- Include no-Abaqus tests for axial, torsion, local 2 bending, local 3 bending, transformation, rigid-body modes, matrix symmetry, invalid orientation, invalid length, invalid properties, and residual sign.
- Keep external Abaqus evidence as user-generated `model.inp`, ODB-extracted nodal `U`/`RF` CSV files, log tails, and metadata under `references/uel-3d-euler-beam/<model-id>/`.
- Do not require element force CSV comparison until an output recovery path is approved.
-
-### Implementation Planning Agent
-
- Implement only after no-Abaqus RED evidence exists.
- Keep the Abaqus `UEL` wrapper thin and isolate the beam matrix, transform, validation, and residual calculations in testable routines if the approved interface permits it.
- Preserve the local DOF order and transformation convention exactly as documented here unless Numerical Review and I/O Definition update this formulation.
@@ -1,382 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL I/O Definition
-
-## 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`
- status: ready-for-reference-model-planning
- owner_agent: io-definition-agent
- date: 2026-06-11
-
-## Scope and Compatibility Statement
-
- input_format: Abaqus input file (`.inp`) plus Abaqus/Standard `UEL` call data
- entry_point: Abaqus/Standard `UEL`
- compatibility: only the keyword, argument, and CSV subset defined here is supported
- solver_execution_policy: Abaqus jobs are run outside this repository by the user
- result_policy: this repository validates externally generated ODB-extracted CSV artifacts and does not parse ODB files
-
-This interface contract deliberately avoids claiming full Abaqus input compatibility. It defines the first-scope two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam `UEL` only.
-
-## Abaqus/Standard UEL ABI Contract
-
-The Abaqus/Standard production wrapper must preserve the manual `UEL` signature and include convention:
-
-```fortran
-      SUBROUTINE UEL(RHS, AMATRX, SVARS, ENERGY, NDOFEL,
-     1 NRHS, NSVARS, PROPS, NPROPS, COORDS, MCRD, NNODE,
-     2 U, DU, V, A, JTYPE, TIME, DTIME, KSTEP, KINC, JELEM,
-     3 PARAMS, NDLOAD, JDLTYP, ADLMAG, PREDEF, NPREDF,
-     4 LFLAGS, MLVARX, DDLMAG, MDLOAD, PNEWDT, JPROPS,
-     5 NJPROP, PERIOD)
-
-      INCLUDE 'ABA_PARAM.INC'
-
-      DIMENSION RHS(MLVARX,*), AMATRX(NDOFEL,NDOFEL),
-     1 SVARS(*), ENERGY(8), PROPS(*), COORDS(MCRD,NNODE),
-     2 U(NDOFEL), DU(MLVARX,*), V(NDOFEL), A(NDOFEL),
-     3 TIME(2), PARAMS(*), JDLTYP(MDLOAD,*),
-     4 ADLMAG(MDLOAD,*), DDLMAG(MDLOAD,*),
-     5 PREDEF(2,NPREDF,NNODE), LFLAGS(*), JPROPS(*)
-```
-
-The wrapper must keep `aba_param.inc` / `ABA_PARAM.INC` as an Abaqus/Standard include, not a project-local replacement. The no-Abaqus kernel may use its own pure calculation interface, but that kernel interface is not defined in this document as source layout.
-
-## Supported ABI Shape
-
-| argument or count | supported value | validation rule |
-| --- | --- | --- |
-| `NNODE` | `2` | reject anything else |
-| `NDOFEL` | `12` | reject anything else |
-| active DOFs per node | `1,2,3,4,5,6` | input keyword and kernel vector order must match |
-| `MCRD` | `>= 3` | read only `COORDS(1:3,1:2)` |
-| `NPROPS` | `9` | reject anything else |
-| `NJPROP` | `0` | first scope uses no integer properties |
-| `NSVARS` | `>= 1` | Abaqus `*USER ELEMENT` state-variable allocation must be positive; first scope leaves allocated `SVARS` entries unchanged |
-| `NRHS` | `1` | reject multi-RHS procedures |
-| `MLVARX` | `>= 12` | required for `RHS(1:12,1)` and `DU(1:12,1)` addressing |
-| `NDLOAD` | `0` | element-generated distributed loads are unsupported |
-| `MDLOAD` | any Abaqus value | no `JDLTYP`, `ADLMAG`, or `DDLMAG` entries are used because `NDLOAD=0` is required |
-| `NPREDF` | any Abaqus value | predefined fields are ignored; thermal and field coupling are unsupported |
-
-Unsupported shape values are fatal input-contract violations. They must not silently produce zero stiffness or zero residual.
-
-## DOF Ordering and Kernel Mapping
-
-Abaqus element vector ordering is node-major:
-
-```text
-1  node 1 U1
-2  node 1 U2
-3  node 1 U3
-4  node 1 UR1
-5  node 1 UR2
-6  node 1 UR3
-7  node 2 U1
-8  node 2 U2
-9  node 2 U3
-10 node 2 UR1
-11 node 2 UR2
-12 node 2 UR3
-```
-
-The wrapper passes this global vector order directly to the beam kernel as `q_global`. The kernel then applies the formulation transform:
-
-```text
-q_local = T*q_global
-K_global = T^T*k_local*T
-RHS = -K_global*q_global
-```
-
-No permutation is allowed between Abaqus `U(1:12)` and the kernel global vector. The local vector has the same node-major layout after projection to the local frame:
-
-```text
-[u1, v1, w1, th1_1, th2_1, th3_1, u2, v2, w2, th1_2, th2_2, th3_2]
-```
-
-## `PROPS` and `JPROPS` Schema
-
-The first-scope interface uses `PROPS` only. `JPROPS` is not used.
-
-| index | name | unit | required rule | semantic |
-| --- | --- | --- | --- | --- |
-| `PROPS(1)` | `E` | force / length^2 | finite and `> 0` | Young's modulus |
-| `PROPS(2)` | `G` | force / length^2 | finite and `> 0` | shear modulus for Saint-Venant torsion |
-| `PROPS(3)` | `A` | length^2 | finite and `> 0` | cross-sectional area |
-| `PROPS(4)` | `Iy` | length^4 | finite and `> 0` | second moment about local 2; couples local `w/th2` |
-| `PROPS(5)` | `Iz` | length^4 | finite and `> 0` | second moment about local 3; couples local `v/th3` |
-| `PROPS(6)` | `J` | length^4 | finite and `> 0` | Saint-Venant torsion constant |
-| `PROPS(7)` | `a_ref_1` | dimensionless direction component | finite | global approximate local 2 reference x-component |
-| `PROPS(8)` | `a_ref_2` | dimensionless direction component | finite | global approximate local 2 reference y-component |
-| `PROPS(9)` | `a_ref_3` | dimensionless direction component | finite | global approximate local 2 reference z-component |
-
-Orientation vector rules:
-
- `a_ref = [PROPS(7), PROPS(8), PROPS(9)]` is a global direction vector, not a point coordinate.
- The vector magnitude is arbitrary because the kernel normalizes its projection.
- Reject `norm(a_ref) <= 1.0e-12`.
- Reject `norm(a_ref - dot(a_ref,e1)*e1) / norm(a_ref) <= 1.0e-8`, where `e1` is the node 1 to node 2 beam axis.
- The accepted local frame is `e1 = node1->node2`, `e2 = normalized projected a_ref`, and `e3 = cross(e1,e2)`.
-
-`JPROPS` policy:
-
- `NJPROP` must be `0`.
- No integer flags, versions, orientation modes, or diagnostics are accepted in first scope.
- Any future `JPROPS` use requires a revised interface contract and new tests.
-
-## Abaqus Input Keyword Subset
-
-The reference model plan should use this `.inp` subset.
-
-| keyword | support_status | required parameters | mapped concept | notes |
-| --- | --- | --- | --- | --- |
-| `*HEADING` | supported | none | model title | optional |
-| `*NODE` | supported | none | node label and global coordinates | at least 3 coordinates per node for UEL geometry |
-| `*ELEMENT` | supported | `TYPE=U1` or the approved user element type, optional `ELSET` | two-node UEL connectivity | connectivity order defines local axis 1 |
-| `*ELSET` | supported | `ELSET` | element set | needed for `*UEL PROPERTY` |
-| `*NSET` | supported | `NSET` | node set | recommended for BC/load/output selection |
-| `*USER ELEMENT` | supported | `TYPE=U1`, `NODES=2`, `COORDINATES=3`, `PROPERTIES=9`, `VARIABLES=1` | UEL declaration | omit `UNSYMM`; omit `I PROPERTIES`; `SVARS(1)` is unused |
-| `*UEL PROPERTY` | supported | `ELSET` | real property assignment | data order is `PROPS(1:9)` |
-| `*BOUNDARY` | supported | standard nodal DOF constraints | essential boundary conditions | DOFs 1-6 allowed |
-| `*CLOAD` | supported | standard nodal concentrated load | external nodal loads/moments | loads are assembled by Abaqus outside UEL |
-| `*STEP` | supported | optional `NAME` | analysis step | static only |
-| `*STATIC` | supported | default or direct static data | small-displacement static procedure | no dynamics |
-| `*OUTPUT` | supported | none | output request root | optional but required for external artifacts |
-| `*NODE OUTPUT` | supported | `NSET` recommended | nodal CSV extraction source | request `U`, optional `UR`, `RF`/reaction moments as available |
-| `*END STEP` | supported | none | step terminator | required |
-
-Unsupported in first scope:
-
- `*DLOAD`, `*DSLOAD`, body forces, pressure loads, and distributed load generation
- `*MASS`, density, modal, transient, damping, and dynamic procedures
- `*BEAM SECTION`, `*BEAM GENERAL SECTION`, offsets, warping, and native beam section keywords for this UEL
- `*ORIENTATION` as the source of UEL orientation; use `PROPS(7:9)` instead
- material model keywords for UEL stiffness; use `*UEL PROPERTY` real values instead
- nonlinear geometry, follower loads, thermal expansion, predefined field coupling, plasticity, damage, creep, and viscoelastic behavior
-
-### Required `*USER ELEMENT` Shape
-
-The reference input deck should declare the user element with this logical content:
-
-```text
-*USER ELEMENT, TYPE=U1, NODES=2, COORDINATES=3, PROPERTIES=9, VARIABLES=1
-1, 2, 3, 4, 5, 6
-```
-
-If the final reference model chooses a different `TYPE=Un` identifier to avoid conflicts, the same `NODES`, `COORDINATES`, `PROPERTIES`, `VARIABLES`, and active DOF contract still applies.
-
-### Required `*UEL PROPERTY` Data Order
-
-```text
-*UEL PROPERTY, ELSET=<uel_element_set>
-E, G, A, Iy, Iz, J, a_ref_1, a_ref_2
-a_ref_3
-```
-
-Line breaks may follow Abaqus input formatting rules, but the logical property order is fixed.
-
-## Subroutine Parameter Contract
-
-| parameter | direction | first-scope responsibility |
-| --- | --- | --- |
-| `RHS(MLVARX,*)` | output | Initialize requested storage to zero every call; for supported residual requests, set `RHS(1:12,1) = -K_global*U(1:12)`. |
-| `AMATRX(NDOFEL,NDOFEL)` | output | Initialize all `12x12` entries to zero every call; for supported stiffness requests, set all entries to `K_global`. |
-| `SVARS(*)` | input/output | unused; require `NSVARS>=1` for Abaqus keyword compatibility; do not store diagnostics in first scope. |
-| `ENERGY(8)` | input/output | set `ENERGY(1:8)=0.0` every supported call; do not use as validation evidence in first scope. |
-| `NDOFEL` | input | must equal `12`. |
-| `NRHS` | input | must equal `1`. |
-| `NSVARS` | input | must be at least `1`. |
-| `PROPS(*)` | input | must contain the 9 real values defined above. |
-| `NPROPS` | input | must equal `9`. |
-| `COORDS(MCRD,NNODE)` | input | read `COORDS(1:3,1)` and `COORDS(1:3,2)` as original global node coordinates. |
-| `MCRD` | input | must be at least `3`. |
-| `NNODE` | input | must equal `2`. |
-| `U(NDOFEL)` | input | total current nodal DOF estimate; used for static residual. |
-| `DU(MLVARX,*)` | input | not used for first-scope static residual; may be used only by no-Abaqus tests to confirm it is ignored. |
-| `V(NDOFEL)` | input | ignored; dynamics out of scope. |
-| `A(NDOFEL)` | input | ignored; dynamics out of scope. |
-| `JTYPE` | input | not used except optional diagnostics; element type compatibility is enforced by `.inp` contract. |
-| `TIME(2)` | input | ignored for linear static stiffness/residual; may be copied to diagnostics only. |
-| `DTIME` | input | ignored; no time-step-dependent behavior. |
-| `KSTEP`, `KINC` | input | not used in calculations; may be used only for diagnostics. |
-| `JELEM` | input | element label for diagnostics and traceability. |
-| `PARAMS(*)` | input | ignored; no dynamic procedure parameters supported. |
-| `NDLOAD` | input | must equal `0`; distributed loads unsupported. |
-| `JDLTYP`, `ADLMAG`, `DDLMAG`, `MDLOAD` | input | ignored only after confirming `NDLOAD=0`. |
-| `PREDEF`, `NPREDF` | input | ignored; predefined fields unsupported. |
-| `LFLAGS(*)` | input | used to identify small-displacement static request and requested contribution. |
-| `MLVARX` | input | must be at least `12`. |
-| `PNEWDT` | input/output | do not modify for valid supported calls; invalid immutable inputs must fail explicitly rather than rely on cutback recovery. |
-| `JPROPS(*)`, `NJPROP` | input | require `NJPROP=0`; `JPROPS` ignored. |
-| `PERIOD` | input | ignored; not used in static analysis. |
-
-## Supported `LFLAGS` Behavior
-
-The first-scope wrapper supports only small-displacement static calls:
-
- require `LFLAGS(2)=0`
- support `LFLAGS(3)=1`, `2`, or `5`
- require `LFLAGS(1)=1` or `2` for static procedure calls
- require `LFLAGS(4)=0` for general-step behavior, not perturbation-only output
- require `NRHS=1`
-
-Contribution rules:
-
-| condition | `AMATRX` | `RHS` | policy |
-| --- | --- | --- | --- |
-| `LFLAGS(3)=1` | `K_global` | `-K_global*U` | primary static call |
-| `LFLAGS(3)=2` | `K_global` | zero | stiffness-only request |
-| `LFLAGS(3)=5` | zero | `-K_global*U` | residual-only request |
-| any other `LFLAGS(3)` | none | none | unsupported fatal diagnostic |
-
-Unsupported request examples include mass, damping, dynamics, half-step residuals, perturbation-only behavior, and large-displacement kinematics.
-
-## Validation Rules and Diagnostics
-
-Invalid input must be caught before matrix assembly. The implementation may choose the exact Abaqus-compatible fatal-reporting mechanism later, but it must preserve these diagnostic identifiers and meanings in tests or logs where feasible.
-
-| id | condition | expected behavior |
-| --- | --- | --- |
-| `UEL3DEB-E001` | `NDOFEL /= 12` | fatal unsupported element DOF count |
-| `UEL3DEB-E002` | `NNODE /= 2` | fatal unsupported topology |
-| `UEL3DEB-E003` | `MCRD < 3` | fatal missing 3D coordinates |
-| `UEL3DEB-E004` | `NPROPS /= 9` | fatal wrong real property count |
-| `UEL3DEB-E005` | `NJPROP /= 0` | fatal unsupported integer properties |
-| `UEL3DEB-E006` | `NSVARS < 1` | fatal missing Abaqus state-variable allocation |
-| `UEL3DEB-E007` | `NRHS /= 1` | fatal unsupported RHS count |
-| `UEL3DEB-E008` | `MLVARX < 12` | fatal invalid RHS/DU leading dimension |
-| `UEL3DEB-E009` | any required coordinate, `U`, or `PROPS` value is NaN or infinite | fatal nonfinite input |
-| `UEL3DEB-E010` | `E`, `G`, `A`, `Iy`, `Iz`, or `J <= 0` | fatal nonpositive physical property |
-| `UEL3DEB-E011` | element length `L <= 1.0e-12*max(1,norm(X1),norm(X2))` | fatal zero or near-zero element length |
-| `UEL3DEB-E012` | `norm(a_ref) <= 1.0e-12` | fatal zero orientation reference |
-| `UEL3DEB-E013` | `norm(a_perp)/norm(a_ref) <= 1.0e-8` | fatal near-parallel orientation reference |
-| `UEL3DEB-E014` | `LFLAGS(2) /= 0` | fatal unsupported large-displacement or non-small-displacement request |
-| `UEL3DEB-E015` | unsupported `LFLAGS(3)` | fatal unsupported contribution request |
-| `UEL3DEB-E016` | `NDLOAD /= 0` | fatal unsupported element load input |
-| `UEL3DEB-E017` | `LFLAGS(1)` is not `1` or `2` | fatal unsupported non-static procedure request |
-| `UEL3DEB-E018` | `LFLAGS(4) /= 0` | fatal unsupported perturbation-output request |
-
-For valid supported calls, the wrapper should set deterministic outputs for the requested contribution and should not modify `PNEWDT`.
-
-## Thin Wrapper Boundary
-
-The Abaqus ABI wrapper owns:
-
- preserving the exact `UEL` signature and `ABA_PARAM.INC` include
- validating argument counts, dimensions, request flags, and property values
- extracting `X1`, `X2`, `U(1:12)`, and `PROPS(1:9)`
- mapping `LFLAGS` to requested stiffness/residual operations
- writing `AMATRX`, `RHS`, `SVARS`, `ENERGY`, and `PNEWDT` according to this contract
- reporting diagnostics with `JELEM`, `KSTEP`, and `KINC` when available
-
-The no-Abaqus beam kernel conceptually owns:
-
- local frame construction from `X1`, `X2`, and `a_ref`
- local stiffness matrix assembly
- local-to-global transformation
- internal force and residual calculation
- numerical status reporting for invalid geometry or properties
-
-This document does not prescribe Fortran module names, source files, helper APIs, or data structures.
-
-## External CSV Extraction Schema
-
-All CSV files are externally generated from Abaqus results by the user. They must be placed under `references/uel-3d-euler-beam/<model-id>/extracted/` and declared in that model's `metadata.json`.
-
-### Required Common Columns
-
-Every comparison CSV row must include:
-
-| 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 used by extraction |
-| `instance` | string | Abaqus instance name, or `ASSEMBLY` if not applicable |
-| `node_label` | integer | Abaqus node label for nodal files |
-| `quantity` | string | extracted output quantity, for example `U`, `UR`, `RF`, or `RM` |
-| `component` | string | component label listed below |
-| `coordinate_system` | string | must be `GLOBAL` for first-scope comparison |
-| `unit` | string | declared user-consistent unit |
-| `value` | float | numeric extracted value |
-
-The CSV schema uses long format, one component per row, to avoid ambiguity between translational and rotational quantities.
-
-### `nodal_displacements.csv`
-
-Required for external solver-result comparison.
-
-Allowed component rows:
-
-| quantity | component | unit type | required |
-| --- | --- | --- | --- |
-| `U` | `U1`, `U2`, `U3` | length | yes |
-| `UR` | `UR1`, `UR2`, `UR3` | radian | optional unless the reference model compares rotations |
-
-Tolerance defaults:
-
- displacement absolute tolerance: `1.0e-8` in declared length units
- rotation absolute tolerance: `1.0e-8` radians unless the reference model narrows it
- relative tolerance: reference model may add scale-aware relative tolerance when needed
-
-### `reactions.csv`
-
-Required for external solver-result comparison at constrained nodes.
-
-Allowed component rows:
-
-| quantity | component | unit type | required |
-| --- | --- | --- | --- |
-| `RF` | `RF1`, `RF2`, `RF3` | force | yes for constrained translational DOFs |
-| `RM` | `RM1`, `RM2`, `RM3` | force*length | required when constrained rotational DOFs are part of the benchmark comparison |
-
-If the user's Abaqus extraction names rotational reactions differently, `metadata.json` must map the raw Abaqus variable/component name to the project component labels above.
-
-Tolerance defaults:
-
- force and moment relative tolerance: `1.0e-6`
- absolute tolerance: Reference Model Agent must define a scale-aware floor for each benchmark if the expected reaction can be near zero
-
-### Optional Element-Level CSVs
-
-No element force, stress, strain, section force, or energy CSV is required or approved for first-scope external comparison. Such CSVs require a later `SVARS` or output-recovery contract.
-
-## Reference Artifact Metadata Requirements
-
-Each external reference model must include metadata fields sufficient for `scripts/validate_reference_artifacts.py` plus feature-level declarations:
-
- `feature_id`: `uel-3d-euler-beam`
- Abaqus version and precision
- compiler vendor/name/version used for the user subroutine build, when applicable
- user subroutine source file hashes after implementation exists
- `model.inp` path and hash
- declared extracted CSV files and their schema version
- ODB extraction provenance, including extraction script name/version if available
- unit declarations for length, force, stress, moment, and rotation
- coordinate system declaration: `GLOBAL` for nodal comparison CSVs
-
-## Open Issues and Downstream Handoff
-
-### Reference Model Agent
-
- Use the keyword subset and property order in this document for `model.inp` examples.
- Include no-Abaqus tests for exact `PROPS(1:9)` mapping, `NJPROP=0`, `NSVARS>=1`, `NDOFEL=12`, `NNODE=2`, and active DOF order.
- Include negative tests for every `UEL3DEB-E###` validation rule that is practical in the no-Abaqus harness.
- Define benchmark-specific CSV filenames and near-zero absolute reaction tolerances.
- Keep external artifact generation outside this repository.
-
-### Implementation Planning Agent
-
- Preserve the Abaqus `UEL` signature exactly in the wrapper.
- Keep the wrapper thin and route only validated arrays/scalars to a no-Abaqus beam kernel.
- Implement deterministic zeroing for non-requested `AMATRX`/`RHS` in no-Abaqus drivers so tests are stable.
- Do not implement `SVARS`, `ENERGY`, distributed loads, dynamics, `JPROPS`, or `*ORIENTATION` support in first scope.
-
-### Reference Verification Agent
-
- Validate only externally generated CSVs declared in metadata.
- Match rows by `step`, `frame`, `instance`, `node_label`, `quantity`, `component`, `coordinate_system`, and `unit`.
- Reject CSVs with missing units, missing coordinate systems, unsupported component labels, or undeclared files.
- Compare first-scope external results using nodal displacement and reaction CSVs only.
@@ -1,162 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL Numerical Review
-
-## Metadata
- feature_id: uel-3d-euler-beam
- source_requirement: `docs/requirements/uel-3d-euler-beam.md`
- source_research: `docs/research/uel-3d-euler-beam-research.md`
- source_formulation: `docs/formulations/uel-3d-euler-beam.md`
- status: pass-for-interface-definition
- owner_agent: numerical-review-agent
- date: 2026-06-11
-
-## Review Verdict
-
- verdict: pass-for-interface-definition
- implementation_readiness: not blocked by formulation, but not approved for production implementation until the interface and no-Abaqus test-model gates are complete
- reason: The formulation has a complete linear static Euler-Bernoulli beam stiffness, consistent local/global transformation, no persistent state requirement, and explicit numerical validity checks. Remaining open items are Abaqus-facing interface decisions and downstream test-model obligations, not formulation blockers.
-
-## Critical Findings
-
-No blocking numerical findings were identified.
-
-No `needs-change` finding is raised against `docs/formulations/uel-3d-euler-beam.md`. The items that remain unresolved are already assigned to the I/O Definition Agent or Reference Model Agent.
-
-## Finding Register
-
-| id | status | review target | finding | required follow-up |
-| --- | --- | --- | --- | --- |
-| NR-001 | pass | `Local Element Stiffness Matrix` | The 12-by-12 local stiffness includes axial `EA/L`, torsion `GJ/L`, local 2 bending with `E*Iy`, and local 3 bending with `E*Iz`. The matrix is complete for the first-scope linear elastic beam. | Reference Model Agent must test each subblock independently. |
-| NR-002 | pass | `Local Element Stiffness Matrix` | The matrix is symmetric by construction. A scratch numerical check gave `maxabs(k-k^T)=0.0` for representative positive properties. | No-Abaqus tests should include scale-aware symmetry checks. |
-| NR-003 | pass | `Local Element Stiffness Matrix` | The free element is positive semidefinite before boundary conditions. A representative eigenvalue check found six small modes and six positive deformational modes; tiny negative values were roundoff scale. | No-Abaqus tests should check six rigid-body modes using a relative threshold tied to the largest stiffness eigenvalue. |
-| NR-004 | pass | `Primary Variables and DOFs`, `Local Element Stiffness Matrix` | The `Iy` and `Iz` association is internally consistent: `Iy` is bending about local 2 and couples `w/th2`; `Iz` is bending about local 3 and couples `v/th3`. The signs are consistent with `th2=-dw/dx` and `th3=dv/dx`. | Test-model gate must include separate local 2 and local 3 bending cases to catch axis swaps. |
-| NR-005 | pass | `Local Frame and Transformation to Global Coordinates` | The transform convention `q_local=T*q_global` and `K_global=T^T*k_local*T` is consistent with virtual work and Abaqus global matrix responsibility. | Interface gate must preserve the same ordering for translation and rotation blocks. |
-| NR-006 | pass | `Local Frame and Transformation to Global Coordinates` | The orientation construction gives an orthonormal right-handed frame when the reference vector has a nonzero perpendicular component. Scratch check: `maxabs(R*R^T-I)=2.22e-16`, `det(R)=0.9999999999999998`. | Interface gate must define the source and units/meaning of the orientation reference. |
-| NR-007 | pass | `Local Frame and Transformation to Global Coordinates` | Reversed node order is numerically consistent when interpreted with swapped nodal DOF ordering. Scratch check: `K_reversed = P^T*K_forward*P` to roundoff for a representative element. | Reference Model Agent should include a reversed-node or equivalent orientation permutation test. |
-| NR-008 | pass | `Element Equations and Residual Convention` | `RHS=-K_global*U` follows the researched Abaqus residual convention external minus internal for no element-generated loads. The formulation correctly keeps exact Abaqus fill behavior assigned to the I/O Definition Agent. | Interface gate must confirm the `RHS` array fill convention and no-Abaqus tests must lock the sign. |
-| NR-009 | pass | `AMATRX and RHS Contribution Rules by Supported LFLAGS` | The supported `LFLAGS(3)=1,2,5` contribution split is numerically coherent for static requests. Unsupported mass, damping, dynamics, and large-displacement paths are explicitly out of scope. | Interface gate must define exact behavior for unsupported requests. |
-| NR-010 | pass | `Numerical Tolerances and Validity Checks` | Zero-length, nonfinite inputs, nonpositive properties, near-parallel orientation, orthonormality, determinant, and symmetry checks are present. The `1.0e-8` near-parallel threshold is conservative enough for first implementation. | Test-model gate must include invalid length, invalid property, zero orientation, and near-parallel orientation negative cases. |
-| NR-011 | pass | `State Variables, Energy, and Output Recovery` | No persistent `SVARS` are needed for a linear elastic, path-independent static element. Energy expression is correct but not required for first scope. | Interface gate should keep `SVARS` and `ENERGY` unused unless it adds an explicit output contract. |
-| NR-012 | pass | `Mapping and Numerical Integration` | Analytical stiffness avoids integration-order and hourglass risks. The straight two-node centerline mapping is adequate for first-scope prismatic members. | Do not introduce reduced numerical integration in implementation planning. |
-
-## Independent Scratch Checks
-
-The review included a local scratch calculation using representative positive properties, non-axis-aligned coordinates, and a nonparallel orientation reference. This was not committed as a test because step 3 is a documentation-only review gate.
-
-```text
-L = 4.69041575982
-local_sym = 0.000e+00
-global_sym_raw = 7.451e-09
-maxabs_K = 5.871224e+07
-global_sym_normalized = 1.269e-16
-scaled_symmetry_tolerance = 5.871e-05
-R_orthonormality_error = 2.220e-16
-detR = 0.9999999999999998
-eig_small_count = 6
-identity_orientation_K_equals_k = 0.000e+00
-reversed_node_permuted_diff = 0.000e+00
-```
-
-Interpretation:
-
- The raw transformed symmetry difference is harmless because it is far below the formulation's scale-aware symmetry tolerance.
- Six near-zero eigenvalues match the expected rigid-body modes for a free two-node 3D beam element.
- The identity-orientation and reversed-node checks support the transformation convention.
-
-## Numerical Risk Assessment
-
-| risk | assessment | review result |
-| --- | --- | --- |
-| rigid_body_modes | Free element must have six rigid-body modes. Formulation states this, and scratch eigenvalue count supports it. | pass |
-| patch_test | A constant axial strain, constant torsion rate, and constant curvature bending patch are representable by the interpolation. Multi-element patch expectations still need test-model specification. | pass |
-| symmetry | Linear elastic closed-form stiffness and orthonormal transform preserve symmetry to roundoff. | pass |
-| positive_definiteness | Free element is semidefinite; constrained models should become positive definite after removing rigid modes. | pass |
-| hourglass | Not applicable because no reduced integration is used. | pass |
-| shear_locking | Not applicable to this Euler-Bernoulli formulation; shear deformation is excluded. Applicability to deep beams is a modeling-scope risk, not a numerical defect. | pass |
-| volumetric_locking | Not applicable. | pass |
-| distortion | Curved, distorted, or tapered geometry is out of scope. Straight element validity reduces to nonzero length and valid orientation. | pass |
-| singular_jacobian | Zero-length member and near-parallel orientation checks address the relevant singular cases. | pass |
-| conditioning | Very short/long members and extreme property ratios can produce ill-conditioned matrices. The formulation flags this; downstream tests should cover scale-aware thresholds. | pass |
-| convergence | For supported linear static cases, the tangent is constant and exactly consistent with internal force. Convergence risk is mainly interface sign/fill mistakes. | pass |
-
-## Consistency Checks
-
-| check | result | notes |
-| --- | --- | --- |
-| units | pass | `EA/L`, `12EI/L^3`, `6EI/L^2`, `4EI/L`, and `GJ/L` have the expected force, force/length, force, moment, and moment/radian roles under self-consistent units. |
-| dimensions | pass | `AMATRX` is 12-by-12; `RHS`, `U`, local force, and residual vectors are length 12. |
-| signs | pass | Bending signs are consistent with `th2=-dw/dx` and `th3=dv/dx`; residual sign remains an interface confirmation item. |
-| dof_ordering | pass | Local ordering is consistent with Abaqus six-DOF node order after local/global projection. |
-| coordinate_transforms | pass | `q_local=T*q_global`, `f_global=T^T*f_local`, and `K_global=T^T*k_local*T` preserve virtual work. |
-| matrix_vector_dimensions | pass | All matrix-vector products in the algorithm pseudocode are dimensionally valid. |
-| integration_weights | pass | Analytical closed-form stiffness avoids numerical quadrature ambiguity. |
-| output_locations | pass | External comparison is limited to nodal global `U` and `RF`; element force output is deferred until an interface output path exists. |
-| state_update | pass | No history state is needed for path-independent linear elasticity. |
-| consistent_tangent | pass | `K_global` is the exact derivative of `f_int=K_global*U` for the first-scope linear static element. |
-
-## Verification Readiness
-
-Downstream no-Abaqus tests should include:
-
- `BM-NOA-AXIAL-001`: axial extension/compression checks for `EA/L`.
- `BM-NOA-TORSION-001`: torsion checks for `GJ/L`.
- `BM-NOA-BEND-Y-001`: local 2 bending with `w/th2` and `E*Iy`.
- `BM-NOA-BEND-Z-001`: local 3 bending with `v/th3` and `E*Iz`.
- `BM-NOA-RBM-001`: six free-element rigid-body modes and matrix symmetry.
- `BM-NOA-ROT-001`: arbitrary rotated element and identity-orientation transform checks.
- `BM-NOA-REVNODE-001`: reversed node order or equivalent nodal permutation check.
- `BM-NOA-RHS-001`: residual sign check for `RHS=-K_global*U` under the approved interface convention.
- invalid-input tests for zero length, nonfinite coordinates, nonpositive properties, zero orientation reference, and near-parallel orientation reference.
-
-Patch/regression tests should include:
-
- one-element constant axial strain patch
- one-element pure torsion patch
- cantilever end-force bending about local 2 and local 3
- two-element collinear patch to catch assembly-order or transform mismatches
- rotated cantilever with non-axis-aligned local frame
-
-External Abaqus reference comparison should remain limited to user-generated artifacts:
-
- nodal displacement `U`
- support reaction `RF`
- convergence/log tail evidence
- coordinate-system labels and units in extracted CSVs
-
-No MMS case is required for this first linear structural element; closed-form beam benchmarks and matrix invariants are more direct.
-
-## Required Revisions
-
-### Formulation Agent
-
- None.
-
-### Research Agent
-
- None.
-
-### I/O Definition Agent
-
- Confirm the exact Abaqus `UEL` `RHS` fill convention for static `NRHS=1`.
- Define the `PROPS`/`JPROPS` or alternate mapping for `E`, `G`, `A`, `Iy`, `Iz`, `J`, and the orientation reference.
- Define the exact behavior for invalid inputs and unsupported `LFLAGS` requests.
- Define whether `ENERGY` remains untouched/zeroed or is populated in a later approved scope.
- Keep `SVARS` unused unless an explicit diagnostic output route is approved.
-
-### Reference Model Agent
-
- Convert the verification readiness list above into no-Abaqus test cases before any production Fortran source changes.
- Define external Abaqus reference bundles only as user-generated `model.inp`, extracted CSV, tail logs, and metadata under `references/uel-3d-euler-beam/<model-id>/`.
-
-## Downstream Handoff
-
-### I/O Definition Agent
-
-The formulation is numerically coherent enough to proceed to interface definition. Preserve the documented local DOF order, `Iy/Iz` axis mapping, transformation convention, and static residual physics.
-
-### Implementation Planning Agent
-
-Do not start production Fortran implementation from this review alone. Implementation planning may use this formulation after the interface contract and no-Abaqus test model plan are complete.
-
-### Reference Model Agent
-
-Use the `Verification Readiness` section as the minimum no-Abaqus regression set. Treat reversed-node behavior and residual sign as required tests, not optional checks.
@@ -1,531 +0,0 @@
-# 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 | checked by Python source-smoke because the file depends on Abaqus-provided include and `XIT` |
-
-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 |
-| `scripts/test_uel_3d_euler_beam_uel.py` | source-smoke contract for the fixed-form Abaqus `UEL` wrapper signature and dimensions |
-
-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>=1`, 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(1)`, unsupported `LFLAGS(2)`, unsupported `LFLAGS(3)`, unsupported `LFLAGS(4)`, 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>=1`, `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(1)=1|2`, `LFLAGS(2)=0`, `LFLAGS(3)=1|2|5`, and `LFLAGS(4)=0` select the supported static general-step path
- `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=1`
- 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.
@@ -1,196 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL Requirements
-
-## Metadata
- feature_id: uel-3d-euler-beam
- title: 3D Euler-Bernoulli Beam Abaqus/Standard UEL
- status: needs-user-decision
- owner_agent: requirement-agent
- date: 2026-06-11
-
-## Purpose
-Define a measurable requirements baseline for a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam element implemented as an Abaqus/Standard `UEL`. This document is the handoff contract for research, formulation, interface definition, no-Abaqus test model design, Fortran implementation planning, and external Abaqus result validation.
-
-## In Scope
- Abaqus/Standard `UEL` entry point for static small-displacement analysis.
- Two-node 3D Euler-Bernoulli beam element with 12 total degrees of freedom.
- Six degrees of freedom per node ordered as `U1, U2, U3, UR1, UR2, UR3`.
- Linear elastic response with axial, bending about two principal local section axes, and Saint-Venant torsion stiffness.
- Static element stiffness contribution through `AMATRX`.
- Static internal force or residual contribution through `RHS`, with exact Abaqus sign convention delegated to the interface contract.
- User-consistent units with no unit conversion inside the element.
- No-Abaqus analytical evidence before any Fortran production source changes.
- External Abaqus artifact evidence based on user-generated ODB-extracted CSV files before solver-result comparison.
-
-## Out Of Scope
- Geometric nonlinearity, large rotation, follower loads, and corotational updates.
- Timoshenko shear deformation, shear correction factors, and shear locking mitigation.
- Distributed loads, body forces, pressure loads, point-load handling inside `UEL`, and load interpolation.
- Mass matrix, damping matrix, modal dynamics, transient dynamics, and density-dependent behavior.
- Thermal strain, plasticity, damage, creep, viscoelasticity, warping torsion, section offset, tapered members, and curved beams.
- Direct ODB parsing or Abaqus job execution from this repository.
- Generated reference CSV, `.msg`, `.dat`, `.log`, or `.sta` evidence produced by Codex.
- Fortran source, no-Abaqus tests, reference artifacts, or implementation plans in this requirements step.
-
-## Analysis Definition
- analysis_type: linear static small-displacement
- Abaqus entry point: `UEL`
- element_family: two-node 3D Euler-Bernoulli beam
- element_nodes: 2
- total_dofs: 12
- dofs_per_node: 6
- dof_order: node 1 `U1, U2, U3, UR1, UR2, UR3`, then node 2 `U1, U2, U3, UR1, UR2, UR3`
- material_model: linear elastic beam section stiffness
- required physical properties: `E`, `G`, `A`, `Iy`, `Iz`, `J`
- density: not required for first implementation; required only if a later approved mass-matrix scope is added
- coordinate_system: global nodal coordinates plus a local beam frame defined by the element axis and an orientation reference
- units: user-consistent force-length unit system; every external CSV used for validation must declare units
- boundary_conditions: defined by downstream no-Abaqus and external reference models
- loads: applied outside the `UEL`; first-scope `UEL` does not implement distributed or body load generation
-
-## Requirement Decisions
- The first implementation shall require independent `E` and `G` values rather than deriving `G` from `E` and `nu`.
- The first implementation shall require `A`, `Iy`, `Iz`, and `J` as positive section properties.
- The first implementation shall not use density because mass and dynamics are out of scope.
- Element local axis 1 shall be the line from node 1 to node 2.
- A nonparallel orientation reference shall be required to define the remaining local beam axes; the exact Abaqus keyword and property mapping belongs to the I/O Definition Agent.
- `RHS` sign convention shall be resolved by the I/O Definition Agent against Abaqus `UEL` residual conventions and then tested by no-Abaqus single-element cases.
-
-## Must Requirements
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-001: The feature shall target Abaqus/Standard `UEL` only.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-002: The element shall be a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-003: The element shall expose exactly 12 active element degrees of freedom with six degrees of freedom per node.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-004: The element degree-of-freedom ordering shall be `U1, U2, U3, UR1, UR2, UR3` at node 1 followed by the same order at node 2.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-005: The first-scope material and section contract shall provide `E`, `G`, `A`, `Iy`, `Iz`, and `J`.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-006: The accepted physical properties shall be finite and strictly positive.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-007: The element orientation contract shall define a valid right-handed local beam frame from the node coordinates and a nonparallel orientation reference.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-008: The element shall provide the static tangent stiffness contribution in `AMATRX`.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-009: The element shall provide the static internal force or residual contribution in `RHS` according to the interface contract sign convention.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-010: The first implementation shall exclude mass, damping, distributed load, thermal, nonlinear geometry, plasticity, damage, shear deformation, warping torsion, and section offset behavior.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-011: The implementation shall not require this repository to run Abaqus jobs or parse ODB files.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-012: The implementation shall have no-Abaqus evidence before any Fortran production source is changed.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-013: Solver-result comparison shall require externally generated Abaqus artifacts under `references/uel-3d-euler-beam/`.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-014: Every external solver-result CSV used for comparison shall include identifiers, component labels, coordinate-system labels, units, and numeric values.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-015: Numerical comparisons shall use explicit absolute and relative tolerances rather than informal pass/fail judgment.
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-016: The requirements, research, formulation, interface, test model, implementation, and validation artifacts shall remain separate gate outputs.
-
-## Should Requirements
- The no-Abaqus test suite should include independent single-element checks for axial extension, torsion, bending about local `y`, bending about local `z`, rigid-body modes, stiffness symmetry, and coordinate transformation.
- External Abaqus reference models should include at least one cantilever-style displacement/reaction check and one rotated-orientation check.
- The interface contract should name the exact `PROPS` or alternative property mapping only after the orientation convention and `RHS` sign convention are settled.
- The formulation document should document local-to-global transformation, rigid-body modes, and expected matrix symmetry without changing the requirements scope.
-
-## Could Requirements
- A later approved scope could add density and consistent or lumped mass matrix behavior.
- A later approved scope could add distributed load vector generation.
- A later approved scope could add Timoshenko shear deformation as a separate element family or variant.
- A later approved scope could add section offset or warping-torsion behavior after new requirements and validation artifacts are approved.
-
-## Input Requirements
- Conceptual physical inputs: `E`, `G`, `A`, `Iy`, `Iz`, `J`, node coordinates, and one orientation reference that is not parallel to the element axis.
- The I/O Definition Agent must define the Abaqus-facing source of these values, including property ordering, keyword support, validation behavior for invalid inputs, and mapping to `UEL` arguments.
- The requirements step does not approve a final `PROPS`, `JPROPS`, `COORDS`, or `PARAMS` layout.
-
-## Output Requirements
- `AMATRX`: required for the static stiffness contribution.
- `RHS`: required for the static internal force or residual contribution.
- `SVARS`: not required for first implementation unless later interface work identifies a minimal diagnostic need.
- `ENERGY`: not required for first implementation; if populated later, it requires a separate requirement and verification method.
- ODB-extracted validation outputs: nodal displacement and reaction CSV evidence are required before solver-result comparison.
-
-## Verification Quantities
- nodal_displacement: required for external Abaqus reference comparison.
- reaction: required for external Abaqus reference comparison.
- element_internal_force_or_residual: required for no-Abaqus verification; external CSV is optional unless a downstream extraction contract exposes it.
- stiffness_matrix: required for no-Abaqus verification.
- rigid_body_modes: required for no-Abaqus verification.
- stress: not-applicable for first implementation unless a later output recovery contract is approved.
- strain: not-applicable for first implementation unless a later output recovery contract is approved.
- energy_or_residual: residual required for no-Abaqus verification; energy not required for first implementation.
-
-## Tolerance Policy
- no_abaqus_stiffness_absolute_tolerance: `1.0e-10` in user-consistent force-length units after nondimensional or scale-aware comparison.
- no_abaqus_stiffness_relative_tolerance: `1.0e-10`.
- no_abaqus_vector_absolute_tolerance: `1.0e-10` in user-consistent force or moment units after scale-aware comparison.
- no_abaqus_vector_relative_tolerance: `1.0e-10`.
- no_abaqus_symmetry_absolute_tolerance: `1.0e-12` for `AMATRX - transpose(AMATRX)` after scale-aware normalization.
- external_displacement_absolute_tolerance: `1.0e-8` in declared length units unless the reference model contract justifies a tighter value.
- external_reaction_relative_tolerance: `1.0e-6` for externally generated Abaqus CSV comparison.
- tolerance_owner: Reference Model Agent may tighten or scale these tolerances only by documenting the physical quantity, units, scale, and rationale.
-
-## Required No-Abaqus Evidence Before Fortran Production Changes
- A no-Abaqus test or driver must check that the 12-by-12 stiffness matrix has the expected symmetry, rank behavior, and rigid-body null modes for an unconstrained element.
- A no-Abaqus test or driver must check axial stiffness against a closed-form two-node beam expectation.
- A no-Abaqus test or driver must check torsional stiffness against a closed-form two-node beam expectation.
- A no-Abaqus test or driver must check bending response about both local section axes.
- A no-Abaqus test or driver must check at least one rotated element orientation against an independently computed transformation expectation.
- A no-Abaqus test or driver must check that `RHS` is consistent with the accepted `AMATRX` and displacement vector sign convention.
- `tests/fortran/manifest.json` or an approved equivalent no-Abaqus validation entry must exist before production Fortran source is changed.
-
-## Required External Abaqus Artifact Evidence Before Solver-Result Comparison
-Expected location: `references/uel-3d-euler-beam/<model-id>/`
-
- `metadata.json`: required with schema version, artifact status, Abaqus version, precision, compiler information, entry point list, source file hashes, input file reference, CSV declarations, and extraction provenance.
- `model.inp`: required.
- `job.msg.tail.txt`: required.
- `job.dat.tail.txt`: required.
- `job.log.tail.txt`: required.
- `job.sta.tail.txt`: required.
- `extracted/*.csv`: required for declared comparison quantities.
- `result.odb.sha256`: optional when the ODB is not stored but provenance needs to identify the source result database.
- Minimum CSV comparison quantities for first external evidence: nodal displacement and reaction at selected nodes for static benchmark models.
-
-## Requirement Verification Matrix
-
-| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-001 | The feature shall target Abaqus/Standard `UEL` only. | scope | Prevents mixed ABI assumptions. | user; step0 | must | document-inspection | Requirements, interface, and later source identify `UEL` as the only entry point. | not-applicable | I/O Definition Agent; Implementation Planning Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-002 | The element shall be a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam. | functional | Defines the element family and excludes shear deformation and nonlinear kinematics. | user; step0 | must | formulation-review; no-abaqus-tests | Formulation and tests cover axial, torsion, and two bending modes without shear terms or nonlinear update terms. | no-Abaqus relative `1.0e-10` for analytical checks | Research Agent; Formulation Agent; Reference Model Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-003 | The element shall expose exactly 12 active element degrees of freedom with six degrees of freedom per node. | interface | Fixes the element topology for `UEL` assembly. | user; step0 | must | interface-review; no-abaqus-tests | Interface contract and tests use `NDOFEL=12` and two six-DOF nodes. | not-applicable | I/O Definition Agent; Reference Model Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-004 | The element degree-of-freedom ordering shall be `U1, U2, U3, UR1, UR2, UR3` at node 1 followed by the same order at node 2. | interface | Prevents stiffness and residual component permutation errors. | user; step0 | must | interface-review; no-abaqus-tests | Unit tests or driver checks map all 12 components to the documented order. | exact index match | I/O Definition Agent; Reference Model Agent; Implementation Planning Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-005 | The first-scope material and section contract shall provide `E`, `G`, `A`, `Iy`, `Iz`, and `J`. | input | Provides all stiffness scalars needed for linear axial, torsion, and bending response. | user; requirement decision | must | interface-review; no-abaqus-tests | Interface contract defines all six required physical properties and no-Abaqus tests exercise each property. | not-applicable for presence; numerical checks per quantity tolerances | I/O Definition Agent; Reference Model Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-006 | The accepted physical properties shall be finite and strictly positive. | input-validation | Prevents singular or nonphysical stiffness definitions. | requirement decision | must | no-abaqus-tests | Invalid zero, negative, NaN, or infinite properties are rejected or reported by the approved interface behavior before matrix assembly. | exact validation outcome | I/O Definition Agent; Reference Model Agent; Implementation Planning Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-007 | The element orientation contract shall define a valid right-handed local beam frame from the node coordinates and a nonparallel orientation reference. | orientation | 3D bending requires stable local section axes. | requirement decision | must | formulation-review; interface-review; no-abaqus-tests | Formulation and interface define the local frame, reject parallel orientation references, and pass a rotated-orientation test. | no-Abaqus relative `1.0e-10` for transformed stiffness checks | Formulation Agent; I/O Definition Agent; Reference Model Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-008 | The element shall provide the static tangent stiffness contribution in `AMATRX`. | output | `AMATRX` is the primary static contribution for Abaqus/Standard assembly. | user; step0 | must | no-abaqus-tests; external-reference-comparison | No-Abaqus tests match analytical stiffness expectations; external reference models converge and match displacement/reaction evidence. | no-Abaqus relative `1.0e-10`; external reaction relative `1.0e-6` | Formulation Agent; Reference Model Agent; Implementation Planning Agent; Validation Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-009 | The element shall provide the static internal force or residual contribution in `RHS` according to the interface contract sign convention. | output | Static equilibrium requires a consistent residual vector. | user; step0 | must | interface-review; no-abaqus-tests; external-reference-comparison | Interface defines the sign convention; no-Abaqus tests verify consistency with `AMATRX` and displacement; external models match reactions and displacements. | no-Abaqus vector relative `1.0e-10`; external displacement absolute `1.0e-8` | I/O Definition Agent; Reference Model Agent; Validation Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-010 | The first implementation shall exclude mass, damping, distributed load, thermal, nonlinear geometry, plasticity, damage, shear deformation, warping torsion, and section offset behavior. | non-scope | Keeps the first implementation verifiable and linear. | user; step0 | must | document-inspection; source-review | Requirements, formulation, interface, tests, and source contain no approved behavior from the excluded list. | not-applicable | Research Agent; Formulation Agent; Implementation Planning Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-011 | The implementation shall not require this repository to run Abaqus jobs or parse ODB files. | validation-boundary | Preserves project architecture and reproducibility. | AGENTS.md; ADR-004 | must | workspace-validation; reference-artifact-review | Validation commands use no-Abaqus tests and artifact metadata checks; no repository script is required to run Abaqus or parse ODB. | not-applicable | Reference Model Agent; Validation Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-012 | The implementation shall have no-Abaqus evidence before any Fortran production source is changed. | process | Enforces RED -> GREEN -> VERIFY for numerical code. | AGENTS.md; ADR-007 | must | manifest-review; validation-command | A no-Abaqus test manifest or approved equivalent exists and fails for expected missing behavior before production source changes. | exact process evidence | Reference Model Agent; Implementation Planning Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-013 | Solver-result comparison shall require externally generated Abaqus artifacts under `references/uel-3d-euler-beam/`. | reference-artifact | Ensures solver evidence has provenance. | AGENTS.md; ADR-006 | must | reference-artifact-validation | `python scripts/validate_reference_artifacts.py` accepts only complete externally generated artifact bundles before comparison. | not-applicable | Reference Model Agent; Validation Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-014 | Every external solver-result CSV used for comparison shall include identifiers, component labels, coordinate-system labels, units, and numeric values. | csv-schema | Prevents ambiguous numerical comparison. | ARCHITECTURE.md | must | schema-validation; reference-artifact-review | CSV schema includes step/frame or time, node or element identifier as applicable, component, coordinate system, unit, and value columns. | exact schema match | I/O Definition Agent; Validation Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-015 | Numerical comparisons shall use explicit absolute and relative tolerances rather than informal pass/fail judgment. | tolerance | Makes verification reproducible. | requirements skill | must | test-review; validation-review | Test model and validation artifacts name absolute and relative tolerances for each compared quantity. | values in Tolerance Policy unless narrowed by owner | Reference Model Agent; Validation Agent | draft |
-| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-016 | The requirements, research, formulation, interface, test model, implementation, and validation artifacts shall remain separate gate outputs. | process | Avoids mixing unreviewed decisions into implementation. | AGENTS.md; ADR-003 | must | document-inspection; workspace-validation | Each downstream phase writes to its own documented artifact family and does not replace requirements with implementation details. | not-applicable | Coordinator Agent; all downstream agents | draft |
-
-## Open Questions
- Exact Abaqus input keyword subset for assigning UEL properties and orientation: owner `I/O Definition Agent`.
- Exact `PROPS`, `JPROPS`, `COORDS`, and orientation reference mapping: owner `I/O Definition Agent`.
- Exact `RHS` sign convention and treatment of `LFLAGS` static requests: owner `I/O Definition Agent`.
- Whether `SVARS` or `ENERGY` should carry diagnostics in a later scope: owner `Formulation Agent` and `I/O Definition Agent`.
- Exact external benchmark model set and CSV filenames: owner `Reference Model Agent`.
- Whether any first-scope reference model needs element-level force extraction beyond nodal `U` and `RF`: owner `Reference Model Agent` and `Validation Agent`.
-
-## Downstream Handoff
-
-### Research Agent
- Confirm Abaqus/Standard `UEL` static contribution expectations for `RHS`, `AMATRX`, `LFLAGS`, and required argument semantics.
- Collect reliable references for 3D Euler-Bernoulli beam stiffness, local coordinate construction, and transformation behavior.
- Separate manual-backed facts from implementation inference.
-
-### Formulation Agent
- Define the local stiffness matrix, local-to-global transformation, rigid-body mode expectations, and internal force/residual relation without adding out-of-scope physics.
- Define how the right-handed local frame is constructed from node coordinates and orientation reference.
- Identify numerical risks such as near-zero element length or nearly parallel orientation references.
-
-### I/O Definition Agent
- Define the exact Abaqus-facing input contract for `E`, `G`, `A`, `Iy`, `Iz`, `J`, coordinates, and orientation.
- Define `UEL` argument responsibilities, including `RHS`, `AMATRX`, `SVARS`, `ENERGY`, `LFLAGS`, tensor/component ordering, units, and validation behavior.
- Define CSV schema requirements for external solver-result comparison.
-
-### Reference Model Agent
- Design no-Abaqus tests for axial, torsion, two bending modes, matrix symmetry, rigid-body modes, orientation transformation, and `RHS` consistency.
- Define required `tests/fortran/manifest.json` entries or approved equivalent no-Abaqus validation entries before Fortran production changes.
- Define external Abaqus reference artifact bundles under `references/uel-3d-euler-beam/<model-id>/` without generating reference CSVs in this repository.
-
-### Implementation Planning Agent
- Do not create or modify Fortran production source until no-Abaqus RED evidence exists.
- Keep the Abaqus `UEL` wrapper thin and isolate testable beam calculations where the approved interface contract permits.
- Use `python scripts/validate_fortran.py`, `python scripts/validate_reference_artifacts.py`, and `python scripts/validate_workspace.py` for VERIFY evidence.
@@ -8,6 +8,13 @@

 Research Agent는 FEM 이론, benchmark, verification reference, solver manual, 논문 자료를 조사한다.

+## Source Selection Protocol
+
+- 유한요소 정식화, residual/tangent, constitutive integration, benchmark, 수치 검증 지식은 `fem-theory-query`를 통해 탐색한다.
+- Abaqus User Subroutine ABI, argument, update responsibility, product applicability, utility routine은 먼저 `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`를 읽어 section 위치를 찾는다.
+- 다음으로 `INDEX.md`의 complete record를 읽고, record의 모든 `source_ranges` 원문을 순서대로 읽는다. Summary, keyword, content anchor는 탐색 metadata일 뿐 authoritative fact가 아니다.
+- FEM wiki evidence, Abaqus manual fact, 논문 또는 benchmark fact, agent inference를 서로 구분해 기록한다.
+
 수행한다:
 - 기능 요구조건과 관련된 이론 자료를 조사한다.
 - 요소별 benchmark, patch test, MMS, MES, convergence study 후보를 찾는다.
@@ -27,7 +34,7 @@ Research Agent는 FEM 이론, benchmark, verification reference, solver manual,

 | tier | source type | examples | use |
 | --- | --- | --- | --- |
-| Tier 1 | 공식 표준, 공식 solver manual, 공식 benchmark, 공공기관 자료 | ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI, official solver manuals | 우선 근거 |
+| Tier 1 | 공식 표준, 공식 solver manual, 공식 benchmark, 공공기관 자료 | local indexed Abaqus User Subroutine Manual source spans, ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI | 우선 근거 |
 | Tier 2 | peer-reviewed paper, reproducible arXiv preprint, textbook | MMS/MES 논문, finite element textbook | 이론/검증 후보 |
 | Tier 3 | vendor example, university course note, technical blog | 공개 강의노트, 기술 블로그 | 보조 근거 |
 | Reject | forum answer, LLM summary, unsourced page, illegal PDF mirror, citation 없는 wiki성 문서 | forum, mirror PDF, 출처 없는 요약 | primary evidence로 사용 금지 |
@@ -100,6 +107,7 @@ Research Agent는 FEM 이론, benchmark, verification reference, solver manual,
 ## 품질 기준

 - 모든 외부 근거는 source metadata와 reliability tier를 가져야 한다.
+- FEM claim은 `fem-theory-query` evidence에, Abaqus-specific claim은 local manual section과 source span에 추적 가능해야 한다.
 - verified fact와 inference를 구분해야 한다.
 - benchmark 후보는 target quantity와 applicability limit을 가져야 한다.
 - Abaqus Benchmarks Guide와 Abaqus Verification Guide의 용도를 구분해야 한다.
@@ -1,188 +0,0 @@
-# 3D Euler-Bernoulli Beam UEL Research Brief
-
-## Metadata
- feature_id: uel-3d-euler-beam
- source_requirement: `docs/requirements/uel-3d-euler-beam.md`
- status: ready-for-formulation
- owner_agent: research-agent
- date: 2026-06-11
-
-## Research Questions
- Abaqus/Standard `UEL`에서 `RHS`, `AMATRX`, `SVARS`, `ENERGY`, `NDOFEL`, `NNODE`, `MCRD`, `LFLAGS`, `PROPS`, `COORDS`, `U`, `DU`, `JPROPS`의 책임과 의미는 무엇인가?
- 2-node 3D Euler-Bernoulli beam/frame element의 local stiffness matrix는 어떤 물리 항으로 구성되는가?
- Abaqus user element가 local element stiffness를 제공해야 하는가, global element stiffness를 제공해야 하는가?
- 3D beam local frame은 어떤 orientation reference와 edge case를 가져야 하는가?
- Static `UEL`에서 `RHS` residual sign convention은 첫 구현에서 어떻게 해석해야 하는가?
- No-Abaqus verification과 external Abaqus CSV comparison에 적합한 benchmark 후보는 무엇인가?
-
-## Source Inventory
-
-| id | source_type | title | author_or_org | URL_or_DOI | access_date | reliability_tier | notes |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| S1 | official solver manual | Abaqus 2025 User Subroutines Reference Guide, `UEL` | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAESUBRefMap/simasub-c-uel.htm | 2026-06-11 | Tier 1 | Publicly accessible Abaqus documentation mirror. If a licensed local SIMULIA help install conflicts, use the licensed install as authoritative. |
-| S2 | official solver manual | Abaqus 2025 Analysis User's Guide, User-Defined Elements | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-c-userelem.htm | 2026-06-11 | Tier 1 | Defines user element input, DOF ordering, global-system responsibility, properties, output limits, and loads. |
-| S3 | official keyword manual | Abaqus 2025 Keywords Reference, `*USER ELEMENT` | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-userelement.htm | 2026-06-11 | Tier 1 | Defines `TYPE`, `NODES`, `COORDINATES`, `PROPERTIES`, `I PROPERTIES`, `VARIABLES`, `UNSYMM`, and active DOF data lines. |
-| S4 | official keyword manual | Abaqus 2025 Keywords Reference, `*UEL PROPERTY` | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-uelproperty.htm | 2026-06-11 | Tier 1 | Defines property values and optional `MATERIAL` and `ORIENTATION` parameters. |
-| S5 | official solver manual | Abaqus 2025 Conventions | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEMODRefMap/simamod-c-conventions.htm | 2026-06-11 | Tier 1 | Defines DOF numbers, global coordinate convention, and self-consistent units. |
-| S6 | official solver manual | Abaqus Analysis User's Guide Volume IV, Beam element cross-section orientation | Dassault Systemes SIMULIA | Local vault: `D:\Obsidian\MultiPhysicsVault\.raw\AbaqusAnalysisUserGuide4\AbaqusAnalysisUserGuide4_031.md` | 2026-06-11 | Tier 1 | Used for beam `t, n1, n2` orientation facts and edge cases. |
-| S7 | textbook | A First Course in the Finite Element Method, 4th ed. | Daryl L. Logan | Local vault source: `D:\Obsidian\MultiPhysicsVault\wiki\sources\A-First-Course-in-the-Finite-Element-Method.md` | 2026-06-11 | Tier 2 | Used for Euler-Bernoulli beam, torsion, 3D space-frame stiffness, transformation, and analytical benchmark facts. |
-| S8 | official verification manual | Abaqus 2025 Verification Guide, `UEL` | Dassault Systemes SIMULIA | https://docs.software.vt.edu/abaqusv2025/English/SIMACAEVERRefMap/simaver-c-uel.htm | 2026-06-11 | Tier 1 | Used for verification pattern: compare a user element model against an equivalent native element model and perform extensive checks. |
-
-## Source-Backed Facts
-
-| fact_id | source | fact | downstream relevance |
-| --- | --- | --- | --- |
-| F-ABAQUS-UEL-001 | S1 | `UEL` is called for each element of a general user-defined element type when element calculations are required. The subroutine interface includes `RHS`, `AMATRX`, `SVARS`, `ENERGY`, `NDOFEL`, `NRHS`, `NSVARS`, `PROPS`, `NPROPS`, `COORDS`, `MCRD`, `NNODE`, `U`, `DU`, `V`, `A`, `JTYPE`, `TIME`, `DTIME`, `LFLAGS`, `MLVARX`, `PNEWDT`, `JPROPS`, `NJPROP`, and `PERIOD`. | I/O Definition Agent must preserve the Abaqus ABI signature and argument meanings. |
-| F-ABAQUS-UEL-002 | S1 | `RHS` contains the element contribution to right-hand-side vectors. For most nonlinear procedures with `NRHS=1`, `RHS` contains the residual vector, described as external forces minus internal forces. | Static residual sign convention must be resolved explicitly before implementation. |
-| F-ABAQUS-UEL-003 | S1 | `AMATRX` contains the element contribution to the Jacobian, stiffness, or other matrix requested by `LFLAGS`. Nonzero entries should be defined even for symmetric matrices. | Beam kernel can form a full 12-by-12 matrix; interface must decide whether `UNSYMM` is unnecessary for the symmetric linear beam. |
-| F-ABAQUS-UEL-004 | S1 | `SVARS` contains user-defined solution-dependent state variables. For general nonlinear steps it is passed in at the start of the increment and normally returned at the end of the increment; for `KINC=0` it is output-only. | First static elastic beam does not need state variables, but any diagnostic section forces must be treated as `SVARS` if output is required. |
-| F-ABAQUS-UEL-005 | S1 | `ENERGY` has eight element energy slots, including kinetic energy, elastic strain energy, artificial strain energy, and incremental work done by loads applied within the user element. | First implementation may leave energy out only if the interface contract states that no element energy output is required. |
-| F-ABAQUS-UEL-006 | S1 | `PROPS` contains user-defined real property values and `JPROPS` contains user-defined integer property values. `NPROPS` and `NJPROP` are their counts. | `E`, `G`, `A`, `Iy`, `Iz`, `J`, and orientation data need an explicit property mapping in the interface gate. |
-| F-ABAQUS-UEL-007 | S1 | `COORDS(K1,K2)` contains the original coordinates of node `K2`; `MCRD` is the coordinate dimension available for each node; `NNODE` is the user-defined number of nodes. | This feature requires `NNODE=2` and three coordinates per node for 3D geometry. |
-| F-ABAQUS-UEL-008 | S1 | `U` contains total current estimates of nodal variables at the end of the increment; `DU` contains incremental values for the current increment and RHS column. `V` and `A` are defined for implicit dynamics only. | First static implementation should use `U` for the total displacement/rotation vector and not depend on `V` or `A`. |
-| F-ABAQUS-UEL-009 | S1 | `LFLAGS(2)=0` identifies small-displacement analysis and `LFLAGS(2)=1` identifies large-displacement analysis. `LFLAGS(3)=1` requests both residual and Jacobian, `2` requests stiffness only, `5` requests residual or load vector only, and other values request mass, damping, or perturbation quantities. | First scope should accept small-displacement static paths and explicitly reject or ignore out-of-scope mass, damping, and large-displacement requests. |
-| F-ABAQUS-UEL-010 | S1 | For static analysis procedure values, Abaqus/Standard requires `AMATRX` and `RHS` and applies convergence checks to force residuals for mechanical DOFs. | `RHS` and `AMATRX` are mandatory for first static benchmark comparisons. |
-| F-ABAQUS-UEL-011 | S1 | UEL solution variables are arranged by node and degree of freedom, with all DOFs for the first node followed by all DOFs for the second node. | This supports the requirement DOF order: node 1 `U1,U2,U3,UR1,UR2,UR3`, then node 2. |
-| F-ABAQUS-UEL-012 | S2 | Abaqus always works in the global system when passing information to and from a user element; user element stiffness, mass, and related matrices should be defined with respect to global directions at nodes. | The beam local stiffness must be transformed to global coordinates before assigning `AMATRX` and `RHS`. |
-| F-ABAQUS-UEL-013 | S2, S3 | A general user element is introduced with `*USER ELEMENT`, including `TYPE=Un`, `NODES=n`, optional `COORDINATES`, `PROPERTIES`, `I PROPERTIES`, `VARIABLES`, and `UNSYMM`. Active DOFs are specified on data lines. | Interface gate must define the exact `*USER ELEMENT` keyword subset and active DOF lines. |
-| F-ABAQUS-UEL-014 | S2, S3 | For general user elements, real property count and integer property count are declared on `*USER ELEMENT`, and property values are provided through `*UEL PROPERTY`; real values precede integer values on data lines. | `PROPS` and `JPROPS` ordering must be documented and tested. |
-| F-ABAQUS-UEL-015 | S4 | `*UEL PROPERTY` requires `ELSET` and can carry property values. Its `ORIENTATION` parameter exists for Abaqus/Standard and names a local coordinate system for material calculations. | Do not assume `ORIENTATION` is directly available in plain `UEL` arguments; I/O Definition Agent must verify whether orientation is encoded through properties, extra nodes, or another approved mechanism. |
-| F-ABAQUS-UEL-016 | S5 | Abaqus DOFs 1, 2, and 3 are x-, y-, and z-displacement; DOFs 4, 5, and 6 are rotations about x-, y-, and z-axes in radians. Abaqus uses self-consistent units and has no built-in mechanical unit system. | Supports 6-DOF-per-node contract and user-consistent unit requirements. |
-| F-ABAQUS-UEL-017 | S6 | Abaqus beam cross-section orientation uses a local right-handed `t, n1, n2` system; `t` is tangent from first to second node, and `n1` and `n2` define section axes. | UEL local frame should use the same first-to-second-node axis convention unless interface work chooses a documented alternative. |
-| F-ABAQUS-UEL-018 | S6 | For 3D beams, an approximate `n1` direction can be defined directly or by an additional off-axis node; the additional node takes precedence; if neither is supplied, the default is `(0,0,-1)`. The actual section axes are orthogonalized after a normal direction is determined. | UEL orientation reference must reject parallel or near-parallel references and must not silently rely on an ambiguous default for validation models. |
-| F-ABAQUS-UEL-019 | S2 | User-defined element output is limited: general user element stress, strain, or other internal quantities must be stored as solution-dependent state variables, and element output to ODB is not generally supported for user-defined elements. | External CSV comparison should initially focus on nodal `U` and `RF`; element section-force comparison requires an explicit `SVARS` output strategy. |
-| F-BEAM-001 | S7 | Euler-Bernoulli beam theory assumes plane cross-sections normal to the longitudinal centroidal axis before bending remain plane and normal after bending under small rotations. | Confirms exclusion of Timoshenko shear deformation in first implementation. |
-| F-BEAM-002 | S7 | A two-node Euler-Bernoulli bending element uses cubic Hermite interpolation for transverse displacement and nodal rotation. | No-Abaqus bending tests can compare against closed-form cubic-displacement beam cases. |
-| F-BEAM-003 | S7 | The 2D Euler-Bernoulli bending stiffness block for transverse displacement and rotation has the familiar `12EI/L^3`, `6EI/L^2`, `4EI/L`, and `2EI/L` terms. | Supplies bending subblocks for both local section axes. |
-| F-BEAM-004 | S7 | The torsional stiffness for a prismatic bar is proportional to `GJ/L`; axial stiffness is proportional to `EA/L`. | Supplies axial and torsional subblocks. |
-| F-BEAM-005 | S7 | A 3D space-frame beam stiffness is obtained by superposing axial, torsion, bending about local `y`, and bending about local `z` submatrices. | Supports the first-scope `E`, `G`, `A`, `Iy`, `Iz`, `J` property set. |
-| F-BEAM-006 | S7 | A 3D frame element is transformed between local and global coordinates using a block-diagonal transformation matrix built from a 3-by-3 direction-cosine matrix. | Required for global `AMATRX` and `RHS`. |
-| F-BEAM-007 | S7 | When the beam local axis aligns with a global axis used to construct the remaining local axes, special orientation cases can make the frame construction singular or ambiguous. | Orientation negative tests must cover near-parallel reference vectors and axis-aligned elements. |
-| F-VERIFY-001 | S8 | Abaqus UEL verification examples compare equivalent native-element and user-element meshes; the guide warns that extensive verification is needed for UEL use. | External Abaqus validation should include comparison against an equivalent Abaqus native beam model where the physics and keyword support match. |
-
-## Local 3D Beam Stiffness Evidence
-
-The following matrix is recorded as source-backed research evidence from S7, not as the final formulation contract. The Formulation Agent must confirm signs, axis labels, and transform convention before implementation.
-
-Local DOF order:
-
-```text
-[u1, v1, w1, rx1, ry1, rz1, u2, v2, w2, rx2, ry2, rz2]
-```
-
-Standard 3D Euler-Bernoulli frame stiffness terms:
-
-```text
-a  = E*A/L
-t  = G*J/L
-by = E*Iy
-bz = E*Iz
-
-k_local =
-[
- [ a,        0,         0,    0,          0,          0, -a,        0,         0,    0,          0,          0],
- [ 0,  12*bz/L^3,       0,    0,          0,   6*bz/L^2,  0, -12*bz/L^3,       0,    0,          0,   6*bz/L^2],
- [ 0,        0,  12*by/L^3,   0,  -6*by/L^2,        0,  0,        0, -12*by/L^3,   0,  -6*by/L^2,        0],
- [ 0,        0,         0,    t,          0,          0,  0,        0,         0,   -t,          0,          0],
- [ 0,        0,  -6*by/L^2,   0,    4*by/L,          0,  0,        0,   6*by/L^2,   0,    2*by/L,          0],
- [ 0,   6*bz/L^2,       0,    0,          0,    4*bz/L,  0,  -6*bz/L^2,       0,    0,          0,    2*bz/L],
- [-a,        0,         0,    0,          0,          0,  a,        0,         0,    0,          0,          0],
- [ 0, -12*bz/L^3,       0,    0,          0,  -6*bz/L^2, 0,  12*bz/L^3,       0,    0,          0,  -6*bz/L^2],
- [ 0,        0, -12*by/L^3,   0,   6*by/L^2,        0,  0,        0,  12*by/L^3,   0,   6*by/L^2,        0],
- [ 0,        0,         0,   -t,          0,          0,  0,        0,         0,    t,          0,          0],
- [ 0,        0,  -6*by/L^2,   0,    2*by/L,          0,  0,        0,   6*by/L^2,   0,    4*by/L,          0],
- [ 0,   6*bz/L^2,       0,    0,          0,    2*bz/L,  0,  -6*bz/L^2,       0,    0,          0,    4*bz/L]
-]
-```
-
-Verification notes for this evidence:
- The matrix is symmetric for the linear elastic first scope.
- The axial, torsion, local-`y` bending, and local-`z` bending subblocks can be tested independently by selecting displacement vectors that activate one physical mode at a time.
- The final document must define whether the project labels `Iy` and `Iz` exactly as S7's local `y` and `z` axes or maps them to Abaqus-style `n1` and `n2` section axes.
-
-## Inferences From Facts
-
-| inference_id | basis | inference | required downstream check |
-| --- | --- | --- | --- |
-| I-UEL-001 | F-ABAQUS-UEL-002, F-ABAQUS-UEL-012 | For the first static linear beam with no distributed loads generated inside `UEL`, externally applied nodal loads are handled by Abaqus outside the subroutine; therefore the element `RHS` contribution should likely be `-K_global * U` under the residual definition external minus internal. | I/O Definition Agent must confirm with the Abaqus `UEL` residual convention and no-Abaqus sign tests. |
-| I-UEL-002 | F-ABAQUS-UEL-003, F-BEAM-005, F-BEAM-006 | `AMATRX` should be the global 12-by-12 stiffness matrix `T^T k_local T` or the equivalent convention selected by the Formulation Agent, not the raw local matrix. | Formulation Agent must define the transform direction and test identity, rotated, and axis-aligned elements. |
-| I-UEL-003 | F-ABAQUS-UEL-009, F-ABAQUS-UEL-010 | First implementation should respond to `LFLAGS(3)=1`, `2`, and `5` for static use and treat mass/damping request values as out of scope. | Interface contract must define exact behavior for unsupported `LFLAGS` values, including whether to report an error or return zero contribution. |
-| I-UEL-004 | F-ABAQUS-UEL-006, F-ABAQUS-UEL-014, F-ABAQUS-UEL-015 | Orientation should be encoded explicitly in project-controlled properties or extra geometry data unless the interface gate proves that a named `*ORIENTATION` is available to plain `UEL` in a usable form. | I/O Definition Agent must choose and document one orientation path. |
-| I-UEL-005 | F-ABAQUS-UEL-019 | External Abaqus CSV comparison should start with nodal displacements and reactions. Element force or section-force CSV comparison should wait until the interface defines `SVARS` output or another explicit extraction route. | Reference Model Agent must separate initial nodal comparison from optional element-output comparison. |
-| I-BEAM-001 | F-BEAM-001, F-BEAM-002, F-BEAM-003 | Cantilever tip-load cases are strong no-Abaqus checks because Euler-Bernoulli cubic displacement fields reproduce nodal displacement and rotation exactly for nodal end loads. | Reference Model Agent should include at least one end-load cantilever bending case about each local bending axis. |
-| I-BEAM-002 | F-BEAM-004, F-BEAM-005 | Pure axial and pure torsion tests can isolate `EA/L` and `GJ/L` terms and catch property-ordering mistakes. | Reference Model Agent should include axial extension and torsion-only single-element tests. |
-| I-BEAM-003 | F-BEAM-006, F-BEAM-007, F-ABAQUS-UEL-018 | A robust orientation algorithm should reject element length near zero and orientation references nearly parallel to the element axis rather than silently normalizing an ill-conditioned cross product. | Numerical Review Agent should set numerical thresholds and negative tests. |
-
-## Applicability Limits
-
- linear_or_nonlinear: first implementation is linear static small-displacement only.
- deformation: small displacement and small rotation formulation only; Abaqus finite rotation update behavior is out of scope.
- element_type: two-node 3D beam/frame user element with 6 mechanical DOFs per node.
- material_model: linear elastic section stiffness only; no plasticity, damage, thermal strain, creep, viscoelasticity, or user material library coupling.
- geometry: initially straight prismatic member between two distinct nodes.
- beam_theory: Euler-Bernoulli bending only; shear deformation and shear correction factors are out of scope.
- torsion: Saint-Venant torsion represented by `GJ/L`; warping torsion and open-section warping DOF 7 are out of scope.
- loads: external nodal forces and moments may be applied by Abaqus; distributed load generation inside `UEL` is out of scope for first implementation.
- mass_damping: mass, inertia, rotary inertia, Rayleigh damping, and structural damping are out of scope.
- coordinate_system: `AMATRX` and `RHS` must be in global nodal DOF coordinates; local beam axes are an internal calculation frame.
- units: Abaqus does not enforce a unit system; all properties and CSV evidence must use self-consistent declared units.
- output: ODB element output for user elements is limited; first external comparison should rely on nodal displacement and reaction CSVs.
- source_limit: public example repositories, forums, and blogs were not used as acceptance evidence for this research step.
-
-## Candidate Benchmarks
-
-| benchmark_id | source | benchmark_type | physics | target_quantities | artifact_needs | applicability |
-| --- | --- | --- | --- | --- | --- | --- |
-| BM-NOA-AXIAL-001 | S7 | analytical no-Abaqus | axial extension/compression of a two-node member | local/global stiffness entries, end forces, `EA/L` response | no-Abaqus driver expected values | Isolates `E`, `A`, length, and DOF ordering. |
-| BM-NOA-TORSION-001 | S7 | analytical no-Abaqus | torsion about local beam axis | torsional stiffness entries, end torques, `GJ/L` response | no-Abaqus driver expected values | Isolates `G`, `J`, and rotational DOFs `UR1`. |
-| BM-NOA-BEND-Y-001 | S7 | analytical no-Abaqus | bending in local `x-z` plane about local `y` axis | stiffness terms using `Iy`, tip displacement, tip rotation, local end moments | no-Abaqus driver expected values | Catches `Iy` sign and axis mapping errors. |
-| BM-NOA-BEND-Z-001 | S7 | analytical no-Abaqus | bending in local `x-y` plane about local `z` axis | stiffness terms using `Iz`, tip displacement, tip rotation, local end moments | no-Abaqus driver expected values | Catches `Iz` sign and axis mapping errors. |
-| BM-NOA-RBM-001 | S7 | no-Abaqus matrix property | unconstrained element rigid-body modes | six near-zero eigenvalues or residual under rigid translations/rotations, matrix symmetry | no-Abaqus linear algebra check | Detects stiffness assembly and coupling mistakes. |
-| BM-NOA-ROT-001 | S6, S7 | no-Abaqus transformation | arbitrarily oriented 3D beam with nonparallel orientation reference | `T` orthonormality, `K_global=T^T k_local T`, transformed residual consistency | no-Abaqus driver expected matrix | Verifies local-to-global transformation and orientation edge cases. |
-| BM-NOA-RHS-001 | S1, S2 | no-Abaqus residual check | linear static residual under prescribed displacement vector | `RHS` sign and equality to chosen residual convention | no-Abaqus sign-convention check | Must be RED before implementation if `RHS` is not implemented. |
-| BM-EXT-UEL-B31-001 | S8 plus approved input deck | external Abaqus comparison | straight cantilever UEL versus equivalent native beam model | nodal `U`, support `RF`, convergence status, log tails | `model.inp`, ODB-extracted nodal CSVs, `.msg/.dat/.log/.sta` tails, metadata | Valid only after user runs Abaqus externally and provides artifacts. |
-| BM-EXT-UEL-ROT-001 | S6, S8 plus approved input deck | external Abaqus comparison | rotated straight beam with explicit orientation reference | nodal `U`, support `RF`, coordinate labels, units | same external artifact bundle as above | Validates Abaqus-facing orientation and global DOF mapping. |
-
-## Verification Relevance
-
- code_verification: no-Abaqus matrix, residual, rigid-body, and transformation checks can verify the element kernel before any production Fortran source changes.
- solution_verification: external Abaqus reference bundles can compare the implemented `UEL` against native beam behavior and analytical expectations, but only after user-generated artifacts are registered.
- validation: no physical experiment is part of this first scope; this is verification of a linear elastic element formulation, not validation of a real beam test.
- reference_comparison: first comparison should use ODB-extracted nodal displacement and reaction CSV files with explicit units and coordinate labels.
-
-## Open Issues
-
- `RHS` sign convention should be treated as evidence-backed but not final until the interface contract defines the exact residual sign and no-Abaqus sign test.
- The final orientation input path is unresolved. Options include real properties, integer flags plus real vector values, additional nodes, or an approved Abaqus keyword mechanism if it is actually visible to plain `UEL`.
- `Iy` and `Iz` mapping must be tied to project local axes and not assumed from textbook notation alone.
- Whether `ENERGY(2)` should be populated for linear static elastic strain energy is unresolved and belongs to the interface/formulation gates.
- Whether any element-level section forces should be stored in `SVARS` for CSV extraction is unresolved. Initial comparison can proceed with nodal `U` and `RF`.
- External benchmark input decks and CSV filenames are not approved in this step.
-
-## Downstream Handoff
-
-### Formulation Agent
- Use S7 as the primary mathematical source for local 3D beam stiffness, but independently verify sign convention and axis labels for the project DOF order.
- Define the local frame construction from node coordinates and orientation reference, including zero-length and near-parallel thresholds.
- Define `K_global`, `RHS`, rigid-body modes, and scale-aware matrix checks without adding shear deformation or nonlinear geometry.
-
-### Numerical Review Agent
- Review local stiffness symmetry, rank, six rigid-body modes, conditioning for short/long elements, and orientation singularities.
- Review whether Euler-Bernoulli assumptions are acceptable for the candidate benchmark dimensions.
- Review tolerance scaling for stiffness entries with different units: force/length, moment/radian, and force/radian coupling terms.
-
-### I/O Definition Agent
- Define `*USER ELEMENT` and `*UEL PROPERTY` keyword subset, including `TYPE`, `NODES=2`, active DOFs `1,2,3,4,5,6`, `COORDINATES`, `PROPERTIES`, `I PROPERTIES`, `VARIABLES`, and `UNSYMM`.
- Define `PROPS`/`JPROPS` ordering for `E`, `G`, `A`, `Iy`, `Iz`, `J`, and orientation.
- Define behavior for unsupported `LFLAGS` requests and invalid properties.
- Define whether `SVARS` and `ENERGY` are unused, zeroed, or populated in first scope.
-
-### Reference Model Agent
- Include no-Abaqus axial, torsion, two bending, rigid-body, transformation, and residual sign checks before implementation.
- Design external Abaqus comparison against native beam behavior only after an approved input deck and artifact contract exist.
- Keep ODB extraction external and require `metadata.json`, `model.inp`, extracted CSVs, and `.msg/.dat/.log/.sta` tail files.
-
-### Implementation Planning Agent
- Do not write production Fortran until no-Abaqus RED evidence exists.
- Plan a thin Abaqus `UEL` wrapper around a testable local/global beam stiffness and residual kernel.
- Keep public example repositories out of acceptance evidence unless license, version, provenance, and generated artifacts are documented later.
@@ -0,0 +1,196 @@
+# Project Guidance Refresh Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Align project guidance, custom agents, and existing skills with mandatory FEM-vault routing, indexed local Abaqus manual lookup, external user-provided CSV verification, and removal of retired feature artifacts.
+
+**Architecture:** Keep the current seven-gate workflow and external CSV artifact model. Add one shared source-routing contract to core guidance, then place concise role-specific instructions only where an agent or skill directly consumes FEM theory or Abaqus manual facts. Remove retired feature files without changing generic user-subroutine or numerical-integration documentation.
+
+**Tech Stack:** Markdown, TOML custom-agent definitions, Codex `SKILL.md`, Python unittest fixture text, Git
+
+**Spec:** `docs/superpowers/specs/2026-08-18-project-guidance-refresh-design.md`
+
+## Global Constraints
+
+- Do not run harness skills, Python tests, Fortran tests, workspace validation, Abaqus jobs, or ODB parsing.
+- Preserve all pre-existing user changes, including current deletions, manual files, `.codex/config.toml`, and `fem-theory-query/vault-path.txt`.
+- Treat user-provided displacement, stress, and feature-specific CSV files plus provenance metadata as solver-result verification inputs.
+- Use `fem-theory-query` for FEM theory, formulation, solver behavior, benchmark, and numerical-verification knowledge.
+- Use `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`, then `INDEX.md`, then every selected `source_ranges` span for Abaqus User Subroutine manual facts.
+- Keep `INDEX.md` summaries as retrieval metadata; use source spans as authoritative evidence.
+- Verify documentation changes with read-only/static checks only.
+
+---
+
+### Task 1: Core Project Guidance
+
+**Files:**
+- Modify: `AGENTS.md`
+- Modify: `docs/PRD.md`
+- Modify: `docs/ARCHITECTURE.md`
+- Modify: `docs/ADR.md`
+- Modify: `docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md`
+- Modify: `docs/research/README.md`
+
+**Interfaces:**
+- Consumes: approved design and existing external CSV artifact contract
+- Produces: one authoritative source-routing policy inherited by all custom agents and skills
+
+- [x] **Step 1: Add the shared source-routing contract to `AGENTS.md`**
+
+State three routes explicitly: FEM theory through `fem-theory-query`; Abaqus manual facts through `INDEX_MAP.md` → `INDEX.md` → every selected source span; solver results through user-provided external CSV and provenance artifacts.
+
+- [x] **Step 2: Remove misleading workflow wording in `AGENTS.md`**
+
+Restore step 5 to TDD no-Abaqus test/reference model design without making harness skills mandatory, restore literal `<feature-id>` and `RED -> GREEN -> VERIFY`, and retain external CSV comparison as the sole solver-result path.
+
+- [x] **Step 3: Align PRD and architecture**
+
+Add the source-routing requirements, add `docs/AbaqusUserSubroutineManual/` to the repository map, and clarify that agents must not infer ABI facts from generated index summaries.
+
+- [x] **Step 4: Record the source-routing decision**
+
+Add a new ADR that separates FEM theory evidence, local Abaqus manual evidence, and external CSV result evidence without rewriting historical ADR decisions.
+
+- [x] **Step 5: Align agent design and research guidance**
+
+Add `fem-theory-query` to every process row that directly consumes FEM knowledge, and add the local manual index protocol to the Research Agent source policy.
+
+- [x] **Step 6: Static review Task 1**
+
+Read all six files and confirm the three evidence routes have no contradictory wording. Do not execute test commands.
+
+### Task 2: Custom Agent Source Routing
+
+**Files:**
+- Modify: `.codex/agents/research-agent.toml`
+- Modify: `.codex/agents/formulation-agent.toml`
+- Modify: `.codex/agents/numerical-review-agent.toml`
+- Modify: `.codex/agents/io-definition-agent.toml`
+- Modify: `.codex/agents/implementation-planning-agent.toml`
+- Modify: `.codex/agents/reference-model-agent.toml`
+- Modify: `.codex/agents/physics-evaluation-agent.toml`
+
+**Interfaces:**
+- Consumes: shared source-routing policy from Task 1
+- Produces: role-specific mandatory source selection without duplicating the full global policy
+
+- [x] **Step 1: Update research and interface agents**
+
+Require the Research Agent and I/O Definition Agent to locate Abaqus manual sections through `INDEX_MAP.md`, inspect the complete `INDEX.md` record, and read all source ranges before making ABI or product-support claims.
+
+- [x] **Step 2: Strengthen FEM routing for theory-owning agents**
+
+Change the existing `fem-theory-query` references from optional wording to mandatory wording when Formulation, Numerical Review, Implementation Planning, Reference Model, or Physics Evaluation work needs FEM knowledge.
+
+- [x] **Step 3: Preserve role boundaries**
+
+Confirm none of the seven agents gains code implementation, Abaqus execution, reference CSV generation, or readiness-approval authority.
+
+- [x] **Step 4: Static TOML review**
+
+Re-read the edited TOML strings and confirm balanced triple quotes and unchanged `model_reasoning_effort = "extra high"` values.
+
+### Task 3: Existing Skill Source Routing
+
+**Files:**
+- Modify: `.codex/skills/abaqus-subroutine-research/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-formulation/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-numerical-review/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-interface/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-test-models/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-physics-sanity/SKILL.md`
+- Modify: `.codex/skills/abaqus-fortran-tdd/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-readiness/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-requirements/SKILL.md`
+- Modify: `.codex/skills/abaqus-subroutine-validation/SKILL.md`
+- Inspect only: corresponding `.codex/skills/*/agents/openai.yaml`
+
+**Interfaces:**
+- Consumes: existing `fem-theory-query` skill and local manual index files
+- Produces: concise imperative instructions within existing project skills; no new skill package
+
+- [x] **Step 1: Add manual lookup to research and interface skills**
+
+Add `INDEX_MAP.md` and `INDEX.md` to required inputs. Require selection by symbol/section/keyword, reading the complete record, then reading every source span in order. State that summaries are non-authoritative.
+
+- [x] **Step 2: Add required FEM sub-skill markers**
+
+Use the exact marker `**REQUIRED SUB-SKILL:** Use fem-theory-query` in skills that directly perform formulation, numerical review, benchmark/test-model design, or physics interpretation.
+
+- [x] **Step 3: Remove dangling README prerequisites**
+
+Remove `Read first` entries for general `docs/*/README.md` files already deleted in the user working tree. Keep feature-specific output contracts so future work can create those directories and documents when needed.
+
+- [x] **Step 4: Keep skill metadata stable**
+
+Do not change frontmatter descriptions or `agents/openai.yaml` unless the trigger meaning changes. Confirm names remain lowercase hyphen-case and frontmatter contains only `name` and `description`.
+
+- [x] **Step 5: Static skill review**
+
+Check imperative wording, source-routing consistency, lack of duplicated long explanations, and unchanged no-Abaqus/external CSV boundaries. Per user instruction, do not run skill tests, forward-tests, or validation scripts.
+
+### Task 4: Remove Retired Feature Content
+
+**Files:**
+- Delete: the remaining supplemental research brief for the retired feature
+- Delete: the remaining feature-specific research brief
+- Delete: the remaining feature-specific wrapper contract test
+- Modify: `scripts/test_validate_fortran.py`
+- Preserve: `docs/AbaqusUserSubroutineManual/**`
+
+**Interfaces:**
+- Consumes: current user deletions of the retired feature
+- Produces: no remaining versioned retired-feature names or content
+
+- [x] **Step 1: Delete the remaining feature-specific files**
+
+Remove only the three inventoried feature-specific files. Do not delete generic user-subroutine documentation, the local Abaqus manual, or unrelated research guidance.
+
+- [x] **Step 2: Neutralize the generic validator fixture**
+
+In `test_manifest_build_commands_create_test_build_directories`, replace the retired feature test name and source paths with `sample_kernel_stiffness`, `src/fortran/sample_kernel.f90`, and `tests/fortran/test_sample_kernel.f90`; update the expected build directory accordingly. Do not change validator behavior.
+
+- [x] **Step 3: Search versioned content**
+
+Search tracked files for the retired feature identifiers and project-specific variants. Ignore generic numerical integration terminology and generic user-subroutine entry point documentation in the official manual.
+
+### Task 5: Static Verification and Handoff
+
+**Files:**
+- Modify: `PLAN.md`
+- Modify: `PROGRESS.md`
+- Modify if a reusable pitfall was found: `WORKNOTE.md`
+- Inspect: all changed and deleted paths
+
+**Interfaces:**
+- Consumes: Tasks 1–4
+- Produces: evidence-backed documentation handoff and one conventional commit
+
+- [x] **Step 1: Run allowed static checks**
+
+Run only read-only/static commands equivalent to:
+
+```powershell
+git diff --check
+git diff --stat
+git status --short
+```
+
+Use text search to confirm manual routing, FEM routing, external CSV verification, and removal of retired feature references.
+
+- [x] **Step 2: Re-read changed guidance**
+
+Confirm `AGENTS.md`, core docs, agent TOML, and skill Markdown agree on the evidence routes and role boundaries.
+
+- [x] **Step 3: Update shared state**
+
+Record completed work, exact static checks, skipped tests, and the next action in `PROGRESS.md`. Add to `WORKNOTE.md` only if a reusable repository-specific pitfall arose.
+
+- [ ] **Step 4: Commit without invoking test hooks**
+
+Stage only task-owned changes plus the user's already-requested retired-feature cleanup that belongs to this objective. Commit with a conventional `docs:` message and `--no-verify` because the user explicitly prohibited test execution. Do not include unrelated `.codex/config.toml` or `vault-path.txt` changes unless they were already independently requested and are intentionally part of the user's working tree.
+
+- [ ] **Step 5: Push the completed commit**
+
+Push the current `dev` branch to its configured upstream after confirming the commit contains no unrelated files.
@@ -6,9 +6,9 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다

 1. 유한요소 이론과 solver 지식은 `fem-theory-query`를 통해 조사한다.
 2. Abaqus User Subroutine ABI와 매뉴얼 사실은 로컬 매뉴얼 index를 통해 찾는다.
-3. 과거 `uel-3d-euler-beam` 기능에 종속된 산출물과 잔존 참조를 제거한다.
+3. 사용자가 폐기한 과거 feature에 종속된 산출물과 잔존 참조를 제거한다.

-`abaverify`는 도입하지 않는다. Abaqus 해석은 사용자가 다른 PC에서 수행하고, 이 저장소는 사용자가 첨부한 변위·응력 CSV와 provenance artifact를 schema/tolerance 기준으로 비교한다.
+Abaqus 해석은 사용자가 다른 PC에서 수행하고, 이 저장소는 사용자가 첨부한 변위·응력 CSV와 provenance artifact를 schema/tolerance 기준으로 비교한다.

 ## Source Routing

@@ -29,7 +29,6 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다
 - Abaqus job과 ODB-to-CSV 추출은 사용자가 다른 Abaqus PC에서 수행한다.
 - 사용자는 변위, 응력 또는 feature contract에서 지정한 결과 CSV와 provenance metadata를 제공한다.
 - 이 저장소는 ODB를 직접 파싱하지 않고 CSV schema, matching key, unit, coordinate system, tolerance를 비교한다.
- `abaverify` 관련 agent, skill, command, artifact contract는 추가하지 않는다.

 ## 변경 범위

@@ -46,16 +45,16 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다

 새 매뉴얼 전용 skill은 만들지 않는다. 전역 `AGENTS.md` 규칙과 기존 research/interface skill에 index 탐색 절차를 추가하는 것이 더 단순하며 중복을 줄인다.

-## Euler Beam 제거 범위
+## 과거 Feature 제거 범위

 이미 삭제된 사용자 변경을 보존하고, 남아 있는 versioned project-specific 항목을 제거한다.

- `docs/abaqus-uel-subroutines-research.md`
- `docs/research/uel-3d-euler-beam-research.md`
- `scripts/test_uel_3d_euler_beam_uel.py`
- `scripts/test_validate_fortran.py`에 남은 Euler beam 전용 fixture 이름과 경로
+- 과거 feature 전용 supplemental research brief
+- 과거 feature 전용 research brief
+- 과거 feature wrapper contract test
+- `scripts/test_validate_fortran.py`에 남은 feature 전용 fixture 이름과 경로

-공식 매뉴얼의 backward Euler 문구와 generic `UEL` entry point 설명은 과거 feature 산출물이 아니므로 유지한다.
+공식 매뉴얼의 수치 적분 용어와 generic user-subroutine entry point 설명은 과거 feature 산출물이 아니므로 유지한다.

 ## 범위 제외

@@ -64,23 +63,21 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다
 - Python, Fortran, workspace test 실행
 - Abaqus job 실행 또는 ODB 직접 parsing
 - CSV validator 구현 변경
- `abaverify` 도입

 ## 정적 검증

 테스트 대신 다음 문서 검사를 수행한다.

 1. 변경 파일을 재독해 source routing과 verification 계약의 충돌을 확인한다.
-2. versioned 파일에서 `uel-3d-euler-beam`, `uel_3d_euler_beam`, `3D Euler-Bernoulli` 잔존 참조를 검색한다.
-3. 매뉴얼을 제외한 project guidance에서 `abaverify`가 남지 않았는지 확인한다.
-4. 변경된 skill frontmatter와 `agents/openai.yaml`의 의미가 일치하는지 확인한다.
-5. `git diff --check`와 diff 검토만 수행한다.
+2. versioned 파일에서 폐기된 feature의 식별자와 전용 설명이 남지 않았는지 검색한다.
+3. 변경된 skill frontmatter와 `agents/openai.yaml`의 의미가 일치하는지 확인한다.
+4. `git diff --check`와 diff 검토만 수행한다.

 ## 성공 기준

 - FEM 관련 지식 탐색이 `fem-theory-query`로 명시된다.
 - Abaqus 매뉴얼 사용 순서가 `INDEX_MAP.md` → `INDEX.md` → 모든 `source_ranges`로 명시된다.
 - 외부 Abaqus PC에서 생성한 변위·응력 CSV 비교가 유일한 solver-result verification 경로로 유지된다.
- project-specific Euler beam 파일과 versioned 참조가 남지 않는다.
+- 폐기된 project-specific feature 파일과 versioned 참조가 남지 않는다.
 - 기존 사용자 변경을 되돌리지 않는다.
 - Harness skill과 테스트를 실행하지 않는다.