FESADev/docs/ARCHITECTURE.md

FESA Solver Architecture

목표

FESA는 C++17/MSVC 기반 유한요소 구조해석 솔버다. 초기 구현은 MITC4 4절점 shell element의 선형정적 해석이며, 이후 비선형 정적해석, 비선형 동적해석, 열전달 및 thermal-stress coupling, 1D/3D 요소로 확장한다.

초기 구현은 정확도와 테스트 가능성을 우선한다. 단, 대규모 모델을 목표로 하므로 자유도 관리, 희소 행렬 조립, 선형 솔버, 병렬 실행 계층은 초기부터 성능 확장이 가능하도록 분리한다.

개발 프로세스 구조

Feature request
-> requirements
-> research evidence
-> FEM formulation
-> I/O contract
-> reference model and artifact contract
-> TDD implementation plan
-> C++ implementation
-> build/test validation
-> HDF5 reference comparison
-> physics/release review

설계 원칙

• Domain은 입력 모델의 의미를 보존하고 파싱 이후 가능한 한 불변에 가깝게 유지한다.
• 해석 중 변하는 물리량과 반복 상태는 AnalysisState에 명시적으로 분리한다.
• 현재 step에서 활성화되는 실행 view는 AnalysisModel이 담당하며, Domain을 복사하지 않는다.
• 요소, 재료, 하중, 경계조건, 해석 알고리즘은 런타임 다형성 기반으로 확장한다.
• 결과는 step/frame/field/history 개념으로 저장하여 정적, 비선형, 동적, 열전달 해석을 같은 결과 모델로 다룬다.
• 외부 라이브러리인 MKL, TBB, HDF5는 adapter 계층 뒤에 둔다.
• Abaqus input 호환성은 parser와 factory/registry 계층에서 관리한다.
• shell node는 6자유도이고, 결과 자유도 순서는 U1, U2, U3, UR1, UR2, UR3이다.
• 단위계는 강제하지 않는다. 입력과 reference artifact metadata에 기록된 일관 단위계를 그대로 사용한다.
• 결과 부호와 shell output component naming은 Abaqus 규약을 따른다.
• 경계조건은 constrained DOF 제거 방식으로 적용하고, reaction은 full vector 기준 K_full * U_full - F_full로 계산한다.
• 기본 실수 precision은 double이다.
• 대규모 모델을 위해 id, index, equation numbering은 int64 기반으로 설계한다.
• Mesh quality 진단은 1차 범위에서 제외한다. 대신 singular system 진단은 필수로 제공한다.

Directory Structure

include/fesa/
  analysis/        # Static, nonlinear static, dynamic, heat transfer analysis interfaces
  assembly/        # Global matrix/vector assembly and sparse pattern creation
  boundary/        # Fix, RBE2, RBE3 and future constraint objects
  core/            # Domain, AnalysisModel, AnalysisState, DofManager
  element/         # Node, Element, MITC4 and future elements
  io/              # Abaqus input parser and HDF5 result writer
  load/            # NodalLoad, PressureLoad, BodyForce
  math/            # Vector, Matrix, SparseMatrix, MKL adapter
  material/        # LinearElastic and future material models
  property/        # ShellProperty and 1D/2D/3D properties
  results/         # ResultStep, ResultFrame, FieldOutput, HistoryOutput
  util/            # Diagnostics, logging, validation helpers
  verification/    # HDF5 reference comparison utilities

src/
  analysis/
  assembly/
  boundary/
  core/
  element/
  io/
  load/
  math/
  material/
  property/
  results/
  util/
  verification/

tests/
  parser/
  element/
  assembly/
  solver/
  hdf5/
  reference/

The current repository may not yet contain all directories. They are intended ownership boundaries for implementation planning.

Core Runtime Objects

