EasyFEA 3.2.0__tar.gz → 3.2.1__tar.gz

{easyfea-3.2.0 → easyfea-3.2.1}/EasyFEA/FEM/Operators/NonLinear.py

@@ -402,9 +402,9 @@ def __AdaptiveTimeQuadratureStressTensor(
 ) -> tuple["FeArray", "FeArray", int]:
     r"""Per-element adaptive strain-path quadrature — the ``tol``-driven path of :func:`TimeQuadratureStressTensor`.
 
-    Each element refines along the nested chain ``1, 3, 5, 9, …`` until *its own* energy defect is within ``tol``, then freezes — so a low-strain element stops at one point while a high-strain one keeps refining. The test is the **integrated** relative error over the element, ``∫_Ωe (S:Δe − ΔW)² dΩ ≤ tol² ∫_Ωe ΔW² dΩ``. It is evaluated as the Gauss-point sums ``Σ_p V_(ep)(S:Δe − ΔW)² ≤ tol² Σ_p V_(ep) ΔW²`` with ``V_(ep)`` the Gauss point's volume (weight × Jacobian) — so the ``V_(ep)`` factor is what makes each side a genuine *integral over the element*, **not** a pointwise energy-density comparison. Energy-safe because ``S:Δe = ΔW`` holds per Gauss point; the squared, volume-weighted form is safe against sign cancellation between Gauss points, and per element the well-resolved regions cannot mask a coarse one.
+    Each element refines along the nested chain ``1, 3, 5, 9, …`` until *its own* energy defect is within ``tol``, then freezes — so a low-strain element stops at one point while a high-strain one keeps refining. The test is the **integrated** relative error over the element, ``∫_Ωe |S:Δe − ΔW| dΩ ≤ tol · ∫_Ωe |ΔW| dΩ``, evaluated as the Gauss-point sums ``Σ_p V_(ep) |S:Δe − ΔW| ≤ tol · Σ_p V_(ep) |ΔW|`` with ``V_(ep)`` the Gauss point's volume (weight × Jacobian) — so the ``V_(ep)`` factor makes each side a genuine *integral over the element*, **not** a pointwise energy-density comparison. This L1 (absolute) form is the tightest simple bound on the element's actual per-step energy drift ``|∫_Ωe (S:Δe − ΔW) dΩ|`` (triangle inequality, no volume factor), and taking ``|·|`` before summing makes it safe against sign cancellation between Gauss points — a well-resolved region cannot mask a coarse one. Energy-safe because ``S:Δe = ΔW`` holds per Gauss point.
 
-    Only the still-active elements are evaluated at each level — the rule is applied to that subset via :meth:`_StrainPathState._sliced` — so the constitutive cost tracks the hard elements, not the mesh. (Nodes shared with a coarser level are re-evaluated rather than cached; the active set shrinks fast, so that stays cheap and keeps the loop plain.) Returns ``(dWde_quad, d2Wde_quad)`` — each row carrying its element's accepted rule — and the largest point count any element reached.
+    Only the still-active elements are evaluated at each level — the rule is applied to that subset via :meth:`_StrainPathState._sliced` — so the constitutive cost tracks the hard elements, not the mesh. (Nodes shared with a coarser level are re-evaluated rather than cached; the active set shrinks fast, so that stays cheap and keeps the loop plain.) Returns ``(dWde_quad, d2Wde_quad)`` — each row carrying its element's accepted rule — and ``nPts_e``, the point count each element accepted.
     """
     groupElem = state_n.groupElem  # state_n and state_np1 share the group
     dim = groupElem.dim
