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

docs: define MITC4 reference case inventory

Browse Source
This commit is contained in:
KOKO\Mimi
2026-08-12 03:44:18 +09:00
parent 73df844979
commit 22a32386d5
2 changed files with 217 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/io-definitions/linear-static-mitc4-shell-io.md
+96 -187
View File
@@ -7,15 +7,13 @@
- source_research: `docs/research/linear-static-mitc4-shell-research.md` - source_research: `docs/research/linear-static-mitc4-shell-research.md`
- source_formulation: `docs/formulations/mitc4-shell-formulation.md` - source_formulation: `docs/formulations/mitc4-shell-formulation.md`
- source_numerical_review: `docs/numerical-reviews/linear-static-mitc4-shell-review.md` - source_numerical_review: `docs/numerical-reviews/linear-static-mitc4-shell-review.md`
- source_commits: requirements `5c3025a`, research `02680dc`, formulation - source_commits: requirements/research/formulation policy revision `73df844`
`6cb0302`, numerical review `ebb2657`, S4 legacy artifacts `57122b0` - status: `approved-ready-for-numerical-review`
- status: `ready-for-reference-model-not-implementation-planning`
- owner_agent: `io-definition-agent` - owner_agent: `io-definition-agent`
- date: `2026-08-12` - date: `2026-08-12`
- authoritative_output: `results.h5` - authoritative_output: `results.h5`
- hdf5_schema_version: `0` - hdf5_schema_version: `0`
- current_reference_alias: `reference/shell/` as read-only S4 legacy alias - reference_cases: read-only S4 at `reference/shell/`; read-only S4R at `reference/shellR/`
- missing_reference_family: separate canonical S4R bundle
- implementation_planning_authorized: `false` - implementation_planning_authorized: `false`
This document defines the approved semantic input and output contract for the This document defines the approved semantic input and output contract for the
@@ -30,17 +28,16 @@ The user approved the following I/O-specific decisions on `2026-08-12`:
2. The optional positive integer on a `*SHELL SECTION` thickness row is accepted 2. The optional positive integer on a `*SHELL SECTION` thickness row is accepted
without a warning and has no semantic effect on FESA quadrature. FESA always uses without a warning and has no semantic effect on FESA quadrature. FESA always uses
the formulation's `2 x 2 x 2` rule. the formulation's `2 x 2 x 2` rule.
3. The existing `reference/shell/` files are retained without mutation as an exact 3. The existing `reference/shell/` S4 and `reference/shellR/` S4R input/displacement
S4 legacy alias. Missing provenance is supplied only by a separately approved files are retained under their current names without mutation. No canonical or
Reference Model contract; it is not inferred here. legacy-alias classification is required.
4. HDF5 schema version `0` is extended additively with MITC4-specific datasets while 4. HDF5 schema version `0` is extended additively with MITC4-specific datasets while
retaining the existing common metadata, nodal-result, diagnostic, CLI, and retaining the existing common metadata, nodal-result, diagnostic, CLI, and
failure-atomicity conventions. failure-atomicity conventions.
Numerical Review has accepted the current linear formulation but has not approved The approved requirements fix the drilling rule and B33 mixed displacement tolerance.
the drilling default, geometry/director thresholds, U mixed tolerance, or UR warning Drilling calibration/output, `NR-O03`, `NR-O04`, bundle-administration metadata, and
threshold. This I/O contract names where those approved values must appear but does an expanded reference portfolio are outside this contract.
not invent implementation defaults.
## 1. Abaqus Input Scope ## 1. Abaqus Input Scope
@@ -109,7 +106,7 @@ thickness[,integration_points]
- The raw input remains recoverable through the source file/content identity, but - The raw input remains recoverable through the source file/content identity, but
no `source_integration_points` physical property is created. no `source_integration_points` physical property is created.
- FESA stiffness remains four midsurface Gauss locations times two thickness Gauss - FESA stiffness remains four midsurface Gauss locations times two thickness Gauss
locations, including when the source value is `5` as in the S4 legacy deck. locations, including when the source value is `5` in the declared S4 case.
Silently accepting this field is an explicit feature contract, not a general rule Silently accepting this field is an explicit feature contract, not a general rule
that Abaqus section parameters may be ignored. that Abaqus section parameters may be ignored.
@@ -222,19 +219,17 @@ parser-provided rotations.
3. At each node, sort incident elements by stable source identity and reject any 3. At each node, sort incident elements by stable source identity and reject any
nonpositive pairwise normal dot product before averaging. nonpositive pairwise normal dot product before averaging.
4. Form and normalize the deterministic area-weighted director. 4. Form and normalize the deterministic area-weighted director.
5. Apply the approved smooth-patch angle criterion. 5. Select the least-aligned global basis axis with fixed `x,y,z` tie order and form
6. Select the least-aligned global basis axis with fixed `x,y,z` tie order and form
right-handed nodal frame `[a,b,d]`. right-handed nodal frame `[a,b,d]`.
The complete center, volume-Gauss, tying, and committed-recovery inventory uses the The complete center, volume-Gauss, tying, and committed-recovery inventory requires
formulation's `J`, `j_s`, `a_g`, `c_d`, `r_J`, and `theta_w` measures. Exact numerical finite nonzero surface area, finite covariant/reciprocal bases, and finite positive
thresholds are required inputs from a future approved Numerical Review decision; `J`. This document supplies no point omission, normal flip, or default axis.
this document supplies no fallback, clamp, point omission, normal flip, or default
axis.
Geometry and director failures are model-validation errors. Duplicate connectivity, Geometry and director failures are model-validation errors. Duplicate connectivity,
self-intersection, degenerate/reversed geometry, invalid Jacobians, opposed incident self-intersection, degenerate/reversed geometry, invalid Jacobians, opposed incident
normals, and unapproved sharp folds fail closed. normals, and invalid basic mappings fail closed. No calibrated smooth-angle,
distortion, aspect, or warpage threshold is applied.
## 4. History Data Mapping ## 4. History Data Mapping
@@ -316,9 +311,10 @@ have no FESA dataset do not create empty synthetic physical results.
internal force, full residual/reaction, shell recovery, equilibrium, and energy internal force, full residual/reaction, shell recovery, equilibrium, and energy
rows. No nonlinear director history, iteration state, velocity, or acceleration is rows. No nonlinear director history, iteration state, velocity, or acceleration is
allocated. allocated.
- Midsurface generalized rows, section-position stress rows, nodal rows, global - Midsurface generalized rows, section-position stress rows, nodal rows, and global
equilibrium rows, and drilling evidence have distinct quantity/location identity. equilibrium rows have distinct quantity/location identity. Values from different
Values from different locations are never averaged to satisfy a schema. locations are never averaged to satisfy a schema. Drilling-specific result rows do
not exist.
## 6. Output HDF5 Schema ## 6. Output HDF5 Schema
@@ -340,25 +336,16 @@ frame group is created.
| `feature_id` | `linear-static-mitc4-shell` | | `feature_id` | `linear-static-mitc4-shell` |
| `solver_version` | executing solver version | | `solver_version` | executing solver version |
| `source_input_identity` | normalized input path plus auditable content identity | | `source_input_identity` | normalized input path plus auditable content identity |
| `unit_system_label` | ordinary run: `user-consistent-unspecified`; a reference run uses the externally approved label from its Reference Model metadata | | `unit_system_label` | `user-consistent-unspecified`; FESA does not infer a named unit system from `.inp` or reference artifacts |
| `coordinate_convention` | `global-cartesian; shell-local=(e1,e2,e3); positive-thickness=+zeta` | | `coordinate_convention` | `global-cartesian; shell-local=(e1,e2,e3); positive-thickness=+zeta` |
| `internal_formulation` | `FESA-MITC4` | | `internal_formulation` | `FESA-MITC4` |
| `integration_rule` | `2x2x2-gauss; mitc4-edge-midpoint-shear` | | `integration_rule` | `2x2x2-gauss; mitc4-edge-midpoint-shear` |
| `step_name` | `Step-1` | | `step_name` | `Step-1` |
| `frame_index` | integer `0` | | `frame_index` | integer `0` |
| `drilling_reference_family` | exact approved family identifier used in this run |
| `drilling_nominal_coordinate` | approved dimensionless nominal `rho_d` policy identifier/value |
| `theta_smooth` | approved smooth-patch bound used in validation |
| `tau_ang` | approved `j_s` bound |
| `tau_area` | approved `a_g` bound |
| `tau_dir` | approved `c_d` bound |
| `tau_var` | approved `r_J` bound |
| `theta_warp` | approved `theta_w` bound |
| `drilling_energy_warning_threshold` | approved warning rule identifier/value |
No unapproved stand-in number is legal in these numerical-policy attributes. The writer can No drilling coefficient/ratio/energy, `theta_smooth`, or distortion/warp calibration
be implementation-ready only after Numerical Review approves their values and attribute is required. The fixed drilling formula is part of the formulation identity,
definition identifiers. not a per-run result policy.
### 6.2 Model identity datasets ### 6.2 Model identity datasets
@@ -407,9 +394,7 @@ requests.
| generalized strain | `/steps/Step-1/frames/0/element/shell/generalized_strain` | `[element_count,4,8]` float64 | element row, location row; `[E11,E22,G12,K11,K22,K12,G13,G23]` | `[1,1,1,1/length,1/length,1/length,1,1]`; shell local; midsurface location | | generalized strain | `/steps/Step-1/frames/0/element/shell/generalized_strain` | `[element_count,4,8]` float64 | element row, location row; `[E11,E22,G12,K11,K22,K12,G13,G23]` | `[1,1,1,1/length,1/length,1/length,1,1]`; shell local; midsurface location |
| section resultant | `/steps/Step-1/frames/0/element/shell/section_resultant` | `[element_count,4,8]` float64 | element row, location row; `[N11,N22,N12,M11,M22,M12,Q13,Q23]` | `[force/length x3,force x3,force/length x2]`; shell local; midsurface location | | section resultant | `/steps/Step-1/frames/0/element/shell/section_resultant` | `[element_count,4,8]` float64 | element row, location row; `[N11,N22,N12,M11,M22,M12,Q13,Q23]` | `[force/length x3,force x3,force/length x2]`; shell local; midsurface location |
| in-plane stress | `/steps/Step-1/frames/0/element/shell/stress` | `[element_count,4,3,3]` float64 | element row, location row, section-position row, component `[S11,S22,S12]` | `force/length^2`; shell local; direct bottom/middle/top evaluation | | in-plane stress | `/steps/Step-1/frames/0/element/shell/stress` | `[element_count,4,3,3]` float64 | element row, location row, section-position row, component `[S11,S22,S12]` | `force/length^2`; shell local; direct bottom/middle/top evaluation |
| drilling stiffness | `/steps/Step-1/frames/0/element/shell/drilling_stiffness` | `[element_count,4]` float64 | element row and source-local node position 1..4 | `force*length`; actual positive `k_d,I` used | | energy | `/steps/Step-1/frames/0/global/energy` | `[1]` float64 | `[PHYSICAL_STRAIN_ENERGY]` | `force*length`; deterministic element reduction; excludes numerical drilling stabilization |
| drilling ratio | `/steps/Step-1/frames/0/element/shell/drilling_ratio` | `[element_count,4]` float64 | same row and source-local node position | dimensionless actual `rho_d,I=k_d,I/D_iso` |
| energy | `/steps/Step-1/frames/0/global/energy` | `[2]` float64 | `[PHYSICAL_STRAIN_ENERGY,DRILLING_STABILIZATION_ENERGY]` | `force*length`; deterministic element reduction |
| force/moment balance | `/steps/Step-1/frames/0/global/equilibrium` | `[6]` float64 | `[FORCE_1,FORCE_2,FORCE_3,MOMENT_1,MOMENT_2,MOMENT_3]` | `[force x3,force*length x3]`; global; moment reference point is global origin `[0,0,0]` | | force/moment balance | `/steps/Step-1/frames/0/global/equilibrium` | `[6]` float64 | `[FORCE_1,FORCE_2,FORCE_3,MOMENT_1,MOMENT_2,MOMENT_3]` | `[force x3,force*length x3]`; global; moment reference point is global origin `[0,0,0]` |
| verification metrics | `/steps/Step-1/frames/0/global/verification_metrics` | `[3]` float64 | `[FREE_RESIDUAL_NORMALIZED,FORCE_BALANCE_NORMALIZED,MOMENT_BALANCE_NORMALIZED]` | dimensionless; metric-definition IDs and thresholds required as attributes | | verification metrics | `/steps/Step-1/frames/0/global/verification_metrics` | `[3]` float64 | `[FREE_RESIDUAL_NORMALIZED,FORCE_BALANCE_NORMALIZED,MOMENT_BALANCE_NORMALIZED]` | dimensionless; metric-definition IDs and thresholds required as attributes |
| diagnostics | `/diagnostics` | `[diagnostic_count]` compound | `severity`, `code`, `file`, `line`, `keyword`, `entity_identity`, `message` | deterministic order; required empty dataset when count is zero | | diagnostics | `/diagnostics` | `[diagnostic_count]` compound | `severity`, `code`, `file`, `line`, `keyword`, `entity_identity`, `message` | deterministic order; required empty dataset when count is zero |
@@ -424,9 +409,8 @@ and `frame_index=0`. Shell element results additionally identify their source
element type, internal formulation, midsurface-location dataset, section-position element type, internal formulation, midsurface-location dataset, section-position
dataset when applicable, and local-frame dataset. dataset when applicable, and local-frame dataset.
The verification-metric definitions and approved thresholds remain Numerical Review Verification-metric definitions and thresholds follow the approved formulation and
dependencies. Until their formula IDs are approved, this path is a fixed schema requirements; they are not reference-bundle metadata.
reservation and not an implementation default.
### 6.5 Reaction, residual, equilibrium, and energy meaning ### 6.5 Reaction, residual, equilibrium, and energy meaning
@@ -438,10 +422,8 @@ residual dataset is not written. `/model/nodal_constraint_mask` controls meaning
Global force/moment balance uses applied `CLOAD` plus constrained reaction about Global force/moment balance uses applied `CLOAD` plus constrained reaction about
the global origin. Free residual entries remain separate evidence and are not added the global origin. Free residual entries remain separate evidence and are not added
as physical reactions. Energy is split exactly into physical strain energy and as physical reactions. The energy dataset contains only physical shell strain energy;
numerical drilling energy. A near-zero physical-energy denominator is never clamped no drilling energy or drilling-to-physical ratio is written.
to form a misleading ratio; the later approved warning policy must classify that
case explicitly.
### 6.6 Atomic finalization ### 6.6 Atomic finalization
@@ -458,9 +440,9 @@ Authoritative comparison reads `results.h5` and read-only Abaqus CSV artifacts.
A deterministic FESA CSV projection is a debugging/review view only; it is neither A deterministic FESA CSV projection is a debugging/review view only; it is neither
solver output nor a reference artifact. solver output nor a reference artifact.
### 7.1 S4/S4R portfolio separation ### 7.1 S4/S4R case separation
- S4 and S4R use distinct `model_id`, input, Reference Model Contract records, and CSV bundles. An optional `metadata.json` does not define bundle identity. - S4 and S4R use their existing distinct input and displacement CSV paths.
- FESA maps both source types to `FESA-MITC4`, but Abaqus S4 and S4R values are not - FESA maps both source types to `FESA-MITC4`, but Abaqus S4 and S4R values are not
expected to equal each other on a finite mesh. expected to equal each other on a finite mesh.
- Reference comparison always compares one FESA run with Abaqus rows generated from - Reference comparison always compares one FESA run with Abaqus rows generated from
@@ -468,73 +450,38 @@ solver output nor a reference artifact.
- Equality of FESA internal numerical rows after changing only source type is a - Equality of FESA internal numerical rows after changing only source type is a
separate implementation test, not an Abaqus S4-versus-S4R comparison. separate implementation test, not an Abaqus S4-versus-S4R comparison.
### 7.2 Approved S4 legacy alias inventory ### 7.2 Declared S4 case
The current exact alias is model ID `shell-s4-legacy`: The blocking S4 case uses:
| role | exact path | SHA-256 | observed inventory | | role | exact path | SHA-256 | observed inventory |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| input | `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` | 164 lines; `TYPE=S4`; one `*STEP,*STATIC`; `NLGEOM=NO`; generator comment `Abaqus/CAE Learning Edition 2024` | | input | `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` | `TYPE=S4`; declared comparison input |
| displacement | `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` | 49 finite data rows; U and UR columns | | displacement | `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` | 49 finite data rows; U and UR columns |
| reaction | `reference/shell/shell reactions.csv` | `0E34EEC27E700C3C0C744C1DAFD8A3B95EFEF34B8616FE96665876586FE82D41` | 49 finite data rows; RF and RM columns; review-only |
| stress | `reference/shell/shell stresses.csv` | `CBAA6E90400FE561535C4793B126F5A47020FF3FA60026C6F100253F276EFBBE` | nodal-associated S columns including S33; review-only and not location-compatible with mandatory FESA stress rows |
The files were introduced by source commit The files must not be renamed, rewritten, zero-clamped, normalized, or repaired.
`57122b0a1bdcb1a8d0eed55599742751edd534be`. They must not be renamed, rewritten, The reaction and stress CSV files in the same directory are optional review evidence
zero-clamped, normalized, or repaired. A hash mismatch is and are not comparison inputs.
`needs-reference-artifacts`, not permission to restore or change the bundle.
The alias is `recognized-legacy-alias-needs-reference-contract`. Before numerical ### 7.3 Declared S4R case
comparison, the Reference Model contract must supply or approve externally:
- generation owner/date and exact provenance; The blocking S4R case uses:
- user unit system and component unit labels;
- canonical model ID, source input identity, step and final-frame identity;
- global coordinate convention;
- material/section/thickness summary;
- CSV schema version and tolerance policy.
CSV lacks explicit step/frame/unit/coordinate columns. They map to | role | exact path | SHA-256 | observed inventory |
`(Step-1,frame 0)`, global Cartesian, and documented units if and only if the approved | --- | --- | --- | --- |
Reference Model Contract confirms that exact interpretation. Missing contract data or a conflict is a | input | `reference/shellR/shellR.inp` | `1325940FB42B78961CF25E84379BF2693846FAD22473E7688AC5456B37B18CB4` | `TYPE=S4R`; declared comparison input |
schema/provenance failure; I/O Definition does not infer values. | displacement | `reference/shellR/shellR displacements.csv` | `8887ACC5ED007CB97583A9FDC1150B48B9297E269A5BA8EBA6C1A5F6306E98CB` | 49 finite data rows; U and UR columns |
### 7.3 Separate canonical S4R bundle These files follow the same immutability rule. The reaction and stress CSV files in
the directory are optional review evidence and are not comparison inputs. No README,
`metadata.json`, canonical name, legacy alias, provenance record, or duplicated model
description is required for either case.
At least one S4R reference bundle is still required: ### 7.4 Displacement header mapping
```text After trimming header whitespace, both declared displacement CSVs use:
reference/<s4r-model-id>/
model.inp
<s4r-model-id>_displacements.csv
```
`model.inp` must contain the approved subset and `TYPE=S4R`. The approved Reference | CSV column | comparison field/component | FESA HDF5 source |
Model Contract records generator/version/provenance, unit system, coordinate system,
model/step/frame, material/section/thickness, source element type, schema version, and
tolerance policy. `metadata.json` is optional; if present, it is read-only supplementary
evidence and every overlapping field is checked against the contract and stored artifacts.
Optional reaction/stress artifacts remain nonblocking evidence.
`<s4r-model-id>` is a Reference Model-owned schema variable, not an unresolved
filename placeholder in this I/O contract.
The canonical wide displacement CSV columns are:
```text
step_name,frame_index,instance_name,source_node_label,
coordinate_system,translation_unit,rotation_unit,
U1,U2,U3,UR1,UR2,UR3
```
Rows are unique by `(step_name,frame_index,instance_name,source_node_label)`, all
numeric values are finite, and the component coordinate system is global Cartesian.
### 7.4 Legacy header normalization
After trimming header whitespace, the exact S4 displacement header mapping is:
| legacy column | canonical field/component | FESA HDF5 source |
| --- | --- | --- | | --- | --- | --- |
| `Part Instance Name` | `instance_name` | `/model/nodes.instance_name` | | `Part Instance Name` | `instance_name` | `/model/nodes.instance_name` |
| `Node Label` | `source_node_label` | `/model/nodes.source_label` | | `Node Label` | `source_node_label` | `/model/nodes.source_label` |
@@ -545,40 +492,30 @@ After trimming header whitespace, the exact S4 displacement header mapping is:
| `UR-UR2` | displacement `UR2` | `nodal/displacement` column 4, HDF5 component `URY` | | `UR-UR2` | displacement `UR2` | `nodal/displacement` column 4, HDF5 component `URY` |
| `UR-UR3` | displacement `UR3` | `nodal/displacement` column 5, HDF5 component `URZ` | | `UR-UR3` | displacement `UR3` | `nodal/displacement` column 5, HDF5 component `URZ` |
Reaction columns are inventoried as `[RF1,RF2,RF3,RM1,RM2,RM3]` when the optional Reaction and stress CSVs do not enter MITC4 pass/fail. No row is synthesized from
file passes its schema precheck, but they do not those optional files.
enter MITC4 Abaqus pass/fail. The legacy stress CSV is not projected onto FESA
integration/section-position rows because it contains a different nodal-associated
location identity and an `S33` column that FESA does not emit. Missing comparison
meaning is recorded as N/A, never repaired by averaging or synthesized rows.
### 7.5 Canonical normalized row ### 7.5 Normalized comparison row
Wide CSV and HDF5 rows normalize in memory to: CSV and HDF5 displacement rows normalize in memory to:
```text ```text
model_id, step_name, frame_index, instance_name, source_node_label, case_id, instance_name, source_node_label, component, value, hdf5_dataset_path
quantity, component, value, unit_dimension, coordinate_system,
hdf5_dataset_path
``` ```
The unique key is all fields except `value`, `unit_dimension`, The unique key is `(case_id,instance_name,source_node_label,component)`. Stable
`coordinate_system`, and `hdf5_dataset_path`; those remaining fields must agree for ordering is case, instance declaration order, stable source node order, then component order
the matched key. Stable ordering is model, step, frame, instance declaration order,
stable source node order, then component order
`[U1,U2,U3,UR1,UR2,UR3]`. `[U1,U2,U3,UR1,UR2,UR3]`.
### 7.6 Row-set precheck and comparison policy ### 7.6 Row-set precheck and comparison policy
Before tolerance evaluation: Before tolerance evaluation:
1. Verify exact artifact inventory/hash or canonical bundle metadata. 1. Verify the declared input and displacement CSV path exists without mutating it.
2. Verify input source type matches model contract. 2. Verify the trimmed displacement headers in Section 7.4.
3. Verify one approved static step and final frame identity. 3. Verify finite values, unique row keys, and exact source node/instance identities.
4. Verify expected trimmed headers, finite values, unique row keys, units, coordinate 4. Project HDF5 and reference to the same six-component displacement inventory.
system, and exact source node/instance identities. 5. Fail on any missing, extra, duplicate, nonfinite, header-mismatched, or
5. Project HDF5 and reference to the same six-component displacement inventory.
6. Fail on any missing, extra, duplicate, nonfinite, schema-mismatched, or
identity-mismatched projected row. identity-mismatched projected row.
Only `U1/U2/U3` affect pass/fail. `UR1/UR2/UR3` are always compared and reported but Only `U1/U2/U3` affect pass/fail. `UR1/UR2/UR3` are always compared and reported but
@@ -588,19 +525,15 @@ For each model, step/frame, quantity, and component group:
```text ```text
reference_scale_c = max(abs(reference_value_i)) reference_scale_c = max(abs(reference_value_i))
row_tolerance_c = absolute_floor_c row_tolerance_c = 1e-9 + 1e-6 * reference_scale_c
+ relative_coefficient_c * reference_scale_c
row_pass = abs(fesa_value-reference_value) <= row_tolerance_c row_pass = abs(fesa_value-reference_value) <= row_tolerance_c
``` ```
Reference scale uses finite Abaqus values only. A zero scale makes the relative term Reference scale uses finite Abaqus values only. A zero scale makes the relative term
zero. No reference or result value is zero-clamped, no row-specific relative zero. No reference or result value is zero-clamped and no row-specific relative
denominator replaces the component scale, and B33 floors/coefficient are not denominator replaces the component scale. The formula is the approved B33 rule:
inherited. the `1e-9` floor is in the user-consistent length unit for U and dimensionless for UR.
U exceedance fails; UR exceedance emits a deterministic warning only.
The exact `absolute_floor_c`, `relative_coefficient_c`, and UR warning threshold are
`needs-reference-model-and-numerical-review`. Comparison implementation cannot begin
until those values and their unit context are approved.
The report records every U/UR row, blocking/nonblocking decision, absolute error, The report records every U/UR row, blocking/nonblocking decision, absolute error,
component-scale normalized error, RMS error, displacement/rotation vector-norm component-scale normalized error, RMS error, displacement/rotation vector-norm
@@ -642,11 +575,10 @@ The approved shell-specific diagnostic inventory includes:
| `unsupported-shell-section-option` | input/3 | composite, offset, orientation, variable thickness, or other excluded meaning appears | | `unsupported-shell-section-option` | input/3 | composite, offset, orientation, variable thickness, or other excluded meaning appears |
| `invalid-shell-thickness` | model/4 | thickness is nonfinite or nonpositive | | `invalid-shell-thickness` | model/4 | thickness is nonfinite or nonpositive |
| `invalid-shell-material` | model/4 | isotropic material violates finite `E,nu` bounds | | `invalid-shell-material` | model/4 | isotropic material violates finite `E,nu` bounds |
| `invalid-shell-geometry` | model/4 | duplicate, self-intersecting, collapsed, reversed, or threshold-invalid surface geometry | | `invalid-shell-geometry` | model/4 | duplicate, self-intersecting, zero-area, reversed, or nonfinite surface geometry |
| `opposed-incident-normal` | model/4 | an incident normal pair has nonpositive dot product before averaging | | `opposed-incident-normal` | model/4 | an incident normal pair has nonpositive dot product before averaging |
| `sharp-shell-fold` | model/4 | incident deviation exceeds approved `theta_smooth` |
| `invalid-shell-director` | model/4 | candidate, average, interpolation, or tangent-frame construction is invalid | | `invalid-shell-director` | model/4 | candidate, average, interpolation, or tangent-frame construction is invalid |
| `invalid-shell-jacobian` | model/4 | required point violates `J/j_s/a_g/c_d/r_J/theta_w` contract | | `invalid-shell-jacobian` | model/4 | a required point has nonfinite/nonpositive `J` or nonfinite basis data |
| `unsupported-drilling-load` | model/4 | nonzero aggregate moment violates `rho_M<=1e-12` | | `unsupported-drilling-load` | model/4 | nonzero aggregate moment violates `rho_M<=1e-12` |
| `unsupported-distributed-load` | input/3 | DLOAD, pressure, gravity, body/edge/follower load is requested | | `unsupported-distributed-load` | input/3 | DLOAD, pressure, gravity, body/edge/follower load is requested |
@@ -662,17 +594,17 @@ warning behavior.
| nesting/cardinality | closed part/assembly/instance/step; one assembly and one static step | input, exit 3 | | nesting/cardinality | closed part/assembly/instance/step; one assembly and one static step | input, exit 3 |
| source identity | duplicates absent; all references resolved; multi-instance identity unique | input, exit 3 | | source identity | duplicates absent; all references resolved; multi-instance identity unique | input, exit 3 |
| element syntax/semantics | only four-node S4/S4R, distinct resolved connectivity, internal FESA-MITC4, no mixed element model | input, exit 3 | | element syntax/semantics | only four-node S4/S4R, distinct resolved connectivity, internal FESA-MITC4, no mixed element model | input, exit 3 |
| resolved element geometry | source order satisfies orientation and every approved geometry measure | model, exit 4 | | resolved element geometry | source order, finite nonzero area, topology and positive-Jacobian predicates pass | model, exit 4 |
| material/section syntax | exact row grammar, resolvable references, exactly one centered homogeneous assignment per element | input, exit 3 | | material/section syntax | exact row grammar, resolvable references, exactly one centered homogeneous assignment per element | input, exit 3 |
| material/section values | finite approved `E,nu,t` bounds | model, exit 4 | | material/section values | finite approved `E,nu,t` bounds | model, exit 4 |
| director/geometry | deterministic pairwise/average/frame construction and every approved measure threshold passes | model, exit 4 | | director/geometry | deterministic pairwise orientation, average and frame construction pass | model, exit 4 |
| boundary/load syntax | global DOF 1..6, resolved finite values, no conflicting prescribed values | input, exit 3 | | boundary/load syntax | global DOF 1..6, resolved finite values, no conflicting prescribed values | input, exit 3 |
| aggregate nodal moment | exact-zero case or nonzero `rho_M<=1e-12` | model, exit 4 | | aggregate nodal moment | exact-zero case or nonzero `rho_M<=1e-12` | model, exit 4 |
| history | sole static Step-1/frame 0, NLGEOM disabled | input, exit 3 | | history | sole static Step-1/frame 0, NLGEOM disabled | input, exit 3 |
| HDF5 model | exact paths, dtypes, shapes, IDs, source types, directors, sections, and finite values | output, exit 6 | | HDF5 model | exact paths, dtypes, shapes, IDs, source types, directors, sections, and finite values | output, exit 6 |
| HDF5 results | every mandatory row/location/component exists in stable order and is finite | output, exit 6 | | HDF5 results | every mandatory row/location/component exists in stable order and is finite | output, exit 6 |
| S4 legacy alias | exact paths/hashes/headers plus approved external metadata | reference precheck | | S4 case | exact declared input/displacement paths and unique finite U/UR rows | reference precheck |
| S4R canonical bundle | canonical files, metadata, S4R input, unique finite U/UR rows | reference precheck | | S4R case | exact declared input/displacement paths and unique finite U/UR rows | reference precheck |
| comparison | exact normalized row-set; U blocking; UR warning-only; approved tolerance | reference verification | | comparison | exact normalized row-set; U blocking; UR warning-only; approved tolerance | reference verification |
No successful parser/HDF5 implementation, numerical solution, reference comparison, No successful parser/HDF5 implementation, numerical solution, reference comparison,
@@ -684,77 +616,54 @@ physics review, or release status follows from approval of this document alone.
| --- | --- | --- | | --- | --- | --- |
| `001-004`, `021-023`, `030`, `037` | exact step, S4/S4R mapping, source/internal identity, wrapper and no-op policies | Implementation Planning tests | | `001-004`, `021-023`, `030`, `037` | exact step, S4/S4R mapping, source/internal identity, wrapper and no-op policies | Implementation Planning tests |
| `005-010` | six global DOFs, isotropic ELASTIC, single-row SHELL SECTION, exact assignment | Implementation Planning tests | | `005-010` | six global DOFs, isotropic ELASTIC, single-row SHELL SECTION, exact assignment | Implementation Planning tests |
| `011-016` | auto-director semantic mapping, geometry inventory, fail-closed diagnostics | Numerical Review for thresholds | | `011-016` | auto-director semantic mapping, basic geometry predicates and fail-closed diagnostics | Implementation Planning tests |
| `017-020` | BOUNDARY/CLOAD grammar, deterministic aggregation, `rho_M<=1e-12`, distributed-load rejection | Implementation Planning tests | | `017-020` | BOUNDARY/CLOAD grammar, deterministic aggregation, `rho_M<=1e-12`, distributed-load rejection | Implementation Planning tests |
| `024-029` | Domain/AnalysisModel/DofManager/AnalysisState semantic ownership and residual meaning | Implementation Planning | | `024-029` | Domain/AnalysisModel/DofManager/AnalysisState semantic ownership and residual meaning | Implementation Planning |
| `031-038` | source-independent MITC4 identity, drilling output evidence, full-integration policy | Numerical Review for coefficient/energy rule | | `031-038` | source-independent MITC4 identity, fixed drilling stabilization and full-integration policy; no drilling output | Implementation Planning tests |
| `039-048` | additive HDF5 v0 paths, mandatory quantities, location identity, atomic output | Reference Model and Implementation Planning | | `039-048` | additive HDF5 v0 paths, mandatory quantities, location identity, atomic output | Reference Model and Implementation Planning |
| `049-057` | diagnostic/schema hooks and mandatory verification-metric/energy evidence | Numerical Review and planning | | `049-057` | diagnostic/schema hooks and required verification-metric/physical-energy evidence | Numerical Review and planning |
| `058-064` | normalized U/UR rows, row-set precheck, blocking/warning behavior, report inventory | Reference Model and Numerical Review for values | | `058-064` | normalized U/UR rows, exact B33 tolerance, blocking/warning behavior, report inventory | Reference Verification |
| `065-072` | exact S4 legacy alias, separate S4R canonical bundle, immutability, displacement-only gate | Reference Model | | `065-072` | exact current S4/S4R paths, immutability and displacement-only gate | Reference Model |
## 11. Open Issues and Downstream Handoff ## 11. Open Issues and Downstream Handoff
### 11.1 Upstream metadata corrections ### 11.1 Numerical Review boundary
The requirements metadata says the previously unobserved `reference/shell/` candidate No I/O-owned calibration value remains open. Numerical Review shall verify the exact
was declared as S4R. The observed immutable input is `TYPE=S4`, and the user has now fixed drilling rule, basic geometry predicates, required HDF5 inventory, and B33
approved separate S4 and S4R artifacts. A later Requirement/Numerical Review metadata tolerance mapping. Drilling calibration/energy output, `NR-O03`, `NR-O04`, bundle
refresh should correct that observation without changing the core requirement that administration and reference-portfolio expansion are removed scope.
both source types map to one FESA formulation.
The current Numerical Review also records `reference/shell/` as unobserved because it ### 11.2 Reference Model Agent
predates the dev-branch merge. Its next rerun should consume this exact alias
inventory and the Reference Model contract.
### 11.2 Numerical Review dependencies
The following values remain explicitly unapproved and have no I/O default:
1. drilling reference family, nodewise `rho_d` range, stable plateau, and nominal;
2. scaled rank/conditioning and U/N/M/Q contamination bounds;
3. drilling-to-physical energy warning classification and threshold;
4. `theta_smooth`;
5. `tau_ang`, `tau_area`, `tau_dir`, `tau_var`, and `theta_warp`;
6. verification-metric formula IDs and acceptance thresholds where not already fixed;
7. component-specific U absolute floors/relative coefficients and UR warning threshold.
Until these are approved, this document is ready for Reference Model design but not
Implementation Planning.
### 11.3 Reference Model Agent
- Write `docs/reference-models/linear-static-mitc4-shell-reference-models.md` using - Write `docs/reference-models/linear-static-mitc4-shell-reference-models.md` using
this exact keyword/HDF5/reference-row contract. this exact keyword/HDF5/reference-row contract.
- Register `shell-s4-legacy` without modifying its four files and supply verified - Record only the two exact existing input/displacement pairs, comparison components,
provenance, units, coordinate system, and final-frame identity. HDF5 projection, source-row identity, B33 tolerance and immutability rule.
- Provide a separate canonical S4R bundle and additional flat/thin/thick/distorted/
curved models needed for tolerance and director/geometry calibration.
- Propose U mixed-tolerance values and the UR nonblocking warning threshold for
Numerical Review approval.
- Treat reaction/stress artifacts as nonblocking review evidence and do not create - Treat reaction/stress artifacts as nonblocking review evidence and do not create
location-equivalence claims absent from this contract. location-equivalence claims absent from this contract.
### 11.4 Numerical Review Agent ### 11.3 Numerical Review Agent
- Review Reference Model evidence and close every dependency in Section 11.2. - Confirm cross-document numerical consistency and rerun the gate before authorizing
- Confirm that actual HDF5 drilling and geometry policy attributes reproduce the Implementation Planning.
approved calibration decision.
- Rerun the numerical gate before authorizing Implementation Planning.
### 11.5 Implementation Planning Agent ### 11.4 Implementation Planning Agent
- Do not start while `implementation_planning_authorized=false`. - Do not start while `implementation_planning_authorized=false`.
- After approval, convert every supported/unsupported keyword row, source identity, - After approval, convert every supported/unsupported keyword row, source identity,
geometry/director error, drilling-load projection, exact HDF5 path/shape/order, geometry/director error, drilling-load projection, exact HDF5 path/shape/order,
atomic failure, legacy/canonical row normalization, and U-versus-UR decision into atomic failure, source-row normalization, and U-versus-UR decision into
`RED -> GREEN -> VERIFY` tests. `RED -> GREEN -> VERIFY` tests.
- Use the project Harness skill to draft multiple self-contained Steps and obtain user
approval before creating phase-planning files. Do not run the executor without a
separate explicit request.
- Keep distributed loads, mixed beam-shell models, Abaqus reduced integration, - Keep distributed loads, mixed beam-shell models, Abaqus reduced integration,
nonlinear state/tangent, and reference artifact mutation outside the plan. nonlinear state/tangent, and reference artifact mutation outside the plan.
### 11.6 Reference Verification Agent ### 11.5 Reference Verification Agent
- Enforce artifact/schema precheck before numeric tolerance. - Enforce artifact/schema precheck before numeric tolerance.
- Match HDF5 and Abaqus rows only by the canonical identity in Section 7.5. - Match HDF5 and Abaqus rows only by the normalized identity in Section 7.5.
- Never ignore missing/extra/nonfinite rows, synthesize S33/S13/S23, average location - Never ignore missing/extra/nonfinite rows, synthesize S33/S13/S23, average location
mismatches, or let UR warnings change U pass/fail. mismatches, or let UR warnings change U pass/fail.
docs/reference-models/linear-static-mitc4-shell-reference-models.md
+121
View File
@@ -0,0 +1,121 @@
# Linear Static MITC4 Shell Reference Cases
## Metadata
- feature_id: `linear-static-mitc4-shell`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- source_io_definition: `docs/io-definitions/linear-static-mitc4-shell-io.md`
- status: `approved-ready-for-numerical-review`
- owner_agent: `reference-model-agent`
- date: `2026-08-12`
- artifact_policy: `read-only-existing-files`
- authoritative_fesa_output: `results.h5`
## 1. Purpose and boundary
This document is the lightweight inventory and comparison contract for the two
approved MITC4 reference cases. Abaqus supplies an external displacement reference;
it does not define FESA element equations, integration, stabilization, recovery, or
implementation structure. FESA and Abaqus are not required to operate identically.
Reference readiness requires only:
- the declared Abaqus `.inp` file and displacement CSV for each case;
- the FESA `results.h5` generated from that case's `.inp`;
- deterministic source-instance/node/component matching;
- the approved tolerance and decision rule in Section 5.
README, `metadata.json`, canonical naming, legacy-alias approval, Abaqus version or
generation provenance, duplicated unit/coordinate/model/step/frame/material/section
descriptions, and a CSV schema-version record are not required. If `metadata.json`
later exists, it is optional read-only context and does not override the declared
input, CSV, row mapping, or tolerance.
## 2. Read-only case inventory
| case_id | source label | role | exact path | SHA-256 | observed content |
| --- | --- | --- | --- | --- | --- |
| `shell-s4` | `S4` | input | `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` | `TYPE=S4`; one linear-static case |
| `shell-s4` | `S4` | required reference | `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` | 49 data rows; U and UR components |
| `shell-s4r` | `S4R` | input | `reference/shellR/shellR.inp` | `1325940FB42B78961CF25E84379BF2693846FAD22473E7688AC5456B37B18CB4` | `TYPE=S4R`; one linear-static case |
| `shell-s4r` | `S4R` | required reference | `reference/shellR/shellR displacements.csv` | `8887ACC5ED007CB97583A9FDC1150B48B9297E269A5BA8EBA6C1A5F6306E98CB` | 49 data rows; U and UR components |
The existing reaction and stress CSVs in both directories are optional inspection
evidence only. They are not pass/fail inputs. No agent may rename, rewrite, normalize,
repair, regenerate, or restore any reference artifact unless a later phase explicitly
authorizes that operation.
## 3. Required CSV mapping
Trim surrounding whitespace from header names, then apply this exact projection:
| Abaqus CSV column | normalized identity/value | FESA HDF5 source |
| --- | --- | --- |
| `Part Instance Name` | `instance_name` | `/model/nodes.instance_name` |
| `Node Label` | `source_node_label` | `/model/nodes.source_label` |
| `U-U1` | `U1` | `/steps/Step-1/frames/0/nodal/displacement[:,0]` (`UX`) |
| `U-U2` | `U2` | `/steps/Step-1/frames/0/nodal/displacement[:,1]` (`UY`) |
| `U-U3` | `U3` | `/steps/Step-1/frames/0/nodal/displacement[:,2]` (`UZ`) |
| `UR-UR1` | `UR1` | `/steps/Step-1/frames/0/nodal/displacement[:,3]` (`URX`) |
| `UR-UR2` | `UR2` | `/steps/Step-1/frames/0/nodal/displacement[:,4]` (`URY`) |
| `UR-UR3` | `UR3` | `/steps/Step-1/frames/0/nodal/displacement[:,5]` (`URZ`) |
The normalized row key is
`(case_id,instance_name,source_node_label,component)`. Stable comparison order is
case order `shell-s4`, `shell-s4r`; then FESA instance declaration order; stable
source-node order; and component order `[U1,U2,U3,UR1,UR2,UR3]`.
## 4. Precheck
Before numerical comparison, each case shall satisfy all of the following:
1. The declared input, displacement CSV, and FESA `results.h5` exist.
2. The six required displacement headers map exactly as Section 3 specifies.
3. Each required CSV and HDF5 value is finite.
4. Each normalized row key is unique.
5. CSV and HDF5 normalized row-key sets are exactly equal.
Missing, extra, duplicate, nonfinite, header-mismatched, or source-identity-mismatched
required rows fail reference verification before tolerance evaluation. Values are not
zero-clamped and mismatched rows are not omitted, averaged, or synthesized.
## 5. Tolerance and decision rule
For each case and component `c` independently, using only finite Abaqus rows:
```text
reference_scale_c = max(abs(abaqus_value_i))
tolerance_c = 1e-9 + 1e-6 * reference_scale_c
absolute_error_i = abs(fesa_value_i - abaqus_value_i)
```
The `1e-9` floor is expressed in the model's user-consistent length unit for
`U1/U2/U3` and is dimensionless for `UR1/UR2/UR3`. A zero reference scale leaves only
the absolute floor; no alternate denominator is introduced.
- Every matched `U1/U2/U3` row must satisfy `absolute_error_i <= tolerance_c`.
Any U exceedance fails that case and the feature reference comparison.
- `UR1/UR2/UR3` uses the same formula. Every exceedance produces a deterministic
warning containing the case, source row, component, error, and tolerance, but does
not change pass/fail.
The comparison report records every U/UR row decision, maximum absolute error,
component-scale normalized error, RMS error, vector-norm error, worst source
row/component, and every UR warning.
## 6. Coverage and handoff
The two cases are the complete required reference inventory for this feature:
- `shell-s4` proves the approved `S4 -> FESA-MITC4` input path against Abaqus U;
- `shell-s4r` proves the approved `S4R -> FESA-MITC4` input path against Abaqus U.
They do not prove Abaqus formulation equivalence or general MITC4 accuracy outside
the modeled cases. Additional flat/thin/thick/distorted/curved models, mesh studies,
drilling sweeps, drilling-energy criteria, `NR-O03`, and `NR-O04` are not required
before Implementation Planning or feature completion.
Numerical Review may use this inventory as downstream comparison input, but missing
bundle-administration data shall not change a mathematically consistent formulation
verdict. Implementation Planning remains unauthorized until the revised Numerical
Review explicitly passes the formulation for planning.