docs: add linear static beam harness phase
This commit is contained in:
KOKO\Mimi
+142
-27
@@ -11,6 +11,12 @@ FESA의 아키텍처 목표는 Abaqus `.inp` subset을 내부 semantic model로
|
||||
- incremental feature addition
|
||||
- Harness 기반 TDD
|
||||
|
||||
현재 승인된 V0 end-to-end 기능은 `linear-static-3d-euler-beam`이다. 상세 계약의
|
||||
source of truth는
|
||||
`docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md`이며, 이 문서는
|
||||
그 계약을 전체 solver architecture의 모듈과 데이터 흐름에 배치한다. 아래에 나타난
|
||||
비선형, 동적, thermal 및 다른 element 계층은 장기 확장 경계이며 V0 지원 범위가 아니다.
|
||||
|
||||
## 디렉토리 구조
|
||||
```text
|
||||
src/
|
||||
@@ -31,9 +37,7 @@ src/
|
||||
analysis/ # static, modal, dynamic, nonlinear procedure drivers
|
||||
results/ # recovery, field/history output, diagnostics
|
||||
validation/ # comparison metrics and tolerance helpers
|
||||
math/
|
||||
Vector/ # managing double array including vector operation, vector operation must use BLAS from MKL
|
||||
Matrix/ # managing double array including matrix operation, matrix operation must use BLAS from MKL
|
||||
math/ # owning Vector, row-major Matrix, CSR SparseMatrix adapters
|
||||
tests/
|
||||
unit/
|
||||
integration/
|
||||
@@ -83,6 +87,57 @@ Runner는 `git add -A`를 사용하므로 clean worktree 또는 별도 Git workt
|
||||
- `results`는 HDF5 schema를 통해 nodal, element, integration-point, diagnostic output을 분리한다.
|
||||
- test helper는 production parser/solver 내부 상태를 우회하지 않는다.
|
||||
|
||||
## V0 입력 경계
|
||||
|
||||
V0 parser는 keyword와 parameter를 case-insensitive하게 해석하되 source label의 원문을
|
||||
보존한다. 지원하는 model/procedure keyword는 다음과 같다.
|
||||
|
||||
- `*HEADING`
|
||||
- `*PART`, `*END PART`
|
||||
- `*NODE`
|
||||
- `*ELEMENT, TYPE=B33`
|
||||
- `*NSET`, `*ELSET`, including `GENERATE`
|
||||
- `*MATERIAL`, `*ELASTIC`
|
||||
- `*BEAM GENERAL SECTION, SECTION=GENERAL`
|
||||
- `*SECTION POINTS`
|
||||
- `*ASSEMBLY`, `*END ASSEMBLY`
|
||||
- `*INSTANCE`, `*END INSTANCE`
|
||||
- `*BOUNDARY`, `*CLOAD`
|
||||
- `*STEP`, `*STATIC`, `*END STEP`
|
||||
|
||||
Part 내부 label은 `SourceEntityId { instance_name, source_label }`로 보존하고 Domain은
|
||||
별도 stable internal index를 부여한다. 같은 part의 여러 identity instance는 허용하지만
|
||||
translation/rotation data와 nested assembly는 구조화된 unsupported diagnostic으로
|
||||
거부한다. 입력 파일당 하나의 static step만 허용하고 두 번째 step은 오류다.
|
||||
|
||||
`*PREPRINT`, `*RESTART`, `*TRANSVERSE SHEAR STIFFNESS`, `*OUTPUT, FIELD`,
|
||||
`*OUTPUT, HISTORY`, `*NODE OUTPUT`, `*ELEMENT OUTPUT`, `*CONTACT OUTPUT` 및 그에 속한
|
||||
미지원 output variable data는 warning 후 no-op 처리한다. 이 allowlist 밖의 미지원
|
||||
model-affecting keyword는 오류다. FESA output은 Abaqus output request에 좌우되지 않는다.
|
||||
|
||||
## V0 beam과 section 계약
|
||||
|
||||
`EulerBeam3D`는 2절점과 절점당 `[UX, UY, UZ, URX, URY, URZ]` 6 DOF를 사용하며 축,
|
||||
두 방향 Euler–Bernoulli 굽힘과 Saint-Venant 비틀림을 제공한다. Beam tangent를 local
|
||||
`x`, Abaqus first section axis `n1`을 local `y`, `t x n1`을 local `z`로 둔다.
|
||||
`*BEAM GENERAL SECTION`의 `A, I11, I12, I22, J`는 `Iy=I11`, `Iz=I22`로 매핑하고
|
||||
V0는 `I12=0`만 허용한다. `E`, `G`, `A`, `Iy`, `Iz`, `J`는 양수여야 하며 zero-length
|
||||
element와 tangent에 평행한 guide vector를 scale-aware tolerance로 거부한다.
|
||||
|
||||
요소 API는 stiffness, transformation, load와 recovery 책임을 분리한다.
|
||||
|
||||
```cpp
|
||||
Matrix localStiffness() const;
|
||||
Matrix globalStiffness() const;
|
||||
Vector localEquivalentLoad(const ConstantLocalLineLoad& load) const;
|
||||
BeamRecovery recover(const Vector& globalElementDisplacement) const;
|
||||
```
|
||||
|
||||
`localEquivalentLoad`는 formulation의 constant local line-load kernel을 unit test하기
|
||||
위한 계약이다. V0 parser는 `*DLOAD`나 distributed-load Domain object를 생성하지 않으므로
|
||||
CLI pipeline에서는 이 kernel을 호출하지 않는다. Stiffness와 recovery는 formulation의
|
||||
2점 Gauss rule과 부호 규약을 따른다.
|
||||
|
||||
## 핵심 객체 모델
|
||||
```text
|
||||
Domain
|
||||
@@ -159,8 +214,14 @@ Results
|
||||
|
||||
Vector
|
||||
Matrix
|
||||
SparseMatrix
|
||||
```
|
||||
|
||||
이 객체 모델 중 V0 `Analysis` 구현은 `LinearStaticAnalysis` 하나이며 `AnalysisState`는
|
||||
full displacement, external/internal force, residual, constrained reaction, step/frame
|
||||
identity와 element recovery rows만 할당한다. Velocity, acceleration, temperature,
|
||||
iteration history와 nonlinear element state는 V0에서 할당하지 않는다.
|
||||
|
||||
## 상태 관리
|
||||
- `Domain`은 입력 파일에서 만들어진 전체 모델 정의를 소유한다. 파싱 이후에는 가능한 한 불변으로 취급한다.
|
||||
- `AnalysisModel`은 현재 step에서 활성화되는 해석 객체들의 실행 view이다. `Domain`을 복사하지 않고 참조 또는 id 기반 view로 구성한다.
|
||||
@@ -171,37 +232,46 @@ Matrix
|
||||
## 데이터 흐름
|
||||
```text
|
||||
Abaqus input file
|
||||
-> InputParser
|
||||
-> Domain 생성
|
||||
-> StepDefinition 루프
|
||||
-> AnalysisModel 생성
|
||||
-> DofManager로 자유도/방정식 번호 생성
|
||||
-> sparse pattern 생성
|
||||
-> Analysis 실행
|
||||
-> Assembler로 전역 행렬/벡터 조립
|
||||
-> BoundaryCondition 적용
|
||||
-> LinearSolver 또는 nonlinear/time integration loop
|
||||
-> AnalysisState 갱신
|
||||
-> ResultsWriter로 step/frame/history 저장
|
||||
-> 다음 step 진행
|
||||
-> syntax parse and semantic mapping
|
||||
-> immutable Domain 생성
|
||||
-> 단일 step AnalysisModel view 생성
|
||||
-> DofManager DOF/scatter map/sparse pattern 생성
|
||||
-> element stiffness 계산과 deterministic COO-to-CSR 조립
|
||||
-> free/constrained partition 생성
|
||||
-> LinearSolver::factorize(Kff)
|
||||
-> full nodal load vector 조립
|
||||
-> effective RHS = Ff - Kfc * dc
|
||||
-> LinearSolver::solve(rhs, df) substitution
|
||||
-> full displacement 복구
|
||||
-> reaction = K*d - F 및 element result 복구
|
||||
-> ResultsWriter로 results.h5 atomic finalization
|
||||
```
|
||||
|
||||
강성행렬 factorization은 하중벡터 조립보다 먼저 수행한다. 반력은 element end action의
|
||||
별도 합이 아니라 조립된 전체 residual에서 구한다.
|
||||
|
||||
## 해석 실행 흐름
|
||||
`Analysis::run()`은 Template Method로 다음 큰 흐름을 고정한다. 해석 종류별 class는 필요한 단계만 재정의한다.
|
||||
`Analysis::run()`은 Template Method로 다음 V0 흐름을 고정한다. 해석 종류별 class는
|
||||
승인된 procedure contract 안에서 필요한 단계만 재정의한다.
|
||||
|
||||
```text
|
||||
initialize
|
||||
buildAnalysisModel
|
||||
buildDofMap
|
||||
buildSparsePattern
|
||||
assemble
|
||||
applyBoundaryConditions
|
||||
solve
|
||||
updateState
|
||||
assembleStiffness
|
||||
partitionConstraints
|
||||
factorize
|
||||
assembleLoads
|
||||
formEffectiveRhs
|
||||
substitute
|
||||
reconstructDisplacement
|
||||
recoverResults
|
||||
writeResults
|
||||
```
|
||||
|
||||
비선형 정적해석은 이 흐름을 Newton-Raphson 반복 루프 안에서 사용하고, 동적해석은 time step/frame 루프 안에서 사용한다.
|
||||
비선형 정적 및 동적 해석은 V0 범위가 아니며 별도 ADR과 formulation을 승인한 뒤 이
|
||||
lifecycle의 확장 지점을 사용한다.
|
||||
|
||||
## 설계 패턴
|
||||
- Strategy Pattern: `Analysis`, `LinearSolver`, `TimeIntegrator`, `ConvergenceCriteria`를 교체 가능한 전략으로 둔다.
|
||||
@@ -213,10 +283,21 @@ writeResults
|
||||
|
||||
## Sparse Matrix Policy
|
||||
- assembly는 초기에는 COO triplet 수집 후 CSR finalize를 기준으로 한다.
|
||||
- `SparseMatrix`는 solver core가 사용하는 추상 contract이고 MKL PARDISO backend는 CSR input contract만 받는다.
|
||||
- `SparseMatrix`는 0-based CSR 데이터를 소유하는 별도 타입이며 dense `Matrix`를
|
||||
상속하지 않는다. MKL PARDISO backend는 adapter 경계에서 필요한 descriptor와 indexing을
|
||||
변환한다.
|
||||
- matrix symmetry, definiteness, singularity diagnostic을 구조화된 diagnostic으로 남긴다.
|
||||
- deterministic assembly를 위해 TBB element loop는 thread-local contribution buffer 또는 two-pass sparse assembly를 사용한다.
|
||||
|
||||
## Dense Math Policy
|
||||
|
||||
- `Vector`는 contiguous `double` 데이터와 크기를 소유하고 copy, dot, Euclidean norm,
|
||||
scale, axpy를 MKL CBLAS adapter로 수행한다.
|
||||
- `Matrix`는 row-major contiguous `double` 데이터와 dimensions를 소유하고
|
||||
matrix-vector 및 matrix-matrix 연산에 `CBLAS_ROW_MAJOR`를 사용한다.
|
||||
- 두 타입은 copy/move semantics와 bounds-checked access를 제공한다.
|
||||
- MKL header와 MKL-specific type은 adapter implementation 밖으로 노출하지 않는다.
|
||||
|
||||
## Parallel Policy
|
||||
- 첫 번째 oneTBB 적용 지점은 element-local matrix/residual 계산이다.
|
||||
- 전역 sparse write는 thread-local buffer 또는 deterministic reduction으로 제한한다.
|
||||
@@ -227,10 +308,12 @@ writeResults
|
||||
/metadata
|
||||
/model/nodes
|
||||
/model/elements
|
||||
/steps/<step-name>/frames/<frame-id>/nodal/displacement
|
||||
/steps/<step-name>/frames/<frame-id>/nodal/reaction
|
||||
/steps/<step-name>/frames/<frame-id>/element/stress
|
||||
/steps/<step-name>/frames/<frame-id>/element/strain
|
||||
/steps/<step-name>/frames/0/nodal/displacement
|
||||
/steps/<step-name>/frames/0/nodal/reaction
|
||||
/steps/<step-name>/frames/0/element/end_force_local
|
||||
/steps/<step-name>/frames/0/element/section_resultant
|
||||
/steps/<step-name>/frames/0/element/generalized_strain
|
||||
/steps/<step-name>/frames/0/element/stress_s11
|
||||
/diagnostics
|
||||
```
|
||||
|
||||
@@ -242,3 +325,35 @@ Schema requirements:
|
||||
- Abaqus reference results는 `reference/<model-id>/` 아래 CSV 파일이다.
|
||||
- Verification은 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준으로 FESA HDF5 rows와 Abaqus reference CSV rows를 비교한다.
|
||||
- FESA HDF5에서 추출한 deterministic CSV view는 optional debugging/review artifact이며 공식 solver output 또는 reference artifact가 아니다.
|
||||
- Writer는 임시 HDF5 파일을 완성한 뒤 최종 경로로 교체하며 실패 시 불완전한
|
||||
`results.h5`를 남기지 않는다.
|
||||
|
||||
## V0 결과 복구와 reference normalization
|
||||
|
||||
- Nodal displacement와 reaction은 global `[UX, UY, UZ, URX, URY, URZ]` 순서다.
|
||||
- Equilibrium end action은 local `[FX,FY,FZ,MX,MY,MZ]`, endpoint section resultant는
|
||||
`[N,T,My,Mz]`, generalized strain/resultant는 두 Gauss point에 기록한다.
|
||||
- General beam section stress는 section point의 axial `S11`만 복구한다. Section point가
|
||||
없으면 centroid `(0,0)`을 `source=fesa-default`로 기록한다.
|
||||
- 승인된 `reference/cantilever beam/cantilever beam elemental forces.csv`는 node station
|
||||
기준 `SF1/SM1/SM2/SM3`을 제공한다. FESA endpoint를 동일한 section-cut 부호로
|
||||
정규화하고 interior node의 두 endpoint가 tolerance 안에서 일치하는지 먼저 확인한 뒤
|
||||
`SF1 -> N`, `SM1 -> My`, `SM2 -> Mz`, `SM3 -> T`로 비교한다.
|
||||
- Reference tolerance는 같은 model, step/frame, quantity, component의 Abaqus rows에서
|
||||
`reference_scale = max(abs(reference_value))`를 구하고 각 row에
|
||||
`absolute_floor + 1e-6 * reference_scale`을 적용한다. SI displacement/rotation floor는
|
||||
`1e-9`, force/moment floor는 `1e-3`이다.
|
||||
- Beam stress는 HDF5 schema와 unit/analytical test로 검증하지만 Abaqus reference
|
||||
comparison은 N/A다.
|
||||
|
||||
## CLI와 diagnostics
|
||||
|
||||
```powershell
|
||||
fesa.exe <model.inp> --output <results.h5>
|
||||
```
|
||||
|
||||
`--output`을 생략하면 현재 작업 디렉터리의 `results.h5`를 사용한다. Exit code는
|
||||
`0=success`, `2=usage`, `3=input syntax/semantic mapping`, `4=model validation`,
|
||||
`5=factorization/substitution`, `6=HDF5 output`으로 고정한다. Diagnostic은 `severity`,
|
||||
`code`, `file`, `line`, `keyword`, `entity_identity`, `message`를 가지며 stderr에
|
||||
deterministic한 순서로 출력한다.
|
||||
|
||||
Reference in New Issue
Block a user