FESA/docs/ADR.md

FESA Architecture Decision Records

이 문서는 FESA의 주요 기술 선택과 포기한 대안을 기록한다. 현재 상태가 Accepted인 결정은 Phase 1 계획과 구현에 적용한다. 결정을 변경할 때는 기존 기록을 지우지 않고 새 ADR에서 대체 관계를 명시한다.

ADR-001: C++20, MSVC v143, x64와 CMake Presets

상태: Superseded by ADR-016

상황: 첫 배포는 Windows 개발팀 내부 검증용이며 Intel oneAPI와 HDF5를 일관되게 연동하고 Harness에서 자동 검증해야 한다.

결정: C++20, Visual Studio 2022 MSVC v143, Windows x64, CMake, CMake Presets, CTest 및 GoogleTest/GoogleMock을 사용한다.

결과와 트레이드오프:

• std::span 등 C++20 기능으로 비소유 수치 view를 명시할 수 있다.
• CMake target 경계와 preset을 빌드 계약으로 사용할 수 있다.
• 다른 컴파일러, 운영체제 및 32비트 플랫폼은 Phase 1 보장 대상이 아니다.

ADR-002: 외부 의존성은 개발 환경에 사전 설치

상태: Accepted

상황: oneMKL, oneTBB, HDF5와 GoogleTest의 공급 방식을 하나로 정해야 한다.

결정: 모든 외부 라이브러리는 개발·빌드 PC에 사전 설치하고 CMake가 설치 위치를 탐색한다. vcpkg나 Conan manifest는 Phase 1에 도입하지 않는다.

결과와 트레이드오프:

• 사내 표준 설치 환경을 그대로 사용할 수 있다.
• dependency bootstrap을 구현하지 않는다.
• 구성 단계는 누락, architecture 불일치 및 지원하지 않는 설치를 명시적으로 진단해야 한다.
• 재현성은 설치 버전 기록과 build environment 문서에 의존한다.

ADR-003: 위험 우선 수직 파이프라인

상태: Accepted

상황: 첫 배포는 요소 종류보다 입력부터 결과까지의 코드 구조 검증에 초점을 둔다.

결정: 가장 작은 Beam 모델로 .inp 파싱, semantic model, DOF, 조립, constraint, PARDISO, 결과 회복 및 HDF5 출력을 먼저 연결한다. 이후 합의된 입력 기능을 완성하고 마지막으로 요소 정확도 자격 검증을 수행한다.

결과와 트레이드오프:

• 모듈 계약과 데이터 누락을 일찍 발견한다.
• 임시 가짜 강성행렬은 사용하지 않고 실제 Timoshenko kernel의 최소 구현을 사용한다.
• 파이프라인 연결 완료는 수치적으로 검증된 배포를 뜻하지 않는다.
• Abaqus tolerance와 physics sanity를 통과해야 Phase 1 배포가 완료된다.

ADR-004: Abaqus syntax와 solver semantic model 분리

상태: Superseded by ADR-013

상황: Abaqus .inp 부분집합을 지원하지만 내부 모델이 Abaqus 문법과 결합되면 해석 코드와 향후 입력 adapter가 오염된다.

결정: io/abaqus가 syntax를 파싱하고 검증된 Domain semantic model로 변환한다. 해석 계층에는 keyword 문자열, line layout 및 parser 임시 객체를 전달하지 않는다.

결과와 트레이드오프:

• 입력 adapter와 FEM 코어를 독립적으로 시험할 수 있다.
• syntax 오류와 semantic 오류를 분리할 수 있다.
• 이 결정의 syntax/semantic 분리 원칙은 유지되며 입력 조직 범위는 ADR-013이 대체한다.

ADR-005: 2절점 3D Isoparametric Timoshenko Beam

상태: Accepted

상황: 첫 요소는 절점당 6자유도의 3D Beam이며 짧고 두꺼운 보의 전단변형을 표현해야 한다.

결정:

• 2절점 직선 Isoparametric Timoshenko Beam을 사용한다.
• 축·굽힘·비틀림 항은 2점, 전단 항은 1점 Gauss 적분한다.
• 일반 단면 (A,I_y,I_z,J,A_{sy},A_{sz})와 등방성 선형 탄성을 사용한다.
• 도심·주축 단면, (I_{yz}=0), 단면 오프셋과 워핑 없음으로 제한한다.

결과와 트레이드오프:

