diff --git a/AGENTS.md b/AGENTS.md index f9cdbcd..4438eff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,12 +17,21 @@ - 주요 아키텍처 결정과 그 이유 및 트레이드오프는 `docs/ADR.md`에서 확인한다. - AI 에이전트는 설계나 구현 결정을 내리기 전에 PRD에서 제품 범위를, ARCHITECTURE에서 소유권과 데이터 흐름을, ADR에서 이미 결정된 트레이드오프를 먼저 확인한다. 기능별 의미는 `docs/requirements/`, `docs/formulations/`, `docs/io-definitions/`, `docs/reference-models/`의 승인 문서를 source of truth로 삼는다. - Harness는 솔버 자체가 아니라 요구조건, TDD, phase 실행, 검증을 통제하는 개발 운영 인프라이다. 전체 실행 흐름은 `docs/HARNESS_WORKFLOW.md`, 설치와 설정은 `docs/HARNESS.md`를 따른다. -- 문서와 구현은 full Abaqus compatibility를 주장하지 않는다. 기능별로 승인된 Abaqus keyword subset만 지원한다. +- FESA는 Abaqus와 독립적인 솔버다. 문서와 구현은 full Abaqus compatibility뿐 아니라 + Abaqus 요소 정식화, 적분, stabilization, 내부 상태 또는 결과 생성 절차의 동등성을 + 주장하거나 목표로 삼지 않는다. 수치 결과의 exact equality는 허용되지만 내부 동작 + 동등성의 evidence가 아니다. +- 기능별로 승인된 Abaqus keyword subset만 입력 형식으로 지원한다. Abaqus 결과는 승인된 + 비교량의 외부 수치 reference일 뿐 FESA 내부 알고리즘 계약이 아니다. - 공식 solver output은 HDF5 `results.h5`이다. - reference 결과는 FESA와 같은 Abaqus `.inp` 모델을 Abaqus로 해석해 생성한 CSV 파일이다. -- reference artifact의 정확한 경로와 파일명은 기능별 reference model contract를 따른다. 신규 모델은 `reference//_*.csv` canonical 이름을 사용한다. -- `metadata.json`은 선택 reference artifact다. 파일이 없어도 bundle을 불완전하다고 판정하지 않으며, 필수 provenance, units, coordinate system, step/frame, schema, tolerance 정보는 승인된 기능별 reference model contract에 기록한다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약과 일치하는지 확인한다. -- 승인된 B33 baseline은 예외적으로 `reference/cantilever beam/`의 기존 space-containing 파일명을 read-only legacy alias로 사용한다. +- reference case는 기능 문서가 지정한 기존 `.inp`와 실제 비교에 필요한 Abaqus CSV 경로를 + 그대로 사용한다. canonical 이름, legacy-alias 승인, bundle `README.md`, `metadata.json`, + Abaqus version/provenance 또는 중복 unit/coordinate/step-frame/schema 기록은 readiness + 조건이 아니다. +- 비교기는 필요한 source row identity와 component를 결정적으로 대응시키고 누락, 추가, + 중복, nonfinite 값을 tolerance 전에 거부한다. Reference artifact는 rename, rewrite 또는 + 보정하지 않는다. - CSV는 FESA 공식 output이 아니며, FESA HDF5에서 추출한 deterministic CSV view는 비교 디버깅/검토용 보조 artifact로만 둔다. ## FESA 개발의 핵심 원칙 @@ -40,7 +49,7 @@ - CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다. - CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다. - CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다. -- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다. +- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다. - CRITICAL: public header와 implementation 의존성 방향을 역전하지 않는다. - CRITICAL: 사람이 계약과 수치식을 대조할 수 있는 단순한 코드를 작성한다. 주석은 코드가 이미 말하는 동작보다 부호, 수명, 순서, backend 제약처럼 비자명한 이유를 설명한다. - Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다. @@ -79,6 +88,22 @@ - B33 reference row는 component별 Abaqus scale로 `absolute_floor + 1e-6 * reference_scale`을 적용한다. Reference 값을 zero-clamp하거나 누락 row를 무시하지 않는다. - `reference/cantilever beam/` artifact는 rename, rewrite 또는 보정하지 않는다. +## 승인된 MITC4 정책 + +- Abaqus source `S4`와 `S4R`은 같은 FESA MITC4 정식화로 매핑하며 source type은 추적 + 정보로만 보존한다. Abaqus의 S4/S4R 알고리즘을 재현하지 않는다. +- Reference case는 `reference/shell/`의 S4 input/displacement CSV와 + `reference/shellR/`의 S4R input/displacement CSV를 현재 이름 그대로 사용한다. +- Global `U1/U2/U3`만 blocking reference quantity다. 각 case/component에 B33과 같은 + `1e-9 + 1e-6 * reference_scale`을 적용한다. `UR1/UR2/UR3`은 같은 기준을 초과하면 + warning만 남긴다. +- MITC4 drilling calibration, coefficient sweep, energy-ratio threshold와 별도 geometry/director + calibration(`NR-O01`~`NR-O04`)은 구현 범위가 아니다. 6-DOF 선형계에는 물리 회전 + stiffness block의 양의 최소 대각항에 `1e-3`을 곱한 고정 numerical drilling + stabilization만 사용하며 drilling 방향 nodal moment는 지원하지 않는다. +- Drilling stabilization은 physical generalized strain/resultant/stress에 포함하지 않으며 + 별도 drilling stiffness/ratio/energy HDF5 output을 요구하지 않는다. + ## 기능을 추가할 때의 판단 기준 - 새 element는 요구조건과 formulation을 승인한 뒤 semantic mapping, property/material 연결, DOF/scatter, local kernel, deterministic assembly, recovery, HDF5 row identity, reference/physics evidence를 함께 설계한다. @@ -123,6 +148,11 @@ AI 에이전트는 유한요소 구조해석 지식이 필요할 때 FEM wiki를 | 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `docs/physics-evaluations/-physics-evaluation.md` | | 배포 준비 | `release-agent` | `fesa-release-readiness` | `docs/releases/-release.md` | +Implementation Planning Agent는 구현 계획 요청에서 `.agents/skills/harness`를 반드시 +사용한다. 먼저 여러 자기완결적 Step의 초안을 제시하고 사용자 승인을 받은 뒤에만 +`phases/index.json`, `phases//index.json`, `phases//stepN.md`를 +생성한다. Harness 실행은 별도 사용자 요청이 있을 때만 수행한다. + ## 최소 검증 진입점 세부 target graph, dependency normalization과 Windows runtime staging은 `docs/ARCHITECTURE.md`와 실제 CMake 파일을 따른다. `.harness/config.json`이 존재하면 그 설정을 우선한다. diff --git a/docs/ADR.md b/docs/ADR.md index 1d07052..d43a67c 100644 --- a/docs/ADR.md +++ b/docs/ADR.md @@ -42,6 +42,8 @@ solution과 test command를 명시한 직접 MSBuild 프로젝트도 검증할 **트레이드오프**: 초기 class 수가 늘어난다. V0에서는 interface를 얇게 유지하고 실제 선형 정적 frame에 필요한 state만 구현한다. ### ADR-005: 공식 결과 파일은 HDF5로 하고 reference 결과는 Abaqus CSV로 둔다 +**상태**: HDF5 authoritative output 결정은 유지하며 reference bundle governance 부분은 ADR-019로 대체됨. + **결정**: FESA solver의 authoritative result output은 `results.h5` HDF5이다. Abaqus reference results는 기능별 reference model contract가 지정한 `reference//` 아래 CSV 파일로 저장하며, verification은 FESA HDF5 rows와 Abaqus reference CSV rows를 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준으로 비교한다. 신규 reference는 canonical 파일명을 사용하고, 승인된 기존 bundle의 legacy alias는 해당 기능 계약에 정확한 경로를 기록한 경우에만 허용한다. **이유**: 구조해석 결과는 step/frame, field/history, node/element/integration point location, units, coordinate system, schema version을 함께 가져야 한다. HDF5는 이 계층 구조와 metadata를 안정적으로 표현한다. @@ -77,6 +79,8 @@ solution과 test command를 명시한 직접 MSBuild 프로젝트도 검증할 **트레이드오프**: 초기 병렬화 범위가 제한된다. MKL 내부 thread와 TBB task arena의 oversubscription 정책을 별도로 문서화해야 한다. ### ADR-010: Abaqus reference artifact는 사람이 생성하거나 명시 승인된 절차로만 갱신한다 +**상태**: Artifact read-only 및 실행 제한은 유지하며 metadata/provenance/naming 계약은 ADR-019로 대체됨. + **결정**: Agent는 Abaqus, Nastran 또는 reference solver를 직접 실행하지 않는다. reference artifact 생성, 수정, 복원은 명시 승인된 phase에서만 수행한다. 모든 bundle의 provenance, generator/version, units, coordinate system, step/frame identity, schema, tolerance와 limitations는 승인된 기능별 Reference Model Contract에 기록한다. `metadata.json`은 선택 reference artifact이며, 부재만으로 bundle을 불완전하다고 판정하지 않는다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약 및 실제 artifact와 일치하는지 확인하며, 충돌은 숨기지 않고 upstream 계약 문제로 보고한다. 승인된 `cantilever-beam-b33` legacy baseline의 space-containing filename과 `README.md` N/A 예외는 유지한다. **이유**: reference 결과는 solver correctness의 기준이다. 생성 절차가 불명확하면 구현 결함과 reference artifact 오류를 구분할 수 없다. @@ -181,3 +185,29 @@ model adequacy를 검출한다. 한 계층의 성공만으로 parser exposure **트레이드오프**: 작은 기능도 여러 계약과 evidence를 함께 준비해야 하므로 개발 속도가 느려진다. 대신 `*DLOAD`처럼 kernel은 있지만 입력에 노출되지 않은 기능, stress처럼 mandatory output이지만 Abaqus reference가 N/A인 기능을 정확하게 표현할 수 있다. + +### ADR-019: Abaqus는 입력 형식과 외부 수치 reference이며 FESA 내부 동작 계약이 아니다 + +**결정**: FESA는 Abaqus와 독립적인 솔버다. 기능별 승인 `.inp` subset을 입력으로 +사용하고, 기능이 blocking으로 선언한 FESA HDF5 quantity만 기존 Abaqus CSV와 승인 +tolerance로 비교한다. Abaqus 요소 정식화, 적분, stabilization, 내부 상태와 결과 생성 +절차를 재현하거나 동등하게 구현하지 않는다. Exact numerical equality는 허용되지만 +내부 동작 동등성의 evidence가 아니다. + +Reference case readiness에는 선언된 `.inp`, 실제 비교에 필요한 CSV, deterministic +source-ID/component matching과 tolerance만 필요하다. 기존 path와 filename을 그대로 +사용하며 canonical naming, legacy-alias 승인, bundle `README.md`, `metadata.json`, Abaqus +version/provenance, 중복 units/coordinates/model/step/frame/material/section 정보와 CSV schema +version은 요구하지 않는다. Reference artifact는 계속 read-only이며 누락, 추가, 중복, +nonfinite required row는 tolerance 전에 실패한다. + +**이유**: Reference comparison의 목적은 FESA의 독립 정식화가 승인된 observable quantity를 +충분히 가깝게 계산하는지 판정하는 것이다. 수치 비교에 사용되지 않는 artifact +거버넌스가 formulation review나 implementation planning을 차단하면 제품 검증보다 문서 +형식 준수가 우선된다. 같은 정보는 `.inp`, CSV header와 feature contract에서 직접 얻을 +수 있다. + +**트레이드오프**: Reference 생성 환경을 사후에 완전히 재구성하는 감사 기능은 줄어든다. +대신 비교 대상과 source-row/component mapping, tolerance, artifact immutability는 유지해 +false match와 결과 보정을 방지한다. 더 강한 provenance가 필요한 기능은 해당 요구조건이 +명시적으로 추가할 수 있으나 프로젝트 기본 gate로 자동 승격하지 않는다. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0c2e478..4478dc0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -3,6 +3,11 @@ ## 목표 FESA의 아키텍처 목표는 Abaqus `.inp` subset을 내부 semantic model로 변환하고, 유한요소 equation system을 구성해 구조해석 결과를 HDF5로 저장하며, reference comparison과 physics sanity가 가능한 C++17/MSVC 솔버 구조를 제공하는 것이다. +FESA의 element formulation과 numerical path는 Abaqus와 독립적이다. Abaqus `.inp`는 +승인된 입력 형식이고 Abaqus CSV는 기능별 blocking quantity의 외부 수치 reference다. +Abaqus 내부 적분, stabilization, state 또는 recovery 동작은 FESA architecture contract가 +아니다. + 핵심 품질 속성: - FEM formulation traceability - explicit I/O contracts @@ -42,7 +47,7 @@ tests/ integration/ # analysis orchestration and CLI contracts reference/ # HDF5-to-Abaqus projection and comparison reference/ - / # approved read-only Abaqus input/CSV bundle + / # declared read-only Abaqus input/required CSV pair .agents/ skills/ # Harness and review skills .codex/ @@ -302,8 +307,11 @@ Schema requirements: - field output과 history output을 구분한다. - reference comparison을 위한 row identity는 node id, element id, integration point id, step/frame id를 포함한다. - FESA solver는 `results.h5`를 authoritative output으로 쓴다. -- Abaqus reference results는 `reference//` 아래 CSV 파일이다. -- Verification은 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준으로 FESA HDF5 rows와 Abaqus reference CSV rows를 비교한다. +- Abaqus reference results는 기능 문서가 선언한 기존 CSV 파일이다. Directory/file + naming, README, metadata 또는 provenance는 architecture readiness 조건이 아니다. +- Verification은 기능이 요구하는 source identity와 component를 결정적으로 대응시키고 + 승인 tolerance를 적용한다. Missing/extra/duplicate/nonfinite required row는 숫자 비교 + 전에 실패한다. 단일 step/final-frame 기능은 별도 CSV step/frame 열을 요구하지 않는다. - FESA HDF5에서 추출한 deterministic CSV view는 optional debugging/review artifact이며 공식 solver output 또는 reference artifact가 아니다. - Writer는 final과 같은 directory의 임시 HDF5에 전체 schema를 쓴 뒤 flush, checked close, read-only reopen/self-check를 수행한다. Existing final은 `ReplaceFileW`, 새 final은 @@ -348,7 +356,7 @@ deterministic한 순서로 출력한다. | 기능 유형 | 시작 전에 고정할 것 | 주요 구현 경계 | 함께 검증할 것 | 피해야 할 shortcut | | --- | --- | --- | --- | --- | -| 새 element/material | DOF, interpolation, constitutive law, integration, local axes/sign, invalid geometry/property | Domain record와 mapper, element kernel, DofManager scatter/pattern, SparseAssembler, ResultRecovery | rigid modes/rank/energy, patch·analytical test, rotated coordinates, reference/physics | 기존 TYPE을 비슷한 kernel에 alias, source ID와 internal index 혼용, 검증 전 범용 hierarchy 추가 | +| 새 element/material | DOF, interpolation, constitutive law, integration, local axes/sign, feature-approved validity boundary | Domain record와 mapper, element kernel, DofManager scatter/pattern, SparseAssembler, ResultRecovery | feature-required invariants/tests and blocking reference quantities | 서로 다른 물리를 같다고 주장, source ID와 internal index 혼용, 검증 전 범용 hierarchy 추가 | | 새 load/constraint | Abaqus target grammar, application order, units, follower 여부, prescribed-value 의미 | Syntax/mapper, Domain target, full-space LoadAssembler 또는 constraint partition, diagnostics | set/direct target ambiguity, multi-instance identity, nonfinite sum, `Ff-Kfc*dc`, reaction | Element load kernel 존재를 parser 지원으로 간주, penalty를 elimination에 몰래 혼합 | | 새 analysis procedure | governing equation, state variables, increment/time lifecycle, tangent/residual, convergence와 output frame | 별도 Analysis implementation, procedure-specific state/equation owner, solver interface extension | orchestration order, failure atomicity, restart/frame identity, numerical benchmark | V0 hook 사이에 조건문으로 반복/시간 적분 삽입, 사용하지 않는 future state 선할당 | | 새 numerical backend | matrix/index contract, lifecycle, reusable state, failure taxonomy, thread/runtime policy | 기존 `LinearSolver` 또는 `ParallelFor` interface의 concrete adapter, CMake normalized target | empty/dimension/extreme-scale input, repeated call, failed-output preservation, clean runtime discovery | Vendor type을 public header에 노출, silent fallback/regularization, absolute install path 고정 | @@ -356,3 +364,16 @@ deterministic한 순서로 출력한다. 모든 확장은 PRD의 제품 완료 정의와 요구조건→정식화→I/O→구현→reference→physics gate를 따른다. 기존 feature contract에 없는 범위를 편의상 “Abaqus compatible”이라고 넓히지 않는다. + +## MITC4 확장 경계 + +MITC4가 구현될 때 Abaqus `S4`와 `S4R` source type은 같은 FESA formulation을 선택한다. +Source type은 metadata/diagnostic identity로 보존하지만 FESA integration 또는 hourglass +경로를 선택하지 않는다. 6-DOF embedding의 비물리 drilling coordinate에는 physical +rotational stiffness block의 positive minimum diagonal에 `1e-3`을 곱한 고정 numerical +stabilization만 둔다. Drilling calibration, artificial-energy policy와 별도 drilling result +dataset은 이 기능 범위가 아니다. + +Reference comparison은 `reference/shell/` S4와 `reference/shellR/` S4R의 기존 input 및 +displacement CSV를 사용한다. Global `U1/U2/U3`만 blocking이고 B33과 같은 component-scale +mixed tolerance를 적용한다. `UR1/UR2/UR3`은 같은 기준의 warning-only evidence다. diff --git a/docs/PRD.md b/docs/PRD.md index 9472842..411d3ec 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -1,9 +1,15 @@ # PRD: FESA 구조해석 솔버 ## 목표 -FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기반 구조해석을 수행하고, step/frame 단위 결과를 `results.h5` HDF5로 저장하며, Abaqus reference CSV rows와 비교 가능한 C++17/MSVC 솔버를 제공한다. +FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 자체 유한요소 정식화로 구조해석을 +수행하고, step/frame 단위 결과를 `results.h5` HDF5로 저장하며, 기능이 지정한 Abaqus +reference CSV 수치와 비교 가능한 C++17/MSVC 솔버를 제공한다. Abaqus의 요소 알고리즘, +적분법, stabilization 또는 내부 결과 생성 절차를 재현하는 것은 목표가 아니다. -이 프로젝트의 성공 기준은 단순 실행 성공이 아니다. 기능은 요구조건, 정식화, I/O 계약, C++ 테스트, reference comparison, physics sanity, release readiness를 모두 통과해야 완료된다. +이 프로젝트의 성공 기준은 단순 실행 성공이 아니다. 기능 구현은 요구조건, 정식화, +I/O 계약, C++ build/test와 기능별 blocking reference comparison을 통과해야 완료된다. +Physics sanity와 release readiness는 구현 완료 뒤 별도 배포 판단을 제공하며 Abaqus 내부 +동작 동등성을 요구하지 않는다. ## 사용자 - Solver developer: C++17/MSVC/CMake/CTest 환경에서 요소, 재료, 해석 절차, solver backend를 구현한다. @@ -31,7 +37,9 @@ Element/material 계층의 일반적인 runtime polymorphism, iterative solver, 3. 해석 procedure는 active model view, DOF/equation map과 sparse system을 만들고, essential constraint elimination을 적용해 선형계를 factorize하고 substitution한다. 4. FESA는 full displacement를 복구하고 equilibrium residual/reaction과 element 결과를 계산한다. 5. 성공 시 output request와 무관한 mandatory 결과, metadata와 diagnostic을 versioned `results.h5`에 기록한다. 실패 시 불완전한 최종 결과 파일을 정상 결과처럼 남기지 않는다. -6. 검증 workflow는 HDF5 row를 승인된 Abaqus reference CSV identity에 투영해 tolerance를 판정하고, 별도로 equilibrium과 물리적 타당성을 검토한다. +6. 검증 workflow는 기능이 지정한 HDF5 quantity를 기존 Abaqus CSV의 source identity와 + component에 대응시켜 tolerance를 판정하고, 별도로 equilibrium과 물리적 타당성을 + 검토한다. Reference bundle naming이나 provenance는 수치 비교 gate가 아니다. Parser keyword, element kernel, solver backend 또는 output dataset 중 하나만 추가된 상태는 end-to-end 제품 기능이 아니다. 같은 기능의 입력 의미부터 외부 결과와 검증까지 연결되어야 한다. @@ -76,12 +84,15 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나 새로운 element, load, constraint, material, analysis procedure 또는 output quantity는 다음 조건을 모두 만족할 때 FESA 제품 기능으로 취급한다. -1. 지원 범위와 제외 범위, 실패 category, units/coordinates/identity, tolerance가 요구조건과 I/O 계약에 명시되어 있다. +1. 지원 범위와 제외 범위, 실패 category, solver output의 units/coordinates/identity, + blocking reference quantity와 tolerance가 요구조건과 I/O 계약에 명시되어 있다. 2. 필요한 FEM 정식화와 recovery/sign convention이 검토되었고, 수치 위험과 검증 문제를 numerical review가 다룬다. 3. Syntax와 semantic mapping이 내부 모델에 안정된 source identity로 연결되며 잘못된 입력을 fail-closed로 거부한다. Kernel만 제공하는 기능은 parser/CLI 지원 여부를 별도로 표시한다. 4. DOF, sparse pattern, assembly, constraint, solver lifecycle과 mutable state ownership이 기존 아키텍처에 연결되거나 승인된 새 procedure 경계를 가진다. 5. Mandatory HDF5 schema와 diagnostic, CLI 실패 의미가 정의되고 failure path가 기존 state 또는 최종 output을 오염시키지 않는다. -6. Unit test가 local 수식과 validation을, integration test가 orchestration과 외부 계약을, reference comparison과 physics sanity가 수치·물리 타당성을 각각 증명한다. Reference가 N/A이면 그 이유와 대체 evidence를 명시한다. +6. Unit test가 local 수식과 validation을, integration test가 orchestration과 외부 계약을, + required reference comparison이 기능별 blocking quantity의 외부 수치 acceptance를 + 각각 증명한다. Reference가 N/A이면 그 이유와 대체 evidence를 명시한다. ## 기능 요구조건 | ID | 요구조건 | Acceptance Criteria | Verification Method | @@ -92,10 +103,10 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나 | FESA-PRD-004 | FESA는 equation numbering과 constraint/free mapping을 `DofManager`에 집중해야 한다. | Node/Element 내부에 equation id를 분산 저장하지 않는다. | code review, DofManager unit test | | FESA-PRD-005 | FESA는 해석 중 변하는 물리량을 `AnalysisState`에 저장해야 한다. | V0 displacement, external/internal force, residual, constrained reaction, step/frame identity와 element recovery rows가 출력에 연결되고 velocity, acceleration, temperature, iteration history는 할당하지 않는다. | state unit test, integration test | | FESA-PRD-006 | FESA는 solver 결과를 HDF5 authoritative output `results.h5`로 저장해야 한다. | V0 step/frame field results, metadata, diagnostics가 schema version과 함께 저장된다. | HDF5 schema test | -| FESA-PRD-007 | FESA는 Abaqus reference CSV rows와 비교 가능한 deterministic row mapping을 제공해야 한다. | displacement와 reaction은 node identity, B33 section resultant는 정규화된 node station identity로 비교하고 stress reference comparison은 N/A로 기록한다. | reference comparison report | +| FESA-PRD-007 | FESA는 기능이 지정한 Abaqus reference CSV quantity와 비교 가능한 deterministic source-row/component mapping을 제공해야 한다. | Required source IDs/components는 일대일 대응되고 missing/extra/duplicate/nonfinite row는 tolerance 전에 실패한다. Canonical naming, README, metadata, provenance 또는 CSV schema version은 요구하지 않는다. | reference comparison report | | FESA-PRD-008 | FESA의 production C++ 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현해야 한다. | 관련 C++ test file, RED 실패와 후속 GREEN 성공 증거가 있고 Stop의 전체 MSVC build/test가 통과한다. | implementation report, Hook guardrail, CTest | | FESA-PRD-009 | FESA는 외부 라이브러리 API를 solver core에 직접 노출하지 않아야 한다. | MKL, TBB, HDF5 의존은 adapter module에 제한된다. | architecture review, dependency review | -| FESA-PRD-010 | FESA 기능 완료는 reference comparison과 physics sanity 통과를 요구해야 한다. | 수치 tolerance와 물리 검토가 모두 pass이고 known limitation이 기록된다. | verification report, physics evaluation report | +| FESA-PRD-010 | FESA 기능 구현 완료는 build/test와 기능별 blocking reference comparison 통과를 요구해야 한다. | Required CTest가 통과하고 선언된 blocking quantity가 승인 tolerance 안에 있다. Physics sanity와 release readiness는 별도 후속 gate다. | build/test report, reference verification report | | FESA-PRD-011 | V0는 입력 파일당 하나의 linear static step과 Abaqus B33 3D Euler beam만 해석해야 한다. | 단일 B33 model은 해석되고, B31과 두 번째 step은 구조화된 unsupported diagnostic으로 거부된다. | parser/semantic unit test, CLI integration test | | FESA-PRD-012 | V0는 Part/Assembly/Instance wrapper와 source identity를 보존해야 한다. | 여러 identity instance의 node/element/set label이 stable internal ID로 deterministic하게 매핑되고 transform 또는 nested assembly는 거부된다. | semantic mapping unit test | | FESA-PRD-013 | Output-request allowlist는 해석 의미를 변경하지 않아야 한다. | 승인 keyword와 variable data는 warning 후 no-op이고, allowlist 밖 model-affecting keyword는 오류이며 기본 결과는 output request와 무관하게 생성된다. | parser diagnostic test, HDF5 integration test | @@ -103,7 +114,7 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나 | FESA-PRD-015 | FESA는 V0 결과와 diagnostic을 안정된 외부 계약으로 출력해야 한다. | CLI가 `0=success`, `2=usage`, `3=input`, `4=model`, `5=solver`, `6=HDF5` exit code를 사용하고 diagnostic field가 계약과 일치하며 HDF5가 displacement, reaction, end force, section resultant, generalized strain/resultant, axial `S11`을 포함하고 실패 시 불완전한 최종 파일을 남기지 않는다. | CLI integration test, HDF5 schema/atomicity test | | FESA-PRD-016 | Dense와 sparse math storage 및 backend 경계를 분리해야 한다. | `Vector`는 contiguous, `Matrix`는 row-major contiguous storage와 MKL CBLAS를 사용하고 `SparseMatrix`는 별도 0-based CSR 타입이며 MKL 타입이 public core API에 노출되지 않는다. | math unit test, dependency review | | FESA-PRD-017 | B33 reference comparison은 component-scale 혼합 tolerance를 사용해야 한다. | 모든 matched row가 `abs_error <= absolute_floor + 1e-6 * reference_scale`을 만족하고 missing/extra/nonfinite row는 comparison 전에 실패한다. | reference comparison unit/integration test, verification report | -| FESA-PRD-018 | 승인된 B33 reference artifact는 read-only baseline으로 유지해야 한다. | `reference/cantilever beam/` 파일을 rename, rewrite, 보정하지 않고 exact legacy path로 읽으며 B33 element type과 expected headers를 artifact check에서 확인한다. | artifact inventory, Git diff review | +| FESA-PRD-018 | 승인된 B33 reference artifact는 현재 경로의 read-only baseline으로 유지해야 한다. | `reference/cantilever beam/` 파일을 rename, rewrite 또는 보정하지 않고 기능이 선언한 exact path에서 읽는다. | artifact inventory, Git diff review | | FESA-PRD-019 | B33 beam section과 local axis를 Abaqus 의미에 맞게 매핑해야 한다. | `n1 -> local y`, `t x n1 -> local z`, `Iy=I11`, `Iz=I22`, `I12=0`을 적용하고 nonpositive property, zero-length element, tangent-parallel guide vector를 구조화된 model diagnostic으로 거부한다. | section-mapping unit test, element geometry test | ## 비기능 요구조건 @@ -113,6 +124,8 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나 - B33 reference tolerance는 model, step/frame, quantity, component별 Abaqus scale만 사용한다. - 승인된 SI B33 bundle의 absolute floor는 displacement/rotation `1e-9`, force/moment `1e-3`이며 relative coefficient는 `1e-6`이다. +- MITC4 U/UR comparison은 같은 component-scale 형식을 사용한다. `U1/U2/U3`만 + blocking이고 `UR1/UR2/UR3` 초과는 warning-only다. - parser, solver, HDF5 writer는 실패 원인을 구조화된 diagnostic으로 보고한다. - oneMKL, oneTBB, HDF5는 CMake에서 명시 탐지하고 실패 원인을 분류한다. - 대규모 모델 성능 최적화보다 V0의 명확성, 테스트 가능성, 검증 traceability를 우선한다. @@ -121,10 +134,12 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나 1. Requirements approved: 기능 범위, 제외 범위, 입력, 출력, tolerance, 검증 물리량이 정의되어 있다. 2. Research evidence complete: 정식화와 benchmark 근거가 신뢰도와 한계와 함께 정리되어 있다. 3. Formulation reviewed: 약형, shape function, B matrix, constitutive contract, 수치적분, output recovery가 검토되어 있다. -4. I/O contract approved: Abaqus keyword subset, internal model mapping, HDF5 result contract, reference CSV comparison row contract가 승인되어 있다. +4. I/O contract approved: Abaqus keyword subset, internal model mapping, HDF5 result contract, + required reference quantity의 최소 source-ID/component matching이 승인되어 있다. 5. Tests fail before implementation: C++/integration/reference test를 제품 코드보다 먼저 작성하고 같은 Step 안에서 RED 실패와 후속 GREEN 성공을 확인한다. 6. CMake/CTest pass: MSVC/x64/Debug 기준 configure, build, test가 통과한다. -7. Reference comparison pass: FESA `results.h5`의 displacement, reaction, section resultant rows가 승인된 B33 CSV와 documented identity 및 component-scale 혼합 tolerance 안에 있다. Beam stress comparison은 명시적 N/A다. +7. Reference comparison pass: 기능이 blocking으로 선언한 FESA `results.h5` quantity가 + 선언된 Abaqus CSV와 source identity/component별로 대응되고 승인된 tolerance 안에 있다. 8. Physics sanity pass: equilibrium, reaction consistency, displacement direction, symmetry, section-force consistency와 normalized residual이 검토되어 있다. 9. Release readiness pass: acceptance traceability, known limitations, release notes draft가 준비되어 있다. diff --git a/docs/SOLVER_AGENT_DESIGN.md b/docs/SOLVER_AGENT_DESIGN.md index d931cd2..985618f 100644 --- a/docs/SOLVER_AGENT_DESIGN.md +++ b/docs/SOLVER_AGENT_DESIGN.md @@ -9,7 +9,11 @@ - 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다. - 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다. - 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다. -- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `reference//`에 저장된 `model.inp`와 Abaqus reference CSV files를 검증 기준으로 사용하고, 선택 `metadata.json`이 존재하면 read-only 보조 자료로 계약과 대조한다. +- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. 기능이 선언한 기존 `.inp`와 실제 + 비교에 필요한 Abaqus CSV만 read-only 검증 기준으로 사용한다. Canonical naming, + README, metadata, version 또는 provenance는 기본 readiness 조건이 아니다. +- FESA는 Abaqus와 독립적인 solver다. Agent는 Abaqus 내부 formulation, integration, + stabilization 또는 recovery equivalence를 요구하거나 추론하지 않는다. - 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다. - 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다. - Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다. @@ -111,12 +115,13 @@ - 단위와 좌표계 규약 ### Reference Model Agent -TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다. +TDD와 검증에 사용할 기존 reference case를 inventory하는 Agent이다. 책임: -- 개발 대상 기능을 검증할 최소 모델, benchmark 모델, 회귀 모델을 설계한다. -- `reference//`에 보관할 Abaqus input file, metadata, Abaqus reference CSV 요구사항을 정의한다. -- 레퍼런스 결과에 포함될 물리량과 tolerance를 명시한다. +- 기능이 요구할 때만 테스트 모델 목적을 구분하고, 기본적으로 기존 case를 사용한다. +- 기존 reference case의 목적, exact input/required CSV path, blocking/warning quantity와 + tolerance를 inventory한다. +- FESA HDF5 quantity와 source ID/component matching을 명시한다. - 테스트 모델이 요구조건을 실제로 검증하는지 확인한다. 중요 제약: @@ -124,18 +129,17 @@ TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다. - Abaqus 해석 결과 CSV는 사람이 생성하거나 별도 승인된 절차로 생성해 `reference//`에 저장한다. - Agent는 저장된 reference artifact만 사용해 비교한다. -권장 reference 구조: +최소 reference case 구조: ```text reference/ - / - model.inp - metadata.json # optional - _displacements.csv - _reactions.csv - _internalforces.csv - _stresses.csv + / + .inp + .csv ``` +Directory와 filename은 제공된 값을 그대로 사용한다. Reference Model Agent는 canonical +이름, README, metadata, provenance 또는 비교하지 않는 quantity CSV를 요구하지 않는다. + ### Implementation Planning Agent 코드 구현 전에 작업 단위와 테스트 순서를 설계하는 Agent이다. @@ -150,6 +154,15 @@ reference/ - 테스트 우선순위 - 변경 파일 후보 - acceptance checklist +- 사용자 승인 전 multi-Step Harness 초안 +- 승인 후 `phases/index.json`, `phases//index.json`, 자기완결적 `stepN.md` + +필수 절차: +- 구현 계획 요청에서 project-local `$harness` skill을 사용한다. +- 한 Step은 하나의 layer/module만 다루고 각 Step에 prerequisite file, TDD + RED/GREEN/VERIFY, 정확한 MSVC/CMake/CTest command와 금지사항을 포함한다. +- Step 초안을 먼저 사용자에게 제시한다. 승인 전에는 `phases/` 파일을 생성하지 않는다. +- Harness executor 실행은 별도 사용자 요청이 있을 때만 수행한다. ### Implementation Agent C++ 코드를 구현하는 Agent이다. @@ -251,7 +264,7 @@ Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 선언된 | 2. 연구자료 조사 | Research Agent | 자료 요약, benchmark 후보 | | 3. 유한요소 정식화 | Formulation Agent, Numerical Review Agent | 정식화 문서, 리뷰 결과 | | 4. 입출력 데이터 정의 | I/O Definition Agent | 입력/출력 schema | -| 5. TDD 테스트모델 작성 | Reference Model Agent, Implementation Planning Agent | 테스트 모델, reference artifact 요구사항 | +| 5. Reference case 준비 | Reference Model Agent, Implementation Planning Agent | 기존 input/required CSV inventory, 비교 mapping, tolerance | | 6. 코드 구현 | Implementation Agent | C++ 코드, 테스트 | | 7. 레퍼런스 결과 비교 검증 | Reference Verification Agent, Physics Evaluation Agent | 비교 리포트, 물리 검토 | | 8. tolerance 만족 시 완료 | Coordinator Agent | 기능 완료 승인 | @@ -275,8 +288,7 @@ flowchart TD L --> I K -- "예" --> M["Reference Verification Agent"] M --> N{"tolerance 만족?"} - N -- "아니오" --> O["Physics Evaluation Agent"] - O --> L + N -- "아니오" --> L N -- "예" --> P["Physics Evaluation Agent"] P --> Q{"물리 검토 통과?"} Q -- "아니오" --> L @@ -300,8 +312,8 @@ flowchart TD ### Gate 3: 테스트 준비 승인 통과 조건: - 구현 전 실패해야 하는 테스트가 정의되어 있다. -- `reference//` artifact 요구사항이 명확하다. -- 최소 모델, benchmark 모델, 회귀 모델의 목적이 구분되어 있다. +- 기능이 요구하는 기존 input/CSV pair와 blocking/warning quantity가 명확하다. +- 필요한 source ID/component matching과 tolerance가 정의되어 있다. ### Gate 4: 구현 검증 통과 조건: @@ -312,9 +324,10 @@ flowchart TD ### Gate 5: 레퍼런스 검증 통과 조건: -- Abaqus reference CSV 결과와 구현 solver HDF5 결과가 tolerance 안에 있다. -- 절점 변위, 반력, 요소 내력, 응력 비교 결과가 리포트로 남아 있다. -- 실패한 물리량이 없거나 승인된 known limitation으로 기록되어 있다. +- 기능이 blocking으로 선언한 Abaqus CSV quantity와 구현 solver HDF5 quantity가 + tolerance 안에 있다. +- Warning-only quantity는 결과와 경고가 리포트에 남고 pass/fail을 바꾸지 않는다. +- Required source row/component의 누락, 추가, 중복 또는 nonfinite 값이 없다. ### Gate 6: 배포 승인 통과 조건: @@ -371,6 +384,8 @@ Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Defin ## 운영 메모 - Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다. -- 사람이 생성한 Abaqus reference artifact의 출처와 생성 조건은 승인된 기능별 Reference Model Contract에 기록한다. 선택 `metadata.json`이 존재하면 read-only로 참고하고 계약과의 충돌을 보고한다. +- 사람이 제공한 Abaqus reference artifact는 현재 path/name 그대로 read-only로 사용한다. + 별도 provenance, README 또는 metadata가 없다는 이유로 gate를 차단하지 않는다. - reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다. -- 기능 완료 판정은 코드 실행 성공이 아니라 reference validation과 physics evaluation 통과를 기준으로 한다. +- 기능 구현 완료 판정은 build/test와 기능별 blocking reference validation 통과를 기준으로 + 한다. Physics evaluation과 release readiness는 별도 후속 배포 gate다. diff --git a/docs/SOLVER_SKILL_DESIGN.md b/docs/SOLVER_SKILL_DESIGN.md index 518980b..3704c3a 100644 --- a/docs/SOLVER_SKILL_DESIGN.md +++ b/docs/SOLVER_SKILL_DESIGN.md @@ -42,8 +42,11 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 3. Formulation Agent는 `fesa-formulation-spec`을 사용해 strong form, weak form, shape functions, B matrix, element stiffness, output recovery를 정리한다. 4. Numerical Review Agent는 `fesa-numerical-review`를 사용해 rigid body modes, patch test, stiffness symmetry, Jacobian, locking 위험을 검토하고 `pass-for-implementation-planning` 여부를 판단한다. 5. I/O Definition Agent는 `fesa-io-contract`를 사용해 지원할 Abaqus `.inp` keyword subset, `results.h5` schema, reference CSV comparison row schema를 정의한다. -6. Reference Model Agent는 `fesa-reference-models`를 사용해 `reference//` artifact bundle 계약과 coverage matrix를 작성한다. -7. Implementation Planning Agent와 Implementation Agent는 `fesa-cpp-msvc-tdd`를 사용해 테스트 작성, 실패 확인, 최소 구현, CMake/CTest 등록, validation을 수행한다. +6. Reference Model Agent는 `fesa-reference-models`를 사용해 기존 input/required CSV + reference-case inventory와 비교 mapping을 작성한다. +7. Implementation Planning Agent는 먼저 project-local `harness`를 사용해 사용자 승인용 + multi-Step 초안을 만들고, 승인 후 phase files를 생성한다. 그 뒤 Implementation Agent와 + 함께 `fesa-cpp-msvc-tdd` 계약에 따라 RED/GREEN/VERIFY를 수행한다. 8. Reference Verification Agent는 `fesa-reference-comparison`을 사용해 구현 solver `results.h5` rows와 Abaqus reference CSV rows를 tolerance 기준으로 비교한다. 9. Physics Evaluation Agent는 `fesa-physics-sanity`를 사용해 global equilibrium, reaction consistency, displacement direction, symmetry, model coverage를 검토한다. 10. Release Agent는 `fesa-release-readiness`를 사용해 gate evidence, acceptance traceability, known limitations, release notes draft를 작성한다. @@ -77,6 +80,8 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 - dimensions, signs, DOF ordering, coordinate transforms, Jacobian, integration rule, stiffness symmetry, rigid body modes, patch test, hourglass, locking을 확인한다. - `pass-for-implementation-planning`은 구현 계획 가능 상태만 의미한다. - 정식화 문서를 직접 수정하지 않는다. +- 이후 Reference Model 문서, artifact naming, README, metadata, provenance 또는 portfolio가 + 없다는 이유로 formulation verdict를 실패시키지 않는다. ### `fesa-io-contract` @@ -87,10 +92,11 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 ### `fesa-reference-models` -- smoke, analytical, patch test, benchmark, regression, negative/invalid-input 모델을 구분한다. -- `reference//` artifact bundle 계약을 정의한다. -- `model.inp`와 요구된 `_displacements.csv`, `_reactions.csv`, `_internalforces.csv`, `_stresses.csv`를 기준 artifact로 둔다. 필수 provenance는 Reference Model Contract에 기록하고, 선택 `metadata.json`이 존재하면 read-only로 대조한다. -- required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts`로 둔다. +- 기능이 실제로 사용하는 기존 reference case를 inventory한다. +- Exact input/required CSV path, case purpose, blocking/warning quantity, HDF5 projection, + source ID/component matching과 tolerance만 정의한다. +- Required comparison file이 없을 때만 `needs-reference-artifacts`로 둔다. Canonical naming, + README, metadata, provenance와 비교하지 않는 quantity CSV는 요구하지 않는다. ### `fesa-cpp-msvc-tdd` @@ -115,10 +121,21 @@ uv run --with pytest python -m pytest -v -rs - 실패는 `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`로 분류한다. - 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 바꾸지 않는다. +### project-local `harness` + +- Implementation Planning Agent가 구현 요청을 여러 독립 Step으로 분해할 때 사용한다. +- 한 Step은 하나의 layer/module만 소유하고 prerequisite file, TDD RED/GREEN/VERIFY, + exact acceptance command와 구체적 금지사항을 포함한다. +- 사용자에게 Step 초안을 먼저 제시한다. 승인 후에만 `phases/index.json`, + `phases//index.json`, `phases//stepN.md`를 생성한다. +- 계획 작성과 executor 실행을 구분하며, `scripts/execute.py`는 별도 사용자 요청 없이 + 실행하지 않는다. + ### `fesa-reference-comparison` - `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` 순서로 수행한다. -- `model.inp`, `results.h5`, Abaqus reference CSV files, Reference Model Contract의 provenance, schema version, units, coordinate system, step/frame identity, ID matching, output location, tolerance source를 확인한다. 선택 `metadata.json`이 존재하면 inventory하고 계약과 대조하되, 부재만으로 비교를 중단하지 않는다. +- 선언된 input, required Abaqus CSV, `results.h5`, source ID/component mapping과 tolerance를 + 확인한다. Missing/extra/duplicate/nonfinite required row는 비교 전에 실패한다. - max absolute error, max relative error, RMS error, norm error, missing rows, extra rows를 보고한다. - Reference pass는 physics validation이나 release readiness를 의미하지 않는다. @@ -147,7 +164,7 @@ uv run --with pytest python -m pytest -v -rs | Numerical Review Agent | `fesa-numerical-review` | | I/O Definition Agent | `fesa-io-contract` | | Reference Model Agent | `fesa-reference-models` | -| Implementation Planning Agent | `fesa-formulation-spec`, `fesa-reference-models`, `fesa-cpp-msvc-tdd` | +| Implementation Planning Agent | project-local `harness`, `fesa-formulation-spec`, `fesa-reference-models`, `fesa-cpp-msvc-tdd` | | Implementation Agent | `fesa-cpp-msvc-tdd` | | Build/Test Executor Agent | `fesa-cpp-msvc-tdd` | | Correction Agent | `fesa-cpp-msvc-tdd` |