# PRD: Abaqus User Subroutine Development

## 목표
이 프로젝트는 Abaqus User Subroutine을 요구조건 분석, 연구, 유한요소 정식화, ABI 정의, TDD test model 설계, Fortran 구현, 검증까지 일관된 agent-driven workflow로 개발하게 한다.

기본 목표는 Abaqus가 없는 환경에서도 가능한 검증을 최대화하고, 수치 결과 검증은 사용자가 다른 Abaqus PC에서 수행한 해석의 ODB 추출 CSV를 schema/tolerance로 비교하는 것이다. 이 프로젝트는 Abaqus job 해석을 직접 실행하지 않는다.

## 사용자
- Abaqus User Subroutine을 개발하는 엔지니어
- Subroutine 요구조건, 정식화, interface, test model, validation을 단계별로 작성하는 Codex agent
- Fortran implementation과 no-Abaqus TDD evidence를 검토하는 reviewer
- Abaqus reference artifact와 물리 타당성을 검토하는 validator

## 문제 정의
- Abaqus User Subroutine은 Abaqus ABI, analysis procedure, tensor ordering, state variable, compiler/linker, reference artifact provenance가 모두 맞아야 한다.
- Abaqus 실행은 설치, 라이선스, compiler integration에 의존하므로 모든 개발 단계의 기본 검증 수단으로 삼기 어렵다.
- ODB는 Abaqus 환경의 scripting interface가 필요한 solver result database이므로 이 프로젝트의 기본 검증에서 직접 파싱하지 않는다.
- LLM agent가 요구조건, formulation, interface, test, implementation, validation을 한 번에 섞으면 검증 불가능한 Fortran code가 생성되기 쉽다.
- 따라서 단계별 gate, 문서 산출물, no-Abaqus TDD, 외부 생성 extracted CSV artifact metadata 검증이 필요하다.

## 핵심 워크플로우
1. Requirement Agent가 feature requirement와 Requirement Verification Matrix를 작성한다.
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를 정의한다.
6. Reference Model Agent가 no-Abaqus driver tests와 외부 생성 Abaqus reference artifact bundle 계약을 설계한다.
7. Implementation Planning Agent와 Implementation Agent가 RED -> GREEN -> VERIFY 순서로 Fortran code를 구현한다.
8. Build/Test Executor, Reference Verification, Physics Evaluation, Release Agent가 extracted CSV comparison evidence와 readiness를 검토한다.

## 핵심 기능
1. `.codex/agents/`와 `.codex/skills/` 기반 단계별 specialist workflow
2. `docs/requirements/`, `docs/research/`, `docs/formulations/`, `docs/io-definitions/`, `docs/reference-models/`, `docs/implementation-plans/`, `docs/reference-verifications/`, `docs/physics-evaluations/`, `docs/releases/` 산출물 체계
3. Fortran production 변경에 대한 TDD guard
4. Intel oneAPI Fortran 기반 no-Abaqus kernel/fake-driver validation
5. `tests/fortran/manifest.json` 기반 Fortran compile/run test discovery
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`
- Secondary supported planning families: `USDFLD`, `VUSDFLD`, `UVARM`, `UEXTERNALDB`, `VEXTERNALDB`, `UHARD`, `VUHARD`
- 각 feature는 target entry point, supported Abaqus input keyword subset, state variable allocation, output quantities, validation models를 요구조건 단계에서 명시해야 한다.

## 성공 기준
- 모든 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를 남긴다.
- `python scripts/validate_workspace.py`가 기본 검증 entry point로 성공한다.
- Abaqus reference comparison은 ODB에서 추출된 CSV와 approved reference artifacts가 `ready-for-comparison` 상태일 때만 수행한다.
- Reference artifact bundle은 최소 `model.inp`, extracted CSV, `.msg/.dat/.log/.sta` tail files를 포함한다.

## 제외 사항
- 프로젝트 정체성을 Abaqus User Subroutine development 외의 다른 개발 체계로 정의하지 않는다.
- 기본 validation에서 Abaqus job을 자동 실행하지 않는다.
- Agent가 reference CSV, `.msg`, `.dat`, `.log`, `.sta` evidence를 임의 생성하거나 승인하지 않는다.
- 프로젝트는 ODB 파일을 직접 파싱하지 않는다. ODB 추출은 사용자가 Abaqus PC에서 수행하고, 이 프로젝트는 추출된 CSV와 metadata를 검증한다.
- 특정 재료모델, 요소모델, plasticity model, damage model의 물리적 타당성을 이 PRD에서 승인하지 않는다.
- Public example repository code를 license 검토 없이 복사하거나 acceptance evidence로 사용하지 않는다.
- Visual Studio `.sln`/`.vcxproj` 전용 workflow를 기본 지원하지 않는다.

## 운영 제약
- 문서 산출물은 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 검증을 수행한다.
