FESADev/docs/ProjectInitialPlanNote.md

FESA 초기 문서 완성 계획 노트

메타데이터

• 작성일: 2026-06-10
• 목적: AGENTS.md, docs/PRD.md, docs/ARCHITECTURE.md를 유한요소법 기반 구조해석 솔버 개발 프로젝트 문서로 완성하기 위한 조사 내용과 실행 계획 정리
• 사용한 로컬 스킬: .codex/skills/fem-theory-query
• 사용하지 않은 스킬: .codex/skills/harness-workflow
• 현재 전제: C++17 이상, MSVC, CMake, CTest, Intel oneAPI MKL, Intel oneAPI TBB, Abaqus .inp 입력, HDF5 결과 저장

성공 기준

• AGENTS.md는 이 프로젝트에서 Codex agent가 따라야 할 솔버 개발 원칙, 금지사항, 검증 경로, agent/skill 사용 규칙을 명확히 정의한다.
• docs/PRD.md는 FESA 구조해석 솔버의 제품 목표, v0/v1 범위, 기능 요구조건, 비기능 요구조건, 검증 gate를 정의한다.
• docs/ARCHITECTURE.md는 C++ 솔버 코드 구조, 모듈 경계, 데이터 흐름, 외부 라이브러리 경계, 테스트 구조를 구현 계획에 쓸 수 있을 정도로 정의한다.
• 세 문서는 기존 Harness 규칙을 없애지 않고, 솔버 개발 워크플로우의 운영 기반으로 흡수한다.
• 문서 완성 후 기본 검증 경로는 계속 python scripts/validate_workspace.py이다.

현재 저장소 기준선

• 현재 AGENTS.md, docs/PRD.md, docs/ARCHITECTURE.md는 주로 C++/MSVC Harness scaffold를 설명한다.
• docs/SOLVER_AGENT_DESIGN.md와 docs/SOLVER_SKILL_DESIGN.md는 이미 FESA 솔버 개발 workflow를 요구조건, 연구, 정식화, I/O, reference model, 구현, reference 비교, 물리 검토, release로 분해해 둔 좋은 기준 문서다.
• .codex/agents에는 requirement-agent, research-agent, formulation-agent, io-definition-agent, reference-model-agent, implementation-agent, reference-verification-agent, physics-evaluation-agent, release-agent 등 workflow별 agent가 이미 존재한다.
• .codex/skills에는 fesa-requirements-baseline, fesa-research-evidence, fesa-formulation-spec, fesa-io-contract, fesa-reference-models, fesa-cpp-msvc-tdd, fesa-reference-comparison, fesa-physics-sanity, fesa-release-readiness가 이미 존재한다.

결론: 세 문서는 "Harness 프로젝트" 문서가 아니라 "FESA 구조해석 솔버 프로젝트" 문서로 승격해야 한다. 다만 Harness 검증, TDD guard, phase 실행기는 솔버 개발을 통제하는 운영 인프라로 남긴다.

로컬 FEM 위키 조사 요약

fem-theory-query 스킬 지침에 따라 D:\Obsidian\MultiPhysicsVault의 FEM 위키를 우선 확인했다.

참고한 주요 위키 페이지:

• [[Finite Element Method]]: FEM은 연속체를 요소로 이산화하고, nodal DOF 기반 보간, 요소 방정식, 전역 조립, 경계조건 적용, 선형/비선형 대수계 풀이로 이어진다.
• [[Finite Element Program Implementation]]: 구현은 입력 파싱, element-local 계산, global DOF mapping, sparse assembly, equation solve, stress/result recovery, output/reporting으로 나뉜다.
• [[Abaqus Input File Syntax]]: Abaqus 입력은 keyword/data/comment line 기반이며 model data와 history data를 분리한다.
• [[Abaqus Output Database and Results Files]]: Abaqus 결과는 field output, history output, diagnostics, restart/status/message 성격의 데이터를 구분한다.
• [[Static Equilibrium Equation Solvers]]: 선형 정적 해석은 sparse 직접/반복 솔버, 제약조건 처리, 반력 복구, matrix property 확인이 핵심이다.
• [[Finite Element Modeling and Convergence Checks]]: 결과 신뢰성은 코드 실행 성공이 아니라 mesh, element choice, boundary/load consistency, convergence, equilibrium, stress interpretation 검토에 달려 있다.

