add uncommitted files
This commit is contained in:
KOKO\Mimi
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,312 @@
|
||||
# FESA Phase 1 Abaqus Assembly and Reference Comparison Design
|
||||
|
||||
## 1. Status and purpose
|
||||
|
||||
This document records the approved Phase 1 design changes for:
|
||||
|
||||
- parsing both flat/orphan-mesh and Part/Assembly/Instance Abaqus inputs;
|
||||
- activating only the Part referenced by one untransformed Instance;
|
||||
- applying Phase 1 transverse-shear defaults when the input omits them; and
|
||||
- validating displacement, reaction, element internal force, and centroidal
|
||||
element stress without per-model metadata files.
|
||||
|
||||
It refines the existing Phase 1 product and architecture documents. It does not
|
||||
authorize solver implementation.
|
||||
|
||||
## 2. Phase 1 input scope
|
||||
|
||||
FESA supports two mutually exclusive input organizations.
|
||||
|
||||
### 2.1 Flat/orphan mesh
|
||||
|
||||
Nodes, elements, sets, sections, boundary conditions, and loads are defined in
|
||||
the global input scope. These records map directly to the solver `Domain`.
|
||||
|
||||
### 2.2 Part/Assembly/Instance
|
||||
|
||||
The parser preserves the following syntax scopes:
|
||||
|
||||
```text
|
||||
ParsedDeck
|
||||
├── PartDefinition[]
|
||||
├── AssemblyDefinition
|
||||
│ └── InstanceDefinition[1]
|
||||
├── MaterialDefinition[]
|
||||
└── StepDefinition
|
||||
```
|
||||
|
||||
Phase 1 accepts exactly one Assembly containing exactly one Instance. The
|
||||
Instance must:
|
||||
|
||||
- reference one defined Part;
|
||||
- contain no translation or rotation data; and
|
||||
- contain no instance-local mesh modifications.
|
||||
|
||||
Multiple Part definitions may be parsed, but only the Part referenced by the
|
||||
accepted Instance is expanded into the analysis `Domain`. Unreferenced Parts
|
||||
remain syntax/semantic input records and do not contribute nodes, elements,
|
||||
properties, loads, degrees of freedom, or results.
|
||||
|
||||
Multiple Instances, multiple Assemblies, mixed flat and hierarchical meshes,
|
||||
missing Part references, and Instance transformation data are semantic errors.
|
||||
Diagnostics identify the keyword and source location that caused the failure.
|
||||
|
||||
The following non-analysis directives found in the supplied Abaqus sample are
|
||||
explicitly recognized no-op records rather than silently ignored unknown
|
||||
keywords:
|
||||
|
||||
- `*HEADING`
|
||||
- `*PREPRINT`
|
||||
- `*RESTART`
|
||||
- `*OUTPUT`
|
||||
|
||||
Comments and output-request data owned by these directives do not affect the
|
||||
analysis `Domain`. Any other unsupported keyword or option remains an error.
|
||||
|
||||
## 3. Scope and identity resolution
|
||||
|
||||
Part-local node and element labels may be reused by future Instances. The
|
||||
semantic layer therefore identifies instantiated entities by:
|
||||
|
||||
```text
|
||||
(instance_name, part_local_label)
|
||||
```
|
||||
|
||||
The Phase 1 single-Instance restriction means this composite key is not needed
|
||||
to disambiguate the current equation system, but it is retained as explicit
|
||||
input and result provenance. Dense internal indices remain separate from
|
||||
external Abaqus labels.
|
||||
|
||||
For a hierarchical input:
|
||||
|
||||
- Part `NSET` and `ELSET` definitions resolve in Part scope.
|
||||
- Material and section references are resolved after the complete deck has
|
||||
been parsed, so their textual declaration order does not control validity.
|
||||
- Section assignments made to a Part `ELSET` are applied to the active
|
||||
Instance.
|
||||
- Assembly `NSET` and `ELSET` definitions with `INSTANCE=` lift local labels
|
||||
from the active Part into Assembly scope.
|
||||
- Nested set references resolve within their declared scope with cycle
|
||||
detection and deterministic sorted-unique membership.
|
||||
- Step-level `*BOUNDARY` and `*CLOAD` references resolve through Assembly sets.
|
||||
|
||||
For a flat input, the same semantic contracts use a reserved global scope and
|
||||
do not require an Instance name.
|
||||
|
||||
The normalized `Domain` contains analysis entities and their provenance, but it
|
||||
does not expose Abaqus keyword records to FEM, element, assembly, constraint, or
|
||||
solver modules.
|
||||
|
||||
## 4. Normalization flow
|
||||
|
||||
```text
|
||||
Abaqus input
|
||||
-> scoped syntax records
|
||||
-> complete-deck name and reference resolution
|
||||
-> organization validation
|
||||
-> active Part/Instance selection or flat-scope selection
|
||||
-> set, material, section, load, and boundary resolution
|
||||
-> normalized immutable Domain
|
||||
-> existing analysis pipeline
|
||||
```
|
||||
|
||||
The normalization stage is the only production layer that understands both
|
||||
Abaqus scopes and the flat solver `Domain`. The analysis pipeline is not made
|
||||
hierarchy-aware in Phase 1.
|
||||
|
||||
## 5. Transverse-shear default
|
||||
|
||||
If `*TRANSVERSE SHEAR STIFFNESS` is absent, the Phase 1 semantic mapper applies:
|
||||
|
||||
\[
|
||||
A_{sy}=A_{sz}=\frac{5}{6}A
|
||||
\]
|
||||
|
||||
and uses `SCF=0`.
|
||||
|
||||
If explicit transverse-shear stiffness is present, its supported values
|
||||
override the effective shear-area default. An explicitly specified nonzero
|
||||
`SCF` is unsupported in Phase 1 and produces an input diagnostic.
|
||||
|
||||
The result database records whether the effective shear properties came from
|
||||
the input or the Phase 1 default. This rule is a documented FESA Phase 1
|
||||
assumption; it is not presented as a general default for arbitrary Abaqus
|
||||
sections.
|
||||
|
||||
## 6. Reference comparison contract
|
||||
|
||||
No `metadata.json` file is required. A comparison request explicitly supplies:
|
||||
|
||||
- the result quantities to compare;
|
||||
- the path of each requested reference CSV;
|
||||
- relative tolerance; and
|
||||
- quantity-specific absolute scale.
|
||||
|
||||
The default relative tolerance is \(10^{-5}\). Absolute scales are defined by
|
||||
the PRD and test registration rather than by per-model metadata.
|
||||
|
||||
The comparison supports four quantities:
|
||||
|
||||
1. nodal displacement and rotation;
|
||||
2. nodal reaction force and moment;
|
||||
3. element-node section force and moment; and
|
||||
4. element-node centroidal axial stress.
|
||||
|
||||
A requested missing file is an error. A quantity not selected by the comparison
|
||||
request is not required and is not silently reported as passed.
|
||||
|
||||
The supplied `reference/cantilever beam` test initially requests only
|
||||
displacement and reaction. The element-force and stress readers and comparison
|
||||
kernels are still implemented and tested with synthetic reference tables.
|
||||
When the corresponding Abaqus CSV files are added, the same reference test can
|
||||
select all four quantities without changing the comparison kernel.
|
||||
|
||||
## 7. Reference CSV schemas
|
||||
|
||||
CSV readers trim surrounding whitespace from headers and values. A UTF-8 byte
|
||||
order mark on the first header is tolerated. Entity rows must be unique for the
|
||||
key required by their result type.
|
||||
|
||||
### 7.1 Displacement
|
||||
|
||||
The existing Abaqus field-report columns are accepted:
|
||||
|
||||
```text
|
||||
Part Instance Name, Node Label,
|
||||
U-U1, U-U2, U-U3, UR-UR1, UR-UR2, UR-UR3
|
||||
```
|
||||
|
||||
For a single Instance, `Part Instance Name` may be omitted.
|
||||
|
||||
### 7.2 Reaction
|
||||
|
||||
The existing Abaqus field-report columns are accepted:
|
||||
|
||||
```text
|
||||
Part Instance Name, Node Label,
|
||||
RF-RF1, RF-RF2, RF-RF3, RM-RM1, RM-RM2, RM-RM3
|
||||
```
|
||||
|
||||
For a single Instance, `Part Instance Name` may be omitted.
|
||||
|
||||
### 7.3 Element internal force
|
||||
|
||||
```text
|
||||
Part Instance Name, Element Label, Node Label,
|
||||
SF-SF1, SF-SF2, SF-SF3, SM-SM1, SM-SM2, SM-SM3
|
||||
```
|
||||
|
||||
The canonical component mapping is:
|
||||
|
||||
```text
|
||||
SF1 -> N
|
||||
SF2 -> Vy
|
||||
SF3 -> Vz
|
||||
SM1 -> T
|
||||
SM2 -> My
|
||||
SM3 -> Mz
|
||||
```
|
||||
|
||||
The element label and element-end node label together identify the result
|
||||
position. For a single Instance, `Part Instance Name` may be omitted.
|
||||
|
||||
### 7.4 Element stress
|
||||
|
||||
```text
|
||||
Part Instance Name, Element Label, Node Label, Sxx
|
||||
```
|
||||
|
||||
`Sxx` is compared with the FESA element-end stress at the section centroid:
|
||||
|
||||
\[
|
||||
\sigma_{xx,\mathrm{centroid}}=\frac{N}{A}
|
||||
\]
|
||||
|
||||
The reference comparison does not use bending stress at an unspecified
|
||||
recovery point. FESA may still store explicitly identified non-centroid
|
||||
recovery-point stresses in its HDF5 result contract. For a single Instance,
|
||||
`Part Instance Name` may be omitted.
|
||||
|
||||
## 8. Comparison behavior
|
||||
|
||||
Each scalar component uses the normalized error:
|
||||
|
||||
\[
|
||||
e_n=\frac{|a-r|}{a_\mathrm{scale}+r_\mathrm{tol}|r|}
|
||||
\]
|
||||
|
||||
and passes when \(e_n\leq1\).
|
||||
|
||||
Before evaluation, the comparison layer rejects:
|
||||
|
||||
- nonfinite actual or reference values;
|
||||
- duplicate entity/result-position rows;
|
||||
- unknown Instance, node, or element labels;
|
||||
- an element-node pair that is not part of the referenced element;
|
||||
- missing requested components; and
|
||||
- reference rows that cannot be matched to one FESA result.
|
||||
|
||||
The comparison report identifies the quantity, entity key, component,
|
||||
reference value, actual value, tolerance, and normalized error for every
|
||||
failure.
|
||||
|
||||
## 9. Required tests
|
||||
|
||||
### 9.1 Parser and semantic normalization
|
||||
|
||||
- A flat deck still produces a valid `Domain`.
|
||||
- The supplied hierarchical cantilever deck produces an active Domain from its
|
||||
single referenced Part.
|
||||
- Unreferenced Parts do not contribute analysis entities.
|
||||
- Part and Assembly sets resolve in the correct scope.
|
||||
- Material definitions declared after the Part resolve correctly.
|
||||
- Multiple Instances and multiple Assemblies are rejected.
|
||||
- Translation and rotation data are rejected.
|
||||
- Missing Part references and wrong Instance names are rejected.
|
||||
- Unsupported keywords are not silently ignored.
|
||||
- Omitted transverse-shear data yields \(A_{sy}=A_{sz}=5A/6\) and `SCF=0`.
|
||||
|
||||
### 9.2 Reference adapters and comparison
|
||||
|
||||
- Existing displacement and reaction CSV files parse after whitespace
|
||||
normalization.
|
||||
- Optional single-Instance columns are handled without weakening multi-scope
|
||||
identity checks.
|
||||
- Synthetic internal-force rows verify all six component mappings.
|
||||
- Synthetic stress rows verify centroidal \(N/A\) comparison.
|
||||
- Requested missing files, duplicates, invalid IDs, invalid element-node pairs,
|
||||
missing columns, and nonfinite values fail.
|
||||
- Relative and absolute tolerance behavior is tested near zero and at
|
||||
representative scales.
|
||||
- The current cantilever integration test selects displacement and reaction
|
||||
only.
|
||||
|
||||
## 10. Phase-plan impact
|
||||
|
||||
The existing ten Harness phases remain. Four phases receive revised steps:
|
||||
|
||||
- `domain-and-input-skeleton`: add scoped Part/Assembly/single-Instance syntax
|
||||
records and minimal normalization.
|
||||
- `abaqus-subset-completion`: complete scoped set resolution, active-Part
|
||||
expansion, no-op directive handling, and transverse-shear defaults.
|
||||
- `result-contract-completion`: recover and expose element-end internal force
|
||||
and centroidal `Sxx` alongside the complete result contract.
|
||||
- `beam-reference-qualification`: replace metadata-driven discovery with
|
||||
explicit comparison requests and use the supplied cantilever displacement
|
||||
and reaction files as the initial real reference.
|
||||
|
||||
Phase step files must keep parser syntax handling, semantic normalization,
|
||||
result recovery, CSV adaptation, and numeric comparison in separate
|
||||
module-bounded steps.
|
||||
|
||||
## 11. Completion criteria for this design change
|
||||
|
||||
Planning is consistent when:
|
||||
|
||||
- PRD, architecture, ADR, detailed implementation plan, and Harness step draft
|
||||
describe the same single-Instance scope;
|
||||
- no planning artifact requires reference metadata;
|
||||
- the current cantilever reference requires only displacement and reaction;
|
||||
- element internal-force and centroidal-stress comparison remain mandatory
|
||||
implementation work; and
|
||||
- no document claims support for multiple or transformed Instances in Phase 1.
|
||||
Reference in New Issue
Block a user