• Domain: owns model definitions from input: nodes, elements, materials, properties, sets, boundary conditions, loads, and step definitions.
• AnalysisModel: step-local execution view over active elements, loads, boundary conditions, properties, materials, and equation system view.
• AnalysisState: owns changing physical quantities and iteration/time state such as displacement, velocity, acceleration, temperature, forces, residual, current time, increment, and element/integration-point state.
• Node: stores node id, coordinates, and six DOF values in order U1, U2, U3, UR1, UR2, UR3.
• Element: computes local stiffness, internal force/resultants, stress recovery, and connectivity.
• ShellMITC4Element: 4 nodes, 24 DOF, 2x2 Gauss integration, MITC transverse shear interpolation.
• Material: base contract for material behavior.
• Property: element property and section data, including shell thickness.
• LinearElasticShellSection: isotropic elastic shell section with thickness and shear correction.
• DofManager: active DOF definitions, constrained/free DOF mapping, equation numbering, sparse pattern ownership, and full/reduced vector reconstruction.
• Assembler: gathers element contributions into deterministic global sparse data.
• SparseMatrix: internal sparse matrix abstraction backed by MKL-compatible CSR for v0.
• LinearSolver: solver interface implemented initially by MklPardisoSolver.
• Analysis: strategy interface for LinearStaticAnalysis and future nonlinear/dynamic/thermal analyses.
• Hdf5ResultWriter: writes mesh, metadata, nodal results, element resultants, stresses, field output, and history output.
• ReferenceComparator: compares FESA HDF5 output with stored reference HDF5 artifacts using tolerance 1e-5.

State Ownership

Domain

Domain represents parsed model definition and should not store equation ids, solver vectors, current displacement, or iteration state.

Included:

• nodes and elements
• materials and properties
• node sets and element sets
• loads and boundary conditions
• analysis step definitions

AnalysisModel

AnalysisModel is built per active step. It references Domain objects by id or stable reference and defines what participates in the current solve.

Included:

• active elements
• active loads
• active boundary conditions
• active property/material references
• current equation system view

DofManager

DofManager centralizes all equation numbering. Node or Element objects must not independently own equation ids.

Responsibilities:

• define active node DOFs
• map constrained and free DOFs
• assign equation numbers
• provide connectivity for sparse matrix pattern generation
• reconstruct full vectors from reduced solution vectors

AnalysisState

AnalysisState stores mutable quantities and future nonlinear/time history extension points.

Included:

• displacement, velocity, acceleration
• temperature
• external force, internal force, residual
• current time, increment, Newton iteration
• element state and integration point state

Phase 1 uses displacement-centered state only, but the structure must not block geometric nonlinear and thermal-stress extensions.

Results State

Results use:

• ResultStep: analysis step result group
• ResultFrame: static load increment or dynamic time frame
• FieldOutput: node/element field results
• HistoryOutput: selected node, element, set, reaction, or energy histories

Data Flow

Abaqus input file
-> InputParser
-> Factory/Registry object creation
-> Domain
-> StepDefinition loop
-> AnalysisModel
-> DofManager
-> sparse pattern creation
-> TBB parallel element stiffness computation
-> deterministic CSR assembly
-> constrained DOF elimination
-> MKL PARDISO solve
-> full displacement vector reconstruction
-> reaction recovery by K_full * U_full - F_full
-> TBB parallel element result recovery
-> HDF5 step/frame/field/history output
-> HDF5 reference comparison

Patterns

Strategy

Used for swappable analysis and numerical algorithms:

• Analysis: LinearStaticAnalysis, NonlinearStaticAnalysis, DynamicAnalysis, HeatTransferAnalysis
• LinearSolver: MklPardisoSolver, future iterative solver
• TimeIntegrator: future Newmark/HHT
• ConvergenceCriteria: future residual, displacement, and energy norms

Template Method

Analysis::run() owns the high-level execution order:

initialize
buildAnalysisModel
buildDofMap
buildSparsePattern
assemble
applyBoundaryConditions
solve
updateState
writeResults

Nonlinear static analysis will reuse this sequence inside Newton-Raphson loops. Dynamic analysis will reuse it inside time step/frame loops.

Factory + Registry

Abaqus input keywords map to internal object factories:

