:orphan:

Tutorials
=========

This section contains :ref:`a series of tutorial notebooks <tutorial-notebooks-label>` which go through some of the
key features of the ``S2FFT`` package.

At a high-level the ``S2FFT`` package is structured such that the two primary transforms,
the Wigner and spherical harmonic transforms, can easily be accessed.

Core usage |:rocket:|
---------------------

To import and use ``S2FFT`` is as simple follows: 

+-------------------------------------------------------+------------------------------------------------------------+
|For a signal on the sphere                             |For a signal on the rotation group                          |
|                                                       |                                                            |
|.. code-block:: Python                                 |.. code-block:: Python                                      |
|                                                       |                                                            |
|   import s2fft                                        |   import s2fft                                             |
|                                                       |                                                            |
|   # Specify sampled signal and harmonic bandlimit     |   # Define sampled signal, harmonic & azimuthal bandlimits |
|   f = ...                                             |   f = ...                                                  |
|   L = ...                                             |   L, N = ...                                               |
|                                                       |                                                            |
|   # Compute harmonic coefficients                     |   # Compute Wigner coefficients                            |
|   flm = s2fft.forward(f, L, method="jax")             |   flmn = s2fft.wigner.forward(f, L, N, method="jax")       |
|                                                       |                                                            |
|   # Map back to pixel-space signal                    |   # Map back to pixel-space signal                         |
|   f = s2fft.inverse(flm, L, method="jax")             |   f = s2fft.wigner.inverse(flmn, L, N, method="jax")       |
+-------------------------------------------------------+------------------------------------------------------------+

.. _tutorial-notebooks-label:

Tutorial notebooks
------------------

Below are a few short tutorials that cover how to use specific features of ``S2FFT``.

We also have a notebook demonstrating how to use CUDA-accelerated HEALPix spherical harmonic transforms in ``S2FFT``, which `is accessible in notebook format here <https://github.com/astro-informatics/s2fft/blob/main/notebooks/JAX_CUDA_HEALPix.ipynb>`_, or alternatively can be `opened in Google Colab <https://colab.research.google.com/github/astro-informatics/s2fft/blob/main/notebooks/JAX_CUDA_HEALPix.ipynb>`_.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates how to use S2FFT to rotate a signal on the sphere.">

.. only:: html

  .. image:: /tutorials/images/thumb/sphx_glr_spherical_rotation_thumb.png
    :alt:

  :doc:`/tutorials/spherical_rotation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Rotate a signal</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This minimal tutorial demonstrates how to use the torch frontend for S2FFT to compute spherical harmonic transforms.">

.. only:: html

  .. image:: /tutorials/images/thumb/sphx_glr_torch_frontend_thumb.png
    :alt:

  :doc:`/tutorials/torch_frontend`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Torch frontend guide</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates how to use S2FFT to compute spherical harmonic transforms.">

.. only:: html

  .. image:: /tutorials/images/thumb/sphx_glr_spherical_harmonic_transform_thumb.png
    :alt:

  :doc:`/tutorials/spherical_harmonic_transform`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Spherical harmonic transform</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This short tutorial demonstrates how to use the custom JAX frontend support S2FFT provides for the SSHT C library.">

.. only:: html

  .. image:: /tutorials/images/thumb/sphx_glr_JAX_SSHT_frontend_thumb.png
    :alt:

  :doc:`/tutorials/JAX_SSHT_frontend`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">JAX SSHT frontend</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates how to use S2FFT to compute Wigner transforms, i.e. Fourier transforms on the rotation group SO(3).">

.. only:: html

  .. image:: /tutorials/images/thumb/sphx_glr_wigner_transform_thumb.png
    :alt:

  :doc:`/tutorials/wigner_transform`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Wigner transform</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This short tutorial demonstrates how to use the custom JAX frontend support S2FFT provides for the HEALPix C++ library.">

.. only:: html

  .. image:: /tutorials/images/thumb/sphx_glr_JAX_HEALPix_frontend_thumb.png
    :alt:

  :doc:`/tutorials/JAX_HEALPix_frontend`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">JAX HEALPix Frontend</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /tutorials/spherical_rotation
   /tutorials/torch_frontend
   /tutorials/spherical_harmonic_transform
   /tutorials/JAX_SSHT_frontend
   /tutorials/wigner_transform
   /tutorials/JAX_HEALPix_frontend


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: tutorials_python.zip </tutorials/tutorials_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: tutorials_jupyter.zip </tutorials/tutorials_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_