ANYsolver 0.1.0__tar.gz → 0.1.2__tar.gz

anysolver-0.1.2/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.2 - 2026-07-28
+
+- Add opt-in executable CalculiX reference validation with isolated case runs,
+  stale-output protection, timeouts, solver version/hash provenance, ASCII
+  FRD/DAT parsing, tolerance-controlled comparisons, and preserved evidence
+  semantics. Deck-only generation remains explicitly `not_executed`; stale
+  non-executed legacy reports are regenerated deterministically, while invalid
+  executed evidence is preserved and rejected for diagnosis.
+- Add current-area follower pressure and its exact, generally nonsymmetric
+  external-load tangent to nonlinear static and arc-length solves. Extend
+  shell initial-stress stiffness to the Mindlin translation/director field
+  using membrane, bending, and second stress moments, and add the qualified
+  thin-ring pressure-buckling gate.
+- Add an opt-in consistent corotational tangent through the full
+  pull-back/frame/rotate-forward chain rule. `auto` retains the lower-cost
+  rotated tangent for ordinary loads and selects the consistent tangent for
+  follower pressure.
+- Unify nonlinear stress recovery around committed shell-layer and beam-fiber
+  histories, matching solution displacements, objective corotational frames,
+  component-level provenance, and explicit elastic fallbacks. Add guarded
+  full-integration Q4/Q8 patch recovery that separates discontinuities and
+  labels its optional surface-stress L2 indicator as non-energy-norm.
+- Add shell membrane/bending stress and prestrain fields plus beam-fiber
+  initial fields, with zero-load equilibration, immutable field provenance,
+  exact load-stage boundary commits, and persistent plastic history through
+  multi-stage displacement control.
+- Replace the default finite-difference plane-stress algorithmic tangent with
+  the analytical consistent derivative of the discrete return map. Retain the
+  representable-step numerical tangent as a qualification oracle and guarded
+  invalid-row fallback, add a safeguarded local consistency solve with
+  fail-closed residual checks, and add constitutive and full-Newton
+  parity/performance evidence.
+
+## 0.1.1 - 2026-07-25
+
+- Correct the layered-shell membrane/bending coupling tangent and keep the
+  accelerated plastic shell path consistent with the scalar return mapping.
+- Fail closed for curved B3 members, experimental Q8R qualification, unsupported
+  DNV-RP-C208 thickness rows, and path-dependent staged displacement control.
+- Include point masses in reported mass properties, make buckling constraints
+  call-order independent, and correct CalculiX gravity export.
+- Remove quadratic model-construction and beam/shell coupling lookup scaling,
+  safely reset precomputed incoming elements, cache recovery operators and
+  topology signatures, defer optional acceleration imports, and use lower
+  PyPardiso thresholds only for compatible retained patterns.
+- Preserve straight-sided B3 midpoint geometry through adaptive cylinder
+  refinement and reconstruct complete elastic layer states after accelerated
+  nonlinear solves.
+- Add explicit runtime exports, generic generated-geometry API aliases, and
+  package-root arc-length exports.
+- Adopt the pure-solver test files from ANYstructure (triangular shell
+  backend, local patch transition, geometry panel).
+
+## 0.1.0 - 2026-07-22
+
+- Transfer the qualified beam/shell solver from ANYintelligent into its own package.
+- Add the headless runtime meshing and analysis facade formerly embedded in ANYstructure.
+- Publish the Python import namespace as `anysolver` without a legacy `fe_solver` shim.
+- Preserve SESAM interchange, verification, qualification, benchmark, and baseline workflows.

{anysolver-0.1.0 → anysolver-0.1.2}/MANIFEST.in

@@ -1,7 +1,7 @@
-include LICENSE
-include README.md
-include CHANGELOG.md
-include MIGRATION.md
-recursive-include docs *.md
-recursive-include scripts *.py
-recursive-include tests *.py *.json *.md
+include LICENSE
+include README.md
+include CHANGELOG.md
+include MIGRATION.md
+recursive-include docs *.md
+recursive-include scripts *.py
+recursive-include tests *.py *.json

