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를 사용한다. |
@@ -0,0 +1,59 @@
+# 해결되지 않은 문제
+
+## 비정적 검증 공백
+
+- 조건·관측: 2026-10-18 통합에서 장시간 HHT 검증이 사용자 요청으로 중단되고 정적·공통
+  631개만 검증됐다. 비정적 333개 등록은 보존됐으나 최신 통합본 전체 수치 실행 근거가 없다.
+- 영향: Shell HHT·solid dynamics·frequency·transient thermal의 전체 검증 완료를 선언할 수 없다.
+- 지금 해결하지 못한 이유: 장시간 solver·test 실행과 독립 물리 판정이 필요한 별도 검증 작업이다.
+- 다음 접근: source와 환경을 고정하고 미실행 identity별 필요한 물리·시간수렴·reference를
+  묶어 검증한다. 중단된 C08b finer-grid와 기존 완료 개별 검사를 구분한다.
+
+## 정식 기준자료 부재와 추가 fine 비교기 부재
+
+- 조건·관측: 정식 `reference/shellNL-meshfine/`, `reference/shellNL-meshfine_02/`,
+  `reference/shellNL-meshfine-pressure/` 자료가 없다고 통합 기록에 남아 있다.
+  `_02`는 전용 comparator case identity와 비교 계약 구현도 없다.
+- 영향: Fine·추가 fine·pressure의 실제 외부 비교가 미완료다. 합성 fixture가 이를 대체하지 않는다.
+- 지금 해결하지 않는 이유: 정식 원본 제공은 외부 의존이며 원본 생성·복원·임시 자료 승격은 승인되지 않았다.
+- 다음 접근: 정식 자료를 확보해 hash·source identity·frame을 확정한다. `_02`는 comparator
+  계약을 별도로 구현한다. `reference/temp`는 검증에 사용하지 않는다.
+
+## Thermal NT11 외부 불일치
+
+- 조건·관측: 기존 676 DS4·729 node 모델의 Step-1/t37/DOF11 NT11 비교에서
+  원본 87/729행 실패, RMS/S 약 0.0496740846으로 공통 0.01 기준을 초과했다.
+  독립 정식화 oracle도 같은 불일치를 보였다.
+- 영향: 기존 비교는 diagnostic/nonblocking이며 외부 수치 정확도 통과가 아니다.
+  다른 station·flux·반력·전체 시간 응답으로 검증 범위를 확대할 수 없다.
+- 지금 해결하지 않는 이유: 사용자가 원 정식화·허용치 유지를 선택했고 새 필수 모델·NT11 CSV가 미확보다.
+- 다음 접근: 새 reference의 identity·시점·hash와 blocking 계약을 확정해 별도로 검증한다.
+  음수 온도 clamp·원본 보정·RMS 완화로 기존 기록을 통과로 바꾸지 않는다.
+
+## Eigen partial-BC 정적 평형 충돌
+
+- 조건·관측: MITC4 eigen의 S3 partial rotational BC 사례와 public static 평형 사이의
+  충돌이 기능 기록에 보류 상태로 남아 있다.
+- 영향: 모드별 Value 5% 승인 예외가 이 정적 평형 문제나 Abaqus 알고리즘 동등성을 해결하지 않는다.
+- 지금 해결하지 않는 이유: 수식·공개 정적 평형 계약의 별도 조사이며 문서만으로 고칠 수 없다.
+- 다음 접근: 동일 source BC에서 static과 eigen의 null/finite 공간·힘/모멘트 의미를 독립 대조한다.
+  부분 회전구속을 full clamp로 대체하지 않는다.
+
+## 성능 목표 미달과 과거 회귀
+
+- 조건·관측: 세 모델의 과거 baseline은 목표 2초·100초·100초를 모두 넘었다.
+  Hex8 동적 수정본의 단일 개발 표본도 117.7986225초였다. Refactor의 ShellNL elapsed
+  회귀 기록은 Native +86.52%·CMake +120.91%이며 원인과 변산이 미확정이다.
+- 영향: 최적화 구현 존재와 최종 사용자 시간 목표 달성 사이에 공백이 있다.
+- 지금 해결하지 않는 이유: 최신 최종 source의 Release 측정·전체 물리 검증이 필요한 별도 작업이다.
+- 다음 접근: 같은 compiler·thread·runtime·전원 조건으로 전체 process 시간을 측정하고
+  원본 결과·필수 회귀를 함께 대조한다. 과거 보류 후보와 다른 source의 표본을 섞지 않는다.
+
+## PARDISO 1×1 heap failure의 vendor 원인 미확정
+
+- 조건·관측: 1×1 SPD 반복의 heap failure는 SpMV 없는 baseline에서도 재현됐다.
+  해당 크기에만 local-thread/TLS 회피가 적용돼 있다.
+- 영향: 제한된 회피의 성공이 다른 크기·thread 정책·vendor 전체 resource 안전성을 증명하지 않는다.
+- 지금 해결하지 못한 이유: vendor 원인이 미확정이며 최소 재현 실행과 backend 조사가 필요하다.
+- 다음 접근: 재발 시 backend version·matrix·thread·factor/solve/release 수명을 고정한 최소 재현을
+  확보한다. 적용 범위를 근거 없이 확대하지 않는다.
@@ -0,0 +1,63 @@
+# 구현과 검증 상태
+
+## 기준 시점
+
+2026-10-18 저장소 HEAD `945d899` 기준이다. 아래 통과 수치는 각 검증 당시 기록의 범위이며
+후속 source에서 새로 실행한 결과로 승계하지 않는다.
+현재 용도는 개인 연구용 로컬 실행이며 장기 목표는 외부 사용자 배포다. 배포 형태·지원 환경·
+dependency 재배포 조건은 확정되지 않았다.
+
+## 구현과 실제 근거
+
+| 영역 | 구현된 범위 | 확보된 검증과 한계 |
+| --- | --- | --- |
+| B33·MITC4 선형 정적 | 입력 → solve → 복구 → HDF5 | 2026-10-18 정식 정적 모델 실행·비교 범위에 포함. 일반 곡선 beam·광범위 distorted/curved shell 정확도를 뜻하지 않는다. |
+| MITC4 비선형 정적·압력 | Full Newton·trial/commit·정적 follower pressure | ShellNL 정식 기본 모델의 U blocking·UR warning·내부 평형 통과 기록. RF/RM은 review-only. Fine·추가 fine·pressure의 정식 자료가 없고 추가 fine 비교기 연결도 없다. |
+| Shell frequency | Lumped mass·실제 FEAST·null/finite 공간·전체 반환 pair 검증 | 2026-09-10 첫 구현의 417개 통과와 Value 10개 모드별 5% 기록. 최신 통합본의 frequency 수치 실행을 완료한 근거로 승계하지 않는다. |
+| Shell HHT | Nodal-lumped-kinetic·reduced-coordinate·fixed-null·schema2 | 과거 C09와 C08a 7-grid, baseline 원본 U 비교 기록. 최신 전체 회귀·C08b finer-grid·최신 원본 비교·전체 물리 판정은 미완료. 중단을 수치 실패나 통과로 세지 않는다. |
+| Hex8 | Mean-volume 강성·reference row-sum mass·정적/고유치/HHT·high+low | 2026-10-13 관련 C++ 91개·Python 96개와 보존 결과 5개 비교 기록. 2026-10-18에는 정적 2개를 재실행. 최신 고유치·동적 전체 검증은 별도다. |
+| DS4 thermal | 5 온도점·consistent capacity·BE·flux/reaction·원자적 출력 | 당시 추가 139개 검사 기록. 기존 NT11은 diagnostic 불일치이며 새 필수 외부 reference 검증은 미완료. 최신 통합본의 전체 열 수치 실행도 미완료다. |
+| 공통 구조·빌드 | Typed procedure/capability/outcome·private backend·Native/CMake | 2026-10-18 두 경로 전체 target build·공개 header 111개 독립 compile·runtime DLL 7개 대조 기록. 물리 기능 전체 검증과 구분한다. |
+| 성능 | MKL 행렬 연산·제한된 불변 cache·Hex8 SIMD·shell 산술 최적화 | 세 모델의 목표 달성은 미완료. 단일 개발 표본과 복원된 후보의 통과를 최종 성능으로 승계하지 않는다. |
+
+2026-10-18 통합 기록은 두 빌드 경로에서 unit 849·integration 72·reference 43, 총 964개
+등록 identity가 일치한다고 보고한다. 사용자 지시로 정적·공통 631개(unit 555·integration 35·
+reference 41)만 직접 실행과 CTest에서 검증했으며 failure/error/skip은 0이었다.
+Python 합성·정책 145개도 통과했다. 보존된 비정적 333개는 당시 미검증이다.
+
+정식 정적 5모델은 beam·shell·shellNL·Hex8 linear/nonlinear static이다.
+Fresh Refactor·통합 Native·통합 CMake 실행물에서 같은 scratch 입력과 경로로 15회 실행했고
+등록 비교·보고서 검증·schema/identity/field parity를 포함한 50단계가 exit 0이었다.
+이는 선택된 정적 근거이며 source 전체의 수치 동등성이나 전체 green 선언이 아니다.
+근거 보관 위치는 `.build/merge-verification/refactor-integration-final-20261018-01/`다.
+해당 보관물이 없는 checkout에서는 실행물을 확보한 것으로 간주하지 않는다.
+
+## 남은 작업과 의존 순서
+
+사용자가 확인한 후속 범위는 남은 동해석·고유치·열해석 검증, 성능 개선과 미해결 이슈 처리다.
+이 목록은 특정 기능의 자동 실행 지시나 장시간 작업·외부 solver 실행 승인으로 해석하지 않는다.
+
+1. 정식 fine·추가 fine·pressure·새 thermal 기준자료의 제공 여부와 source/frame/hash 계약을
+   확정한다. 추가 fine는 자료뿐 아니라 전용 case identity와 comparator 연결이 필요하다.
+2. 현재 source·compiler·build tree를 묶어 비정적 수치 검증을 수행한다. Shell HHT 시간수렴·
+   원본 비교, solid dynamics, frequency, transient thermal을 선택된 정적 근거와 구분한다.
+   자료가 필요한 외부 비교는 정식 자료 확보 뒤 수행한다.
+3. Eigen partial-BC 정적 평형 충돌과 thermal 외부 불일치의 영향을 각각 판정한다.
+   기준 완화·질량 변경·원본 보정으로 해결하지 않는다.
+4. 같은 물리·허용치·출력·정밀도를 보존한 상태에서 성능 회귀 원인을 조사하고 최종 source의
+   Release 시간과 수치 결과를 다시 측정한다. 검증되지 않은 가속을 완료로 기록하지 않는다.
+
+위 순서는 자료·물리 판정·측정의 의존 관계다. 동해석·고유치·열해석 사이의 상세 우선순위와
+새 기능 추가 순서는 사용자가 별도로 정하지 않았다.
+
+## 성능 목표
+
+| 모델 | 목표 초 | 과거 단일 baseline 초 |
+| --- | ---: | ---: |
+| hexa_nonlinearstatic | 2 | 10.914924 |
+| hexa_dynnonlinear | 100 | 402.069447 |
+| shellNL-dyn-meshfine | 100 | 6372.325621 |
+
+Hex8 동적 개발 표본 117.7986225초는 native 0과 U 비교 통과였으나 100초 목표를 넘었다.
+Refactor 당시 ShellNL elapsed 회귀 Native +86.52%·CMake +120.91%는 과거 단일 기록이며
+원인·변산이 미확정이다. 최종 통합 source의 새 Release 성능 측정은 미완료다.