FESADev/docs/mitc4-shell-feast-eigen/implementation-interfaces.md

구현 경계와 source/test 대응

• Feature ID: mitc4-shell-feast-eigen
• Owner: implementation-planning-agent
• Input contract revision: r2
• 기본 보고서: implementation-plan

실제 repository 확장점

기존 DomainMappingContext::Impl이 syntax·material/property·sole step candidate를 소유하고 thin mapper들이 finalize를 호출한다. 이 범위를 확장하며 parallel parser/새 registry를 만들지 않는다. KeywordBlock에는 physical_lines가 있지만 DataLine에는 fields/location만 있어 I/O의 raw count/density data를 보존하려면 original_line이 필요하다.

Domain::Steps()와 AnalysisModel::Step()은 기존 static API다. 별도 frequency 정의를 추가하고 active boundary/location view로 DofManager를 연결한다. StaticStep의 미사용 time/load fields에 frequency 의미를 끼워 넣지 않는다. FrequencyStep은 boundaries/source options/N을 소유하고 density는 material identity에 연결된 Domain composition record다. Concrete material base를 optional capability로 늘리지 않는다.

현재 ElementFactory::CreateShell은 private이고 unique_ptr<Element>를 반환한다. 승인 shell-only procedure에 필요한 typed CreateMitc4Shell 생성 seam을 추가하되 기존 generic Create도 같은 checked construction을 사용한다. Consumer의 downcast/type-switch 없이 typed mass contribution과 기존 ElementView stiffness contribution을 같은 layout/scatter에 준다. Global equation/index/pattern은 끝까지 DofManager 소유다.

Mitc4Shell::Stiffness는 현재 min rotary diagonal을 사용하고 NonlinearMitc4Shell::Create는 그 초기 kd를 저장한다. 새 private trace helper로 앞 경계만 바꾸면 nonlinear은 기존 frozen path를 재사용한다. Tests는 formula 값 변경뿐 아니라 완전한 geometry/frame 재생성·partial BC·반력·objective tangent를 검증한다.

hdf5_internal::WriteModel은 model datasets와 static metadata를 함께 쓴다. Model-only seam을 분리하고 기존 WriteModel이 같은 static metadata와 datasets를 호출하도록 유지한다. Eigen은 그 model-only 함수와 eigen-only metadata/schema를 사용한다. 기존 static reader inventory는 그대로 두며 eigen discriminant 없이 새 파일을 static으로 읽지 않게 테스트한다.

Step별 API와 책임

Step	완성되는 경계	소유 데이터와 호출 규칙
0	FrequencyStep, Domain::FrequencySteps/Densities, active view, exact mapping	Raw syntax→validated immutable records; density/t/source resolution; static API/순서 보존
1	ComputeDrillingScale→Mitc4Shell::Stiffness	초기 physical20만 입력, eight diagonals scaled mean; nonlinear 초기 저장 경로 재사용
2	ConsistentMass→DeriveLumpedMass→ShellMassAssembler	Original24/C0..2 snapshot 보존, nodal6 blocks, stable COO/reduction; same source scatter
3	ReduceEigenSystem/RestoreEigenvector, DofManager finite layout	Original free K/ML 별도 보존, node P/Z/L/rcond와 finite pattern, sparse block whitening
4	FeastBackend/InitialSpace/Search→EigenSolver::SolveLowest	Vendor-private actual calls, neutral scalar/vector/history output; actual N/n/c/m0 각각 구분
5	ValidateEigenpairs→LinearFrequencyProcedureExecutor::Execute	All-c 검증 후 paired N candidate, 전체 c metrics/history, Domain/view 수명, 아직 accepted commit 아님
6	EigenResultsWriter/WriteEigenSchema/SelfCheckEigen→prepared CLI finalization	Log close, candidate close/readback, final replacement 뒤 nofail state swap
7	EigenReferenceComparison와 fresh-run portfolio	Source-key Value-only join/common policy, raw/new-binary evidence, canonical3 보고서

Private helper names는 Step에 지정한 책임·signature 역할을 지킨다. Parameter type의 상세 배치와 작은 private structs는 Implementation이 routine 선택할 수 있지만 승인 owned files 밖 확장, physics/schema/tolerance 변경은 Coordinator에 반환한다. Public header는 standard/FESA value type만 노출하고 MKL_INT, HDF5 hid_t, Win32 handle/header는 private source에 둔다.

TDD file boundary

