FESADev/docs/SOLVER_AGENT_DESIGN.md

구조해석 솔버 개발 Agent 구성안

목적

이 문서는 Abaqus, Nastran과 같은 유한요소법 기반 구조해석 솔버를 개발하기 위한 AI Agent 운영 구성을 정의한다.

이번 구성안은 ALL-FEM 논문의 구조를 확장하거나 재사용하는 계획이 아니다. 논문은 Agent 설계를 위한 참고 자료로만 사용하며, 본 프로젝트는 C++/MSVC 기반 독립 솔버 개발 워크플로우를 따른다.

설계 원칙

• 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
• 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
• 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
• Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. reference/<model-id>/에 저장된 model.inp, metadata.json, Abaqus reference CSV files를 검증 기준으로 사용한다.
• 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
• 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.

전체 Agent 구성

Coordinator Agent

전체 개발 흐름을 관리하는 상위 조정 Agent이다.

책임:

• 기능 개발 요청을 단계별 작업으로 분해한다.
• 각 Agent의 산출물을 연결하고 누락된 결정을 추적한다.
• 요구조건, 정식화, 테스트, 구현, 검증, 배포 단계의 진행 상태를 관리한다.
• 실패 시 어떤 Agent로 되돌릴지 결정한다.

주요 산출물:

• 기능별 개발 계획
• 단계별 승인 상태
• 실패 원인과 재작업 지시

Requirement Agent

솔버 기능 요구조건을 정의하는 Agent이다.

책임:

• 해석 기능의 범위, 입력, 출력, 제약조건을 정의한다.
• 대상 요소, 재료 모델, 경계조건, 하중 조건, 해석 타입을 명확히 한다.
• 검증해야 할 물리량과 tolerance 기준을 정한다.

주요 산출물:

• 기능 요구조건 문서
• acceptance criteria
• 검증 물리량 목록

예시 검증 물리량:

• 절점 변위
• 반력
• 요소 내력
• 응력
• 변형률
• 에너지 또는 잔차 기준

Research Agent

책, 논문, 매뉴얼, 공개 benchmark를 조사하는 Agent이다.

책임:

• 유한요소 정식화에 필요한 이론 자료를 수집한다.
• 요소별 benchmark와 patch test 사례를 찾는다.
• Abaqus/Nastran 결과와 비교할 수 있는 공개 예제 또는 문헌 해를 조사한다.
• 자료의 신뢰도와 적용 범위를 평가한다.

주요 산출물:

• 연구자료 요약
• 공식, 가정, 한계 정리
• benchmark 후보 목록

Formulation Agent

코드 구현을 위한 유한요소 정식화를 작성하는 Agent이다.

책임:

• 약형, 형상함수, B matrix, constitutive matrix, 수치적분, 요소 강성 행렬을 정의한다.
• 자유도 배치, 좌표계, 단위계, 부호 규약을 명확히 한다.
• 선형/비선형, 정적/동적, small/large deformation 여부를 구분한다.
• 구현 가능한 알고리즘 형태로 정식화를 정리한다.

주요 산출물:

• 요소별 정식화 문서
• 알고리즘 의사코드
• 수치적분 규칙
• edge case와 singular case 목록

Numerical Review Agent

정식화와 수치 알고리즘을 독립 검토하는 Agent이다.

책임:

• 수식의 차원, 부호, 좌표 변환, 적분 규칙을 검토한다.
• rigid body mode, patch test, symmetry, positive definiteness 등 기본 수치 조건을 확인한다.
• locking, hourglass mode, ill-conditioning 같은 위험을 식별한다.
• 구현 전 정식화 오류를 줄인다.

주요 산출물:

• 정식화 리뷰 결과
• 수치 위험 목록
• 추가 테스트 요구사항

I/O Definition Agent

솔버 입력과 출력 데이터 구조를 정의하는 Agent이다.

책임:

• mesh, node, element, material, section, boundary condition, load, step 입력 형식을 정의한다.
• authoritative HDF5 result schema와 reference CSV comparison row schema를 정의한다.
• Abaqus input file과 내부 입력 모델 사이의 대응 관계를 정리한다.
• 결과 비교를 위해 FESA HDF5 dataset과 Abaqus reference CSV row의 ID/컴포넌트 규약을 맞춘다.

주요 산출물:

• 입력 데이터 schema
• 출력 데이터 schema
• HDF5 result schema
• 결과 비교용 deterministic CSV view schema
• 단위와 좌표계 규약

Reference Model Agent

TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다.

책임:

• 개발 대상 기능을 검증할 최소 모델, benchmark 모델, 회귀 모델을 설계한다.
• reference/<model-id>/에 보관할 Abaqus input file, metadata, Abaqus reference CSV 요구사항을 정의한다.
• 레퍼런스 결과에 포함될 물리량과 tolerance를 명시한다.
• 테스트 모델이 요구조건을 실제로 검증하는지 확인한다.

중요 제약:

