Interaction Matrix Module

synim.synim.apply_dm_transformations_combined(pup_diam_m, pup_mask, dm_array, dm_mask, dm_height, dm_rotation, gs_pol_coo, gs_height, wfs_rotation, wfs_translation, wfs_nsubaps=None, wfs_mag_global=1.0, wfs_anamorphosis_90=1.0, wfs_anamorphosis_45=1.0, slope_method='derivatives', specula_convention=True, verbose=False)

Apply DM and WFS transformations COMBINED (single interpolation step). This avoids cumulative interpolation errors when both DM and WFS have rotations.

synim.synim.apply_dm_transformations_separated(pup_diam_m, pup_mask, dm_array, dm_mask, dm_height, dm_rotation, gs_pol_coo, gs_height, wfs_nsubaps=None, slope_method='derivatives', specula_convention=True, verbose=False)

Apply ONLY DM transformations (for separated workflow). Returns slopes/derivatives that need WFS transformations applied separately.

synim.synim.apply_wfs_transformations_combined(derivatives_x, derivatives_y, trans_pup_mask, dm_mask, wfs_nsubaps, wfs_fov_arcsec, pup_diam_m, idx_valid_sa=None, slope_method='derivatives', specula_convention=True, verbose=False)

Compute slopes from pre-transformed derivatives (for combined workflow). No additional transformations needed.

synim.synim.apply_wfs_transformations_separated(derivatives_x, derivatives_y, pup_mask, dm_mask, wfs_nsubaps, wfs_fov_arcsec, pup_diam_m, wfs_rotation, wfs_translation, wfs_mag_global, wfs_anamorphosis_90=1.0, wfs_anamorphosis_45=1.0, idx_valid_sa=None, slope_method='derivatives', specula_convention=True, verbose=False)

Apply WFS transformations to derivatives (for separated workflow).

synim.synim.compute_derivatives_with_extrapolation(data, mask=None)

Compute x and y derivatives using numpy.gradient on a 2D or 3D numpy array if mask is present does an extrapolation to avoid issue at the edges

Parameters: - data: numpy 3D array - mask: optional, numpy 2D array, mask

Returns: - dx: numpy 3D array, x derivative - dy: numpy 3D array, y derivative

synim.synim.compute_subaperture_illumination(pup_mask, wfs_nsubaps, wfs_rotation=0.0, wfs_translation=(0.0, 0.0), wfs_magnification=(1.0, 1.0), idx_valid_sa=None, specula_convention=True, verbose=False)

Compute the relative illumination of valid subapertures.

This is useful for weighting the noise covariance matrix based on the actual flux received by each subaperture (edge subapertures receive less light).

Parameters: - pup_mask: numpy 2D array, pupil mask - wfs_nsubaps: int, number of subapertures along diameter - wfs_rotation: float, WFS rotation in degrees - wfs_translation: tuple, WFS translation (x, y) in pixels - wfs_magnification: tuple, WFS magnification (x, y) - idx_valid_sa: array, indices of valid subapertures (2D format preferred) - specula_convention: bool, whether to use SPECULA convention - verbose: bool, whether to print information

Returns: - illumination: 1D array, relative illumination of each valid subaperture (normalized to max=1)

synim.synim.compute_telsum_with_extrapolation(data, mask=None, wfs_nsubaps=None, verbose=False)

Computes the raw telescoping sum (average phase difference per pixel) for each subaperture. Acts as the telescoping sum equivalent of computing continuous derivatives.

synim.synim.interaction_matrices_multi_wfs(pup_diam_m, pup_mask, dm_array, dm_mask, dm_height, dm_rotation, wfs_configs, gs_pol_coo=None, gs_height=None, slope_method='derivatives', specula_convention=True, im_on_cpu=False, minimize_memory=False, verbose=False)

Computes interaction matrices for multiple WFS configurations.

Each WFS can have its own guide star position (gs_pol_coo) and height (gs_height).

Parameters: - pup_diam_m: float, pupil diameter in meters - pup_mask: numpy 2D array, pupil mask (n_pup x n_pup) - dm_array: numpy 3D array, DM modes (n x n x n_dm_modes) - dm_mask: numpy 2D array, DM mask (n x n) - dm_height: float, DM conjugation altitude - dm_rotation: float, DM rotation in degrees - wfs_configs: list of dict, each containing WFS parameters - gs_pol_coo: tuple or None (DEPRECATED) - gs_height: float or None (DEPRECATED) - slope_method: str, ‘derivatives’ or ‘telsum’ - specula_convention: bool, optional - im_on_cpu: bool, optional, force output interaction matrices on CPU - minimize_memory: bool, optional, delete intermediate variables to save memory - verbose: bool, optional

Returns: - im_dict: dict, interaction matrices keyed by WFS name or index - derivatives_info: dict with metadata about the computation

synim.synim.interaction_matrix(pup_diam_m, pup_mask, dm_array, dm_mask, dm_height, dm_rotation, wfs_nsubaps, wfs_fov_arcsec, gs_pol_coo, gs_height, wfs_rotation, wfs_translation, wfs_mag_global, wfs_anamorphosis_90=1.0, wfs_anamorphosis_45=1.0, idx_valid_sa=None, slope_method='derivatives', specula_convention=True, verbose=False, display=False)

Computes interaction matrix using intelligent workflow selection.

Automatically chooses between: - Separated workflow: When transformations are only in DM OR WFS (2 interpolation steps) - Combined workflow: When both DM and WFS have transformations (1 interpolation step)