modify documents
This commit is contained in:
NINI
@@ -16,6 +16,21 @@ Read first:
|
||||
- docs/PRD.md
|
||||
- docs/ARCHITECTURE.md
|
||||
- docs/ADR.md
|
||||
- docs/NUMERICAL_CONVENTIONS.md
|
||||
- docs/ABAQUS_INPUT_SUBSET.md
|
||||
- docs/VERIFICATION_PLAN.md
|
||||
- docs/RESULTS_SCHEMA.md
|
||||
- docs/MITC4_FORMULATION.md
|
||||
- docs/MULTI_AGENT_RESEARCH_PLAN.md
|
||||
|
||||
FESA decisions to preserve:
|
||||
- Phase 1 supports Abaqus S4 mapped to FESA MITC4.
|
||||
- S4R is explicitly deferred.
|
||||
- Units are not enforced; rotations are radians.
|
||||
- Result signs follow Abaqus conventions.
|
||||
- Boundary conditions use constrained DOF elimination.
|
||||
- Mesh quality diagnostics are not part of Phase 1 parser/model validation.
|
||||
- Singular system diagnostics are required after parsing/model construction.
|
||||
|
||||
Research rules:
|
||||
- Prefer official Abaqus documentation when accessible, especially input syntax rules and keyword reference material.
|
||||
@@ -39,6 +54,10 @@ Required dossier structure:
|
||||
|
||||
Seed sources to consider:
|
||||
- Abaqus input syntax rules: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
|
||||
- Abaqus conventions: 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 conventional shell element library: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-r-shellgeneral.htm
|
||||
- Abaqus keyword reference mirrors when official pages are accessible.
|
||||
- Abaqus shell section behavior: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-c-shellsectionbehavior.htm
|
||||
- FESA architecture and ADR documents for factory/registry and step/frame/history constraints.
|
||||
|
||||
@@ -16,6 +16,17 @@ Read first:
|
||||
- docs/PRD.md
|
||||
- docs/ARCHITECTURE.md
|
||||
- docs/ADR.md
|
||||
- docs/NUMERICAL_CONVENTIONS.md
|
||||
- docs/VERIFICATION_PLAN.md
|
||||
- docs/MITC4_FORMULATION.md
|
||||
- docs/MULTI_AGENT_RESEARCH_PLAN.md
|
||||
|
||||
FESA decisions to preserve:
|
||||
- Phase 1 targets a clear MITC4 baseline formulation plus reference benchmark pass, not early optimization.
|
||||
- Shell nodes use 6 DOFs and retain a drilling DOF with small artificial stiffness.
|
||||
- Units are self-consistent and not enforced by the solver.
|
||||
- Result signs follow Abaqus conventions.
|
||||
- Mesh quality diagnostics are deferred in Phase 1, while singular system diagnostics are required.
|
||||
|
||||
Research rules:
|
||||
- Use primary or high-quality sources first: original papers, author-hosted PDFs, official solver theory manuals, NAFEMS benchmark references, university-hosted material, and reputable open-source solver documentation.
|
||||
@@ -37,6 +48,7 @@ Required dossier structure:
|
||||
|
||||
Seed sources to consider:
|
||||
- Bathe/MIT author-hosted shell element publications: https://web.mit.edu/kjb/www/Principal_Publications/
|
||||
- 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
|
||||
- OpenSees ShellMITC4 manual: https://opensees.berkeley.edu/OpenSees/manuals/usermanual/640.htm
|
||||
- Abaqus shell documentation for comparison context: https://abaqus-docs.mit.edu/
|
||||
|
||||
@@ -6,6 +6,7 @@ sandbox_mode = "read-only"
|
||||
developer_instructions = """
|
||||
Review changes like a repository owner.
|
||||
Prioritize correctness, architecture compliance, behavior regressions, and missing tests over style.
|
||||
Always compare the patch against AGENTS.md, docs/ARCHITECTURE.md, docs/ADR.md, and the requested acceptance criteria.
|
||||
Always compare the patch against AGENTS.md, docs/ARCHITECTURE.md, docs/ADR.md, docs/NUMERICAL_CONVENTIONS.md, docs/ABAQUS_INPUT_SUBSET.md, docs/VERIFICATION_PLAN.md, docs/RESULTS_SCHEMA.md, docs/MITC4_FORMULATION.md, and the requested acceptance criteria.
|
||||
Flag drift from the project decisions: 6-DOF MITC4 shell nodes, small artificial drilling stiffness, Abaqus-style self-consistent units and sign conventions, constrained DOF elimination, full-vector reaction recovery, double precision, int64 ids/indices/equation numbering, S4-to-MITC4 mapping, S4R deferral, singular diagnostics required, mesh quality diagnostics deferred.
|
||||
Lead with concrete findings and file references. If no material issues are found, say so explicitly and mention residual risks.
|
||||
"""
|
||||
|
||||
@@ -16,6 +16,21 @@ Read first:
|
||||
- docs/PRD.md
|
||||
- docs/ARCHITECTURE.md
|
||||
- docs/ADR.md
|
||||
- docs/NUMERICAL_CONVENTIONS.md
|
||||
- docs/ABAQUS_INPUT_SUBSET.md
|
||||
- docs/VERIFICATION_PLAN.md
|
||||
- docs/RESULTS_SCHEMA.md
|
||||
- docs/MITC4_FORMULATION.md
|
||||
- docs/MULTI_AGENT_RESEARCH_PLAN.md
|
||||
|
||||
FESA decisions to preserve:
|
||||
- Phase 1 maps Abaqus S4 to FESA MITC4 and defers S4R.
|
||||
- Use 6 DOFs per node: UX, UY, UZ, RX, RY, RZ.
|
||||
- Retain drilling DOF and use small artificial drilling stiffness.
|
||||
- Use double precision and int64 ids/indices/equation numbering.
|
||||
- Boundary conditions use constrained DOF elimination.
|
||||
- Reactions are recovered from full vectors.
|
||||
- Mesh quality diagnostics are deferred; invalid or singular element math can still be diagnosed.
|
||||
|
||||
Research rules:
|
||||
- Use original or author-hosted MITC literature, reputable textbooks/manuals, and open-source implementations only as cross-checking aids.
|
||||
@@ -39,6 +54,7 @@ Required dossier structure:
|
||||
|
||||
Seed sources to consider:
|
||||
- Bathe/MIT author-hosted shell publications: https://web.mit.edu/kjb/www/Principal_Publications/
|
||||
- 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 and formulation context: https://web.mit.edu/kjb/www/Principal_Publications/Performance_of_the_MITC3%2B_and_MITC4%2B_shell_elements_in_widely_used_benchmark_problems.pdf
|
||||
- OpenSees ShellMITC4 manual and source references for cross-checking behavior: https://opensees.berkeley.edu/OpenSees/manuals/usermanual/640.htm
|
||||
- Abaqus shell section behavior for comparison with S4-style shell behavior: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-c-shellsectionbehavior.htm
|
||||
|
||||
@@ -5,7 +5,9 @@ model_reasoning_effort = "high"
|
||||
sandbox_mode = "read-only"
|
||||
developer_instructions = """
|
||||
Plan before implementing.
|
||||
Read AGENTS.md and the docs directory, identify the smallest coherent phase boundaries, and draft self-contained steps.
|
||||
Read AGENTS.md and the docs directory, especially PRD.md, ARCHITECTURE.md, ADR.md, NUMERICAL_CONVENTIONS.md, ABAQUS_INPUT_SUBSET.md, VERIFICATION_PLAN.md, RESULTS_SCHEMA.md, and MITC4_FORMULATION.md.
|
||||
Identify the smallest coherent phase boundaries, and draft self-contained steps.
|
||||
Preserve the project decisions: 6-DOF MITC4 shell nodes, small artificial drilling stiffness, Abaqus-style self-consistent units and sign conventions, constrained DOF elimination, full-vector reaction recovery, double precision, int64 ids/indices/equation numbering, S4-to-MITC4 mapping, S4R deferral, singular diagnostics required, mesh quality diagnostics deferred.
|
||||
Keep each step scoped to one layer or one module when possible.
|
||||
Do not make code changes unless the parent agent explicitly asks you to write files.
|
||||
Return concrete file paths, acceptance commands, and blocking assumptions.
|
||||
|
||||
@@ -16,6 +16,20 @@ Read first:
|
||||
- docs/PRD.md
|
||||
- docs/ARCHITECTURE.md
|
||||
- docs/ADR.md
|
||||
- docs/NUMERICAL_CONVENTIONS.md
|
||||
- docs/ABAQUS_INPUT_SUBSET.md
|
||||
- docs/VERIFICATION_PLAN.md
|
||||
- docs/RESULTS_SCHEMA.md
|
||||
- docs/MITC4_FORMULATION.md
|
||||
- docs/MULTI_AGENT_RESEARCH_PLAN.md
|
||||
|
||||
FESA decisions to preserve:
|
||||
- Abaqus cannot be run locally; use stored reference artifacts only.
|
||||
- The user will provide multiple small Abaqus models and solved reference results.
|
||||
- Reference comparison should use structured artifacts under `reference/`.
|
||||
- Reaction checks must use full-vector recovery.
|
||||
- Singular system negative tests are required.
|
||||
- Mesh quality diagnostics are not a Phase 1 verification target.
|
||||
|
||||
Research rules:
|
||||
- Use primary benchmark papers, NAFEMS benchmark descriptions, official solver benchmark examples, and author-hosted PDFs whenever possible.
|
||||
@@ -43,7 +57,7 @@ Priority Phase 1 benchmark candidates:
|
||||
- Pinched cylinder
|
||||
- Hemispherical shell
|
||||
- Twisted beam
|
||||
- Distorted mesh variants after baseline tests pass
|
||||
- Distorted mesh variants only after baseline tests pass; do not turn them into mesh quality diagnostics.
|
||||
|
||||
Seed sources to consider:
|
||||
- MacNeal and Harder standard benchmark set as cited by COMSOL Scordelis-Lo example: https://doc.comsol.com/5.6/doc/com.comsol.help.models.sme.scordelis_lo_roof/scordelis_lo_roof.html
|
||||
|
||||
12
AGENTS.md
12
AGENTS.md
@@ -10,19 +10,21 @@
|
||||
## 아키텍처 규칙
|
||||
- CRITICAL: 레퍼런스가 되는 예제들과 결과 비교를 통해 솔버의 품질을 항상 유지
|
||||
- CRITICAL: `docs/ARCHITECTURE.md`와 `docs/ADR.md`의 결정 사항을 우선 준수할 것. 구조 변경이 필요하면 먼저 ADR을 추가/수정할 것
|
||||
- CRITICAL: 수치 규약은 `docs/NUMERICAL_CONVENTIONS.md`를 우선 준수할 것. DOF, 좌표계, 단위, 부호, precision, reaction recovery 규약을 임의로 바꾸지 말 것
|
||||
- 요소, 재료, 하중, 경계조건, 해석 알고리즘은 런타임 다형성 기반으로 확장할 것
|
||||
- `Domain`은 입력 모델 정의를 보존하고 가능한 한 불변으로 취급할 것
|
||||
- 현재 step에서 활성화되는 객체는 `AnalysisModel`로 분리하고, 해석 중 변하는 물리량과 반복 상태는 `AnalysisState`에 저장할 것
|
||||
- 자유도 정의, constrained/free dof mapping, equation numbering, sparse pattern 생성은 `DofManager`가 전담할 것. Node/Element 내부에 equation id를 분산 저장하지 말 것
|
||||
- 해석 알고리즘은 Strategy + Template Method 구조를 따를 것. 선형 정적, 비선형 정적, 동적, 열전달 해석은 공통 실행 흐름을 공유하되 세부 반복/적분 알고리즘은 분리할 것
|
||||
- Abaqus input keyword와 내부 객체 생성은 Factory + Registry 구조로 분리할 것. Phase 1 입력 범위는 `*Node`, `*Element`, `*Nset`, `*Elset`, `*Material`, `*Elastic`, `*Shell Section`, `*Boundary`, `*Cload`, `*Step`
|
||||
- Abaqus input keyword와 내부 객체 생성은 Factory + Registry 구조로 분리할 것. Phase 1 입력 범위와 미지원 기능은 `docs/ABAQUS_INPUT_SUBSET.md`를 따를 것
|
||||
- MKL, TBB, HDF5 API는 solver core에 직접 노출하지 말고 adapter/wrapper 계층 뒤에서 사용할 것
|
||||
- 결과는 step/frame/field/history 모델로 관리할 것
|
||||
- 대규모 모델을 목표로 sparse matrix, assembly, solver 계층은 성능 확장이 가능하게 설계할 것
|
||||
- MITC4 요소 구현은 Phase 1에서 정확도와 테스트 가능성을 우선하며, reference 검증 전 과도한 최적화를 하지 말 것
|
||||
- 결과는 `docs/RESULTS_SCHEMA.md`의 step/frame/field/history 모델로 관리할 것
|
||||
- 대규모 모델을 목표로 sparse matrix, assembly, solver 계층은 성능 확장이 가능하게 설계하고, id/index/equation 번호는 int64 기반으로 둘 것
|
||||
- MITC4 요소 구현은 Phase 1에서 `docs/MITC4_FORMULATION.md`의 baseline formulation과 reference benchmark 통과를 우선하며, reference 검증 전 과도한 최적화를 하지 말 것
|
||||
- Mesh quality 진단은 Phase 1 범위에서 제외하되, singular system 진단은 필수로 구현할 것
|
||||
|
||||
## Harness Workflow
|
||||
- 먼저 `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`를 읽고 기획/설계 의도를 파악할 것
|
||||
- 먼저 `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/NUMERICAL_CONVENTIONS.md`, `docs/ABAQUS_INPUT_SUBSET.md`, `docs/VERIFICATION_PLAN.md`, `docs/RESULTS_SCHEMA.md`, `docs/MITC4_FORMULATION.md`를 읽고 기획/설계 의도를 파악할 것
|
||||
- 단계별 실행 계획이 필요하면 repo skill `harness-workflow`를 사용해 `phases/` 아래 파일을 설계할 것
|
||||
- 변경사항 리뷰가 필요하면 repo skill `harness-review` 또는 Codex의 `/review`를 사용할 것
|
||||
- `phases/{phase}/index.json`은 phase 진행 상태의 단일 진실 공급원으로 취급할 것
|
||||
|
||||
220
docs/ABAQUS_INPUT_SUBSET.md
Normal file
220
docs/ABAQUS_INPUT_SUBSET.md
Normal 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
54
docs/ADR.md
@@ -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를 관리한다.
|
||||
|
||||
@@ -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
200
docs/MITC4_FORMULATION.md
Normal 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.
|
||||
@@ -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
185
docs/NUMERICAL_CONVENTIONS.md
Normal 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/`.
|
||||
@@ -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
268
docs/RESULTS_SCHEMA.md
Normal 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
176
docs/VERIFICATION_PLAN.md
Normal 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.
|
||||
Reference in New Issue
Block a user