ANYsolver 0.4.2__tar.gz → 0.4.5__tar.gz

anysolver-0.4.5/CHANGELOG.md

@@ -0,0 +1,250 @@
+# Changelog
+
+## Unreleased
+
+## 0.4.5 - 2026-09-16
+
+- Publish the bounded B3-GE opt-in release after correcting the isolated
+  installed-wheel gate to install the wheel's declared runtime dependencies.
+- Preserve the failed v0.4.4 GitHub publication attempt as process evidence;
+  no v0.4.4 artifacts reached PyPI.
+- Keep legacy B3 as the default and leave qualified Q4/S3 mechanics and
+  defaults unchanged.
+
+## 0.4.4 - 2026-09-16
+
+- Publish the accepted `B3-GE` model-owned geometrically exact beam workflow
+  as an explicit `b3-ge` opt-in. Legacy B3 remains the default for every
+  existing three-node beam route and historical record.
+- Bind the minor release to the accepted G7 production-opt-in evidence and a
+  bounded installed-wheel gate. Qualified Q4/S3 mechanics and defaults are
+  unchanged.
+- Remove unreferenced development notes from the active tree and exclude
+  research plans, raw evidence, tests, and build scripts from release source
+  archives. The complete pre-cleanup tree remains available at the archive tag
+  `archive/anysolver-pre-0.4.4-development-20260916`.
+
+## 0.4.3 - 2026-09-09
+
+- Add the explicitly selected `ge-beam3` straight mixed beam and the reviewed
+  `ge-beam3-native` model-owned straight/regular-curved beam workflows, with
+  declared generalized and physical-fibre sections, authenticated history,
+  recovery, restart, and admitted reference/current-rest spectral analysis.
+- Add the reviewed objective eccentric generalized-beam connection to one
+  owned elastic qualified Q4 or S3 V2D through the native workflow API.
+- Preserve the full development/qualification history and its scoped
+  independent acceptance. This is not qualification of generic mixed FEModel
+  routing, plastic/fibre-shell coupling, finite-velocity rotational dynamics,
+  arbitrary sections, or stable postbuckling paths from rest.
+- Keep existing B2/B3, qualified Q4/S3 mechanics and all defaults unchanged.
+  See `docs/GE_BEAM3_NATIVE_WORKFLOWS.md` for the supported API and limitations.
+- Separate the explicit current GE runtime CI inventory from preserved extended
+  experiments. Historical evidence and the unpublished qualification wheel
+  remain immutable; the versioned release wheel is verified separately.
+
+## 0.4.2 - 2026-09-03
+
+- Canonicalize solver-owned compact qualified-Q4 plastic state once at the
+  accepted Newton finalization boundary. Public sealing remains fail-closed,
+  while restart and subsequent current-tangent replay become byte-exact.
+- Preserve qualified Q4/S3 mechanics, coefficients, recovery, formulation
+  identities, and defaults.
+
+## 0.4.1 - 2026-09-03
+
+- Correct the coordinated ecosystem dependency bands to require ANYmaterial
+  0.2.x, ANYmesher 0.4.x, and ANYfileio 0.3.1 or newer. Version 0.4.0 carried the
+  pre-activation bands and cannot be resolved together with ANYfem 0.4.0.
+- Add a release gate that resolves the built wheel with the exact coordinated
+  sibling releases before trusted publication.
+- Admit only a fixed binary64 last-place envelope when scalar final-state
+  replay validates compact qualified-Q4 plastic states produced by vectorized
+  assembly. This fixes sealing after valid plastic increments while preserving
+  exact origin/configuration hashes, exact rich-state replay, and strict
+  rejection of material history differences. Qualified Q4/S3 mechanics and
+  formulation defaults are unchanged.
+
+## 0.4.0 - 2026-09-03
+
+- Relicense ANYsolver source releases from GPL-3.0-or-later to MPL-2.0.
+  Earlier published versions retain the licence terms that applied to them.
+- Publish a machine-readable direct-dependency licence inventory and preserve
+  third-party notices in source and wheel distributions. The extracted ANY
+  dependencies remain separately licensed and are not bundled or relicensed
+  by ANYsolver.
+- Add release-time checks for repository metadata, notices, dependency
+  inventory, and licence files in built distributions.
+- Document the qualified-S3 admission boundary for automatically imprinted
+  four-way shell intersections. These junctions continue to fail closed rather
+  than bypassing qualification or silently selecting legacy S3.
+- Activate the V6W-qualified native-parity S3 V2D companion as the default
+  three-node shell for new/current-policy models. Historical records without
+  formulation authority remain explicit `legacy-s3`, direct `ShellElement`
+  construction remains legacy, and qualified S3 creation fails closed without
+  an authoritative physical owner normal. Qualified Q4 mechanics are unchanged.
+- Mark the coordinated breaking activation boundary as ANYsolver 0.4.0 and
+  admit the compatible ANYmesher 0.3 line while retaining the strict 0.4 cap.
+
+- Add the explicitly selected `e4-pl-s3`/`qualified-s3` linear MITC3+
+  companion candidate with frozen source identity, two bubble rotations,
+  basis-invariant three-mode PL completion, stable serialization identity,
+  authoritative-normal admission, formulation-native local recovery, and
+  analytic nodal-plus-bubble mass with the frozen Guyan reduction. The modal
+  solver excludes exact zero-inertia drill coordinates without inventing mass,
+  using coordinate-invariant static condensation for bounded systems and a
+  fail-closed swapped descriptor pencil for larger systems. The candidate now
+  also supplies formulation-native total-Lagrangian layered response,
+  stateless generalized-section geometry with analytically integrated initial
+  stress resultants and generalized eigenstrains, contact virtual work,
+  committed recovery without fabricated layer data, physical-director
+  reversal, current-state modal/buckling operators, and solver-owned
+  static/arc-length checkpoints. The original candidate remained opt-in until
+  the independent V6W qualification and this successor activation boundary.
+- Keep qualified E4-PL as the production Q4 default and begin the explicit
+  legacy-Q4 retirement window. Legacy Q4 selectors now emit a dedicated
+  deprecation warning, diagnostics expose the selected formulation and
+  rollback lifecycle, and migration guidance freezes availability through
+  0.4.x with removal no earlier than 0.5.0 after two clean release gates.
+  TRI3, TRI6, Q8, and Q8R remain unchanged.
+
+## 0.3.0 - 2026-08-23
+
+- Preserve the corrected published-2025 S4 reference, nullspace proof, geometry
+  handoff, and qualification scaffold as dormant release evidence. The legacy
+  S4 remains the production default and improved-S4 activation remains
+  unavailable under the recorded restrictions; no gauge constraint, invented
+  stiffness, dispatch route, or activity-policy change is introduced.
+- Widen the declared ANYfileio consumer range to `>=0.1,<0.3`, add pinned
+  source compatibility cells for the 0.1 and 0.2 public contracts, and align
+  the publication dependency gate. Installed-wheel, index-resolver, and
+  publication qualification remain separate release gates.
+- Widen the declared ANYmesher consumer range to `>=0.1,<0.3`, add CI coverage
+  for pinned 0.1.0 and 0.2.1 endpoints, preserve the public neutral panel, mesh,
+  quality, and section contract, retain the strict 0.3 cap, and align CI and
+  publication dependency gates with the declared metadata.
+- Complete the Sol Ultra `performance_2` campaign with qualified static/arc
+  persistent nonlinear state transactions, compiled canonical-curve Hill-48 batches,
+  orthotropic/generalized S4 kernels, revision-cached corotational block
+  transforms, large-selection isotropic S4 recovery, and direct reduced
+  elastic nonlinear-impact assembly. Unsupported formulations, curves, state
+  layouts, impact plastic/fiber history, small recovery selections, affine
+  constraints, and damage/state scopes retain explicit scalar or
+  full-coordinate fallbacks with reason diagnostics.
+- Add conservative opt-in impact tangent/factorization reuse, compact lazy
+  contact records, and revision-guarded incremental damage K/M updates. A zero
+  reuse budget remains the full-Newton oracle; contact, convergence, plastic,
+  damage, deletion, time-step, and line-search changes force a refresh. Damage
+  plan setup is gated by projected future events and retained-memory headroom;
+  invalidation returns to the exact rebuild and never scales point masses.
+- Add the optional caller-owned `AnalysisSession` for bounded K/M/constraint,
+  reduced-matrix, output-row, and factorization reuse across repeated linear,
+  modal, buckling, transient, and capacity work. Linear transient loads are
+  preprojected once and selected history output avoids full-vector
+  reconstruction when recovery does not require it. Explicit solver,
+  assembly, and recovery thread scopes remain independently controlled and are
+  restored after each call.
+- Release 0.2.0 extraction boundary: material behavior now comes from
+  `ANYmaterial`, neutral geometry/meshing from `ANYmesher`, and SESAM/CalculiX
+  parsing and writing from `ANYfileio`. ANYsolver retains solver-specific
+  FEModel adapters, MPC elements, boundary interpretation, external execution,
+  comparisons, and the 0.2.x legacy import facades. Deterministic FE baselines
+  remain unchanged.
+- Add dependency-free generalized section contracts: pre-integrated shell
+  `A/B/D/As` with membrane-bending coupling and optional areal inertia, plus a
+  coupled beam 6x6 stiffness and optional mass-per-length law. Generated
+  geometry accepts inline or named definitions; recovery exposes exact
+  generalized strains/resultants, nonlinear shell acceleration falls back
+  deterministically, and unsupported CalculiX/fiber/plastic mappings fail
+  closed.
+- Add a dependency-free structural material contract and homogeneous
+  orthotropic engineering materials for shells and beams. This includes
+  projected shell material directions/angles, explicit orthotropic beam
+  torsional rigidity, generated-geometry and CalculiX shell interchange, and
+  deterministic fallback from isotropic accelerated kernels to general
+  assembly.
+- Add material-axis Hill-48 shell plasticity with directional-strength
+  hardening, consistent tangent plus numerical oracle/fallback, stored physical
+  stress recovery, labelled Hill equivalent stress/utilization, orthotropic
+  beam-fiber longitudinal yielding, and damage/contact integration. General
+  anisotropy, laminates, ply failure, and shear/torsion plastic interaction
+  remain outside scope.
+- Add an exact constant-stress analytical/CalculiX orthotropic S4 reference
+  deck, perfect-plastic Hill behavior when no hardening curve is supplied, and
+  current-strength Hill utilization with physical-stress recovery provenance.
+
+## 0.1.3 - 2026-07-28
+
+- Complete the generated-geometry runtime bridge: apply configured shear force
+  and torsional moment, pass current-area follower pressure only to supported
+  nonlinear static/arc-length paths, retain the selected corotational
+  kinematics in arc length, and fail closed for incompatible follower paths.
+  Runtime prestress recovery now consumes matching committed nonlinear
+  histories and exposes Gauss-point membrane/bending resultants plus recovery
+  provenance.
+- Correct nonlinear display recovery so plastic-history von Mises values use
+  only the return-mapped shell in-plane or beam-fiber components, while purely
+  elastic nonlinear states retain their full equivalent stress. Preserve
+  combinations with elastically reconstructed transverse shear/torsion as a
+  separately labelled model-scope diagnostic.
+- Add the public `resolve_runtime_analysis()` contract so application GUIs can
+  reflect normalized nonlinear/material/control/kinematics selections without
+  importing private runtime helpers.
+
+## 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.4.5/MANIFEST.in

