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

modify documents

Browse Source
This commit is contained in:
NINI
2026-04-23 00:03:55 +09:00
parent 61f5f2e333
commit 4b89f4aa96
16 changed files with 1245 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

220
docs/ABAQUS_INPUT_SUBSET.md Normal file
View File

@@ -0,0 +1,220 @@
# Abaqus Input Subset
## Purpose
This document defines the Abaqus `.inp` subset supported by FESA Phase 1.
FESA aims for strict, explicit compatibility with a small subset rather than partial silent interpretation of the full Abaqus language.
## Source Basis
- Abaqus input files use keyword lines, data lines, and comment lines; keyword and parameter names are case-insensitive, comma-separated, and may use continuation lines: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
- Abaqus sets are a central reference mechanism for nodes and elements: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
- Abaqus shell library documents S4 as a 4-node general-purpose shell and S4R as a reduced-integration shell with hourglass control: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-r-shellgeneral.htm
- Abaqus `*BOUNDARY` direct data lines use node or node set, first DOF, optional last DOF, and optional magnitude: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-boundary.htm
- Abaqus `*CLOAD` data lines use node or node set, DOF, and reference load magnitude: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-cload.htm
## Phase 1 Supported Keywords
| Keyword | Status | FESA Object | Notes |
|---|---|---|---|
| `*Node` | Supported | `Node` | 3D coordinates only |
| `*Element` | Supported | `Element` | `TYPE=S4` maps to `MITC4` |
| `*Nset` | Supported | `NodeSet` | Explicit list and `GENERATE` should be supported |
| `*Elset` | Supported | `ElementSet` | Explicit list and `GENERATE` should be supported |
| `*Material` | Supported | `Material` | `NAME` required |
| `*Elastic` | Supported | `LinearElasticMaterial` | Isotropic `E, nu` only |
| `*Shell Section` | Supported | `ShellProperty` | Homogeneous shell section only |
| `*Boundary` | Supported | `FixBoundaryCondition` | Direct zero-valued constraints |
| `*Cload` | Supported | `NodalLoad` | Concentrated forces/moments |
| `*Step` | Supported | `StepDefinition` | Static linear Phase 1 step |
| `*Static` | Accepted inside `*Step` | `LinearStaticAnalysis` | Optional for Phase 1 |
| `*End Step` | Supported | Step delimiter | Required for explicit step closure |
Unsupported keywords must produce a clear diagnostic unless explicitly listed as ignorable metadata.
## General Parser Rules
FESA parser rules:
- Keyword names and parameter names are case-insensitive.
- Keyword lines start with `*`.
- Comment lines start with `**` and are ignored.
- Data fields are comma-separated.
- Empty trailing fields may be ignored.
- Numeric data may use decimal or scientific notation.
- `D` exponents should be accepted and normalized as `E` exponents.
- Keyword continuation with a trailing comma should be supported for keyword lines.
- Data continuation should be supported only where this document explicitly allows it.
- Abbreviated Abaqus keywords are not supported in Phase 1. Require exact keyword names after case normalization.
- Include files through `INPUT=` are not supported in Phase 1.
- Part/Assembly/Instance syntax is not supported in Phase 1 unless added by ADR.
## Labels and Names
Rules:
- Set and material labels are stored case-insensitively by default.
- Preserve the original spelling for diagnostics and result metadata.
- Labels must start with a letter unless quoted.
- Quoted labels may be accepted, but Phase 1 should warn if quoting is required for disambiguation.
- Labels beginning and ending with double underscores are reserved and should be rejected.
## `*Node`
Supported form:
```text
*Node
node_id, x, y, z
```
Rules:
- `node_id` is signed 64-bit integer.
- Coordinates are `double`.
- 2D node definitions are not supported for MITC4.
- Duplicate node ids are an error.
- Node ids need not be contiguous.
## `*Element`
Supported form:
```text
*Element, type=S4, elset=EALL
element_id, n1, n2, n3, n4
```
Rules:
- `TYPE=S4` maps directly to FESA `MITC4`.
- `TYPE=S4R` is not supported in Phase 1. It is reserved for future support.
- Element and node ids are signed 64-bit integers.
- Four node connectivity entries are required.
- Duplicate element ids are an error.
- Missing nodes are an error.
- If `ELSET` is given, the element is added to that element set.
- Element node ordering follows Abaqus shell ordering and determines the positive normal by right-hand rule.
## `*Nset` and `*Elset`
Supported explicit form:
```text
*Nset, nset=FIXED
1, 2, 3, 4
```
Supported generated form:
```text
*Elset, elset=EALL, generate
1, 100, 1
```
Rules:
- Explicit lists may span repeated data lines.
- `GENERATE` means `start, end, increment`.
- The increment must be positive.
- Set references to other sets are not required in Phase 1.
- `UNSORTED` is not required in Phase 1.
- Duplicates should be deduplicated while preserving a deterministic order for diagnostics.
- Missing referenced ids should be reported when the set is consumed by a property, load, or boundary condition.
## `*Material` and `*Elastic`
Supported form:
```text
*Material, name=STEEL
*Elastic
E, nu
```
Rules:
- Only isotropic linear elasticity is supported in Phase 1.
- Temperature dependence, field-variable dependence, orthotropic elasticity, plasticity, density, and damping are unsupported.
- `E` must be positive.
- `nu` must be in a physically meaningful isotropic range. For Phase 1, reject `nu <= -1.0` or `nu >= 0.5`.
## `*Shell Section`
Supported form:
```text
*Shell Section, elset=EALL, material=STEEL
thickness
```
Rules:
- `ELSET` and `MATERIAL` are required.
- Homogeneous single-layer shell sections only.
- Thickness is `double` and must be positive.
- Offsets, composite layups, section integration controls, orientations, temperature-dependent sections, and transverse shear stiffness overrides are unsupported in Phase 1.
- Thermal-stress coupling is a future feature and must not be inferred from Phase 1 section data.
## `*Boundary`
Supported direct form:
```text
*Boundary
node_or_nset, first_dof, last_dof, magnitude
```
Rules:
- `node_or_nset` may be a node id or node set label.
- DOFs are `1..6`.
- If `last_dof` is omitted, constrain only `first_dof`.
- Phase 1 supports zero-valued constraints. Omitted magnitude means zero.
- Nonzero prescribed displacement/rotation is not a Phase 1 requirement.
- Type-format boundary labels such as `PINNED`, `XSYMM`, or `ENCASTRE` are not supported unless later documented.
- Constrained DOFs are eliminated by `DofManager`.
## `*Cload`
Supported form:
```text
*Cload
node_or_nset, dof, magnitude
```
Rules:
- `node_or_nset` may be a node id or node set label.
- DOFs are `1..6`.
- Translational DOFs define concentrated forces.
- Rotational DOFs define concentrated moments.
- `FOLLOWER`, `AMPLITUDE`, `OP=NEW`, file-based loads, buoyancy/drag/inertia loads, and cyclic symmetry loads are unsupported in Phase 1.
## `*Step`, `*Static`, and `*End Step`
Supported form:
```text
*Step, name=Step-1
*Static
*Cload
...
*Boundary
...
*End Step
```
Rules:
- Phase 1 supports linear static steps.
- `NLGEOM` is ignored only if explicitly false or absent. `NLGEOM=YES` must be rejected until nonlinear analysis is implemented.
- Multiple steps may be parsed into `Domain`, but Phase 1 execution may initially support one active static step if documented in implementation steps.
- Step activation should feed `AnalysisModel`.
## Diagnostics
Required parser diagnostics:
- Unknown keyword.
- Unsupported keyword parameter.
- Missing required parameter.
- Duplicate node, element, material, property, or set definition.
- Missing node in element connectivity.
- Missing set used by shell section, boundary, or load.
- Unsupported element type such as `S4R`.
- Unsupported material or shell section mode.
- Invalid DOF number.
- Invalid generated set range.
Diagnostic messages should include file path, line number, keyword, and offending token.
## Explicit Non-Goals
- Abaqus `Part`, `Assembly`, `Instance`, and instance-qualified labels.
- `*Include`.
- `S4R`, `S4R5`, `S8R`, triangular shells, solid elements, beam elements.
- Pressure loads.
- RBE2/RBE3.
- Nonzero prescribed displacements.
- Amplitudes.
- Local coordinate transforms.
- Composite shell sections.
- Thermal-stress input.
- Mesh quality diagnostics.