• 전단변형을 표현하고 세장 보의 shear locking을 완화한다.
• reduced shear integration과 좌표변환을 별도로 검증해야 한다.
• 점별 전단·비틀림 응력은 단면 형상 정보가 없어 출력하지 않는다.
• 미래 Beam이나 shell formulation을 위한 범용 kernel framework를 미리 만들지 않는다.

ADR-006: Essential BC 소거와 MKL PARDISO

상태: Accepted

상황: 최대 약 10만 자유도의 선형 정적 문제를 안정적으로 풀고 비영 지정값과 반력을 지원해야 한다.

결정: essential DOF를 소거해 reduced symmetric CSR system을 구성하고 MKL PARDISO 대칭 양정치 직접해법으로 푼다. full solution을 복원한 뒤 원래 평형식에서 반력을 계산한다.

결과와 트레이드오프:

• 초기 구현과 singularity 진단이 반복해법보다 단순하고 안정적이다.
• PARDISO API와 handle은 solvers/linear adapter에 격리한다.
• MPC, penalty, Lagrange multiplier 및 iterative backend는 Phase 1에서 제외한다.
• 구속이 부족한 모델은 명시적 numerical failure로 처리한다.

ADR-007: 결정적 oneTBB 요소 계산과 조립

상태: Accepted

상황: 요소 계산을 병렬화하면서 reference 회귀검증에 필요한 수치 재현성을 유지해야 한다.

결정: oneTBB로 요소별 contribution을 병렬 계산하고 thread-local 결과를 안정된 key로 정렬한 뒤 고정 순서로 합산해 CSR을 생성한다. PARDISO 실행 중에는 외부 TBB 작업을 중첩하지 않는다.

결과와 트레이드오프:

• thread scheduling 변화에 의한 비결정적 합산을 줄인다.
• 공유 CSR에 대한 원자적 무질서 누적을 피한다.
• 최대 throughput보다 재현성과 디버깅 가능성을 우선한다.
• 병렬화 이득이 작은 모델에는 scheduling overhead가 생길 수 있다.

ADR-008: 자기완결형, 버전 지정 HDF5 결과

상태: Accepted

상황: 결과 파일만으로 모델과 해석 조건을 추적하고 reference comparison을 수행해야 한다.

결정: 모델, ID mapping, step, solver 설정, 절점·요소 결과와 diagnostic을 하나의 HDF5 파일에 저장하고 root에 schema version을 기록한다.

결과와 트레이드오프:

• 원본 .inp 없이도 결과 entity와 해석 조건을 추적할 수 있다.
• schema 변경을 명시적으로 versioning할 수 있다.
• 모델을 중복 저장하므로 결과 파일이 커진다.
• HDF5 writer/reader와 resource 수명 관리가 별도 adapter 책임이 된다.

ADR-009: Abaqus 2024 오프라인 골든 검증

상태: Superseded by ADR-014 and ADR-015

상황: 상용 reference solver는 개발·CI 환경에서 자동 실행할 수 없지만 변위, 반력, 요소 내력 및 응력 비교가 필요하다.

결정: Abaqus/Standard 2024가 생성한 입력과 CSV 결과를 versioned golden data로 관리한다. 구체적인 CSV 선택과 전단 기본값 계약은 ADR-014와 ADR-015가 대체한다.

결과와 트레이드오프:

• CI에서 Abaqus 설치와 license가 필요하지 않다.
• 골든 데이터 갱신은 별도 Abaqus 환경과 수동 승인 절차가 필요하다.
• per-model metadata 요구사항은 ADR-015에서 제거한다.

ADR-010: 검증 계층별 허용오차

상태: Accepted

상황: 모든 물리량에 하나의 상대오차를 적용하면 영에 가까운 값이나 서로 다른 규모의 결과를 올바르게 판정할 수 없다.

결정: 단위·정식화 테스트와 Abaqus 비교를 분리하고, reference 비교에는 기본 상대오차 (10^{-5})와 물리량별 characteristic scale 기반 절대오차를 함께 사용한다.

결과와 트레이드오프:

• 영에 가까운 값과 큰 값 모두 의미 있게 비교할 수 있다.
• 모델별 예외 tolerance에는 문서화된 수치 근거가 필요하다.
• 단일 tolerance보다 comparison request와 helper가 복잡해진다.

ADR-011: 일관 단위계와 결과 좌표계

상태: Accepted

