add docu
This commit is contained in:
김경종
@@ -1,33 +1,54 @@
|
|||||||
# Project: FESA Harness
|
# 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와 작업 규칙의 기준이다.
|
||||||
|
|
||||||
## 기술 스택
|
## 기술 스택
|
||||||
- C++17 이상
|
- Abaqus User Subroutine in Fortran
|
||||||
- MSVC on Windows
|
|
||||||
- CMake + CTest
|
|
||||||
- Abaqus UserSubroutine source in Fortran
|
|
||||||
- Intel oneAPI Fortran compiler on Windows
|
- Intel oneAPI Fortran compiler on Windows
|
||||||
- Harness scripts in Python 3
|
- 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: 기본 검증 경로는 `python scripts/validate_workspace.py`이다.
|
||||||
- CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
|
- CRITICAL: Abaqus 실행은 기본 검증에서 수행하지 않는다. `HARNESS_ABAQUS_VALIDATION=run`과 `HARNESS_ABAQUS_VALIDATION_COMMANDS`가 명시된 경우에만 실행한다.
|
||||||
- CRITICAL: Abaqus 실행은 기본 검증에서 수행하지 않는다. `HARNESS_ABAQUS_VALIDATION=run`으로 명시한 경우에만 실행한다.
|
|
||||||
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
|
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
|
||||||
- CRITICAL: Abaqus reference artifact나 solver 코드 복원은 명시적으로 요청된 phase에서만 수행한다.
|
- 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 custom agent의 `model_reasoning_effort` 기본값은 `extra high`로 둔다.
|
||||||
- Harness runner는 `scripts/execute.py`에 둔다.
|
|
||||||
- Codex hook 정책은 `.codex/hooks/`에 둔다.
|
- Codex hook 정책은 `.codex/hooks/`에 둔다.
|
||||||
- Harness planning/review instructions are stored in `.codex/skills/`.
|
- Abaqus User Subroutine planning/review instructions는 `.codex/skills/`에 둔다.
|
||||||
- Generated phase execution outputs remain ignored under `phases/**/step*-output.json`.
|
- Generated phase execution outputs remain ignored under `phases/**/step*-output.json`.
|
||||||
|
|
||||||
## 개발 프로세스
|
## 검증 명령어
|
||||||
- TDD를 기본으로 한다. C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
|
|
||||||
- Fortran user subroutine production file을 바꿀 때는 관련 no-Abaqus Fortran/Python driver test가 있어야 한다.
|
|
||||||
- 커밋 전 hook은 Harness Python self-test와 workspace validation을 실행해야 한다.
|
|
||||||
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`.
|
|
||||||
- 계획이 필요한 장기 작업은 Harness phase로 나누고, 각 step은 독립 실행 가능해야 한다.
|
|
||||||
|
|
||||||
## 명령어
|
|
||||||
```bash
|
```bash
|
||||||
python -m unittest discover -s scripts -p "test_*.py"
|
python -m unittest discover -s scripts -p "test_*.py"
|
||||||
python scripts/validate_workspace.py
|
python scripts/validate_workspace.py
|
||||||
@@ -37,24 +58,34 @@ python scripts/execute.py <phase-dir>
|
|||||||
python scripts/execute.py <phase-dir> --push
|
python scripts/execute.py <phase-dir> --push
|
||||||
```
|
```
|
||||||
|
|
||||||
## MSVC 검증 기본값
|
## Fortran / Abaqus 검증 기본값
|
||||||
- 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`
|
|
||||||
|
|
||||||
## Abaqus / Fortran 검증 기본값
|
|
||||||
- `HARNESS_FORTRAN_VALIDATION=auto`: `tests/fortran/manifest.json`이 있으면 Intel Fortran no-Abaqus tests를 실행한다.
|
- `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_FORTRAN_COMPILER=auto`: `ifx`를 우선 사용하고, 없으면 `ifort`를 사용한다.
|
||||||
- `HARNESS_ONEAPI_VARS_BAT`: Intel oneAPI 환경 설정 batch file override.
|
- `HARNESS_ONEAPI_VARS_BAT`: Intel oneAPI 환경 설정 batch file override.
|
||||||
- `HARNESS_ABAQUS_VALIDATION=off`: 기본값이며 Abaqus job을 실행하지 않는다.
|
- `HARNESS_ABAQUS_VALIDATION=off`: 기본값이며 Abaqus job을 실행하지 않는다.
|
||||||
- `HARNESS_ABAQUS_VALIDATION=detect`: Abaqus executable 탐지만 수행한다.
|
- `HARNESS_ABAQUS_VALIDATION=detect`: Abaqus executable 탐지만 수행한다.
|
||||||
- `HARNESS_ABAQUS_VALIDATION=run`: `HARNESS_ABAQUS_VALIDATION_COMMANDS`에 명시된 Abaqus command만 실행한다.
|
- `HARNESS_ABAQUS_VALIDATION=run`: `HARNESS_ABAQUS_VALIDATION_COMMANDS`에 명시된 Abaqus command만 실행한다.
|
||||||
- `HARNESS_ABAQUS_USE_ONEAPI_ENV=auto`: Abaqus run command 앞에 oneAPI 환경 설정을 자동 적용할 수 있다.
|
- `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:`.
|
||||||
|
|||||||
+49
-21
@@ -1,41 +1,69 @@
|
|||||||
# Architecture Decision Records
|
# Architecture Decision Records
|
||||||
|
|
||||||
## 철학
|
## 철학
|
||||||
Harness는 현재 프로젝트의 실제 기술 스택을 반영해야 한다. C++/MSVC 프로젝트에서 npm, Next.js, TypeScript test naming을 기본값으로 두면 agent prompt와 hook policy가 잘못된 구현을 유도한다.
|
Abaqus User Subroutine 개발은 일반 application code 개발보다 ABI, solver execution, compiler integration, reference artifact provenance의 영향을 크게 받는다. 이 프로젝트의 결정은 Abaqus 실행을 기본 전제로 삼지 않으면서도, Fortran code와 numerical behavior를 검증 가능한 단위로 나누는 방향을 따른다.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### ADR-001: C++ 전용 Harness
|
### ADR-001: 프로젝트 정체성은 Abaqus User Subroutine Development다
|
||||||
**결정**: Harness scaffold는 C++/MSVC 전용으로 운영한다. JavaScript/TypeScript fallback은 유지하지 않는다.
|
**결정**: 이 저장소의 프로젝트 정체성은 Abaqus User Subroutine development로 둔다. 다른 개발 체계를 프로젝트 정체성으로 사용하지 않는다.
|
||||||
|
|
||||||
**이유**: FESA 개발 환경은 MSVC 기반 C++이다. 언어별 fallback을 남기면 validation, TDD guard, acceptance criteria가 흐려진다.
|
**이유**: 현재 agent, skill, research, validation script는 Abaqus User Subroutine 개발 workflow를 중심으로 확장되어 있다. 프로젝트 이름과 문서가 다른 정체성을 말하면 agent가 잘못된 우선순위와 검증 경로를 선택한다.
|
||||||
|
|
||||||
**트레이드오프**: 같은 Harness scaffold를 JS/TS 프로젝트에 재사용할 수 없다. 필요하면 별도 template이나 language registry를 새 ADR로 설계한다.
|
**트레이드오프**: 기존 script와 environment variable 이름에 남아 있는 `HARNESS_*` prefix는 호환성을 위해 유지한다. 이름은 historical implementation detail로 취급하고, 문서의 목적 설명은 Abaqus User Subroutine 개발에 맞춘다.
|
||||||
|
|
||||||
### ADR-002: CMake/MSVC/x64/Debug 기본 검증
|
### ADR-002: Fortran과 Intel oneAPI를 기본 구현 체계로 사용한다
|
||||||
**결정**: 기본 workspace validation은 CMake, Visual Studio 17 2022 generator, x64 platform, Debug config, CTest로 수행한다.
|
**결정**: Abaqus User Subroutine production source는 Fortran을 기본 언어로 작성하고, Intel oneAPI Fortran compiler를 기본 compiler family로 사용한다. 자동 탐지는 `ifx`를 우선하고 `ifort`를 fallback으로 둔다.
|
||||||
|
|
||||||
**이유**: MSVC 환경에서 CMake/CTest는 source tree가 복원되거나 새 C++ project가 추가될 때 가장 일관된 build/test entry point다.
|
**이유**: Abaqus User Subroutine의 일반적인 Windows workflow는 Fortran compiler와 Abaqus execution procedure의 연동에 의존한다. `ifx` 우선 정책은 oneAPI 현재 방향과 맞고, `ifort` fallback은 기존 Abaqus 환경과의 호환성을 보존한다.
|
||||||
|
|
||||||
**트레이드오프**: Visual Studio solution-only project는 기본 지원하지 않는다. 명시적으로 필요하면 `HARNESS_VALIDATION_COMMANDS`로 override한다.
|
**트레이드오프**: C/C++ subroutine workflow는 기본 지원 범위가 아니다. 필요하면 별도 feature requirement와 interface contract에서 명시한다.
|
||||||
|
|
||||||
### ADR-003: 엄격한 C++ TDD Guard
|
### ADR-003: 개발은 7단계 gate workflow로 진행한다
|
||||||
**결정**: C++ production file 변경은 관련 C++ test file이 없으면 차단한다.
|
**결정**: 모든 중요한 subroutine feature는 requirements, research, formulation, interface, test model, implementation, validation gate를 통과한다.
|
||||||
|
|
||||||
**이유**: Harness의 핵심 목적은 agent가 검증 없는 C++ 변경을 만들지 않도록 하는 것이다. Header 중심 C++ 구조에서도 module 또는 basename 기반 테스트 존재를 확인한다.
|
**이유**: Abaqus User Subroutine은 수학, ABI, input deck, compiler, solver output이 동시에 맞아야 한다. Agent가 한 단계에서 모든 결정을 내리면 검증 불가능한 구현이 만들어질 위험이 크다.
|
||||||
|
|
||||||
**트레이드오프**: 초기 scaffolding 작업에서 guard가 엄격하게 느껴질 수 있다. 문서, CMake 설정, Harness metadata는 guard 대상에서 제외한다.
|
**트레이드오프**: 작은 변경에도 문서화 비용이 생긴다. 단, 단순 correction은 기존 approved contract 안에서 Correction Agent가 최소 수정으로 처리할 수 있다.
|
||||||
|
|
||||||
### ADR-004: Harness 자체 테스트 우선
|
### ADR-004: 기본 검증은 no-Abaqus path로 유지한다
|
||||||
**결정**: commit hook은 먼저 Python Harness self-test를 실행한 뒤 workspace validation을 실행한다.
|
**결정**: `python scripts/validate_workspace.py`는 기본 검증 entry point이며 Abaqus job을 자동 실행하지 않는다. Abaqus 실행은 `HARNESS_ABAQUS_VALIDATION=run`과 `HARNESS_ABAQUS_VALIDATION_COMMANDS`가 명시된 경우에만 수행한다.
|
||||||
|
|
||||||
**이유**: 현재 저장소에는 C++ source tree가 없을 수 있다. Harness가 스스로 검증 가능해야 이후 phase generation과 source restoration을 안전하게 진행할 수 있다.
|
**이유**: Abaqus 실행은 설치, 라이선스, target version, compiler integration, working directory, scratch behavior에 의존한다. 기본 검증이 Abaqus에 의존하면 개발 재현성이 떨어진다.
|
||||||
|
|
||||||
**트레이드오프**: commit 시간이 조금 늘어난다. 대신 hook/validation regressions를 빠르게 잡는다.
|
**트레이드오프**: 기본 검증만으로 Abaqus runtime symbol resolution이나 actual solver behavior를 완전히 보장할 수 없다. 해당 evidence는 opt-in validation과 approved reference artifacts로 보완한다.
|
||||||
|
|
||||||
### ADR-005: Fortran Abaqus UserSubroutine 확장
|
### ADR-005: Abaqus ABI wrapper는 얇게 유지하고 계산 kernel은 no-Abaqus로 검증한다
|
||||||
**결정**: Abaqus UserSubroutine 구현 언어는 Fortran으로 둔다. 기본 validation은 no-Abaqus mode를 유지하고, Intel oneAPI Fortran kernel/fake-driver tests와 reference artifact metadata validation을 수행한다.
|
**결정**: Subroutine source는 가능한 한 thin Abaqus ABI wrapper와 testable kernel 또는 driver logic으로 분리한다.
|
||||||
|
|
||||||
**이유**: Abaqus UserSubroutine은 Abaqus runtime, license, compiler integration에 의존한다. 기본 hook이나 workspace validation에서 Abaqus job을 자동 실행하면 개발 환경과 license 상태에 따라 재현성이 떨어진다. 계산 kernel과 Abaqus ABI wrapper를 분리하면 no-Abaqus 환경에서도 TDD를 유지할 수 있다.
|
**이유**: UMAT, VUMAT, UEL 같은 entry point는 Abaqus가 호출하는 argument contract가 크고 solver-dependent하다. 핵심 계산 로직을 no-Abaqus test에서 검증할 수 있어야 RED -> GREEN -> VERIFY 개발이 가능하다.
|
||||||
|
|
||||||
**트레이드오프**: no-Abaqus validation은 Abaqus symbol resolution, include compatibility, actual job execution을 완전히 보장하지 않는다. 해당 검증은 `HARNESS_ABAQUS_VALIDATION=run`으로 명시한 환경에서만 수행한다.
|
**트레이드오프**: Wrapper와 kernel 사이의 mapping code가 추가된다. 이 mapping 자체는 interface contract와 wrapper-level compile/smoke test로 검증해야 한다.
|
||||||
|
|
||||||
|
### ADR-006: Reference artifacts는 metadata contract로 검증한다
|
||||||
|
**결정**: Abaqus reference artifacts는 `references/<feature-id>/<model-id>/metadata.json`과 함께 보관하고, `scripts/validate_reference_artifacts.py`로 metadata, source hash, required files를 검증한다.
|
||||||
|
|
||||||
|
**이유**: Abaqus output CSV만 있으면 어떤 source, Abaqus version, compiler, precision, command에서 생성됐는지 추적할 수 없다. Source hash와 log tail을 포함해야 comparison evidence로 사용할 수 있다.
|
||||||
|
|
||||||
|
**트레이드오프**: Reference artifact 준비 비용이 증가한다. 대신 stale artifact, source mismatch, missing provenance를 자동으로 탐지할 수 있다.
|
||||||
|
|
||||||
|
### ADR-007: Fortran production 변경은 TDD guard 대상이다
|
||||||
|
**결정**: `.f`, `.for`, `.f90`, `.f95`, `.f03`, `.f08` production source 변경은 관련 test file이 없으면 guard가 차단한다.
|
||||||
|
|
||||||
|
**이유**: Abaqus User Subroutine 구현은 numerical regression을 만들기 쉽다. Production code 변경 전에 no-Abaqus driver test 또는 관련 existing test를 확보해야 한다.
|
||||||
|
|
||||||
|
**트레이드오프**: 초기 prototype 작성 시 guard가 엄격하게 느껴질 수 있다. 이 경우에도 먼저 minimal driver test를 두고 구현한다. Reference artifacts와 documentation은 production-source guard 대상에서 제외한다.
|
||||||
|
|
||||||
|
### ADR-008: Optional CMake/MSVC validation은 supporting path로만 유지한다
|
||||||
|
**결정**: CMake project가 존재하면 Visual Studio 17 2022, x64, Debug, CTest validation path를 실행한다. 단, 이것은 supporting native components를 위한 optional path이며 프로젝트 정체성을 바꾸지 않는다.
|
||||||
|
|
||||||
|
**이유**: 기존 validation infrastructure가 CMake/CTest를 지원하고, 향후 helper library나 supporting native code가 생길 수 있다. 하지만 Abaqus User Subroutine development의 기본 구현 단위는 Fortran과 Abaqus ABI contract다.
|
||||||
|
|
||||||
|
**트레이드오프**: 문서에서 CMake/MSVC를 완전히 제거하지 않는다. 대신 optional supporting validation으로 제한해 agent가 C++ project로 오해하지 않게 한다.
|
||||||
|
|
||||||
|
### ADR-009: Public examples는 acceptance evidence가 아니다
|
||||||
|
**결정**: Public Abaqus subroutine repositories, course notes, blogs는 layout과 learning reference로만 사용한다. Acceptance evidence가 되려면 source reliability, license, version, applicability, generated artifact provenance를 별도로 기록해야 한다.
|
||||||
|
|
||||||
|
**이유**: Public example은 bug-free 또는 validation-quality artifact라는 보장이 없다. 이 프로젝트의 acceptance는 requirements, reference artifact metadata, comparison evidence, physics sanity를 통해 판단한다.
|
||||||
|
|
||||||
|
**트레이드오프**: 공개 예제를 빠르게 복사해 시작하는 방식보다 느리다. 대신 장기적으로 source provenance와 verification traceability를 유지할 수 있다.
|
||||||
|
|||||||
+126
-39
@@ -1,75 +1,162 @@
|
|||||||
# 아키텍처
|
# Architecture: Abaqus User Subroutine Development
|
||||||
|
|
||||||
## 목표
|
## 목표
|
||||||
이 저장소의 현재 책임은 C++/MSVC 프로젝트를 위한 Codex Harness scaffold를 제공하는 것이다. Harness는 phase execution, edit guard, commit validation, workspace validation을 분리해서 관리한다.
|
이 저장소는 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 산출물을 섞지 않는다.
|
||||||
|
|
||||||
## 디렉토리 구조
|
## 디렉토리 구조
|
||||||
```text
|
```text
|
||||||
.codex/
|
.codex/
|
||||||
|
├── agents/ # Abaqus User Subroutine specialist agent definitions
|
||||||
├── hooks/ # Codex hook scripts
|
├── hooks/ # Codex hook scripts
|
||||||
└── skills/ # Harness planning/review instructions
|
└── skills/ # Abaqus workflow, review, TDD, validation instructions
|
||||||
docs/ # Project and Harness guidance
|
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/
|
scripts/
|
||||||
├── execute.py # Phase step executor
|
├── execute.py
|
||||||
|
├── fortran_toolchain.py
|
||||||
|
├── validate_fortran.py
|
||||||
|
├── validate_reference_artifacts.py
|
||||||
├── validate_workspace.py
|
├── validate_workspace.py
|
||||||
└── test_*.py # Harness self-tests
|
└── test_*.py
|
||||||
phases/ # Optional generated phase plans
|
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 흐름
|
||||||
```text
|
```text
|
||||||
User-approved task
|
User request
|
||||||
-> Harness phase files under phases/
|
-> Requirement gate
|
||||||
-> scripts/execute.py injects AGENTS.md and docs/*.md
|
-> Research gate
|
||||||
-> Codex executes one step at a time
|
-> Formulation gate
|
||||||
-> step updates phases/{phase}/index.json
|
-> Numerical review gate
|
||||||
-> validation runs through scripts/validate_workspace.py
|
-> 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
|
||||||
|
└── *.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 흐름
|
||||||
|
```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
|
||||||
|
-> 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 흐름
|
## Hook 흐름
|
||||||
```text
|
```text
|
||||||
apply_patch/Edit/Write
|
apply_patch/Edit/Write
|
||||||
-> .codex/hooks/tdd-guard.py
|
-> .codex/hooks/tdd-guard.py
|
||||||
-> C++ production changes require related tests
|
-> C/C++/Fortran production source changes require related tests
|
||||||
|
|
||||||
git commit command
|
git commit command
|
||||||
-> .codex/hooks/pre_commit_checks.py
|
-> .codex/hooks/pre_commit_checks.py
|
||||||
-> Python Harness self-tests
|
-> python -m unittest discover -s scripts -p "test_*.py"
|
||||||
-> scripts/validate_workspace.py
|
-> python scripts/validate_workspace.py
|
||||||
```
|
```
|
||||||
|
|
||||||
## Validation 흐름
|
Documents, CMake metadata, reference artifacts, and test files are exempt from the production-source TDD guard where appropriate.
|
||||||
|
|
||||||
|
## Optional Supporting CMake / MSVC 흐름
|
||||||
```text
|
```text
|
||||||
HARNESS_VALIDATION_COMMANDS set
|
|
||||||
-> run exact commands
|
|
||||||
|
|
||||||
Always, unless HARNESS_VALIDATION_COMMANDS overrides:
|
|
||||||
-> scripts/validate_reference_artifacts.py
|
|
||||||
-> scripts/validate_fortran.py
|
|
||||||
|
|
||||||
CMakePresets.json has msvc-debug configure preset
|
CMakePresets.json has msvc-debug configure preset
|
||||||
-> cmake --preset msvc-debug
|
-> cmake --preset msvc-debug
|
||||||
-> cmake --build preset binary dir --config Debug
|
-> cmake --build preset binary dir --config Debug
|
||||||
-> ctest --test-dir preset binary dir -C Debug
|
-> ctest --test-dir preset binary dir --output-on-failure -C Debug
|
||||||
|
|
||||||
CMakeLists.txt exists
|
CMakeLists.txt exists without preset
|
||||||
-> cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
|
-> cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
|
||||||
-> cmake --build build/msvc-debug --config Debug
|
-> cmake --build build/msvc-debug --config Debug
|
||||||
-> ctest --test-dir build/msvc-debug --output-on-failure -C Debug
|
-> ctest --test-dir build/msvc-debug --output-on-failure -C Debug
|
||||||
|
|
||||||
No CMake project
|
No CMake project
|
||||||
-> print guidance and exit successfully
|
-> skip CMake/CTest after script validations
|
||||||
|
|
||||||
HARNESS_ABAQUS_VALIDATION=detect
|
|
||||||
-> report Abaqus executable discovery only
|
|
||||||
|
|
||||||
HARNESS_ABAQUS_VALIDATION=run
|
|
||||||
-> run HARNESS_ABAQUS_VALIDATION_COMMANDS only
|
|
||||||
-> never generate reference CSVs
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Abaqus UserSubroutine 확장
|
이 경로는 supporting native components를 위한 optional validation path이며 프로젝트 정체성을 C++ project로 바꾸지 않는다.
|
||||||
|
|
||||||
Fortran Abaqus UserSubroutine 개발은 thin Abaqus ABI wrapper와 no-Abaqus kernel/fake-driver tests를 분리한다.
|
## Failure Routing
|
||||||
기본 workspace validation은 Abaqus를 실행하지 않으며, Intel oneAPI Fortran compiler가 감지되고 `tests/fortran/manifest.json`이 있을 때만 Fortran compile/run tests를 수행한다.
|
- `fortran-compile` 또는 `link`: Implementation 또는 Correction Agent
|
||||||
Stored reference artifacts under `references/<feature-id>/<model-id>/` are read-only and validated through metadata, source hashes, log tails, and declared CSV files.
|
- `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를 기록하고 중단
|
||||||
|
|||||||
+57
-18
@@ -1,26 +1,65 @@
|
|||||||
# PRD: C++/MSVC Harness
|
# PRD: Abaqus User Subroutine Development
|
||||||
|
|
||||||
## 목표
|
## 목표
|
||||||
Codex Harness가 C++/MSVC 프로젝트에서 phase planning, TDD guard, commit validation, workspace validation을 일관되게 수행하게 한다.
|
이 프로젝트는 Abaqus User Subroutine을 요구조건 분석, 연구, 유한요소 정식화, ABI 정의, TDD test model 설계, Fortran 구현, 검증까지 일관된 agent-driven workflow로 개발하게 한다.
|
||||||
|
|
||||||
|
기본 목표는 Abaqus가 없는 환경에서도 가능한 검증을 최대화하고, Abaqus 실행이 필요한 검증은 명시적으로 opt-in한 환경에서만 수행하는 것이다.
|
||||||
|
|
||||||
## 사용자
|
## 사용자
|
||||||
- Windows/MSVC 기반 C++ 개발자
|
- Abaqus User Subroutine을 개발하는 엔지니어
|
||||||
- Harness phase를 작성하고 실행하는 Codex agent
|
- Subroutine 요구조건, 정식화, interface, test model, validation을 단계별로 작성하는 Codex agent
|
||||||
- Harness 결과를 검토하는 reviewer
|
- 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에 의존하므로 모든 개발 단계의 기본 검증 수단으로 삼기 어렵다.
|
||||||
|
- LLM agent가 요구조건, formulation, interface, test, implementation, validation을 한 번에 섞으면 검증 불가능한 Fortran code가 생성되기 쉽다.
|
||||||
|
- 따라서 단계별 gate, 문서 산출물, no-Abaqus TDD, reference artifact metadata 검증이 필요하다.
|
||||||
|
|
||||||
|
## 핵심 워크플로우
|
||||||
|
1. Requirement Agent가 feature requirement와 Requirement Verification Matrix를 작성한다.
|
||||||
|
2. Research Agent가 Abaqus manual, 책, 논문, benchmark source를 조사하고 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가 validation evidence와 readiness를 검토한다.
|
||||||
|
|
||||||
## 핵심 기능
|
## 핵심 기능
|
||||||
1. CMake/MSVC/x64/Debug 기반 workspace validation
|
1. `.codex/agents/`와 `.codex/skills/` 기반 단계별 specialist workflow
|
||||||
2. C++ source/header 변경에 대한 엄격한 TDD guard
|
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. npm 없이 Python self-test와 CMake/CTest 검증을 수행하는 pre-commit hook
|
3. Fortran production 변경에 대한 TDD guard
|
||||||
4. C++ 프로젝트에 맞는 Harness workflow/review prompt
|
4. Intel oneAPI Fortran 기반 no-Abaqus kernel/fake-driver validation
|
||||||
5. CMake project가 아직 없어도 Harness 자체 테스트가 가능한 no-op validation path
|
5. `tests/fortran/manifest.json` 기반 Fortran compile/run test discovery
|
||||||
6. Fortran Abaqus UserSubroutine source 변경에 대한 no-Abaqus TDD guard
|
6. `references/<feature-id>/<model-id>/metadata.json` 기반 reference artifact metadata validation
|
||||||
7. Intel oneAPI Fortran 기반 kernel/fake-driver validation
|
7. Abaqus job 실행을 기본 검증에서 제외하고 `HARNESS_ABAQUS_VALIDATION=run`에서만 수행하는 opt-in validation
|
||||||
8. Abaqus 실행 opt-in validation과 reference artifact metadata validation
|
8. Optional CMake/CTest validation path for supporting native code when a CMake project exists
|
||||||
|
|
||||||
|
## 대표 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를 가진다.
|
||||||
|
- 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은 approved reference artifacts가 `ready-for-comparison` 상태일 때만 수행한다.
|
||||||
|
|
||||||
## 제외 사항
|
## 제외 사항
|
||||||
- 이전 FESA solver source tree 복원
|
- 프로젝트 정체성을 Abaqus User Subroutine development 외의 다른 개발 체계로 정의하지 않는다.
|
||||||
- JavaScript/TypeScript fallback 유지
|
- 기본 validation에서 Abaqus job을 자동 실행하지 않는다.
|
||||||
- Abaqus reference artifact 생성 또는 solver reference 비교 구현
|
- Agent가 reference CSV, `.msg`, `.dat`, `.log` evidence를 임의 생성하거나 승인하지 않는다.
|
||||||
- Visual Studio `.sln`/`.vcxproj` 전용 MSBuild workflow
|
- 특정 재료모델, 요소모델, plasticity model, damage model의 물리적 타당성을 이 PRD에서 승인하지 않는다.
|
||||||
- 기본 validation에서 Abaqus job 자동 실행
|
- Public example repository code를 license 검토 없이 복사하거나 acceptance evidence로 사용하지 않는다.
|
||||||
|
- Visual Studio `.sln`/`.vcxproj` 전용 workflow를 기본 지원하지 않는다.
|
||||||
|
|
||||||
|
## 운영 제약
|
||||||
|
- 문서 산출물은 Korean narrative를 기본으로 하되, Abaqus keyword, subroutine name, status value, command, schema key는 English를 유지한다.
|
||||||
|
- Abaqus version, compiler version, precision, command line, source hash, output tail, CSV schema는 reference artifact metadata에 기록한다.
|
||||||
|
- Abaqus execution이 필요한 검증은 user 또는 승인된 환경이 명시적으로 설정해야 한다.
|
||||||
|
|||||||
Reference in New Issue
Block a user