54
docs/ADR.md
View File

@@ -65,3 +65,57 @@
**이유**: 대규모 모델, 경계조건, 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를 관리한다.

31
docs/ARCHITECTURE.md
View File

@@ -13,6 +13,10 @@ FESA는 MITC4 Shell 요소 기반 구조해석에서 시작해 비선형 정적
- 결과는 step/frame/field/history 개념으로 저장하여 정적, 비선형, 동적, 열전달 해석을 같은 결과 모델로 다룬다.
- 외부 라이브러리(MKL, TBB, HDF5)는 adapter 계층 뒤에 둔다.
- Abaqus input 호환성은 파서와 factory/registry 계층에서 관리한다. Phase 1의 입력 범위에는 `*Node`, `*Element`, `*Nset`, `*Elset`, `*Material`, `*Elastic`, `*Shell Section`, `*Boundary`, `*Cload`, `*Step`을 포함한다.
- 수치 규약은 `docs/NUMERICAL_CONVENTIONS.md`를 따른다. Phase 1 shell node는 6자유도이고, 단위계는 강제하지 않으며, 결과 부호는 Abaqus 규약을 따른다.
- 경계조건은 constrained DOF 제거 방식으로 적용하고, reaction은 full vector 기준 `K_full * U_full - F_full`로 계산한다.
- 기본 실수 precision은 `double`이고, 대규모 모델을 위해 id/index/equation numbering은 int64 기반으로 설계한다.
- Mesh quality 진단은 Phase 1 범위에서 제외한다. 대신 singular system 진단은 필수로 제공한다.
## 디렉토리 구조
```
@@ -66,7 +70,8 @@ DofManager
├── node dof definitions
├── constrained/free dof mapping
├── equation numbering
└── sparse matrix pattern ownership
├── sparse matrix pattern ownership
└── full/reduced vector reconstruction
Analysis
├── LinearStaticAnalysis
@@ -238,9 +243,33 @@ Abaqus input file
-> 다음 step 진행
```
## Phase 1 구현 범위
- MITC4 Shell 요소
- 선형 탄성 재료
- 절점하중
- 고정 경계조건
- Abaqus input subset: `*Node`, `*Element`, `*Nset`, `*Elset`, `*Material`, `*Elastic`, `*Shell Section`, `*Boundary`, `*Cload`, `*Step`
- `S4`를 `MITC4`로 매핑하고 `S4R`은 추후 지원
- 6자유도 shell node와 drilling 자유도 인공 강성
- constrained DOF 제거 방식
- full vector 기반 reaction recovery
- 선형 정적 해석
- step/frame 기반 결과 저장의 최소 구조
- double precision과 int64 indexing
- singular system 진단
- reference 모델 결과 비교 테스트
## 성능 확장 방향
- 행렬 조립은 element 단위 병렬화를 고려해 설계한다.
- 전역 행렬은 대규모 모델을 위해 sparse matrix를 기본으로 한다.
- MKL 기반 direct solver를 우선 지원하되, solver interface는 iterative solver를 추가할 수 있게 둔다.
- 대규모 sparse solve를 위해 MKL `pardiso_64`를 사용할 수 있도록 64-bit sparse index 경계를 유지한다.
- TBB 병렬화는 요소 stiffness 계산, element force 계산, assembly precompute 등 독립 작업부터 적용한다.
- 정확도 검증이 끝나기 전에는 MITC4 element formulation을 과도하게 최적화하지 않는다.
## 상세 설계 문서
- `docs/NUMERICAL_CONVENTIONS.md`: DOF, 좌표계, 단위, 부호, precision, reaction recovery, singular diagnostics
- `docs/ABAQUS_INPUT_SUBSET.md`: Phase 1 Abaqus input keyword subset과 unsupported feature
- `docs/VERIFICATION_PLAN.md`: reference 폴더 구조, benchmark matrix, tolerance 정책
- `docs/RESULTS_SCHEMA.md`: HDF5 step/frame/field/history schema
- `docs/MITC4_FORMULATION.md`: MITC4 baseline formulation 계약과 open decisions

