docs: organize project guidance and module contracts

2026-09-29 00:34:57 +09:00
parent 73db138566
commit a3502c9b97
50 changed files with 1748 additions and 414 deletions
@@ -0,0 +1,24 @@
+# 외부 입력 subset과 독립 솔버
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+기존 모델을 읽고 외부 결과로 검증해야 하지만, 공개 입력 형식과 외부 솔버의 내부 알고리즘은
+같은 계약이 아니다. 파서 호환성을 제품 목표로 삼으면 검증 가능한 물리 의미보다 문법 수용이 앞설 수 있다.
+
+## 결정
+
+승인된 Abaqus keyword subset의 의미만 지원한다. S4/S4R 등 source 표기는 보존하고
+FESA 정식화로 연결한다. 외부 solver의 내부 적분·안정화·상태·결과 생성 동등성은 주장하지 않는다.
+
+## 대안과 선택 이유
+
+Full compatibility는 비공개 내부 동작까지 추정해야 하므로 채택하지 않는다.
+자체 입력 형식만 쓰는 방식은 기존 .inp와 외부 reference를 직접 활용하는 현재 작업 흐름과 맞지 않는다.
+
+## 영향
+
+입력과 kernel의 연결·차이를 명시해야 한다. Exact 수치 일치는 가능하지만 내부 동등성의
+증거가 아니다. Unknown model-affecting 입력은 silent approximation 대신 실패한다.
@@ -0,0 +1,24 @@
+# 검증 환경과 private backend
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+수치 library의 package target·integer·resource와 Windows runtime이 core로 퍼지면
+물리 코드와 설치 환경을 독립적으로 검증하기 어렵다.
+
+## 결정
+
+현재 CMake/MSVC x64 Debug/CTest와 C++17 이상을 검증 기준으로 유지한다. MKL·TBB·
+HDF5·Win32는 backend-neutral 경계 뒤에 두고 project-owned dependency target과 runtime staging을 사용한다.
+
+## 대안과 선택 이유
+
+Vendor 타입을 public에 노출하면 adapter 교체가 core와 consumer 변경으로 전파된다.
+다른 toolchain의 즉시 지원 선언은 해당 환경의 numerical/runtime evidence 없이 할 수 없다.
+
+## 영향
+
+Dependency 추가마다 build뿐 아니라 실제 runtime closure를 확인한다. 개인 설치 경로를
+제품 계약으로 고정하지 않으며 실행기 MSBuild 지원을 FESA의 별도 제품 검증으로 취급하지 않는다.
@@ -0,0 +1,24 @@
+# 모델 정의와 equation 소유권
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+Source label, 모델 배열과 equation 번호는 서로 다른 수명과 의미를 가진다. 실행별
+제약이나 procedure가 바뀌어도 원본 모델과 결과 identity는 보존되어야 한다.
+
+## 결정
+
+Domain이 전체 정의를 소유하고 AnalysisModel은 non-owning view로 둔다.
+DofManager가 DOF·partition·equation·sparse pattern을 전담한다. Semantic definition과 numerical object는 검증된 생성 경계로 연결한다.
+
+## 대안과 선택 이유
+
+Node/Element에 equation 번호를 저장하면 여러 실행 상태가 원본 정의에 섞인다.
+모델 복사는 별도 수명·동기화 비용을 만들고 source identity가 다른 복사본처럼 취급될 수 있다.
+
+## 영향
+
+Domain 수명을 view보다 길게 유지해야 한다. Parser나 consumer가 모든 concrete storage를
+알아야 하는 구조를 피하되 speculative clone·registry·사용하지 않는 capability는 추가하지 않는다.
@@ -0,0 +1,24 @@
+# Local contribution과 결정적인 조립
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+병렬 계산의 속도를 얻으면서 같은 입력의 sparse 구조·합산·진단·결과 순서를
+재현해야 한다. Floating-point 누적 순서는 수치 결과에 영향을 준다.
+
+## 결정
+
+Local contribution은 index-owned buffer에 계산하고 join 뒤 stable COO와 고정된
+reduction으로 global matrix/vector에 반영한다. Global pattern은 DOF owner가 정의한다.
+
+## 대안과 선택 이유
+
+Worker의 직접 global CSR 갱신은 race 또는 lock 순서 의존을 만든다.
+Hash iteration에 의존한 누적도 stable source ordering을 보장하지 않는다.
+
+## 영향
+
+Contribution buffer와 정렬 비용을 부담한다. Optimization은 같은 순서·물리 의미·실패
+선택을 보존해야 하며 더 빠르다는 이유로 결정론을 선택 기능으로 만들 수 없다.
@@ -0,0 +1,24 @@
+# Candidate 검증과 공식 HDF5
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+반복 중 일부 값 또는 저장 중 일부 dataset만 성공한 결과를 정상 해석으로 읽으면
+실패 뒤 기존 유효 결과까지 신뢰할 수 없게 된다.
+
+## 결정
+
+State와 recovery는 완성·검증된 candidate만 반영한다. 공식 결과는 입력 lexical sibling의
+HDF5이며 임시 파일의 self-check·close 후 최종 교체한다. Output lease로 동일 output pair의 동시 쓰기를 막는다.
+
+## 대안과 선택 이유
+
+실패 중간 state나 final 파일에 직접 누적하면 rollback 범위를 명확히 하기 어렵다.
+CSV를 공식 결과로 두면 계층적 위치·단위·identity 계약을 현재 방식으로 유지할 수 없다.
+
+## 영향
+
+Candidate와 readback 비용을 부담한다. State commit과 file finalize, final HDF5와
+진단 로그의 수명은 구분하며 실패 시 로그까지 동일하게 보존된다고 약속하지 않는다.
@@ -0,0 +1,24 @@
+# Procedure별 lifecycle과 full residual
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+정적·비선형·고유치·동적 해석은 초기화·해법·종료·결과 의미가 다르다.
+반력과 free 잔차는 같은 수치 vector에 있어도 다른 물리적 역할을 가진다.
+
+## 결정
+
+각 procedure가 필요한 state와 solver lifecycle을 소유한다. 기존 선형 정적 해석은
+elimination의 coupling을 유지하고 full residual Kd-F에서 constrained 반력과 free 평형을 구한다.
+
+## 대안과 선택 이유
+
+Static lifecycle에 계속 분기를 누적하면 다른 procedure의 state·종료 의미가 섞인다.
+Constrained 외력만 부호 반전한 반력은 지정 변위와 stiffness coupling을 반영하지 못한다.
+
+## 영향
+
+새 procedure는 입력부터 output까지 연결해야 한다. 빈 free system은 유효한 경우
+지원하며 arbitrary penalty·regularization을 failure의 우회로로 사용하지 않는다.
@@ -0,0 +1,24 @@
+# 원본 reference와 승인된 비교 정책
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+구현에 맞춰 기준 데이터를 고치거나 family마다 scale을 달리 정하면 수치 검증이
+구현과 기준의 순환적 자기 정당화가 된다.
+
+## 결정
+
+기존 reference의 경로·값을 보존하고 source identity·component를 먼저 일대일
+대응한다. Approved family/scale/near-zero/row/RMS/zero-scale 정책과 판정 영향을 유지한다.
+
+## 대안과 선택 이유
+
+Canonical naming·보조 metadata를 필수로 추가하는 방식은 실제 비교에 필요하지 않은
+정리 작업을 gate로 만든다. Missing row 무시·평균·floor·clamp는 다른 모델을 통과시킬 수 있다.
+
+## 영향
+
+필수 원본이 없으면 비교 미실행으로 남긴다. 정책 변경은 사용자 승인과 영향 검증을
+요구하며 새 evidence를 생성할 수 있지만 과거 실패 보고와 원본을 소급 수정하지 않는다.
@@ -0,0 +1,24 @@
+# 수치·물리·외부 비교의 분리
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+유한한 해, 선형계 성공 또는 외부 변위 일치만으로 정식화·회복·에너지·시간 정확성을
+모두 확인할 수 없다. HHT의 reference 통과와 temporal 실패도 별개 증거다.
+
+## 결정
+
+동작 검사, analytical/invariant, 필요한 reference와 독립 numerical/physics 판단을
+구분한다. 수식·요소·재료·적분·상태 갱신 변경은 독립 검토를 받는다.
+
+## 대안과 선택 이유
+
+모든 기능에 같은 고정 benchmark 목록을 강제하면 의미 없는 검사를 늘린다.
+반대로 test count나 runner exit만으로 완료를 판정하면 검증되지 않은 물리를 통과로 오인한다.
+
+## 영향
+
+기능별 필수 evidence와 미실행·실패·제외를 명시해야 한다. Release-readiness 감사는
+별도 요청이며 독립 검토·감사 결과가 배포 권한을 부여하지 않는다.
@@ -0,0 +1,24 @@
+# 필요한 전문 작업과 명시적 검증 실행
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+고정 stage·반복 인계·자동 Git·종료 hook 중심 운영은 실질적인 공학 판단보다
+형식적인 상태 유지와 중복 실행을 늘렸다.
+
+## 결정
+
+메인이 범위를 파악해 필요한 전문 작업만 배정한다. 실행기는 config·toolchain·
+backend 명령을 명시 호출 시 한 번 실행한다. 일반 실패는 현재 owner가 수정한다.
+
+## 대안과 선택 이유
+
+전용 coordinator·planning/correction profile·고정 상태기계·retry 예산을 유지하는
+방식은 폐기한다. 검증 script에 commit/push 권한을 묶는 방식도 채택하지 않는다.
+
+## 영향
+
+메인이 작업 범위와 evidence를 확인해야 한다. 반복 승인 없이 승인된 일반 작업을
+이어가되 원격·파괴·외부 비용·상위 계약 변경의 사용자 결정 경계는 유지한다.
@@ -0,0 +1,24 @@
+# 공통 기준과 기능별 상세 계약
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+공통 기준에 모든 기능 진행상태를 누적하거나 같은 checklist를 여러 파일에 두면
+어느 기록이 현재 요구와 상태인지 모호해진다.
+
+## 결정
+
+공통 제품·수치 기준과 기능별 요구·정식화·I/O·결정을 구별한다. Feature의
+FEATURED_AGENTS·PRD·ADR을 유지하고 현재 checklist는 Feature PRD 한 곳에 둔다.
+
+## 대안과 선택 이유
+
+모든 기능에 빈 보고서·requirements·matrix를 일괄 만드는 방식은 중복을 늘린다.
+기존 계약을 새 파일명 규칙에 맞춰 자동 이동·재번호화하면 승인·evidence의 추적성을 잃는다.
+
+## 영향
+
+복잡한 상세 내용만 분리한다. 기존 ID·승인 근거·reference와 과거 운영 이력을 보존한다.
+전체 상태 요약이 기능별 필수 검사를 대체하지 않으며 공통 기준 변경은 별도 요청으로 다룬다.
@@ -0,0 +1,24 @@
+# MITC4 고유치 첫 구현의 경계
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+MITC4 고유치의 첫 구현에서 외부 값 차이와 추가 정확도 개선을 분리해 진행할
+필요가 있었고, 사용자가 모드별 5% 범위의 첫 구현을 승인했다.
+
+## 결정
+
+실제 FEAST와 consistent에서 유도한 lumped mass를 사용한다. 외부 Value는 mode별
+singleton family의 상대오차·RMS 모두 5%로 판정하는 named policy를 적용한다.
+
+## 대안과 선택 이유
+
+공통 RMS 1%를 이 첫 구현에 그대로 요구하는 선택 대신 범위를 명시한 예외를
+채택했다. 다른 모드의 scale로 차이를 흡수하거나 reference를 보정하는 방식은 허용하지 않는다.
+
+## 영향
+
+다른 해석의 RMS 1%와 내부 eigen 잔차·정규화·직교성 기준은 유지한다.
+정확도 개선·보류한 검증은 해결된 것으로 취급하지 않고 과거 1% 실패 기록도 보존한다.
@@ -0,0 +1,24 @@
+# HHT의 consistent kinetic mass
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+유한회전 shell 동역학에서는 회전관성과 configuration에 따른 kinetic kinematics를
+다뤄야 한다. 고유치 계산의 질량 선택을 그대로 옮기면 다른 물리를 해석할 수 있다.
+
+## 결정
+
+HHT에는 사용자 선택인 consistent kinetic mass를 사용하고 analytic null·
+부분구속·회전 관성·convective 항을 보존한다. 물리 가속도와 알고리즘 보조 가속도를 구분한다.
+
+## 대안과 선택 이유
+
+Lumped mass는 비교 연구로 남겼으며 현 HHT 지원의 fallback으로 채택하지 않았다.
+임의 drilling inertia나 부분구속의 full-clamp 치환은 원래 모델을 바꾼다.
+
+## 영향
+
+비대칭 접선·moving null·regularity와 실제 shell temporal 검증 부담이 있다.
+현재 시간수렴 실패를 유지하며 가속도 복구 후보는 독립 검증·채택 전 승인된 해법으로 간주하지 않는다.
@@ -0,0 +1,24 @@
+# Uncoupled shell 열해석부터 구현
+
+- 상태: 기존 승인·인터뷰 합의의 의미 유지
+- 결정 주체: 사용자와 기존 승인 계약의 담당자
+
+## 배경
+
+최종 목표는 양방향 열-구조 연성이지만, 현재는 온도장 자체의 transient 해석과
+검증 범위를 먼저 확정해야 한다.
+
+## 결정
+
+첫 범위는 단일 step uncoupled shell 열해석, 균질 단면의 온도점 5개와 상수 물성,
+고정 증분이다. 초기에 검토한 두께 방향 등온 범위는 5점 온도장으로 대체한다.
+
+## 대안과 선택 이유
+
+즉시 양방향 연성을 구현하는 방식은 현재 요구 범위를 넘는다. 두께 등온 모델은
+아랫면·윗면의 독립 지정 온도와 두께 방향 열전달 요구를 충족하지 못한다.
+
+## 영향
+
+열행렬·flux·반력·에너지·시간수렴을 별도로 검증해야 한다. 두 구간 이차 보간,
+Backward Euler, geometry 근사와 결과 schema는 제안 상태이며 이 범위 결정만으로 채택되지 않는다.
@@ -0,0 +1,20 @@
+# 프로젝트 결정 목록
+
+현재 유지하는 선택과 그 비용을 구분한다. 과거 승인 이력과 수치 기준은 그대로 보존하며,
+아래 기록은 새로운 physics·acceptance 승인이 아니다. 열해석의 제안 방법은 채택 목록에 넣지 않는다.
+
+| 파일 | 유지하는 선택 |
+| --- | --- |
+| `0001-independent-solver.md` | 외부 입력 subset과 독립 솔버 |
+| `0002-build-and-backends.md` | 검증 환경과 private backend |
+| `0003-model-and-equations.md` | 모델 정의와 equation 소유권 |
+| `0004-ordered-assembly.md` | Local contribution과 결정적인 조립 |
+| `0005-state-and-output.md` | Candidate 검증과 공식 HDF5 |
+| `0006-procedure-lifecycle.md` | Procedure별 lifecycle과 full residual |
+| `0007-reference-evidence.md` | 원본 reference와 승인된 비교 정책 |
+| `0008-layered-verification.md` | 수치·물리·외부 비교의 분리 |
+| `0009-explicit-development.md` | 필요한 전문 작업과 명시적 검증 실행 |
+| `0010-feature-contract-ownership.md` | 공통 기준과 기능별 상세 계약 |
+| `0011-eigen-first-implementation.md` | MITC4 고유치 첫 구현의 경계 |
+| `0012-hht-kinetic-mass.md` | HHT의 consistent kinetic mass |
+| `0013-thermal-staged-scope.md` | Uncoupled shell 열해석부터 구현 |