# 아키텍처

## 목표
FESA는 MITC4 Shell 요소 기반 구조해석에서 시작해 비선형 정적해석, 비선형 동적해석, 열전달 및 thermal-stress coupling, 1D/3D 요소까지 확장하는 유한요소 솔버이다.

초기 구현은 정확도와 테스트 가능성을 우선한다. 단, 대규모 모델을 목표로 하므로 자유도 관리, 희소 행렬 조립, 선형 솔버, 병렬 실행 계층은 초기부터 성능 확장이 가능하도록 분리한다.

## 설계 원칙
- Domain 객체는 입력 모델의 의미를 보존하고 가능한 한 불변에 가깝게 유지한다.
- 해석 중 변하는 물리량과 반복 상태는 AnalysisState에 명시적으로 분리한다.
- 요소, 재료, 하중, 경계조건, 해석 알고리즘은 런타임 다형성 기반으로 확장한다.
- MITC4 구현은 Phase 1에서 정확도와 테스트 가능성을 우선하며, assembly와 solver 계층은 대규모 모델 최적화가 가능하도록 경계를 둔다.
- 결과는 step/frame/field/history 개념으로 저장하여 정적, 비선형, 동적, 열전달 해석을 같은 결과 모델로 다룬다.
- 외부 라이브러리(MKL, TBB, HDF5)는 adapter 계층 뒤에 둔다.
- Abaqus input 호환성은 파서와 factory/registry 계층에서 관리한다. Phase 1의 입력 범위에는 `*Node`, `*Element`, `*Nset`, `*Elset`, `*Material`, `*Elastic`, `*Shell Section`, `*Boundary`, `*Cload`, `*Step`을 포함한다.
- 수치 규약은 `docs/NUMERICAL_CONVENTIONS.md`를 따른다. Phase 1 shell node는 6자유도이고, 단위계는 강제하지 않으며, 결과 부호는 Abaqus 규약을 따른다.
- 경계조건은 constrained DOF 제거 방식으로 적용하고, reaction은 full vector 기준 `K_full * U_full - F_full`로 계산한다.
- 기본 실수 precision은 `double`이고, 대규모 모델을 위해 id/index/equation numbering은 int64 기반으로 설계한다.
- Mesh quality 진단은 Phase 1 범위에서 제외한다. 대신 singular system 진단은 필수로 제공한다.

## 디렉토리 구조
```
src/
├── Analysis/        # Static, nonlinear static, dynamic, heat transfer analysis
├── Assembly/        # 전역 행렬/벡터 조립, sparse pattern 생성
├── Boundary/        # Fix, RBE2, RBE3 등 경계조건
├── Core/            # Domain, AnalysisModel, AnalysisState, DofManager
├── Element/         # Node, Element, MITC4 등 요소 구현
├── IO/              # Abaqus input parser, HDF5 results writer
├── Load/            # NodalLoad, PressureLoad, BodyForce 등 하중
├── Math/            # Vector, Matrix, SparseMatrix, MKL adapter
├── Material/        # LinearElastic 등 재료 모델
├── Property/        # ShellProperty, 1D/2D/3D property
├── Results/         # Step, Frame, FieldOutput, HistoryOutput
└── Util/            # 공통 유틸리티, 로깅, 검증 보조 함수
```

## 핵심 클래스 구조
```
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
```

## 디자인 패턴

### 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()`에서 고정하고, 세부 단계는 해석 종류별로 재정의한다.

기본 흐름:
```
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 분리를 추가한다.

## 상태 관리

### Domain
`Domain`은 입력 파일에서 만들어진 전체 모델 정의를 소유한다. 파싱 이후에는 가능한 한 불변으로 취급한다.

포함 대상:
- nodes, elements
- materials, properties
- node sets, element sets
- loads, boundary conditions
- analysis step definitions

### AnalysisModel
`AnalysisModel`은 현재 step에서 활성화되는 해석 객체들의 실행 view이다. `Domain`을 복사하지 않고 참조 또는 id 기반 view로 구성한다.

포함 대상:
- active elements
- active loads
- active boundary conditions
- active property/material references
- current equation system view

### DofManager
`DofManager`는 자유도와 방정식 번호를 전담한다. Node 또는 Element 내부에 equation id를 분산 저장하지 않는다.

책임:
- node별 활성 자유도 정의
- constrained/free dof mapping
- equation numbering
- sparse matrix pattern 생성에 필요한 connectivity 제공
- 경계조건 적용 전후의 dof view 관리

### 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 확장 지점을 유지한다.

### Results State
결과는 `ResultStep` -> `ResultFrame` -> `FieldOutput`/`HistoryOutput` 구조로 관리한다.

- `ResultStep`: 해석 step 단위 결과
- `ResultFrame`: 정적해석의 load increment 또는 동적해석의 time frame
- `FieldOutput`: node/element field 결과
- `HistoryOutput`: 특정 node, element, set, reaction, energy 등의 이력 결과

## 데이터 흐름
```
Abaqus input file
-> InputParser
-> Domain 생성
-> StepDefinition 루프
-> AnalysisModel 생성
-> DofManager로 자유도/방정식 번호 생성
-> sparse pattern 생성
-> Analysis 실행
-> Assembler로 전역 행렬/벡터 조립
-> BoundaryCondition 적용
-> LinearSolver 또는 nonlinear/time integration loop
-> AnalysisState 갱신
-> ResultsWriter로 step/frame/history 저장
-> 다음 step 진행
```

## Phase 1 구현 범위
- MITC4 Shell 요소
- 선형 탄성 재료
- 절점하중
- 고정 경계조건
- Abaqus input subset: `*Node`, `*Element`, `*Nset`, `*Elset`, `*Material`, `*Elastic`, `*Shell Section`, `*Boundary`, `*Cload`, `*Step`
- `S4`를 `MITC4`로 매핑하고 `S4R`은 추후 지원
- 6자유도 shell node와 drilling 자유도 인공 강성
- constrained DOF 제거 방식
- full vector 기반 reaction recovery
- 선형 정적 해석
- step/frame 기반 결과 저장의 최소 구조
- double precision과 int64 indexing
- singular system 진단
- reference 모델 결과 비교 테스트

## 성능 확장 방향
- 행렬 조립은 element 단위 병렬화를 고려해 설계한다.
- 전역 행렬은 대규모 모델을 위해 sparse matrix를 기본으로 한다.
- MKL 기반 direct solver를 우선 지원하되, solver interface는 iterative solver를 추가할 수 있게 둔다.
- 대규모 sparse solve를 위해 MKL `pardiso_64`를 사용할 수 있도록 64-bit sparse index 경계를 유지한다.
- TBB 병렬화는 요소 stiffness 계산, element force 계산, assembly precompute 등 독립 작업부터 적용한다.
- 정확도 검증이 끝나기 전에는 MITC4 element formulation을 과도하게 최적화하지 않는다.

## 상세 설계 문서
- `docs/NUMERICAL_CONVENTIONS.md`: DOF, 좌표계, 단위, 부호, precision, reaction recovery, singular diagnostics
- `docs/ABAQUS_INPUT_SUBSET.md`: Phase 1 Abaqus input keyword subset과 unsupported feature
- `docs/VERIFICATION_PLAN.md`: reference 폴더 구조, benchmark matrix, tolerance 정책
- `docs/RESULTS_SCHEMA.md`: HDF5 step/frame/field/history schema
- `docs/MITC4_FORMULATION.md`: MITC4 baseline formulation 계약과 open decisions