200
docs/MITC4_FORMULATION.md Normal file
View File

@@ -0,0 +1,200 @@
# MITC4 Formulation
## Purpose
This document defines the baseline MITC4 formulation target for FESA Phase 1.
It is intentionally a formulation contract, not implementation code. Exact formulas should be added and reviewed before coding the MITC4 element.
## Source Basis
- Dvorkin and Bathe's four-node shell element paper presents a continuum-mechanics-based, non-flat, general quadrilateral shell element for thin and thick shells and nonlinear analysis: https://web.mit.edu/kjb/www/Publications_Prior_to_1998/A_Continuum_Mechanics_Based_Four-Node_Shell_Element_for_General_Nonlinear_Analysis.pdf
- The paper identifies transverse shear locking as a key problem in simple 4-node shell interpolation and motivates modified transverse shear treatment: https://web.mit.edu/kjb/www/Publications_Prior_to_1998/A_Continuum_Mechanics_Based_Four-Node_Shell_Element_for_General_Nonlinear_Analysis.pdf
- OpenSees describes `ShellMITC4` as a bilinear isoparametric shell element with modified shear interpolation, four counter-clockwise nodes, and six DOFs per node: https://opensees.berkeley.edu/wiki/index.php/Shell_Element
- The MITC benchmark paper states that the MITC method is used to remedy shell locking and that the standard MITC4 employs MITC treatment for transverse shear strains; it also notes that Abaqus S4 uses Dvorkin-Bathe transverse shear interpolation: https://web.mit.edu/kjb/www/Principal_Publications/Performance_of_the_MITC3%2B_and_MITC4%2B_shell_elements_in_widely_used_benchmark_problems.pdf
- Abaqus finite-strain shell theory documentation provides useful comparison context for S4/S4R geometry, interpolation, orientation update, and transverse shear treatment, but FESA Phase 1 is linear static: https://abaqus-docs.mit.edu/2017/English/SIMACAETHERefMap/simathe-c-finitestrainshells.htm
## Phase 1 Target
Phase 1 implements a clear MITC4 baseline formulation and passes reference benchmarks before performance optimization.
Scope:
- 4-node quadrilateral shell.
- Linear static analysis.
- Linear isotropic elastic material.
- Homogeneous shell section.
- 6 DOFs per node.
- Small-strain formulation for Phase 1.
- Transverse shear interpolation based on MITC4 assumptions.
- Abaqus-compatible result signs.
Non-scope:
- S4R reduced-integration behavior.
- Hourglass control.
- Composite sections.
- Material nonlinearity.
- Geometric nonlinearity.
- Pressure loads.
- Thermal-stress coupling.
- Mesh quality diagnostics.
## Nodal DOFs
Each node has:
```text
UX, UY, UZ, RX, RY, RZ
```
Rules:
- Translational DOFs are global translations.
- Rotational DOFs are rotations about global or transformed axes following Abaqus component convention.
- `RZ` is retained as a drilling DOF.
- Drilling stiffness is artificial in Phase 1 and must be parameterized.
## Element Input Contract
`MITC4Element` requires:
- four node ids in Abaqus S4 order.
- four node coordinates.
- shell thickness.
- linear elastic material constants `E` and `nu`.
- drilling stiffness parameter.
- element id and property id for diagnostics and output.
Node ordering:
- Input node order follows Abaqus S4 convention.
- Positive normal follows the right-hand rule around the nodes.
- FESA maps Abaqus `TYPE=S4` to `MITC4`.
- Abaqus `TYPE=S4R` is not supported in Phase 1.
## Coordinate Frames
The exact local basis construction must be completed before MITC4 implementation.
Minimum requirements:
- Define a local shell normal from the quadrilateral geometry.
- Define local in-plane axes `e1` and `e2` so that `e1`, `e2`, and normal form a right-handed basis.
- Preserve Abaqus-compatible output signs.
- Document behavior for non-planar quadrilaterals.
- Use the same convention consistently for stiffness, stress/strain recovery, and result output.
Recommended Phase 1 convention:
- Use the element midsurface geometry to compute an average normal.
- Use a projected global axis to define the local 1-direction when possible, matching Abaqus convention conceptually.
- Fall back to a stable element-edge-based direction when the projected global axis is nearly parallel to the normal.
- Record the final algorithm in this document before coding.
## Shape Functions
Baseline quadrilateral bilinear interpolation:
```text
N1 = 0.25 * (1 - r) * (1 - s)
N2 = 0.25 * (1 + r) * (1 - s)
N3 = 0.25 * (1 + r) * (1 + s)
N4 = 0.25 * (1 - r) * (1 + s)
```
where `r, s` are natural coordinates in `[-1, 1]`.
Implementation requirements:
- Compute shape function derivatives with respect to natural coordinates.
- Build the surface Jacobian and local derivatives.
- Detect invalid or near-zero Jacobian as a singular/invalid element diagnostic, not as a mesh quality metric.
## Strain Treatment
The baseline element separates:
- membrane strain terms.
- bending curvature terms.
- transverse shear strain terms.
- artificial drilling stabilization.
MITC4 requirement:
- Use standard displacement interpolation for membrane and bending terms in Phase 1.
- Use MITC transverse shear interpolation to alleviate shear locking.
- Do not replace MITC4 with plain full-integration Reissner-Mindlin Q4.
The exact tying point equations and shear interpolation formula must be added from the selected primary source before implementation.
## Numerical Integration
Initial Phase 1 plan:
- In-plane integration: 2x2 Gauss for membrane/bending/shear stiffness unless the final formulation requires a different split.
- Thickness integration: homogeneous linear elastic section may be integrated analytically or with a documented simple rule.
- Benchmark literature commonly reports 2x2 in-plane Gauss integration for S4/MITC4-style 4-node elements and 2-point thickness integration in comparative shell studies.
Rules:
- Do not introduce reduced integration or hourglass control for S4R behavior in Phase 1.
- Do not optimize integration before reference benchmarks pass.
- Integration point ordering for output must be documented before stress/strain reference comparisons.
## Drilling DOF Stabilization
Decision:
- Phase 1 uses small artificial drilling stiffness.
Requirements:
- Expose a parameter such as `drilling_stiffness_scale`.
- Provide a deterministic default.
- Make the default small enough not to dominate physical response.
- Include benchmark sensitivity checks if reference results are sensitive to the value.
- Report the value in result metadata.
Open default proposal:
```text
k_drill = alpha * representative_element_stiffness
```
where `alpha` should be selected only after reviewing formulation sources and early reference cases.
## Element Outputs
Phase 1 minimum:
- element stiffness matrix.
- element equivalent nodal internal force for full-vector residual/reaction recovery.
- optional stress/strain output after displacement benchmarks are stable.
Future output:
- local shell stresses.
- local shell strains.
- section forces and moments.
- integration point and section point data.
## Required Element-Level Tests
Before integration with the global solver:
- shape functions sum to one.
- derivatives satisfy expected bilinear identities.
- element stiffness dimensions are `24 x 24`.
- stiffness is symmetric for linear elastic Phase 1.
- rigid body translations produce near-zero internal strain energy.
- rigid body rotations do not create physical membrane/bending stiffness beyond documented drilling effects.
- constant membrane patch behavior.
- bending-dominated sanity case.
- drilling stiffness sensitivity check.
## Reference Benchmarks
MITC4 baseline acceptance should include:
- single-element membrane test.
- single-element bending test.
- cantilever shell strip.
- simply supported square plate.
- Scordelis-Lo roof.
- pinched cylinder.
- twisted beam.
Distorted mesh tests should be added after the baseline passes, but Phase 1 does not implement general mesh quality diagnostics.
## Future Extensions
Geometric nonlinearity:
- Add updated geometry, current frame handling, tangent stiffness, and Newton-Raphson integration.
- Preserve `AnalysisState` element/internal state extension points.
Thermal-stress coupling:
- Add temperature field state.
- Add thermal strain contribution.
- Add material expansion data.
- Add result fields for temperature and thermal strain/stress.
S4R:
- Add only after a separate ADR and formulation document update.
- Requires reduced integration and hourglass control decisions.
## Open Decisions Before Coding
- Exact MITC4 transverse shear tying point formula.
- Exact element local basis for warped quads.
- Exact drilling stiffness default.
- Exact stress/strain recovery locations.
- Whether Phase 1 reports `S`, `E`, and `SF`, or only `U` and `RF`.
- Whether local coordinate transforms from Abaqus input are deferred or rejected.

