# Project: FESA Structural Solver

## 목적
FESA는 Abaqus, Nastran 같은 유한요소법 기반 구조해석 솔버를 C++17/MSVC 환경에서 개발하는 프로젝트다. 현재 우선 대상은 MITC4 4절점 shell element 기반 선형정적 구조해석 기능이다.

## 기술 스택
- C++17 이상
- MSVC on Windows
- CMake + CTest
- Intel oneAPI MKL: CSR matrix와 PARDISO 선형해법
- Intel oneAPI TBB: 병렬 요소 계산과 병렬 후처리
- HDF5 C library: 해석 결과와 reference 결과 저장
- Python 3: Harness, validation, phase execution, self-test

## 기본 개발 워크플로우
솔버 기능 개발은 아래 순서를 기본으로 한다.

1. 솔버 기능에 대한 요구조건 정의
2. 책, 논문 등 연구자료 조사
3. 코드 구현을 위한 유한요소 정식화
4. 솔버 입출력 데이터 정의
5. TDD 방법 사용을 위한 개발 솔버와 reference 솔버 테스트모델 작성
6. 코드 구현
7. reference 솔버의 해석 결과와 구현 솔버의 해석 결과 비교 검증
8. 결과 차이가 tolerance 범위 내에 들어오면 구현 완료
9. 솔버 기능 배포

각 단계 산출물은 `docs/requirements/`, `docs/research/`, `docs/formulations/`, `docs/io-definitions/`, `docs/reference-models/`, `docs/implementation-plans/`, `docs/reference-verifications/`, `docs/releases/` 아래에 기록한다.

## 검증 기준
- CRITICAL: 기본 검증 경로는 `python scripts/validate_workspace.py`이다.
- CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
- CRITICAL: C++ production file을 변경할 때는 관련 C++ test file이 같은 변경 또는 기존 코드에 있어야 한다.
- CRITICAL: Abaqus, Nastran, reference solver는 agent가 직접 실행하지 않는다. 사람이 생성하거나 승인된 절차로 생성한 reference artifact만 사용한다.
- CRITICAL: 해석 결과 비교 tolerance는 단일 기준 `1e-5`를 사용한다. 각 성분은 `abs(error) <= 1e-5` 또는 `relative(error) <= 1e-5`를 만족해야 한다.

## MITC4 초기 구현 범위
- Feature id: `mitc4-linear-static-shell`
- Analysis: linear static, small displacement/small rotation
- Element: 4-node MITC4 shell, 6 DOF per node
- DOF order: `U1, U2, U3, UR1, UR2, UR3`
- Material/section: single-layer isotropic linear elastic shell section
- Input: Abaqus `.inp` subset
- Output: HDF5 result file
- Reference: stored Abaqus S4R primary reference; Abaqus S4 is diagnostic
- Required compared quantities: nodal displacement, reaction, element internal force/resultant, stress

## Architecture Rules
- OpenSees와 유사하게 `Domain`, `Node`, `Element`, `Material/Section`, `Analysis`, `SystemOfEqn`, `Recorder/ResultWriter` 책임을 분리한다.
- OpenSees source 구조는 참고하되 raw pointer ownership이나 과도한 inheritance는 복제하지 않는다. FESA는 C++17 RAII와 명확한 ownership을 사용한다.
- Element 계산, assembly, solver, I/O, reference comparison은 테스트 가능한 작은 모듈로 분리한다.
- `Domain`은 입력 모델 정의를 보존하고 파싱 이후 가능한 한 불변으로 취급한다.
- 해석 중 변하는 값은 `AnalysisState`에 둔다. Node/Element/Domain에 solver state나 equation id를 분산 저장하지 않는다.
- 현재 step의 실행 view는 `AnalysisModel`로 분리한다.
- Abaqus keyword와 내부 객체 생성은 parser 본체가 아니라 factory/registry 계층으로 분리한다.
- MKL, TBB, HDF5 직접 호출은 adapter 계층 뒤에 둔다.
- TBB 병렬화는 deterministic 결과를 유지해야 한다. 전역 조립은 thread-local contribution을 만든 뒤 deterministic merge를 수행한다.
- MKL PARDISO와 TBB thread oversubscription을 피하기 위해 thread count 정책을 기록한다.
- HDF5 writer는 HDF5 C API 위에 FESA 내부 RAII wrapper를 둔다.
- 경계조건은 constrained DOF 제거 방식으로 적용하고, reaction은 full vector 기준 `K_full * U_full - F_full`로 계산한다.
- 기본 실수 precision은 `double`이고, id/index/equation numbering은 int64 기반으로 설계한다.
- 단위계는 강제하지 않으며, 결과 부호와 shell output component naming은 Abaqus 규약을 따른다.
- Mesh quality 진단은 1차 범위에서 제외하지만 singular system 진단은 필수다.

## 명령어
```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
python scripts/execute.py <phase-dir>
python scripts/execute.py <phase-dir> --push
```

MITC4 CTest 예시:
```powershell
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -L mitc4
```

## MSVC 검증 기본값
- Generator: `Visual Studio 17 2022`
- Platform: `x64`
- Config: `Debug`
- Build directory: `build/msvc-debug`

Override variables:
- `HARNESS_VALIDATION_COMMANDS`
- `HARNESS_CMAKE_GENERATOR`
- `HARNESS_CMAKE_PLATFORM`
- `HARNESS_CMAKE_CONFIG`
- `HARNESS_BUILD_DIR`
- `MKLROOT`
- `TBBROOT`
- `HDF5_ROOT`
- `HDF5_DIR`

## 커밋 및 문서화
- 커밋 전 hook은 Harness Python self-test와 workspace validation을 실행해야 한다.
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`.
- 계획이 필요한 장기 작업은 Harness phase로 나누고, 각 step은 독립 실행 가능해야 한다.
- Generated phase execution outputs remain ignored under `phases/**/step*-output.json`.