ANYsolver 0.1.0__py3-none-any.whl

anysolver/imperfections.py

@@ -0,0 +1,390 @@
+"""Rule-aware geometric imperfection helpers for nonlinear capacity checks.
+
+Imperfections are represented as stress-free reference-geometry offsets.  In
+other words, applying an imperfection modifies nodal coordinates before the
+nonlinear solve; zero displacement in the imperfect model has zero strain and
+zero internal force.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, Mapping, Optional, Sequence, Tuple
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from .buckling import BucklingResult
+    from .fe_core import FEModel
+    from .nonlinear_static import NonlinearStaticResult
+
+
+def _unit(vector: Sequence[float], fallback: Sequence[float] = (0.0, 0.0, 1.0)) -> np.ndarray:
+    value = np.asarray(vector, dtype=float).reshape(-1)
+    if value.size < 3:
+        padded = np.zeros(3, dtype=float)
+        padded[: value.size] = value
+        value = padded
+    norm = float(np.linalg.norm(value[:3]))
+    if norm <= 1.0e-14:
+        return _unit(fallback)
+    return value[:3] / norm
+
+
+def _node_coords(model: "FEModel", node_ids: Iterable[int]) -> Dict[int, np.ndarray]:
+    coords: Dict[int, np.ndarray] = {}
+    for node_id in node_ids:
+        node = model.mesh.get_node(int(node_id))
+        if node is None:
+            raise ValueError(f"Node {node_id} not found")
+        coords[int(node_id)] = node.coords()
+    return coords
+
+
+def _invalidate_element_caches(model: "FEModel") -> None:
+    for element in model.mesh.elements.values():
+        for name in (
+            "_stiffness_matrix",
+            "_mass_matrix",
+            "_internal_forces",
+            "_nl_cache",
+            "_hourglass_stiffness_matrix",
+        ):
+            if hasattr(element, name):
+                setattr(element, name, None)
+    if hasattr(model.mesh, "_sparsity_cache"):
+        model.mesh._sparsity_cache = {}
+
+
+@dataclass(frozen=True)
+class ImperfectionField:
+    """Nodal reference-coordinate offsets in metres."""
+
+    offsets: Mapping[int, Sequence[float]]
+    name: str = "imperfection"
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def as_arrays(self) -> Dict[int, np.ndarray]:
+        result: Dict[int, np.ndarray] = {}
+        for node_id, offset in self.offsets.items():
+            vector = np.asarray(offset, dtype=float).reshape(-1)
+            if vector.size < 3:
+                padded = np.zeros(3, dtype=float)
+                padded[: vector.size] = vector
+                vector = padded
+            result[int(node_id)] = vector[:3].copy()
+        return result
+
+    @property
+    def max_offset(self) -> float:
+        return max((float(np.linalg.norm(offset)) for offset in self.as_arrays().values()), default=0.0)
+
+    def combine(self, *others: "ImperfectionField", name: Optional[str] = None) -> "ImperfectionField":
+        offsets = self.as_arrays()
+        metadata: Dict[str, Any] = {"components": [self.name]}
+        for other in others:
+            metadata["components"].append(other.name)
+            for node_id, offset in other.as_arrays().items():
+                offsets[node_id] = offsets.get(node_id, np.zeros(3, dtype=float)) + offset
+        return ImperfectionField(offsets, name=name or "+".join(metadata["components"]), metadata=metadata)
+
+
+@dataclass(frozen=True)
+class CompositeImperfection:
+    """Combination of local/global imperfection fields."""
+
+    components: Sequence[Any]
+    name: str = "composite_imperfection"
+
+    def to_field(self, model: "FEModel") -> ImperfectionField:
+        fields = [to_imperfection_field(model, component) for component in self.components]
+        if not fields:
+            return ImperfectionField({}, name=self.name)
+        return fields[0].combine(*fields[1:], name=self.name)
+
+
+@dataclass(frozen=True)
+class EigenmodeImperfection:
+    """Imperfection scaled from a linear buckling mode."""
+
+    buckling_result: "BucklingResult"
+    mode_number: int = 1
+    amplitude: float = 0.0
+    dof_filter: str = "translations"
+    name: str = "eigenmode_imperfection"
+
+    def to_field(self, model: "FEModel") -> ImperfectionField:
+        return imperfection_from_buckling_mode(
+            model,
+            self.buckling_result,
+            self.mode_number,
+            self.amplitude,
+            dof_filter=self.dof_filter,
+            name=self.name,
+        )
+
+
+@dataclass(frozen=True)
+class StandardImperfection:
+    """Deterministic DNV-style imperfection pattern."""
+
+    kind: str
+    node_ids: Sequence[int]
+    amplitude: Optional[float] = None
+    direction: Sequence[float] = (0.0, 0.0, 1.0)
+    axes: Sequence[int] = (0, 1)
+    waves: Tuple[int, int] = (1, 1)
+    name: str = "standard_imperfection"
+
+    def to_field(self, model: "FEModel") -> ImperfectionField:
+        kind = self.kind.lower()
+        if kind in {"member_bow", "bow"}:
+            return standard_member_bow(model, self.node_ids, self.amplitude, self.direction, name=self.name)
+        if kind in {"plate_mode", "plate_half_wave", "plate"}:
+            return standard_plate_mode(model, self.node_ids, self.amplitude, self.direction, self.axes, self.waves, name=self.name)
+        if kind in {"flange_twist", "twist"}:
+            return standard_flange_twist(model, self.node_ids, self.amplitude if self.amplitude is not None else 0.02, self.direction, name=self.name)
+        raise ValueError(f"Unknown standard imperfection kind {self.kind!r}")
+
+
+@dataclass(frozen=True)
+class ImperfectionCalibrationResult:
+    """Result from binary-search equivalent imperfection calibration."""
+
+    amplitude: float
+    capacity: float
+    iterations: int
+    converged: bool
+    history: Tuple[Dict[str, float], ...]
+    result: Optional["NonlinearStaticResult"] = None
+
+
+def to_imperfection_field(model: "FEModel", imperfection: Any) -> ImperfectionField:
+    if imperfection is None:
+        return ImperfectionField({})
+    if isinstance(imperfection, ImperfectionField):
+        return imperfection
+    converter = getattr(imperfection, "to_field", None)
+    if converter is not None:
+        return converter(model)
+    if isinstance(imperfection, Mapping):
+        return ImperfectionField(imperfection)
+    raise TypeError(f"Cannot convert {type(imperfection).__name__} to ImperfectionField")
+
+
+def apply_imperfection(model: "FEModel", imperfection: Any, copy_model: bool = True) -> "FEModel":
+    """Apply a stress-free geometric imperfection to a model."""
+    target = copy.deepcopy(model) if copy_model else model
+    field = to_imperfection_field(target, imperfection)
+    for node_id, offset in field.as_arrays().items():
+        node = target.mesh.get_node(node_id)
+        if node is None:
+            raise ValueError(f"Imperfection references missing node {node_id}")
+        node.x += float(offset[0])
+        node.y += float(offset[1])
+        node.z += float(offset[2])
+    if hasattr(target, "bump_revision"):
+        target.bump_revision("geometry")
+    else:
+        _invalidate_element_caches(target)
+    if not hasattr(target, "imperfection_metadata"):
+        target.imperfection_metadata = []
+    target.imperfection_metadata.append(
+        {"name": field.name, "max_offset": field.max_offset, "metadata": dict(field.metadata)}
+    )
+    return target
+
+
+def imperfection_from_buckling_mode(
+    model: "FEModel",
+    buckling_result: "BucklingResult",
+    mode_number: int,
+    amplitude: float,
+    dof_filter: str = "translations",
+    name: str = "eigenmode_imperfection",
+) -> ImperfectionField:
+    """Scale a buckling mode so the maximum nodal offset equals amplitude."""
+    mode = next((item for item in buckling_result.modes if int(item.mode_number) == int(mode_number)), None)
+    if mode is None:
+        raise ValueError(f"Buckling mode {mode_number} not available")
+    shape = np.asarray(mode.mode_shape, dtype=float).reshape(-1)
+    offsets: Dict[int, np.ndarray] = {}
+    filter_name = dof_filter.lower()
+    for node_id, node in model.mesh.nodes.items():
+        if filter_name in {"translations", "translation", "xyz"}:
+            vector = shape[node.dofs[:3]]
+        elif filter_name in {"z", "uz", "out_of_plane"}:
+            vector = np.array([0.0, 0.0, shape[node.dofs[2]]], dtype=float)
+        else:
+            raise ValueError("dof_filter must be 'translations' or 'out_of_plane'")
+        offsets[int(node_id)] = np.asarray(vector, dtype=float)
+    max_norm = max((float(np.linalg.norm(value)) for value in offsets.values()), default=0.0)
+    if max_norm <= 0.0:
+        raise ValueError("Selected buckling mode has zero translational amplitude")
+    scale = float(amplitude) / max_norm
+    return ImperfectionField(
+        {node_id: scale * value for node_id, value in offsets.items()},
+        name=name,
+        metadata={"source": "buckling_mode", "mode_number": int(mode_number), "amplitude": float(amplitude)},
+    )
+
+
+def standard_member_bow(
+    model: "FEModel",
+    member_nodes: Sequence[int],
+    amplitude: Optional[float] = None,
+    direction: Sequence[float] = (0.0, 0.0, 1.0),
+    name: str = "member_bow",
+) -> ImperfectionField:
+    """Half-sine member bow, defaulting to DNV-style L/300 amplitude."""
+    coords = _node_coords(model, member_nodes)
+    ordered_ids = list(coords)
+    start = coords[ordered_ids[0]]
+    end = coords[ordered_ids[-1]]
+    axis = end - start
+    length = float(np.linalg.norm(axis))
+    if length <= 0.0:
+        raise ValueError("member_nodes must span a non-zero length")
+    axis /= length
+    direction_vector = _unit(direction)
+    direction_vector = direction_vector - float(direction_vector @ axis) * axis
+    if float(np.linalg.norm(direction_vector)) <= 1.0e-14:
+        # Choose the Cartesian axis least aligned with the member, then
+        # project it into the transverse plane.
+        basis = np.eye(3, dtype=float)[int(np.argmin(np.abs(axis)))]
+        direction_vector = basis - float(basis @ axis) * axis
+    direction_vector /= float(np.linalg.norm(direction_vector))
+    amp = float(length / 300.0 if amplitude is None else amplitude)
+    offsets: Dict[int, np.ndarray] = {}
+    for node_id, coord in coords.items():
+        s = float((coord - start) @ axis) / length
+        offsets[node_id] = amp * np.sin(np.pi * np.clip(s, 0.0, 1.0)) * direction_vector
+    return ImperfectionField(offsets, name=name, metadata={"kind": "member_bow", "amplitude": amp, "length": length})
+
+
+def _node_ids_from_region(model: "FEModel", shell_region: Sequence[int]) -> Tuple[int, ...]:
+    node_ids = set()
+    for item_id in shell_region:
+        element = model.mesh.get_element(int(item_id))
+        if element is not None and hasattr(element, "node_ids"):
+            node_ids.update(int(node_id) for node_id in element.node_ids)
+        elif model.mesh.get_node(int(item_id)) is not None:
+            node_ids.add(int(item_id))
+        else:
+            raise ValueError(f"Region id {item_id} is neither a node nor an element")
+    return tuple(sorted(node_ids))
+
+
+def standard_plate_mode(
+    model: "FEModel",
+    shell_region: Sequence[int],
+    amplitude: Optional[float] = None,
+    direction: Sequence[float] = (0.0, 0.0, 1.0),
+    axes: Sequence[int] = (0, 1),
+    waves: Tuple[int, int] = (1, 1),
+    name: str = "plate_mode",
+) -> ImperfectionField:
+    """Sinusoidal plate imperfection, defaulting to s/200 amplitude."""
+    node_ids = _node_ids_from_region(model, shell_region)
+    coords = _node_coords(model, node_ids)
+    ax0, ax1 = int(axes[0]), int(axes[1])
+    values = np.asarray([coord for coord in coords.values()], dtype=float)
+    lo = values[:, [ax0, ax1]].min(axis=0)
+    hi = values[:, [ax0, ax1]].max(axis=0)
+    spans = np.maximum(hi - lo, 1.0e-14)
+    amp = float(min(spans) / 200.0 if amplitude is None else amplitude)
+    direction_vector = _unit(direction)
+    wx, wy = int(waves[0]), int(waves[1])
+    offsets: Dict[int, np.ndarray] = {}
+    for node_id, coord in coords.items():
+        sx = (coord[ax0] - lo[0]) / spans[0]
+        sy = (coord[ax1] - lo[1]) / spans[1]
+        shape = np.sin(wx * np.pi * sx) * np.sin(wy * np.pi * sy)
+        offsets[node_id] = amp * shape * direction_vector
+    return ImperfectionField(offsets, name=name, metadata={"kind": "plate_mode", "amplitude": amp, "waves": (wx, wy)})
+
+
+def standard_flange_twist(
+    model: "FEModel",
+    node_ids: Sequence[int],
+    twist_radians: float = 0.02,
+    direction: Sequence[float] = (0.0, 0.0, 1.0),
+    name: str = "flange_twist",
+) -> ImperfectionField:
+    """Small rigid twist ``delta x = theta x r`` about ``direction``.
+
+    ``direction`` is the twist axis.  The default angle is 0.02 rad.
+    """
+    coords = _node_coords(model, node_ids)
+    values = np.asarray(list(coords.values()), dtype=float)
+    if values.size == 0:
+        return ImperfectionField({}, name=name)
+    centroid = values.mean(axis=0)
+    twist_axis = _unit(direction)
+    offsets = {
+        node_id: float(twist_radians) * np.cross(twist_axis, coord - centroid)
+        for node_id, coord in coords.items()
+    }
+    return ImperfectionField(
+        offsets,
+        name=name,
+        metadata={
+            "kind": "flange_twist",
+            "twist_radians": float(twist_radians),
+            "twist_axis": twist_axis.tolist(),
+        },
+    )
+
+
+def calibrate_imperfection_amplitude(
+    model_builder: Callable[[], "FEModel"],
+    target_capacity: float,
+    imperfection_builder: Callable[[float], Any],
+    load_program: Any,
+    bracket: Tuple[float, float],
+    tolerance: float = 0.02,
+    max_iterations: int = 20,
+    solver_kwargs: Optional[Mapping[str, Any]] = None,
+) -> ImperfectionCalibrationResult:
+    """Binary-search an equivalent imperfection amplitude for target capacity."""
+    from .nonlinear_static import solve_static_nonlinear
+
+    lo, hi = float(bracket[0]), float(bracket[1])
+    if lo < 0.0 or hi <= lo:
+        raise ValueError("bracket must satisfy 0 <= low < high")
+    kwargs = dict(solver_kwargs or {})
+    history = []
+    best_result = None
+    best_amp = hi
+    best_capacity = float("nan")
+    converged = False
+    for iteration in range(1, max_iterations + 1):
+        amp = 0.5 * (lo + hi)
+        model = apply_imperfection(model_builder(), imperfection_builder(amp), copy_model=False)
+        if hasattr(load_program, "stages"):
+            result = solve_static_nonlinear(model, load_program=load_program, **kwargs)
+        else:
+            result = solve_static_nonlinear(model, load_case=load_program, **kwargs)
+        capacity = float(getattr(result, "peak_load_factor", result.capacity_estimate))
+        history.append({"iteration": float(iteration), "amplitude": amp, "capacity": capacity})
+        best_result = result
+        best_amp = amp
+        best_capacity = capacity
+        rel_error = abs(capacity - float(target_capacity)) / max(abs(float(target_capacity)), 1.0)
+        if rel_error <= tolerance:
+            converged = True
+            break
+        # Larger imperfections normally reduce buckling capacity.
+        if capacity > target_capacity:
+            lo = amp
+        else:
+            hi = amp
+    return ImperfectionCalibrationResult(
+        amplitude=best_amp,
+        capacity=best_capacity,
+        iterations=len(history),
+        converged=converged,
+        history=tuple(history),
+        result=best_result,
+    )

anysolver/jit_compiler.py

@@ -0,0 +1,108 @@
+"""Centralized Numba JIT compilation helper with PyInstaller fallback.
+
+This module exports ``njit`` and ``jit`` decorators.  If Numba is installed and
+the application is not running in a frozen PyInstaller state, it uses Numba's
+JIT.  Otherwise it falls back to a zero-overhead pass-through decorator.
+
+``JIT_ENABLED`` and ``JIT_BACKEND`` are public diagnostics.  Performance tests
+must only enforce compiled-kernel timing expectations when ``JIT_ENABLED`` is
+true; correctness tests continue to run with the Python fallback.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _passthrough_decorator(*args: Any, **kwargs: Any) -> Callable[[F], F]:
+    """Return the decorated function unchanged when Numba is unavailable."""
+
+    def decorator(func: F) -> F:
+        return func
+
+    if len(args) == 1 and callable(args[0]) and not kwargs:
+        return args[0]
+    return decorator
+
+
+_use_numba = False
+_numba_import_error: str | None = None
+if not getattr(sys, "frozen", False):
+    try:
+        from numba import jit as _jit
+        from numba import njit as _njit
+        from numba import get_num_threads as _numba_get_num_threads
+        from numba import prange as _numba_prange
+        from numba import set_num_threads as _numba_set_num_threads
+
+        _use_numba = True
+    except ImportError as exc:
+        _numba_import_error = str(exc)
+
+if _use_numba:
+    njit = _njit
+    jit = _jit
+    prange = _numba_prange
+else:
+    njit = _passthrough_decorator
+    jit = _passthrough_decorator
+    prange = range
+
+JIT_ENABLED: bool = bool(_use_numba)
+JIT_BACKEND: str = "numba" if JIT_ENABLED else "python"
+JIT_DISABLED_REASON: str | None
+if JIT_ENABLED:
+    JIT_DISABLED_REASON = None
+elif getattr(sys, "frozen", False):
+    JIT_DISABLED_REASON = "frozen_application"
+elif _numba_import_error:
+    JIT_DISABLED_REASON = f"numba_import_failed: {_numba_import_error}"
+else:
+    JIT_DISABLED_REASON = "numba_not_installed"
+
+
+def jit_diagnostics() -> dict[str, Any]:
+    """Return the active kernel backend and fallback reason."""
+    thread_count = None
+    requested_threads = os.environ.get("FE_SOLVER_NUMBA_THREADS")
+    if JIT_ENABLED:
+        try:
+            thread_count = int(_numba_get_num_threads())
+        except Exception:
+            thread_count = None
+    return {
+        "enabled": JIT_ENABLED,
+        "backend": JIT_BACKEND,
+        "disabled_reason": JIT_DISABLED_REASON,
+        "frozen": bool(getattr(sys, "frozen", False)),
+        "num_threads": thread_count,
+        "requested_threads_env": requested_threads,
+    }
+
+
+def set_numba_threads(thread_count: int | None) -> int | None:
+    """Set the active Numba worker count and return the previous count."""
+    if not JIT_ENABLED or thread_count is None:
+        return None
+    value = int(thread_count)
+    if value <= 0:
+        raise ValueError("Numba thread count must be positive")
+    previous = int(_numba_get_num_threads())
+    _numba_set_num_threads(value)
+    return previous
+
+
+@contextlib.contextmanager
+def numba_thread_scope(thread_count: int | None):
+    """Temporarily set Numba threads for one solver phase."""
+    previous = set_numba_threads(thread_count)
+    try:
+        yield
+    finally:
+        if previous is not None:
+            _numba_set_num_threads(previous)