위키 기반 핵심 판단:

• FESA 문서의 중심 개념은 "요소 정식화"만이 아니라 "입력 모델 계약 -> 내부 semantic model -> equation system -> result contract -> reference validation"이어야 한다.
• Abaqus .inp 호환은 full compatibility가 아니라 기능별 supported keyword subset으로 제한해 문서화해야 한다.
• 결과 HDF5는 단순 파일 포맷 선택이 아니라 step/frame, field/history, coordinate system, units, output location, schema version을 담는 결과 계약이어야 한다.
• 기능 완료 판정은 CTest 통과와 별개로 reference comparison, physics sanity, release readiness gate를 모두 통과해야 한다.

웹 조사 요약

확인일은 2026-06-10이다. 공식 문서와 공개 프로젝트 문서 위주로 확인했다.

FEM 코드 구조와 설계 패턴

• OOFEM은 object-oriented finite element framework를 지향하며, 공개 저장소 구조에서 src/core, src/sm 구조해석 모듈, src/dss 직접 sparse solver, tests와 benchmarks를 분리한다. 이는 FESA도 core, structural mechanics, solver backend, tests/references를 분리해야 한다는 근거가 된다.
  • 출처: OOFEM DOAJ article, OOFEM GitHub README
• MFEM은 mesh, finite element space, linear/bilinear/nonlinear form, coefficient, boundary condition 같은 개념을 명확히 분리한다. FESA는 이를 그대로 라이브러리화하기보다, structural solver에 맞춰 Mesh, DofSpace, ElementRoutine, MaterialModel, Assembler, AnalysisProcedure 경계를 갖는 편이 적절하다.
  • 출처: MFEM FEM documentation, MFEM GitHub README
• MOOSE의 Kernel 시스템은 weak form 항을 residual/Jacobian contributor로 분리하고 quadrature point 단위에서 평가한다. FESA의 비선형 확장을 고려하면 element/material routine은 residual, tangent, state update를 같은 계약 안에서 제공해야 한다.
  • 출처: MOOSE Kernels System, MOOSE NonlinearSystem

Abaqus 입력과 reference 검증

• Abaqus .inp는 keyword line, data line, comment line으로 구성되며 keyword/parameter는 대소문자를 구분하지 않는다. FESA parser는 이 일반 규칙과 기능별 keyword subset을 분리해서 설계해야 한다.
  • 출처: Abaqus Input Syntax Rules
• Abaqus model은 model data와 history data로 나뉘며, *STEP 이후의 history data가 analysis procedure, load, boundary condition, output request를 정의한다. FESA 내부 모델도 이 구분을 유지해야 parser와 analysis procedure가 섞이지 않는다.
  • 출처: Abaqus Model Definition
• Abaqus Verification Guide와 Benchmarks Guide는 작은 검증 문제, 외부 benchmark, NAFEMS 계열 benchmark로 정확도와 수렴성을 확인하는 방식을 제시한다. FESA reference model portfolio도 smoke, analytical, patch, benchmark, regression 모델을 구분해야 한다.
  • 출처: Abaqus Verification Guide, Abaqus Benchmarks Guide

결과 저장과 HDF5

• Abaqus ODB는 field output, history output, diagnostic information을 구분한다. FESA의 HDF5 결과 schema도 같은 성격 구분을 가져야 후처리와 reference 비교가 안정적이다.
  • 출처: Abaqus Requesting Output to the Output Database
• HDF5 C++ API는 file, group, dataset, attribute, datatype, dataspace 개념을 제공하며 RAII, exception 기반 오류 처리, type-safe interface를 지원한다. FESA 결과 writer는 HDF5 C++ API 또는 얇은 RAII wrapper를 통해 schema version, units, coordinate system, step/frame metadata를 attribute/dataset으로 기록해야 한다.
  • 출처: HDF5 C++ API Introduction

MKL/TBB 사용 방향

