김경종
181 lines
8.3 KiB
Markdown
181 lines
8.3 KiB
Markdown
# 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를 검증한다.
|
|
- 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/
|
|
├── 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를 직접 수행하지 않는다.
|
|
|
|
## 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 설계
|
|
- 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를 기록하고 중단
|