Tutorials
=========

These tutorials demonstrate the features of HCIPy in the context of a standard workflow. Tutorials are separated in three categories, depending on the required level of familiarity with HCIPy.

Beginner
--------

These tutorials provide an introduction to the basic parts of HCIPy. New users should read these tutorials to get started with HCIPy.

.. toctree::
    :maxdepth: 1
    :hidden:

    BroadbandTelescopePSF/BroadbandTelescopePSF
    FiberCoupling/FiberCoupling
    NearFarFieldDiffraction/NearFarFieldDiffraction
    PolarizationIntro/PolarizationIntro
    VectorApodizingPhasePlate/VectorApodizingPhasePlate
    VortexCoronagraph/VortexCoronagraph



.. only:: html

	.. container:: tutorial_item

		:doc:`Making a broadband telescope point spread function <BroadbandTelescopePSF/BroadbandTelescopePSF>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: BroadbandTelescopePSF/thumb.png

			.. container:: tutorial_description

				**Level:** Beginner

				**Description:** We will introduce the basic elements in HCIPy and produce a broadband point spread function for the Magellan telescope.

.. only:: html

	.. container:: tutorial_item

		:doc:`Introduction to coupling light into optical fibers <FiberCoupling/FiberCoupling>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: FiberCoupling/thumb.png

			.. container:: tutorial_description

				**Level:** Beginner

				**Description:** In high-contrast imaging we usually only consider the propagation of electric fields in homogenous media, such as air or lenses. In this tutorial we will show how to work with optical fibers, which propagate a different set of mode bases. We start by importing the required libraries and defining some unit constants.

.. only:: html

	.. container:: tutorial_item

		:doc:`Near and far-field diffraction <NearFarFieldDiffraction/NearFarFieldDiffraction>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: NearFarFieldDiffraction/thumb.png

			.. container:: tutorial_description

				**Level:** Beginner

				**Description:** We will demonstrate the near and far-field propagators in HCIPy. We'll use both a circular aperture and the LUVOIR-A telescope pupil as example pupils.

.. only:: html

	.. container:: tutorial_item

		:doc:`Introduction to polarization <PolarizationIntro/PolarizationIntro>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: PolarizationIntro/thumb.png

			.. container:: tutorial_description

				**Level:** Beginner

				**Description:** We will introduce how polarization is simulated in HCIPy, both for full and partially polarized light. We will show which polarization optical elements are implemented and how these are used.

.. only:: html

	.. container:: tutorial_item

		:doc:`Imaging with a vector-Apodizing Phase Plate coronagraph <VectorApodizingPhasePlate/VectorApodizingPhasePlate>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: VectorApodizingPhasePlate/thumb.png

			.. container:: tutorial_description

				**Level:** Beginner

				**Description:** We will introduce the propagation of polarized light through a vector apodizing phase plate coronagraph (vAPP).

.. only:: html

	.. container:: tutorial_item

		:doc:`Imaging with a vortex coronagraph <VortexCoronagraph/VortexCoronagraph>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: VortexCoronagraph/thumb.png

			.. container:: tutorial_description

				**Level:** Beginner

				**Description:** We will simulate on-axis and off-axis images of stars through a (ring-apodized) vortex coronagraph.

Intermediate
------------

These tutorials show the main functionality using the built-in classes of HCIPy. These tutorials focus on one aspect of high-contrast imaging.

.. toctree::
    :maxdepth: 1
    :hidden:

    ElectricFieldConjugation/ElectricFieldConjugation
    PyramidWFS/PyramidWFS
    SegmentedDMs/SegmentedDMs
    SimplePolarimeter/SimplePolarimeter
    VectorApodizingPhasePlateDesign/VectorApodizingPhasePlateDesign
    VectorZernikeWavefrontSensor/VectorZernikeWavefrontSensor



