Projection Matrix Module

synim.synpm.projection_matrix(pup_diam_m, pup_mask, dm_array, dm_mask, base_inv_array, dm_height, dm_rotation, base_rotation, base_translation, base_magnification, gs_pol_coo, gs_height, verbose=False, specula_convention=True, specula_convention_inv=False)

Computes a projection matrix for DM modes onto a desired basis. Uses intelligent workflow selection like interaction_matrix.

Parameters: - pup_diam_m: float, size in m of the side of the pupil - pup_mask: numpy 2D array, pupil mask (n_pup x n_pup) - dm_array: numpy 3D array, Deformable Mirror 2D shapes (n x n x n_dm_modes) - dm_mask: numpy 2D array, DM mask (n x n) - base_inv_array: numpy 2D or 3D array, inverted basis for projection

Can be: - 2D: (nmodes, npixels_valid) - IFunc format - 2D: (npixels_valid, nmodes) - IFuncInv format - 3D: (npix, npix, nmodes) - full 3D array

  • dm_height: float, conjugation altitude of the Deformable Mirror

  • dm_rotation: float, rotation in deg of the Deformable Mirror with respect to the pupil

  • base_rotation: float, rotation of the basis in deg

  • base_translation: tuple, translation of the basis (x, y) in pixels

  • base_magnification: tuple, magnification of the basis (x, y)

  • gs_pol_coo: tuple, polar coordinates of the guide star radius in arcsec and angle in deg

  • gs_height: float, altitude of the guide star

  • verbose: bool, optional, display verbose output

  • specula_convention: bool, optional, use SPECULA convention (transpose arrays)

  • specula_convention_inv: bool, optional, use SPECULA convention for base_inv_array

Returns: - projection: numpy 2D array, projection matrix (n_dm_modes, n_base_modes)

Workflow Selection: - SEPARATED: Used when EITHER DM OR Base has transformations (not both)

Applies transformations in 2 steps (more flexible)

  • COMBINED: Used when BOTH DM AND Base have transformations

    Applies transformations in 1 step (avoids double interpolation)

synim.synpm.transpose_base_array_for_specula(base_inv_array, pup_mask_original, verbose=False)

Transpose base_inv_array for SPECULA convention.

CRITICAL: Requires the ORIGINAL (non-transposed) pupil mask to correctly extract and re-map pixel indices after transposition.

Handles both 2D and 3D base arrays: - 3D arrays: simple transpose (height, width, nmodes) → (width, height, nmodes) - 2D arrays: reconstructs 3D using ORIGINAL mask, transposes, then re-extracts

Parameters: - base_inv_array: 2D or 3D numpy array

  • 2D can be: (nmodes, npixels_total) [IFunc] or (npixels_total, nmodes) [IFuncInv]

  • 3D: (height, width, nmodes)

  • pup_mask_original: numpy 2D array, ORIGINAL (non-transposed) pupil mask

  • verbose: bool, print debug information

Returns: - transposed_array: numpy array with swapped X-Y coordinates