FESADev/docs2/ARCHITECTURE.md

# Structural FEM Solver Architecture

## 1. 범위와 현재 상태

이 문서는 범용 구조해석 FEM solver의 목표 C++ 아키텍처와 이를 개발하는 control plane을
정의한다. 현재 repository에는 agent/skill, 문서와 Harness가 있으며 solver source와 build
metadata는 아직 없다. 아래 `include/`와 `src/` 구조는 feature 구현 시 지켜야 할 목표
경계이지 현재 구현 완료 목록이 아니다.

## 2. 아키텍처 원칙

- Physics와 numerical meaning을 file format 및 vendor backend보다 안쪽에 둔다.
- Model definition, mutable analysis state와 recovered result를 별도 lifetime으로 관리한다.
- Local element 계산과 global topology/assembly/solve 책임을 분리한다.
- 모든 경계에서 identity, units, coordinates, ordering과 failure를 명시한다.
- Candidate를 완전히 검증한 뒤 authoritative state로 commit한다.
- 지원하지 않는 semantic input은 fail closed 처리한다.
- 재현 가능한 ordering과 reduction을 correctness contract로 취급한다.
- 확장점은 실제 두 번째 구현이 필요할 때 최소 interface로 도입한다.

## 3. Context 구조

```text
                         Development control plane
  user -> Coordinator -> specialist agents -> evidence -> Harness/tests
                              |
                              v
                         repository changes

                           Solver data plane
  input adapter -> semantic model -> analysis procedure -> results model
                         |              |
                         v              v
                  element/material   assembly/constraints
                         \              /
                          numerical backend
                                |
                         output adapters
```

Control plane은 source와 evidence를 만들고 검증하지만 solver runtime API의 일부가 아니다.
Solver data plane은 agent, prompt, phase 파일 또는 Harness에 의존하지 않는다.

## 4. 목표 디렉터리

```text
include/fem/
  core/          public identity, units, diagnostics와 value types
  model/         immutable semantic model API
  element/       element formulation contracts
  material/      constitutive contracts
  analysis/      analysis procedure contracts
  results/       backend-neutral result identity와 query API

src/
  core/
  model/
  element/
  material/
  dof/
  assembly/
  constraints/
  analysis/
  numerics/
  results/
  io/
    abaqus/      선택적으로 지원하는 Abaqus interchange subset adapter
  storage/       선택된 result serialization adapter

tests/
  unit/
  integration/
  verification/
  harness/

reference/       승인된 read-only model 및 expected-result artifact
docs/features/   feature별 requirement부터 release까지의 evidence
```

첫 feature는 필요한 경로만 추가한다. 빈 framework class나 미래용 계층을 미리 만들지 않는다.

## 5. 모듈 책임

| 모듈 | 소유 책임 | 소유하지 않는 책임 |
| --- | --- | --- |
| `core` | typed identity, units/coordinate metadata, status/diagnostic | mesh, solver, file syntax |
| `model` | node/connectivity/set/load/constraint/step의 검증된 semantic definition | equation numbering, mutable state |
| `element` | kinematics, quadrature, local residual/tangent, recovery | global matrix와 source parsing |
| `material` | constitutive response, trial/commit/revert state | element interpolation과 analysis loop |
| `dof` | active DOF와 deterministic equation numbering | constraint enforcement와 solve |
| `assembly` | sparsity, scatter, stable local-to-global reduction | element physics와 linear solve |
| `constraints` | prescribed/MPC 등 feature가 지원하는 equation policy | parser syntax와 result storage |
| `analysis` | procedure lifecycle, iteration, convergence, state commit | concrete file adapter와 vendor API 노출 |
| `numerics` | vector/matrix abstraction과 private backend adapter | physical entity 및 source label 의미 |
| `results` | quantity/location/component/frame/provenance identity와 recovery records | storage file layout |
| `io` | external syntax와 semantic model 간 mapping | solver physics 변경 |
| `storage` | versioned serialization과 atomic publication | authoritative physical meaning 정의 |

## 6. 의존성 규칙

```text
io adapters ------> model/core <------ output/storage adapters
                         ^
                         |
element/material --> analysis <-- constraints/assembly
        |                 |
        +------------> numerics

public API -> core/model/element/material/analysis/results abstractions only
```