• Intel oneMKL은 sparse solver, Sparse BLAS, PARDISO를 제공한다. PARDISO는 CSR 계열 sparse storage를 쓰므로 FESA 전역 행렬 표현은 CSR/COO-to-CSR 조립 경로를 기준으로 설계해야 한다.
  • 출처: oneMKL PARDISO reference
• Intel oneMKL은 CMake config file을 제공하며 MKLConfig.cmake를 find_package() 경로로 사용할 수 있다. FESA CMake는 oneMKL 발견 실패를 명확한 configure error 또는 optional feature error로 처리해야 한다.
  • 출처: Intel oneMKL CMake config
• oneTBB parallel_for는 iteration space를 chunk로 나누어 병렬 실행한다. FESA에서 1차 병렬화 후보는 element-level local matrix/residual 계산이다.
  • 출처: oneTBB parallel_for
• oneMKL의 일부 함수 영역은 oneTBB로 thread된다. 특히 PARDISO는 reordering/factorization 단계에서 oneTBB thread를 사용하지만 solve 단계는 sequential로 호출된다고 문서화되어 있다. FESA는 element loop 병렬화와 MKL 내부 병렬화가 서로 oversubscription을 만들지 않도록 thread policy를 문서화해야 한다.
  • 출처: oneMKL functions threaded with oneTBB

FESA 권장 코드 구조

문서 계획 단계의 후보 구조이며, 실제 구현 전 ARCHITECTURE.md에서 확정한다.

src/
  fesa/
    core/                 # ids, status, diagnostics, units, small value types
    io/
      abaqus/             # .inp lexer/parser, keyword subset, include policy
      hdf5/               # HDF5 result writer/reader, schema versioning
    model/                # semantic model: nodes, elements, sets, materials, sections, steps
    fem/                  # DOF space, equation numbering, quadrature, shape functions
    elements/             # truss/bar, beam, plane, solid, shell element routines
    materials/            # elastic/plastic material contracts and state variables
    assembly/             # local-to-global mapping, sparse pattern, COO/CSR assembly
    constraints/          # essential BC, MPC, penalty or elimination policies
    solvers/
      linear/             # MKL PARDISO backend, iterative backend boundary
      nonlinear/          # Newton control, residual/tangent norms, increments
    analysis/             # static, modal, dynamic, nonlinear procedure drivers
    results/              # recovery, field/history output, diagnostics
    validation/           # comparison metrics and tolerance helpers
tests/
  unit/
  integration/
  reference/
references/
  <feature-id>/
    <model-id>/
      model.inp
      metadata.json
      expected.h5 or reference CSV views

모듈 경계 원칙

• io/abaqus는 syntax와 semantic mapping만 담당하고 해석 알고리즘을 알지 않는다.
• model은 Abaqus keyword 문자열이 아니라 solver semantic model을 가진다.
• fem은 DOF, interpolation, quadrature, local/global mapping을 제공하되 특정 analysis procedure에 종속되지 않는다.
• elements와 materials는 local residual/tangent/stress recovery 계약을 제공한다.
• assembly는 sparse pattern 생성과 local contribution 조립을 담당한다.
• solvers는 MKL/TBB 세부 구현을 감추는 backend boundary를 가진다.
• analysis는 step/history data를 받아 procedure를 실행하고, solver backend와 result writer를 조율한다.
• results는 HDF5 schema를 통해 nodal, element, integration-point, diagnostic output을 분리한다.

권장 설계 패턴

• Strategy: linear solver backend, nonlinear convergence policy, constraint handling, time integration, output backend를 교체 가능한 전략으로 둔다.
• Factory/Registry: Abaqus keyword, element type, material type을 내부 semantic object로 생성한다. 초기에는 compile-time/static registry로 충분하며 동적 plugin은 문서 범위에서 제외한다.
• Template Method: element routine은 gather state -> evaluate quadrature -> accumulate local matrix/vector -> recover output 순서를 공유하되 요소별 shape function과 constitutive contract를 분리한다.
• Adapter: MKL PARDISO, oneTBB, HDF5, Abaqus syntax를 내부 core API에서 직접 노출하지 않는다.
• RAII: MKL handle, HDF5 file/dataset, temporary solver workspace는 수명과 오류 처리를 wrapper에 묶는다.
• Data-oriented core: global vectors, sparse matrix arrays, DOF maps, element connectivity는 cache locality와 deterministic assembly를 우선한다.
• Deterministic assembly: TBB element loop는 thread-local contribution buffer 또는 two-pass sparse assembly를 사용해 reference comparison의 재현성을 해치지 않도록 한다.
• Explicit diagnostics: parser warning, unsupported keyword, singular matrix, rigid body mode, convergence failure, HDF5 schema mismatch를 구조화된 diagnostic으로 남긴다.

