structsolve 0.4.2__tar.gz → 0.5.0__tar.gz

{structsolve-0.4.2/structsolve.egg-info → structsolve-0.5.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: structsolve
-Version: 0.4.2
+Version: 0.5.0
 Summary: Structural analysis solvers
 Author-email: "Saullo G. P. Castro" <castrosaullo@gmail.com>
 License: BSD-2-Clause
 Project-URL: Homepage, https://github.com/compmech/structsolve
 Project-URL: Repository, https://github.com/compmech/structsolve
 Keywords: structural analysis,stress,vibration,linear buckling,newton raphson,arc length
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
@@ -51,6 +51,7 @@ Structural analysis solvers tailored for semi-analytical models
 - Eigensolver for dynamics: ([K] + lambda^2[M]){u} = 0
 - Nonlinear statics using Newton-Raphson 
 - Nonlinear statics using the Arc-Length method
+- Support for unsymmetric problems, such as those involving follower forces
 
 Currently these solvers are pretty much compatible with my other repositories
 [panels](https://github.com/saullocastro/panels), 
@@ -60,7 +61,7 @@ Currently these solvers are pretty much compatible with my other repositories
 Citing this library
 ===================
 
-Saullo G. P. Castro (2026). Structural analysis solvers tailored for semi-analytical models (Version 0.4.2). Zenodo. DOI: https://doi.org/10.5281/zenodo.2581212.
+Saullo G. P. Castro (2026). Structural analysis solvers tailored for semi-analytical models (Version 0.5.0). Zenodo. DOI: https://doi.org/10.5281/zenodo.2581212.
 
 
 Documentation
@@ -75,7 +76,9 @@ History
 
 See [CHANGELOG.md](CHANGELOG.md) for the details of each version.
 
-* version 0.4.2 (2026-09-17)
+* version 0.5.0 (2026-10-01)
+    - Configuration-dependent loads and unsymmetric eigenproblems
+* version 0.4.3 (2026-09-17)
     - Fixed the eigenvalue shift of the sparse solver of `lb`, which could
       return buckling loads higher than the critical ones
     - Fixed wrong buckling loads of the sparse solver of `lb` when SciPy is

{structsolve-0.4.2 → structsolve-0.5.0}/README.md

@@ -14,6 +14,7 @@ Structural analysis solvers tailored for semi-analytical models
 - Eigensolver for dynamics: ([K] + lambda^2[M]){u} = 0
 - Nonlinear statics using Newton-Raphson 
 - Nonlinear statics using the Arc-Length method
+- Support for unsymmetric problems, such as those involving follower forces
 
 Currently these solvers are pretty much compatible with my other repositories
 [panels](https://github.com/saullocastro/panels), 
@@ -23,7 +24,7 @@ Currently these solvers are pretty much compatible with my other repositories
 Citing this library
 ===================
 
-Saullo G. P. Castro (2026). Structural analysis solvers tailored for semi-analytical models (Version 0.4.2). Zenodo. DOI: https://doi.org/10.5281/zenodo.2581212.
+Saullo G. P. Castro (2026). Structural analysis solvers tailored for semi-analytical models (Version 0.5.0). Zenodo. DOI: https://doi.org/10.5281/zenodo.2581212.
 
 
 Documentation
@@ -38,7 +39,9 @@ History
 
 See [CHANGELOG.md](CHANGELOG.md) for the details of each version.
 
-* version 0.4.2 (2026-09-17)
+* version 0.5.0 (2026-10-01)
+    - Configuration-dependent loads and unsymmetric eigenproblems
+* version 0.4.3 (2026-09-17)
     - Fixed the eigenvalue shift of the sparse solver of `lb`, which could
       return buckling loads higher than the critical ones
     - Fixed wrong buckling loads of the sparse solver of `lb` when SciPy is

{structsolve-0.4.2 → structsolve-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "structsolve"
-version = "0.4.2"
+version = "0.5.0"
 description = "Structural analysis solvers"
 readme = "README.md"
 license = {text = "BSD-2-Clause"}
@@ -17,7 +17,7 @@ keywords = [
     "newton raphson", "arc length",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",
     "Intended Audience :: Developers",
     "Intended Audience :: Education",

{structsolve-0.4.2 → structsolve-0.5.0}/structsolve/analysis.py

@@ -1,7 +1,11 @@
 from __future__ import absolute_import
 
+import numpy as np
+
 from .static import solve
-from .logger import msg
+from .logger import msg, warn
+from . import callbacks
+from .newton_raphson import _check_convergence
 from .newton_raphson import _solver_NR
 from .arc_length_riks import _solver_arc_length_riks
 from .arc_length_crisfield import _solver_arc_length_crisfield
@@ -132,6 +136,24 @@ class Analysis(object):
         matrix with the geometric stiffness matrix at ``c``. It is called
         with ``NLgeom=True``. Required for non-linear analyses.
 
+    Notes
+    -----
+    Configuration-dependent loads, e.g. follower pressures, are supported
+    through optional keyword arguments, passed only to the callables that
+    declare them explicitly, see :mod:`.callbacks`:
+
+    - ``calc_fint(c, inc=lbd)``, ``calc_kC(c, NLgeom=True, inc=lbd)`` and
+      ``calc_kG(c, NLgeom=True, inc=lbd)`` receive the current load factor,
+      such that ``calc_fint`` may contain the configuration-dependent part of
+      the load, scaled by ``inc``, and ``calc_kC + calc_kG`` its derivative.
+    - ``calc_fext(inc=1., c=c)`` must return the load vector of the
+      configuration ``c`` for a unit load factor, the derivative of the
+      residual with respect to the load factor, used by the arc-length
+      solvers.
+
+    The tangent stiffness matrix may then be unsymmetric, which the solvers
+    support, since they use LU factorizations.
+
     Attributes
     ----------
     increments : list
@@ -189,8 +211,28 @@ class Analysis(object):
         r"""General solver for static analyses
 
         The linear analysis solves `[K_C]\{c\} = \{F_{ext}\}` using
-        :func:`.solve`. The non-linear analysis uses the solver selected by
-        the ``NL_method`` attribute.
+        :func:`.solve`. When the load depends on the configuration, i.e.
+        ``calc_fext`` declares the keyword argument ``c``, see
+        :mod:`.callbacks`, the structure is still geometrically linear but
+        the load is evaluated in the current configuration,
+        `[K_C]\{c\} = \{F_{ext}(c)\}`, which is solved by the load
+        correction iterations
+
+        .. math::
+
+            \{c_{k+1}\} = \{c_k\} + [K_C]^{-1}(\{F_{ext}(c_k)\}
+                          - [K_C]\{c_k\})
+
+        starting from the solution of the reference load, until the relative
+        criterion ``relTOL`` is satisfied, see
+        :func:`.newton_raphson._check_convergence`, or ``maxNumIter``
+        iterations are done. For a follower load whose force vector is
+        affine in `c`, `\{F(c)\} = \{F_0\} - [K_f]\{c\}`, this is the
+        solution of `([K_C] + [K_f])\{c\} = \{F_0\}`, with the
+        convergence rate of the spectral radius of `[K_C]^{-1}[K_f]`, i.e.
+        of the ratio of the load to the lowest critical load of the
+        linearized problem; beyond it the iterations diverge. The non-linear
+        analysis uses the solver selected by the ``NL_method`` attribute.
 
         Parameters
         ----------
@@ -232,6 +274,8 @@ class Analysis(object):
             k0 = self.calc_kC(silent=silent)
 
             c = solve(k0, fext, silent=silent)
+            if callbacks.is_load_configuration_dependent(self):
+                c = self._linear_static_follower(k0, c, silent)
 
             self.cs.append(c)
             self.increments.append(1.)
@@ -241,3 +285,25 @@ class Analysis(object):
 
         return self.increments, self.cs
 
+
+    def _linear_static_follower(self, k0, c, silent):
+        r"""Load correction iterations of the linear static analysis with a
+        configuration-dependent load, see :meth:`.static`"""
+        msg('Configuration-dependent load: load correction iterations',
+            level=2, silent=silent)
+        for iteration in range(1, self.maxNumIter + 1):
+            fext = self.calc_fext(inc=1., c=c, silent=True)
+            fint = k0 @ c
+            R = fext - fint
+            conv, Rnorm, Rrel = _check_convergence(self, R, fint, fext)
+            msg('Iteration: %d, relative ||R|| = %1.3e' % (iteration, Rrel),
+                level=3, silent=silent)
+            if conv:
+                return c
+            if not np.isfinite(Rnorm):
+                break
+            c = c + solve(k0, R, silent=True)
+        warn('The load correction iterations did not converge, the load may '
+             'exceed the critical load of the linearized problem', level=1,
+             silent=silent)
+        return c

{structsolve-0.4.2 → structsolve-0.5.0}/structsolve/arc_length.py

@@ -14,6 +14,7 @@ from scipy.sparse.linalg import splu
 from .logger import msg, warn
 from .static import solve
 from .sparseutils import remove_null_cols
+from . import callbacks
 from .newton_raphson import (_check_convergence, _check_divergence,
                              _NR_iterations, INC_CUT_FACTOR)
 
@@ -101,6 +102,14 @@ def _solver_arc_length(an, method, silent=False):
     - the arc length becomes smaller than ``an.minInc``
     - ``MAX_NUM_STEPS`` steps converged
 
+    When the load depends on the configuration, i.e. ``calc_fext`` accepts
+    the keyword argument ``c``, `\{F_{ext}\}` in `\{\delta c_q\}` and in the
+    tangent predictor is the load vector of the current configuration
+    ``calc_fext(inc=1., c=c)``, the derivative `\partial R/\partial
+    \lambda` of the residual, whereas `\{u_{ref}\}` remains the linear
+    solution of the reference vector. The callables that accept ``inc``
+    receive the current load factor, see :mod:`.callbacks`.
+
     The initial arc length corresponds to a load factor increment of
     ``an.initialInc`` along the initial tangent. The convergence and
     divergence checks are the same as in the Newton-Raphson solver, see
@@ -158,16 +167,15 @@ def _solver_arc_length(an, method, silent=False):
             if step_num == 1 and modified_NR and not an.kT_initial_state:
                 kT = kC0
             else:
-                kC = an.calc_kC(c=c, NLgeom=True, silent=True)
-                kG = an.calc_kG(c=c, NLgeom=True, silent=True)
-                kT = kC + kG
+                kT = callbacks.calc_kT(an, c, lbd)
             try:
                 solve_kT_conv = _factorize(kT)
             except RuntimeError:
                 warn('Singular tangent stiffness matrix at the last converged state! Analysis stopped',
                      level=1, silent=silent)
                 break
-        dc_q_conv = solve_kT_conv(fext)
+        # load vector of the converged configuration, dR/dlbd
+        dc_q_conv = solve_kT_conv(callbacks.calc_load_vector(an, c, fext))
         norm_q = np.sqrt(inner(dc_q_conv, 1., dc_q_conv, 1.))
         if arc_length is None:
             arc_length = an.initialInc*norm_q
@@ -193,7 +201,7 @@ def _solver_arc_length(an, method, silent=False):
         iteration = 0
         while True:
             iteration += 1
-            fint = an.calc_fint(c=(c + dc), silent=True)
+            fint = callbacks.calc_fint(an, c + dc, lbd + dlbd)
             fext_total = (lbd + dlbd)*fext
             R = fext_total - fint
             conv, Rnorm, Rrel = _check_convergence(an, R, fint, fext_total,
@@ -211,14 +219,13 @@ def _solver_arc_length(an, method, silent=False):
             if modified_NR and iter_kT < an.compute_every_n:
                 iter_kT += 1
             else:
-                kC = an.calc_kC(c=(c + dc), NLgeom=True, silent=True)
-                kG = an.calc_kG(c=(c + dc), NLgeom=True, silent=True)
                 try:
-                    solve_kT = _factorize(kC + kG)
+                    solve_kT = _factorize(callbacks.calc_kT(an, c + dc,
+                                                            lbd + dlbd))
                 except RuntimeError:
                     warn('Singular tangent stiffness matrix', level=2, silent=silent)
                     break
-                dc_q = solve_kT(fext)
+                dc_q = solve_kT(callbacks.calc_load_vector(an, c + dc, fext))
                 iter_kT = 1
             dc_R = solve_kT(R)
 

structsolve-0.5.0/structsolve/callbacks.py

@@ -0,0 +1,68 @@
+r"""Calls to the callables of :class:`.Analysis` used by the non-linear solvers
+
+The callables may depend on the load factor `\lambda` and on the
+configuration through their optional keyword arguments, which are passed only
+when the callable declares them explicitly in its signature (a ``**kwargs``
+does not count), such that the callables written for the previous versions
+are called exactly as before:
+
+- ``inc``: the current load factor `\lambda`, passed to ``calc_fint``,
+  ``calc_kC`` and ``calc_kG``. It allows configuration-dependent loads, e.g.
+  follower pressures, whose configuration-dependent part enters
+  ``calc_fint`` and whose load stiffness enters ``calc_kC`` or ``calc_kG``,
+  both scaled by `\lambda`. The residual remains
+
+  .. math::
+
+      \{R(c, \lambda)\} = \lambda \{F_{ext}\} - \{F_{int}(c, \lambda)\}
+
+  with ``calc_kC + calc_kG`` its exact Jacobian `-\partial R/\partial c`.
+
+- ``c``: the current configuration, passed to ``calc_fext``, which must then
+  return the load vector of that configuration for a unit load factor, i.e.
+  `\partial R/\partial \lambda` at `c`. The arc-length solvers use it in the
+  predictor and in the constraint instead of the constant reference vector
+  ``calc_fext(inc=1.)``.
+
+"""
+import inspect
+
+
+def accepts_kwarg(func, name):
+    """Tell whether ``func`` declares the keyword argument ``name``"""
+    try:
+        sig = inspect.signature(func)
+    except (TypeError, ValueError):
+        return False
+    par = sig.parameters.get(name)
+    return par is not None and par.kind in (par.POSITIONAL_OR_KEYWORD,
+                                           par.KEYWORD_ONLY)
+
+
+def calc_fint(an, c, lbd):
+    r"""``an.calc_fint`` at ``c``, with ``inc=lbd`` when accepted"""
+    kwargs = dict(inc=lbd) if accepts_kwarg(an.calc_fint, 'inc') else {}
+    return an.calc_fint(c=c, silent=True, **kwargs)
+
+
+def calc_kT(an, c, lbd):
+    r"""Tangent stiffness matrix ``calc_kC + calc_kG`` at ``c``, with
+    ``inc=lbd`` passed to the callables that accept it"""
+    kwC = dict(inc=lbd) if accepts_kwarg(an.calc_kC, 'inc') else {}
+    kwG = dict(inc=lbd) if accepts_kwarg(an.calc_kG, 'inc') else {}
+    kC = an.calc_kC(c=c, NLgeom=True, silent=True, **kwC)
+    kG = an.calc_kG(c=c, NLgeom=True, silent=True, **kwG)
+    return kC + kG
+
+
+def is_load_configuration_dependent(an):
+    """Tell whether ``an.calc_fext`` accepts the configuration ``c``"""
+    return accepts_kwarg(an.calc_fext, 'c')
+
+
+def calc_load_vector(an, c, fext):
+    r"""`\partial R/\partial \lambda` at ``c``: ``calc_fext(inc=1., c=c)``
+    when ``calc_fext`` accepts ``c``, otherwise the constant ``fext``"""
+    if is_load_configuration_dependent(an):
+        return an.calc_fext(inc=1., c=c, silent=True)
+    return fext

{structsolve-0.4.2 → structsolve-0.5.0}/structsolve/freq.py

@@ -2,8 +2,9 @@ import warnings
 
 import numpy as np
 import scipy
-from scipy.sparse.linalg import eigs, spsolve
-from scipy.linalg import eig
+from scipy.sparse import csr_matrix
+from scipy.sparse.linalg import eigs, eigsh, spsolve
+from scipy.linalg import eig, eigh
 
 from .logger import msg, warn
 from .sparseutils import remove_null_cols
@@ -29,9 +30,25 @@ def _estimate_sigma(K, M):
         return -1.
 
 
+def _residuals(K, M, lambda2, eigvecs):
+    r"""Relative residuals `||K u + \lambda^2 M u||/(||K u|| + |\lambda^2|
+    ||M u||)` of the finite eigenpairs"""
+    finite = np.isfinite(lambda2)
+    u = eigvecs[:, finite]
+    lam = lambda2[finite]
+    Ku = K @ u
+    Mu = M @ u
+    num = np.linalg.norm(Ku + Mu*lam, axis=0)
+    den = np.linalg.norm(Ku, axis=0) + np.abs(lam)*np.linalg.norm(Mu, axis=0)
+    out = np.zeros(num.shape)
+    np.divide(num, den, out=out, where=den > 0)
+    return out
+
+
 def freq(K, M, tol=0, sparse_solver=True,
         silent=False, sort=True, num_eigvalues=25,
-        num_eigvalues_print=5, skip_null_cols=False):
+        num_eigvalues_print=5, skip_null_cols=False, symmetric=False,
+        check_rtol=1e-6):
     r"""Frequency analysis
 
     Calculates the eigenvalues `\lambda^2` and eigenvectors `\{u\}` of the
@@ -80,12 +97,27 @@ def freq(K, M, tol=0, sparse_solver=True,
     skip_null_cols : bool, optional
         If True, skip the removal of null columns from the matrices.
         Use only when ``K`` and ``M`` are known to be non-singular.
+    symmetric : bool or None, optional
+        ``False``, the default, uses the general solvers described above,
+        valid for unsymmetric matrices, e.g. ``K`` with an aerodynamic matrix
+        or with the load stiffness of follower loads. ``True`` uses the
+        solvers of symmetric matrices, :func:`scipy.sparse.linalg.eigsh` in
+        shift-invert mode or :func:`scipy.linalg.eigh`, which require
+        symmetric ``K`` and ``M`` and a positive definite ``M``, and return
+        real eigenvalues and eigenvectors normalized with respect to ``M``.
+        ``None`` selects them when :func:`.linear_buckling.is_symmetric` is
+        true for both matrices.
+    check_rtol : float or None, optional
+        A warning is issued when the relative residual of an eigenpair,
+        `||K u + \lambda^2 M u||/(||K u|| + |\lambda^2| ||M u||)`, is larger
+        than ``check_rtol``. ``None`` skips the check.
 
     Returns
     -------
     lambda2 : ndarray
         Complex array with the eigenvalues `\lambda^2 = -\omega_n^2`, in the
-        order returned by the eigenvalue solver.
+        order returned by the eigenvalue solver, real with
+        ``symmetric=True``.
     eigvecs : ndarray
         The `i^{th}` eigenvector is ``eigvecs[:, i]``, with the size of the
         original matrices. The sparse solver returns eigenvectors normalized
@@ -95,6 +127,16 @@ def freq(K, M, tol=0, sparse_solver=True,
         eigenvalues in ``lambda2`` only if the solver already returned them
         in the order of increasing natural frequency.
 
+    Notes
+    -----
+    Non-conservative systems, e.g. under follower loads, may lose stability
+    by flutter, which the static criterion of :func:`.lb` does not detect:
+    with ``K`` the tangent stiffness matrix at a load level, including the
+    load stiffness, the eigenvalues `\lambda^2` of the general solvers are
+    real and negative below the flutter load and become complex conjugate
+    pairs above it, when two natural frequencies coalesce (the kinetic
+    criterion). A real positive `\lambda^2` indicates divergence.
+
     """
     msg('Running frequency analysis...', silent=silent)
 
@@ -108,7 +150,23 @@ def freq(K, M, tol=0, sparse_solver=True,
     else:
         Keff, Meff, used_cols = remove_null_cols(K, M, silent=silent,
                 level=3)
-    if sparse_solver:
+    if symmetric is None:
+        from .linear_buckling import is_symmetric
+        symmetric = is_symmetric(Keff) and is_symmetric(Meff)
+    if symmetric and sparse_solver:
+        sigma = _estimate_sigma(Keff, Meff)
+        msg('eigsh() solver (sigma={0})...'.format(sigma), level=3,
+            silent=silent)
+        eigvals, peigvecs = eigsh(A=csr_matrix(Keff), M=csr_matrix(Meff),
+                                  k=k, which='LM', tol=tol, sigma=sigma)
+        lambda2 = -eigvals
+    elif symmetric:
+        msg('eigh() solver...', level=3, silent=silent)
+        Kd = Keff.toarray() if hasattr(Keff, 'toarray') else np.asarray(Keff)
+        Md = Meff.toarray() if hasattr(Meff, 'toarray') else np.asarray(Meff)
+        eigvals, peigvecs = eigh(a=Kd, b=Md)
+        lambda2 = -eigvals
+    elif sparse_solver:
         #NOTE Looking for better performance with symmetric matrices, I tried
         #     using sparseutils.sparse.is_symmetric and eigsh, but it seems not
         #     to improve speed (I did not try passing only half of the sparse
@@ -139,6 +197,13 @@ def freq(K, M, tol=0, sparse_solver=True,
         eigvals, peigvecs = eig(a=Meff, b=Keff)
         lambda2 = -1./eigvals
 
+    if check_rtol is not None and peigvecs.shape[1]:
+        res = _residuals(Keff, Meff, lambda2, peigvecs)
+        if res.size and res.max() > check_rtol:
+            warn('freq: relative residual {0:.1e} of an eigenpair is larger '
+                 'than check_rtol={1:.1e}'.format(res.max(), check_rtol),
+                 level=2, silent=silent)
+
     if used_cols is not None:
         eigvecs = np.zeros((size, peigvecs.shape[1]), dtype=peigvecs.dtype)
         eigvecs[used_cols, :] = peigvecs
@@ -164,6 +229,13 @@ def freq(K, M, tol=0, sparse_solver=True,
     msg('first {0} eigenvalues:'.format(num_eigvalues_print), level=1,
         silent=silent)
     for lambda2i in lambda2[:num_eigvalues_print]:
-        msg('lambda**2: %1.5f, natural frequency: %1.5f rad/s' % (lambda2i, (-lambda2i)**0.5), level=2, silent=silent)
+        #NOTE complex for non-conservative systems, e.g. beyond flutter
+        omegan = np.sqrt(-complex(lambda2i))
+        if np.iscomplexobj(lambda2) and abs(complex(lambda2i).imag) > 0:
+            msg('lambda**2: {0:.5g}, natural frequency: {1:.5g} rad/s'.format(
+                complex(lambda2i), omegan), level=2, silent=silent)
+        else:
+            msg('lambda**2: %1.5f, natural frequency: %1.5f rad/s'
+                % (np.real(lambda2i), omegan.real), level=2, silent=silent)
 
     return lambda2, eigvecs