AbaqusSubroutineDev/AGENTS.md

Project: Abaqus User Subroutine Development

프로젝트 정체성

• 이 저장소의 목적은 Abaqus User Subroutine을 요구조건 분석부터 검증까지 일관되게 개발하는 것이다.
• User Subroutine production code는 Fortran을 기본 언어로 작성한다.
• Intel oneAPI Fortran compiler를 기본 컴파일러 체계로 사용한다. 자동 탐지는 ifx를 우선하고, 없으면 ifort를 사용한다.
• Abaqus 실행은 라이선스, 설치 버전, 컴파일러 연동 상태에 의존하므로 기본 검증에서 실행하지 않는다.
• .codex/agents/와 .codex/skills/는 Abaqus User Subroutine 개발 단계별 전문 agent와 작업 규칙의 기준이다.

기술 스택

• Abaqus User Subroutine in Fortran
• Intel oneAPI Fortran compiler on Windows
• Python 3 validation and automation scripts
• Codex custom agents and skills
• Optional CMake + CTest validation path when a CMake project exists
• Optional MSVC/x64/Debug validation path for supporting native components only

개발 워크플로우

1. Subroutine 요구조건 분석
2. 책, 논문, Abaqus manual, benchmark 등 연구자료 조사
3. 코드 구현을 위한 유한요소 정식화
4. Subroutine 입출력 파라미터와 Abaqus ABI 계약 정의
5. TDD 방법을 사용하는 no-Abaqus test model 및 reference artifact 계약 작성
6. Fortran 코드 구현
7. Subroutine 검증, 물리 타당성 검토, readiness audit

Agent / Skill 운영 규칙

• 장기 작업은 위 7단계 gate로 나누고, 각 gate는 독립적으로 검토 가능한 문서 산출물을 남긴다.
• Agent mapping과 gate 정의는 docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md를 기준으로 한다.
• Requirement Agent는 docs/requirements/<feature-id>.md에 요구조건과 Requirement Verification Matrix를 작성한다.
• Research Agent는 docs/research/<feature-id>-research.md에 source-backed fact, inference, applicability limit를 분리해 기록한다.
• Formulation Agent와 Numerical Review Agent는 formulation, tangent, state variable, numerical risk를 구현 전 검토한다.
• I/O Definition Agent는 Abaqus ABI argument, update responsibility, tensor order, unit, CSV schema를 명시한다.
• Reference Model Agent는 tests/fortran/manifest.json 계획과 references/<feature-id>/<model-id>/ artifact 계약을 정의한다.
• Implementation Agent는 승인된 implementation plan만 구현하며 RED -> GREEN -> VERIFY 순서를 지킨다.
• Validation, Physics Evaluation, Release Agent는 source code, tests, reference artifacts, tolerances를 임의로 변경하지 않는다.

아키텍처 규칙

• CRITICAL: 기본 검증 경로는 python scripts/validate_workspace.py이다.
• CRITICAL: Abaqus 실행은 기본 검증에서 수행하지 않는다. HARNESS_ABAQUS_VALIDATION=run과 HARNESS_ABAQUS_VALIDATION_COMMANDS가 명시된 경우에만 실행한다.
• CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
• CRITICAL: Fortran user subroutine production file을 바꿀 때는 관련 no-Abaqus Fortran/Python driver test가 있어야 한다.
• CRITICAL: Abaqus reference artifact 생성, 갱신, 승인된 solver output 복원은 명시적으로 요청된 phase에서만 수행한다.
• Abaqus ABI wrapper는 얇게 유지하고, 테스트 가능한 계산 로직은 no-Abaqus kernel 또는 driver에서 검증 가능하게 분리한다.
• Reference artifacts는 승인 후 read-only evidence로 취급한다.
• Codex custom agent의 model_reasoning_effort 기본값은 extra high로 둔다.
• Codex hook 정책은 .codex/hooks/에 둔다.
• Abaqus User Subroutine planning/review instructions는 .codex/skills/에 둔다.
• Generated phase execution outputs remain ignored under phases/**/step*-output.json.

검증 명령어

python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
python scripts/validate_fortran.py
python scripts/validate_reference_artifacts.py
python scripts/execute.py <phase-dir>
python scripts/execute.py <phase-dir> --push

Fortran / Abaqus 검증 기본값

• HARNESS_FORTRAN_VALIDATION=auto: tests/fortran/manifest.json이 있으면 Intel Fortran no-Abaqus tests를 실행한다.
• HARNESS_FORTRAN_VALIDATION=off: Fortran validation을 건너뛴다.
• HARNESS_FORTRAN_VALIDATION=detect: manifest와 compiler 감지만 수행하고 compile/run command를 만들지 않는다.
• HARNESS_FORTRAN_COMPILER=auto: ifx를 우선 사용하고, 없으면 ifort를 사용한다.
• HARNESS_ONEAPI_VARS_BAT: Intel oneAPI 환경 설정 batch file override.
• HARNESS_ABAQUS_VALIDATION=off: 기본값이며 Abaqus job을 실행하지 않는다.
• HARNESS_ABAQUS_VALIDATION=detect: Abaqus executable 탐지만 수행한다.
• HARNESS_ABAQUS_VALIDATION=run: HARNESS_ABAQUS_VALIDATION_COMMANDS에 명시된 Abaqus command만 실행한다.
• HARNESS_ABAQUS_USE_ONEAPI_ENV=auto: Abaqus run command 앞에 oneAPI 환경 설정을 자동 적용할 수 있다.

Supporting CMake / MSVC 검증 기본값

• CMake project가 존재할 때만 CMake/CTest 경로를 실행한다.
• Generator: Visual Studio 17 2022
• Platform: x64
• Config: Debug
• Build directory: build/msvc-debug
• Override variables:
  • HARNESS_VALIDATION_COMMANDS
  • HARNESS_CMAKE_GENERATOR
  • HARNESS_CMAKE_PLATFORM
  • HARNESS_CMAKE_CONFIG
  • HARNESS_BUILD_DIR

개발 프로세스 규칙

• 문서 변경은 관련 구현을 대신하지 않는다. Requirements, research, formulation, interface, test model, implementation, validation evidence를 구분한다.
• 모든 must requirement는 verification method, acceptance criteria, tolerance 또는 decision owner를 가져야 한다.
• Public example repository는 layout과 학습 자료로만 사용한다. Acceptance evidence로 쓰려면 source, license, version, generated artifact provenance를 별도로 기록한다.
• Abaqus .inp, .msg, .dat, .log, extracted CSV는 reference artifact contract에 맞춰 저장한다.
• 커밋 전 hook은 Python self-test와 workspace validation을 실행해야 한다.
• 커밋 메시지는 conventional commits 형식을 따른다: feat:, fix:, docs:, refactor:, test:.