• Agent는 Abaqus를 직접 실행하지 않는다.
• Abaqus 해석 결과 CSV는 사람이 생성하거나 별도 승인된 절차로 생성해 reference/<model-id>/에 저장한다.
• Agent는 저장된 reference artifact만 사용해 비교한다.

권장 reference 구조:

reference/
  <model-id>/
    model.inp
    metadata.json
    <model-id>_displacements.csv
    <model-id>_reactions.csv
    <model-id>_internalforces.csv
    <model-id>_stresses.csv

Implementation Planning Agent

코드 구현 전에 작업 단위와 테스트 순서를 설계하는 Agent이다.

책임:

• 요구조건과 정식화를 C++ 구현 작업으로 분해한다.
• 먼저 작성할 단위 테스트, 통합 테스트, 레퍼런스 비교 테스트를 정의한다.
• 기존 architecture와 ownership boundary에 맞춰 변경 파일을 제한한다.
• 구현 Agent가 따라야 할 acceptance criteria를 제공한다.

주요 산출물:

• 구현 계획
• 테스트 우선순위
• 변경 파일 후보
• acceptance checklist

Implementation Agent

C++ 코드를 구현하는 Agent이다.

책임:

• 테스트를 먼저 작성하고 실패를 확인한다.
• 정식화와 I/O schema에 맞춰 최소 구현을 작성한다.
• C++17 이상, MSVC, CMake, CTest 환경에서 동작하도록 구현한다.
• 불필요한 일반화나 speculative abstraction을 피한다.

주요 산출물:

• C++ source/header 변경
• 테스트 코드
• CMake/CTest 변경

Build/Test Executor Agent

빌드와 테스트를 실행하는 Agent이다.

책임:

• Harness validation을 실행한다.
• MSVC x64 Debug CMake configure/build/CTest 결과를 수집한다.
• 실패 로그를 요약하고 Correction Agent에 전달한다.

기본 검증 명령:

python scripts/validate_workspace.py

검증 대상:

• CMake configure
• MSVC Debug build
• CTest
• Harness self-test

Correction Agent

빌드, 테스트, 런타임 실패를 수정하는 Agent이다.

책임:

• 실패 로그를 원인별로 분류한다.
• 컴파일 오류, 링크 오류, 테스트 실패, 결과 비교 실패를 구분한다.
• 최소 수정으로 실패를 해결한다.
• 같은 실패가 반복되면 Coordinator Agent에 차단 상태를 보고한다.

주요 산출물:

• 수정 패치
• 실패 원인 요약
• 재검증 요청

Reference Verification Agent

구현 솔버 결과와 저장된 레퍼런스 결과를 비교하는 Agent이다.

책임:

• 구현 솔버 results.h5의 rows와 reference/<model-id>/의 Abaqus reference CSV rows를 비교하고, FESA debug CSV views는 row identity 검토와 report evidence로만 사용한다.
• 절점 변위, 반력, 요소 내력, 응력의 tolerance 만족 여부를 평가한다.
• absolute tolerance, relative tolerance, norm-based tolerance를 구분해 적용한다.
• 결과 차이가 tolerance 밖이면 원인 후보를 분류한다.

주요 산출물:

• reference comparison report
• 실패한 물리량과 위치
• 최대 오차, 평균 오차, norm 오차

Physics Evaluation Agent

수치 결과가 물리적으로 타당한지 검토하는 Agent이다.

책임:

• 레퍼런스와 수치적으로 비슷해도 물리적으로 이상한 결과가 있는지 확인한다.
• 변위 방향, 반력 평형, 응력 집중, 대칭 조건, rigid body mode를 검토한다.
• 테스트 모델이 기능을 충분히 검증하지 못하면 추가 모델을 요구한다.

주요 산출물:

• 물리 검토 결과
• 추가 검증 모델 요구사항
• release 가능 여부 의견

Release Agent

기능 배포 준비를 담당하는 Agent이다.

책임:

• 요구조건, 테스트, 레퍼런스 비교, 물리 검토가 모두 통과했는지 확인한다.
• 기능 문서와 release note를 정리한다.
• 알려진 제한사항과 tolerance 기준을 기록한다.

주요 산출물:

• release checklist
• 기능 문서
• known limitations

개발 프로세스 매핑

개발 과정	담당 Agent	필수 산출물
1. 솔버 기능 요구조건 정의	Requirement Agent	요구조건, acceptance criteria
2. 연구자료 조사	Research Agent	자료 요약, benchmark 후보
3. 유한요소 정식화	Formulation Agent, Numerical Review Agent	정식화 문서, 리뷰 결과
4. 입출력 데이터 정의	I/O Definition Agent	입력/출력 schema
5. TDD 테스트모델 작성	Reference Model Agent, Implementation Planning Agent	테스트 모델, reference artifact 요구사항
6. 코드 구현	Implementation Agent	C++ 코드, 테스트
7. 레퍼런스 결과 비교 검증	Reference Verification Agent, Physics Evaluation Agent	비교 리포트, 물리 검토
8. tolerance 만족 시 완료	Coordinator Agent	기능 완료 승인
9. 기능 배포	Release Agent	release checklist, 문서