.. only:: html

	.. container:: tutorial_item

		:doc:`Electric Field Conjugation <ElectricFieldConjugation/ElectricFieldConjugation>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: ElectricFieldConjugation/thumb.png

			.. container:: tutorial_description

				**Level:** Intermediate

				**Description:** We will implement a basic electric field conjugation with pairwise probing of the electric field. We will use an optical system with both phase and amplitude aberrations, and 2 deformable mirrors for correction.

.. only:: html

	.. container:: tutorial_item

		:doc:`Wavefront sensing with a Pyramid wavefront sensor <PyramidWFS/PyramidWFS>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: PyramidWFS/thumb.png

			.. container:: tutorial_description

				**Level:** Intermediate

				**Description:** We will simulate a closed-loop adaptive optics system, based on the the Magellan Adaptive Optics Extreme (MagAO-X) system, that uses an unmodulated pyramid wavefront sensor with a 2k-MEMS DM.

.. only:: html

	.. container:: tutorial_item

		:doc:`Segmented deformable mirrors <SegmentedDMs/SegmentedDMs>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: SegmentedDMs/thumb.png

			.. container:: tutorial_description

				**Level:** Intermediate

				**Description:** We will use segmented deformable mirrors and simulate the PSFs that result from segment pistons and tilts. We will compare this functionality against Poppy, another optical propagation package.

.. only:: html

	.. container:: tutorial_item

		:doc:`Simple polarimeter <SimplePolarimeter/SimplePolarimeter>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: SimplePolarimeter/thumb.png

			.. container:: tutorial_description

				**Level:** Intermediate

				**Description:** We will simulate a simple polarimeter that measures linear polarization states. In this example we will use this polarimeter to measure the polarization state of starlight.

.. only:: html

	.. container:: tutorial_item

		:doc:`Design of vector-Apodizing Phase Plate patterns <VectorApodizingPhasePlateDesign/VectorApodizingPhasePlateDesign>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: VectorApodizingPhasePlateDesign/thumb.png

			.. container:: tutorial_description

				**Level:** Intermediate

				**Description:** This tutorial introduces the basics of designing a phase pattern for a vector-Apodizing Phase Plate (vAPP) coronagraph.

.. only:: html

	.. container:: tutorial_item

		:doc:`Simultaneous phase and amplitude aberration sensing with a vector-Zernike wavefront sensor <VectorZernikeWavefrontSensor/VectorZernikeWavefrontSensor>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: VectorZernikeWavefrontSensor/thumb.png

			.. container:: tutorial_description

				**Level:** Intermediate

				**Description:** We will introduce the classical Zernike wavefront sensor (ZWFS) and a way to reconstruct phase aberrations. Then we will introduce the vector-Zernike WFS (vZWFS) and show how this version allows for simultaneous phase and amplitude aberration sensing.

Advanced
--------
These tutorials show how to use HCIPy for your own research. This includes extending HCIPy with your own optical elements and advanced use cases.

.. toctree::
    :maxdepth: 1
    :hidden:

    CreatingYourOwnOpticalElements/CreatingYourOwnOpticalElements
    ShackHartmannWFS/ShackHartmannWFS



.. only:: html

	.. container:: tutorial_item

		:doc:`Creating your own optical elements <CreatingYourOwnOpticalElements/CreatingYourOwnOpticalElements>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: CreatingYourOwnOpticalElements/thumb.png

			.. container:: tutorial_description

				**Level:** Advanced

				**Description:** We will present the internal workings of optical elements, and show how you can create your own optical elements in HCIPy.

.. only:: html

	.. container:: tutorial_item

		:doc:`Adaptive optics with a Shack-Hartmann wavefront sensor <ShackHartmannWFS/ShackHartmannWFS>`

		.. container:: tutorial_row

			.. container:: tutorial_thumbnail

				.. figure:: ShackHartmannWFS/thumb.png

			.. container:: tutorial_description

				**Level:** Advanced

				**Description:** We will simulate a closed-loop adaptive optics system, based on the the Spectro-Polarimetric High-contrast Exoplanet REsearch (SPHERE) adaptive optics (AO) system, that uses a Shack-Hartmann WFS. We will simulate calibration and on-sky operation of this simulated AO system.