37
docs/MULTI_AGENT_RESEARCH_PLAN.md
View File

@@ -12,6 +12,12 @@ The user will provide Abaqus input files and solved reference result files under
## Current Architecture Constraints
- Follow `AGENTS.md`, `docs/ARCHITECTURE.md`, and `docs/ADR.md`.
- Follow the technical dossier documents:
- `docs/NUMERICAL_CONVENTIONS.md`
- `docs/ABAQUS_INPUT_SUBSET.md`
- `docs/VERIFICATION_PLAN.md`
- `docs/RESULTS_SCHEMA.md`
- `docs/MITC4_FORMULATION.md`
- Use runtime polymorphism for elements, materials, loads, boundary conditions, and analysis algorithms.
- Keep `Domain` close to immutable after parsing.
- Use `AnalysisModel` for the active step view.
@@ -21,6 +27,15 @@ The user will provide Abaqus input files and solved reference result files under
- Use Factory plus Registry for Abaqus keyword to object creation.
- Keep MKL, TBB, and HDF5 behind adapter/wrapper boundaries.
- Store results using step/frame/field/history concepts.
- Use 6 DOFs per shell node: UX, UY, UZ, RX, RY, RZ.
- Use small artificial drilling stiffness in Phase 1, with the final scale documented before implementation.
- Do not enforce a unit system; use Abaqus-style self-consistent units.
- Follow Abaqus result sign conventions.
- Use constrained DOF elimination and full-vector reaction recovery.
- Use `double` precision and int64 ids/indices/equation numbering.
- Require singular system diagnostics.
- Defer mesh quality diagnostics in Phase 1.
- Map Abaqus `S4` to FESA `MITC4`; defer `S4R`.
## Created Codex Agents
The first recommended batch has been created under `.codex/agents/`.
@@ -73,24 +88,34 @@ These agents should be created after the first four produce dossiers.
## User-Provided Inputs Needed
The following inputs should be requested from the user as the research matures:
1. The intended `reference/` folder layout, or permission to propose one.
1. Confirmation or revision of the proposed `reference/` folder layout in `docs/VERIFICATION_PLAN.md`.
2. At least one simple Abaqus `.inp` file and its solved reference result artifact.
3. Preferred reference result format if available: `.dat`, `.rpt`, exported `.csv`, HDF5, or another structured format.
4. Whether Phase 1 should map Abaqus `S4` directly to FESA `MITC4`.
5. Whether Phase 1 shell nodes use six DOFs per node from the beginning: three translations and three rotations.
6. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
7. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.
3. Preferred reference result format if available: `.dat`, `.rpt`, exported `.csv`, JSON, HDF5, or another structured format.
4. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
5. The Abaqus version used to generate reference artifacts.
6. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.
7. The final default scale for artificial drilling stiffness, after formulation research.
## Seed Sources
- Abaqus input syntax rules: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
- Abaqus conventions for DOFs, units, coordinate systems, and stress/strain components: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
- Abaqus boundary keyword reference: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-boundary.htm
- Abaqus concentrated load keyword reference: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-cload.htm
- Abaqus shell section behavior: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-c-shellsectionbehavior.htm
- Abaqus conventional shell element library: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-r-shellgeneral.htm
- OpenSees ShellMITC4 manual: https://opensees.berkeley.edu/OpenSees/manuals/usermanual/640.htm
- Dvorkin-Bathe four-node shell element paper: https://web.mit.edu/kjb/www/Publications_Prior_to_1998/A_Continuum_Mechanics_Based_Four-Node_Shell_Element_for_General_Nonlinear_Analysis.pdf
- MITC3+/MITC4+ benchmark paper: https://web.mit.edu/kjb/www/Principal_Publications/Performance_of_the_MITC3%2B_and_MITC4%2B_shell_elements_in_widely_used_benchmark_problems.pdf
- COMSOL Scordelis-Lo benchmark example: https://doc.comsol.com/5.6/doc/com.comsol.help.models.sme.scordelis_lo_roof/scordelis_lo_roof.html
- NAFEMS nonlinear benchmark survey page: https://www.nafems.org/publications/pubguide/benchmarks/Page6/
- HDF5 data model: https://docs.hdfgroup.org/documentation/hdf5/latest/_h5_d_m__u_g.html
- HDF5 datasets: https://docs.hdfgroup.org/documentation/hdf5/latest/_h5_d__u_g.html
- HDF5 attributes: https://portal.hdfgroup.org/documentation/hdf5/latest/_h5_a__u_g.html
- Intel oneMKL `pardiso_64`: https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2024-2/pardiso-64.html
## Non-Goals
- Do not implement solver code.
- Do not generate phase execution files until the user explicitly asks for implementation planning.
- Do not require Abaqus execution in local validation.
- Do not treat unsourced formulas or benchmark constants as final.
- Do not add mesh quality diagnostics to Phase 1 planning unless the user changes the decision.

