WF Correction

class Asterix.wfsc.corrector.Corrector(Correctionconfig, testbed: Testbed, MaskDH, estimator: Estimator, matrix_dir=None, save_for_bench=False, realtestbed_dir='', silence=False)

Bases: object

Corrector Class allows you to define a corrector with different algorithms.

Corrector is a class which takes as parameter:

• the testbed structure

• the correction parameters

• the estimator

It must contains 2 functions at least:

• an initialization (e.g. Jacobian matrix) Corrector.__init__

  The initialization requires previous initialization of the testbed and of the estimator.

• a correction function Corrector.toDM_voltage(estimation), which returns the DM Voltage vector

  using as parameter the estimation (2D array or 3D for polychromatic correction). It can one DM or more, depending on the testbed.

AUTHOR : Johan Mazoyer

Methods

toDM_voltage(testbed, estimate[, mode, ...])	Run a correction from a estimate, and return the DM voltage compatible with the testbed.
update_matrices(testbed, estimator[, ...])	Measure the interaction matrices needed for the correction Is launch once in the Correction initialization and then once each time we update the matrix.

update_matrices(testbed: Testbed, estimator: Estimator, initial_DM_voltage=0.0, input_wavefront=1.0, silence=False)

Measure the interaction matrices needed for the correction Is launch once in the Correction initialization and then once each time we update the matrix.

AUTHOR : Johan Mazoyer

Parameters:

testbedOpticalSystem.Testbed

Testbed object which describe your testbed

estimatorEstimator

an estimator object. This contains all information about the estimation

initial_DM_voltagefloat or 1d numpy array, default 0.

initial DM voltages to measure the Matrix

input_wavefrontfloat or 2d numpy array or 3d numpy array, default 1.

initial wavefront to measure the Matrix

silenceboolean, default False.

Whether to silence print outputs.

toDM_voltage(testbed: Testbed, estimate, mode=1, ActualCurrentContrast=1.0, silence=False, **kwargs)

Run a correction from a estimate, and return the DM voltage compatible with the testbed.

AUTHOR : Johan Mazoyer

Parameters:

testbedOpticalSystem.Testbed

Testbed object which describe your testbed

estimatelist of 2D complex array

list is the number of wl in the estimation, usually 1 or testbed.nb_wav Each arrays are of size of sixe [dimEstim, dimEstim]. This is the result of Estimator.estimate, from which this function send a command to the DM

modeint, defaut 1

Use in EFC, EM, and Steepest, this is the mode we use in the SVD inversion if the mode is the same than the previous iteration, we store the inverted matrix to avoid inverted it again

ActualCurrentContrastfloat, defau,t 1.

Use in StrokeMin to find a target contrast Contrast at the current iteration of the loop

silenceboolean, default False.

Whether to silence print outputs.

Asterix.wfsc.wf_control_functions.create_interaction_matrix(testbed: Testbed, dimEstim, amplitudeEFC, matrix_dir, initial_DM_voltage=0.0, input_wavefront=1.0, MatrixType='', polychrom='singlewl', wav_vec_estim=None, dir_save_all_planes=None, silence=False, visu=False)

Create the jacobian matrix for Electric Field Conjugation. The Matrix is not limited to the DH size but to the whole FP [dimEstim, dimEstim]. First half is real part, second half is imag part.

The matrix size is therefore [total(DM.basis_size), 2*dimEstim^2]

We save the matrix in .fits independently for each DMs, only if the initial wavefront and DMs are flat.

This code works for all testbeds without prior assumption (if we have at least 1 DM of course). We have optimized the code to only do once the optical elements before the DM movement and repeat only what is after the DMS

AUTHOR : Johan Mazoyer

Sept 2022 : created

Parameters:

testbedTestbed Optical_element

testbed structure with at least 1 DM

dimEstimint

size of the output image in teh estimator

amplitudeEFCfloat

amplitude of the EFC probe on the DM

matrix_dirstring

path to directory to save all the matrices here

MatrixTypestring

‘smallphase’ (when applying modes on the DMs we, do a small phase assumption : exp(i phi) = 1+ i.phi) or ‘perfect’ (we keep exp(i phi)). in both case, if the DMs are not initially flat (non zero initial_DM_voltage), we do not make the small phase assumption for initial DM phase

polychromstring

For polychromatic estimation and correction: - ‘singlewl’: only a single wavelength is used for estimation / correction. 1 Interation Matrix - ‘broadband_pwprobes’: probes images PW are broadband but Matrices are at central wavelength: 1 PW Matrix and 1 Interation Matrix - ‘multiwl’: nb_wav images are used for estimation and there are nb_wav matrices of estimation and nb_wav matrices for correction

