modify documents

docs/mitc4-shell-feast-eigen2/requirements.md

@@ -1,17 +1,24 @@
-# MITC4 질량행렬·FEAST eigen 요구사항
+# MITC4 eigen 요구사항과 근거
+
+
+
+<a id="requirements"></a>
+
+<a id="requirements--mitc4-질량행렬feast-eigen-요구사항"></a>
+## MITC4 질량행렬·FEAST eigen 요구사항
 
 - Feature ID: `mitc4-shell-feast-eigen2`
 - Requirement baseline revision: `r2` (2026-09-10, 사용자 승인에 따른 022 외부 accuracy 기준 변경)
-- Owner: `requirement-agent`
 - 상태: 요구사항 기준선 작성. 구현·수치 검증 또는 readiness 통과 기록이 아니다.
 
 기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
 [ADR-028](../ADR.md#adr-028), [ARCHITECTURE](../ARCHITECTURE.md),
 [TOLERANCE](../TOLERANCE.md). 현재 작업·checklist는 [PRD](PRD.md),
 소유권은 [FEATURED_AGENTS](FEATURED_AGENTS.md), 결정은 [ADR](ADR.md)을 따른다.
-근거 구분·기존 ID 대응·미결정은 [requirements-evidence](requirements-evidence.md)에 둔다.
+근거 구분·기존 ID 대응·미결정은 [requirements-evidence](requirements.md#requirements-evidence)에 둔다.
 
-## 범위와 해석 의미
+<a id="requirements--범위와-해석-의미"></a>
+### 범위와 해석 의미
 
 Consistent mass를 계산하고 그 결과로부터 lumped mass를 유도하며 실제 무감쇠 선형
 고유진동 해석은 **derived lumped mass와 MKL FEAST**를 사용한다. 같은 lumped mass를
@@ -46,7 +53,8 @@ beam/solid/shell, concentrated/nonstructural mass, composite/offset/variable thi
 별도 frequency interval/shift 사용자 기능, Lanczos/AMS 대체 backend, reference
 생성·수정·복원과 외부 배포도 제외한다. Eigen 기능의 밀도 필수 조건을 기존 static에 확대하지 않는다.
 
-## Requirement verification matrix
+<a id="requirements--requirement-verification-matrix"></a>
+### Requirement verification matrix
 
 각 행은 하나의 관찰 의무이며 acceptance는 해당 요구와 검증 조건을 충족하는 것이다.
 현재 요청은 이 의무를 정의하는 **requirement 단계만** 수행한다. 아래 검증은 후속 솔버
@@ -54,11 +62,11 @@ beam/solid/shell, concentrated/nonstructural mass, composite/offset/variable thi
 I/O layout은 후속 전문 owner가 필요한 시점에 정의한다. 외부 tolerance는 공통 정책을 따른다.
 
 출처: `U`=[새 Feature ADR](ADR.md)의 기존 명시 사용자 결정 적용,
-`R`=[근거 문서](requirements-evidence.md)의 reference 관찰,
+`R`=[근거 문서](requirements.md#requirements-evidence)의 reference 관찰,
 `P`=위 프로젝트 기준, `L`=[기존 shell 요구](../linear-static-mitc4-shell/requirements.md),
 `N`=[기존 nonlinear I/O](../nonlinear-static-newton-raphson/io.md)의 공통 경로·실패 의미.
 `Formulation`, `NR`, `I/O`, `Implementation`, `Physics`는 전문 책임이며 고정 호출 단계가 아니다.
-각 행은 [기존 r3](../mitc4-shell-feast-eigen/requirements.md)의 같은 번호에 대응한다.
+각 행은 [기존 r3](../mitc4-shell-feast-eigen/requirements.md#requirements)의 같은 번호에 대응한다.
 
 | Requirement ID | Shall statement | 측정 가능한 acceptance / verification method | 출처·후속 owner |
 | --- | --- | --- | --- |
@@ -90,7 +98,8 @@ I/O layout은 후속 전문 owner가 필요한 시점에 정의한다. 외부 to
 | FEM-REQ-MITC4-EIGEN2-026 | 솔버는 계산된 consistent mass에서 lumped mass를 유도하고 승인된 질량·관성 보존 계약을 검증해야 한다. | 유도 관계·독립 lumping oracle·총 병진 질량 보존, 차원/대칭성/물리 kinetic-energy 비음성, 물리 회전 관성과 drilling nullspace 의미 검사. Lumping 수식·좌표 block 처리·정확한 관성 불변식과 threshold는 Formulation/NR가 고정 | U, P, L; Formulation, NR |
 | FEM-REQ-MITC4-EIGEN2-027 | 개선된 numerical drilling stabilization은 같은 물리 모델의 좌표·접평면 기저 선택에 공변적이고 기존 비물리 역할을 유지해야 한다. | 독립 재계산한 stabilization/complete K의 congruence, finite·대칭·양의 numerical stabilization, 물리 rigid modes 보존, physical recovery 제외 및 결정론 검증. Partial BC의 NR-MFE-001과 대응 정적 response를 필수 통과시키며 기존 static의 동일 scale 사용 경로도 정합 검증; 수식·threshold는 Formulation/NR 소유 | U, L; Formulation, NR, Implementation, Physics |
 
-## 지정 reference와 남는 검증 범위
+<a id="requirements--지정-reference와-남는-검증-범위"></a>
+### 지정 reference와 남는 검증 범위
 
 Eigen input은 `reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp`, 외부 reference는
 같은 폴더의 `shellNL-eigen-meshfine eigenvalues.txt`를 그대로 사용한다. 입력의
@@ -115,7 +124,8 @@ bitwise equality가 아니라 승인된 물리·identity·공통 정책으로
 reaction의 local distribution 검토는 별개다. 알려진 partial-BC 반례를 full-free/full-clamp
 사례만으로 대체하거나 실패 수치를 기대값으로 재생성해 정당화하지 않는다.
 
-## 사용자 제외 예제
+<a id="requirements--사용자-제외-예제"></a>
+### 사용자 제외 예제
 
 다음 네 예제는 `reference/temp/` 아래 원본뿐 아니라 옛 경로, 복사 input, cached HDF5·log·
 추출 결과를 통한 검증에서도 제외한다. 원본 열람·artifact audit·solve·비교·복원 또는
@@ -133,10 +143,148 @@ reaction의 local distribution 검토는 별개다. 알려진 partial-BC 반례
 명시적으로 보고한다. 과거 test 수 `362/352`를 새 완료 조건으로 사용하지 않고 실제 남은
 의무·선택·실행·사용자 제외를 구분한다.
 
-## 이번 완료와 후속 판단의 경계
+<a id="requirements--이번-완료와-후속-판단의-경계"></a>
+### 이번 완료와 후속 판단의 경계
 
 이번 완료는 요구·출처·coverage·링크의 정적 확인까지다. 구현/FEAST/build/test/reference,
 독립 numerical/physics review와 release-readiness는 미실행이다. 기존 명시 release-readiness
 감사 요청은 후속 요구 기록으로 보존하되 이번 요청의 실행 범위나 모든 기능의 고정 단계
 의무로 확대하지 않는다. 메인이 필요한 후속 전문 작업과 evidence를 판단한다.
 공통 문서·기존 Feature·source·test·reference는 읽기 전용이며 Git은 메인이 소유한다.
+
+<a id="requirements-evidence"></a>
+
+<a id="requirements-evidence--요구사항-근거와-적용-경계"></a>
+## 요구사항 근거와 적용 경계
+
+- Feature ID: `mitc4-shell-feast-eigen2`
+- Requirement baseline revision: `r1`
+- 작성일: `2026-09-08`
+- 원본: [requirements.md](requirements.md#requirements), 현재 작업: [PRD](PRD.md).
+
+기준은 [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
+[ADR-028](../ADR.md#adr-028), [새 Feature ADR](ADR.md)이다. 이 문서는 근거와 미실행을
+구분하며 새 수학·구현 acceptance 승인이나 solver readiness 판정이 아니다.
+
+<a id="requirements-evidence--근거의-종류와-재사용"></a>
+### 근거의 종류와 재사용
+
+| 근거 | 재사용하는 내용 | 이번 기준선으로 가져오지 않는 것 |
+| --- | --- | --- |
+| 2026-09-08 사용자 요청과 [새 PRD](PRD.md) | 새 Feature 이름, requirement부터 재시작, 유용한 기존 자료 참고, 작업 중 commit; 최종 지시로 requirement 단계만 수행 | Research 이후 실행 권한·전체 단계 자동 진행·push 권한 |
+| [기존 ADR](../mitc4-shell-feast-eigen/ADR.md)의 MFE-ADR-001/002/004/005 | MKL FEAST, consistent→derived lumped→eigen, 지정 reference의 Value-only, 입력의 mode count 권위 | Mass variant 선택 API, 다른 backend, 외부 mode-shape acceptance |
+| 같은 ADR의 MFE-ADR-007 | 좌표 공변적 stabilization 개선 및 영향받는 static/eigen 검증의 명시 사용자 승인 | 특정 trace 공식 또는 기존 NR pass의 자동 채택 |
+| 같은 ADR의 MFE-ADR-013 | reference/temp 네 예제와 옛 경로·복사·cache 검증 제외 | 과거 14개 blob·이동 commit·검사 수를 이번 재확인으로 보고 |
+| [기존 requirements r3](../mitc4-shell-feast-eigen/requirements.md#requirements), [기존 evidence r3](../mitc4-shell-feast-eigen/requirements.md#requirements-evidence) | 27개 관찰 의무, 단위·identity·실패·남는 static/internal portfolio, 알려진 partial-BC 반례 | 기존 revision의 수식·threshold·영속 문자열이 새 Feature에 자동 승인되었다는 문구 |
+| 기존 [research evidence](../mitc4-shell-feast-eigen/research.md#research-evidence), [formulation](../mitc4-shell-feast-eigen/formulation.md#formulation), [NR](../mitc4-shell-feast-eigen/numerical-review.md#numerical-review), [I/O](../mitc4-shell-feast-eigen/io.md#io) | 후속 전문 작업에서 필요한 근거·후보·반례를 찾을 위치 | 이번에 새로 조사·검토·검증한 evidence라는 주장 |
+| 기존 [PRD 사용자 요구](../mitc4-shell-feast-eigen/PRD.md#사용자-요구와-승계-경계) | 명시 release-readiness 감사 요청의 이력 보존 | 옛 고정 9-stage 순회, Hook·phase 상태·중복 수동/자동 실행의 복원 |
+
+요구사항 작성 당시 기존 r3 요구 문서는 **당시 worktree의 미커밋 자료**를 읽었다.
+현재 링크는 정리된 해당 기록을 가리킨다. 당시 HEAD/commit에 동일 내용이 있었다고 가정하지 않는다. 과거 공개 문헌 조사도
+기존 evidence에 기록된 당시 이력으로만 참조한다. 이번 작업은 외부 문헌 조사·정식화 유도·
+독립 수치 검토를 수행하지 않았다.
+
+기존 `NR-MFE-001`은 같은 물리 partial rotation BC에서 좌표를 회전하고 stiffness를
+재계산할 때 나타난 반례다. 기존 evidence의 numerical 값은 재계산하지 않았다. `014/027`은
+알려진 사례를 검증에서 배제하지 않는 의도를 승계한다. 이전 행렬을 단순 기저변환하는
+검사만으로 geometry부터 재계산한 complete K의 공변성 검사를 대체하지 않는다.
+기존 linear 요구 `FESA-REQ-LSMITC4-034/056`과
+[nonlinear formulation §10.3](../nonlinear-static-newton-raphson/formulation.md#103-fixed-scale-and-potential)의
+scale 선정 부분이 영향 대상이며 다른 물리·lifecycle 의미를 교체하지 않는다.
+
+<a id="requirements-evidence--기존-id와-새-id-대응"></a>
+### 기존 ID와 새 ID 대응
+
+기존 열은 prefix `FEM-REQ-MITC4-EIGEN-`, 새 열은 prefix
+`FEM-REQ-MITC4-EIGEN2-`를 생략한다. 27개 ID를 1:1로 대응하며 아래 요약은
+요구사항 본문의 acceptance를 대신하지 않는다.
+
+| 기존 suffix | 새 suffix | 보존하는 관찰 의무·변경 경계 |
+| --- | --- | --- |
+| `001` | `001` | 원형상·무응력 단일 무감쇠 procedure |
+| `002` | `002` | S4/S4R의 기존 물리 의미와 stabilization 개선 분리 |
+| `003` | `003` | Material/section의 양의 유한 밀도 연결과 진단 |
+| `004` | `004` | 기존 geometry/director/thickness 유효성 |
+| `005` | `005` | Consistent mass의 계산·독립 oracle·lumping 원본 |
+| `006` | `006` | 물리 병진/회전 관성과 drilling null |
+| `007` | `007` | 같은 DOF/constraint·결정적 조립 |
+| `008` | `008` | 실제 partial BC에서 유한 spectrum 보존·FEAST admissibility |
+| `009` | `009` | 입력 요청의 낮은 N개·zero modes·불가능 요청 진단 |
+| `010` | `010` | 오름차순 mode identity·multiplicity |
+| `011` | `011` | Derived lumped mass로 실제 MKL FEAST 실행 |
+| `012` | `012` | Backend 실패·미수렴·불완전 모드의 성공 반영 금지 |
+| `013` | `013` | 같은 lumped M의 residual·normalization·orthogonality |
+| `014` | `014` | 두 mass와 complete K/eigen의 물리·좌표 불변식 |
+| `015` | `015` | 원본 Frequency 및 부수 옵션의 명시적 의미 처리 |
+| `016` | `016` | 미지원 모델·옵션의 silent no-op 거부 |
+| `017` | `017` | HDF5 quantity·단위·source/mode/backend/mass 식별 |
+| `018` | `018` | 내부 modal vectors와 source/physical DOF 대응 |
+| `019` | `019` | 검증 candidate 반영과 state/final output 실패 보존 |
+| `020` | `020` | 지정 eigen TXT Value-only 외부 비교 |
+| `021` | `021` | Tolerance 전 identity/quantity/schema/finite 검사 |
+| `022` | `022` | 공통 tolerance 유지; family는 후속 NR/I/O 정의 |
+| `023` | `023` | 현행 behavior tests·관련 검사·완료 시 전체검증; 고정 RED/중복 실행 삭제 |
+| `024` | `024` | 남는 shell/shellNL 및 내부 static 회귀·밀도 없는 static 유지 |
+| `025` | `025` | 메인의 evidence 추적 완료 판단·필수 독립 검증; 고정 stage 삭제·감사 요청 이력 보존 |
+| `026` | `026` | Consistent에서 유도한 lumped의 질량·관성 보존 검사 |
+| `027` | `027` | 좌표 공변적 비물리 stabilization 및 partial-BC 정적/eigen 검증 |
+
+<a id="requirements-evidence--현재-원본의-정적-관찰"></a>
+### 현재 원본의 정적 관찰
+
+아래는 메인이 `2026-09-08` 전달한 read-only 관찰이다. Python `pathlib`·regex·finite
+검사와 keyword inventory는 exit `0`이었고 solver 실행은 아니다. Requirement owner는
+원본을 다시 읽거나 hash·산술 검사를 반복하지 않았다. 과거 hash를 현재 확인값으로 옮기지 않는다.
+
+| 대상 | 메인이 확인한 현재 사실 |
+| --- | --- |
+| `reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp` | 729 nodes, 676 S4 elements; density `2700.`, shell section `0.5, 5` |
+| Step/BC | 한 `*Step, name=Step-2, nlgeom=NO, perturbation`; `Set-2` DOF 1~6의 homogeneous boundary 행 |
+| Frequency | `eigensolver=Lanczos, sim, acoustic coupling=on, normalization=mass`; data `10, , , , ,` |
+| `shellNL-eigen-meshfine eigenvalues.txt` | Mode IDs 1~10, finite Value, 중복 mode ID 없음 |
+| Value 순서 | `219507, 885523, 885523, 1855340, 2740230, 2775150, 4149410, 4149410, 6733790, 6733790` |
+| 표시값 반복 | `(2,3)`, `(7,8)`, `(9,10)`에서 같은 표시 Value; 이것만으로 실제 spectral multiplicity를 판정하지 않음 |
+| 남는 static artifact | `rg --files`로 `reference/shell`·`reference/shellNL` 각각 inp 및 displacements/reactions/stresses CSV 존재 확인; 내용·수치 통과 확인은 아님 |
+
+TXT의 표시 Value는 보정하지 않는다. 단위계는 수치 크기로 추론하지 않는다. 기존 관찰은
+선행 static/load가 없는 단일 frequency 모델과 TXT의 분리된 Value/Freq를 기록한다.
+입력의 유일한 step과 TXT mode를 연결할 수 있다는 것은 요구 정리를 위한 관찰이며,
+comparison readiness·HDF5 projection·frame/family의 최종 정의는 후속 NR/I/O 책임이다.
+
+`reference/temp` 원본은 이번에 읽거나 실행하지 않았다. 네 제외 예제와 남는 coverage의
+원본은 [requirements](requirements.md#requirements--사용자-제외-예제)이며 과거 검사 개수나 cache로
+현재 실행 검증을 대체하지 않는다.
+
+<a id="requirements-evidence--후속-전문-판단과-사용자-결정-경계"></a>
+### 후속 전문 판단과 사용자 결정 경계
+
+아래는 requirement 작성의 blocker가 아니라 후속 작업이 필요할 때 구체화할 사항이다.
+이번 요청으로 그 작업을 시작하지 않는다.
+
+| 후속 owner | 필요한 판단·고정 경계 |
+| --- | --- |
+| Formulation | Consistent→lumped 유도, 정확한 관성 불변식·좌표 block, massless drilling과 실제 global BC의 유한 spectrum 보존, FEAST admissibility, 낮은 N개 완전성. 특정 quadrature·row-sum·projection/whitening 공식은 자동 채택하지 않음 |
+| Formulation·NR | 공변 stabilization과 기존 nonlinear 초기 고정 scale lifecycle의 정합, partial-BC 반례·대응 static response 및 개선된 pencil 재검증. 기존 trace scale 공식·NR pass를 새 승인으로 간주하지 않음 |
+| NR | 독립 내부 oracle·scale/threshold·검증 충분성·FEAST controls 검토. 외부 eigen Value는 blocking acceptance이며 비교 family는 공통 TOLERANCE의 같은 model/step/frame/quantity/차원/좌표/판정 영향 규칙 안에서 정의; 과거 singleton family 판정을 자동 채택하지 않음 |
+| I/O | 최소 syntax/무해 옵션/진단, source step·mode·modal vector 의미와 HDF5 projection. Exact layout·영속 contract/stabilization 문자열은 이번에 고정하지 않음; 기존 public 호환성 보존 |
+| 메인·Implementation·Physics | 실제 retained test 선택과 실행 evidence·독립 물리 판단. 옛 362/352 수, 미실행·실패·stale를 통과로 소급하지 않으며 명시 감사 요청은 후속 범위와 함께 관리 |
+
+질량 흐름·backend·입력 count·Value-only·stabilization 개선·제외 목록은 기존 명시 결정으로
+해결되어 재질문하지 않는다. 현재 추가 사용자 결정이 필요한 material conflict는 발견하지
+않았다. 후속 증거가 새 물리 근사·지원 축소·공개 호환성/영속 schema의 비호환 변경 또는
+acceptance 변경을 필요로 할 때만 근거와 함께 메인에게 반환한다. Reference 변경이나
+공통 tolerance 완화로 충돌을 해소하지 않는다.
+
+<a id="requirements-evidence--정적-확인과-미실행"></a>
+### 정적 확인과 미실행
+
+Requirement owner는 `Get-Content`·`rg`로 할당 관리문서, 기존 r3 요구·근거, 관련 사용자
+ADR와 프로젝트 PRD/ARCHITECTURE/ADR-028/TOLERANCE 절을 읽었다. 명령 exit `0`.
+`python -B -X utf8 -` 문서 작성 및 정적 검사는 exit `0`으로 27개 새 matrix ID의 유일성·연속성,
+27개 old→new 대응과 상대 파일 링크 존재를 확인했다. 수정 대상은 할당된 두 문서이며
+checklist는 PRD 한 곳에서 관리한다.
+
+C++·FEAST·CMake/CTest·Harness·pytest·외부 solver·reference 수치 비교·독립 numerical/physics
+review·release-readiness는 requirement-only 요청 때문에 미실행이다. 문서 완료는 이 검사의
+통과나 새 수학·구현 acceptance 승인을 뜻하지 않는다. Source·test·공통 정책·기존 Feature·
+phase·reference와 Git 작업은 변경하지 않았다.