{anysolver-0.1.0 → anysolver-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ANYsolver
-Version: 0.1.0
+Version: 0.1.2
 Summary: Qualified beam and shell finite-element solver
 Author-email: Audun Arnesen Nyhus <audunarn@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -82,21 +82,23 @@ changes before making release claims.
 | Area | Implemented functionality |
 | --- | --- |
 | Model | Six DOFs per node; SI units; materials, density, nodal mass, shell/beam topology, supports, and MPC constraints. |
-| Shells | 3- and 6-node triangles; 4-node MITC-style and 8-node Mindlin-Reissner quadrilaterals; stiffness, mass, pressure, geometric stiffness, and stress recovery. Q8R reduced integration is experimental and outside the qualified thin-bending/nonlinear-batch scope. |
+| Shells | 3- and 6-node triangles; 4-node MITC-style and 8-node Mindlin-Reissner quadrilaterals; stiffness, mass, pressure, and stress recovery. The shell initial-stress operator includes membrane, bending, and second stress moments acting through the implemented Mindlin translation/director field. Q8R reduced integration is experimental and outside the qualified thin-bending/nonlinear-batch scope. |
 | Beams | 2-node and straight-sided 3-node Timoshenko beams with axial, biaxial bending, shear, torsion, consistent/lumped mass options, geometric stiffness, and optional fiber-section plasticity. |
 | Coupling | Coincident or eccentric beam-shell kinematics through explicit interpolated MPC transformations. |
-| Loads | Nodal force/moment, shell pressure, in-plane edge loads, acceleration/gravity, prescribed displacement, load combinations, proportional and staged nonlinear loads. |
+| Loads | Nodal force/moment, dead or current-area follower shell pressure, in-plane edge loads, acceleration/gravity, prescribed displacement, load combinations, proportional and staged nonlinear loads. Follower pressure includes its exact, generally nonsymmetric external-load tangent. |
 | Linear analysis | Static single- and multiple-RHS solves, reactions and MPC-force diagnostics, free-free rigid-body nullspace handling, and sparse factorization reuse. |
 | Modal and mass | Consistent mass assembly, point masses, model mass/inertia properties, constrained and free-free vibration modes. |
-| Buckling | Linear eigenvalue buckling for beam axial force and shell membrane-resultant prestress, including sparse shift-invert and repeated-mode diagnostics. |
-| Nonlinear static | Incremental Newton solution, adaptive stepping, force or displacement control, von Karman or opt-in corotational kinematics, layered shell J2 plasticity, beam fiber plasticity, staged loads, and simplified element erosion. |
-| Continuation | Bounded Crisfield-style spherical arc-length tracing through a first limit point and a guarded descending branch. |
+| Buckling | Linear eigenvalue buckling for beam axial force and shell Mindlin initial-stress resultants, including sparse shift-invert and repeated-mode diagnostics. A follower-load stiffness can be included when its constrained tangent is symmetric; a general nonsymmetric follower eigenproblem is outside scope. |
+| Nonlinear static | Incremental Newton solution, adaptive stepping, force or displacement control, dead or follower pressure, von Karman or opt-in corotational kinematics, rotated or consistent corotational tangent, layered shell J2 plasticity with a safeguarded local solve and analytical consistent tangent, beam fiber plasticity, stage-boundary commits, true preload/restart displacement control, and simplified element erosion. |
+| Continuation | Bounded Crisfield-style spherical arc-length tracing through a first limit point and a guarded descending branch, including current-area follower pressure and its load tangent. |
 | Dynamics | Newmark or HHT-alpha implicit transient response, Rayleigh damping, prescribed shell pressure patches, selected/envelope history storage, and memory preflight. |
 | Impact/contact | One rigid sphere with frictionless penalty contact against shells and opt-in beam-axis segments; event substepping, Aitken relaxation, nonlinear material response, and engineering damage/erosion options. |
 | Imperfections | Stress-free eigenmode, member-bow, plate-wave, flange-twist, explicit, and composite imperfection fields. |
+| Initial fields | Element-local shell membrane/bending stress or membrane/curvature prestrain, arbitrary configured beam-fiber stress/prestrain distributions, zero-external-load equilibration, admissibility checks, and provenance kept separate from geometric imperfections. |
 | Workflows | Normalized generated geometry to static/prestress/buckling; traceable static-to-buckling-to-imperfect nonlinear-capacity workflow. |
 | Interchange | Pure-Python SESAM formatted FEM record/document parsing, guarded round-trip writing, supported semantic import to `FEModel`, coordinate transforms, beam orientation, and SIF shell-stress reading by load case. |
-| Results | Result provenance, element and nodal stress recovery, selected recovery, reaction filtering, validation diagnostics, deterministic baselines, benchmarks, and generated qualification reports. |
+| Results | Result provenance; unified elastic or committed shell-layer/beam-fiber stress recovery; guarded Zienkiewicz-Zhu-style patch recovery for qualified shell neighborhoods; selected recovery; reaction filtering; validation diagnostics; deterministic baselines; benchmarks; and generated qualification reports. |
+| External verification | Reproducible CalculiX input generation plus opt-in isolated execution, FRD/DAT parsing, solver provenance, and tolerance-controlled analytical comparison. Deck-only reports remain explicitly `not_executed` and make no numerical-agreement claim. |
 
 Implemented does not automatically mean qualified for every geometry or load
 regime. The live capability matrix is produced by
@@ -116,21 +118,46 @@ Important limits:
 - the 3-node quadratic beam is straight-sided; curved members must be
   represented by straight beam segments until a true curved formulation is
   implemented;
-- shell buckling uses the implemented membrane-resultant geometric stiffness,
-  not a complete finite-rotation shell geometric stiffness;
-- no follower-pressure load or tangent;
+- the shell initial-stress operator covers the in-plane `N`, `M`, and `H`
+  stress moments acting on Mindlin midsurface translations and director
+  gradients; it does not add drilling, transverse-normal-stress, or a
+  geometrically exact finite-rotation shell/director formulation;
+- current-area follower pressure is supported in nonlinear static and
+  arc-length analyses, with its exact load tangent. Linear/dead pressure
+  remains the default. Linear buckling rejects a constrained nonsymmetric
+  follower-pressure pencil because general complex nonconservative
+  eigenanalysis is not implemented;
 - no general shell-shell, body-body, frictional, rolling, or self-contact;
 - no fluid-structure interaction, cavitation, or water-entry model;
 - no cohesive cracks, remeshing, material separation, or fracture-mechanics
   claim—the erosion models are engineering screens;
 - no unrestricted deep post-buckling or automatic bifurcation branch switching;
-- no consistent frame-derivative tangent for the corotational formulation;
-- no general material-aware stress reconstruction when committed nonlinear
-  layer/fiber state is unavailable;
-- no true multi-stage plastic preload followed by displacement control;
-- no unverified material laws, residual-stress fields, or distortion ranges;
-- SESAM `FEModel` export and external-solver execution/comparison remain outside
-  the supported interchange gate.
+- the consistent corotational tangent includes frame derivatives and is
+  selected automatically for follower pressure, but its numerical
+  frame-sensitivity evaluation is costlier than the rotated tangent used by
+  default for ordinary corotational solves;
+- material-history-aware recovery requires retained, matching committed
+  nonlinear layer/fiber states; missing or invalid state is reported and the
+  affected components fall back explicitly to elastic reconstruction;
+- the guarded patch-recovery fit is qualified only for locally planar,
+  consistently oriented, homogeneous, full-integration Q4 or Q8 shell
+  neighborhoods. Discontinuities remain separate, and the optional normalized
+  stress-L2 discrepancy is a diagnostic—not an energy-norm error estimate;
+- initial stress/prestrain fields are qualified only in element-local reference
+  coordinates with `kinematics="von_karman"`. Shell fields use the documented
+  membrane/positive-face-bending convention, and beam fields require a
+  configured fiber section. Input stress must be admissible for the supplied
+  hardening state; equilibration may redistribute it and does not reconstruct
+  the manufacturing history. A field-bearing restart also requires its
+  matching converged displacement vector;
+- the analytical plane-stress tangent is branch-consistent. The numerical
+  derivative remains an oracle and automatic invalid-row fallback; local
+  yield-residual nonconvergence fails closed;
+- no unverified material laws or distortion ranges;
+- SESAM `FEModel` export remains outside the supported interchange gate;
+- CalculiX comparison requires a compatible local executable and an explicit
+  execution request. Deck generation alone is a reproducibility handoff, not
+  external numerical evidence.
 
 Use `validate_production_model()`, the analysis-specific preflight checks, and
 the generated production-scope artifacts before production use.
@@ -161,5 +188,16 @@ python scripts/run_fe_verification.py
 ```
 
 The last command regenerates the canonical JSON and Markdown evidence under
-`reports/verification/`. External-reference decks are handoff artifacts unless
-matching external-solver results have actually been executed and compared.
+`reports/verification/`. Its default external-reference mode generates
+handoff decks with status `not_executed`; that status is not a pass or a claim
+of numerical agreement. To execute the comparisons, provide a compatible
+CalculiX executable on `PATH`, through `ANYSOLVER_CALCULIX_EXECUTABLE`, or with
+`--calculix`, and run:
+
+```powershell
+python scripts/run_fe_verification.py --execute-calculix
+```
+
+An external case becomes passing evidence only after isolated execution,
+successful FRD/DAT parsing, and every declared comparison meeting its
+tolerance.

{anysolver-0.1.0 → anysolver-0.1.2}/README.md

@@ -1,130 +1,168 @@
-# ANYsolver finite-element solver
-
-`anysolver` is a headless structural FE solver for beam,
-shell, stiffened-panel, and cylindrical-shell analysis. It is an engineering
-solver with an explicit qualification scope, not a general-purpose CAD,
-contact, or fracture platform.
-
-Install the released package with:
-
-```powershell
-python -m pip install ANYsolver
-```
-
-For coordinated local development with ANYstructure:
-
-```powershell
-python -m pip install -e C:\Github\ANYsolver
-```
-
-Core analyses and the solver-owned generated-geometry workflow are available
-directly from `anysolver`; the lightweight normalized flat-panel and cylinder
-facade is exposed through `anysolver.runtime`:
-
-```python
-from anysolver import (
-    FEModel,
-    GeneratedGeometryFEMConfig,
-    LoadCase,
-    run_generated_geometry_fem,
-    solve_linear,
-)
-from anysolver.runtime import LightweightFEMConfig, run_production_fem
-```
-
-The generic `GeneratedGeometryFEM*` names are the preferred workflow API.
-Historical `AnyStructureFEM*` aliases remain available only for downstream
-compatibility. Material selection is centralized in
-`dnv_c208_steel_properties()` and `dnv_c208_steel_curve()`; the runtime facade
-uses the same canonical table and validation.
-
-The source code and tests are authoritative. Generated reports under
-`reports/` are dated evidence snapshots and must be regenerated after solver
-changes before making release claims.
-
-## Functional overview
-
-| Area | Implemented functionality |
-| --- | --- |
-| Model | Six DOFs per node; SI units; materials, density, nodal mass, shell/beam topology, supports, and MPC constraints. |
-| Shells | 3- and 6-node triangles; 4-node MITC-style and 8-node Mindlin-Reissner quadrilaterals; stiffness, mass, pressure, geometric stiffness, and stress recovery. Q8R reduced integration is experimental and outside the qualified thin-bending/nonlinear-batch scope. |
-| Beams | 2-node and straight-sided 3-node Timoshenko beams with axial, biaxial bending, shear, torsion, consistent/lumped mass options, geometric stiffness, and optional fiber-section plasticity. |
-| Coupling | Coincident or eccentric beam-shell kinematics through explicit interpolated MPC transformations. |
-| Loads | Nodal force/moment, shell pressure, in-plane edge loads, acceleration/gravity, prescribed displacement, load combinations, proportional and staged nonlinear loads. |
-| Linear analysis | Static single- and multiple-RHS solves, reactions and MPC-force diagnostics, free-free rigid-body nullspace handling, and sparse factorization reuse. |
-| Modal and mass | Consistent mass assembly, point masses, model mass/inertia properties, constrained and free-free vibration modes. |
-| Buckling | Linear eigenvalue buckling for beam axial force and shell membrane-resultant prestress, including sparse shift-invert and repeated-mode diagnostics. |
-| Nonlinear static | Incremental Newton solution, adaptive stepping, force or displacement control, von Karman or opt-in corotational kinematics, layered shell J2 plasticity, beam fiber plasticity, staged loads, and simplified element erosion. |
-| Continuation | Bounded Crisfield-style spherical arc-length tracing through a first limit point and a guarded descending branch. |
-| Dynamics | Newmark or HHT-alpha implicit transient response, Rayleigh damping, prescribed shell pressure patches, selected/envelope history storage, and memory preflight. |
-| Impact/contact | One rigid sphere with frictionless penalty contact against shells and opt-in beam-axis segments; event substepping, Aitken relaxation, nonlinear material response, and engineering damage/erosion options. |
+# ANYsolver finite-element solver
+
+`anysolver` is a headless structural FE solver for beam,
+shell, stiffened-panel, and cylindrical-shell analysis. It is an engineering
+solver with an explicit qualification scope, not a general-purpose CAD,
+contact, or fracture platform.
+
+Install the released package with:
+
+```powershell
+python -m pip install ANYsolver
+```
+
+For coordinated local development with ANYstructure:
+
+```powershell
+python -m pip install -e C:\Github\ANYsolver
+```
+
+Core analyses and the solver-owned generated-geometry workflow are available
+directly from `anysolver`; the lightweight normalized flat-panel and cylinder
+facade is exposed through `anysolver.runtime`:
+
+```python
+from anysolver import (
+    FEModel,
+    GeneratedGeometryFEMConfig,
+    LoadCase,
+    run_generated_geometry_fem,
+    solve_linear,
+)
+from anysolver.runtime import LightweightFEMConfig, run_production_fem
+```
+
+The generic `GeneratedGeometryFEM*` names are the preferred workflow API.
+Historical `AnyStructureFEM*` aliases remain available only for downstream
+compatibility. Material selection is centralized in
+`dnv_c208_steel_properties()` and `dnv_c208_steel_curve()`; the runtime facade
+uses the same canonical table and validation.
+
+The source code and tests are authoritative. Generated reports under
+`reports/` are dated evidence snapshots and must be regenerated after solver
+changes before making release claims.
+
+## Functional overview
+
+| Area | Implemented functionality |
+| --- | --- |
+| Model | Six DOFs per node; SI units; materials, density, nodal mass, shell/beam topology, supports, and MPC constraints. |
+| Shells | 3- and 6-node triangles; 4-node MITC-style and 8-node Mindlin-Reissner quadrilaterals; stiffness, mass, pressure, and stress recovery. The shell initial-stress operator includes membrane, bending, and second stress moments acting through the implemented Mindlin translation/director field. Q8R reduced integration is experimental and outside the qualified thin-bending/nonlinear-batch scope. |
+| Beams | 2-node and straight-sided 3-node Timoshenko beams with axial, biaxial bending, shear, torsion, consistent/lumped mass options, geometric stiffness, and optional fiber-section plasticity. |
+| Coupling | Coincident or eccentric beam-shell kinematics through explicit interpolated MPC transformations. |
+| Loads | Nodal force/moment, dead or current-area follower shell pressure, in-plane edge loads, acceleration/gravity, prescribed displacement, load combinations, proportional and staged nonlinear loads. Follower pressure includes its exact, generally nonsymmetric external-load tangent. |
+| Linear analysis | Static single- and multiple-RHS solves, reactions and MPC-force diagnostics, free-free rigid-body nullspace handling, and sparse factorization reuse. |
+| Modal and mass | Consistent mass assembly, point masses, model mass/inertia properties, constrained and free-free vibration modes. |
+| Buckling | Linear eigenvalue buckling for beam axial force and shell Mindlin initial-stress resultants, including sparse shift-invert and repeated-mode diagnostics. A follower-load stiffness can be included when its constrained tangent is symmetric; a general nonsymmetric follower eigenproblem is outside scope. |
+| Nonlinear static | Incremental Newton solution, adaptive stepping, force or displacement control, dead or follower pressure, von Karman or opt-in corotational kinematics, rotated or consistent corotational tangent, layered shell J2 plasticity with a safeguarded local solve and analytical consistent tangent, beam fiber plasticity, stage-boundary commits, true preload/restart displacement control, and simplified element erosion. |
+| Continuation | Bounded Crisfield-style spherical arc-length tracing through a first limit point and a guarded descending branch, including current-area follower pressure and its load tangent. |
+| Dynamics | Newmark or HHT-alpha implicit transient response, Rayleigh damping, prescribed shell pressure patches, selected/envelope history storage, and memory preflight. |
+| Impact/contact | One rigid sphere with frictionless penalty contact against shells and opt-in beam-axis segments; event substepping, Aitken relaxation, nonlinear material response, and engineering damage/erosion options. |
 | Imperfections | Stress-free eigenmode, member-bow, plate-wave, flange-twist, explicit, and composite imperfection fields. |
-| Workflows | Normalized generated geometry to static/prestress/buckling; traceable static-to-buckling-to-imperfect nonlinear-capacity workflow. |
-| Interchange | Pure-Python SESAM formatted FEM record/document parsing, guarded round-trip writing, supported semantic import to `FEModel`, coordinate transforms, beam orientation, and SIF shell-stress reading by load case. |
-| Results | Result provenance, element and nodal stress recovery, selected recovery, reaction filtering, validation diagnostics, deterministic baselines, benchmarks, and generated qualification reports. |
-
-Implemented does not automatically mean qualified for every geometry or load
-regime. The live capability matrix is produced by
-`write_production_readiness_artifacts()` and the verification manifest.
-
-## Production scope
-
-The qualified target is thin flat or cylindrical shell structure, with beam
-stiffeners/girders represented through the documented coupling, inside the
-verified mesh, material, distortion, eccentricity, and load ranges.
-
-Important limits:
-
-- no arbitrary CAD topology or automatic general-purpose meshing;
-- Q8R is experimental: its hourglass stabilization is not qualified for thin
-  bending and it is deliberately excluded from nonlinear batch acceleration;
-- the 3-node quadratic beam is straight-sided; curved members must be
-  represented by straight beam segments until a true curved formulation is
-  implemented;
-- shell buckling uses the implemented membrane-resultant geometric stiffness,
-  not a complete finite-rotation shell geometric stiffness;
-- no follower-pressure load or tangent;
-- no general shell-shell, body-body, frictional, rolling, or self-contact;
-- no fluid-structure interaction, cavitation, or water-entry model;
-- no cohesive cracks, remeshing, material separation, or fracture-mechanics
-  claim—the erosion models are engineering screens;
-- no unrestricted deep post-buckling or automatic bifurcation branch switching;
-- no consistent frame-derivative tangent for the corotational formulation;
-- no general material-aware stress reconstruction when committed nonlinear
-  layer/fiber state is unavailable;
-- no true multi-stage plastic preload followed by displacement control;
-- no unverified material laws, residual-stress fields, or distortion ranges;
-- SESAM `FEModel` export and external-solver execution/comparison remain outside
-  the supported interchange gate.
-
-Use `validate_production_model()`, the analysis-specific preflight checks, and
-the generated production-scope artifacts before production use.
-
-## Documentation map
-
-- [`ARCHITECTURE.md`](docs/ARCHITECTURE.md): package boundaries, analysis flow, and
-  invariants.
-- [`THEORY.md`](docs/THEORY.md): implemented formulations and validity limits.
-- [`ARC_LENGTH.md`](docs/ARC_LENGTH.md): continuation controls and use.
-- [`NONLINEAR_PERFORMANCE.md`](docs/NONLINEAR_PERFORMANCE.md): nonlinear assembly,
-  sparse backend, threading, and diagnostics.
-- [`QUALITY_CONTROL.md`](docs/QUALITY_CONTROL.md): verification commands, evidence
-  hierarchy, and current checked status.
-- [`reference_cases/README.md`](docs/reference_cases/README.md):
-  local CalculiX/PrePoMax reference-case layout.
-- [`MIGRATION.md`](MIGRATION.md): source provenance, inclusion boundary, and
-  import changes.
-
-## Basic verification
-
-From the repository root:
-
-```powershell
-python -m pytest tests -q -p no:cacheprovider
-python run_qc.py --no-save
-python scripts/run_fe_verification.py
-```
-
-The last command regenerates the canonical JSON and Markdown evidence under
-`reports/verification/`. External-reference decks are handoff artifacts unless
-matching external-solver results have actually been executed and compared.
+| Initial fields | Element-local shell membrane/bending stress or membrane/curvature prestrain, arbitrary configured beam-fiber stress/prestrain distributions, zero-external-load equilibration, admissibility checks, and provenance kept separate from geometric imperfections. |
+| Workflows | Normalized generated geometry to static/prestress/buckling; traceable static-to-buckling-to-imperfect nonlinear-capacity workflow. |
+| Interchange | Pure-Python SESAM formatted FEM record/document parsing, guarded round-trip writing, supported semantic import to `FEModel`, coordinate transforms, beam orientation, and SIF shell-stress reading by load case. |
+| Results | Result provenance; unified elastic or committed shell-layer/beam-fiber stress recovery; guarded Zienkiewicz-Zhu-style patch recovery for qualified shell neighborhoods; selected recovery; reaction filtering; validation diagnostics; deterministic baselines; benchmarks; and generated qualification reports. |
+| External verification | Reproducible CalculiX input generation plus opt-in isolated execution, FRD/DAT parsing, solver provenance, and tolerance-controlled analytical comparison. Deck-only reports remain explicitly `not_executed` and make no numerical-agreement claim. |
+
+Implemented does not automatically mean qualified for every geometry or load
+regime. The live capability matrix is produced by
+`write_production_readiness_artifacts()` and the verification manifest.
+
+## Production scope
+
+The qualified target is thin flat or cylindrical shell structure, with beam
+stiffeners/girders represented through the documented coupling, inside the
+verified mesh, material, distortion, eccentricity, and load ranges.
+
+Important limits:
+
+- no arbitrary CAD topology or automatic general-purpose meshing;
+- Q8R is experimental: its hourglass stabilization is not qualified for thin
+  bending and it is deliberately excluded from nonlinear batch acceleration;
+- the 3-node quadratic beam is straight-sided; curved members must be
+  represented by straight beam segments until a true curved formulation is
+  implemented;
+- the shell initial-stress operator covers the in-plane `N`, `M`, and `H`
+  stress moments acting on Mindlin midsurface translations and director
+  gradients; it does not add drilling, transverse-normal-stress, or a
+  geometrically exact finite-rotation shell/director formulation;
+- current-area follower pressure is supported in nonlinear static and
+  arc-length analyses, with its exact load tangent. Linear/dead pressure
+  remains the default. Linear buckling rejects a constrained nonsymmetric
+  follower-pressure pencil because general complex nonconservative
+  eigenanalysis is not implemented;
+- no general shell-shell, body-body, frictional, rolling, or self-contact;
+- no fluid-structure interaction, cavitation, or water-entry model;
+- no cohesive cracks, remeshing, material separation, or fracture-mechanics
+  claim—the erosion models are engineering screens;
+- no unrestricted deep post-buckling or automatic bifurcation branch switching;
+- the consistent corotational tangent includes frame derivatives and is
+  selected automatically for follower pressure, but its numerical
+  frame-sensitivity evaluation is costlier than the rotated tangent used by
+  default for ordinary corotational solves;
+- material-history-aware recovery requires retained, matching committed
+  nonlinear layer/fiber states; missing or invalid state is reported and the
+  affected components fall back explicitly to elastic reconstruction;
+- the guarded patch-recovery fit is qualified only for locally planar,
+  consistently oriented, homogeneous, full-integration Q4 or Q8 shell
+  neighborhoods. Discontinuities remain separate, and the optional normalized
+  stress-L2 discrepancy is a diagnostic—not an energy-norm error estimate;
+- initial stress/prestrain fields are qualified only in element-local reference
+  coordinates with `kinematics="von_karman"`. Shell fields use the documented
+  membrane/positive-face-bending convention, and beam fields require a
+  configured fiber section. Input stress must be admissible for the supplied
+  hardening state; equilibration may redistribute it and does not reconstruct
+  the manufacturing history. A field-bearing restart also requires its
+  matching converged displacement vector;
+- the analytical plane-stress tangent is branch-consistent. The numerical
+  derivative remains an oracle and automatic invalid-row fallback; local
+  yield-residual nonconvergence fails closed;
+- no unverified material laws or distortion ranges;
+- SESAM `FEModel` export remains outside the supported interchange gate;
+- CalculiX comparison requires a compatible local executable and an explicit
+  execution request. Deck generation alone is a reproducibility handoff, not
+  external numerical evidence.
+
+Use `validate_production_model()`, the analysis-specific preflight checks, and
+the generated production-scope artifacts before production use.
+
+## Documentation map
+
+- [`ARCHITECTURE.md`](docs/ARCHITECTURE.md): package boundaries, analysis flow, and
+  invariants.
+- [`THEORY.md`](docs/THEORY.md): implemented formulations and validity limits.
+- [`ARC_LENGTH.md`](docs/ARC_LENGTH.md): continuation controls and use.
+- [`NONLINEAR_PERFORMANCE.md`](docs/NONLINEAR_PERFORMANCE.md): nonlinear assembly,
+  sparse backend, threading, and diagnostics.
+- [`QUALITY_CONTROL.md`](docs/QUALITY_CONTROL.md): verification commands, evidence
+  hierarchy, and current checked status.
+- [`reference_cases/README.md`](docs/reference_cases/README.md):
+  local CalculiX/PrePoMax reference-case layout.
+- [`MIGRATION.md`](MIGRATION.md): source provenance, inclusion boundary, and
+  import changes.
+
+## Basic verification
+
+From the repository root:
+
+```powershell
+python -m pytest tests -q -p no:cacheprovider
+python run_qc.py --no-save
+python scripts/run_fe_verification.py
+```
+
+The last command regenerates the canonical JSON and Markdown evidence under
+`reports/verification/`. Its default external-reference mode generates
+handoff decks with status `not_executed`; that status is not a pass or a claim
+of numerical agreement. To execute the comparisons, provide a compatible
+CalculiX executable on `PATH`, through `ANYSOLVER_CALCULIX_EXECUTABLE`, or with
+`--calculix`, and run:
+
+```powershell
+python scripts/run_fe_verification.py --execute-calculix
+```
+
+An external case becomes passing evidence only after isolated execution,
+successful FRD/DAT parsing, and every declared comparison meeting its
+tolerance.