세 문서별 완성 계획

1. AGENTS.md

목표: Codex agent의 행동 규칙을 FESA 솔버 개발에 맞게 재정의한다.

포함할 내용:

• 프로젝트 정체성: FESA는 C++17/MSVC 기반 FEM 구조해석 솔버이며 Harness는 개발 통제 인프라다.
• 절대 규칙:
  • 기본 검증은 python scripts/validate_workspace.py.
  • C++ production 변경은 관련 C++ test 선행.
  • Abaqus reference artifact 생성/복원은 명시 승인된 phase에서만 수행.
  • harness-workflow 사용은 사용자가 허용할 때까지 금지.
  • full Abaqus compatibility를 주장하지 않고 기능별 keyword subset만 지원.
• 개발 workflow:
  1. 요구조건 분석
  2. 연구자료 조사
  3. 유한요소 정식화
  4. I/O 계약 정의
  5. TDD 및 reference model 준비
  6. C++ 구현
  7. reference 비교
  8. physics sanity
  9. release readiness
• agent/skill map: 기존 .codex/agents와 .codex/skills/fesa-*를 workflow 단계에 연결.
• 문서 산출물 위치: docs/requirements, docs/research, docs/formulations, docs/io-definitions, docs/reference-models, docs/reference-verifications, docs/physics-evaluations, docs/releases.
• dependency policy: oneMKL, oneTBB, HDF5는 CMake에서 명시 탐지하고, 실패 시 원인을 분류한다.

검증:

• python -m unittest discover -s scripts -p "test_*.py"
• python scripts/validate_workspace.py

2. docs/PRD.md

목표: FESA solver product requirements를 정의한다.

권장 섹션:

• Product Vision: Abaqus .inp subset을 입력으로 받아 구조해석 결과를 HDF5로 저장하고, reference 결과와 비교 가능한 C++ solver.
• Users:
  • solver developer
  • verification reviewer
  • analyst preparing Abaqus-compatible input subsets
  • Codex agent workflow operator
• V0 Scope:
  • 선형 정적 해석 골격
  • 최소 Abaqus keyword subset: *HEADING, *NODE, *ELEMENT, *NSET, *ELSET, *MATERIAL, *ELASTIC, section keyword, *BOUNDARY, *CLOAD, *STEP, *STATIC, output request subset
  • 1D truss/bar를 첫 번째 end-to-end feature 후보로 둔다.
  • HDF5 result schema v0와 reference comparison view를 정의한다.
• V1 Scope:
  • 2D plane stress/strain
  • 3D solid
  • sparse assembly/MKL PARDISO
  • TBB element loop 병렬화
  • reference model portfolio 확장
• Out of Scope:
  • Abaqus full parser 호환
  • Abaqus 직접 실행 자동화
  • GUI/postprocessor
  • Explicit dynamics, contact, plasticity, shell은 초기 범위 제외 또는 후속 feature
• Functional Requirements:
  • parser, semantic model, equation assembly, solver, result recovery, HDF5 output, diagnostics, reference comparison.
• Nonfunctional Requirements:
  • MSVC x64 Debug 검증
  • deterministic results for reference tests
  • schema versioning
  • reproducible tolerance policy
  • clear unsupported keyword diagnostics
• Acceptance Gates:
  • requirements approved
  • research evidence complete
  • formulation reviewed
  • I/O contract approved
  • tests fail before implementation
  • CMake/CTest pass
  • reference comparison pass
  • physics sanity pass
  • release readiness pass

검증:

