modify docu

2026-06-11 17:18:03 +09:00
parent c4f8f95d4b
commit 742f311be1
66 changed files with 3354 additions and 375 deletions
@@ -105,7 +105,9 @@ references/
    <model-id>/
      model.inp
      metadata.json
-      expected.h5 or reference CSV views
+      reference.h5
+      csv/
+        deterministic comparison views
 ```

 ### 모듈 경계 원칙
@@ -118,16 +120,210 @@ references/
 - `analysis`는 step/history data를 받아 procedure를 실행하고, solver backend와 result writer를 조율한다.
 - `results`는 HDF5 schema를 통해 nodal, element, integration-point, diagnostic output을 분리한다.

+## 핵심 클래스 구조 후보
+아래 구조는 `docs/ARCHITECTURE.md`에 반영할 개념적 class map이다. `1DElement`, `2DElement`, `3DElement` 같은 이름은 분류 표현이며, 실제 C++ 식별자는 `Element1D`처럼 유효한 이름으로 확정한다.
+
+```text
+Domain
+├── Node
+├── Element
+├── Material
+├── Property
+├── NodeSet
+├── ElementSet
+├── BoundaryCondition
+├── Load
+└── StepDefinition
+
+AnalysisModel
+├── active elements
+├── active loads
+├── active boundary conditions
+├── active properties/materials
+└── equation system view
+
+AnalysisState
+├── displacement U
+├── velocity V
+├── acceleration A
+├── temperature T
+├── external force Fext
+├── internal force Fint
+├── residual R
+├── current time / increment / iteration
+└── element state / integration point state
+
+DofManager
+├── node dof definitions
+├── constrained/free dof mapping
+├── equation numbering
+├── sparse matrix pattern ownership
+└── full/reduced vector reconstruction
+
+Analysis
+├── LinearStaticAnalysis
+├── NonlinearStaticAnalysis
+├── DynamicAnalysis
+├── FrequencyAnalysis
+└── HeatTransferAnalysis
+
+Element
+├── 1DElement
+│   ├── Truss
+│   └── Beam
+├── 2DElement
+│   ├── MITC3
+│   └── MITC4
+└── 3DElement
+    ├── Hexahedral
+    ├── Tetrahedral
+    ├── Wedge
+    └── Pyramid
+
+BoundaryCondition
+├── Fix
+├── RBE2
+└── RBE3
+
+Load
+├── NodalLoad
+├── PressureLoad
+└── BodyForce
+
+Results
+├── ResultStep
+├── ResultFrame
+├── FieldOutput
+└── HistoryOutput
+
+InputParser
+ResultsWriter
+Assembler
+LinearSolver
+Vector
+Matrix
+SparseMatrix
+```
+
+문서화 시 핵심 책임은 다음처럼 구분한다.
+- `Domain`은 입력 파일에서 생성된 전체 모델 정의를 소유한다.
+- `AnalysisModel`은 현재 step에서 활성화된 해석 객체 view를 제공한다.
+- `DofManager`는 자유도 정의, 제약/free mapping, equation numbering, sparse pattern ownership을 전담한다.
+- `AnalysisState`는 해석 중 변하는 물리량과 반복 상태를 소유한다.
+- `Analysis` 계층은 procedure별 실행 전략을 제공한다.
+- `Element`, `Material`, `Load`, `BoundaryCondition`은 base interface를 통해 다루되, Phase 1에서는 명확성과 테스트 가능성을 성능 최적화보다 우선한다.
+
 ## 권장 설계 패턴
- Strategy: linear solver backend, nonlinear convergence policy, constraint handling, time integration, output backend를 교체 가능한 전략으로 둔다.
- Factory/Registry: Abaqus keyword, element type, material type을 내부 semantic object로 생성한다. 초기에는 compile-time/static registry로 충분하며 동적 plugin은 문서 범위에서 제외한다.
- Template Method: element routine은 `gather state -> evaluate quadrature -> accumulate local matrix/vector -> recover output` 순서를 공유하되 요소별 shape function과 constitutive contract를 분리한다.
- Adapter: MKL PARDISO, oneTBB, HDF5, Abaqus syntax를 내부 core API에서 직접 노출하지 않는다.
+- Strategy Pattern: 해석 알고리즘과 수치 알고리즘을 교체 가능하게 구성한다.
+  - `Analysis`: `LinearStaticAnalysis`, `NonlinearStaticAnalysis`, `DynamicAnalysis`, `HeatTransferAnalysis`
+  - `LinearSolver`: `MKLPardisoSolver`, 향후 iterative solver
+  - `TimeIntegrator`: `HHTIntegrator`, 향후 Newmark 등
+  - `ConvergenceCriteria`: residual norm, displacement norm, energy norm
+- Template Method Pattern: 해석 실행의 큰 흐름은 `Analysis::run()`에서 고정하고, 세부 단계는 해석 종류별로 재정의한다.
+  ```text
+  initialize
+  buildAnalysisModel
+  buildDofMap
+  buildSparsePattern
+  assemble
+  applyBoundaryConditions
+  solve
+  updateState
+  writeResults
+  ```
+  비선형 정적해석은 위 흐름을 Newton-Raphson 반복 루프 안에서 사용하고, 동적해석은 time step/frame 루프 안에서 사용한다.
+- Factory + Registry Pattern: Abaqus input keyword와 내부 객체 생성을 분리한다.
+  - `*Element, type=S4` -> `MITC4ElementFactory`
+  - `*Material`, `*Elastic` -> `LinearElasticMaterialFactory`
+  - `*Boundary` -> `FixBoundaryFactory`
+  - `*Cload` -> `NodalLoadFactory`
+  - `*Nset`, `*Elset` -> set registry
+  요소, 재료, 하중, 경계조건 타입 추가 시 parser 본체의 변경을 최소화한다.
+- Adapter Pattern: MKL, TBB, HDF5 API는 solver core에 직접 노출하지 않는다.
+  - `SparseMatrix`, `Vector`, `Matrix`
+  - `LinearSolver`
+  - `ParallelFor`
+  - `ResultsWriter`
+  외부 라이브러리 교체 또는 테스트 double 사용이 가능하도록 adapter 계층에서 의존성을 제한한다.
+- Runtime Polymorphism: 요소, 재료, 하중, 경계조건은 base interface를 통해 다룬다. Phase 1에서는 명확성과 테스트 가능성을 우선하고, 대규모 모델 성능 최적화가 필요할 경우 assembly 내부에서 타입별 batch 처리 또는 kernel 분리를 추가한다.
 - RAII: MKL handle, HDF5 file/dataset, temporary solver workspace는 수명과 오류 처리를 wrapper에 묶는다.
 - Data-oriented core: global vectors, sparse matrix arrays, DOF maps, element connectivity는 cache locality와 deterministic assembly를 우선한다.
 - Deterministic assembly: TBB element loop는 thread-local contribution buffer 또는 two-pass sparse assembly를 사용해 reference comparison의 재현성을 해치지 않도록 한다.
 - Explicit diagnostics: parser warning, unsupported keyword, singular matrix, rigid body mode, convergence failure, HDF5 schema mismatch를 구조화된 diagnostic으로 남긴다.

+## 상태 관리 모델
+
+### 1. `Domain`
+`Domain`은 입력 파일에서 만들어진 전체 모델 정의를 소유한다. 파싱 이후에는 가능한 한 불변으로 취급한다.
+
+포함 대상:
+- nodes, elements
+- materials, properties
+- node sets, element sets
+- loads, boundary conditions
+- analysis step definitions
+
+### 2. `AnalysisModel`
+`AnalysisModel`은 현재 step에서 활성화되는 해석 객체들의 실행 view이다. `Domain`을 복사하지 않고 참조 또는 id 기반 view로 구성한다.
+
+포함 대상:
+- active elements
+- active loads
+- active boundary conditions
+- active property/material references
+- current equation system view
+
+### 3. `DofManager`
+`DofManager`는 자유도와 방정식 번호를 전담한다. `Node` 또는 `Element` 내부에 equation id를 분산 저장하지 않는다.
+
+책임:
+- node별 활성 자유도 정의
+- constrained/free dof mapping
+- equation numbering
+- sparse matrix pattern 생성에 필요한 connectivity 제공
+- 경계조건 적용 전후의 dof view 관리
+- full/reduced vector reconstruction
+
+### 4. `AnalysisState`
+`AnalysisState`는 해석 중 변하는 물리량과 반복 상태를 소유한다.
+
+포함 대상:
+- displacement, velocity, acceleration
+- temperature
+- external force, internal force, residual
+- current time, increment, Newton iteration
+- element state, integration point state
+
+Phase 1에서는 displacement 중심으로 최소 구현하되, 기하비선형과 thermal-stress coupling을 위해 element/internal state 확장 지점을 유지한다.
+
+### 5. Results State
+결과는 `ResultStep` -> `ResultFrame` -> `FieldOutput`/`HistoryOutput` 구조로 관리한다.
+
+- `ResultStep`: 해석 step 단위 결과
+- `ResultFrame`: 정적해석의 load increment 또는 동적해석의 time frame
+- `FieldOutput`: node/element field 결과
+- `HistoryOutput`: 특정 node, element, set, reaction, energy 등의 이력 결과
+
+## 권장 데이터 흐름
+`docs/ARCHITECTURE.md`에는 아래 흐름을 solver 실행의 표준 경로로 반영한다.
+
+```text
+Abaqus input file
+-> InputParser
+-> Domain 생성
+-> StepDefinition 루프
+-> AnalysisModel 생성
+-> DofManager로 자유도/방정식 번호 생성
+-> sparse pattern 생성
+-> Analysis 실행
+-> Assembler로 전역 행렬/벡터 조립
+-> BoundaryCondition 적용
+-> LinearSolver 또는 nonlinear/time integration loop
+-> AnalysisState 갱신
+-> ResultsWriter로 step/frame/history 저장
+-> 다음 step 진행
+```
+
 ## 세 문서별 완성 계획

 ### 1. `AGENTS.md`
@@ -294,14 +490,15 @@ references/
 | 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `docs/physics-evaluations/<feature-id>-physics-evaluation.md` |
 | 배포 준비 | `release-agent` | `fesa-release-readiness` | `docs/releases/<feature-id>-release.md` |

-## HDF5와 기존 CSV reference skill의 정합성 이슈
-현재 프로젝트 문서와 skill은 reference comparison artifact로 CSV를 많이 언급한다. 사용자 요구조건은 solver 결과 저장 포맷을 HDF5로 지정한다.
+## HDF5와 deterministic CSV view 정합성 결정
+프로젝트 문서와 skill의 reference comparison 경로는 HDF5 authoritative output과 deterministic CSV view 구조를 기준으로 정리한다.

-권장 결정:
+결정:
 - FESA solver의 정식 결과 파일은 HDF5로 한다.
- reference comparison을 위해 HDF5 dataset에서 deterministic CSV view를 추출하거나, comparison tool이 HDF5와 reference CSV를 직접 비교하도록 한다.
- `docs/PRD.md`와 `docs/ARCHITECTURE.md`에는 "HDF5 authoritative output, CSV comparison view optional"을 명시한다.
- 기존 `fesa-reference-comparison` skill은 즉시 바꾸기보다, 문서에서 HDF5 support extension을 후속 작업으로 기록한다.
+- solver output은 `results.h5`, stored reference output은 `reference.h5`를 authoritative artifact로 둔다.
+- reference comparison을 위해 HDF5 dataset에서 `csv/displacements.csv`, `csv/reactions.csv`, `csv/element_forces.csv`, `csv/stresses.csv` 같은 deterministic CSV view를 추출할 수 있다.
+- CSV view는 row identity와 사람이 검토 가능한 비교 view일 뿐이며 authoritative storage가 아니다.
+- `fesa-reference-comparison`, `fesa-io-contract`, `fesa-reference-models`, 관련 agent 문서는 이 구조를 기준으로 유지한다.

 ## 주요 리스크와 열린 질문
 - 첫 end-to-end feature를 1D truss/bar로 확정할지, 2D plane stress까지 포함할지 결정이 필요하다. 문서 계획상 v0는 1D truss/bar가 가장 안전하다.
@@ -335,5 +532,5 @@ references/
 - HDF5 result schema ADR 작성.
 - Abaqus `.inp` v0 keyword subset ADR 작성.
 - MKL/TBB threading policy ADR 작성.
- `fesa-reference-comparison` skill의 HDF5 comparison 확장 계획 작성.
+- HDF5 result schema와 deterministic CSV view exporter의 구체 schema/test 작성.
 - 첫 기능 `linear-truss-1d`의 `docs/requirements/linear-truss-1d.md` 작성.