Internal kernels

Warning

These functions are private. They are documented for people working on pyTomoAO itself; their names and signatures may change in any release. Use tomographicReconstructor in application code.

The two modules below are interchangeable implementations of the same set of kernels. The CPU version uses NumPy with Numba-compiled inner loops; the GPU version uses CuPy. pyTomoAO.reconstructor imports one or the other at module load, based on whether CuPy is importable.

Function	Role
_covariance_matrix	Von Kármán phase covariance between two point sets
_auto_correlation	Slope-to-slope covariance across all guide star pairs
_cross_correlation	Optimisation-direction-to-slope covariance
_sparseGradientMatrixAmplitudeWeighted	Phase-to-slope gradient operator for the lenslet array
_build_reconstructor_model	Assembles the model-based MMSE reconstructor
_build_reconstructor_im	Assembles the interaction-matrix-based reconstructor

The GPU variants additionally accept a use_float32 flag controlling the working precision on the device.

CPU implementation

pyTomoAO.tomographyUtilsCPU._covariance_matrix(*args)

Optimized phase covariance matrix calculation using the Von Karman turbulence model.

Parameters:

*args (tuple) –

Either (rho1, r0, L0, fractionalR0) for the auto-covariance, or (rho1, rho2, r0, L0, fractionalR0) for the cross-covariance, where:

• rho1, rho2 : complex coordinate arrays (x + iy)

• r0 : Fried parameter [m]

• L0 : outer scale [m]

• fractionalR0 : turbulence layer weighting factor

Returns:

numpy.ndarray – Covariance matrix with the same dimensions as the input coordinates.

Raises:

ValueError – If the number of positional arguments is neither 4 nor 5.

pyTomoAO.tomographyUtilsCPU._auto_correlation(tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, gridMask)

Computes the auto-correlation meta-matrix for tomographic atmospheric reconstruction.

Parameters:

• tomoParams (object) –

  Tomography parameters:

  • sampling (int): number of grid samples per axis

  • mask (ndarray): 2D boolean grid mask

• lgsWfsParams (object) –

  LGS WFS parameters:

  • D (float): telescope diameter [m]

  • wfsLensletsRotation (ndarray): lenslet rotations [rad]

  • wfsLensletsOffset (ndarray): lenslet offsets [normalized]

• atmParams (object) –

  Atmospheric parameters:

  • nLayer (int): number of turbulence layers

  • altitude (ndarray): layer altitudes [m]

  • r0 (float): Fried parameter [m]

  • L0 (float): outer scale [m]

  • fractionnalR0 (ndarray): turbulence strength per layer

• lgsAsterismParams (object) –

  LGS constellation parameters:

  • nLGS (int): number of LGS

  • directionVectorLGS (ndarray): direction vectors

  • LGSheight (float): LGS height [m]

• gridMask (ndarray) – 2D boolean mask for valid grid points.

Returns:

numpy.ndarray – Auto-correlation meta-matrix of shape (nGs*valid_pts, nGs*valid_pts).

pyTomoAO.tomographyUtilsCPU._cross_correlation(tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, gridMask=None)

Computes the cross-correlation meta-matrix for tomographic atmospheric reconstruction.

Parameters:

• tomoParams (object) –

  Tomography parameters:

  • sampling (int): number of grid samples per axis

  • mask (ndarray): 2D boolean grid mask

• lgsWfsParams (object) –

  LGS WFS parameters:

  • D (float): telescope diameter [m]

  • wfsLensletsRotation (ndarray): lenslet rotations [rad]

  • wfsLensletsOffset (ndarray): lenslet offsets [normalized]

• atmParams (object) –

  Atmospheric parameters:

  • nLayer (int): number of turbulence layers

  • altitude (ndarray): layer altitudes [m]

  • r0 (float): Fried parameter [m]

  • L0 (float): outer scale [m]

  • fractionnalR0 (ndarray): turbulence strength per layer

• lgsAsterismParams (object) –

  LGS constellation parameters:

  • nLGS (int): number of LGS

  • directionVectorLGS (ndarray): direction vectors

  • LGSheight (float): LGS height [m]

• gridMask (ndarray, optional) – 2D boolean mask for valid grid points.

Returns:

numpy.ndarray – Cross-correlation meta-matrix of shape (nGs*valid_pts, nGs*valid_pts).

pyTomoAO.tomographyUtilsCPU._sparseGradientMatrixAmplitudeWeighted(validLenslet, amplMask=None, overSampling=2, stencilSize=3)

Computes the sparse gradient matrix (3x3 or 5x5 stencil) with amplitude mask.

Parameters:

• validLenslet (numpy.ndarray) – 2D valid lenslet map.

• amplMask (numpy.ndarray, optional) – 2D amplitude weight mask. Defaults to uniform weighting.

• overSampling (int, optional) – Oversampling factor for the gridMask, either 2 or 4 (default is 2).

Returns:

• Gamma (scipy.sparse.csr_matrix) – Sparse gradient matrix.

• gridMask (numpy.ndarray) – 2D mask used for the reconstructed phase.

pyTomoAO.tomographyUtilsCPU._build_reconstructor_model(tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, alpha=1)

Build the model-based tomographic reconstructor on the CPU.

Parameters:

• tomoParams (object) – Configuration objects held by the reconstructor.

• lgsWfsParams (object) – Configuration objects held by the reconstructor.

• atmParams (object) – Configuration objects held by the reconstructor.

• lgsAsterismParams (object) – Configuration objects held by the reconstructor.

• alpha (float, optional) – Regularization weight applied to the inversion (default is 1).

Returns:

tuple – (reconstructor, Gamma, gridMask, Cxx, Cox, Cnz, RecStatSA).

