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.
Making a broadband telescope point spread function
Level: Beginner
Description: We will introduce the basic elements in HCIPy and produce a broadband point spread function for the Magellan telescope.
Core Concepts: Grids and Fields
Level: Beginner
Description: In this notebook we’ll explore grids and fields, the two fundamental data structures in HCIPy. Grids define the spatial coordinates where we evaluate optical elements, and fields store physical quantities like electric field amplitude or phase at those points.
Core Concepts: Wavefronts and Optical Elements
Level: Beginner
Description: We’ll explore the Wavefront object and how optical elements transform wavefronts through amplitude and phase modifications. We’ll propagate wavefronts in different regimes and build a simple optical system.
Introduction to coupling light into optical fibers
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.
Near and far-field diffraction
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.
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.
Level: Beginner
Description: We will introduce the core elements in HCIPy (Grids and Fields) and will generate telescope pupils for all telescopes included in HCIPy.
Imaging with a vector-Apodizing Phase Plate coronagraph
Level: Beginner
Description: We will introduce the propagation of polarized light through a vector apodizing phase plate coronagraph (vAPP).
Imaging with a vortex coronagraph
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.
Simulating Atmospheric Turbulence
Level: Intermediate
Description: We’ll model how Earth’s atmosphere distorts starlight using HCIPy’s phase screen framework, from single-layer models to realistic multi-layer atmospheric profiles.
Level: Intermediate
Description: We will show how to use the configuration system of HCIPy: what it is and when to use it, how to read and change configuration values, both from within Python, from a configuration file, and from environment variables, and how to react to changes to the configuration.
Level: Intermediate
Description: We will implement a basic electric field conjugation with pairwise probing of the electric field using an optical system with both phase and amplitude aberrations and two deformable mirrors for correction.
Working with Fourier Transforms
Level: Intermediate
Description: This tutorial explores Fourier transforms in HCIPy, from basic usage to advanced techniques. Fourier transforms are fundamental to optical simulations—they let us propagate light between pupil and focal planes, analyze spatial frequencies, filter images, calculate PSFs and MTFs, and perform image registration via shifts, rotations, and distortions.
Level: Intermediate
Description: In optical simulations we often need to resample fields between grids of different resolution or structure. This notebook covers linear and nearest-neighbor interpolation, boundary handling, and working with unstructured grids in HCIPy. Fields can be complex-valued (as is common in optical simulations with amplitude and phase); interpolation works component-wise on the real and imaginary parts.
Wavefront sensing with a Pyramid wavefront sensor
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.
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.
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.
Design of vector-Apodizing Phase Plate patterns
Level: Intermediate
Description: This tutorial introduces the basics of designing a phase pattern for a vector-Apodizing Phase Plate (vAPP) coronagraph.
Simultaneous phase and amplitude aberration sensing with a vector-Zernike wavefront sensor
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.
Creating your own optical elements
Level: Advanced
Description: We will present the internal workings of optical elements, and show how you can create your own optical elements in HCIPy.
Adaptive optics with a Shack-Hartmann wavefront sensor
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.