각 Step index는 tests/build/reports를 포함한 정확한 path 목록을 가진다. 현재 scripts/msvc_harness/tdd_policy.py는 production basename에 대응하는 test basename을 찾으므로 새 C++ header/source의 test를 반드시 먼저 생성한다. 아래는 새 경계별 대응이며 기존 production은 해당 existing test와 추가 feature suite를 함께 사용한다.

Production basename	Related test path
frequency_step	tests/unit/model/frequency_step_test.cpp
domain_mapping_context	tests/unit/io/abaqus/domain_mapping_context_test.cpp
mitc4_drilling_scale	tests/unit/elements/mitc4_drilling_scale_test.cpp
mitc4_shell_mass	tests/unit/elements/mitc4_shell_mass_test.cpp
shell_mass_assembler	tests/unit/assembly/shell_mass_assembler_test.cpp
eigen_reduction	tests/unit/analysis/eigen_reduction_test.cpp
feast_backend	tests/unit/solvers/eigen/feast_backend_test.cpp
feast_initial_space	tests/unit/solvers/eigen/feast_initial_space_test.cpp
feast_search	tests/unit/solvers/eigen/feast_search_test.cpp
eigen_solver	tests/unit/solvers/eigen/eigen_solver_test.cpp
mkl_feast_eigen_solver	tests/unit/solvers/eigen/mkl_feast_eigen_solver_test.cpp
eigen_analysis_state	tests/unit/analysis/eigen_analysis_state_test.cpp
eigen_validation	tests/unit/analysis/eigen_validation_test.cpp
linear_frequency_procedure	tests/integration/analysis/linear_frequency_procedure_test.cpp
eigen_results_writer	tests/unit/results/eigen_results_writer_test.cpp
eigen_hdf5_results_writer	tests/unit/io/hdf5/eigen_hdf5_results_writer_test.cpp
eigen_hdf5_schema	tests/unit/io/hdf5/eigen_hdf5_schema_test.cpp
hdf5_model_writer	tests/unit/io/hdf5/hdf5_model_writer_test.cpp
prepared_analysis	tests/unit/analysis/prepared_analysis_test.cpp

Existing stem의 model_types/domain/analysis_model/dof_manager/input_syntax/input_reader/ mitc4_shell/element_factory/fesa_application은 현재 대응 tests가 있고 각 Step의 관련 test와 함께 검증한다. 새 test registration은 tests/CMakeLists.txt, 새 library cpp는 src/fesa/CMakeLists.txt만 소유한다. Root CMake/dependency/preset 변경은 필요하지 않다. Vendor link/runtime는 기존 Fesa::MKL/HDF5/TBB target closure로 실제 API를 실행해 확인한다. 명백한 missing runtime가 발견되면 임의 PATH 우회나 scope 확대 대신 exact evidence를 반환한다.

현재 tests/CMakeLists.txt의 fesa_tests는 세 executable fesa_unit_tests, fesa_integration_tests, fesa_reference_tests에 의존하는 aggregate target이다. 따라서 Step의 --target fesa_tests는 reference까지 빌드한다. 새 tests/unit/ 파일은 unit executable, tests/integration/ 파일은 integration executable, tests/reference/ 파일은 reference executable에 등록한다. 각 executable의 기존 runtime staging과 gtest_discover_tests를 유지한다. Focused inventory에서 새 이름 모두가 존재해야 한다.

Candidate commit과 테스트 주입

별도 EigenAnalysisState는 N vectors와 raw scalars/source, all-c checks/history만 소유한다. Working reduction/solver scratch는 procedure 실행 동안 유지되고 accepted state에 global dense matrix나 미래 dynamics state를 남기지 않는다. Swap은 noexcept이고 소유 vector/record 교환만 수행한다. Execute 반환 candidate를 accepted state라고 보고하지 않는다.

Prepared/static 기존 overload는 보존하고 frequency executor/result/writer가 있는 overload를 추가하여 procedure 선택을 한 경계에 둔다. Output finalization은 candidate를 완성/검증/close하고 final replacement 성공 뒤 state swap을 수행한다. 이 순서에 fallible callback/allocation을 남기지 않는다. Failure injection은 EigenSolver/EigenResultsWriter 및 private backend/schema seam에 제한한다. 새로운 public CLI failure flags는 없다. Raw HDF5 mutation은 test-local generated file에서만 하고 저장 reference input/TXT/CSV는 read-only다.