Cyclic-symmetry modal analysis
==============================

Free-vibration modal analysis on a single base sector of an
:math:`N`-fold cyclically-symmetric rotor.  Driven by
:meth:`CyclicModel.solve_modal
<femorph_solver.CyclicModel.solve_modal>`.

Algorithm
---------

For a rotor of :math:`N` identical sectors, the global
spectrum decomposes per **harmonic index**
:math:`k \in \{0, 1, \ldots, N/2\}` (Thomas 1979; Wildheim
1979).  Each harmonic produces a reduced complex-Hermitian
sub-problem on the base sector

.. math::
    :label: cyclic-gevp

    \mathbf{K}_k\, \boldsymbol{\phi}_k =
    \omega^{2}\, \mathbf{M}_k\, \boldsymbol{\phi}_k,

with the cyclic boundary condition
:math:`\mathbf{u}_\text{high} = e^{\imath\, k\, \alpha}\,
\mathbf{R}(\alpha)\, \mathbf{u}_\text{low}`,
:math:`\alpha = 2\pi / N`.

femorph-solver applies the **Grimes–Lewis–Simon (1994) real
2n-augmentation** to recast each complex-Hermitian sub-problem
as a real-symmetric problem of doubled size:

.. math::

    \tilde{\mathbf{K}}_{k} =
    \begin{bmatrix}
        \mathrm{Re}(\mathbf{K}_{k}) & -\mathrm{Im}(\mathbf{K}_{k}) \\
        \mathrm{Im}(\mathbf{K}_{k}) & \mathrm{Re}(\mathbf{K}_{k})
    \end{bmatrix},
    \qquad
    \tilde{\mathbf{M}}_{k} = \cdots,

then dispatches to the same shift-invert Lanczos pipeline as
the :doc:`modal` solver.  Each eigenvalue appears with
multiplicity 2 in the augmented problem; the eigenvectors
recombine into a complex pair on the way out.

For :math:`k = 0` and (when :math:`N` is even) :math:`k = N/2`
the imaginary block is identically zero and the augmentation
collapses to two copies of the same real eigenvalue.  For
:math:`0 < k < N/2` the two halves form a **travelling-wave
pair** — the real / imaginary parts of
:math:`\boldsymbol{\phi}_k` are 90°-shifted snapshots of a
wave travelling around the rotor's circumference.

Public API
----------

The high-level entry is
:meth:`CyclicModel.solve_modal <femorph_solver.CyclicModel.solve_modal>`
on a :class:`~femorph_solver.CyclicModel` wrapper around a
single-sector :class:`~femorph_solver.Model`:

.. code-block:: python

    from femorph_solver import CyclicModel
    cm = CyclicModel.wrap(model, n_sectors=N)         # auto-detects faces
    # ... or pass explicit pre-paired indices:
    # cm = CyclicModel.wrap(model, low_face=low, high_face=high, n_sectors=N)
    results = cm.solve_modal(n_modes=10)              # one per harmonic

Or load a CDB deck directly:

.. code-block:: python

    cm = CyclicModel.from_cdb("rotor_sector.cdb")
    results = cm.solve_modal(n_modes=10)

For low-level use (when you already hold ``K`` / ``M`` and DOF-indexed
face arrays), call
:func:`solve_cyclic <femorph_solver.solvers.cyclic.solve_cyclic>`
directly.

* ``n_sectors`` — number of sectors :math:`N`.
* ``harmonic_indices`` — defaults to all of
  :math:`0, 1, \ldots, N/2`.
* Returns one
  :class:`CyclicModalResult <femorph_solver.solvers.cyclic.CyclicModalResult>`
  per harmonic index, each carrying ``omega_sq``, ``frequency``,
  complex ``mode_shapes`` on the base sector, and the
  ``harmonic_index`` metadata.

Verification cross-references
-----------------------------

* :ref:`sphx_glr_gallery_analyses_cyclic_example_rotor_sector.py` — 4-sector annular sector full sweep.
* :ref:`sphx_glr_gallery_analyses_cyclic_example_cyclic_modes_disk.py` — 12-sector annular disk, lowest mode per harmonic.
* :ref:`sphx_glr_gallery_analyses_cyclic_example_cyclic_modes_bladed_rotor.py` — 16-blade rotor, travelling-wave pair render.
* :ref:`sphx_glr_gallery_analyses_cyclic_example_cyclic_mode_family.py` — 4×2 viewport grid of the disk mode family classified by harmonic index.

Implementation: :mod:`femorph_solver.solvers.cyclic`.

References
----------

* Thomas, D. L. (1979) "Dynamics of rotationally periodic
  structures," *Journal of Sound and Vibration* 66 (4),
  585–597.
* Wildheim, S. J. (1979) "Vibrations of rotationally periodic
  structures," Ph.D. dissertation, Linköping University.
* Grimes, R. G., Lewis, J. G. and Simon, H. D. (1994) "A
  shifted block Lanczos algorithm for solving sparse symmetric
  generalized eigenproblems," *SIAM J. Matrix Analysis and
  Applications* 15 (1), 228–272 (real 2n augmentation).
* Bathe, K.-J. (2014) *Finite Element Procedures*, 2nd ed.,
  §10.3.4 (cyclic-symmetry modal).
* Crandall, S. H. and Mark, W. D. (1963) *Random Vibration
  in Mechanical Systems*, Academic Press, §3.5 (travelling-
  wave / standing-wave decomposition).
* Singh, M. P. and Vakakis, A. F. (1993) "On the dynamics of
  cyclic-symmetric structures," *Mechanism and Machine
  Theory* 28 (5), 627–637 (mode classification by harmonic
  index).