initial_DM_voltage1D-array real

initial DM voltage for all DMs

input_wavefrontcomplex scalar or 2d complex array or 3d complex array. Default is 1 (flat WF)

Input wavefront in pupil plane

dir_save_all_planesstring or None, default None

If not None, absolute directory to save all planes in fits for debugging purposes. This can generate a lot of fits especially if in a loop, use with caution.

silenceboolean, default False.

Whether to silence print outputs.

visubool default false

if true show the focal plane intensity in 2D for each mode

Returns:

InterMat2D array of size [total(DM.basis_size), 2*dimEstim^2]

jacobian matrix for Electric Field Conjugation.

Asterix.wfsc.wf_control_functions.create_singlewl_interaction_matrix(testbed: Testbed, dimEstim, amplitudeEFC, wavelength, matrix_dir, initial_DM_voltage=0.0, input_wavefront=1.0, MatrixType='', dir_save_all_planes=None, silence=False, visu=False)

Create the jacobian matrix for Electric Field Conjugation for one wavelength. The Matrix is not limited to the DH size but to the whole FP [dimEstim, dimEstim]. First half is real part, second half is imag part.

The matrix size is therefore [total(DM.basis_size), 2*dimEstim^2]

We save the matrix in .fits independently for each DMs, only if the initial wavefront and DMs are flat.

This code works for all testbeds without prior assumption (if we have at least 1 DM of course). We have optimized the code to only do once the optical elements before the DM movement and repeat only what is after the DMS

AUTHOR : Axel Potier and Johan Mazoyer

Parameters:

testbedTestbed Optical_element

testbed structure with at least 1 DM

dimEstim: int

size of the output image in teh estimator

amplitudeEFC: float

amplitude of the EFC probe on the DM

wavelengthfloat

wavelength in m.

matrix_dirstring

path to directory to save all the matrices here

MatrixType: string

‘smallphase’ (when applying modes on the DMs we, do a small phase assumption : exp(i phi) = 1+ i.phi) or ‘perfect’ (we keep exp(i phi)). in both case, if the DMs are not initially flat (non zero initial_DM_voltage), we do not make the small phase assumption for initial DM phase

initial_DM_voltage1D-array real

initial DM voltage for all DMs

input_wavefront2D complex array or complex scalar. Default is 1 (flat WF)

Input wavefront in pupil plane

dir_save_all_planesstring, default None

If not None, path to directory to save all planes in fits for debugging purposes. This can generate a lot of fits especially if in a loop, use with caution.

silenceboolean, default False.

Whether to silence print outputs.

visubool default false

if true, show the focal plane intensity in 2D for each mode.

Returns:

InterMat2D array of size [total(DM.basis_size), 2*dimEstim^2]

jacobian matrix for Electric Field Conjugation.

Asterix.wfsc.wf_control_functions.crop_interaction_matrix_to_dh(FullInteractionMatrix: ndarray, mask: ndarray)

Crop the Interaction Matrix to the DH mask size. AUTHOR : Johan Mazoyer

Parameters:

FullInteractionMatrix: Interaction matrix over the full focal plane

mask2D numpy array

a binary mask to delimitate the DH

Returns:

DHInteractionMatrix2D numpy array

matrix only inside the DH. first half is real part, second half is imag part

Asterix.wfsc.wf_control_functions.calc_efc_solution(mask, Result_Estimate, inversed_jacobian, testbed: Testbed)

Voltages to apply on the deformable mirrors in order to minimize the speckle intensity in the dark hole region.

AUTHOR : Axel Potier

Parameters:

mask2D Binary mask

Dark hole region

Result_Estimatelist of 2D complex array

List is the number of wl in the estimation, usually 1 or testbed.nb_wav Each arrays are of size of sixe [dimEstim, dimEstim]. estimation of focal plane EF

inversed_jacobian2D array

inverse of the jacobian matrix linking the estimation to the basis coefficient

testbedTestbed Optical_element

a testbed with one or more DM

Returns:

solution1D array

voltage to apply on each deformable mirror actuator

Asterix.wfsc.wf_control_functions.calc_em_solution(mask, Result_Estimate, Hessian_Matrix, Jacobian, testbed: Testbed)

Voltage to apply on the deformable mirror in order to minimize the speckle intensity in the dark hole region.

AUTHOR : Axel Potier

Parameters:

maskBinary mask

Dark hole region.

Result_Estimatelist of 2D complex array

