baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revert

Browse Source
This commit is contained in:
김경종
2026-06-10 10:03:11 +09:00
parent 87529c811a
commit 0912ee6f3b
174 changed files with 414 additions and 8544 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ADR.md
+19 -91
View File
@@ -1,106 +1,34 @@
# Architecture Decision Records
## ADR-001: Solver Development Workflow Is Stage-Gated
**Decision**: FESA solver features must follow this workflow: requirements, research, formulation, I/O contract, TDD reference models, implementation, reference comparison, tolerance decision, release.
## 철학
Harness는 현재 프로젝트의 실제 기술 스택을 반영해야 한다. C++/MSVC 프로젝트에서 npm, Next.js, TypeScript test naming을 기본값으로 두면 agent prompt와 hook policy가 잘못된 구현을 유도한다.
**Reason**: Structural solver correctness depends on more than code execution. Requirements, mathematical formulation, input/output contracts, reference artifacts, numerical comparison, and release evidence must be traceable.
---
**Tradeoff**: Initial feature delivery is slower. The benefit is that implementation agents do not invent formulation, tolerance, or reference assumptions during coding.
### ADR-001: C++ 전용 Harness
**결정**: Harness scaffold는 C++/MSVC 전용으로 운영한다. JavaScript/TypeScript fallback은 유지하지 않는다.
## ADR-002: C++17/MSVC/CMake/CTest Remain The Baseline
**Decision**: The project targets C++17 or newer, MSVC on Windows, CMake, and CTest. Default validation uses Visual Studio 17 2022, x64, Debug.
**이유**: FESA 개발 환경은 MSVC 기반 C++이다. 언어별 fallback을 남기면 validation, TDD guard, acceptance criteria가 흐려진다.
**Reason**: The project is a Windows/MSVC structural solver. CMake/CTest gives a consistent build and test entry point for both harness validation and feature development.
**트레이드오프**: 같은 Harness scaffold를 JS/TS 프로젝트에 재사용할 수 없다. 필요하면 별도 template이나 language registry를 새 ADR로 설계한다.
**Tradeoff**: Visual Studio solution-only workflows and non-MSVC toolchains are not the primary path. They can be introduced by explicit ADR when needed.
### ADR-002: CMake/MSVC/x64/Debug 기본 검증
**결정**: 기본 workspace validation은 CMake, Visual Studio 17 2022 generator, x64 platform, Debug config, CTest로 수행한다.
## ADR-003: MITC4 Linear Static Shell Is The Initial Solver Feature
**Decision**: The first solver implementation target is `mitc4-linear-static-shell`: a 4-node MITC4 shell element for linear static structural analysis.
**이유**: MSVC 환경에서 CMake/CTest는 source tree가 복원되거나 새 C++ project가 추가될 때 가장 일관된 build/test entry point다.
**Reason**: MITC4 is a meaningful shell element target with strong research and OpenSees reference structure. It exercises element formulation, assembly, solver, I/O, and reference verification without immediately requiring nonlinear or dynamic analysis.
**트레이드오프**: Visual Studio solution-only project는 기본 지원하지 않는다. 명시적으로 필요하면 `HARNESS_VALIDATION_COMMANDS`로 override한다.
**Tradeoff**: This is more complex than a truss/bar bootstrap. The project accepts the complexity because MITC4 is the requested initial element.
### ADR-003: 엄격한 C++ TDD Guard
**결정**: C++ production file 변경은 관련 C++ test file이 없으면 차단한다.
## ADR-004: OpenSees-Inspired Architecture, Modern C++ Ownership
**Decision**: FESA follows OpenSees-like conceptual boundaries: `Domain`, `Node`, `Element`, `Material/Section`, `Analysis`, `SystemOfEqn`, and `Recorder/ResultWriter`. It does not clone OpenSees raw ownership style.
**이유**: Harness의 핵심 목적은 agent가 검증 없는 C++ 변경을 만들지 않도록 하는 것이다. Header 중심 C++ 구조에서도 module 또는 basename 기반 테스트 존재를 확인한다.
**Reason**: OpenSees provides a useful solver architecture vocabulary, while modern C++17 RAII gives safer ownership and testable module boundaries.
**트레이드오프**: 초기 scaffolding 작업에서 guard가 엄격하게 느껴질 수 있다. 문서, CMake 설정, Harness metadata는 guard 대상에서 제외한다.
**Tradeoff**: FESA classes will not be drop-in compatible with OpenSees. Similarity is architectural, not API compatibility.
### ADR-004: Harness 자체 테스트 우선
**결정**: commit hook은 먼저 Python Harness self-test를 실행한 뒤 workspace validation을 실행한다.
## ADR-005: MKL PARDISO For Global Linear Solves
**Decision**: FESA uses Intel oneAPI MKL CSR matrices and PARDISO for the initial global linear static solve.
**이유**: 현재 저장소에는 C++ source tree가 없을 수 있다. Harness가 스스로 검증 가능해야 이후 phase generation과 source restoration을 안전하게 진행할 수 있다.
**Reason**: Shell models need sparse linear algebra beyond toy dense solvers. MKL is already aligned with the Windows/MSVC toolchain and provides production-grade direct sparse solving.
**Tradeoff**: oneAPI MKL becomes a required dependency for real solver builds. The CMake configuration must detect `MKLROOT` or a known oneAPI installation path.
## ADR-006: TBB For Parallel Element Work
**Decision**: FESA uses Intel oneAPI TBB for parallel element stiffness, residual/result recovery, and other embarrassingly parallel solver phases.
**Reason**: Element-level computation is a natural parallelism boundary. TBB integrates with oneAPI and avoids designing a custom thread pool.
**Tradeoff**: Global assembly must be deterministic. FESA will use thread-local contribution buffers and deterministic merge rather than concurrent writes into global CSR arrays.
## ADR-007: HDF5 For Solver And Reference Results
**Decision**: FESA writes solver results to HDF5 and compares against stored HDF5 reference artifacts.
**Reason**: Shell results contain structured mesh, step/frame, nodal, element, Gauss point, resultant, stress, metadata, and tolerance data. HDF5 is better suited than flat CSV for this result hierarchy.
**Tradeoff**: HDF5 becomes a required dependency. FESA will provide an internal RAII wrapper over the HDF5 C API, but the actual HDF5 C library must be supplied by `HDF5_ROOT` or `HDF5_DIR`. The current local Windows install is `C:\Program Files\HDF_Group\HDF5\2.1.1`; use `HDF5_ROOT` for that root or `HDF5_DIR` for `C:\Program Files\HDF_Group\HDF5\2.1.1\cmake`.
## ADR-008: Single Tolerance Policy
**Decision**: Reference comparison uses a single tolerance value `1e-5`. A compared scalar passes when absolute error or relative error is within `1e-5`.
**Reason**: A single tolerance policy is simple, explicit, and matches the current project decision.
**Tradeoff**: Quantity-specific scaling is deferred. If future models show that one global tolerance is too strict or too loose for some quantities, a new ADR must revise this policy.
## ADR-009: Agents Do Not Run Reference Solvers
**Decision**: Abaqus, Nastran, and other reference solvers are not run by agents. Agents only consume stored reference artifacts.
**Reason**: Reference solver execution requires licensing, environment control, provenance, and human approval. Stored artifacts make validation reproducible inside the harness.
**Tradeoff**: Implementation can be blocked until required reference artifacts are supplied.
## ADR-010: Domain, AnalysisModel, And AnalysisState Are Separate
**Decision**: `Domain` owns the validated runtime model object graph created from parsed input, `AnalysisModel` owns the active step execution view, and `AnalysisState` owns mutable solution and iteration state.
**Reason**: This prevents parser DTOs, equation ids, displacement vectors, residuals, and future nonlinear/time states from leaking into the persistent domain model. It also keeps the static solver compatible with future nonlinear, dynamic, and thermal workflows.
**Tradeoff**: The initial implementation has more object boundaries than a single monolithic model container.
## ADR-011: Factory/Registry Handles Input Object Creation
**Decision**: Abaqus keyword parsing and internal object creation are separated through factory/registry mechanisms.
**Reason**: Adding elements, materials, loads, boundary conditions, sets, or properties should not require rewriting parser control flow.
**Tradeoff**: The first parser implementation needs a small registry layer before many object types exist.
## ADR-012: Boundary Conditions Use DOF Elimination
**Decision**: Essential boundary conditions are applied by constrained DOF elimination. Reactions are recovered from the full system as `K_full * U_full - F_full`.
**Reason**: This gives a clear reduced solve while preserving physically meaningful reaction recovery for reference comparison.
**Tradeoff**: The implementation must preserve enough full-system information for reaction recovery instead of only storing the reduced matrix.
## ADR-013: Results Use Step/Frame/Field/History Model
**Decision**: HDF5 results are organized by step, frame, field output, and history output.
**Reason**: The same result model can support static, nonlinear, dynamic, heat-transfer, and thermal-stress analyses.
**Tradeoff**: The v0 linear static output is more structured than a flat single-step result file.
## ADR-014: Double Precision And 64-Bit Numbering
**Decision**: Solver scalar calculations use `double`; ids, sparse indices, and equation numbering are designed around int64 boundaries.
**Reason**: Structural solver verification needs double precision, and large sparse systems should not be blocked by 32-bit numbering assumptions.
**Tradeoff**: Memory use may be higher than a 32-bit-only implementation.
## ADR-015: Units Are User-Consistent, Not Enforced
**Decision**: FESA does not enforce a unit system. Inputs and reference artifacts must be unit-consistent and record units in metadata.
**Reason**: Abaqus-style workflows commonly rely on user-consistent units.
**Tradeoff**: The solver cannot automatically detect every unit mismatch. Reference metadata and validation reports must make unit assumptions visible.
**트레이드오프**: commit 시간이 조금 늘어난다. 대신 hook/validation regressions를 빠르게 잡는다.