185
docs/NUMERICAL_CONVENTIONS.md Normal file
View File

@@ -0,0 +1,185 @@
# Numerical Conventions
## Purpose
This document defines the numerical conventions that must remain stable across the FESA solver, reference data, tests, and result files.
When a convention here conflicts with a lower-level implementation note, this document wins unless `docs/ADR.md` is updated.
## Source Basis
- Abaqus defines translational DOFs 1-3 and rotational DOFs 4-6, with rotations expressed in radians: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
- Abaqus has no built-in unit system except rotation and angle measures; user data must be self-consistent: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
- Abaqus uses right-handed coordinate systems and defines shell local surface directions from the projected global axis and positive element normal: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
- Intel oneMKL provides `pardiso_64`, an ILP64-style PARDISO interface accepting `long long int` integer data for large sparse systems: https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2024-2/pardiso-64.html
## Binding Decisions
- MITC4 coordinate and strain details will be defined explicitly in `docs/MITC4_FORMULATION.md`.
- Phase 1 shell nodes use 6 DOFs per node.
- The drilling DOF is retained and receives a small artificial stiffness in Phase 1.
- FESA does not enforce a unit system. Input values must be self-consistent, Abaqus-style.
- Result sign conventions follow Abaqus conventions.
- Essential boundary conditions are applied by constrained DOF elimination.
- Reaction forces are recovered from the full system vectors, not from the reduced system alone.
- Reference comparison uses stored Abaqus inputs and stored solved reference results under `reference/`.
- Mesh quality diagnostics are not part of Phase 1.
- Singular system diagnostics are required.
- Floating-point values use `double` by default.
- Large-model ids and indices use signed 64-bit integers.
## Degrees of Freedom
All Phase 1 shell nodes expose six structural DOFs:
| FESA Component | Abaqus DOF | Meaning | Unit |
|---|---:|---|---|
| `UX` | 1 | Translation in global or transformed x-direction | model length |
| `UY` | 2 | Translation in global or transformed y-direction | model length |
| `UZ` | 3 | Translation in global or transformed z-direction | model length |
| `RX` | 4 | Rotation about x-axis | radian |
| `RY` | 5 | Rotation about y-axis | radian |
| `RZ` | 6 | Rotation about z-axis | radian |
Implementation rules:
- Store DOF component ids using a compact enum or integer range `1..6`.
- Store global node ids, element ids, equation ids, sparse indices, and nonzero counts with signed 64-bit integer types.
- `DofManager` owns active DOF discovery, constrained/free partitioning, equation numbering, and sparse pattern inputs.
- Do not store equation ids inside `Node` or `Element`.
## Precision and Numeric Types
Recommended type aliases:
```cpp
using Real = double;
using GlobalId = std::int64_t;
using LocalIndex = std::int64_t;
using EquationId = std::int64_t;
using SparseIndex = std::int64_t;
```
Rules:
- Use `double` for matrix entries, vector entries, coordinates, material constants, loads, displacements, rotations, and result values.
- Use 64-bit integer indexing throughout the sparse assembly path so that MKL `pardiso_64` remains available for large models.
- Avoid silent narrowing when passing ids or sparse arrays to external libraries.
## Units
FESA follows the Abaqus convention: no unit system is built into the solver.
Rules:
- The solver core treats all dimensional input as unitless numeric values.
- The user and reference data must use a self-consistent unit system.
- Rotations are always radians.
- Result files may store an optional `unit_system_note` metadata string, but the solver must not convert units.
Examples of acceptable unit systems:
- `N, mm, tonne, second`
- `N, m, kg, second`
- `lbf, inch, lbf*s^2/in, second`
## Coordinate Systems
Global coordinates:
- The default global system is right-handed Cartesian.
- Phase 1 does not support user-defined transformed nodal coordinate systems unless explicitly added to `docs/ABAQUS_INPUT_SUBSET.md`.
Shell local directions:
- FESA result signs follow Abaqus shell local direction conventions.
- The exact MITC4 element basis construction must be defined in `docs/MITC4_FORMULATION.md`.
- For Abaqus compatibility, the positive shell normal is tied to node ordering by the right-hand rule.
- Local 1 and 2 directions must form a right-handed basis with the positive normal.
## Result Sign Convention
FESA result sign conventions follow Abaqus unless a FESA-specific exception is documented.
Phase 1 output variables:
- `U`: nodal displacement and rotation vector in DOF order `UX, UY, UZ, RX, RY, RZ`.
- `RF`: nodal reaction force and reaction moment in the same component order.
- `S`: shell stress components in local shell directions when available.
- `E`: shell strain components in local shell directions when available.
- `SF`: shell section force and moment resultants when available.
Stress and strain component ordering follows the Abaqus convention:
- direct 1
- direct 2
- direct 3
- shear 12
- shear 13
- shear 23
Shear strain output should be documented as engineering shear strain when matched to Abaqus-style output.
## Boundary Conditions
Phase 1 uses constrained DOF elimination:
1. Build the full DOF list.
2. Mark constrained DOFs from `*Boundary`.
3. Partition DOFs into free and constrained sets.
4. Assemble or project the reduced free-DOF system.
5. Solve for free DOF unknowns.
6. Reconstruct the full displacement vector.
Rules:
- Phase 1 supports zero-valued fixed constraints as the primary path.
- Nonzero prescribed displacements are not a Phase 1 requirement unless added to `docs/ABAQUS_INPUT_SUBSET.md`.
- `DofManager` owns constrained/free mapping and must provide enough data to reconstruct full vectors.
## Reaction Recovery
Reaction force and moment recovery uses the full system:
```text
R_full = K_full * U_full - F_full
```
Rules:
- `K_full` means the assembled stiffness before constrained DOF elimination.
- `U_full` means the solved displacement vector reconstructed with constrained DOF values.
- `F_full` means the full external load vector in the original global DOF space.
- `RF` is reported primarily for constrained DOFs, but full residual-like vectors may be retained for diagnostics.
- Reference comparison should include at least one reaction balance test.
## Drilling DOF Policy
Phase 1 retains `RZ` at each shell node and assigns a small artificial drilling stiffness.
Rules:
- The value must be parameterized, not hard-coded deep inside the MITC4 kernel.
- The default value must be documented in `docs/MITC4_FORMULATION.md` before implementation.
- The artificial stiffness should be small relative to representative membrane or bending stiffness, but large enough to avoid a singular stiffness matrix for unconstrained drilling modes.
- Reference comparisons should include sensitivity checks if the drilling stiffness materially changes displacement results.
## Singular System Diagnostics
FESA must provide actionable diagnostics before or during linear solve failure.
Required Phase 1 checks:
- No free DOFs exist after applying constraints.
- At least one active element exists in the current `AnalysisModel`.
- Every active element references existing nodes.
- Every active element references an assigned property and material.
- Every active property references an existing material.
- Every load and boundary condition references an existing node or node set.
- At least one load component is nonzero for ordinary static solve tests unless the test explicitly expects zero response.
- Free DOFs exist that are not touched by any active element connectivity.
- Rotational DOFs, especially drilling DOFs, may be unconstrained or weakly constrained.
- The reduced system size and sparse nonzero count are nonzero before solve.
- The sparse solver reports zero pivot, numerical factorization failure, or structural singularity.
Recommended diagnostic style:
```text
FESA-SINGULAR-DOF-UNTOUCHED:
Node 42 DOF RZ is free but has no stiffness contribution from active elements.
Check boundary conditions, element connectivity, property assignment, or drilling stiffness settings.
```
Phase 1 explicitly does not perform mesh quality diagnostics such as aspect ratio, warpage, skew, or element distortion checks.
## Reference Comparison Tolerances
Reference comparison must use both absolute and relative tolerances:
```text
pass if abs(actual - expected) <= abs_tol
or abs(actual - expected) <= rel_tol * max(abs(expected), reference_scale)
```
Initial defaults may be proposed per benchmark in `docs/VERIFICATION_PLAN.md`. Final tolerances should be tied to stored reference data and solver maturity.
## Open Decisions
- The exact default drilling stiffness scale.
- The final MITC4 local basis algorithm for warped quadrilateral elements.
- Which shell stress/strain/resultant outputs are mandatory in Phase 1.
- The first accepted reference result file format under `reference/`.

