Parameters Manager

class synim.params_manager.ParamsManager(params_file, root_dir=None, verbose=False, monitor=False)

Bases: object

Class for managing parameters needed to compute interaction matrices for all combinations of DMs and WFSs without redundant loading.

Methods

assemble_covariance_matrix(C_atm_blocks, ...)

Assemble the full covariance matrix from individual blocks, extracting only the modes specified in mode_indices.

assemble_interaction_matrices([wfs_type, ...])

Assemble interaction matrices for a specific type of WFS into a single full interaction matrix.

build_noise_covariance([wfs_type, n_wfs, ...])

Build noise covariance matrix with multiple strategies: 1.

compute_covariance_matrices(r0, L0[, ...])

Compute atmospheric covariance matrices for all components (DMs or layers).

compute_interaction_matrices(output_im_dir, ...)

Compute and save interaction matrices for all combinations of WFSs and DMs/Layers.

compute_interaction_matrix([wfs_type, ...])

Compute an interaction matrix for a specific WFS-DM/Layer combination.

compute_multirate_reconstructors(r0, L0[, ...])

Computes all 2^N - 1 reconstruction matrices for multirate dynamic scheduling.

compute_projection_matrices([output_dir, ...])

Compute and save projection matrices for all combinations of optical sources and DMs/layers.

compute_projection_matrix([reg_factor, ...])

Assemble 4D projection matrices from individual PM files and calculate the final projection matrix using the full DM and layer matrices.

compute_tomographic_projection_matrix([...])

Compute the tomographic projection matrix following optimal MCAO logic.

compute_tomographic_reconstructor(r0, L0[, ...])

Compute full tomographic reconstructor from interaction matrices and covariances.

count_mcao_stars()

Count the number of LGS, NGS, reference stars, DMs, optimisation optics, science stars and layers in the parameter configuration, similar to count_mcao_stars of IDL.

generate_im_filename([wfs_type, wfs_index, ...])

Generate the interaction matrix filename for a given WFS-DM/Layer combination.

get_component_params(component_idx[, ...])

Get DM or layer parameters, loading from cache if available.

get_source_info(wfs_name)

Return source info for a given WFS.

get_wfs_params([wfs_type, wfs_index, xp_local])

Get WFS parameters for a specific WFS.

list_dm()

Return a list of all DM names and indices.

list_wfs()

Return a list of all WFS names and types.

prepare_interaction_matrix_params([...])

Prepare parameters for computing an interaction matrix.

resource_report()

Print peak CPU, RAM and GPU usage for each tracked section.

save_assembled_interaction_matrix([...])

Assemble and save the full interaction matrix for a specific WFS type and component type.
assemble_covariance_matrix(C_atm_blocks, component_indices, mode_indices=None, wfs_type=None, component_type='layer', verbose=None, return_inverse=False)

Assemble the full covariance matrix from individual blocks, extracting only the modes specified in mode_indices.

Parameters:

  • C_atm_blocks (list) – List of covariance matrices for each component

  • component_indices (list) – List of component indices

  • mode_indices (list, optional) – List of mode index arrays for each component. If None, uses modal_combination.

  • wfs_type (str, optional) – WFS type for modal_combination lookup

  • component_type (str) – Type of component (‘dm’ or ‘layer’)

  • verbose (bool, optional) – Override the class’s verbose setting

  • return_inverse (bool, optional) – Whether to return the inverse of the covariance matrix

Returns:

Full covariance matrix with selected modes

Return type:

np.ndarray

assemble_interaction_matrices(wfs_type='ngs', output_im_dir=None, component_type='dm', save=False, apply_filter=True, active_wfs_mask=None, slope_method='derivatives')

Assemble interaction matrices for a specific type of WFS into a single full interaction matrix.

NOTE: This method applies filtering AFTER loading from disk, ensuring consistent treatment of both computed and pre-existing matrices.

Parameters:

  • wfs_type (str) – The type of WFS to assemble matrices for (‘ngs’, ‘lgs’, ‘ref’)

  • output_im_dir (str, optional) – Directory where IM files are stored

  • component_type (str) – Type of component to assemble (‘dm’ or ‘layer’)

  • save (bool) – Whether to save the assembled matrix to disk

  • active_wfs_mask (list of bool, optional) – Mask to select active WFSs for assembly. If None, all WFSs of the specified type are included.

  • apply_filter (bool) – Whether to apply filtmat_tag filtering if present

Returns:

(im_full, n_slopes_per_wfs, mode_indices, component_indices) -

Assembled matrix and associated parameters

Return type:

tuple

