From 22a32386d56421f38db27bc74ee953c13d5754e0 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Wed, 12 Aug 2026 03:44:18 +0900 Subject: [PATCH] docs: define MITC4 reference case inventory --- .../linear-static-mitc4-shell-io.md | 283 ++++++------------ ...ear-static-mitc4-shell-reference-models.md | 121 ++++++++ 2 files changed, 217 insertions(+), 187 deletions(-) create mode 100644 docs/reference-models/linear-static-mitc4-shell-reference-models.md diff --git a/docs/io-definitions/linear-static-mitc4-shell-io.md b/docs/io-definitions/linear-static-mitc4-shell-io.md index c82e30d..47fc717 100644 --- a/docs/io-definitions/linear-static-mitc4-shell-io.md +++ b/docs/io-definitions/linear-static-mitc4-shell-io.md @@ -7,15 +7,13 @@ - source_research: `docs/research/linear-static-mitc4-shell-research.md` - source_formulation: `docs/formulations/mitc4-shell-formulation.md` - source_numerical_review: `docs/numerical-reviews/linear-static-mitc4-shell-review.md` -- source_commits: requirements `5c3025a`, research `02680dc`, formulation - `6cb0302`, numerical review `ebb2657`, S4 legacy artifacts `57122b0` -- status: `ready-for-reference-model-not-implementation-planning` +- source_commits: requirements/research/formulation policy revision `73df844` +- status: `approved-ready-for-numerical-review` - owner_agent: `io-definition-agent` - date: `2026-08-12` - authoritative_output: `results.h5` - hdf5_schema_version: `0` -- current_reference_alias: `reference/shell/` as read-only S4 legacy alias -- missing_reference_family: separate canonical S4R bundle +- reference_cases: read-only S4 at `reference/shell/`; read-only S4R at `reference/shellR/` - implementation_planning_authorized: `false` 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 without a warning and has no semantic effect on FESA quadrature. FESA always uses the formulation's `2 x 2 x 2` rule. -3. The existing `reference/shell/` files are retained without mutation as an exact - S4 legacy alias. Missing provenance is supplied only by a separately approved - Reference Model contract; it is not inferred here. +3. The existing `reference/shell/` S4 and `reference/shellR/` S4R input/displacement + files are retained under their current names without mutation. No canonical or + legacy-alias classification is required. 4. HDF5 schema version `0` is extended additively with MITC4-specific datasets while retaining the existing common metadata, nodal-result, diagnostic, CLI, and failure-atomicity conventions. -Numerical Review has accepted the current linear formulation but has not approved -the drilling default, geometry/director thresholds, U mixed tolerance, or UR warning -threshold. This I/O contract names where those approved values must appear but does -not invent implementation defaults. +The approved requirements fix the drilling rule and B33 mixed displacement tolerance. +Drilling calibration/output, `NR-O03`, `NR-O04`, bundle-administration metadata, and +an expanded reference portfolio are outside this contract. ## 1. Abaqus Input Scope @@ -109,7 +106,7 @@ thickness[,integration_points] - The raw input remains recoverable through the source file/content identity, but no `source_integration_points` physical property is created. - 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 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 nonpositive pairwise normal dot product before averaging. 4. Form and normalize the deterministic area-weighted director. -5. Apply the approved smooth-patch angle criterion. -6. Select the least-aligned global basis axis with fixed `x,y,z` tie order and form +5. Select the least-aligned global basis axis with fixed `x,y,z` tie order and form right-handed nodal frame `[a,b,d]`. -The complete center, volume-Gauss, tying, and committed-recovery inventory uses the -formulation's `J`, `j_s`, `a_g`, `c_d`, `r_J`, and `theta_w` measures. Exact numerical -thresholds are required inputs from a future approved Numerical Review decision; -this document supplies no fallback, clamp, point omission, normal flip, or default -axis. +The complete center, volume-Gauss, tying, and committed-recovery inventory requires +finite nonzero surface area, finite covariant/reciprocal bases, and finite positive +`J`. This document supplies no point omission, normal flip, or default axis. Geometry and director failures are model-validation errors. Duplicate connectivity, 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 @@ -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 rows. No nonlinear director history, iteration state, velocity, or acceleration is allocated. -- Midsurface generalized rows, section-position stress rows, nodal rows, global - equilibrium rows, and drilling evidence have distinct quantity/location identity. - Values from different locations are never averaged to satisfy a schema. +- Midsurface generalized rows, section-position stress rows, nodal rows, and global + equilibrium rows have distinct quantity/location identity. Values from different + locations are never averaged to satisfy a schema. Drilling-specific result rows do + not exist. ## 6. Output HDF5 Schema @@ -340,25 +336,16 @@ frame group is created. | `feature_id` | `linear-static-mitc4-shell` | | `solver_version` | executing solver version | | `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` | | `internal_formulation` | `FESA-MITC4` | | `integration_rule` | `2x2x2-gauss; mitc4-edge-midpoint-shear` | | `step_name` | `Step-1` | | `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 -be implementation-ready only after Numerical Review approves their values and -definition identifiers. +No drilling coefficient/ratio/energy, `theta_smooth`, or distortion/warp calibration +attribute is required. The fixed drilling formula is part of the formulation identity, +not a per-run result policy. ### 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 | | 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 | -| 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 | -| 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 | +| energy | `/steps/Step-1/frames/0/global/energy` | `[1]` float64 | `[PHYSICAL_STRAIN_ENERGY]` | `force*length`; deterministic element reduction; excludes numerical drilling stabilization | | 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 | | 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 dataset when applicable, and local-frame dataset. -The verification-metric definitions and approved thresholds remain Numerical Review -dependencies. Until their formula IDs are approved, this path is a fixed schema -reservation and not an implementation default. +Verification-metric definitions and thresholds follow the approved formulation and +requirements; they are not reference-bundle metadata. ### 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 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 -numerical drilling energy. A near-zero physical-energy denominator is never clamped -to form a misleading ratio; the later approved warning policy must classify that -case explicitly. +as physical reactions. The energy dataset contains only physical shell strain energy; +no drilling energy or drilling-to-physical ratio is written. ### 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 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 expected to equal each other on a finite mesh. - 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 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 | | --- | --- | --- | --- | -| 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 | -| 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 -`57122b0a1bdcb1a8d0eed55599742751edd534be`. They must not be renamed, rewritten, -zero-clamped, normalized, or repaired. A hash mismatch is -`needs-reference-artifacts`, not permission to restore or change the bundle. +The files must not be renamed, rewritten, zero-clamped, normalized, or repaired. +The reaction and stress CSV files in the same directory are optional review evidence +and are not comparison inputs. -The alias is `recognized-legacy-alias-needs-reference-contract`. Before numerical -comparison, the Reference Model contract must supply or approve externally: +### 7.3 Declared S4R case -- generation owner/date and exact provenance; -- 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. +The blocking S4R case uses: -CSV lacks explicit step/frame/unit/coordinate columns. They map to -`(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 -schema/provenance failure; I/O Definition does not infer values. +| role | exact path | SHA-256 | observed inventory | +| --- | --- | --- | --- | +| input | `reference/shellR/shellR.inp` | `1325940FB42B78961CF25E84379BF2693846FAD22473E7688AC5456B37B18CB4` | `TYPE=S4R`; declared comparison input | +| 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 -reference// - model.inp - _displacements.csv -``` +After trimming header whitespace, both declared displacement CSVs use: -`model.inp` must contain the approved subset and `TYPE=S4R`. The approved Reference -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. - -`` 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 | +| CSV column | comparison field/component | FESA HDF5 source | | --- | --- | --- | | `Part Instance Name` | `instance_name` | `/model/nodes.instance_name` | | `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-UR3` | displacement `UR3` | `nodal/displacement` column 5, HDF5 component `URZ` | -Reaction columns are inventoried as `[RF1,RF2,RF3,RM1,RM2,RM3]` when the optional -file passes its schema precheck, but they do not -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. +Reaction and stress CSVs do not enter MITC4 pass/fail. No row is synthesized from +those optional files. -### 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 -model_id, step_name, frame_index, instance_name, source_node_label, -quantity, component, value, unit_dimension, coordinate_system, -hdf5_dataset_path +case_id, instance_name, source_node_label, component, value, hdf5_dataset_path ``` -The unique key is all fields except `value`, `unit_dimension`, -`coordinate_system`, and `hdf5_dataset_path`; those remaining fields must agree for -the matched key. Stable ordering is model, step, frame, instance declaration order, -stable source node order, then component order +The unique key is `(case_id,instance_name,source_node_label,component)`. Stable +ordering is case, instance declaration order, stable source node order, then component order `[U1,U2,U3,UR1,UR2,UR3]`. ### 7.6 Row-set precheck and comparison policy Before tolerance evaluation: -1. Verify exact artifact inventory/hash or canonical bundle metadata. -2. Verify input source type matches model contract. -3. Verify one approved static step and final frame identity. -4. Verify expected trimmed headers, finite values, unique row keys, units, coordinate - system, and exact source node/instance identities. -5. Project HDF5 and reference to the same six-component displacement inventory. -6. Fail on any missing, extra, duplicate, nonfinite, schema-mismatched, or +1. Verify the declared input and displacement CSV path exists without mutating it. +2. Verify the trimmed displacement headers in Section 7.4. +3. Verify finite values, unique row keys, and exact source node/instance identities. +4. Project HDF5 and reference to the same six-component displacement inventory. +5. Fail on any missing, extra, duplicate, nonfinite, header-mismatched, or identity-mismatched projected row. 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 reference_scale_c = max(abs(reference_value_i)) -row_tolerance_c = absolute_floor_c - + relative_coefficient_c * reference_scale_c +row_tolerance_c = 1e-9 + 1e-6 * reference_scale_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 -zero. No reference or result value is zero-clamped, no row-specific relative -denominator replaces the component scale, and B33 floors/coefficient are not -inherited. - -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. +zero. No reference or result value is zero-clamped and no row-specific relative +denominator replaces the component scale. The formula is the approved B33 rule: +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 report records every U/UR row, blocking/nonblocking decision, absolute error, 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 | | `invalid-shell-thickness` | model/4 | thickness is nonfinite or nonpositive | | `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 | -| `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-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-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 | | 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 | -| 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 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 | | 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 | | 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 | -| S4 legacy alias | exact paths/hashes/headers plus approved external metadata | reference precheck | -| S4R canonical bundle | canonical files, metadata, S4R input, unique finite U/UR rows | reference precheck | +| S4 case | exact declared input/displacement paths and 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 | 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 | | `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 | | `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 | -| `049-057` | diagnostic/schema hooks and mandatory verification-metric/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 | -| `065-072` | exact S4 legacy alias, separate S4R canonical bundle, immutability, displacement-only gate | Reference Model | +| `049-057` | diagnostic/schema hooks and required verification-metric/physical-energy evidence | Numerical Review and planning | +| `058-064` | normalized U/UR rows, exact B33 tolerance, blocking/warning behavior, report inventory | Reference Verification | +| `065-072` | exact current S4/S4R paths, immutability and displacement-only gate | Reference Model | ## 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 -was declared as S4R. The observed immutable input is `TYPE=S4`, and the user has now -approved separate S4 and S4R artifacts. A later Requirement/Numerical Review metadata -refresh should correct that observation without changing the core requirement that -both source types map to one FESA formulation. +No I/O-owned calibration value remains open. Numerical Review shall verify the exact +fixed drilling rule, basic geometry predicates, required HDF5 inventory, and B33 +tolerance mapping. Drilling calibration/energy output, `NR-O03`, `NR-O04`, bundle +administration and reference-portfolio expansion are removed scope. -The current Numerical Review also records `reference/shell/` as unobserved because it -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 +### 11.2 Reference Model Agent - Write `docs/reference-models/linear-static-mitc4-shell-reference-models.md` using this exact keyword/HDF5/reference-row contract. -- Register `shell-s4-legacy` without modifying its four files and supply verified - provenance, units, coordinate system, and final-frame identity. -- 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. +- Record only the two exact existing input/displacement pairs, comparison components, + HDF5 projection, source-row identity, B33 tolerance and immutability rule. - Treat reaction/stress artifacts as nonblocking review evidence and do not create 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 that actual HDF5 drilling and geometry policy attributes reproduce the - approved calibration decision. -- Rerun the numerical gate before authorizing Implementation Planning. +- Confirm cross-document numerical consistency and rerun the gate before authorizing + Implementation Planning. -### 11.5 Implementation Planning Agent +### 11.4 Implementation Planning Agent - Do not start while `implementation_planning_authorized=false`. - After approval, convert every supported/unsupported keyword row, source identity, 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. +- 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, 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. -- 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 mismatches, or let UR warnings change U pass/fail. diff --git a/docs/reference-models/linear-static-mitc4-shell-reference-models.md b/docs/reference-models/linear-static-mitc4-shell-reference-models.md new file mode 100644 index 0000000..c233de4 --- /dev/null +++ b/docs/reference-models/linear-static-mitc4-shell-reference-models.md @@ -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.