@@ -417,7 +417,7 @@ def __AdaptiveTimeQuadratureStressTensor(
     dW = material.Compute_W(state_np1) - material.Compute_W(state_n)  # ΔW per point
     dE = state_np1.Compute_GreenLagrange() - state_n.Compute_GreenLagrange()
     dE_vec = Project_matrix_to_vector(dE[..., :dim, :dim])  # Δe (Kelvin-Mandel)
-    refW = einsum("ep,ep,ep->e", wJ_e_pg, dW, dW)  # Σ_p V ΔW²  (Ne,)
+    refW = einsum("ep,ep->e", wJ_e_pg, np.abs(dW))  #  Σ_p V |ΔW| (Ne,)
     Ne, nPg, ncomp = *wJ_e_pg.shape[:2], dE_vec.shape[-1]
 
     def at(
@@ -428,7 +428,8 @@ def __AdaptiveTimeQuadratureStressTensor(
     dWde_quad = FeArray.zeros(Ne, nPg, ncomp)
     d2Wde_quad = FeArray.zeros(Ne, nPg, ncomp, ncomp)
     activeElements = np.arange(Ne)  # elements still refining
-    nPts, nPts_used = 1, 1
+    nPts_e = np.zeros(Ne, dtype=int)  # accepted point count per element (diagnostic)
+    nPts = 1
     while activeElements.size:
         nodes, weights = __clenshaw_curtis(nPts)
         S = sum(
@@ -441,27 +442,27 @@ def __AdaptiveTimeQuadratureStressTensor(
         defect = einsum("epi,epi->ep", S, dE_vec[activeElements]) - dW[activeElements]
         next_nPts = 3 if nPts == 1 else 2 * nPts - 1  # next level in the chain
         # accept an element once its own energy defect is within tol (all of them at the last level)
-        done = (next_nPts > max(maxPoints, 1)) | (
-            einsum("ep,ep,ep->e", wJ_e_pg[activeElements], defect, defect)
-            <= tol * tol * (refW[activeElements] + 1e-300)
+        isAccepted = (next_nPts > max(maxPoints, 1)) | (
+            einsum("ep,ep->e", wJ_e_pg[activeElements], np.abs(defect))
+            <= tol * refW[activeElements]
         )
-        if done.any():
-            e = activeElements[done]  # elements accepting this rule
-            dWde_quad[e] = S[done]
+        if isAccepted.any():
+            acceptedElems = activeElements[isAccepted]  # elements accepting this rule
+            dWde_quad[acceptedElems] = S[isAccepted]
             # their tangent only: Σ_k 2 w_k s_k d2Wde, s=0 drops out (∂e/∂u = s B)
-            d2Wde_quad[e] = sum(
+            d2Wde_quad[acceptedElems] = sum(
                 (
-                    (2.0 * w * s) * material.Compute_d2Wde(at(s, e))
+                    (2.0 * w * s) * material.Compute_d2Wde(at(s, acceptedElems))
                     for s, w in zip(nodes, weights)
                     if s
                 ),
                 0.0,
             )
-            nPts_used = max(nPts_used, nPts)
-            activeElements = activeElements[~done]
+            nPts_e[acceptedElems] = nPts  # record each frozen element's accepted rule
+            activeElements = activeElements[~isAccepted]
         nPts = next_nPts
 
-    return dWde_quad, d2Wde_quad, nPts_used
+    return dWde_quad, d2Wde_quad, nPts_e
 
 
 def TimeQuadratureStressTensor(
@@ -484,7 +485,7 @@ def TimeQuadratureStressTensor(
 
     ``(s_k, w_k)`` is the Clenshaw-Curtis rule on ``nPoints`` points (:func:`__clenshaw_curtis`); ``1, 2, 3`` are the midpoint, trapezoid and Simpson rules. Intermediate nodes are :class:`_StrainPathState`; ``s = 0, 1`` reuse the end states.
 
-    **Adaptive (per-element) mode.** With ``tol`` set, the rule is chosen *element by element* by :func:`__AdaptiveTimeQuadratureStressTensor`: each element walks the nested chain ``1, 3, 5, 9, 17, 33`` (up to ``maxPoints``) and freezes once *its own* energy defect is within ``tol``, so points are spent only where the step is nonlinear — a low-strain element may stop at a single midpoint while a stiff one keeps refining. The defect ``S_quad:Δe − ΔW`` is the quadrature error of the discrete-gradient identity ``S_quad:Δe = ΔW`` (with ``ΔW`` *known* from the endpoints), so the test is absolute — no consecutive-difference guess. It is the **integrated** relative error over the element, ``∫_Ωe (S_quad:Δe − ΔW)² dΩ ≤ tol² ∫_Ωe ΔW² dΩ`` — the integrals are the volume-weighted Gauss-point sums ``Σ_p V_(ep)···``, *not* a pointwise energy-density comparison — so ``tol`` reads as "conserve energy to this relative tolerance". Squaring guards against sign cancellation between Gauss points, and being absolute the test accepts the coarsest rule directly: the ``1``-point midpoint is exact for a linear energy integrand, so a quadratic ``W`` converges at a single point. The tangent uses each element's accepted rule, so residual and tangent stay consistent.
+    **Adaptive (per-element) mode.** With ``tol`` set, the rule is chosen *element by element* by :func:`__AdaptiveTimeQuadratureStressTensor`: each element walks the nested chain ``1, 3, 5, 9, 17, 33`` (up to ``maxPoints``) and freezes once *its own* energy defect is within ``tol``, so points are spent only where the step is nonlinear — a low-strain element may stop at a single midpoint while a stiff one keeps refining. The defect ``S_quad:Δe − ΔW`` is the quadrature error of the discrete-gradient identity ``S_quad:Δe = ΔW`` (with ``ΔW`` *known* from the endpoints), so the test is absolute — no consecutive-difference guess. It is the **integrated** relative error over the element, ``∫_Ωe |S_quad:Δe − ΔW| dΩ ≤ tol · ∫_Ωe |ΔW| dΩ`` — the integrals are the volume-weighted Gauss-point sums ``Σ_p V_(ep)···``, *not* a pointwise energy-density comparison — so ``tol`` reads as "conserve energy to this relative tolerance". Taking the absolute value before summing bounds the element's actual energy drift directly and guards against sign cancellation between Gauss points. Since each level is scored on its own (no comparison to a coarser one) the test accepts the coarsest rule directly: the ``1``-point midpoint is exact for a linear energy integrand, so a quadratic ``W`` converges at a single point. The tangent uses each element's accepted rule, so residual and tangent stay consistent.
 
     Since ``Δe = B(ū)·Δu`` exactly and ``de/ds = Δe`` is constant along the segment, the fundamental theorem of calculus gives ``S_quad:Δe = ΔW`` once the ``s``-integral is exact — a **discrete gradient**. The energy defect is therefore just the quadrature error, which Clenshaw-Curtis drives down spectrally; a quadratic ``W`` is exact at every rule. Note ``nPoints = 1`` is the average-strain stress ``S(½(e_n + e_{n+1}))``, *not* the midpoint-displacement stress of :func:`SecondPiolaKirchhoffStressTensor`.
 
@@ -518,9 +519,9 @@ def TimeQuadratureStressTensor(
         Consistent tangent, built for ``coefK = 0.5``.
     R_e : ndarray of shape ``(Ne, nPe·dim)``
         Internal residual force.
-    nPts : int
-        Clenshaw-Curtis points used — ``nPoints`` when fixed; when adaptive, the *largest* level
-        any element reached (individual elements may use fewer). Lets the caller log the cost.
+    nPts_e : ndarray of shape ``(Ne,)``
+        Clenshaw-Curtis points each element used — constant ``nPoints`` when fixed, per-element
+        when adaptive.
     """
 
     groupElem = state_mid.groupElem
@@ -547,7 +548,7 @@ def TimeQuadratureStressTensor(
             dWde_quad += w * material.Compute_dWde(state)
             if s != 0.0:
                 d2Wde_quad += (2.0 * w * s) * material.Compute_d2Wde(state)
-        nPts_used = int(nPoints)
+        nPts_e = np.full(groupElem.Ne, int(nPoints))  # every element uses the same rule
     else:
         # Adaptive: refine per element on the *energy defect*. This stress exists so that
         # S_quad : Δe = ΔW exactly (a discrete gradient, for energy conservation); the only error
@@ -555,7 +556,7 @@ def TimeQuadratureStressTensor(
         # is *known* from the endpoints — so the test is absolute (each level scored on its own).
         # Refining element-by-element rather than the whole block spends points only where the
         # material is nonlinear over the step (see __AdaptiveTimeQuadratureStressTensor).
-        dWde_quad, d2Wde_quad, nPts_used = __AdaptiveTimeQuadratureStressTensor(
+        dWde_quad, d2Wde_quad, nPts_e = __AdaptiveTimeQuadratureStressTensor(
             material, state_n, state_np1, tol, int(maxPoints)
         )
 
@@ -572,7 +573,7 @@ def TimeQuadratureStressTensor(
         residual_e *= thickness
 
     K_e, R_e = __reorder_dofs(dim, nPe, tangent_e, residual_e)
-    return K_e, R_e, nPts_used
+    return K_e, R_e, nPts_e
 
 
 def ActiveStressTensor(
@@ -628,17 +629,20 @@ def KelvinVoigtDamping(
     material: "_HyperElastic",
     state: "HyperElasticState",
     velocity: np.ndarray,
-) -> tuple[np.ndarray, np.ndarray]:
-    r"""Kelvin–Voigt viscous element contributions (C_e, Kgeo_e) for the
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    r"""Kelvin–Voigt viscous element contributions (Kgeo_e, R_e, C_e) for the
     large-strain viscous force F_visco(u) = C(u)·v, with Σ_visco = η·Ė
     (Green-Lagrange strain rate of velocity) and B = De(u)·grad.
 
-    - C_e = thickness · η · ∫ Bᵀ B dΩ — the damping matrix; the simulation puts
-      it in slot 2 of (K, C, M, F) (residual b -= C @ v_t, time-scheme history,
-      and the coefC·C tangent).
+    Ordered ``(tangent, residual, extra)`` like the rest of this module.
+
     - Kgeo_e — the configuration tangent ∂(C·v)/∂u at fixed velocity (geometric
       stiffening from Σ_visco plus the ∂Ė/∂u term); the simulation adds it to
       K_e so it rides coefK.
+    - R_e = thickness · η · ∫ Bᵀ Ė dΩ — the viscous residual, which the simulation
+      subtracts from F_e.
+    - C_e = thickness · η · ∫ Bᵀ B dΩ — the damping matrix; the simulation puts it
+      in slot 2 of (K, C, M, F), where it rides the coefC·C tangent.
 
     Parameters
     ----------
@@ -653,11 +657,12 @@ def KelvinVoigtDamping(
     Returns
     -------
     tuple
-        (None, None) when material.eta == 0 or velocity is None. Both matrices
-        are (Ne, nPe·dim, nPe·dim) reordered to (xi, yi, zi, ..., xn, yn, zn).
+        (None, None, None) when material.eta == 0 or velocity is None. Kgeo_e and C_e
+        are (Ne, nPe·dim, nPe·dim) and R_e is (Ne, nPe·dim), all reordered to
+        (xi, yi, zi, ..., xn, yn, zn).
     """
     if material.eta == 0.0 or velocity is None:
-        return None, None  # type: ignore [return-value]
+        return None, None, None  # type: ignore [return-value]
 
     groupElem = state.groupElem
     matrixType = state.matrixType
@@ -668,22 +673,22 @@ def KelvinVoigtDamping(
 
     grad_e_pg, B_e_pg = __block_grad_B(state)
     Beta_e_pg = state.Compute_Deta(velocity) @ grad_e_pg
+    sig_e_pg = material.eta * state.Compute_Edot_vec(velocity)  # Σ_visco = η·Ė
 
     # damping matrix C = thickness · η · ∫ Bᵀ B (fused einsum, see SPK above)
     subscripts = "ep,epji,epjl->eil"
     C_e = thickness * material.eta * einsum(subscripts, wJ_e_pg, B_e_pg, B_e_pg)
 
+    # viscous residual ∫ Bᵀ Σ_visco — same contraction as the active stress
+    residual_e = thickness * einsum("ep,epji,epj->ei", wJ_e_pg, B_e_pg, sig_e_pg)
+
     # configuration tangent ∂(C·v)/∂u = geometric (∫ gradᵀ Sig grad) + material-like
     # (η ∫ Bᵀ (∂Ė/∂u)) pieces
     A_mat = material.eta * einsum(subscripts, wJ_e_pg, B_e_pg, Beta_e_pg)
-    A_geo = __geometric_tangent(
-        wJ_e_pg,
-        state,
-        material.eta * state.Compute_Edot_vec(velocity),
-    )
+    A_geo = __geometric_tangent(wJ_e_pg, state, sig_e_pg)
     Kgeo_e = thickness * (A_mat + A_geo)
 
-    return __reorder_dofs(dim, nPe, C_e, Kgeo_e)
+    return __reorder_dofs(dim, nPe, Kgeo_e, residual_e, C_e)
 
 
 def __skew(v: np.ndarray) -> np.ndarray:

{easyfea-3.2.0 → easyfea-3.2.1}/EasyFEA/Simulations/_hyperelastic.py

@@ -15,6 +15,7 @@ from ..Utilities import Terminal, _types
 if TYPE_CHECKING:
     from ..FEM import Mesh
 from ..FEM import MatrixType, Operators
+from ..Utilities._cache import cache_computed_values
 
 # models
 from ..Models import ModelType, Project_Kelvin, Result_strain_or_stress_field_e
@@ -169,7 +170,7 @@ class HyperElastic(_Simu):
         stressType: "HyperElastic.StressType" = StressType.pointwise,
         nPoints: int = 3,
         useConsistentTangent: bool = True,
-        quadTol: Optional[float] = None,
+        energyTol: Optional[float] = None,
     ) -> None:
         r"""Selects the stress used by the internal force. Call **after** :py:meth:`~EasyFEA.Simulations._Simu.Solver_Set_Hyperbolic_Algorithm`.
 
@@ -192,18 +193,18 @@ class HyperElastic(_Simu):
         nPoints : int, optional
             ``quadrature`` only: number of Clenshaw-Curtis points, by default 3 (Simpson).
             ``1`` and ``2`` are the midpoint and trapezoid rules; more converges spectrally.
-            When ``quadTol`` is set this is the starting (minimum) level instead of a fixed count.
+            When ``energyTol`` is set this is the starting (minimum) level instead of a fixed count.
         useConsistentTangent : bool, optional
             ``gonzalez`` only: if False, drop the discrete-gradient corrections from the
             tangent. Same residual and same exact conservation, but Newton converges linearly
             — a diagnostic, to measure what the consistent tangent is worth.
-        quadTol : float, optional
+        energyTol : float, optional
             ``quadrature`` only: if set, the rule is refined adaptively *element by element*
             along the nested Clenshaw-Curtis chain ``1, 3, 5, 9, ...`` (capped at 33) — each
             element stops once its own **integrated** relative energy defect
-            ``∫(S_quad:Δe − ΔW)² dΩ ≤ quadTol² ∫ΔW² dΩ`` over that element is met (a volume
+            ``∫|S_quad:Δe − ΔW| dΩ ≤ energyTol · ∫|ΔW| dΩ`` over that element is met (a volume
             integral over its Gauss points, not a pointwise density). So energy is conserved to
-            ``quadTol`` while points are spent only where the step is nonlinear. ``None``
+            ``energyTol`` while points are spent only where the step is nonlinear. ``None``
             (default) keeps the fixed ``nPoints`` rule.
         """
         stressType = HyperElastic.StressType(stressType)
@@ -216,13 +217,14 @@ class HyperElastic(_Simu):
             )
         assert nPoints >= 1, f"nPoints must be >= 1 (got {nPoints})."
 
-        self.__stressParams = (stressType, nPoints, useConsistentTangent, quadTol)
-        self.__quadNPoints = 0  # diagnostic: points the last assembly used
+        self.__stressParams = (stressType, nPoints, useConsistentTangent, energyTol)
+        # diagnostic: per-element quadrature-point counts, last assembly
+        self.__nPts_e = None
 
     def __Solver_Get_Stress_Params(
         self,
     ) -> tuple["HyperElastic.StressType", int, bool, Optional[float]]:
-        """Returns (stressType, nPoints, useConsistentTangent, quadTol) internal-force props."""
+        """Returns (stressType, nPoints, useConsistentTangent, energyTol) internal-force props."""
         return self.__stressParams
 
     @property
@@ -230,6 +232,11 @@ class HyperElastic(_Simu):
         """Stress used by the internal force — see :py:meth:`Solver_Set_Stress`."""
         return self.__Solver_Get_Stress_Params()[0]
 
+    @cache_computed_values
+    def __Mass_e(self, groupElem, rho, thickness, dim):
+        """Constant element mass matrix ``thickness · ∫ρ N·N``."""
+        return thickness * Operators.Bilinear.UV(groupElem, rho, dof_n=dim)
+
     def Construct_local_matrix_system(
         self,
         problemType,
@@ -237,22 +244,22 @@ class HyperElastic(_Simu):
     ):
         """Returns ``{groupElem: (K_e, C_e, M_e, F_e)}`` for the current Newton iterate.
 
-        Newton solves ``A(u)·Δu = -R(u)``; the simulation assembles ``A = coefK·K + coefC·C + coefM·M`` and ``b -= C @ v_t``. Per group of elements: ``K_e`` is the elastic tangent (plus the viscous configuration tangent ``Kgeo_e``), ``F_e = -R_e`` the residual, ``C_e`` the Kelvin–Voigt damping matrix and ``M_e`` the mass matrix (dynamic schemes only).
+        Newton solves ``A(u)·Δu = -R(u)`` with ``A = coefK·K + coefC·C + coefM·M``. Per group of elements: ``K_e`` is the elastic tangent (plus the viscous configuration tangent ``Kgeo_e``), ``C_e`` the Kelvin–Voigt damping matrix, ``M_e`` the mass matrix (dynamic schemes only) and ``F_e = -R_e`` the complete residual — internal force together with the ``C_e·v_t + M_e·a_t`` inertia and damping terms.
         """
         dim = self.dim
         thickness = self.material.thickness if dim == 2 else 1
         isDynamic = self.algo in AlgoType.Get_Hyperbolic_Types()
 
-        # current Newton-Raphson iterate; for dynamic schemes also capture the
-        # velocity, for Kelvin–Voigt viscosity.
+        # current Newton-Raphson iterate; for dynamic schemes also capture the velocity
+        # (Kelvin–Voigt viscosity) and the acceleration (inertia), both needed by F_e.
         displacement = self._Solver_Get_Newton_Raphson_current_solution()
-        velocity = None
+        velocity = accel = None
         # Both non-default stresses are built from the step endpoints (u_n, u_{n+1}) on top
         # of the midpoint base point, so both need u_{n+1} kept before the midpoint
         # evaluation overwrites `displacement` with ū. Re-checked here (not only in the
         # setter) so that re-calling Solver_Set_Hyperbolic_Algorithm with another algo
         # can't leave a stale selection.
-        stressType, nPoints, useConsistentTangent, quadTol = (
+        stressType, nPoints, useConsistentTangent, energyTol = (
             self.__Solver_Get_Stress_Params()
         )
         isPointwise = stressType == HyperElastic.StressType.pointwise
@@ -261,7 +268,7 @@ class HyperElastic(_Simu):
         ), f"the '{stressType}' stress requires AlgoType.midpoint (got {self.algo})."
         u_np1 = displacement
         if isDynamic:
-            displacement, velocity, _ = self._Solver_Evaluate_u_v_a_for_time_scheme(
+            displacement, velocity, accel = self._Solver_Evaluate_u_v_a_for_time_scheme(
                 problemType, displacement
             )
         if not isPointwise:
@@ -270,7 +277,7 @@ class HyperElastic(_Simu):
         errDetF = "det(F) < 0 - reduce load steps"
 
         out = {}
-        quadNPoints = 0  # max Clenshaw-Curtis points over groups this Newton iteration
+        list_nPts_e = []  # per-element point counts across groups (quadrature only)
         for groupElem in self.mesh.Get_list_groupElem():
             state = HyperElasticState(groupElem, displacement, matrixType)
 
@@ -298,15 +305,15 @@ class HyperElastic(_Simu):
                         useConsistentTangent,
                     )
                 elif stressType == HyperElastic.StressType.quadrature:
-                    K_e, residual_e, nPts = (
+                    K_e, residual_e, nPts_e = (
                         Operators.NonLinear.TimeQuadratureStressTensor(
                             self.material,
                             *hyperElasticStates,
                             nPoints,
-                            quadTol,
+                            energyTol,
                         )
                     )
-                    quadNPoints = max(quadNPoints, nPts)
+                    list_nPts_e.append(nPts_e)
                 else:
                     raise NotImplementedError
 
@@ -324,24 +331,41 @@ class HyperElastic(_Simu):
 
             F_e = -residual_e
 
-            # Kelvin–Voigt viscosity: C_e is the damping matrix (slot 2, rides
-            # coefC, carries the viscous residual b -= C @ v_t); Kgeo_e is the
-            # configuration tangent ∂(C·v)/∂u, added to K_e so it rides coefK.
+            # Kelvin–Voigt viscosity: C_e is the damping matrix (slot 2, so it rides coefC
+            # in A), R_visco_e its residual, and Kgeo_e the configuration tangent
+            # ∂(C·v)/∂u, added to K_e so it rides coefK.
             C_e = None
             if self.material.eta != 0 and velocity is not None:
-                C_e, Kgeo_e = Operators.NonLinear.KelvinVoigtDamping(
+                Kgeo_e, R_visco_e, C_e = Operators.NonLinear.KelvinVoigtDamping(
                     self.material, state, velocity
                 )
                 K_e += Kgeo_e
+                F_e -= R_visco_e
 
-            # mass matrix — only assembled for dynamic schemes
+            # mass matrix and the inertia residual — dynamic schemes only
             M_e = None
             if isDynamic:
-                M_e = thickness * Operators.Bilinear.UV(groupElem, self.rho, dof_n=dim)
+                # M_e = thickness · ∫ρ N·N is constant across the solve, so it is cached (see __Mass_e)
+                # instead of rebuilt every Newton iteration. An array ρ is unhashable, so it cannot key the
+                # cache and is recomputed directly.
+                if isinstance(self.rho, np.ndarray):
+                    M_e = thickness * Operators.Bilinear.UV(
+                        groupElem, self.rho, dof_n=dim
+                    )
+                else:
+                    M_e = self.__Mass_e(groupElem, self.rho, thickness, dim)
+                F_e -= np.einsum(
+                    "eij,ej->ei",
+                    M_e,
+                    groupElem.Locates_sol_e(accel, dim),
+                    optimize=True,
+                )
 
             out[groupElem] = (K_e, C_e, M_e, F_e)
 
-        self.__quadNPoints = quadNPoints  # 0 unless quadrature stress ran this assembly
+        # per-element Clenshaw-Curtis point counts this assembly, or None if the quadrature
+        # stress did not run (pointwise / gonzalez)
+        self.__nPts_e = np.concatenate(list_nPts_e) if list_nPts_e else None
 
         return out
 
@@ -358,10 +382,8 @@ class HyperElastic(_Simu):
         if self.algo in AlgoType.Get_Hyperbolic_Types():
             iter["speed"] = self._Get_v_n(self.problemType)
             iter["accel"] = self._Get_a_n(self.problemType)
-        if (
-            self.__quadNPoints
-        ):  # points the converged step used (quadrature stress only)
-            iter["quadNPoints"] = self.__quadNPoints
+        if self.__nPts_e is not None:  # per-element point counts, quadrature only
+            iter["nPts_e"] = self.__nPts_e
 
         return super().Save_Iter(iter)
 

{easyfea-3.2.0 → easyfea-3.2.1}/EasyFEA/Simulations/_simu.py

@@ -16,6 +16,7 @@ from ..__about__ import __version__
 
 # utilities
 from ..Utilities import Folder, Terminal, Tic, _params, _types
+from ..Utilities._cache import cache_computed_values, clear_cached_computed_values
 from ..Utilities._observers import Observable, _IObserver
 from ..Utilities._mpi import CAN_USE_MPI, MPI_SIZE, MPI_RANK, MPI_COMM
 
@@ -220,7 +221,12 @@ class _Simu(_IObserver, _params.Updatable, ABC):
             Optional[np.ndarray],
         ],
     ]:
-        r"""Construct the local matrix system :math:`\Krm \, \mathrm{u} + \Crm \, \vrm + \Mrm \, \arm = \Frm` for the given problem, returned per contributing group of elements `{groupElem: (K_e, C_e, M_e, F_e)}`."""
+        r"""Construct the local matrix system :math:`\Krm \, \mathrm{u} + \Crm \, \vrm + \Mrm \, \arm = \Frm` for the given problem, returned per contributing group of elements `{groupElem: (K_e, C_e, M_e, F_e)}`.
+
+        For a **linear** problem :math:`\Frm` is the load alone: :py:meth:`_Solver_Apply_Neumann` moves :math:`\mathrm{u}^n, \vrm^n, \arm^n` to the right-hand side with the history terms of the active time scheme.
+
+        For a **nonlinear** problem the unknown is :math:`\Delta \mathrm{u}`, so :math:`\Frm_e` is the complete residual :math:`-\Rrm_e`, inertia and damping included (:math:`-\Crm_e \, \vrm_t - \Mrm_e \, \arm_t`, with :math:`\vrm_t, \arm_t` from :py:meth:`_Solver_Evaluate_u_v_a_for_time_scheme`).
+        """
         raise NotImplementedError
 
     # Iterations
@@ -711,6 +717,11 @@ class _Simu(_IObserver, _params.Updatable, ABC):
             self.__listMesh.append(mesh)
             self.__mesh = mesh
 
+            # New connectivity invalidates the geometry-derived caches.
+            # This cannot live in `Need_Update`, which fires on every Newton
+            # iteration — exactly the case those caches exist to serve.
+            clear_cached_computed_values(self)
+
             # The mesh changes, so the matrices must be reconstructed
             self.Need_Update()
             # Initialize boundary conditions
@@ -738,7 +749,7 @@ class _Simu(_IObserver, _params.Updatable, ABC):
         if MPI_SIZE == 1:
             return
 
-        list_mesh = []
+        list_mesh: list[Mesh] = []
         for mesh in self.__listMesh:
             if isinstance(mesh, str):
                 mesh = Load_Mesh(Folder.Join(self.folder, mesh))
@@ -750,6 +761,9 @@ class _Simu(_IObserver, _params.Updatable, ABC):
                 self.__listMesh[i] = mesh
             self.__mesh = self.__listMesh[self.__indexMesh]
             self.Bc_Init()
+            # rank 0 swaps its partition for the full global mesh — the geometry-derived caches describe the
+            # partition and no longer apply.
+            clear_cached_computed_values(self)
             self.Need_Update()
             self.__isGathered = True
 
@@ -774,6 +788,9 @@ class _Simu(_IObserver, _params.Updatable, ABC):
 
         self.__mesh = mesh
 
+        # switching to another mesh in the history changes the connectivity
+        clear_cached_computed_values(self)
+
         self.Need_Update()  # need to reconstruct matrices
 
     def _Update(self, observable: Observable, event: str) -> None:
@@ -793,8 +810,8 @@ class _Simu(_IObserver, _params.Updatable, ABC):
     # Solver
     # ----------------------------------------------
 
-    @staticmethod
     def __Assemble_csr(
+        self,
         dict_group_data: dict["_GroupElem", np.ndarray],
         dof_n: int,
         Ndof: int,
@@ -802,6 +819,23 @@ class _Simu(_IObserver, _params.Updatable, ABC):
     ) -> sparse.csr_matrix:
         """Scatter per-group local element matrices/vectors into a global CSR.
 
+        A finite-element matrix has far more element-level entries than stored coefficients — each shared
+        node makes several element contributions land on the same ``(row, col)`` — so assembly is
+        fundamentally "sum every contribution into its slot". The element→DOF coordinates depend only on
+        connectivity, so across a Newton loop or time stepping they never change; only the values do. This
+        method exploits that: scipy builds and owns the sparsity pattern on the first assembly, and a small
+        precomputed map lets every later assembly do the summation with a single ``np.bincount``, skipping
+        scipy's repeated sort-and-sum-duplicates.
+
+        The map is cached per ``(dof_n, isMatrix, Ndof, contributing groups)``. The contributing groups are
+        part of the key because a simulation may feed different group sets to different slots — in the
+        cardiac benchmark the surface group contributes to K, C and F but leaves M ``None``, so K and M have
+        genuinely different patterns.
+
+        Reuse is exact to floating-point round-off (~1e-16 relative), not bit-identical to a fresh scipy
+        build, because ``bincount`` sums each slot's contributions in a different order than scipy's
+        coo->csr does.
+
         Parameters
         ----------
         dict_group_data : dict[_GroupElem, FeArray]
@@ -819,28 +853,77 @@ class _Simu(_IObserver, _params.Updatable, ABC):
         if not dict_group_data:
             return sparse.csr_matrix(shape)
 
-        list_rows, list_cols, list_data = [], [], []
-        for groupElem, X_e in dict_group_data.items():
-            if X_e is None:
-                continue
-            if isMatrix:
-                rows = groupElem.Get_rows_e(dof_n).ravel()
-                cols = groupElem.Get_columns_e(dof_n).ravel()
-            else:
-                rows = groupElem.Get_assembly_e(dof_n).ravel()
-                cols = np.zeros_like(rows)
-            list_rows.append(rows)
-            list_cols.append(cols)
-            list_data.append(X_e.ravel())
+        # Fixing the group order here keeps `data` aligned with the map built from these same groups.
+        groups = tuple(g for g, X_e in dict_group_data.items() if X_e is not None)
+        if not groups:
+            return sparse.csr_matrix(shape)
 
-        if not list_data:
+        data = np.concatenate([dict_group_data[g].ravel() for g in groups])
+
+        # An MPI rank may own no element of any contributing group.
+        if data.size == 0:
             return sparse.csr_matrix(shape)
 
-        data = np.concatenate(list_data)
+        # The reduction map (which CSR slot each element entry feeds) is cached per key; it depends only on
+        # connectivity, so a Newton loop / time stepping reuses it and only the values below change.
+        inv, indices, indptr, nnz = self.__Get_csr_map(dof_n, isMatrix, Ndof, groups)
+        assert data.size == inv.size, f"Not enough data to fill a {shape} CSR."
+
+        # Sum every element entry into its slot with one bincount. `bincount` is real-only, so a complex
+        # system is summed as its real and imaginary parts — still one pass each, still the rare path.
+        if np.iscomplexobj(data):
+            csr_data = np.bincount(
+                inv, weights=data.real, minlength=nnz
+            ) + 1j * np.bincount(inv, weights=data.imag, minlength=nnz)
+        else:
+            csr_data = np.bincount(inv, weights=data, minlength=nnz)
+
+        matrix = sparse.csr_matrix((csr_data, indices, indptr), shape=shape)
+        # Canonical by construction (scipy sorted the pattern): lets Solvers skip its canonical fixup.
+        matrix.has_canonical_format = True
+        return matrix
+
+    @cache_computed_values
+    def __Get_csr_map(self, dof_n, isMatrix, Ndof, groups):
+        """Reduction map from element entries to global CSR slots for one assembly key.
+
+        Returns ``(inv, indices, indptr, nnz)``: ``inv[k]`` is the CSR-data slot that element entry ``k``
+        feeds, and ``(indices, indptr, nnz)`` is scipy's canonical pattern. Depends only on connectivity, so
+        ``@cache_computed_values`` (keyed on ``dof_n, isMatrix, Ndof, groups``) reuses it across every
+        assembly of a key and rebuilds it when the groups / Ndof / dof_n change or the mesh is reset. ``inv``
+        is the single largest cached array; int32 halves it and is safe since slots are bounded by nnz < 2^31.
+        """
+        shape = (Ndof, Ndof) if isMatrix else (Ndof, 1)
+
+        list_rows, list_cols = [], []
+        for groupElem in groups:
+            if isMatrix:
+                list_rows.append(groupElem.Get_rows_e(dof_n).ravel())
+                list_cols.append(groupElem.Get_columns_e(dof_n).ravel())
+            else:
+                r = groupElem.Get_assembly_e(dof_n).ravel()
+                list_rows.append(r)
+                list_cols.append(np.zeros_like(r))
         rows = np.concatenate(list_rows)
         cols = np.concatenate(list_cols)
-        assert data.size == rows.size, f"Not enough data to fill a {shape} CSR."
-        return sparse.csr_matrix((data, (rows, cols)), shape=shape)
+
+        # scipy owns the canonical sparsity pattern; build it once from a structure-only matrix (the values
+        # are irrelevant — only the nonzero positions matter).
+        matrix = sparse.csr_matrix((np.ones(rows.size), (rows, cols)), shape=shape)
+        matrix.sort_indices()
+
+        # `canon` is the sorted linear (row-major) index of each stored coefficient; `searchsorted` maps each
+        # element entry to the slot whose `(row, col)` it matches. Building the map from scipy's own pattern
+        # (rather than a parallel hand-built one) is correct by construction, independent of any sort order.
+        ncol = Ndof if isMatrix else 1
+        canon = (
+            np.repeat(np.arange(shape[0]), np.diff(matrix.indptr)) * ncol
+            + matrix.indices
+        )
+        inv = np.searchsorted(canon, rows.astype(np.int64) * ncol + cols).astype(
+            np.int32
+        )
+        return inv, matrix.indices, matrix.indptr, matrix.nnz
 
     def Assembly(
         self, problemType: ModelType
@@ -1464,96 +1547,79 @@ class _Simu(_IObserver, _params.Updatable, ABC):
 
         b += F
 
-        if (
-            self.isNonLinear
-            and self.algo in AlgoType.Get_Hyperbolic_and_Parabolic_Types()
-        ):
-
-            # get the current newton raphson solution (updated via u += delta_u)
-            u = self._Solver_Get_Newton_Raphson_current_solution()
-
-            # here evaluate the vectors according to the time scheme
-            _, v_t, a_t = self._Solver_Evaluate_u_v_a_for_time_scheme(problemType, u)
-
-            # add residual contributions in b
-            if v_t is not None:
-                b -= C @ sparse.csr_matrix(v_t.reshape(-1, 1))
-            if a_t is not None:
-                b -= M @ sparse.csr_matrix(a_t.reshape(-1, 1))
-            # K(u) Δu = - R(u)
-            #         = - (F(u) - b)
-            #         = - F(u) + b
-
-        else:
+        if self.isNonLinear:
+            # The unknown is Δu and `F` is the complete residual -R(u), so b is already
+            # built. The history terms below belong to a solve for u^{n+1}.
+            pass
 
-            if algo == AlgoType.elliptic:
-                pass
+        elif algo == AlgoType.elliptic:
+            pass
 
-            elif algo == AlgoType.parabolic:
-                dt, alpha = self.__Solver_Get_Parabolic_Params()
+        elif algo == AlgoType.parabolic:
+            dt, alpha = self.__Solver_Get_Parabolic_Params()
 
-                ut_np1 = u_n + (1 - alpha) * dt * v_n
+            ut_np1 = u_n + (1 - alpha) * dt * v_n
 
-                b += 1 / (alpha * dt) * C @ ut_np1
+            b += 1 / (alpha * dt) * C @ ut_np1
 
-            elif algo == AlgoType.newmark:
-                # same as hht in accel with alpha = 0
-                dt, beta, gamma, _ = self.__Solver_Get_Hyperbolic_Params()
+        elif algo == AlgoType.newmark:
+            # same as hht in accel with alpha = 0
+            dt, beta, gamma, _ = self.__Solver_Get_Hyperbolic_Params()
 
-                ut_np1 = u_n + dt * v_n + dt**2 / 2 * (1 - 2 * beta) * a_n
-                vt_np1 = v_n + dt * (1 - gamma) * a_n
+            ut_np1 = u_n + dt * v_n + dt**2 / 2 * (1 - 2 * beta) * a_n
+            vt_np1 = v_n + dt * (1 - gamma) * a_n
 
-                # ut_np1
-                coefC = gamma / (beta * dt)
-                coefM = 1 / (beta * dt**2)
-                b += (coefC * C + coefM * M) @ ut_np1
+            # ut_np1
+            coefC = gamma / (beta * dt)
+            coefM = 1 / (beta * dt**2)
+            b += (coefC * C + coefM * M) @ ut_np1
 
-                # vt_np1
-                b -= C @ vt_np1
+            # vt_np1
+            b -= C @ vt_np1
 
-            elif algo == AlgoType.midpoint:
-                # hht with alpha = 1/2, gamma = 1/2 and beta = 1/4
-                dt = self.__Solver_Get_Hyperbolic_Params()[0]
+        elif algo == AlgoType.midpoint:
+            # hht with alpha = 1/2, gamma = 1/2 and beta = 1/4
+            dt = self.__Solver_Get_Hyperbolic_Params()[0]
 
-                # u_n
-                coefM = 2 / dt**2
-                coefC = 1 / dt
-                b += (coefM * M + coefC * C - 1 / 2 * K) @ u_n
+            # u_n
+            coefM = 2 / dt**2
+            coefC = 1 / dt
+            b += (coefM * M + coefC * C - 1 / 2 * K) @ u_n
 
-                # v_n
-                coefM = 2 / dt
-                b += coefM * M @ v_n
+            # v_n
+            coefM = 2 / dt
+            b += coefM * M @ v_n
 
-            elif algo == AlgoType.hht:
-                dt, beta, gamma, alpha = self.__Solver_Get_Hyperbolic_Params()
+        elif algo == AlgoType.hht:
+            dt, beta, gamma, alpha = self.__Solver_Get_Hyperbolic_Params()
 
-                # u_n
-                coefM = 1 / (beta * dt**2)
-                coefC = gamma / (beta * dt)
-                b -= ((alpha - 1) * (coefM * M + coefC * C) + alpha * K) @ u_n
+            # u_n
+            coefM = 1 / (beta * dt**2)
+            coefC = gamma / (beta * dt)
+            b -= ((alpha - 1) * (coefM * M + coefC * C) + alpha * K) @ u_n
 
-                # v_n
-                coefM = (alpha - 1) / (beta * dt)
-                coefC = (alpha - 1) * (gamma / beta) + 1
-                b -= (coefM * M + coefC * C) @ v_n
+            # v_n
+            coefM = (alpha - 1) / (beta * dt)
+            coefC = (alpha - 1) * (gamma / beta) + 1
+            b -= (coefM * M + coefC * C) @ v_n
 
-                # a_n
-                coefM = (alpha - 1) / (2 * beta) + 1
-                coefC = dt * (alpha - 1) * (gamma / (2 * beta) - 1)
-                b -= (coefM * M + coefC * C) @ a_n
+            # a_n
+            coefM = (alpha - 1) / (2 * beta) + 1
+            coefC = dt * (alpha - 1) * (gamma / (2 * beta) - 1)
+            b -= (coefM * M + coefC * C) @ a_n
 
-            elif algo == AlgoType.euler_implicit:
-                dt = self.__Solver_Get_Hyperbolic_Params()[0]
-                b += (1 / dt**2 * M + 1 / dt * C) @ u_n
-                b += (1 / dt * M) @ v_n
+        elif algo == AlgoType.euler_implicit:
+            dt = self.__Solver_Get_Hyperbolic_Params()[0]
+            b += (1 / dt**2 * M + 1 / dt * C) @ u_n
+            b += (1 / dt * M) @ v_n
 
-            elif algo == AlgoType.euler_explicit:
-                # b = F^n - K u^n - C v^n  (A = M, solving for a^n)
-                b -= K @ u_n
-                b -= C @ v_n
+        elif algo == AlgoType.euler_explicit:
+            # b = F^n - K u^n - C v^n  (A = M, solving for a^n)
+            b -= K @ u_n
+            b -= C @ v_n
 
-            else:
-                raise NotImplementedError(f"Algo {algo} is not implemented here.")
+        else:
+            raise NotImplementedError(f"Algo {algo} is not implemented here.")
 
         tic.Tac("Solver", f"Neumann ({problemType}, {algo})", self._verbosity)
 

{easyfea-3.2.0 → easyfea-3.2.1}/EasyFEA/Utilities/PyVista.py

@@ -63,6 +63,7 @@ def Plot(
     show_grid=False,
     colorbarTitle=None,
     verticalColobar=True,
+    scalar_bar_kwargs: Optional[dict] = None,
     **kwargs,
 ):
     """Plots the object obj that can be either a simu, mesh, MultiBlock, PolyData.\n
@@ -111,6 +112,15 @@ def Plot(
         colorbar title, by default None
     verticalColobar : bool, optionnal
         color bar is vertical, by default True
+    scalar_bar_kwargs : dict, optionnal
+        Extra scalar-bar options, merged over the ones built from ``colorbarTitle`` and ``verticalColobar`` and taking precedence over them, by default None.
+        Useful when the defaults are unreadable — a horizontal bar in a narrow subplot needs ``n_labels`` and ``fmt`` to stop the ticks overlapping::
+
+            PyVista.Plot(simu, "uz", verticalColobar=False,
+                         scalar_bar_kwargs={"n_labels": 3, "fmt": "%.1e"})
+
+        Note that pyvista keys scalar bars by title, so several bars in one figure need distinct ``title`` entries.
+        Everything accepted by https://docs.pyvista.org/api/plotting/_autosummary/pyvista.plotter.add_scalar_bar
     **kwargs:
         Everything that can goes in add_mesh function https://docs.pyvista.org/version/stable/api/plotting/_autosummary/pyvista.Plotter.add_mesh.html#pyvista.Plotter.add_mesh
 
@@ -172,6 +182,15 @@ def Plot(
         pos = "position_y"
         val = 0.025
 
+    # caller options win, so `scalar_bar_kwargs` can override the title, the orientation or the position as well as add to them
+    scalar_bar_args = {
+        "title": colorbarTitle,
+        "vertical": verticalColobar,
+        pos: val,
+    }
+    if scalar_bar_kwargs is not None:
+        scalar_bar_args.update(scalar_bar_kwargs)
+
     # plot the mesh
     if not isinstance(pvMesh, list):
         pvMeshs = [pvMesh]
@@ -191,11 +210,7 @@ def Plot(
             cmap=cmap,
             n_colors=nColors,
             clim=clim,
-            scalar_bar_args={
-                "title": colorbarTitle,
-                "vertical": verticalColobar,
-                pos: val,
-            },
+            scalar_bar_args=scalar_bar_args,
             **kwargs,
         )
 

{easyfea-3.2.0 → easyfea-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easyfea
-Version: 3.2.0
+Version: 3.2.1
 Summary: User-friendly Python library that simplifies finite element analysis.
 Author-email: Matthieu Noel <matthieu.noel7@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

{easyfea-3.2.0 → easyfea-3.2.1}/easyfea.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easyfea
-Version: 3.2.0
+Version: 3.2.1
 Summary: User-friendly Python library that simplifies finite element analysis.
 Author-email: Matthieu Noel <matthieu.noel7@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

{easyfea-3.2.0 → easyfea-3.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "easyfea"
-version = "3.2.0"
+version = "3.2.1"
 description = "User-friendly Python library that simplifies finite element analysis."
 authors = [{ name = "Matthieu Noel", email = "matthieu.noel7@gmail.com" }]
 readme = "README.md"