build_noise_covariance(wfs_type='lgs', n_wfs=None, n_slopes_total=None, noise_variance=None, C_noise=None, use_elongation=False, active_wfs_mask=None, return_diagnostics=False, verbose=None)

Build noise covariance matrix with multiple strategies: 1. Use provided C_noise (highest priority) 2. Use provided noise_variance (scalar or array) 3. Compute from sigma2_in_nm2 with illumination weighting 4. Optionally use elongated spot model for LGS

Parameters:

  • wfs_type (str) – Type of WFS (‘lgs’, ‘ngs’, ‘ref’)

  • n_wfs (int, optional) – Number of WFS. Auto-detected if None.

  • n_slopes_total (int, optional) – Total number of slopes in assembled IM

  • noise_variance (float or array, optional) – Noise variance per WFS

  • C_noise (np.ndarray, optional) – Pre-computed full noise covariance matrix

  • use_elongation (bool) – Whether to use elongated spot model for LGS

  • active_wfs_mask (array-like, optional) – Mask to indicate active WFS

  • return_diagnostics (bool) – If True, also return debug diagnostics dict

  • verbose (bool, optional) – Override the class’s verbose setting

Returns:

Noise covariance matrix (inverse, ready for MMSE),

optionally (C_noise_inv, diagnostics) when return_diagnostics=True

Return type:

np.ndarray or tuple

Raises:

ValueError – If insufficient information provided

compute_covariance_matrices(r0, L0, component_type='layer', output_dir=None, overwrite=False, skip_gpu_covariance=False, verbose=None)

Compute atmospheric covariance matrices for all components (DMs or layers).

Implements smart caching similar to IDL’s ifs_covmat: - Generates unique filename based on component parameters, r0, L0 - Loads from disk if file exists (unless overwrite=True) - Computes and saves if file doesn’t exist - Saves in FITS format (like IDL) for compatibility

Parameters:

  • r0 (float) – Fried parameter in meters

  • L0 (float) – Outer scale in meters

  • component_type (str) – Type of component (‘dm’ or ‘layer’)

  • output_dir (str, optional) – Directory to save covariance matrices

  • overwrite (bool) – Whether to overwrite existing files

  • skip_gpu_covariance (bool) – If True, skip GPU-accelerated covariance computation

  • verbose (bool, optional) – Override the class’s verbose setting

Returns:

Dictionary with:

  • ’C_atm_blocks’: List of covariance matrices for each component

  • ’component_indices’: List of component indices

  • ’r0’: Fried parameter used

  • ’L0’: Outer scale used

  • ’wavelength_nm’: wavelength in nm used for conversion

  • ’files’: List of file paths (saved or loaded)

Return type:

dict

compute_interaction_matrices(output_im_dir, output_rec_dir, wfs_type=None, component_type=None, slope_method='derivatives', overwrite=False, verbose=None, display=False)

Compute and save interaction matrices for all combinations of WFSs and DMs/Layers. Uses multi-WFS optimization when possible.

Parameters:

  • output_im_dir (str) – Output directory for saved matrices

  • output_rec_dir (str) – Output directory for reconstruction matrices

  • wfs_type (str, optional) – Type of WFS (‘ngs’, ‘lgs’, ‘ref’) to use

  • component_type (str, optional) – Type of component (‘dm’ or ‘layer’). If None, compute for all.

  • slope_method (str) – Method for slope calculation (‘derivatives’, ‘telsum’)

  • overwrite (bool, optional) – Whether to overwrite existing files

  • verbose (bool, optional) – Override the class’s verbose setting

  • display (bool, optional) – Whether to display plots

Returns:

Dictionary mapping WFS-Component pairs to saved interaction matrix paths

Return type:

dict

compute_interaction_matrix(wfs_type=None, wfs_index=None, dm_index=None, layer_index=None, slope_method='derivatives', verbose=None, display=False)

Compute an interaction matrix for a specific WFS-DM/Layer combination.

Parameters:

  • wfs_type (str, optional) – Type of WFS (‘sh’, ‘pyr’) or source type (‘lgs’, ‘ngs’, ‘ref’)

  • wfs_index (int, optional) – Index of the WFS (1-based)

  • dm_index (int, optional) – Index of the DM (1-based)

  • layer_index (int, optional) – Index of the Layer (1-based)

  • slope_method (str) – Method for slope calculation (‘derivatives’, ‘telsum’)

  • verbose (bool, optional) – Override the class’s verbose setting

  • display (bool) – Whether to display plots

Returns:

Computed interaction matrix

Return type:

numpy.ndarray

compute_multirate_reconstructors(r0, L0, wfs_type='ngs', component_type='dm', **kwargs)

Computes all 2^N - 1 reconstruction matrices for multirate dynamic scheduling. Generates binary suffixes (e.g., _v101) representing the active WFS tuple.