상황: Abaqus와 같은 입력 호환성과 명확한 Beam 결과 부호를 유지해야 한다.

결정: FESA는 단위를 변환하지 않고 사용자가 일관 단위계를 제공한다. 절점 변위·회전과 반력은 전역좌표계로, 단면력·단면변형률과 회복응력은 요소 국부좌표계로 출력한다.

결과와 트레이드오프:

• 입력이 단순하고 Abaqus 모델과 공유하기 쉽다.
• 단위 일관성은 입력 작성자의 책임이다.
• HDF5에 요소별 국부 기저와 좌표계 metadata를 저장해야 한다.

ADR-012: Phase 1 최소 실체화와 기존 Harness 유지

상태: Accepted

상황: 장기 아키텍처는 여러 요소와 해석 절차를 예상하지만, 첫 배포는 Beam 선형 정적 파이프라인에 한정된다. 저장소에는 이미 phase executor와 MSVC validation hook이 있다.

결정:

• 필요한 모듈과 클래스만 해당 phase에서 만든다.
• 미래 taxonomy는 docs/ARCHITECTURE.md에 기록하되 빈 구현을 생성하지 않는다.
• 현재 scripts/execute.py, docs/HARNESS.md 및 .agents/skills/harness/SKILL.md의 실행 계약을 변경하지 않는다.

결과와 트레이드오프:

• 선행 abstraction과 사용되지 않는 상태를 줄인다.
• 두 번째 실제 요소나 analysis가 추가될 때 factory, registry 또는 state 계약을 확장한다.
• Harness phase는 현재의 feat-{phase-name} 브랜치, 재시도, guardrail 및 코드/metadata 분리 commit 동작을 따른다.

ADR-013: 단일 Instance를 Domain으로 정규화

상태: Accepted

상황: 제공된 Abaqus 검증 모델은 Part/Assembly/Instance 구조를 사용하지만 해석 코어 전체에 Abaqus scope를 노출하면 Phase 1 복잡도가 크게 증가한다.

결정: flat/orphan mesh를 계속 지원하면서 여러 Part와 단일 Assembly·단일 무변환 Instance를 파싱한다. semantic mapper는 Instance가 참조하는 Part만 활성화해 flat Domain으로 정규화한다. 외부 entity는 (instance name, part-local label)로 식별하고 dense solver index와 분리한다.

결과와 트레이드오프:

• 제공된 계층형 입력을 해석하면서 FEM·assembly·solver 경계를 유지한다.
• 사용되지 않는 Part는 파싱하되 해석 객체를 생성하지 않는다.
• Part와 Assembly 집합 scope를 별도로 해석해야 한다.
• 여러 Assembly/Instance, Instance 좌표변환 및 instance-local mesh 수정은 Phase 1 미지원 diagnostic이다.

ADR-014: 생략된 Beam 전단강성의 Phase 1 기본값

상태: Accepted

상황: 일반 Beam 단면 입력과 제공된 검증 샘플에 명시적 *TRANSVERSE SHEAR STIFFNESS가 없지만 Timoshenko kernel에는 유효 전단면적이 필요하다.

결정: 전단강성이 생략되면 (A_{sy}=A_{sz}=5A/6)과 SCF=0을 적용한다. 지원되는 명시값은 기본값을 덮어쓰고 nonzero SCF는 거부한다.

결과와 트레이드오프:

• 현재 정사각형 캔틸레버 샘플의 전단 응답을 일관되게 표현할 수 있다.
• 이 값은 임의 일반 단면에 대한 보편적 Abaqus 기본값이 아니라 FESA Phase 1 가정이다.
• HDF5 결과에 전단 값과 입력/기본값 출처를 기록해야 한다.

ADR-015: 명시적 물리량 선택 기반 CSV 검증

상태: Superseded by ADR-017

상황: 현재 캔틸레버 reference에는 변위와 반력만 있고 per-model metadata는 요구하지 않는다. 요소 내력과 응력 비교 기능은 해당 CSV가 추가되기 전에 구현해야 한다.

결정: comparison request가 물리량, CSV 경로, 상대 tolerance와 절대 scale을 명시한다. 현재 캔틸레버는 변위와 반력만 선택한다. 요소 내력은 SF1..SF3/SM1..SM3을 (N,V_y,V_z,T,M_y,M_z)로, 응력 Sxx는 요소 절점의 단면 도심 (N/A)로 비교한다. 요소 내력·응력 adapter는 synthetic CSV로 우선 검증한다.

