# Architecture: Abaqus User Subroutine Development

## 목표
이 저장소는 Abaqus User Subroutine 개발을 위한 agent-driven workflow와 검증 체계를 제공한다. 핵심 아키텍처는 단계별 specialist agent, gate 문서, no-Abaqus Fortran TDD, 외부 생성 ODB 추출 CSV validation, reference artifact metadata validation으로 구성된다.

## 주요 원칙
- Abaqus User Subroutine 개발이 프로젝트의 중심이다.
- Fortran source는 Abaqus ABI wrapper와 testable kernel/driver logic을 가능한 한 분리한다.
- 기본 검증은 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 산출물을 섞지 않는다.

## 디렉토리 구조
```text
.codex/
├── agents/             # Abaqus User Subroutine specialist agent definitions
├── 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
├── numerical-reviews/  # Independent numerical reviews
├── io-definitions/     # Abaqus ABI and CSV schema contracts
├── reference-models/   # TDD model and reference artifact plans
├── implementation-plans/
├── build-test-reports/
├── reference-verifications/
├── physics-evaluations/
└── releases/
scripts/
├── execute.py
├── fortran_toolchain.py
├── validate_fortran.py
├── validate_reference_artifacts.py
├── validate_workspace.py
└── test_*.py
tests/
└── fortran/manifest.json       # Optional no-Abaqus Fortran test manifest
references/
└── <feature-id>/<model-id>/    # External Abaqus result artifacts for CSV comparison
phases/
└── <phase-id>/                 # Optional staged execution plans
```

## Gate 흐름
```text
User request
-> Requirement gate
-> Research gate
-> Formulation gate
-> Numerical review gate
-> Interface gate
-> Test model gate
-> Implementation planning gate
-> RED -> GREEN -> VERIFY Fortran implementation
-> Build/test evidence
-> Reference verification
-> Physics sanity
-> Readiness audit
```

각 gate는 다음 gate가 사용할 수 있는 explicit handoff를 남긴다. Blocking issue는 downstream에서 임의 해결하지 않고 owning upstream gate로 되돌린다.

## Agent / Skill 구조
- `docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md`는 7단계 개발 프로세스와 agent/skill mapping의 기준 문서다.
- Agent definitions는 `.codex/agents/*.toml`에 있고, 각 agent는 자신의 hard boundary를 가진다.
- 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
-> related no-Abaqus test must exist or be added first
-> RED: targeted test fails for the expected reason
-> GREEN: minimum Fortran code change
-> VERIFY:
   python scripts/validate_fortran.py
   python scripts/validate_reference_artifacts.py
   python scripts/validate_workspace.py
```

`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을 따른다.
- UMAT family는 stress, state variable, `DDSDDE`, time/increment, material constants, tensor ordering을 interface contract에 명시해야 한다.
- VUMAT family는 `nblock` vector loop, old/new arrays, corotational quantity, energy/state update responsibility를 명시해야 한다.
- UEL family는 `RHS`, `AMATRX`, `SVARS`, `ENERGY`, DOF layout, `LFLAGS` requested contribution을 명시해야 한다.

## Reference Artifact 구조
```text
references/<feature-id>/<model-id>/
├── metadata.json
├── model.inp
├── job.msg.tail.txt
├── job.dat.tail.txt
├── job.log.tail.txt
├── job.sta.tail.txt
├── result.odb.sha256           # Optional when ODB cannot or should not be stored
├── extraction/
│   └── extract_odb_to_csv.py    # Optional provenance copy of user-run extraction script
└── extracted/
    └── *.csv
```

`metadata.json` schema version은 `abaqus-user-subroutine-artifact-v1`이다. `artifact_status=ready-for-comparison`인 artifact는 Abaqus version, precision, compiler vendor/name/version, entry points, source file hashes, input file, output tails, ODB extraction provenance, declared CSV files를 모두 가져야 한다.

수치 검증은 ODB 직접 parsing이 아니라 `extracted/*.csv`의 schema/tolerance comparison이다. CSV row는 비교 가능한 최소 식별자로 step, frame/time, instance, node 또는 element label, integration point, section point, output position, component, coordinate system, unit, value를 포함해야 한다. Feature별 interface contract는 필요한 column과 tolerance를 더 좁게 정의한다.

Reference artifacts는 생성 후 검증 입력으로 취급한다. Validation agent는 source code, tests, tolerances, reference artifacts를 임의 수정하지 않는다.

## Validation 흐름
```text
HARNESS_VALIDATION_COMMANDS set
-> run exact commands only

Default workspace validation:
-> scripts/validate_reference_artifacts.py
-> scripts/validate_fortran.py
-> optional CMake/CTest path if CMake project exists
```

Standard numerical validation flow:
```text
Fortran subroutine implemented
-> user-authored model.inp
-> user runs Abaqus with the subroutine on another PC
-> user extracts ODB quantities to CSV
-> user places model.inp, extracted CSV, msg/dat/log/sta tails, and metadata under references/
-> scripts/validate_reference_artifacts.py checks artifact completeness
-> comparison tooling checks CSV schema, IDs, units, coordinate systems, and tolerances
```

Existing Abaqus execution environment variables are treated as legacy/diagnostic script capabilities, not the project validation workflow. New documents and agents should describe solver evidence as externally generated artifacts, not as commands run by this repository.

## Hook 흐름
```text
apply_patch/Edit/Write
-> .codex/hooks/tdd-guard.py
-> C/C++/Fortran production source changes require related tests

git commit command
-> .codex/hooks/pre_commit_checks.py
-> python -m unittest discover -s scripts -p "test_*.py"
-> python scripts/validate_workspace.py
```

Documents, CMake metadata, reference artifacts, and test files are exempt from the production-source TDD guard where appropriate.

## Optional Supporting CMake / MSVC 흐름
```text
CMakePresets.json has msvc-debug configure preset
-> cmake --preset msvc-debug
-> cmake --build preset binary dir --config Debug
-> ctest --test-dir preset binary dir --output-on-failure -C Debug

CMakeLists.txt exists without preset
-> cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
-> cmake --build build/msvc-debug --config Debug
-> ctest --test-dir build/msvc-debug --output-on-failure -C Debug

No CMake project
-> skip CMake/CTest after script validations
```

이 경로는 supporting native components를 위한 optional validation path이며 프로젝트 정체성을 C++ project로 바꾸지 않는다.

## Failure Routing
- `fortran-compile` 또는 `link`: Implementation 또는 Correction Agent
- `no-abaqus-test`: Implementation 또는 Test Model owner
- `reference-artifact`: Reference Model 또는 Reference Verification Agent
- `schema-mismatch`, `unit-or-coordinate-mismatch`: I/O Definition Agent
- `tolerance-failure`, `nonfinite-result`: Correction Agent 또는 Numerical Review Agent
- `physics-implausible`: Physics Evaluation Agent
- `upstream-contract`: owning upstream gate로 회송
- `environment`: Build/Test Executor Agent가 환경 evidence를 기록하고 중단