compute_projection_matrices(output_dir=None, overwrite=False, verbose=None)

Compute and save projection matrices for all combinations of optical sources and DMs/layers. Uses multi-base optimization when possible.

Parameters:

  • output_dir (str, optional) – Output directory for saved matrices

  • overwrite (bool, optional) – Whether to overwrite existing files

  • verbose (bool, optional) – Override the class’s verbose setting

Returns:

Dictionary mapping Source-Component pairs to saved projection matrix paths

Return type:

dict

compute_projection_matrix(reg_factor=1e-08, output_dir=None, save=False)

Assemble 4D projection matrices from individual PM files and calculate the final projection matrix using the full DM and layer matrices.

Optimized version: loads each DM/layer only once and iterates over optical sources.

Parameters:

  • reg_factor (float, optional) – Regularization factor for the pseudoinverse calculation. Default is 1e-8.

  • output_dir (str, optional) – Directory where PM files are stored and where assembled matrices will be saved.

  • save (bool) – Whether to save the assembled matrices to disk

Returns:

Final projection matrix (n_dm_modes, n_layer_modes) pm_full_dm (numpy.ndarray): Full DM projection matrix

(n_opt_sources, n_dm_modes, n_pupil_modes)

pm_full_layer (numpy.ndarray): Full Layer projection matrix

(n_opt_sources, n_layer_modes, n_pupil_modes)

Return type:

popt (numpy.ndarray)

compute_tomographic_projection_matrix(output_dir=None, save=False, wfs_type='lgs', verbose=None)

Compute the tomographic projection matrix following optimal MCAO logic.

Implements the standard MCAO projection:

P_opt = (P_DM^T @ P_DM + reg_factor*I)^(-1) @ P_DM^T @ P_Layer

This method optimally slices the massive projection matrices by extracting only the modes defined in the configuration (e.g., ref_n_modes_layer). It bypasses filtered low-order modes (e.g., Tip, Tilt, Focus) during the heavy matrix multiplications, and finally restores zero-columns where needed to match the exact dimensions expected by the Real-Time Computer reconstructor.

Parameters:

  • output_dir (str, optional) – Directory to store/load PM files.

  • save (bool) – Whether to save the final tomographic projection matrix to disk.

  • wfs_type (str) – WFS type (‘lgs’, ‘ngs’, ‘ref’) used to fetch specific mode truncation configurations.

  • verbose (bool, optional) – Override the class’s verbose setting.

Returns:

(p_opt, pm_full_dm, pm_full_layer, info)

  • p_opt: Final projection matrix (n_dm_modes_target, n_layer_modes_target)

  • pm_full_dm: Full DM projection matrix (loaded from disk)

  • pm_full_layer: Full Layer projection matrix (loaded from disk)

  • info: dict with computation metadata

Return type:

tuple

compute_tomographic_reconstructor(r0, L0, wfs_type='lgs', component_type='layer', noise_variance=None, C_noise=None, slope_method='derivatives', reconstructor_method='mmse', output_dir=None, save=False, overwrite=False, skip_gpu_covariance=False, active_wfs_mask=None, save_inverse_covariances=False, inverse_cov_output_dir=None, inverse_cov_prefix=None, verbose=None)

Compute full tomographic reconstructor from interaction matrices and covariances.

This method integrates: 1. Interaction matrix assembly (computed on-the-fly, not saved) 2. Covariance matrix computation/loading (cached to disk) - skipped for ‘pinv’ method 3. Reconstructor calculation (MMSE or pseudo-inverse)

Parameters:

  • r0 (float) – Fried parameter in meters

  • L0 (float) – Outer scale in meters

  • wfs_type (str) – Type of WFS (‘lgs’, ‘ngs’, ‘ref’)

  • component_type (str) – Type of component (‘dm’ or ‘layer’)

  • noise_variance (float or array, optional) – Noise variance per WFS (only for MMSE)

  • C_noise (np.ndarray, optional) – Full noise covariance matrix (only for MMSE)

  • slope_method (str) – Method for slope computation (‘derivatives’, ‘telsum’)

  • reconstructor_method (str) – Reconstructor type (‘mmse’ or ‘pinv’). ‘mmse’: Minimum Mean Square Error using atmospheric and noise covariances ‘pinv’: Simple pseudo-inverse of interaction matrix (useful for NGS with few modes)

  • output_dir (str, optional) – Directory for saving results

  • save (bool) – Whether to save the reconstructor

  • overwrite (bool) – Whether to overwrite existing files

  • skip_gpu_covariance (bool) – Whether to skip GPU acceleration for covariance computation (MMSE only)

  • active_wfs_mask (list of bool, optional) – Mask indicating active WFSs

  • save_inverse_covariances (bool) – Whether to save inverse covariance matrices for debug/comparison (MMSE only)

  • inverse_cov_output_dir (str, optional) – Directory for inverse covariance debug files (MMSE only)

  • inverse_cov_prefix (str, optional) – Prefix for inverse covariance debug filenames (MMSE only)

  • verbose (bool, optional) – Override the class’s verbose setting