pyTomoAO.tomographyUtilsCPU._build_reconstructor_im(IM, tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, dmParams, alpha=1)

Build the interaction-matrix-based tomographic reconstructor on the CPU.

Parameters:

• IM (numpy.ndarray) – Block-diagonal interaction matrix, one block per wavefront sensor.

• tomoParams (object) – Configuration objects held by the reconstructor.

• lgsWfsParams (object) – Configuration objects held by the reconstructor.

• atmParams (object) – Configuration objects held by the reconstructor.

• lgsAsterismParams (object) – Configuration objects held by the reconstructor.

• dmParams (object) – Configuration objects held by the reconstructor.

• alpha (float, optional) – Regularization weight applied to the inversion (default is 1).

Returns:

tuple – (reconstructor, gridMask, Cxx, Cox, Cnz, RecStatSA).

GPU implementation

pyTomoAO.tomographyUtilsGPU._covariance_matrix(*args, use_float32=False)

GPU implementation of the Von Karman phase covariance matrix calculation.

Parameters:

• *args (tuple) – Either (rho1, r0, L0, fractionalR0) for the auto-covariance, or (rho1, rho2, r0, L0, fractionalR0) for the cross-covariance, with the coordinate arrays given as CuPy arrays of complex positions (x + iy).

• use_float32 (bool, optional) – Compute in single precision (default is False).

Returns:

cupy.ndarray – Covariance matrix with the same dimensions as the input coordinates.

Raises:

ValueError – If the number of positional arguments is neither 4 nor 5.

pyTomoAO.tomographyUtilsGPU._auto_correlation(tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, gridMask, use_float32=False)

GPU implementation of the slope auto-correlation meta-matrix.

Mirrors pyTomoAO.tomographyUtilsCPU._auto_correlation(); see that function for a description of the parameter objects.

Parameters:

• tomoParams (object) – Configuration objects held by the reconstructor.

• lgsWfsParams (object) – Configuration objects held by the reconstructor.

• atmParams (object) – Configuration objects held by the reconstructor.

• lgsAsterismParams (object) – Configuration objects held by the reconstructor.

• gridMask (numpy.ndarray) – 2D boolean mask for valid grid points.

• use_float32 (bool, optional) – Compute in single precision (default is False).

Returns:

numpy.ndarray – Auto-correlation meta-matrix of shape (nGs*valid_pts, nGs*valid_pts).

pyTomoAO.tomographyUtilsGPU._cross_correlation(tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, gridMask=None, use_float32=False)

GPU implementation of the phase-to-slope cross-correlation meta-matrix.

Mirrors pyTomoAO.tomographyUtilsCPU._cross_correlation(); see that function for a description of the parameter objects.

Parameters:

• tomoParams (object) – Configuration objects held by the reconstructor.

• lgsWfsParams (object) – Configuration objects held by the reconstructor.

• atmParams (object) – Configuration objects held by the reconstructor.

• lgsAsterismParams (object) – Configuration objects held by the reconstructor.

• gridMask (numpy.ndarray, optional) – 2D boolean mask for valid grid points.

• use_float32 (bool, optional) – Compute in single precision (default is False).

Returns:

numpy.ndarray – Cross-correlation meta-matrix of shape (nGs*valid_pts, nGs*valid_pts).

pyTomoAO.tomographyUtilsGPU._sparseGradientMatrixAmplitudeWeighted(validLenslet, amplMask=None, overSampling=2)

Computes the sparse gradient matrix (3x3 or 5x5 stencil) with amplitude mask.

Parameters:

• validLenslet (numpy.ndarray) – 2D valid lenslet map.

• amplMask (numpy.ndarray, optional) – 2D amplitude weight mask. Defaults to uniform weighting.

• overSampling (int, optional) – Oversampling factor for the gridMask, either 2 or 4 (default is 2).

Returns:

• Gamma (scipy.sparse.csr_matrix) – Sparse gradient matrix.

• gridMask (numpy.ndarray) – 2D mask used for the reconstructed phase.

pyTomoAO.tomographyUtilsGPU._build_reconstructor_model(tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, use_float32=False, alpha=1)

Build the model-based tomographic reconstructor on the GPU.

Parameters:

• tomoParams (object) – Configuration objects held by the reconstructor.

• lgsWfsParams (object) – Configuration objects held by the reconstructor.

• atmParams (object) – Configuration objects held by the reconstructor.

• lgsAsterismParams (object) – Configuration objects held by the reconstructor.

• use_float32 (bool, optional) – Compute in single precision (default is False).

• alpha (float, optional) – Regularization weight applied to the inversion (default is 1).

Returns:

tuple – (reconstructor, Gamma, gridMask, Cxx, Cox, Cnz, RecStatSA).

pyTomoAO.tomographyUtilsGPU._build_reconstructor_im(IM, tomoParams, lgsWfsParams, atmParams, lgsAsterismParams, dmParams, use_float32=False, alpha=1)

Build the interaction-matrix-based tomographic reconstructor on the GPU.

Parameters:

• IM (numpy.ndarray or cupy.ndarray) – Block-diagonal interaction matrix, one block per wavefront sensor. A host array is copied to the device.

• tomoParams (object) – Configuration objects held by the reconstructor.

• lgsWfsParams (object) – Configuration objects held by the reconstructor.

• atmParams (object) – Configuration objects held by the reconstructor.

• lgsAsterismParams (object) – Configuration objects held by the reconstructor.

• dmParams (object) – Configuration objects held by the reconstructor.

• use_float32 (bool, optional) – Compute in single precision (default is False).

• alpha (float, optional) – Regularization weight applied to the inversion (default is 1).

Returns:

tuple – (reconstructor, gridMask, Cxx, Cox, Cnz, RecStatSA).