FESADev/docs/SOLVER_AGENT_DESIGN.md

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

목적

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

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

설계 원칙

• 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
• 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
• 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
• Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. 기능이 선언한 기존 .inp와 실제 비교에 필요한 Abaqus CSV만 read-only 검증 기준으로 사용한다. Canonical naming, README, metadata, version 또는 provenance는 기본 readiness 조건이 아니다.
• FESA는 Abaqus와 독립적인 solver다. Agent는 Abaqus 내부 formulation, integration, stabilization 또는 recovery equivalence를 요구하거나 추론하지 않는다.
• 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
• 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
• Harness 운영은 docs/HARNESS_WORKFLOW.md의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다.

전체 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와 검증에 사용할 기존 reference case를 inventory하는 Agent이다.

책임:

• 기능이 요구할 때만 테스트 모델 목적을 구분하고, 기본적으로 기존 case를 사용한다.
• 기존 reference case의 목적, exact input/required CSV path, blocking/warning quantity와 tolerance를 inventory한다.
• FESA HDF5 quantity와 source ID/component matching을 명시한다.
• 테스트 모델이 요구조건을 실제로 검증하는지 확인한다.

중요 제약:

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

최소 reference case 구조:

reference/
  <case-dir>/
    <declared-input>.inp
    <declared-required-quantity>.csv

Directory와 filename은 제공된 값을 그대로 사용한다. Reference Model Agent는 canonical 이름, README, metadata, provenance 또는 비교하지 않는 quantity CSV를 요구하지 않는다.

Implementation Planning Agent

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

책임:

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

주요 산출물:

• 구현 계획
• 테스트 우선순위
• 변경 파일 후보
• acceptance checklist
• 사용자 승인 전 multi-Step Harness 초안
• 승인 후 phases/index.json, phases/<task-name>/index.json, 자기완결적 stepN.md

필수 절차:

• 구현 계획 요청에서 project-local $harness skill을 사용한다.
• 한 Step은 하나의 layer/module만 다루고 각 Step에 prerequisite file, TDD RED/GREEN/VERIFY, 정확한 MSVC/CMake/CTest command와 금지사항을 포함한다.
• Step 초안을 먼저 사용자에게 제시한다. 승인 전에는 phases/ 파일을 생성하지 않는다.
• Harness executor 실행은 별도 사용자 요청이 있을 때만 수행한다.

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/config.json 또는 자동 감지 결과에 맞는 MSVC build/test 명령을 실행한다.
• MSVC x64 Debug CMake configure/build/CTest 결과를 수집한다.
• 실패 로그를 요약하고 Correction Agent에 전달한다.

기본 CMake 검증 명령:

cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure

Preset 또는 직접 MSBuild 프로젝트는 .harness/config.json에 선언된 명령을 따른다.

검증 대상:

• 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. Reference case 준비	Reference Model Agent, Implementation Planning Agent	기존 input/required CSV inventory, 비교 mapping, tolerance
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 -- "아니오" --> 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: 테스트 준비 승인

통과 조건:

• 구현 전 실패해야 하는 테스트가 정의되어 있다.
• 기능이 요구하는 기존 input/CSV pair와 blocking/warning quantity가 명확하다.
• 필요한 source ID/component matching과 tolerance가 정의되어 있다.

Gate 4: 구현 검증

통과 조건:

• CMake/MSVC/CTest validation이 통과한다.
• 단위 테스트와 통합 테스트가 통과한다.
• 관련 C++ test file이 있고 같은 구현 Step 안에 RED 실패와 후속 GREEN 성공 증거가 있다.
• Stop의 전체 MSVC build/test 검증이 통과한다.

Gate 5: 레퍼런스 검증

통과 조건:

• 기능이 blocking으로 선언한 Abaqus CSV quantity와 구현 solver HDF5 quantity가 tolerance 안에 있다.
• Warning-only quantity는 결과와 경고가 리포트에 남고 pass/fail을 바꾸지 않는다.
• Required source row/component의 누락, 추가, 중복 또는 nonfinite 값이 없다.

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. Isoparametric 3D Euler beam element
3. 1D truss 또는 bar element
4. 2D plane stress/plane strain element
5. 3D solid element
6. material model 확장
7. nonlinear 또는 dynamic analysis 확장

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

운영 메모

• Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
• 사람이 제공한 Abaqus reference artifact는 현재 path/name 그대로 read-only로 사용한다. 별도 provenance, README 또는 metadata가 없다는 이유로 gate를 차단하지 않는다.
• reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
• 기능 구현 완료 판정은 build/test와 기능별 blocking reference validation 통과를 기준으로 한다. Physics evaluation과 release readiness는 별도 후속 배포 gate다.