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 결과 저장. 현재 로컬 기본 설치 경로는 C:\Program Files\HDF_Group\HDF5\2.1.1이다.
Python 3: Harness, validation, phase execution, self-test

Git 저장소

Canonical remote repository: https://teagit.mimi1011.synology.me/baram2584/FESADev.git
기본 remote 이름은 origin으로 사용한다.
현재 공유 기준 브랜치는 dev이며, 새 작업 브랜치는 특별한 지시가 없으면 codex/<short-task-name> 형식을 사용한다.
새 환경에서 시작할 때는 git remote -v로 remote를 확인하고, 없으면 git remote add origin https://teagit.mimi1011.synology.me/baram2584/FESADev.git로 등록한다.
push, tag, release, 외부 배포는 사용자가 명시적으로 요청하거나 승인한 경우에만 수행한다.
현재 사용자 지시에 따라 Agent가 수행한 작업 범위의 commit/push는 지속 승인된 것으로 취급한다. 작업 완료 후 검증하고, Agent가 만든 변경만 stage/commit한 뒤 origin에 push한다.

기본 개발 워크플로우

솔버 기능 개발은 아래 순서를 기본으로 한다.

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

각 단계 산출물은 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는 코드나 문서를 수정하기 전에 반드시 아래 순서로 읽는다.

AGENTS.md
docs/PLAN.md
docs/PROGRESS.md
docs/WORKNOTE.md
docs/AGENT_RULES.md
현재 작업과 직접 관련된 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를 둔다.
HDF5 discovery는 HDF5_ROOT=C:\Program Files\HDF_Group\HDF5\2.1.1 또는 HDF5_DIR=C:\Program Files\HDF_Group\HDF5\2.1.1\cmake를 우선 사용한다. 둘 다 없을 때만 CMake 기본 검색 경로에 맡긴다.
경계조건은 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 진단은 필수다.

명령어

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 예시:

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:.
커밋 전에는 git status --short --branch와 git remote -v로 작업 브랜치와 remote가 의도한 상태인지 확인한다.
계획이 필요한 장기 작업은 Harness phase로 나누고, 각 step은 독립 실행 가능해야 한다.
Generated phase execution outputs remain ignored under phases/**/step*-output.json.

8.3 KiB Raw Blame History