결과와 트레이드오프:

• 누락된 비요청 CSV 때문에 현재 reference 검증이 차단되지 않는다.
• 요청한 파일이 없으면 실패하며 비요청 물리량을 통과로 오인하지 않는다.
• 단일 Instance에서는 Instance 열을 생략할 수 있다.
• tolerance와 검증 출처는 test registration과 docs/VALIDATION.md에서 관리한다.

ADR-016: Visual Studio 2026 MSVC v145로 툴체인 갱신

상태: Accepted

상황: 개발 환경에 Visual Studio 2026 Community와 MSVC v145가 설치되어 있고, CMake 4.4.0이 Visual Studio 18 2026 생성기를 지원한다. 반면 기존 ADR-001의 Visual Studio 2022 MSVC v143은 설치되어 있지 않아 solver bootstrap을 진행할 수 없다.

결정: ADR-001의 컴파일러 선택을 대체해 C++20, Visual Studio 2026 MSVC v145, Windows x64를 사용한다. CMake Preset은 Visual Studio 18 2026 생성기와 v145 toolset을 명시한다. CMake, CMake Presets, CTest 및 GoogleTest/GoogleMock 선택은 유지한다.

결과와 트레이드오프:

• 현재 설치된 개발 환경에서 별도 v143 설치 없이 bootstrap을 진행할 수 있다.
• 빌드 계약이 Visual Studio 2026과 v145에 고정되므로 이전 MSVC toolset은 Phase 1 보장 대상이 아니다.
• 컴파일러 갱신에 따른 경고와 표준 라이브러리 동작은 전체 Debug/Release 검증에서 다시 확인해야 한다.

ADR-017: FESA 정식화 적합성과 Abaqus 결과 상관성의 이중 gate

상태: Accepted

상황: FESA의 2절점 Timoshenko Beam은 선택적 감차적분과 SCF=0을 사용하고 Abaqus B31의 slenderness compensation을 구현하지 않는다. 따라서 SCF=0.25인 Abaqus 결과에 기본 상대오차 (10^{-5})를 적용하면 FESA 정식화 결함과 의도된 정식화 차이를 구분할 수 없다. 현재 캔틸레버 reference에는 변위, 반력 및 요소 단면력 CSV가 있다.

결정:

• FESA 정식화 적합성 gate는 해석해, 에너지, 강체 mode, 평형 및 엄격한 tolerance로 FESA 자체 정식화를 검증한다.
• Abaqus 결과 상관성 gate는 원본 Abaqus 입력과 CSV를 변경하지 않는다. FESA는 동일한 기하·재료·하중과 명시적 전단강성을 사용하되 SCF=0인 별도 입력을 production parser와 solver로 해석한다.
• 상관성 gate는 요청된 모든 entity와 component가 유일하게 매칭되고 유한한 component별 RMSE 및 Relative L2가 생성되면 evaluable이다. 서로 다른 정식화에 기본 상대오차 (10^{-5}) pass/fail을 적용하지 않는다.
• Relative L2의 reference norm이 영에 가까우면 해당 component의 characteristic absolute scale norm을 분모 하한으로 사용한다.
• 병진과 회전, 힘과 모멘트처럼 단위가 다른 component를 하나의 RMSE 또는 norm에 혼합하지 않는다.
• Abaqus의 ((\mathbf t,\mathbf n_1,\mathbf n_2))와 FESA의 ((\mathbf e_x,\mathbf e_y,\mathbf e_z))를 각각 일치시킨 모델에서 Abaqus SF1,SF2,SF3,SM1,SM2,SM3은 FESA (N,V_y,V_z,T,M_y,M_z) 순서로 SF1,SF3,SF2,SM3,SM1,SM2를 사용한다.
• 현재 캔틸레버 상관성 요청은 변위, 반력 및 요소 단면력을 명시한다. 요청하지 않은 응력은 통과로 보고하지 않는다.

결과와 트레이드오프:

• FESA 구현 회귀와 상용 solver와의 모델 상관성을 서로 오인하지 않는다.
• Abaqus 원본과 FESA 투영 입력을 함께 관리해야 하며 formulation 차이를 docs/VALIDATION.md에 기록해야 한다.
• 첫 상관성 보고서는 metric을 제시하지만 관측값에 맞춘 acceptance envelope를 만들지 않는다. 후속 envelope에는 해석적 또는 mesh study 근거가 필요하다.