.. _GSH:
.. index:: Generalized Spherical Harmonics

Generalized Spherical Harmonics
*******************************

The generalized spherical harmonics model expands the ODF as a sum of harmonic functions in :math:`\mathrm{SO}(3)` symmetrized by the crystal point group. They are convewnient because they split the ODF in different resolutions parametrized by the spherical harmonics order :math:`ell`. The model can be initialized from:

#. A maximum spherical harmoncis order :math:`\ell_{\mathrm{max}}`
#. A list of symmetrized sperical surface harmonics correspinding to the crystal point group.

The Symmetrized harmics can be generated by functions from the :py:mod:`odftt.spharm.symmetrized_harmonics_coefficients` module.

While the GSHs are typically not the best choice for texture tomography reconstructions, they are used to perform some other computations efficiently. `odftt` uses a version of the GSHs that are completely real from definition following `Schaeben and van den Boogart 2003 <https://doi.org/10.1016/S0040-1951(03)00190-2>`_.

If we treat the property of the Wigner matrixes to be able to rotate real-spherical-harmonics-coefficients as a definition, the phase convention of the Wigner matrices is set by the choice of phase constants and normalization for the surface harmonics. We have chosen the same as are used in `mumott <https://mumott.org>`_ to ensure interoperability.

Full GSH coefficients are represented as lists of square matrixes while symmetrized coefficients should be interpreted in terms of a :py:obj:`odftt.texture.odfs.Harmonics` object which uses a single 1D vector where each element is the coefficient of one symmetrized mode. The property `odf.mode_coefficients` is a list of the full RBF coefficients of each symmetrized mode. `odf.make_GSH_coeffs` provides a utility to transform symmetrized mode coefficient vectors into full GSH basis.


.. figure:: img/cubic_surface_harmonic.png

    An example of a cubic-symmetric surface harmonic used in the definition of symmetrized GSHs.

.. toctree::
   :maxdepth: 1
   :caption: Jupyter notebooks:

   notebooks/demonstration_harmonics

Function reference
------------------

.. autoclass:: odftt.texture.odfs.Harmonics
   :members:
   :member-order: bysource