@@ -0,0 +1,22 @@
+include LICENSE
+include COPYRIGHT
+include LICENSING.md
+include THIRD_PARTY_NOTICES.md
+include dependency-licenses.json
+include README.md
+include CHANGELOG.md
+include MIGRATION.md
+prune docs
+include docs/ARCHITECTURE.md
+include docs/ARC_LENGTH.md
+include docs/B3_GE_PRODUCTION_OPT_IN.md
+include docs/E4_PL_MIGRATION.md
+include docs/GE_BEAM3_NATIVE_WORKFLOWS.md
+include docs/NONLINEAR_PERFORMANCE.md
+include docs/PERFORMANCE_ARCHITECTURE.md
+include docs/QUALITY_CONTROL.md
+include docs/THEORY.md
+include docs/releases/ANYsolver_0.4.5.md
+prune reports
+prune scripts
+prune tests

anysolver-0.4.5/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: ANYsolver
+Version: 0.4.5
+Summary: Qualified beam and shell finite-element solver
+Author-email: Audun Arnesen Nyhus <audunarn@gmail.com>
+License-Expression: MPL-2.0
+Project-URL: Homepage, https://github.com/audunarn/ANYsolver
+Project-URL: Repository, https://github.com/audunarn/ANYsolver
+Project-URL: Issues, https://github.com/audunarn/ANYsolver/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: COPYRIGHT
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: threadpoolctl>=3.5
+Requires-Dist: ANYmaterial<0.3,>=0.2
+Requires-Dist: ANYmesher<0.5,>=0.4
+Requires-Dist: ANYfileio<0.4,>=0.3.1
+Provides-Extra: numba
+Requires-Dist: numba>=0.59; extra == "numba"
+Provides-Extra: pardiso
+Requires-Dist: pypardiso>=0.4; extra == "pardiso"
+Provides-Extra: accelerated
+Requires-Dist: numba>=0.59; extra == "accelerated"
+Requires-Dist: pypardiso>=0.4; extra == "accelerated"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mpmath==1.3.0; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# 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 across sibling repositories, install the
+checkouts first:
+
+```powershell
+python -m pip install -e C:\Github\ANYmaterial
+python -m pip install -e C:\Github\ANYmesh
+python -m pip install -e C:\Github\ANYfileIO
+python -m pip install -e C:\Github\ANYsolver
+```
+
+### Release order for the 0.4 line
+
+ANYsolver 0.4 depends on compatible extracted packages. Publish them to the
+same target index in this order:
+
+1. `ANYmaterial` and `ANYmesher` (either order).
+2. `ANYfileio`, which depends on both.
+3. `ANYsolver` 0.4.x, which depends on all three.
+
+Apply that order separately to TestPyPI and PyPI. The compatible sibling
+releases are available on PyPI. The publish workflow checks the selected
+target index and refuses to build or upload ANYsolver unless
+`ANYmaterial>=0.1,<0.2`, `ANYmesher>=0.1,<0.4`, and
+`ANYfileio>=0.1,<0.3` can already be resolved there. CI also uses pinned sibling
+source checkouts to exercise the exact compatibility graph.
+
+ANYsolver uses the neutral mesh, panel-generation, quality, and section APIs
+available in ANYmesher 0.1 and retains compatibility through the additive 0.3
+line. The strict `<0.4` cap prevents an unqualified major contract change.
+The endpoint compatibility job exercises pinned 0.1.0 and 0.2.1 installed
+wheels on Windows AMD64 CPython 3.13; that focused job is not a wider platform
+or interpreter qualification claim.
+
+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,
+    resolve_runtime_analysis,
+    run_production_fem,
+)
+```
+
+The runtime facade applies its normalized axial force, bending moment, shear
+force, torsional moment, and pressure inputs to the generated model. Set
+`LightweightFEMConfig.follower_pressure=True` only for nonlinear static or
+arc-length analysis using the `static only` or `nonlinear static` runtime
+path; incompatible linear, stepwise eigenvalue-buckling, transient, collision,
+and structured-capacity paths return an explicit `invalid_follower_pressure`
+status. Arc length retains the requested von Karman or corotational
+kinematics. Production runtime failures remain failures rather than being
+replaced by an estimator.
+
+Application integrations should use `resolve_runtime_analysis(config)` to
+reflect the solver's effective nonlinear/material/control/kinematics choices;
+the normalization helpers with leading underscores are implementation details.
+
+The generic `GeneratedGeometryFEM*` names are the preferred workflow API.
+Historical `AnyStructureFEM*` aliases remain available only for downstream
+compatibility. Material selection is owned by `ANYmaterial`; the root-level
+`dnv_c208_steel_properties()` and `dnv_c208_steel_curve()` names are temporary
+compatibility imports over its 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
+
+Production four-node shell selectors use the qualified E4-PL formulation by
+default. New/current-policy three-node shell selectors use the independently
+qualified E4-PL S3 V2D companion; historical S3 records without formulation
+authority remain explicit legacy. TRI6, Q8, and Q8R remain on their established
+implementations.
+
+Qualified S3 admission intentionally fails closed where a triangle touches a
+shell edge with more than two incident elements. Automatically imprinted
+four-way sheet intersections therefore require junction-aware meshing support
+or an explicit model-level legacy-S3 rollback; the mesher never silently
+changes the formulation.
+The explicit legacy-Q4 rollback is deprecated during the 0.4.x burn-in and is
+scheduled for removal no earlier than 0.5.0; see
+[the E4-PL migration guide](docs/E4_PL_MIGRATION.md) for diagnostics, rollback,
+and release gates.
+
+| Area | Implemented functionality |
+| --- | --- |
+| Model | Six DOFs per node; SI units; materials, density, nodal mass, shell/beam topology, supports, and MPC constraints. `audit_constraints()` reports equation provenance, feasibility, structural rank, dependency depth, and independent DOFs before assembly. |
+| Materials | Constitutive objects, elastic reductions, Hill-48 yield data, and DNV curves come from `ANYmaterial`; ANYsolver owns their use in element integration and nonlinear solution. Orthotropic shells support material direction/angle and Hill-48 plasticity; orthotropic beams use local material axes and an explicit section torsional rigidity. |
+| Shells | 3- and 6-node triangles; 4-node MITC-style and 8-node Mindlin-Reissner quadrilaterals; isotropic, rotated orthotropic, or pre-integrated generalized `A/B/D/As` section stiffness. Generalized sections retain membrane-bending coupling and recover exact strains/resultants without inventing ply stresses. |
+| Beams | 2-node and straight-sided 3-node Timoshenko beams with axial, biaxial bending, direction-dependent shear, torsion, consistent/lumped mass options, geometric stiffness, optional fiber-section plasticity, or a fully coupled local 6x6 generalized section law. |
+| 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, sparse factorization reuse, and post-solve affine-constraint residual checks. |
+| 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 or orthotropic Hill-48 plasticity with safeguarded local solves and consistent tangents, 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 | `ANYfileio` owns SESAM/CalculiX parsing, validation, neutral semantics, and guarded writing. ANYsolver retains only neutral-record-to-`FEModel` adapters and the legacy compatibility imports introduced for the 0.2 line. |
+| Results | Result provenance; unified elastic or committed shell-layer/beam-fiber stress recovery; Gauss-point membrane-force and bending-moment resultants for generated-geometry prestress; 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 model flattening, opt-in isolated execution, solver provenance, and tolerance-controlled analytical comparison, using `ANYfileio` for deck writing and FRD/DAT parsing. Deck-only reports remain explicitly `not_executed` and make no numerical-agreement claim. |
+
+`StructuralMaterial` is a runtime-checkable, ANYmaterial-owned protocol containing
+`name`, `density`, `elastic_symmetry`, and
+`elastic_compliance_matrix()` in engineering Voigt order
+`[11, 22, 33, 23, 13, 12]`. `FEModel.register_material()` accepts compatible
+external objects through that contract;
+`FEModel.add_orthotropic_material()` constructs the canonical
+`OrthotropicMaterial`.
+
+ANYmesher owns neutral mesh topology, numbering, quality and coupling records;
+this package converts them into solver elements and exact constraints.
+ANYfileio owns SESAM and CalculiX syntax; this package converts neutral records
+to FEModel objects and retains execution and validation evidence.
+
+Every production solver uses the same fixed/MPC preflight. Invalid or cyclic
+systems fail before assembly or factorization. Linear, modal, buckling,
+nonlinear, arc-length, transient, and impact results include a normalized
+constraint residual diagnostic. Modal and buckling modes correctly verify the
+homogeneous variation equations when the base model has prescribed offsets.
+
+`ResourceConfig(solver_threads=N, assembly_threads=M)` now applies scoped
+native and Numba limits. Native pools are restored even after exceptions, and
+parallel Numba assembly suppresses nested BLAS/OpenMP pools to one thread.
+Diagnostics record requested limits, active runtime pools, the selected sparse
+backend, and any limiter/backend fallback. Omitting the resource policy retains
+the backend's existing unrestricted default.
+
+Applications that expect a large qualified-Q4 nonlinear analysis can move the
+first-use JIT cost out of the interactive solve path with an explicit warm-up:
+
+```python
+from anysolver import warm_fe_solver_kernels
+
+warm_fe_solver_kernels(include_nonlinear_static=True)
+```
+
+This opt-in helper builds and discards a small 4x4 Q4 batch solely to prepare
+the existing native kernel. It does not change the application model, material
+state, element mechanics, or normal solver behavior.
+
+`GeneralizedShellSectionProtocol` and `GeneralizedBeamSectionContract` are
+likewise solver-owned structural interfaces. The built-in
+`GeneralizedShellSection(A, B, D, As, ...)` accepts pre-integrated laminate or
+homogenized shell stiffness, while `GeneralizedBeamSection(stiffness, ...)`
+accepts a coupled 6x6 sectional law. They may be attached directly to elements
+or supplied inline/by name through generated geometry. Optional section mass
+data override the legacy homogeneous mass construction; otherwise the attached
+material, thickness, and legacy section geometry continue to define mass.
+
+For shells, `material_direction` is projected into the shell plane and then
+`material_angle_deg` is applied right-handed about the positive shell normal;
+without a direction, the angle starts at shell-local x. For beams, material
+axes 1/2/3 are beam-local x/y/z. Orthotropic beam sections must provide a
+positive `cross_section["torsional_rigidity"]` in N*m^2; isotropic beams retain
+`G*J`.
+
+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;
+- no arbitrary 3-D anisotropic material law, ply-stack integration, ply stress
+  recovery, tension/compression-asymmetric composite failure, or progressive
+  composite damage. Pre-integrated linear shell `A/B/D/As` and beam 6x6
+  section laws are supported, including their elastic couplings;
+- 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;
+- for legacy isotropic plastic histories, `von_mises` retains the established
+  return-mapped shell in-plane or beam-fiber scope. Orthotropic results keep
+  `von_mises` as the conventional invariant of the physical stress, including
+  matching elastic transverse shear/torsion reconstruction, while
+  `equivalent_stress` and `hill_utilization` remain explicitly scoped to the
+  Hill-return-mapped components. `mixed_reconstruction_von_mises` and recovery
+  provenance identify that mixed constitutive scope;
+- 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;
+- orthotropic and generalized-section shells use the general
+  element/nonlinear paths and report deterministic fallback diagnostics;
+  generalized beams use the general element path, while the existing
+  accelerated shell kernels remain isotropic homogeneous-section only;
+- generalized-section recovery is resultants-only. CalculiX export rejects
+  these sections because the current deck mapping cannot preserve their
+  coupling; use analytical or a dedicated section-capable reference model;
+- 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.
+- [`extract_mat_mesh_io_performance_review.md`](reports/extract_mat_mesh_io_performance_review.md):
+  current extraction, assembly, nonlinear, MPC and buckling performance evidence.
+## 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.
+
+## License
+
+Starting with version 0.4.0, this project is licensed under the Mozilla Public
+License 2.0. See [LICENSE](LICENSE) for the full terms and
+[LICENSING.md](LICENSING.md) for the transition and third-party scope.
+
+Earlier published versions remain available under the licence terms that
+applied to those versions.