- Adapter가 core contract에 의존하며 core가 adapter에 의존하지 않는다.
- `element`와 `material`은 서로의 concrete type을 소유하지 않는다. 명시적 evaluation
  context/response contract로 통신한다.
- `analysis`는 backend-neutral numerical interface만 본다.
- Vendor header, handle과 exception은 `src/numerics` 또는 `src/storage` 내부에서 끝난다.
- `io`가 model object를 부분적으로 publish하지 않는다. Builder/candidate를 검증한 뒤
  immutable model을 생성한다.

CI에서는 public-header self-containment와 금지 dependency 검사를 추가할 수 있다. 그런
검사가 아직 없으면 architecture review가 동일 경계를 확인한다.

## 7. 핵심 데이터 계약

### 7.1 Identity

다음 identity는 교환할 수 없다.

- `SourceLabel`: input/output에서 사용자가 보는 label
- `EntityId`: 검증된 model 내부 identity
- `DofId`: physical component가 포함된 자유도 identity
- `EquationId`: 특정 analysis state의 active equation 번호
- `ResultKey`: entity, quantity, location, component, step/frame와 coordinate metadata 조합

Dense array index를 source label로 암묵적으로 사용하지 않는다. 외부 artifact 매칭은 row
순서가 아니라 명시적 identity를 사용한다.

### 7.2 Units와 coordinates

Solver는 입력 값의 일관 단위계를 임의로 추론하지 않는다. Feature contract가 필요한
dimension을 정의하고 adapter가 단위 metadata를 보존하거나 명시적으로 변환한다. Vector,
tensor, rotation과 result component는 local/global/material coordinate system과 ordering을
기록한다.

### 7.3 Model, state, results

- `Model`: analysis 동안 변하지 않는 topology와 semantic definition
- `AnalysisState`: DOF values, committed/trial material state, iteration/convergence metadata
- `Results`: 성공적으로 publish된 step/frame별 physical output

Trial update 실패 시 committed state를 보존한다. 실패 frame은 정상 frame과 같은
authoritative status로 노출하지 않는다.

## 8. 해석 생명주기

```text
PARSE/BUILD
  -> SEMANTIC VALIDATION
  -> MODEL FREEZE
  -> PROCEDURE INITIALIZATION
  -> DOF/CONSTRAINT SETUP
  -> SPARSITY SETUP
  -> {ASSEMBLE -> SOLVE -> UPDATE -> CONVERGENCE CHECK}*
  -> COMMIT
  -> RECOVER
  -> PUBLISH RESULTS
```

Linear procedure도 같은 owner 경계를 사용하며 반복 구간이 한 번일 수 있다. Nonlinear,
dynamic, eigen과 contact 기능은 이 lifecycle 위에 필요한 state와 gate를 추가하지만 다른
analysis family의 의미를 공통 API에 억지로 넣지 않는다.

Residual과 tangent의 부호, essential constraint 적용 시점, reaction recovery와 state
commit 시점은 formulation/analysis contract에 포함한다.

## 9. Element 및 material kernel

Element evaluation input은 최소한 geometry, DOF/state view, material evaluation capability,
step/iteration context와 requested outputs를 포함한다. Output은 local ordering이 명시된
residual/tangent 및 recovery data다.

Element kernel은 다음을 수행하지 않는다.

- global equation 번호 생성
- global sparse matrix에 직접 write
- source file lookup
- global convergence 판정
- result storage write

Material update는 trial response를 반환하고 analysis owner가 전체 increment 성공 후 commit을
요청한다. Numerical integration point와 state-variable ordering은 feature contract에
versioned되어야 한다.

## 10. Assembly, constraints와 numerics

- Sparsity는 validated connectivity와 DOF policy에서 deterministic하게 생성한다.
- Parallel worker는 소유가 정해진 buffer에만 기록하고 reduction 순서를 고정한다.
- Constraint 방식은 elimination, transformation, penalty 등 선택된 feature contract에
  명시한다. 서로 다른 방식의 reaction 의미를 동일하다고 가정하지 않는다.
- Numerical backend는 matrix/storage/solver capability를 제공하지만 physical model을 알지
  않는다.