anysolver/kernel_warmup.py

@@ -0,0 +1,180 @@
+"""Optional runtime warmup for FE solver compiled kernels."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Iterable, Tuple
+
+from scipy import sparse
+
+from .jit_compiler import JIT_DISABLED_REASON, JIT_ENABLED, jit_diagnostics
+from .matrix_assembly import assemble_mass_matrix, assemble_stiffness_matrix
+from .mesh_gen import generate_simple_panel_mesh
+
+
+def _normalize_shell_order(shell_order: str) -> str:
+    order = str(shell_order).strip().upper()
+    aliases = {"S8": "Q8", "S8R": "Q8R"}
+    return aliases.get(order, order)
+
+
+def _warmup_model(shell_order: str):
+    order = _normalize_shell_order(shell_order)
+    if order == "S4":
+        model = generate_simple_panel_mesh(1.0, 0.75, 0.01, num_divisions_x=1, num_divisions_y=1)
+    elif order in {"Q8", "Q8R"}:
+        model = generate_simple_panel_mesh(
+            1.0,
+            0.75,
+            0.01,
+            num_divisions_x=1,
+            num_divisions_y=1,
+            use_8node_elements=True,
+        )
+        if order == "Q8R":
+            for element in model.mesh.elements.values():
+                if getattr(element, "_is_8node", False):
+                    element.reduced_integration = True
+    else:
+        raise ValueError(f"Unsupported shell order for warmup: {shell_order!r}")
+    return model
+
+
+def _matrix_difference_norm(left: sparse.spmatrix, right: sparse.spmatrix) -> float:
+    denominator = max(float(sparse.linalg.norm(left)), 1.0)
+    return float(sparse.linalg.norm(left - right) / denominator)
+
+
+def _warm_nonlinear_impact_kernel() -> Dict[str, Any]:
+    """Touch the material-nonlinear impact path without running a real case."""
+
+    import numpy as np
+
+    from .boundary import BoundaryCondition
+    from .contact import (
+        NonlinearTransientConfig,
+        RigidSphereImpact,
+        SphereContactConfig,
+        solve_transient_sphere_impact,
+    )
+    from .dynamics import TransientConfig
+    from .elements import ShellElement
+    from .fe_core import FEModel
+    from .fracture import PlasticImpactDamageConfig
+    from .material_curves import DNVC208MaterialCurve
+
+    model = FEModel("kernel_warmup_nonlinear_impact")
+    model.add_material("soft", 1.0e5, 0.3, density=20.0)
+    model.materials["soft"].hardening_curve = DNVC208MaterialCurve(
+        sigma_prop=800.0,
+        sigma_yield=1000.0,
+        sigma_yield_2=1200.0,
+        eps_p_y1=1.0e-5,
+        eps_p_y2=1.0e-3,
+        K=2000.0,
+        n=0.1,
+    )
+    for node_id, xyz in {
+        1: (0.0, 0.0, 0.0),
+        2: (1.0, 0.0, 0.0),
+        3: (1.0, 1.0, 0.0),
+        4: (0.0, 1.0, 0.0),
+    }.items():
+        model.add_node(node_id, *xyz)
+    model.add_element(1, ShellElement(1, [1, 2, 3, 4], "soft", thickness=0.05))
+    model.add_boundary_condition(
+        BoundaryCondition(
+            "warmup_restrain",
+            [1, 2, 3, 4],
+            {"ux": 0.0, "uy": 0.0, "rx": 0.0, "ry": 0.0, "rz": 0.0},
+        )
+    )
+
+    start = time.perf_counter()
+    result = solve_transient_sphere_impact(
+        model,
+        TransientConfig(dt=0.01, t_end=0.01),
+        RigidSphereImpact(
+            "warmup",
+            radius=0.2,
+            mass=5.0,
+            start_point=(0.5, 0.5, 0.25),
+            travel_direction=(0.0, 0.0, -1.0),
+            speed=1.0,
+        ),
+        SphereContactConfig(penalty_stiffness=500.0, max_contact_iterations=8),
+        nonlinear_config=NonlinearTransientConfig(enabled=True, max_iterations=6, max_cutbacks=1),
+        plastic_damage_config=PlasticImpactDamageConfig(threshold=0.01, max_deleted_fraction=1.0),
+    )
+    elapsed = time.perf_counter() - start
+    return {
+        "status": str(result.status),
+        "seconds": float(elapsed),
+        "method": str(result.diagnostics.get("method", "")),
+        "stiffness_assembly_skipped": bool((result.diagnostics.get("stiffness") or {}).get("assembly_skipped", False)),
+        "strain_summary_available": "strain_summary" in result.diagnostics,
+        "num_saved_steps": int(len(result.times)),
+    }
+
+
+def warm_fe_solver_kernels(
+    shell_orders: Iterable[str] = ("S4", "Q8", "Q8R"),
+    *,
+    include_nonlinear_impact: bool = False,
+) -> Dict[str, Any]:
+    """Warm representative FE kernels and return timing/correctness diagnostics.
+
+    The helper is intentionally optional and side-effect free apart from Numba's
+    normal in-process/disk cache behavior.  It is suitable for runtime
+    applications that want to absorb first-call compilation before an analysis.
+    """
+
+    results: Dict[str, Any] = {}
+    total_start = time.perf_counter()
+    jit = jit_diagnostics()
+    for requested_order in shell_orders:
+        order = _normalize_shell_order(requested_order)
+        model = _warmup_model(order)
+        start = time.perf_counter()
+        K_first, first_info = assemble_stiffness_matrix(model)
+        first_seconds = time.perf_counter() - start
+        start = time.perf_counter()
+        K_second, second_info = assemble_stiffness_matrix(model)
+        second_seconds = time.perf_counter() - start
+        start = time.perf_counter()
+        M_first, _mass_first_info = assemble_mass_matrix(model)
+        mass_first_seconds = time.perf_counter() - start
+        start = time.perf_counter()
+        M_second, _mass_second_info = assemble_mass_matrix(model)
+        mass_second_seconds = time.perf_counter() - start
+        results[order] = {
+            "status": "completed",
+            "shell_order": order,
+            "element_count": int(model.mesh.num_elements),
+            "jit_enabled": bool(JIT_ENABLED),
+            "jit_disabled_reason": JIT_DISABLED_REASON,
+            "jit_backend": jit.get("backend"),
+            "parallel_threads": jit.get("num_threads"),
+            "cold_assembly_seconds": float(first_seconds),
+            "warm_assembly_seconds": float(second_seconds),
+            "warm_speedup": float(first_seconds / second_seconds) if second_seconds > 0.0 else 0.0,
+            "matrix_difference_norm": _matrix_difference_norm(K_first, K_second),
+            "mass_cold_assembly_seconds": float(mass_first_seconds),
+            "mass_warm_assembly_seconds": float(mass_second_seconds),
+            "mass_matrix_difference_norm": _matrix_difference_norm(M_first, M_second),
+            "first_assembly": first_info.get("diagnostics", {}),
+            "second_assembly": second_info.get("diagnostics", {}),
+        }
+    nonlinear_impact = None
+    if include_nonlinear_impact:
+        nonlinear_impact = _warm_nonlinear_impact_kernel()
+    return {
+        "status": "completed",
+        "jit": jit,
+        "total_seconds": float(time.perf_counter() - total_start),
+        "shell_orders": results,
+        "nonlinear_impact": nonlinear_impact,
+    }
+
+
+__all__: Tuple[str, ...] = ("warm_fe_solver_kernels",)