modify docu

2026-06-11 17:18:03 +09:00
parent c4f8f95d4b
commit 742f311be1
66 changed files with 3354 additions and 375 deletions
@@ -1,31 +1,242 @@
 # 아키텍처

 ## 목표
-이 저장소의 현재 책임은 C++/MSVC 프로젝트를 위한 Codex Harness scaffold를 제공하는 것이다. Harness는 phase execution, edit guard, commit validation, workspace validation을 분리해서 관리한다.
+FESA의 아키텍처 목표는 Abaqus `.inp` subset을 내부 semantic model로 변환하고, 유한요소 equation system을 구성해 구조해석 결과를 HDF5로 저장하며, reference comparison과 physics sanity가 가능한 C++17/MSVC 솔버 구조를 제공하는 것이다.
+
+핵심 품질 속성:
+- FEM formulation traceability
+- explicit I/O contracts
+- sparse linear algebra backend isolation
+- deterministic verification
+- incremental feature addition
+- Harness 기반 TDD와 workspace validation

 ## 디렉토리 구조
 ```text
+src/
+  fesa/
+    core/                 # ids, status, diagnostics, units, small value types
+    io/
+      abaqus/             # .inp lexer/parser, keyword subset, include policy
+      hdf5/               # HDF5 result writer/reader, schema versioning
+    model/                # semantic model: nodes, elements, sets, materials, sections, steps
+    fem/                  # DOF space, equation numbering, quadrature, shape functions
+    elements/             # truss/bar, beam, plane, solid, shell element routines
+    materials/            # elastic/plastic material contracts and state variables
+    assembly/             # local-to-global mapping, sparse pattern, COO/CSR assembly
+    constraints/          # essential BC, MPC, penalty or elimination policies
+    solvers/
+      linear/             # MKL PARDISO backend, iterative backend boundary
+      nonlinear/          # Newton control, residual/tangent norms, increments
+    analysis/             # static, modal, dynamic, nonlinear procedure drivers
+    results/              # recovery, field/history output, diagnostics
+    validation/           # comparison metrics and tolerance helpers
+tests/
+  unit/
+  integration/
+  reference/
+references/
+  <feature-id>/
+    <model-id>/
+      model.inp
+      metadata.json
+      reference.h5
+      csv/
+        deterministic comparison views
 .codex/
-├── hooks/              # Codex hook scripts
-└── skills/             # Harness planning/review instructions
-docs/                   # Project and Harness guidance
+  hooks/                  # Codex hook scripts
+  skills/                 # FESA solver and Harness instructions
+docs/                     # Product, architecture, ADR, workflow artifacts
 scripts/
-├── execute.py          # Phase step executor
-├── validate_workspace.py
-└── test_*.py           # Harness self-tests
-phases/                 # Optional generated phase plans
+  execute.py              # Phase step executor
+  validate_workspace.py   # Default validation entry point
+  test_*.py               # Harness self-tests
+phases/                   # Optional generated phase plans
 ```

+## Harness Execution Layer
+`scripts/execute.py`:
+- creates or checks out `codex/<phase-name>`
+- refuses to run on a dirty worktree
+- requires per-step `allowed_paths`
+- stages only explicit allowed paths and runner housekeeping files
+- runs Python Harness self-tests and workspace validation before every runner-created commit
+
+## 모듈 경계
+- `core`는 외부 라이브러리에 의존하지 않는다.
+- `io/abaqus`는 syntax와 semantic mapping만 담당하고 해석 알고리즘을 알지 않는다.
+- `model`은 Abaqus keyword 문자열이 아니라 solver semantic model을 가진다.
+- `fem`은 DOF, interpolation, quadrature, local/global mapping을 제공하되 특정 analysis procedure에 종속되지 않는다.
+- `elements`와 `materials`는 local residual/tangent/stress recovery 계약을 제공한다.
+- `assembly`는 sparse pattern 생성과 local contribution 조립을 담당한다.
+- `constraints`는 essential BC, MPC, penalty/elimination 정책을 분리한다.
+- `solvers`는 MKL/TBB 세부 구현을 감추는 backend boundary를 가진다.
+- `analysis`는 step/history data를 받아 procedure를 실행하고 solver backend와 result writer를 조율한다.
+- `results`는 HDF5 schema를 통해 nodal, element, integration-point, diagnostic output을 분리한다.
+- test helper는 production parser/solver 내부 상태를 우회하지 않는다.
+
+## 핵심 객체 모델
+```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
+├── Element1D
+│   ├── Truss
+│   └── Beam
+├── Element2D
+│   ├── MITC3
+│   └── MITC4
+└── Element3D
+    ├── Hexahedral
+    ├── Tetrahedral
+    ├── Wedge
+    └── Pyramid
+
+BoundaryCondition
+├── Fix
+├── RBE2
+└── RBE3
+
+Load
+├── NodalLoad
+├── PressureLoad
+└── BodyForce
+
+Results
+├── ResultStep
+├── ResultFrame
+├── FieldOutput
+└── HistoryOutput
+```
+
+## 상태 관리
+- `Domain`은 입력 파일에서 만들어진 전체 모델 정의를 소유한다. 파싱 이후에는 가능한 한 불변으로 취급한다.
+- `AnalysisModel`은 현재 step에서 활성화되는 해석 객체들의 실행 view이다. `Domain`을 복사하지 않고 참조 또는 id 기반 view로 구성한다.
+- `DofManager`는 자유도와 방정식 번호를 전담한다. `Node` 또는 `Element` 내부에 equation id를 분산 저장하지 않는다.
+- `AnalysisState`는 해석 중 변하는 물리량과 반복 상태를 소유한다. Phase 1에서는 displacement 중심으로 최소 구현하되, 기하비선형과 thermal-stress coupling을 위해 element/internal state 확장 지점을 유지한다.
+- 결과는 `ResultStep` -> `ResultFrame` -> `FieldOutput`/`HistoryOutput` 구조로 관리한다.
+
 ## 데이터 흐름
 ```text
-User-approved task
-> Harness phase files under phases/
-> scripts/execute.py injects AGENTS.md and docs/*.md
-> Codex executes one step at a time
-> step updates phases/{phase}/index.json
-> validation runs through scripts/validate_workspace.py
+Abaqus input file
+-> InputParser
+-> Domain 생성
+-> StepDefinition 루프
+-> AnalysisModel 생성
+-> DofManager로 자유도/방정식 번호 생성
+-> sparse pattern 생성
+-> Analysis 실행
+-> Assembler로 전역 행렬/벡터 조립
+-> BoundaryCondition 적용
+-> LinearSolver 또는 nonlinear/time integration loop
+-> AnalysisState 갱신
+-> ResultsWriter로 step/frame/history 저장
+-> 다음 step 진행
 ```

