Architecture: Abaqus User Subroutine Development

목표

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

주요 원칙

Abaqus User Subroutine 개발이 프로젝트의 중심이다.
Fortran source는 Abaqus ABI wrapper와 testable kernel/driver logic을 가능한 한 분리한다.
기본 검증은 Abaqus를 실행하지 않는다.
Abaqus 실행과 reference artifact 생성은 명시적으로 승인된 환경에서만 수행한다.
Requirements, research, formulation, interface, test model, implementation, validation 산출물을 섞지 않는다.

디렉토리 구조

.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>/    # Optional approved Abaqus reference artifacts
phases/
└── <phase-id>/                 # Optional staged execution plans

Gate 흐름

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 구조

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 구조

references/<feature-id>/<model-id>/
├── metadata.json
├── model.inp
├── job.msg.tail.txt
├── job.dat.tail.txt
├── job.log.tail.txt
└── *.csv

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

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

Validation 흐름

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
-> optional Abaqus command path only when HARNESS_ABAQUS_VALIDATION=run

HARNESS_ABAQUS_VALIDATION=detect는 Abaqus executable 탐지만 보고한다. HARNESS_ABAQUS_VALIDATION=run은 HARNESS_ABAQUS_VALIDATION_COMMANDS가 없으면 configuration error로 실패한다.

Hook 흐름

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 흐름

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를 기록하고 중단

7.1 KiB Raw Blame History