FESADev/docs/hht-implicit-dynamics/io-reduced-coordinate.md

Reduced-coordinate shell HHT I/O 계약

상태: user-approved; implementation-and-readback-pending, 2026-10-12. Owner: io-definition-agent. 사용자 승인된 shell schema v2와 public A 의미를 정의한다. 기본 subset·quantity·inventory·진단·원자 출력은 기존 계약, 외부 비교는 reference 계약을 따른다. 수식 및 acceptance의 owner는 해당 정식화와 Feature PRD이며 이 문서는 수치 기준을 추가하지 않는다.

1. 입력과 authoritative identity

기존 *DYNAMIC, DIRECT, exact h/T schedule, zero BC, constant global translational CLOAD, homogeneous centered MITC4 shell, nodal-lumped-kinetic mass와 기본 alpha/beta/gamma를 유지한다. Reduced method를 선택하는 새 INP keyword/option은 추가하지 않는다. 초기조건·시간변화 하중·restart·rank-changing branch 등 의미 있는 미지원 입력은 기존 진단으로 fail closed한다. 기존 allowlisted *RESTART, WRITE, FREQUENCY=0은 warning no-op이며 restart 지원이 아니다.

Source step/instance/node/element label, canonical inventory, accepted frame/index와 exact time이 결과 identity다. Private chart/split/pivot·reduced equation ID는 source identity를 대체하지 않는다. Full node-major q/v/a는 각각 기존 translation/global total rotation-vector chart의 위치·chart velocity·physical endpoint chart acceleration이다. 단위·component·orientation·angular velocity/acceleration·reaction·stress/resultant·energy·momentum의 물리 의미는 변경하지 않는다. Inertia와 recovery는 reconstructed full physical q/v/a로 계산하며 reduced residual 또는 public A로 대체하지 않는다.

2. Full A와 private integrator history

Quantity	승인 의미
full q	Q(p,t)
full v	Qp*vp+Qt
full a	Qp*ap+Qpp[vp,vp]+2*Qpt*vp+Qtt
public full A	frame n≥1에서 (1+alpha)*a_n-alpha*a_(n-1); frame0에서 a0. Full-chart diagnostic filter combination이며 full q/v의 Newmark predictor driver가 아님
private p/vp/ap/Ar	Reduced integrator history. Ar=(1+alpha)*ap_n-alpha*ap_(n-1), 초기 Ar0=ap0; analysis 소유
private chart context	Accepted branch/split/pivot 및 필요한 chart context. Model 정의와 분리하여 history와 함께 commit

Public A의 dataset path nodal/algorithmic_acceleration, shape [N,6], float64, AUX1..AUX6 및 physical a와 같은 단위를 유지한다. Ar 또는 Qp*Ar를 이 dataset에 저장하지 않는다. Public A만으로 private history를 복원하거나 restart할 수 없다. Private reduced/chart dataset이나 새로운 공개 restart API는 추가하지 않는다.

3. Shell schema v2

Schema identity (feature_id,analysis_procedure,schema_version)는 hht-implicit-dynamics,hht-implicit-dynamics,2다. 기존 shell mandatory dataset paths/shapes/dtypes/components·model/frame identity attrs는 유지하고 다음 변경을 함께 적용한다.

위치	필수 값
/metadata::schema_version	uint64 little-endian 2
/metadata::time_integration_formulation	UTF-8 reduced-coordinate-HHT-with-physical-rate-reconstruction
모든 기존 result dataset의 schema_version	uint64 little-endian 2
nodal/algorithmic_acceleration::quantity_semantics	UTF-8 full-chart-HHT-filter-combination-not-predictor-driver

acceleration_convention=physical-endpoint-and-auxiliary-separated, mass_formulation=nodal-lumped-kinetic, internal formulation 및 기존 q/v/physical-a semantics는 유지한다. Dataset version만 2이고 metadata가 1인 파일, marker 누락/오타, A의 과거 semantics, 잘못된 mass/coefficients/inventory/nonfinite는 dynamic-output-schema 실패다. Mandatory attrs의 dtype/rank와 attrs inventory 검사도 갱신한다.

