baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c151cae56d2b03fe087a69a0e1409e3e67b48f6
FESADev/AGENTS.md
T
NINI 0c151cae56 modify agent and skill
2026-06-08 01:43:17 +09:00

7.0 KiB
Raw Blame History

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 진단은 필수다.

명령어

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:.
  • 계획이 필요한 장기 작업은 Harness phase로 나누고, 각 step은 독립 실행 가능해야 한다.
  • Generated phase execution outputs remain ignored under phases/**/step*-output.json.
Reference in New Issue View Git Blame Copy Permalink