Linear buckling analysis
========================

.. note::

    Linear buckling is **planned** but not yet shipped in
    femorph-solver as of v0.18.x.  This page documents the
    intended API + theory so users coming from MAPDL or
    NASTRAN can plan their migration; the actual solver path
    will land in a future release.  Track progress on the
    `roadmap <https://github.com/femorph/solver/projects>`_.

When to use (when shipped)
--------------------------

Linear buckling answers **"at what load multiplier does the
structure first lose stability?"**.  Use it when:

- You're sizing a slender column / shell against Euler-type
  bifurcation buckling.
- You need a conservative collapse-load estimate before
  committing to non-linear post-buckling analysis.
- Industry codes (Eurocode 3, AISC 360) ask for the
  classical-buckling check as an intermediate step.

For pre-stressed modal analysis (a different but related
eigenproblem) use the future pre-stressed :doc:`modal` path.
For non-linear post-buckling, you'll need the geometric-
non-linearity solver — also planned.

Boundary conditions and loads
-----------------------------

- **Reference static load** — the load case that produces
  the pre-stress field.  Run it through :doc:`linear-static`
  first; the recovered displacements feed into the
  geometric-stiffness assembly.
- **Dirichlet constraints** — same as :doc:`linear-static`.

The math (one paragraph)
------------------------

Linear buckling solves the **eigenvalue problem**

.. math::

    \bigl(\mathbf{K} + \lambda\, \mathbf{K}_g(\mathbf{u}_0)\bigr)\,
    \boldsymbol{\phi} = \mathbf{0},

where :math:`\mathbf{K}_g(\mathbf{u}_0)` is the geometric
stiffness assembled from the pre-stress field
:math:`\mathbf{u}_0` recovered by the reference static
solve.  The smallest positive eigenvalue :math:`\lambda_1`
is the **load multiplier at the first bifurcation**; the
buckling load is :math:`\lambda_1 \times` the reference
load.

Roadmap status
--------------

- Geometric-stiffness kernel for HEX8: planned for the next
  major release.
- ``Model.buckling_solve()`` API: planned alongside
  geometric-stiffness kernel.
- Pre-stressed modal (the related but different eigenproblem
  on :math:`(\mathbf{K} + \mathbf{K}_g)`): planned in the
  same release.

Cross-vendor naming
-------------------

==========================  ==============================  ============================================
femorph-solver               ANSYS Mechanical APDL           Cross-vendor equivalents
==========================  ==============================  ============================================
linear buckling (planned)    ``ANTYPE, BUCKLE``              NASTRAN ``SOL 105``; Abaqus ``*BUCKLE``; LS-DYNA ``*CONTROL_IMPLICIT_BUCKLE``
==========================  ==============================  ============================================

See :doc:`/interop/terminology` for the full Rosetta.

In the meantime
---------------

If you have a buckling-sensitive design today and need a
femorph-solver-based check before the linear-buckling solver
ships, the workarounds are:

1. **Run a linear static + slenderness check** by hand:
   recover :math:`\sigma_\text{cr}^\text{Euler} = \pi^{2}\,
   E\, I / (K\, L)^{2}` from the geometry and compare against
   the recovered :math:`\sigma`.  Conservative but immediate.
2. **Run a frequency-loaded transient** :
   apply the load slowly and watch for runaway displacement
   as :math:`P \to P_\text{cr}`.  Indirect but indicative.
3. **Round-trip through MAPDL** via the CDB / RST path:
   run the buckling solve in MAPDL, read the buckling-mode
   eigenvectors back in, post-process the mode shapes in
   femorph-solver.  The
   :doc:`/getting-started/mapdl-interop` reader handles the
   CDB; the RST reader handles the result.