• *ELEMENT, TYPE=S4 -> MITC4ElementFactory
• *ELEMENT, TYPE=S4R -> MITC4ElementFactory
• *MATERIAL, *ELASTIC -> LinearElasticMaterialFactory
• *SHELL SECTION -> ShellPropertyFactory
• *BOUNDARY -> FixBoundaryFactory
• *CLOAD -> NodalLoadFactory
• *NSET, *ELSET -> set registry

Adding an element, material, load, or boundary condition should not require rewriting the parser core.

Adapter

MKL, TBB, and HDF5 APIs are not exposed directly to solver core objects.

Adapter targets:

• SparseMatrix, Vector, Matrix
• LinearSolver
• ParallelFor
• ResultsWriter

This allows test doubles and future dependency replacement without changing solver physics code.

HDF5 Dependency Discovery

The current local Windows/MSVC HDF5 installation is:

C:\Program Files\HDF_Group\HDF5\2.1.1

Implementation planning should use the HDF5 C API through the adapter layer, not the HDF5 C++ API. CMake discovery should prefer one of these explicit environment variables before falling back to default package search:

$env:HDF5_ROOT = "C:\Program Files\HDF_Group\HDF5\2.1.1"
$env:HDF5_DIR = "C:\Program Files\HDF_Group\HDF5\2.1.1\cmake"

The expected local artifacts are include\hdf5.h, lib\hdf5.lib, bin\hdf5.dll, and cmake\hdf5-config.cmake. h5dump.exe -V should report HDF5 2.1.1 on this machine.

Runtime Polymorphism

Elements, materials, loads, and boundary conditions are handled through base interfaces. Phase 1 prioritizes clarity and testability. If large-model performance requires it later, assembly internals may add type-specific batch kernels.

MITC4 Result Contract

Nodal displacement output:

node_id, U1, U2, U3, UR1, UR2, UR3

Nodal reaction output:

node_id, RF1, RF2, RF3, RM1, RM2, RM3

Element internal force/resultant output at Gauss points:

element_id, gauss_id, xi, eta, N11, N22, N12, M11, M22, M12, Q13, Q23

Stress output:

element_id, gauss_id, section_point, S11, S22, S12, S13, S23

HDF5 Layout

/metadata
  feature_id
  solver_version
  model_id
  hdf5_version
  schema_version
  units
  tolerance
  reference_solver

/mesh/nodes
/mesh/elements/mitc4/connectivity

/results/step_000/frame_000/nodal/displacement
/results/step_000/frame_000/nodal/reaction
/results/step_000/frame_000/element/forces
/results/step_000/frame_000/element/stress
/results/step_000/frame_000/history

Parallelism And Sparse Assembly

TBB parallelism is allowed for element-local computations, element force recovery, assembly precompute, and independent postprocessing.

Global assembly must remain deterministic:

parallel element loop
-> thread-local sparse contribution buffers
-> stable sort by (row, column)
-> deterministic sum
-> CSR arrays

The sparse matrix path must preserve 64-bit index boundaries so MKL pardiso_64 can be used for large models.

The solver must avoid uncontrolled MKL/TBB oversubscription. Thread-count decisions are part of analysis metadata and validation reports.

Validation Flow

python scripts/validate_workspace.py
-> CMake configure
-> MSVC Debug build
-> CTest
-> feature-specific reference comparison tests

When no CMake project exists yet, validation may report the harness no-op path. Once solver code is introduced, CMake/CTest validation is mandatory.

Reference Artifact Flow

Agents do not run Abaqus or Nastran.

Human-approved Abaqus run
-> stored HDF5 reference artifact under references/<feature>/<model-id>/
-> FESA solver HDF5 output
-> ReferenceComparator
-> pass/fail using abs-or-rel 1e-5

For mitc4-linear-static-shell, Abaqus S4R is primary and S4 is diagnostic.

Performance Extension Direction

• Sparse matrix storage is the default global system representation.
• MKL direct solver is the first supported solver, but LinearSolver must allow future iterative solvers.
• Element stiffness and result recovery should be designed for type-specific batch kernels later, but not optimized before correctness evidence exists.
• MITC4 formulation should remain clear and reviewable until patch and reference comparisons pass.