+## 해석 실행 흐름
+`Analysis::run()`은 Template Method로 다음 큰 흐름을 고정한다. 해석 종류별 class는 필요한 단계만 재정의한다.
+
+```text
+initialize
+buildAnalysisModel
+buildDofMap
+buildSparsePattern
+assemble
+applyBoundaryConditions
+solve
+updateState
+writeResults
+```
+
+비선형 정적해석은 이 흐름을 Newton-Raphson 반복 루프 안에서 사용하고, 동적해석은 time step/frame 루프 안에서 사용한다.
+
+## 설계 패턴
+- Strategy Pattern: `Analysis`, `LinearSolver`, `TimeIntegrator`, `ConvergenceCriteria`를 교체 가능한 전략으로 둔다.
+- Template Method Pattern: `Analysis::run()`은 공통 실행 흐름을 고정하고 세부 단계는 procedure별로 재정의한다.
+- Factory + Registry Pattern: Abaqus keyword와 내부 객체 생성을 분리한다. 예: `*Element, type=S4` -> `MITC4ElementFactory`.
+- Adapter Pattern: MKL, TBB, HDF5 API는 solver core에 직접 노출하지 않는다.
+- Runtime Polymorphism: 요소, 재료, 하중, 경계조건은 base interface를 통해 다룬다. 대규모 모델 성능 최적화가 필요하면 assembly 내부에서 타입별 batch 처리 또는 kernel 분리를 추가한다.
+- RAII: MKL handle, HDF5 file/dataset, temporary solver workspace의 수명과 오류 처리를 wrapper에 묶는다.
+
+## Sparse Matrix Policy
+- assembly는 초기에는 COO triplet 수집 후 CSR finalize를 기준으로 한다.
+- `SparseMatrix`는 solver core가 사용하는 추상 contract이고 MKL PARDISO backend는 CSR input contract만 받는다.
+- matrix symmetry, definiteness, singularity diagnostic을 구조화된 diagnostic으로 남긴다.
+- deterministic assembly를 위해 TBB element loop는 thread-local contribution buffer 또는 two-pass sparse assembly를 사용한다.
+
+## Parallel Policy
+- 첫 번째 oneTBB 적용 지점은 element-local matrix/residual 계산이다.
+- 전역 sparse write는 thread-local buffer 또는 deterministic reduction으로 제한한다.
+- MKL 내부 thread와 TBB element loop가 oversubscription을 만들지 않도록 thread count와 task arena 정책을 명시한다.
+
+## HDF5 Result Schema
+```text
+/metadata
+/model/nodes
+/model/elements
+/steps/<step-name>/frames/<frame-id>/nodal/displacement
+/steps/<step-name>/frames/<frame-id>/nodal/reaction
+/steps/<step-name>/frames/<frame-id>/element/stress
+/steps/<step-name>/frames/<frame-id>/element/strain
+/diagnostics
+```
+
+Schema requirements:
+- schema version, units, coordinate system, solver version, source input identity를 metadata에 기록한다.
+- field output과 history output을 구분한다.
+- reference comparison을 위한 row identity는 node id, element id, integration point id, step/frame id를 포함한다.
+- HDF5가 authoritative output이며 CSV는 optional deterministic comparison view이다.
+- Solver output은 `results.h5`, stored reference output은 `reference.h5`, CSV view는 `csv/*.csv` 경로를 기본으로 한다.
+
+## Test Architecture
+- unit: parser, DOF map, shape functions, material law, sparse assembly, HDF5 schema
+- integration: small `.inp` to HDF5 end-to-end
+- reference: stored Abaqus artifact comparison
+- physics: equilibrium, sign, symmetry, rigid body mode, stress sanity
+- harness: hooks, phase executor, workspace validation
+
 ## Hook 흐름
 ```text
 apply_patch/Edit/Write