List is the number of wl in the estimation, usually 1 or testbed.nb_wav Each arrays are of size of sixe [dimEstim, dimEstim]. estimation of focal plane EF.

Hessian_Matrix2D array

Hessian matrix of the DH energy.

Jacobian2D array

Jacobian matrix created linking the estimation to the basis coefficient.

testbedTestbed Optical_element

Testbed with one or more DM.

Returns:

solution1D array

Voltage to apply on each deformable mirror actuator.

Asterix.wfsc.wf_control_functions.calc_strokemin_solution(mask, Result_Estimate, Jacob_trans_Jacob, Jacobian, DesiredContrast, last_best_alpha, testbed: Testbed, silence=False)

Voltage to apply on the deformable mirror in order to minimize the speckle intensity in the dark hole region in the stroke min solution See Axel Potier Phd for notation and Mazoyer et al. 2018a for alpha search improvement.

AUTHOR : Johan Mazoyer

Parameters:

maskBinary mask

Dark hole region.

Result_Estimatelist of 2D complex array

list is the number of wl in the estimation, usually 1 or testbed.nb_wav Each arrays are of size of sixe [dimEstim, dimEstim]. estimation of focal plane EF.

Jacob_trans_Jacob2D array

Jabobian.Transpose(Jabobian) matrix.

Jacobian2D array

Jacobian matrix created linking the estimation to the basis coefficient.

DesiredContrastfloat

The contrast value we wish to achieve.

last_best_alphafloat

Starting point for alpha.

testbedTestbed Optical_element

Testbed with one or more DM.

silenceboolean, default False.

Whether to silence print outputs.

Returns:

solution1D array

Voltage to apply on each deformable mirror actuator.

lasbestalphafloat

The last best alpha. This avoid to recalculate the best alpha from scratch at each iteration since it’s often a very close value.

Asterix.wfsc.wf_control_functions.calc_steepest_solution(mask, Result_Estimate, Hessian_Matrix, Jacobian, testbed: Testbed)

Voltage to apply on the deformable mirror in order to minimize the speckle intensity in the dark hole region.

AUTHOR : Axel Potier

Parameters:

maskBinary mask

Dark hole region.

Result_Estimatelist of 2D complex array

List is the number of wl in the estimation, usually 1 or testbed.nb_wav Each arrays are of size of sixe [dimEstim, dimEstim]. estimation of focal plane EF.

Hessian_Matrix2D array

Hessian matrix of the DH energy.

Jacobian2D array

Inverse of the jacobian matrix linking the estimation to the basis coefficient.

testbedTestbed Optical_element

Testbed with one or more DM.

Returns:

solution1D array

Voltage to apply on each deformable mirror actuator.

Asterix.wfsc.thd_quick_invert.THD_quick_invert(Nbmodes, name_active_DM, matrix_directory, regularization, number_wl_in_matrix=1, silence=False)

This code invert the matrix just in the case of THD testbed.

The goal is to be able to invert the matrix directly on the RTC to be able to do it during correction. Needs the following fits files (automatically created in corrector.py if onbench == True):

if DM1 only is active:

• Base_Matrix_DM1.fits

• Direct_Matrix_DM1only.fits

if DM3 only is active:

-Base_Matrix_DM3.fits - Direct_Matrix_DM3only.fits

if both DM1 and DM3 are active:

• Base_Matrix_DM1.fits

• Base_Matrix_DM1.fits

• Direct_Matrix_2DM.fits

Save the following fits files (that can be read by the testbed RTC):

if DM1 only is active:

• Matrix_control_EFC_DM1.fits

if DM3 only is active:

-Matrix_control_EFC_DM3.fits

if both DM1 and DM3 are active:

• Matrix_control_EFC_DM1.fits

• Matrix_control_EFC_DM3.fits

AUTHOR : Johan Mazoyer

Parameters:

Nbmodes: int

threshold to cut the singular values

name_active_DMint

Simple code to identify which DMs are active 1, 3 or 13 depending on the DM you want to access

matrix_directorystr

Directory where Direct matrices are read and Inverse matrices are saved Careful Windows and MacOS do not write path the same way

regularizationstring, default ‘truncation’

if ‘truncation’: when goal is set to ‘c’, the modes with the highest inverse

singular values are truncated

if ‘tikhonov’: when goal is set to ‘c’, the modes with the highest inverse

singular values are smoothed (low pass filter)

number_wl_in_matrixint, default 1

number of wavelength in the direct matrix

silenceboolean, default False.

Whether to silence print outputs.