# 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 for threshold tests; cross-formulation correlation superseded by ADR-017

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

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

**결과와 트레이드오프:**

- 영에 가까운 값과 큰 값 모두 의미 있게 비교할 수 있다.
- 모델별 예외 tolerance에는 문서화된 수치 근거가 필요하다.
- 단일 tolerance보다 comparison request와 helper가 복잡해진다.
- Abaqus와 FESA의 정식화가 다른 상관성 비교에는 ADR-017의 component별 RMSE와
  Relative L2 계약을 적용한다.

## 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 근거가 필요하다.
