Pyramid WFS

Overview

The Pyramid class implements a Pyramid Wavefront Sensor (PWFS). A four-faced glass pyramid prism placed at the telescope focal plane performs amplitude filtering of the electromagnetic field, splitting it into four pupil images on a detector. The WFS signals are derived from the intensity distribution across these four pupils.

The filtering is a Fourier-plane operation: the pyramid mask modulates the focal-plane amplitude, and the four pupil images are the result of this filtering. This is fundamentally different from a direct gradient measurement.

Modulation — the star is continuously tip-tilt modulated around the pyramid tip in a circle of radius modulation λ/D. This averages the Fourier filtering over a range of focal-plane positions, extending the linear regime of the sensor and making it effective even when phase aberrations are large.

Rooftop

The rooftop parameter models a manufacturing defect at the apex of the pyramid prism — instead of a perfect four-faced pyramid with four triangular faces meeting at a point, the prism has two triangular faces and two trapezoidal faces. The rooftop is oriented diagonally by default. The theta_rotation parameter rotates the entire mask (and hence the pupil image positions) around the optical axis.

Signal post-processing

The raw detector frame is processed into a 1-D signal vector and a 2-D representation of the WFS signals. Several normalisation conventions are available via the postProcessing parameter.

GPU acceleration

The Pyramid is the only OOPAO class with existing GPU (CuPy) acceleration. When CuPy is installed, the FFT operations inside the modulation loop run on GPU automatically.

Quick start

from OOPAO.Pyramid import Pyramid

wfs = Pyramid(
    nSubap        = 20,
    telescope     = tel,
    modulation    = 3.0,    # lambda/D
    lightRatio    = 0.5,
)

# Propagate light (updates wfs.signal)
ngs * tel * wfs

# Access WFS signals
print(wfs.signal)           # 1-D signal vector
print(wfs.signal_2D)        # 2-D representation of WFS signals
print(wfs.cam.frame)        # raw detector frame

# Enable photon noise
wfs.cam.photonNoise = True

# Switch to full-frame output
wfs.postProcessing = 'fullFrame'

API reference

class OOPAO.Pyramid.Pyramid(nSubap, telescope, modulation, lightRatio, postProcessing='slopesMaps', psfCentering=True, n_pix_separation=2.0, calibModulation=50.0, n_pix_edge=None, extraModulationFactor=0, binning=1, nTheta_user_defined=None, userValidSignal=None, old_mask=False, rooftop=0, theta_rotation=0, delta_theta=0.0, user_modulation_path=None, pupilSeparationRatio=None, edgePixel=None, zeroPadding=None)[source]

Pyramid Wavefront Sensor with focal-plane amplitude filtering and optional modulation.

Parameters:

  • nSubap (float) – Diameter of each pyramid pupil image in detector pixels.

  • telescope (Telescope) – Associated telescope object (carries phase, flux, and pupil information).

  • modulation (float) – Tip-tilt modulation radius in λ/D units.

  • lightRatio (float) – Minimum fractional illumination threshold to select valid subapertures.

  • postProcessing (str) –

    Signal computation mode. Options:

    • 'slopesMaps' — normalised WFS signals (default).

    • 'fullFrame' — raw detector frame.

    • 'slopesMaps_incidence_flux' — WFS signals normalised by incident flux.

    • 'slopesMaps_sum_flux' — WFS signals normalised by total flux sum.

    • 'fullFrame_incidence_flux', 'fullFrame_sum_flux' — full-frame variants.

  • psfCentering (bool) – If True, pyramid mask is centred on 4 pixels (default). If False, centred on 1 pixel.

  • n_pix_separation (float) – Pixel gap between the four pyramid pupil images. Default 2.

  • calibModulation (float) – Large modulation radius (λ/D) used at calibration to identify valid pixels. Default 50.

  • n_pix_edge (float or None) – Edge padding in pixels around each pupil image. Defaults to n_pix_separation / 2.

  • extraModulationFactor (int) – Extra modulation points per quadrant (1 adds 4 points total). Default 0.

  • binning (int) – Detector binning factor. Default 1.

  • nTheta_user_defined (int or None) – Override the number of modulation steps. Default None (automatic from modulation).

  • userValidSignal (numpy.ndarray or None) – User-defined boolean mask for valid pixels. Default None.

  • old_mask (bool) – Use the legacy pyramid mask (local tip/tilt shifts). Default False.

  • rooftop (float) – Models a manufacturing defect at the apex of the pyramid prism, where two triangular faces are replaced by two trapezoidal faces. The value defines the width of the flat region in λ/D. The rooftop is oriented diagonally by default. Default 0 (perfect four-triangular-face pyramid).

  • theta_rotation (float) – Rotation angle of the pyramid mask in radians, which rotates the pupil image positions accordingly. Incompatible with old_mask=True. Default 0.

  • delta_theta (float) – Angular offset for modulation points. Default 0.0.

  • user_modulation_path (list or None) – Custom list of [x, y] modulation coordinates in λ/D. Default None.

  • pupilSeparationRatio (float or None) – Deprecated. Use n_pix_separation instead.

  • edgePixel (int or None) – Deprecated. Use n_pix_edge instead.

  • zeroPadding (int or None) – Manual override for the zero-padding size. Default None (automatic).

Key properties

signal: numpy.ndarray

1-D WFS signal vector (valid pixels only) after the current propagation.

signal_2D: numpy.ndarray

2-D representation of the WFS signals.

nSignal: int

Length of the signal vector (number of valid measurement pixels).

validPixelsMask: numpy.ndarray

Boolean 2-D mask identifying valid detector pixels.

cam: Detector

Built-in detector object. Use to set noise properties (cam.photonNoise, cam.readoutNoise, etc.).

focal_plane_camera: Detector

Focal-plane camera at the pyramid tip. Used with GainSensingCamera.

postProcessing: str

Signal post-processing mode. Can be changed between propagations.

modulation: float

Current modulation radius in λ/D. Changing this triggers recomputation of the modulation path.

mask: numpy.ndarray

Complex 2-D pyramid mask applied in the focal plane.

nTheta: int

Number of modulation steps used per frame.

Methods

relay(src)[source]

Core propagation method. Called automatically by src * wfs. Performs the focal-plane amplitude filtering for each modulation step and computes the WFS signals.

Parameters:

src (Source or Asterism) – Source or Asterism being propagated.

set_binning(binning)

Apply a new detector binning factor and recompute the valid pixel mask.

Parameters:

binning (int) – New binning factor.

Operator summary

Expression

Effect

ngs * tel * wfs

Propagate through telescope then PWFS

ngs ** atm * tel * wfs

Full reset + atmosphere + telescope + PWFS

wfs * wfs.focal_plane_camera

Forward PSF to focal-plane camera

Note

GPU acceleration is activated automatically when CuPy is installed. The FFT operations inside the modulation loop run on GPU; all other computations remain on CPU. Full GPU support across all classes is not yet implemented.