- Backend status는 structured solver diagnostic으로 변환하며 exception이나 error code를
  public API로 그대로 흘리지 않는다.

## 11. I/O와 Abaqus reference convention

Abaqus input/output의 공개 정의는 호환 feature를 설계할 때 우선 reference로 사용한다.
Adapter는 지원 keyword/option, model data와 history data, default, set/instance scope,
orientation, step과 output 위치를 명시적으로 mapping한다.

다음 원칙을 지킨다.

- 선택된 subset만 지원한다고 선언한다.
- 결과에 영향을 줄 수 있는 unknown/unsupported semantic keyword는 오류다.
- 무시해도 semantic 차이가 없다고 계약된 formatting 또는 metadata만 warning이 될 수 있다.
- 공개 문서로 확인할 수 없는 내부 동작을 추측하지 않는다.
- Adapter의 interchange 호환성과 solver formulation 검증을 별개의 evidence로 관리한다.

다른 입력 형식도 동일한 semantic model builder를 사용한다.

기본 공개 reference set은 다음과 같다. Feature evidence에는 실제 사용한 product version과
세부 page를 고정해 기록한다.

- [Input file model/history organization](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEMODRefMap/simamod-c-ov.htm)
- [Element selection and formulation overview](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-c-analysistype.htm)
- [Nonlinear equation solution controls](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEANLRefMap/simaanl-c-nonlineareqns.htm)
- [Output concepts and identifiers](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEOUTRefMap/simaout-c-ov.htm)
- [Verification Guide](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEVERRefMap/simaver-c-ov.htm)

이 목록은 출발점이지 모든 feature의 충분한 근거가 아니다. Governing theory와 feature별
공식 문서를 함께 사용하고, 문서 version 간 차이는 contract에 명시한다.

## 12. 결과와 persistence

Results model은 저장 형식과 독립적이며 다음을 식별한다.

- analysis/step/frame와 success status
- entity와 source identity
- quantity, location, component와 coordinate system
- units/dimension와 precision
- formulation, mesh와 solver provenance

Storage adapter는 schema version을 기록하고 임시 candidate에 쓴 뒤 validation 성공 시
atomic publish한다. CSV, HDF5 또는 다른 형식은 선택된 project/feature contract이며 core
기본값이 아니다.

## 13. 오류 모델

오류는 적어도 다음 category를 구분한다.

`input`, `model`, `formulation`, `assembly`, `constraint`, `linear-solver`, `convergence`,
`recovery`, `storage`, `environment`, `internal`

Diagnostic에는 category, stable code, message, 관련 entity/source location과 원인 chain을
포함할 수 있다. 예상 가능한 사용자/model 오류는 process crash나 assertion으로 처리하지
않는다. Assertion은 내부 invariant 위반에 사용한다.

## 14. Determinism과 병렬성

- Entity와 equation ordering은 stable input identity와 명시적 policy에서 결정한다.
- Hash iteration order를 authoritative output order로 사용하지 않는다.
- Floating-point reduction tree를 고정하거나 비결정성 범위를 계약·검증한다.
- 병렬 최적화는 serial reference test와 동일한 identity 및 허용된 numerical envelope를
  만족해야 한다.
- Randomized test는 seed와 재현 정보를 기록한다.

## 15. 개발 control plane

Coordinator와 specialist agent는 `docs/SOLVER_AGENT_DESIGN.md`의 state machine을 따른다.
Skill은 역할별 절차를 제공하고 Harness는 계획된 repository-local 변경의 TDD와 build/test를
강제한다.

Control plane의 안전 경계는 다음과 같다.

- Agent 보고서와 runtime output을 product result로 취급하지 않는다.
- Hook은 방어 계층이지 완전한 sandbox가 아니다.
- Project config와 build preset은 실행 가능한 신뢰 경계다.
- Harness는 관련 없는 working-tree 변경을 stage/commit하지 않는다.
- External solver와 원격 repository 변경은 별도 권한이 필요하다.

## 16. Architecture 변경

Public dependency 방향, identity, state ownership, result schema 의미 또는 analysis lifecycle을
바꾸는 변경은 `docs/ADR.md`에 새 decision을 추가한다. 기존 ADR을 조용히 다시 쓰지 않고
superseding ADR로 이력을 남긴다.