7
docs/PRD.md
View File

@@ -12,6 +12,7 @@ MITC4 Shell 요소를 사용해 구조 해석을 하는 유한요소 솔버를
3. Abaqus Input format 사용을 통해 다른 상용 소프트웨어와 호환성 높음
4. step/frame/history 기반 해석 결과 관리
5. reference 모델 결과 비교를 통한 정확도 검증
6. singular system 진단을 통한 해석 실패 원인 추적
## 개발 계획
1. Phase 1
@@ -23,6 +24,12 @@ MITC4 Shell 요소를 사용해 구조 해석을 하는 유한요소 솔버를
- 선형 정적 해석
- step/frame 기반 결과 저장의 최소 구조
- reference 모델 결과 비교 테스트
- 6자유도 shell node: UX, UY, UZ, RX, RY, RZ
- drilling 자유도에는 작은 인공 강성 적용
- constrained DOF 제거 방식
- full vector 기반 reaction force 계산
- double precision 및 int64 id/index/equation numbering
- singular system 진단
2. Phase 2
- 압력하중
- RBE2, RBE3 경계조건

268
docs/RESULTS_SCHEMA.md Normal file
View File

@@ -0,0 +1,268 @@
# Results Schema
## Purpose
This document defines the FESA result data model and the proposed HDF5 layout.
The schema must support Phase 1 linear static results while remaining compatible with future nonlinear increments, dynamic frames, thermal fields, and history outputs.
## Source Basis
- HDF5 files organize named objects in a rooted graph with groups and datasets: https://docs.hdfgroup.org/documentation/hdf5/latest/_h5_d_m__u_g.html
- HDF5 datasets store multidimensional arrays and metadata needed to interpret them: https://docs.hdfgroup.org/documentation/hdf5/latest/_h5_d__u_g.html
- HDF5 attributes are small metadata objects attached to groups or datasets: https://portal.hdfgroup.org/documentation/hdf5/latest/_h5_a__u_g.html
## Data Model
FESA stores results with this hierarchy:
```text
ResultFile
└── ResultStep
└── ResultFrame
├── FieldOutput
└── HistoryOutput
```
Definitions:
- `ResultStep`: one analysis step from input.
- `ResultFrame`: one output point inside a step. For Phase 1 linear static, use frame `0`.
- `FieldOutput`: node, element, integration-point, or section-point field values.
- `HistoryOutput`: scalar or vector time/load history values for selected entities or global quantities.
## HDF5 Root Layout
Proposed file layout:
```text
/
metadata/
model/
results/
steps/
Step-1/
frames/
0/
fieldOutputs/
U/
RF/
S/
E/
SF/
historyOutputs/
referenceComparison/
```
## Root Attributes
Attach these attributes to `/`:
| Attribute | Type | Required | Meaning |
|---|---|---|---|
| `schema_name` | string | yes | `FESA_RESULTS` |
| `schema_version` | int64 | yes | Start at `1` |
| `solver_name` | string | yes | `FESA` |
| `solver_version` | string | no | Build or release version |
| `created_utc` | string | no | ISO 8601 timestamp |
| `input_file` | string | no | Original input path |
| `input_sha256` | string | no | Input file hash |
| `unit_system_note` | string | no | User-provided self-consistent unit note |
| `dof_convention` | string | yes | `UX,UY,UZ,RX,RY,RZ` |
| `sign_convention` | string | yes | `Abaqus-compatible` |
## `/metadata`
Recommended datasets or attributes:
```text
/metadata/sourceFiles
/metadata/analysisType
/metadata/precision
/metadata/indexType
/metadata/conventions
```
Rules:
- Use attributes for small scalar metadata.
- Use datasets for variable-length tables or arrays.
- Store `precision = double`.
- Store `index_type = int64`.
## `/model`
The result file may contain enough model data to interpret outputs:
```text
/model/nodes/ids
/model/nodes/coordinates
/model/elements/ids
/model/elements/types
/model/elements/connectivity
/model/sets/nodeSets/<set_name>
/model/sets/elementSets/<set_name>
/model/dofs/components
```
Rules:
- Store ids as int64.
- Store coordinates as double.
- Store connectivity as int64.
- Phase 1 element type string should be `MITC4`.
- If complete model mirroring is deferred, store at least node ids, element ids, and output entity labels required to interpret results.
## Field Output Layout
Each field output group should follow this pattern:
```text
/results/steps/Step-1/frames/0/fieldOutputs/U/
values
entity_ids
component_labels
```
Attributes:
| Attribute | Type | Meaning |
|---|---|---|
| `position` | string | `NODAL`, `ELEMENT`, `INTEGRATION_POINT`, or `SECTION_POINT` |
| `entity_type` | string | `node`, `element`, etc. |
| `component_count` | int64 | Number of components |
| `basis` | string | `GLOBAL`, `LOCAL_SHELL`, or another documented basis |
| `description` | string | Human-readable field description |
Datasets:
- `entity_ids`: shape `[n_entities]`, int64.
- `values`: shape `[n_entities, n_components]`, double.
- `component_labels`: shape `[n_components]`, string.
## Phase 1 Field Outputs
### `U`
Nodal displacement and rotation.
```text
position = NODAL
entity_type = node
basis = GLOBAL
component_labels = ["UX", "UY", "UZ", "RX", "RY", "RZ"]
```
### `RF`
Nodal reaction force and moment.
```text
position = NODAL
entity_type = node
basis = GLOBAL
component_labels = ["RFX", "RFY", "RFZ", "RMX", "RMY", "RMZ"]
```
`RF` is computed from the full system:
```text
RF = K_full * U_full - F_full
```
### `S`
Shell stress output when implemented.
```text
position = INTEGRATION_POINT or SECTION_POINT
entity_type = element
basis = LOCAL_SHELL
component_labels = ["S11", "S22", "S33", "S12", "S13", "S23"]
```
### `E`
Shell strain output when implemented.
```text
position = INTEGRATION_POINT or SECTION_POINT
entity_type = element
basis = LOCAL_SHELL
component_labels = ["E11", "E22", "E33", "E12", "E13", "E23"]
```
### `SF`
Shell section force and moment resultants when implemented.
```text
position = ELEMENT or INTEGRATION_POINT
entity_type = element
basis = LOCAL_SHELL
component_labels = ["SF1", "SF2", "SF12", "SM1", "SM2", "SM12", "SS13", "SS23"]
```
The final component labels should be cross-checked with the accepted Abaqus reference output variables.
## Frame Attributes
Attach these attributes to each frame group:
| Attribute | Type | Meaning |
|---|---|---|
| `frame_id` | int64 | Zero-based frame id |
| `step_time` | double | Time/load parameter within step |
| `total_time` | double | Accumulated analysis time |
| `increment` | int64 | Increment number |
| `iteration` | int64 | Newton iteration or `0` for linear static |
| `converged` | int | `1` true, `0` false |
| `description` | string | Optional note |
For Phase 1 linear static:
- `frame_id = 0`
- `step_time = 1.0`
- `total_time = 1.0`
- `increment = 1`
- `iteration = 0`
- `converged = 1`
## History Outputs
History output layout:
```text
/results/steps/Step-1/historyOutputs/<history_name>/
x
values
component_labels
```
Attributes:
- `x_label`: usually `step_time`, `total_time`, `load_factor`, or `frame_id`.
- `entity_type`: `global`, `node`, `element`, `set`.
- `entity_id` or `entity_name`.
Phase 1 recommended history outputs:
- total external load by component.
- total reaction by component.
- maximum displacement magnitude.
- linear solver status.
## Reference Comparison Group
Optional comparison output:
```text
/referenceComparison/cases/<case_name>/
expected
actual
abs_error
rel_error
pass
```
Attributes:
- `reference_source`
- `reference_solver`
- `reference_solver_version`
- `comparison_status`
- `comparison_timestamp_utc`
## Naming Rules
- Use stable ASCII group and dataset names.
- Use original input labels as attributes when names contain spaces or nonportable characters.
- Normalize step names to HDF5-safe names while preserving original names in attributes.
- Never depend on HDF5 object iteration order for semantic ordering. Store explicit ids and labels.
## Compression and Chunking
Phase 1 may write contiguous datasets for simplicity.
For large models:
- Use chunked datasets for large field outputs.
- Consider compression only when it does not materially slow common read paths.
- Keep metadata small enough for attributes.
## Open Decisions
- Exact mandatory stress/strain/resultant output variables in Phase 1.
- Whether result files always mirror the model or only store output entity ids.
- Whether reference comparison results are stored in solver output files or separate reports.

