add documents

2026-10-18 15:06:44 +09:00
parent 945d899b2f
commit 43867d0b3d
22 changed files with 913 additions and 10 deletions
@@ -0,0 +1,17 @@
+# 입력 subset과 알고리즘 구분
+
+## 배경
+
+Abaqus의 요소·해법 이름으로 연구 모델을 읽지만 내부 요소·적분·질량·고유치 backend는
+FESA가 승인한 정식화를 사용한다. 같은 이름 수용만으로 외부 알고리즘 동등성이 성립하지 않는다.
+
+## 선택
+
+입력은 procedure별 allowlist로 검사하고 source spelling과 identity를 보존한다.
+S4/S4R은 같은 FESA MITC4로, FREQUENCY의 LANCZOS 표기는 경고와 함께 실제 FEAST로 연결한다.
+
+## 대안과 영향
+
+Source 이름으로 Abaqus reduced integration·hourglass·LANCZOS를 선택하는 해석은 실제 구현과
+다르므로 채택하지 않는다. Unknown model keyword를 무시하는 방식도 모델 의미를 바꾸므로 쓰지 않는다.
+현재 subset 밖의 입력은 실패한다. 새 기능은 별도 의미·입력·결과·검증 계약을 확정해 추가할 수 있다.
@@ -0,0 +1,18 @@
+# 정의와 실행 상태의 소유권 분리
+
+## 배경
+
+정적·고유치·동적·열 해석은 같은 모델 정의를 쓰지만 mutable state와 완료 결과의 의미가 다르다.
+Static 상태에 미사용 field와 조건문을 쌓으면 잘못된 family를 직렬화하거나 실패한 trial을 노출할 수 있다.
+
+## 선택
+
+Domain은 의미 정의를, DofManager는 equation·pattern을, 요소는 local 응답을 소유한다.
+Procedure는 typed candidate·accepted history를 관리하고 typed completed outcome을 반환한다.
+Vendor resource는 private adapter가 소유하며 borrowed view·kernel은 실행 중 주소와 수명을 유지한다.
+
+## 대안과 영향
+
+Node·element가 equation과 accepted history를 나눠 저장하거나 공통 무타입 buffer로 family를
+합치는 구조는 책임 경계를 흐리므로 사용하지 않는다. Caller가 참조 대상의 수명을 보장해야 하는
+비용이 생긴다. 새 procedure는 기존 static 결과로 위장할 수 없으며 해당 state·outcome·writer가 필요하다.
@@ -0,0 +1,17 @@
+# 병렬 계산과 누적 순서
+
+## 배경
+
+여러 요소가 같은 DOF에 기여하며 부동소수점 합산 순서와 먼저 발견되는 오류가 결과를 바꿀 수 있다.
+Thread 수와 scheduling이 source identity·결과·진단의 재현성을 바꾸면 비교 근거가 흔들린다.
+
+## 선택
+
+Worker는 자기 element/index buffer에만 local 결과를 쓴다. Join 뒤 stable COO/source 순서와
+고정 reduction으로 전역 값을 누적한다. 오류 선택도 발견 시각 대신 지정된 순서를 따른다.
+
+## 대안과 영향
+
+공유 CSR에 직접 병렬 더하기는 완료 순서에 따른 합산을 만들므로 쓰지 않는다.
+Buffer와 ordered reduction 비용을 감수하며 hash iteration과 worker 완료 순서를 결과 순서로 쓸 수 없다.
+Reduction 순서를 바꾸는 최적화는 단순 refactoring이 아니라 수치 변경으로 검증한다.
@@ -0,0 +1,19 @@
+# 검증된 결과만 최종 공개
+
+## 배경
+
+Accepted 증분이 생긴 뒤에도 다음 증분·로그 close·HDF5 기록·재개방 검사에서 실패할 수 있다.
+이때 기존 정상 최종 결과를 훼손하면 실패 실행과 성공 실행을 구별할 수 없다.
+
+## 선택
+
+Trial 검증 뒤 state를 commit하고, 전체 해석 완료와 로그 close 성공 뒤 writer를 호출한다.
+별도 candidate 파일을 기록·close·self-check한 뒤 최종 경로를 교체한다.
+Output lease로 같은 결과 쌍을 쓰는 실행을 하나로 제한한다.
+
+## 대안과 영향
+
+최종 파일을 먼저 truncate하거나 각 trial을 정상 결과로 직접 저장하는 방식은 실패 보존 조건과
+충돌하므로 사용하지 않는다. Candidate용 저장 공간과 재개방 비용이 필요하다.
+실패 로그가 갱신되고 이전 최종 파일이 남을 수 있어 파일 존재만으로 이번 성공을 판단할 수 없다.
+실행 중 accepted history는 강제 종료 로그만으로 복원하지 못한다.
@@ -0,0 +1,18 @@
+# MITC4 첫 고유치 구현의 비교 예외
+
+## 배경
+
+첫 MITC4 lumped-mass eigen 구현은 외부 원본 Value의 공통 RMS 1% 기준을 충족하지 못했다.
+2026-09-10 사용자는 첫 구현 범위에서 모드별 비교 예외를 승인했다.
+
+## 선택
+
+`mitc4-eigen-first-implementation` 정책을 source modal frame별 blocking singleton Value에만
+적용해 행 상대오차와 RMS를 각각 5% inclusive로 검사한다. Report에 policy_id와 RMS 0.05를 남긴다.
+Near-zero·zero-scale·identity/finite와 내부 전체 반환 pair의 `1e-10` 검증은 유지한다.
+
+## 대안과 영향
+
+공통 RMS 1% 적용 결과는 당시 실패 이력으로 남긴다. 모든 기능의 RMS를 5%로 바꾸는 방식은
+승인 범위 밖이므로 사용하지 않는다. 이 예외는 Hex8 eigen·정적 U/UR/reaction에 적용할 수 없다.
+외부 Value 비교의 첫 구현 수용이지 partial-BC 정적 평형 충돌이나 알고리즘 동등성의 해결이 아니다.
@@ -0,0 +1,17 @@
+# 기존 NT11 비교의 진단 분류
+
+## 배경
+
+기존 DS4 reference의 Step-1/t37/DOF11 NT11은 87/729행 실패와 RMS/S 약 0.0496740846을
+보였고 독립 정식화 oracle도 같은 불일치를 보였다. 공통 RMS 0.01을 넘는다.
+
+## 선택
+
+사용자는 원 정식화와 tolerance를 유지하고 이 비교만 diagnostic/nonblocking으로 분류했다.
+새 필수 모델·CSV는 별도 identity·시점·hash를 확정해 검증한다.
+
+## 대안과 영향
+
+온도 clamp·reference 보정·허용치 완화는 승인된 물리와 원본을 바꾸므로 사용하지 않는다.
+진단 분류 검사의 성공은 외부 수치 PASS가 아니다. 새 reference가 확보되기 전에는
+외부 검증 완료를 선언할 수 없으며 기존 불일치 기록도 지우지 않는다.
@@ -0,0 +1,18 @@
+# 직접 빌드와 보조 빌드 유지
+
+## 배경
+
+직접 MSBuild가 주 개발 빌드이며 CMake/Ninja도 같은 제품과 검사를 구성한다.
+별도 source나 우연한 PATH runtime을 사용하면 빌드 경로에 따라 제품·검증 범위가 달라진다.
+
+## 선택
+
+직접 관리하는 solution과 CMake의 source·검사 identity·CRT·ISA·link·runtime을 함께 유지한다.
+설치 경로는 환경변수나 ignored local 설정으로 받고 GoogleTest는 승인된 local source를 사용한다.
+
+## 대안과 영향
+
+직접 프로젝트를 CMake 생성물로 교체하거나 빌드 전 CMake·Ninja를 숨겨 호출하는 방식은
+주 개발 경로의 독립성을 잃으므로 사용하지 않는다. 두 source 목록을 함께 유지하는 비용이 생긴다.
+의존성 자동 다운로드와 개인 경로 고정도 현재 접근과 다르므로 추가하지 않는다.
+한 경로의 link 성공은 다른 경로의 discovery·실행·runtime 검증을 대신할 수 없다.
@@ -0,0 +1,20 @@
+# Shell 질량 영공간과 동적 좌표
+
+## 배경
+
+MITC4의 numerical drilling은 physical inertia가 없는 방향이다. 부분 회전구속과 warped
+geometry에서는 이를 단순 성분 삭제나 scalar 회전 질량으로 바꾸면 유한 공간의 의미가 달라진다.
+
+## 선택
+
+Eigen은 consistent moment에서 유도한 nodal block lumped mass와 실제 BC 이후의
+analytic null/free 교집합 제거를 사용한다. 현재 HHT는 nodal-lumped-kinetic measure와
+초기 null의 고정 보완기저를 사용한 reduced-coordinate 적분으로 physical rate를 복원한다.
+HHT 관성력·접선·energy·momentum은 같은 kinetic measure에서 계산한다.
+
+## 대안과 영향
+
+Artificial drilling inertia와 partial BC의 full clamp 대체는 현재 질량·구속 의미를 바꾸므로
+사용하지 않는다. 과거 consistent/full-coordinate HHT 기록은 현재 경로의 검증으로 승계하지 않는다.
+고정 patch 밖의 history transport가 검증되지 않으면 실패한다. 공개 auxiliary acceleration만으로
+private 적분 이력을 구성할 수 없고 현재 restart도 제공하지 않는다.
@@ -0,0 +1,21 @@
+# Hex8 강성·질량·정밀도
+
+## 배경
+
+Pointwise bulk의 과도한 강성, warped 요소의 질량 분포와 큰 병진 속 작은 변형의 소실이
+같은 모델의 정적·고유치·동적 결과에 영향을 준다.
+
+## 선택
+
+2026-10-10 승인된 volume-weighted mean volumetric energy와 점별 deviatoric energy를
+사용한다. 2026-10-11 승인된 reference consistent matrix의 BC 축소 전 row-sum mass를
+eigen·HHT·reaction·kinetic energy·momentum에 일관되게 쓴다.
+Solid HHT는 normalized high+low 상태를 다음 accepted history까지 유지하며 F64 출력은 전체 값의 RN64다.
+
+## 대안과 영향
+
+Center/unweighted mean·Fbar·mean-J는 채택한 energy와 달라 대체하지 않는다.
+Warped node 질량을 `rho*V/8`로 통일하거나 current geometry로 재계산하지 않는다.
+매 증분을 rounded F64만으로 이어 가면 low가 소실되므로 내부 상태로 사용하지 않는다.
+Backend에 넘기는 RN64와 full-pair acceptance를 구별해야 하며 출력만 재입력해 같은 내부 판정을
+재현하거나 restart를 제공한다고 주장할 수 없다.
@@ -0,0 +1,19 @@
+# Shell 두께 온도와 시간적분
+
+## 배경
+
+DS4는 shell 면내 전도뿐 아니라 두께 방향 온도 변화와 초기 지정온도의 용량 결합을 다룬다.
+독립된 여러 2D 판이나 초기 온도 projection으로 바꾸면 첫 증분과 열반력의 의미가 달라진다.
+
+## 선택
+
+Q4 면내와 두 구간 C0 P2 두께 보간으로 node당 다섯 온도점을 결합한다.
+Consistent capacity와 Backward Euler를 사용한다. Raw 초기 온도를 frame0에 보존하고
+첫 양의 시점부터 지정온도를 적용하며 열저장을 포함한 full residual에서 반력을 복구한다.
+
+## 대안과 영향
+
+다섯 독립 판·capacity lumping·인공 확산·음수 온도 clamp를 사용하지 않는다.
+초기 projection으로 첫 BC jump를 없애지 않는다. 고정 다섯 점의 두께 오차 plateau와
+초기 경계층이 남으며 thin-shell product-domain은 실제 3D 접합부 전도와 동등하지 않다.
+중앙면 양쪽 도함수가 다를 수 있어 flux trace를 평균할 수 없다.
@@ -0,0 +1,14 @@
+# 주요 설계 결정
+
+| 파일 | 결정과 주요 영향 |
+| --- | --- |
+| `0001-input-subset.md` | 입력 표기의 수용과 외부 solver 알고리즘 동등성을 구분한다. |
+| `0002-typed-ownership.md` | 모델·방정식·local 응답·procedure별 상태·backend의 소유권을 분리한다. |
+| `0003-ordered-reduction.md` | 병렬 local 계산 뒤 안정된 순서로 전역 누적한다. |
+| `0004-candidate-output.md` | Accepted state와 최종 파일 공개를 별도 검증 경계로 둔다. |
+| `0005-eigen-comparison.md` | MITC4 첫 구현의 모드별 Value 비교만 5% RMS 예외를 둔다. |
+| `0006-thermal-diagnostic.md` | 기존 NT11 불일치를 보존하고 새 필수 reference를 별도로 검증한다. |
+| `0007-local-build-paths.md` | 직접 MSBuild를 주 경로로 두고 같은 source의 CMake 경로를 유지한다. |
+| `0008-shell-inertia.md` | Shell eigen/HHT의 질량 영공간을 보존하고 물리 rate를 복원한다. |
+| `0009-hex8-numerics.md` | Mean-volume 강성·reference row-sum mass·high+low 상태를 사용한다. |
+| `0010-thermal-discretization.md` | 다섯 두께 온도점·consistent capacity·Backward Euler를 사용한다. |