• PRD의 모든 must 요구조건은 acceptance criteria와 verification method를 가져야 한다.
• PRD의 범위는 SOLVER_AGENT_DESIGN.md, SOLVER_SKILL_DESIGN.md, 각 docs/*/README.md와 충돌하지 않아야 한다.

3. docs/ARCHITECTURE.md

목표: 구현자가 바로 TDD 계획으로 넘길 수 있는 code architecture를 정의한다.

권장 섹션:

• Architectural Goals:
  • FEM formulation traceability
  • explicit I/O contracts
  • sparse linear algebra backend isolation
  • deterministic verification
  • incremental feature addition
• Layered Architecture:
  • CLI/application layer
  • Abaqus input adapter
  • semantic model
  • FEM kernel
  • assembly and constraints
  • solver backend
  • analysis procedure
  • result output/HDF5
  • validation/test harness
• Data Flow:

  Abaqus .inp
  -> lexer/parser
  -> keyword AST or records
  -> semantic model
  -> DOF numbering
  -> element/material local evaluation
  -> sparse assembly
  -> constraints
  -> MKL solver
  -> recovery
  -> HDF5 result
  -> reference comparison/physics sanity
  

• Dependency Rules:
  • core는 외부 라이브러리에 의존하지 않는다.
  • io/hdf5만 HDF5에 직접 의존한다.
  • solvers/linear/mkl만 oneMKL에 직접 의존한다.
  • parallel 또는 assembly 일부만 oneTBB에 직접 의존한다.
  • test helper는 production parser/solver 내부 상태를 우회하지 않는다.
• Sparse Matrix Policy:
  • assembly는 처음에는 COO triplet 수집 후 CSR finalize를 기준으로 한다.
  • MKL PARDISO backend는 CSR input contract를 문서화한다.
  • matrix symmetry, definiteness, singularity diagnostic을 결과에 남긴다.
• Parallel Policy:
  • element-local computation 병렬화를 첫 번째 TBB 적용 지점으로 둔다.
  • 전역 sparse write는 thread-local buffer 또는 deterministic reduction으로 제한한다.
  • MKL thread count와 TBB task arena 정책을 명시한다.
• HDF5 Schema:

  /metadata
  /model/nodes
  /model/elements
  /steps/<step-name>/frames/<frame-id>/nodal/displacement
  /steps/<step-name>/frames/<frame-id>/nodal/reaction
  /steps/<step-name>/frames/<frame-id>/element/stress
  /steps/<step-name>/frames/<frame-id>/element/strain
  /diagnostics
  

• Test Architecture:
  • unit: parser, DOF map, shape functions, material law, sparse assembly, HDF5 schema
  • integration: small .inp to HDF5 end-to-end
  • reference: Abaqus artifact comparison
  • physics: equilibrium, sign, symmetry, rigid body mode, stress sanity

검증:

• architecture의 각 모듈은 최소 하나의 test category와 연결되어야 한다.
• 외부 dependency는 adapter boundary 없이 core module에 직접 들어오면 안 된다.

기존 skill/agent workflow와 문서 연결

Solver workflow	Agent	Skill	문서 산출물
요구조건 분석	requirement-agent	fesa-requirements-baseline	docs/requirements/<feature-id>.md
연구자료 조사	research-agent	fesa-research-evidence, fem-theory-query	docs/research/<feature-id>-research.md
유한요소 정식화	formulation-agent	fesa-formulation-spec	docs/formulations/<feature-id>-formulation.md
수치 검토	numerical-review-agent	fesa-numerical-review	docs/numerical-reviews/<feature-id>-review.md
I/O 정의	io-definition-agent	fesa-io-contract	docs/io-definitions/<feature-id>-io.md
reference model	reference-model-agent	fesa-reference-models	docs/reference-models/<feature-id>-reference-models.md
구현 계획/구현	implementation-planning-agent, implementation-agent	fesa-cpp-msvc-tdd	tests, source, implementation report
build/test	build-test-executor-agent	fesa-cpp-msvc-tdd	docs/build-test-reports/<feature-id>.md
correction	correction-agent	fesa-cpp-msvc-tdd	docs/corrections/<feature-id>.md
reference 비교	reference-verification-agent	fesa-reference-comparison	docs/reference-verifications/<feature-id>-reference-verification.md
물리 검토	physics-evaluation-agent	fesa-physics-sanity	docs/physics-evaluations/<feature-id>-physics-evaluation.md
배포 준비	release-agent	fesa-release-readiness	docs/releases/<feature-id>-release.md

HDF5와 기존 CSV reference skill의 정합성 이슈

현재 프로젝트 문서와 skill은 reference comparison artifact로 CSV를 많이 언급한다. 사용자 요구조건은 solver 결과 저장 포맷을 HDF5로 지정한다.

권장 결정:

• FESA solver의 정식 결과 파일은 HDF5로 한다.
• reference comparison을 위해 HDF5 dataset에서 deterministic CSV view를 추출하거나, comparison tool이 HDF5와 reference CSV를 직접 비교하도록 한다.
• docs/PRD.md와 docs/ARCHITECTURE.md에는 "HDF5 authoritative output, CSV comparison view optional"을 명시한다.
• 기존 fesa-reference-comparison skill은 즉시 바꾸기보다, 문서에서 HDF5 support extension을 후속 작업으로 기록한다.

주요 리스크와 열린 질문

• 첫 end-to-end feature를 1D truss/bar로 확정할지, 2D plane stress까지 포함할지 결정이 필요하다. 문서 계획상 v0는 1D truss/bar가 가장 안전하다.
• oneMKL interface는 LP64와 ILP64 중 하나를 선택해야 한다. 초기 MSVC/x64/Debug에서는 LP64를 기본 후보로 두고 대형 모델 전환 시 ILP64를 검토한다.
• MKL 내부 thread와 TBB element loop가 동시에 활성화될 때 oversubscription을 피할 정책이 필요하다.
• HDF5 C++ API를 직접 쓸지, C API 위에 프로젝트 RAII wrapper를 둘지 결정이 필요하다. 초기에는 wrapper를 두고 내부 구현은 C++ API로 시작하는 편이 문서 요구에 맞다.
• Abaqus .inp include path, quoted labels, abbreviated keywords, unsupported keyword diagnostics는 parser 요구조건에서 명확히 다뤄야 한다.
• reference artifact 생성은 agent가 직접 하지 않는다는 기존 제약을 유지해야 한다. 사람이 생성한 artifact의 provenance를 metadata.json에 남긴다.

실행 순서 제안

1. AGENTS.md 개정
   • Harness 중심 문구를 FESA solver 중심으로 확장한다.
   • 기존 검증 명령과 TDD guard는 유지한다.
   • agent/skill workflow와 금지사항을 명시한다.
   • 검증: Python self-test, workspace validation.
2. docs/PRD.md 개정
   • 현재 "C++/MSVC Harness" PRD를 FESA solver PRD로 대체 또는 대폭 확장한다.
   • v0/v1 scope, functional/nonfunctional requirements, out-of-scope, acceptance gates를 작성한다.
   • 검증: 요구조건마다 verification method와 acceptance criteria가 있는지 수동 리뷰.
3. docs/ARCHITECTURE.md 개정
   • 현재 Harness architecture를 FESA solver architecture로 확장한다.
   • Harness architecture는 "development operations layer"로 남긴다.
   • 모듈 구조, dependency rules, data flow, HDF5 schema, MKL/TBB policy, test architecture를 작성한다.
   • 검증: module/test mapping과 dependency rule 수동 리뷰.
4. 문서 정합성 점검
   • docs/SOLVER_AGENT_DESIGN.md, docs/SOLVER_SKILL_DESIGN.md, docs/*/README.md와 용어/경로 충돌을 점검한다.
   • python -m unittest discover -s scripts -p "test_*.py" 실행.
   • python scripts/validate_workspace.py 실행.

후속 작업 후보

• HDF5 result schema ADR 작성.
• Abaqus .inp v0 keyword subset ADR 작성.
• MKL/TBB threading policy ADR 작성.
• fesa-reference-comparison skill의 HDF5 comparison 확장 계획 작성.
• 첫 기능 linear-truss-1d의 docs/requirements/linear-truss-1d.md 작성.