176
docs/VERIFICATION_PLAN.md Normal file
View File

@@ -0,0 +1,176 @@
# Verification Plan
## Purpose
This document defines how FESA will be verified against small focused tests and stored reference artifacts.
The project rule is strict: solver quality is maintained by comparing against reference examples and reference results.
## Source Basis
- The original Dvorkin-Bathe four-node shell paper presents a non-flat quadrilateral shell element for thin and thick shells and includes test/demonstration problems: https://web.mit.edu/kjb/www/Publications_Prior_to_1998/A_Continuum_Mechanics_Based_Four-Node_Shell_Element_for_General_Nonlinear_Analysis.pdf
- The MITC3+/MITC4+ benchmark paper states that MITC methods address shell locking and uses widely-used shell benchmarks with convergence studies: https://web.mit.edu/kjb/www/Principal_Publications/Performance_of_the_MITC3%2B_and_MITC4%2B_shell_elements_in_widely_used_benchmark_problems.pdf
- COMSOL's Scordelis-Lo example documents the benchmark geometry, material, load, constraints, and reference displacement context: https://doc.comsol.com/5.6/doc/com.comsol.help.models.sme.scordelis_lo_roof/scordelis_lo_roof.html
- NAFEMS benchmark surveys list nonlinear shell and structural benchmark classes for future phases: https://www.nafems.org/publications/pubguide/benchmarks/Page6/
## Verification Philosophy
FESA verification uses multiple layers:
1. Unit tests for low-level math, parser, and DOF management.
2. Element tests for MITC4 stiffness, rigid body modes, patch behavior, and drilling stabilization.
3. Assembly tests for small known systems.
4. Solver tests for constrained/reduced systems and reaction recovery.
5. Input-to-result integration tests using Abaqus-style `.inp` files.
6. Reference comparisons against stored Abaqus result artifacts under `reference/`.
A single large benchmark is not enough. Phase 1 should use many small models that isolate failure causes.
## Abaqus Availability
Abaqus is not available locally and must not be required by CI.
Rules:
- The user provides `.inp` files and solved reference result artifacts.
- FESA tests compare against stored artifacts only.
- Reference artifacts are treated as the numerical source of truth once accepted into `reference/`.
## Proposed Reference Folder Contract
Recommended layout:
```text
reference/
README.md
phase1-linear-static/
manifest.json
single-element-membrane/
model.inp
expected.json
notes.md
single-element-bending/
model.inp
expected.json
notes.md
cantilever-strip/
model.inp
expected.json
notes.md
scordelis-lo-roof/
model.inp
expected.json
notes.md
```
`manifest.json` should include:
```json
{
"schema_version": 1,
"cases": [
{
"name": "single-element-membrane",
"input": "single-element-membrane/model.inp",
"expected": "single-element-membrane/expected.json",
"analysis_type": "linear_static",
"element": "MITC4",
"source_solver": "Abaqus",
"source_solver_version": "provided-by-user",
"unit_system_note": "self-consistent",
"tags": ["phase1", "element", "membrane"]
}
]
}
```
## Expected Result Artifact
Preferred `expected.json` structure:
```json
{
"schema_version": 1,
"case_name": "single-element-membrane",
"source": {
"solver": "Abaqus",
"version": "provided-by-user",
"created_by": "provided-by-user"
},
"units": {
"note": "self-consistent"
},
"comparisons": [
{
"path": "/results/steps/Step-1/frames/0/fieldOutputs/U",
"entity": {"type": "node", "id": 4},
"component": "UX",
"expected": 0.0,
"abs_tol": 1e-9,
"rel_tol": 1e-7
}
]
}
```
CSV or `.rpt` files may be stored as raw source artifacts, but structured JSON or HDF5 comparison artifacts should be used by automated tests.
## Tolerance Policy
Use absolute and relative tolerance:
```text
abs_error = abs(actual - expected)
rel_error = abs_error / max(abs(expected), reference_scale)
pass if abs_error <= abs_tol or rel_error <= rel_tol
```
Initial guidance:
- Parser and exact metadata tests: exact match.
- DOF mapping tests: exact integer match.
- Small linear algebra tests: `abs_tol = 1e-12`, `rel_tol = 1e-10`.
- Element stiffness symmetry: matrix norm tolerance around `1e-10` to `1e-9`, adjusted by stiffness scale.
- Reference displacement tests: start with `rel_tol = 1e-5` and refine after baseline agreement.
- Reaction equilibrium tests: use force-scale-based tolerances.
Final benchmark tolerances must be stored with each reference case.
## Phase 1 Benchmark Matrix
| Case | Purpose | Required Output |
|---|---|---|
| Parser smoke model | Verify Phase 1 keyword subset | Domain object counts, set membership |
| Single MITC4 membrane | Constant strain behavior | `U`, element strains/stresses if available |
| Single MITC4 bending | Bending stiffness sanity | `U`, rotations |
| Rigid body mode check | Verify near-zero internal forces without constraints | eigen/nullspace or controlled diagnostic |
| Constrained static sanity | Verify constrained DOF elimination | `U`, `RF` |
| Reaction balance | Verify full-vector reaction recovery | total load vs total reaction |
| Cantilever shell strip | Bending-dominated displacement convergence | tip `U`, support `RF` |
| Simply supported square plate | Thin shell/plate locking sensitivity | center displacement |
| Scordelis-Lo roof | Curved shell benchmark | midpoint vertical displacement |
| Pinched cylinder | Curved shell bending/membrane behavior | loaded-point displacement |
| Twisted beam | Warped shell and drilling sensitivity | tip displacement/rotation |
## Minimum Phase 1 Acceptance
Before MITC4 Phase 1 is considered credible:
- All parser smoke tests pass.
- `DofManager` free/constrained mapping tests pass.
- Reduced-system solve reconstructs full `U`.
- `RF = K_full * U_full - F_full` is tested.
- MITC4 element stiffness is symmetric within tolerance for linear elastic Phase 1.
- Rigid body modes do not create artificial membrane/bending stiffness beyond documented drilling stabilization effects.
- At least three stored Abaqus reference models pass: one single-element case, one simple multi-element plate/shell case, and one curved shell benchmark.
## Singular System Verification
Required negative tests:
- Model with no boundary conditions should fail with a singular-system diagnostic.
- Model with missing property should fail before assembly.
- Model with load on missing node or set should fail during input/model validation.
- Model with an unconstrained isolated node should identify free untouched DOFs.
- Model with only drilling DOF instability should mention weak or unconstrained rotational DOFs.
## What Not To Verify In Phase 1
- Mesh quality metrics such as aspect ratio, skew, warpage, Jacobian quality, or distortion warnings.
- Pressure loads.
- RBE2/RBE3.
- Nonlinear increments.
- Time integration.
- Thermal-stress coupling.
## User Inputs Needed
- First accepted `reference/` folder layout.
- At least one Abaqus `.inp` with solved displacement and reaction output.
- Preferred raw reference format: `.dat`, `.rpt`, `.csv`, `.json`, or `.h5`.
- Abaqus version used to generate the reference.
- Whether reference files are generated from Abaqus `S4` only for Phase 1.