과거 v1 파일은 당시 full-coordinate 실행 evidence로 보존한다. 현재 reduced-shell executor의 writer/self-check는 v2 identity를 사용하며 v1을 reduced 결과로 수용하지 않는다. Comparator는 schema1의 historical full-coordinate branch와 schema2의 reduced branch를 구분하여 읽는다. Historical branch는 기존 marker 생략 또는 명시된 full-coordinate marker를 허용하고 dataset version1을 요구하며, 현재 reduced 결과의 검증 통과로 승계하지 않는다. Marker 자동 보충·metadata rewrite·v1→v2 재표시는 금지한다. Solid HHT와 static/eigen의 schema를 변경하지 않는다.

4. 초기화·candidate·BC·실패

Frame0는 기존 0+, exact full q0=v0=0 및 full endpoint 평형·hidden consistency를 만족하는 a0를 유지한다. 같은 Q branch의 p0/vp0/ap0가 이 full state를 복원해야 한다. 이를 표현하지 못하면 dynamic-initial-consistency 실패이며 silent projection·첫 frame 제외·O(h²) 초기 rate 보정은 허용하지 않는다.

Private reduced history/chart와 public accepted full frame을 동일 candidate acceptance에서 원자 commit한다. Full original free residual·physical recovery·hidden diagnostics·finite/inventory/constraint 검사가 완료되기 전에 일부 상태만 commit하지 않는다. Hidden defects의 진단 의미는 유지하며 I/O owner가 새로운 Newton gate를 도입하지 않는다. 실패한 trial의 branch/pivot/cache/Ar는 마지막 committed state/history와 최종 HDF5를 변경하지 않는다.

Zero BC component selector는 full q/v/a/A에서 exact zero다. Partial rotational BC는 free 공간과 admissible null의 실제 교집합을 사용하며 모든 node에 5/node reduced dimension을 강제하지 않는다. Empty-null/all-clamped/mixed-node 상태도 원 full 방정식·inventory를 보존한다. Coupled algebraic branch를 node별 독립 scalar root로 바꾸거나 deterministic ordering을 worker 완료 순서에 맡기지 않는다.

실패 조건	Diagnostic binding
초기 full state 복원 불가	dynamic-initial-consistency
admissible null/rank, coupled chart regularity, reduced positive mass 실패	dynamic-mass-regularity
invalid branch/chart, nonfinite reconstructed state	dynamic-invalid-state 또는 구체적인 기존 geometry code
inner branch/outer Newton 한도, linear solve 실패	dynamic-nonconvergence / dynamic-linear-solve; stage 구분
schema/marker/A semantics·readback 불일치	dynamic-output-schema

Step/increment/time/stage와 가능한 source node/element identity 및 원 진단 context를 유지한다. Fixed patch 밖에서는 검증된 history transport가 없으면 fail closed한다. Silent rechart·clamp·epsilon mass·새 exit code는 추가하지 않는다.

5. 구현·검증 인계

실제 consumer	필요한 변경
src/fesa/io/hdf5/dynamic_hdf5_results_writer.cpp	Metadata allowed attrs/쓰기 및 reopen self-check, 모든 result dataset version, A quantity semantics를 v2에 연결. Physical quantity 정의·dataset inventory·원자 finalize 유지
tests/unit/io/hdf5/dynamic_hdf5_results_writer_test.cpp	v2 marker/version/A readback, a/A 구분, wrong/missing marker·mixed version 실패 및 기존 final 보존 확인
scripts/verification/compare_hht_dynamic.py	Metadata version/marker 및 dataset version strict 검사 갱신. Source node/frame/time·U/UR projection·202 families·tolerance 유지
tests/test_compare_hht_dynamic.py	현재 fixture를 v2 identity로 정의; v2 missing/wrong marker·mixed version 거부와 historical v1 branch의 별도 의미 검증. 과거 evidence 파일 수정 금지
DynamicAnalysisState와 shell dynamic procedure	private reduced history와 full accepted frame의 transactional ownership; public A를 full predictor driver로 재사용하지 않도록 경계 분리

Reference CSV에는 A/V/physical acceleration 또는 reduced state가 없다. 비교는 원래 full U/UR이며 v2 marker를 허용했다는 이유로 새로운 reference PASS를 승계하지 않는다. C08b P 및 추가 grid 승인은 Feature PRD의 acceptance 변경이며 reference U/UR tolerance 변경이 아니다.

열린 upstream 항목은 실제 coupled Q branch/derivatives 및 exact tangent, partial BC의 admissible chart, patch history transport, 초기 equivalence와 rollback evidence다. Writer/readback·solver/reference 실행은 이 문서 owner가 수행하지 않았다. 계약 승인만으로 구현 또는 수치·물리 검증 완료를 주장하지 않는다.