NINI
126 lines
7.0 KiB
Markdown
126 lines
7.0 KiB
Markdown
# 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`를 만족해야 한다.
|
|
|
|
## Agent Coordination Files
|
|
여러 AI Agent가 나눠서 작업할 때 `docs/PLAN.md`, `docs/PROGRESS.md`, `docs/WORKNOTE.md`를 공통 handoff 파일로 사용한다.
|
|
|
|
새 세션을 시작하는 Agent는 코드나 문서를 수정하기 전에 반드시 아래 순서로 읽는다.
|
|
|
|
1. `AGENTS.md`
|
|
2. `docs/PLAN.md`
|
|
3. `docs/PROGRESS.md`
|
|
4. `docs/WORKNOTE.md`
|
|
5. `docs/AGENT_RULES.md`
|
|
6. 현재 작업과 직접 관련된 `docs/` 산출물
|
|
|
|
각 파일의 책임:
|
|
- `docs/PLAN.md`: 전체 작업 목표, 단계별 계획, 작업 순서, acceptance criteria, 담당 가능 Agent, 차단 조건을 관리한다.
|
|
- `docs/PROGRESS.md`: 지금까지 완료된 일, 진행 중인 일, 다음에 해야 할 일, 마지막 검증 결과, 열린 blocker를 관리한다.
|
|
- `docs/WORKNOTE.md`: 작업 중 실수, 시행착오, 실패 원인, 되돌아간 결정, 다음 Agent가 피해야 할 함정을 기록한다.
|
|
|
|
업데이트 규칙:
|
|
- 작업 범위나 단계 계획이 바뀌면 `docs/PLAN.md`를 갱신한다.
|
|
- 의미 있는 작업을 완료하거나 검증을 실행하면 `docs/PROGRESS.md`를 갱신한다.
|
|
- 실수, 실패한 접근, 환경 문제, 반복되면 안 되는 시행착오가 있으면 `docs/WORKNOTE.md`에 날짜와 함께 추가한다.
|
|
- 다른 Agent나 사용자가 남긴 기록은 삭제하거나 덮어쓰지 않는다. 필요한 경우 새 dated entry로 정정한다.
|
|
- 파일 내용과 사용자의 최신 지시가 충돌하면 최신 사용자 지시를 우선하고, 충돌 내용을 `docs/PROGRESS.md` 또는 `docs/WORKNOTE.md`에 남긴다.
|
|
- 세 파일에는 비밀정보, license key, 개인 토큰, machine-local credential을 기록하지 않는다.
|
|
|
|
## 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`.
|