표준 작업 흐름

flowchart TD
  A["기능 요청"] --> B["Requirement Agent"]
  B --> C["Research Agent"]
  C --> D["Formulation Agent"]
  D --> E["Numerical Review Agent"]
  E --> F["I/O Definition Agent"]
  F --> G["Reference Model Agent"]
  G --> H["Implementation Planning Agent"]
  H --> I["Implementation Agent"]
  I --> J["Build/Test Executor Agent"]
  J --> K{"빌드/테스트 통과?"}
  K -- "아니오" --> L["Correction Agent"]
  L --> I
  K -- "예" --> M["Reference Verification Agent"]
  M --> N{"tolerance 만족?"}
  N -- "아니오" --> O["Physics Evaluation Agent"]
  O --> L
  N -- "예" --> P["Physics Evaluation Agent"]
  P --> Q{"물리 검토 통과?"}
  Q -- "아니오" --> L
  Q -- "예" --> R["Release Agent"]

검증 Gate

Gate 1: 요구조건 승인

통과 조건:

• 대상 기능과 제외 범위가 명확하다.
• 입력, 출력, tolerance, 검증 물리량이 정의되어 있다.
• 레퍼런스 비교 방식이 정해져 있다.

Gate 2: 정식화 승인

통과 조건:

• 요소 정식화와 수치적분 규칙이 문서화되어 있다.
• 좌표계, 자유도, 부호 규약이 명확하다.
• Numerical Review Agent가 주요 수치 위험을 검토했다.

Gate 3: 테스트 준비 승인

통과 조건:

• 구현 전 실패해야 하는 테스트가 정의되어 있다.
• reference/<model-id>/ artifact 요구사항이 명확하다.
• 최소 모델, benchmark 모델, 회귀 모델의 목적이 구분되어 있다.

Gate 4: 구현 검증

통과 조건:

• CMake/MSVC/CTest validation이 통과한다.
• 단위 테스트와 통합 테스트가 통과한다.
• Harness TDD guard를 만족한다.

Gate 5: 레퍼런스 검증

통과 조건:

• Abaqus reference CSV 결과와 구현 solver HDF5 결과가 tolerance 안에 있다.
• 절점 변위, 반력, 요소 내력, 응력 비교 결과가 리포트로 남아 있다.
• 실패한 물리량이 없거나 승인된 known limitation으로 기록되어 있다.

Gate 6: 배포 승인

통과 조건:

• 요구조건의 acceptance criteria가 모두 만족된다.
• 문서와 release note가 준비되어 있다.
• 남은 제한사항이 명확히 기록되어 있다.

FESA HDF5 / Abaqus Reference CSV 비교 기준

권장 비교 방식:

• authoritative 비교는 FESA results.h5 rows와 Abaqus reference CSV rows 기준으로 수행한다.
• FESA HDF5에서 추출한 deterministic CSV view는 debugging/review 보조 artifact로만 사용한다.
• scalar 값: absolute tolerance와 relative tolerance를 함께 적용한다.
• vector 값: component-wise 비교와 norm 비교를 함께 기록한다.
• stress tensor: component-wise 비교를 기본으로 하고, 필요한 경우 principal stress 또는 von Mises stress를 추가 비교한다.
• 반력: 전체 하중 평형과 개별 구속 자유도 반력을 모두 확인한다.

권장 리포트 항목:

• model name
• compared quantity
• number of compared rows
• maximum absolute error
• maximum relative error
• RMS error
• worst node or element id
• pass/fail

반복 실패 처리

반복 실패가 발생하면 Correction Agent가 무한 수정 루프를 계속하지 않는다. 다음 중 하나로 분류해 Coordinator Agent에 보고한다.

• 요구조건 불명확
• 정식화 오류 가능성
• reference artifact 오류 가능성
• I/O schema 불일치
• 구현 결함
• tolerance 기준 부적절
• 테스트 모델이 기능을 과도하게 또는 불충분하게 검증함

Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Definition, Reference Model, Implementation Agent 중 적절한 단계로 되돌린다.

초기 적용 우선순위

1. 선형 정적 해석의 최소 골격
2. 1D truss 또는 bar element
3. 2D plane stress/plane strain element
4. 3D solid element
5. material model 확장
6. nonlinear 또는 dynamic analysis 확장

각 단계는 요구조건, 정식화, 테스트모델, 구현, 레퍼런스 비교, 배포 Gate를 독립적으로 통과해야 한다.

운영 메모

• Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
• 사람이 생성한 Abaqus reference artifact의 출처와 생성 조건을 metadata.json에 기록한다.
• reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
• 기능 완료 판정은 코드 실행 성공이 아니라 reference validation과 physics evaluation 통과를 기준으로 한다.