Returns:

Dictionary with:

  • ’reconstructor’: Reconstructor matrix (MMSE or pseudo-inverse)

  • ’im_full’: Full interaction matrix

  • ’C_atm_full’: Full atmospheric covariance matrix (None for pinv)

  • ’C_noise’: Noise covariance matrix (None for pinv)

  • ’mode_indices’: Mode indices per component

  • ’component_indices’: Component indices

  • ’n_slopes_per_wfs’: Number of slopes per WFS

  • ’rec_filename’: Filename if saved

  • ’reconstructor_method’: Method used (‘mmse’ or ‘pinv’)

Return type:

dict

count_mcao_stars()

Count the number of LGS, NGS, reference stars, DMs, optimisation optics, science stars and layers in the parameter configuration, similar to count_mcao_stars of IDL.

Returns:

dict: Dictionary with counts.

generate_im_filename(wfs_type=None, wfs_index=None, dm_index=None, layer_index=None, slope_method='derivatives', timestamp=False, verbose=False)

Generate the interaction matrix filename for a given WFS-DM/Layer combination.

get_component_params(component_idx, is_layer=False, cut_start_mode=False, n_modes_to_use=None, xp_local=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/synim/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>, float_dtype_local=<class 'numpy.float32'>)

Get DM or layer parameters, loading from cache if available.

Parameters:

  • component_idx (int) – Index of the DM or layer to load

  • is_layer (bool) – Whether to load a layer instead of a DM

  • cut_start_mode (bool) – Whether to select modes from start_mode to start_mode+n_modes

  • n_modes_to_use (int, optional) – Number of modes to use starting from start_mode. If None, uses all available modes after start_mode.

  • xp_local – array module to use (numpy or cupy)

  • float_dtype_local – data type for arrays (e.g., float_dtype or cpu_float_dtype)

Returns:

DM or layer parameters

Return type:

dict

get_source_info(wfs_name)

Return source info for a given WFS.

get_wfs_params(wfs_type=None, wfs_index=None, xp_local=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/synim/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>)

Get WFS parameters for a specific WFS.

Parameters:

  • wfs_type (str, optional) – Type of WFS (‘sh’, ‘pyr’) or source type (‘lgs’, ‘ngs’, ‘ref’)

  • wfs_index (int, optional) – Index of the WFS (1-based)

  • xp_local – array module to use (numpy or cupy)

Returns:

WFS parameters

Return type:

dict

list_dm()

Return a list of all DM names and indices.

list_wfs()

Return a list of all WFS names and types.

prepare_interaction_matrix_params(wfs_type=None, wfs_index=None, dm_index=None, layer_index=None)

Prepare parameters for computing an interaction matrix.

Parameters:

  • wfs_type (str, optional) – Type of WFS (‘sh’, ‘pyr’) or source type (‘lgs’, ‘ngs’, ‘ref’)

  • wfs_index (int, optional) – Index of the WFS (1-based)

  • dm_index (int, optional) – Index of the DM (1-based)

  • layer_index (int, optional) – Index of the Layer (1-based)

Returns:

Parameters ready to be passed to synim.interaction_matrix

Return type:

dict

resource_report()

Print peak CPU, RAM and GPU usage for each tracked section.

save_assembled_interaction_matrix(wfs_type='lgs', component_type='dm', output_dir=None, overwrite=False, apply_filter=True, slope_method='derivatives', active_wfs_mask=None, verbose=None)

Assemble and save the full interaction matrix for a specific WFS type and component type.

This is useful for: - Debugging reconstructor computation - Reusing assembled IMs without recomputing - Comparing filtered vs unfiltered IMs

Parameters:

  • wfs_type (str) – Type of WFS (‘lgs’, ‘ngs’, ‘ref’)

  • component_type (str) – Type of component (‘dm’ or ‘layer’)

  • output_dir (str, optional) – Directory to save the assembled IM

  • overwrite (bool) – Whether to overwrite existing file

  • apply_filter (bool) – Whether to apply filtmat_tag filtering

  • active_wfs_mask (list of bool, optional) – Mask indicating active WFSs to include in assembly

  • verbose (bool, optional) – Override the class’s verbose setting

Returns:

Path to saved file

Return type:

str