김경종
70 lines
7.6 KiB
Markdown
70 lines
7.6 KiB
Markdown
# Architecture Decision Records
|
|
|
|
## 철학
|
|
Abaqus User Subroutine 개발은 일반 application code 개발보다 ABI, solver execution, compiler integration, reference artifact provenance의 영향을 크게 받는다. 이 프로젝트의 결정은 Abaqus 실행을 저장소 내부 기본 전제로 삼지 않으면서도, Fortran code와 ODB에서 추출된 numerical behavior를 검증 가능한 단위로 나누는 방향을 따른다.
|
|
|
|
---
|
|
|
|
### ADR-001: 프로젝트 정체성은 Abaqus User Subroutine Development다
|
|
**결정**: 이 저장소의 프로젝트 정체성은 Abaqus User Subroutine development로 둔다. 다른 개발 체계를 프로젝트 정체성으로 사용하지 않는다.
|
|
|
|
**이유**: 현재 agent, skill, research, validation script는 Abaqus User Subroutine 개발 workflow를 중심으로 확장되어 있다. 프로젝트 이름과 문서가 다른 정체성을 말하면 agent가 잘못된 우선순위와 검증 경로를 선택한다.
|
|
|
|
**트레이드오프**: 기존 script와 environment variable 이름에 남아 있는 `HARNESS_*` prefix는 호환성을 위해 유지한다. 이름은 historical implementation detail로 취급하고, 문서의 목적 설명은 Abaqus User Subroutine 개발에 맞춘다.
|
|
|
|
### ADR-002: Fortran과 Intel oneAPI를 기본 구현 체계로 사용한다
|
|
**결정**: Abaqus User Subroutine production source는 Fortran을 기본 언어로 작성하고, Intel oneAPI Fortran compiler를 기본 compiler family로 사용한다. 자동 탐지는 `ifx`를 우선하고 `ifort`를 fallback으로 둔다.
|
|
|
|
**이유**: Abaqus User Subroutine의 일반적인 Windows workflow는 Fortran compiler와 Abaqus execution procedure의 연동에 의존한다. `ifx` 우선 정책은 oneAPI 현재 방향과 맞고, `ifort` fallback은 기존 Abaqus 환경과의 호환성을 보존한다.
|
|
|
|
**트레이드오프**: C/C++ subroutine workflow는 기본 지원 범위가 아니다. 필요하면 별도 feature requirement와 interface contract에서 명시한다.
|
|
|
|
### ADR-003: 개발은 7단계 gate workflow로 진행한다
|
|
**결정**: 모든 중요한 subroutine feature는 requirements, research, formulation, interface, test model, implementation, validation gate를 통과한다.
|
|
|
|
**이유**: Abaqus User Subroutine은 수학, ABI, input deck, compiler, solver output이 동시에 맞아야 한다. Agent가 한 단계에서 모든 결정을 내리면 검증 불가능한 구현이 만들어질 위험이 크다.
|
|
|
|
**트레이드오프**: 작은 변경에도 문서화 비용이 생긴다. 단, 단순 correction은 기존 approved contract 안에서 Correction Agent가 최소 수정으로 처리할 수 있다.
|
|
|
|
### ADR-004: 기본 검증은 no-Abaqus path와 외부 생성 CSV artifact validation으로 유지한다
|
|
**결정**: `python scripts/validate_workspace.py`는 기본 검증 entry point이며 Abaqus job을 자동 실행하지 않는다. Abaqus 해석과 ODB CSV 추출은 사용자가 외부 Abaqus PC에서 수행하고, 이 저장소는 `references/<feature-id>/<model-id>/`에 등록된 extracted CSV artifact를 검증한다.
|
|
|
|
**이유**: Abaqus 실행은 설치, 라이선스, target version, compiler integration, working directory, scratch behavior에 의존한다. 또한 ODB는 일반 Python이 아니라 Abaqus scripting environment가 필요한 결과 database이므로, 이 프로젝트의 기본 검증이 Abaqus 실행 또는 ODB 직접 파싱에 의존하면 개발 재현성이 떨어진다.
|
|
|
|
**트레이드오프**: 기본 검증만으로 Abaqus runtime symbol resolution이나 actual solver behavior를 완전히 보장할 수 없다. 해당 evidence는 사용자가 외부에서 수행한 Abaqus 해석 결과, ODB 추출 CSV, log tail, metadata provenance를 approved reference artifacts로 등록해 보완한다.
|
|
|
|
### ADR-005: Abaqus ABI wrapper는 얇게 유지하고 계산 kernel은 no-Abaqus로 검증한다
|
|
**결정**: Subroutine source는 가능한 한 thin Abaqus ABI wrapper와 testable kernel 또는 driver logic으로 분리한다.
|
|
|
|
**이유**: UMAT, VUMAT, UEL 같은 entry point는 Abaqus가 호출하는 argument contract가 크고 solver-dependent하다. 핵심 계산 로직을 no-Abaqus test에서 검증할 수 있어야 RED -> GREEN -> VERIFY 개발이 가능하다.
|
|
|
|
**트레이드오프**: Wrapper와 kernel 사이의 mapping code가 추가된다. 이 mapping 자체는 interface contract와 wrapper-level compile/smoke test로 검증해야 한다.
|
|
|
|
### ADR-006: Reference artifacts는 extracted CSV와 metadata contract로 검증한다
|
|
**결정**: Abaqus reference artifacts는 `references/<feature-id>/<model-id>/metadata.json`과 함께 보관하고, `scripts/validate_reference_artifacts.py`로 metadata, source hash, required files를 검증한다. 최소 bundle은 `model.inp`, extracted CSV, `.msg/.dat/.log/.sta` tail files를 포함한다. ODB 파일은 직접 parsing하지 않으며, 필요하면 opaque artifact 또는 hash/provenance로만 기록한다.
|
|
|
|
**이유**: Abaqus output CSV만 있으면 어떤 source, Abaqus version, compiler, precision, extraction script에서 생성됐는지 추적할 수 없다. Source hash와 log tail을 포함해야 comparison evidence로 사용할 수 있다. `.sta` tail은 해석 진행과 종료 상태를 확인하는 보조 evidence로 필요하다.
|
|
|
|
**트레이드오프**: Reference artifact 준비 비용이 증가하고, 사용자는 Abaqus PC에서 ODB-to-CSV extraction을 별도로 수행해야 한다. 대신 stale artifact, source mismatch, missing provenance, schema mismatch를 자동으로 탐지할 수 있다.
|
|
|
|
### 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를 유지할 수 있다.
|