NINI
12 KiB
Architecture Decision Records
철학
솔버의 높은 성능과 정확도, Abaqus와의 높은 호환성
ADR-001: Runtime Polymorphism 기반 Solver Core
결정: 요소, 재료, 하중, 경계조건, 해석 알고리즘은 base interface와 runtime polymorphism 기반으로 확장한다.
이유: FESA는 MITC4 Shell 요소에서 시작하지만 RBE2/RBE3, 압력하중, 비선형 정적해석, 동적해석, 열전달, 1D/3D 요소로 확장될 예정이다. 초기에는 정확도와 테스트 가능성이 가장 중요하므로, 각 물리 객체를 독립적으로 테스트하고 교체할 수 있는 구조가 필요하다.
트레이드오프: virtual dispatch 비용과 객체 분산에 따른 캐시 효율 저하가 발생할 수 있다. 대규모 모델 성능이 필요한 영역은 Assembler, element kernel, sparse solver 계층에서 batch 처리 또는 타입별 최적화를 추가한다.
ADR-002: Immutable Domain + Mutable AnalysisState
결정: 입력 모델 정의는 Domain에 보존하고 가능한 한 불변으로 취급한다. 해석 중 변하는 displacement, velocity, acceleration, temperature, force, residual, iteration 정보는 AnalysisState에 분리한다.
이유: 선형 정적해석, 기하비선형 정적해석, 동적해석, 열전달 및 thermal-stress coupling은 서로 다른 상태 변수를 필요로 한다. 모델 정의와 해석 상태를 분리하면 restart, 결과 저장, reference 비교, 테스트가 쉬워진다.
트레이드오프: Domain, AnalysisModel, AnalysisState 사이의 참조/id 관리가 필요하다. 단순한 단일 해석 코드보다 초기 구조가 복잡하지만, 다중 step 및 비선형/동적 확장성을 얻는다.
ADR-003: Step/Frame/Field/History 결과 모델
결정: 해석 결과는 ResultStep, ResultFrame, FieldOutput, HistoryOutput 구조로 저장한다.
이유: 정적해석, 비선형 increment, 동적 time frame, history output을 같은 결과 모델로 다루기 위해 Abaqus와 유사한 step/frame/history 개념이 필요하다. HDF5 저장 구조와 reference 결과 비교도 이 구조를 기준으로 설계한다.
트레이드오프: Phase 1 선형 정적해석만 놓고 보면 결과 구조가 다소 무겁다. 그러나 Phase 2 이후의 비선형 반복, Phase 3 동해석, reaction/history 검증을 위해 초기에 최소 구조를 잡는 편이 낫다.
ADR-004: Strategy + Template Method 기반 Analysis 실행
결정: 해석 알고리즘은 Analysis strategy로 분리하고, 공통 실행 흐름은 template method로 관리한다.
이유: 선형 정적해석, Newton-Raphson 비선형 정적해석, HHT 동적해석, 열전달 해석은 조립, 경계조건 적용, solver 호출, 상태 갱신, 결과 저장이라는 공통 흐름을 공유한다. 공통 흐름을 유지하면서 해석별 반복 구조만 바꾸는 방식이 중복을 줄인다.
트레이드오프: 공통 template이 지나치게 커지면 해석별 특수성이 숨겨질 수 있다. 따라서 Analysis는 전체 흐름을 조율하고, assembly, solver, convergence, time integration은 별도 strategy로 분리한다.
ADR-005: Factory + Registry 기반 Abaqus Input 객체 생성
결정: Abaqus input keyword와 내부 객체 생성을 factory/registry 계층으로 분리한다. Phase 1 입력 범위에는 *Node, *Element, *Nset, *Elset, *Material, *Elastic, *Shell Section, *Boundary, *Cload, *Step을 포함한다.
이유: Abaqus input format 호환성을 유지하면서 요소/재료/하중/경계조건 타입을 계속 추가해야 한다. parser 본체가 모든 타입을 직접 생성하면 확장할수록 변경 비용과 회귀 위험이 커진다.
트레이드오프: registry 초기화와 타입 매핑 코드가 추가된다. 대신 새 keyword나 element type을 추가할 때 parser core의 변경을 최소화할 수 있다.
ADR-006: External Library Adapter Boundary
결정: MKL, TBB, HDF5는 solver core에 직접 노출하지 않고 adapter/wrapper 계층 뒤에서 사용한다.
이유: FESA의 핵심 도메인 모델과 해석 알고리즘이 특정 외부 라이브러리 API에 강하게 결합되면 테스트와 교체가 어려워진다. SparseMatrix, Vector, LinearSolver, ParallelFor, ResultsWriter 같은 경계를 통해 외부 의존성을 제한한다.
트레이드오프: wrapper 계층 구현 비용이 추가된다. 성능이 민감한 부분에서는 adapter가 불필요한 복사를 만들지 않도록 API를 신중히 설계해야 한다.
ADR-007: DofManager가 자유도와 방정식 번호를 전담
결정: node와 element 내부에 equation id를 분산 저장하지 않고, DofManager가 자유도 정의, constrained/free dof mapping, equation numbering, sparse pattern 생성을 전담한다.
이유: 대규모 모델, 경계조건, RBE2/RBE3, 비선형 재조립, thermal-stress coupling에서는 자유도 관리가 solver 품질과 성능에 직접 영향을 준다. 자유도 관리를 별도 객체로 분리하면 경계조건 적용과 행렬 조립이 명확해진다.
트레이드오프: element 계산 시 node id에서 equation id로 변환하는 조회 비용이 생긴다. 이 비용은 assembly precompute 또는 element connectivity cache로 줄인다.
ADR-008: Numerical Convention Baseline
결정: Phase 1 shell node는 6자유도(UX, UY, UZ, RX, RY, RZ)를 사용하고, 기본 precision은 double, id/index/equation numbering은 int64 기반으로 설계한다. 단위계는 Abaqus처럼 강제하지 않고, 결과 부호 규약은 Abaqus를 따른다.
이유: MITC4 Shell, Abaqus input/result 호환성, 대규모 sparse system, 향후 RBE/비선형/동역학 확장을 모두 고려하면 6자유도와 64-bit indexing이 가장 안정적인 공통 기반이다. 단위계를 강제하지 않으면 Abaqus reference와 같은 self-consistent unit workflow를 유지할 수 있다.
트레이드오프: int64 index는 작은 모델에서 메모리 사용량이 증가할 수 있다. 단위계를 강제하지 않으므로 reference case와 사용자 입력 문서에 unit note를 성실히 남겨야 한다.
ADR-009: Essential Boundary Condition and Reaction Recovery
결정: Essential boundary condition은 constrained DOF 제거 방식으로 적용한다. Reaction force/moment는 reduced system 결과만 사용하지 않고 full vector 기준 R_full = K_full * U_full - F_full로 계산한다.
이유: constrained/free DOF mapping이 명확하고 대규모 sparse solve에 적합하며, reaction force는 reference 검증과 하중 평형 검증에서 핵심 출력이다.
트레이드오프: full stiffness/load/displacement 정보를 reaction recovery 시점까지 보존하거나 재구성해야 하므로 메모리와 데이터 흐름 관리가 필요하다.
ADR-010: Drilling DOF Stabilization
결정: Phase 1 MITC4는 drilling 자유도를 유지하고, 작은 인공 drilling 강성을 적용한다. 기본값은 docs/MITC4_FORMULATION.md에서 구현 전 확정한다.
이유: 6자유도 shell node 구조와 Abaqus-style output convention을 유지하면서 singular matrix 위험을 줄이기 위해 drilling stabilization이 필요하다.
트레이드오프: 인공 강성이 물리 응답에 작은 영향을 줄 수 있다. 따라서 값은 parameterized 되어야 하고, reference benchmark에서 민감도를 확인해야 한다.
ADR-011: S4 Mapping and S4R Deferral
결정: Phase 1 Abaqus *Element, TYPE=S4는 FESA MITC4로 매핑한다. S4R은 Phase 1에서 지원하지 않고 추후 별도 ADR과 formulation 업데이트 후 지원한다.
이유: Abaqus S4는 MITC4와 비교 가능한 fully integrated 4-node shell reference로 사용할 수 있다. 반면 S4R은 reduced integration과 hourglass control 결정을 요구하므로 Phase 1의 명확한 baseline formulation 목표와 분리한다.
트레이드오프: 사용자가 가진 S4R reference model은 Phase 1에서 바로 사용할 수 없다. 대신 S4 baseline과 MITC4 benchmark 통과를 먼저 안정화한다.
ADR-012: Singular Diagnostics Required, Mesh Quality Deferred
결정: Phase 1은 singular system 진단을 필수로 제공한다. Aspect ratio, warpage, skew 등 mesh quality 진단은 Phase 1 범위에서 제외한다.
이유: 초기 solver 사용성과 디버깅에는 singular system 원인 추적이 더 직접적으로 중요하다. Mesh quality 진단은 기준과 threshold를 잘못 잡으면 formulation 검증보다 많은 논쟁을 만들 수 있으므로 baseline solver 이후로 미룬다.
트레이드오프: 품질이 낮은 mesh가 조용히 나쁜 결과를 만들 수 있다. Phase 1에서는 reference benchmark와 singular diagnostics로 우선 통제한다.
ADR-013: Technical Dossier Documents as Implementation Contracts
결정: 구현 전 다음 문서를 계약 문서로 유지한다: NUMERICAL_CONVENTIONS.md, ABAQUS_INPUT_SUBSET.md, VERIFICATION_PLAN.md, RESULTS_SCHEMA.md, MITC4_FORMULATION.md.
이유: FEM solver는 DOF, 좌표계, 부호, parser subset, result schema, benchmark 기준이 조금만 흔들려도 구현이 불안정해진다. 구현자가 따를 수 있는 technical dossier를 먼저 고정한다.
트레이드오프: 문서 유지 비용이 증가한다. 하지만 문서와 구현이 어긋날 때는 ADR 또는 해당 dossier를 먼저 갱신하여 설계 drift를 관리한다.
ADR-014: Documentation Index and Implementation Readiness Gate
결정: docs/README.md를 프로젝트 문서 index와 문서 우선순위의 entry point로 둔다. Phase 1 implementation plan을 작성하기 전 docs/README.md의 Implementation Readiness Checklist 미결 항목을 명시한다.
이유: FESA는 수치 규약, Abaqus subset, MITC4 formulation, HDF5 schema, reference verification이 강하게 결합되어 있다. 구현 전에 어떤 문서가 어느 결정을 소유하는지 분명히 하지 않으면 작은 구현 선택이 전체 solver convention을 흔들 수 있다.
트레이드오프: 계획 단계에서 문서 확인 비용이 늘어난다. 대신 이후 Codex 세션과 multi-agent 작업이 같은 규칙을 공유하고, 미결 결정을 숨기지 않는다.
ADR-015: Reference-Artifact-Only Validation Baseline
결정: Phase 1 검증은 저장된 references/ artifact와 비교한다. Abaqus 실행은 로컬 개발, CI, 기본 validation의 요구사항으로 두지 않는다.
이유: 사용자는 Abaqus input과 해석 결과를 references/ 폴더로 제공하며, 현재 개발 환경에서 Abaqus 실행은 사용할 수 없다. 저장 artifact 기반 검증이 재현성과 자동화에 더 적합하다.
트레이드오프: reference artifact 생성과 갱신은 수동 절차에 의존한다. 따라서 reference manifest, Abaqus version, unit note, tolerance, 비교 대상 output path를 명확히 기록해야 한다.
ADR-016: References Folder and CSV Displacement Artifact Contract
결정: 저장 reference의 공식 루트는 references/이다. 초기 자동 변위 검증은 Abaqus 해석 입력 *.inp와 Abaqus에서 export한 *_displacements.csv 파일 쌍을 사용한다. CSV column은 Node Label, U-U1, U-U2, U-U3, UR-UR1, UR-UR2, UR-UR3를 기본 형식으로 한다.
이유: 사용자가 첫 reference case로 references/quad_01.inp와 references/quad_01_displacements.csv를 제공했다. CSV는 사람이 검토하기 쉽고, 초기 parser/solver 검증 harness에서 HDF5 writer가 완성되기 전에도 U field 비교를 자동화하기 좋다.
트레이드오프: CSV는 HDF5보다 metadata 표현력이 약하다. 따라서 Abaqus version, unit note, unsupported keyword note, tolerance는 references/README.md, case manifest, 또는 추후 metadata 파일에 보강해야 한다. quad_01.inp처럼 S4R, Part/Assembly/Instance, NLGEOM=YES를 포함하는 reference input은 저장 reference로 보존하되 Phase 1 parser 지원 범위를 자동으로 확장하지 않는다.