wf_psf.sims.spatial_varying_psf

Spatially Varying PSF Simulator.

This module contains classes and methods for simulating spatially varying Point Spread Functions (PSFs) using polynomial variations of Zernike coefficients.

Authors:

Tobias Liaudat <tobias.liaudat@cea.fr> & Jennifer Pollack <jennifer.pollack@cea.fr>

Classes

CoordinateHelper()

Coordinate Helper.

MeshHelper()

Mesh Helper.

PolynomialMatrixHelper()

PolynomialMatrixHelper.

SpatialVaryingPSF(psf_simulator[, d_max, ...])

Spatial Varying PSF.

ZernikeHelper()

ZernikeHelper.
class wf_psf.sims.spatial_varying_psf.CoordinateHelper[source]

Bases: object

Coordinate Helper.

A utility class for handling coordinate operations.

Methods

add_random_shift_to_positions(xv_grid, ...)

Add Random Shift to Positions.

calculate_shift(x_lims, y_lims, grid_points)

Calculate Shift.

check_and_adjust_coordinate_limits(x, y, ...)

Check and adjust coordinate limits.

check_position_coordinate_limits(xv, yv, ...)

Check Position Coordinate Limits.

scale_positions(x, y, x_lims, y_lims)

Scale Positions.
static add_random_shift_to_positions(xv_grid, yv_grid, grid_points, x_lims, y_lims, seed=None)[source]

Add Random Shift to Positions.

Add random shifts to positions within each grid cell, ensuring no overlap between neighboring cells.

Parameters:

  • xv_grid (Numpy array) – Grid of x-coordinates.

  • yv_grid (Numpy array) – Grid of y-coordinates.

  • grid_points (list) – A list defining the size of each axis grid

  • x_lims (list) – Lower and upper limits along the x-axis.

  • y_lims (list) – Lower and upper limits along the y-axis.

  • seed (int) – Seed for random number generation.

Returns:

  • xv_s (numpy.ndarray) – Positions with added random shifts along the x-axis.

  • yv_s (numpy.ndarray) – Positions with added random shifts along the y-axis.

static calculate_shift(x_lims, y_lims, grid_points)[source]

Calculate Shift.

A method to calcuate the step size for shifting positions based on the specified coordinate limits and grid points.

Parameters:

x_lims (list) – A list representing the lower and upper limits along the x-axis.

y_lims: list

A list representing the lower and upper limits along the y-axis.

grid_points: list

List defining the size of each axis grid.

Returns:

  • xstep (int)

  • ystep (int)

static check_and_adjust_coordinate_limits(x, y, x_lims, y_lims)[source]

Check and adjust coordinate limits.

A method to check and adjust coordinate limits to within the range of x_lims and y_lims, respectively.

Parameters:

  • x (numpy.ndarray) – A 1-dimensional numpy-ndarray containing positions along x-axis.

  • y (numpy.ndarray) – A 1-dimensional numpy-ndarray containing positions along y-axis.

  • x_lims (list) – Lower and upper limits along the x-axis.

  • y_lims (list) – Lower and upper limits along the y-axis.

Returns:

  • x (numpy.ndarray) – A numpy.ndarraycontaining adjusted positions along the x-axis within the specified limits.

  • y (numpy.ndarray) – A numpy.ndarraycontaining adjusted positions along the x-axis within the specified limits.

static check_position_coordinate_limits(xv, yv, x_lims, y_lims, verbose)[source]

Check Position Coordinate Limits.

This function checks if the given position coordinates (xv, yv) are within the specified limits (x_lims, y_lims). It raises a warning if any coordinate is outside the limits.

Parameters:

  • xv (numpy.ndarray) – The x coordinates to be checked.

  • yv (numpy.ndarray) – The y coordinates to be checked.

  • x_lims (tuple) – A tuple (min, max) specifying the lower and upper limits for x coordinates.

  • y_lims (tuple) – A tuple (min, max) specifying the lower and upper limits for y coordinates.

  • verbose (bool) – If True, print warning messages when coordinates are outside the limits.

Return type:

None

static scale_positions(x, y, x_lims, y_lims)[source]

Scale Positions.

A method to scale x- and y- positions.

Parameters:

  • x (numpy.ndarray) – A 1-dimensional numpy ndarray denoting a vector of x positions.

  • y (numpy.ndarray) – A 1-dimensional numpy ndarray denoting a vector of y positions.

  • x_lims (list) – A list representing the lower and upper limits along the x-axis.

  • y_lims (list) – A list representing the lower and upper limits along the y-axis.

Returns:

  • scaled_x (numpy.ndarray) – Scaled x positions.

  • scaled_y (numpy.ndarray) – Scaled y positions.

class wf_psf.sims.spatial_varying_psf.MeshHelper[source]

Bases: object

Mesh Helper.

A utility class for generating mesh grids.

Methods

build_mesh(x_lims, y_lims[, grid_points, ...])

Build Mesh.
static build_mesh(x_lims, y_lims, grid_points=None, grid_size=None, endpoint=True)[source]

Build Mesh.

A method to build a mesh.

Parameters:

  • x_lims (list) – A list representing the lower and upper limits along the x-axis.

  • y_lims (list) – A list representing the lower and upper limits along the y-axis.

  • grid_points (list or None, optional) – List defining the size of each axis grid for constructing the mesh grid. If provided and grid_size is also provided, grid_size will override this parameter. (default is None)

  • grid_size (int or None, optional) – Number of points to generate for each axis of the grid. If None and grid_points is not provided, the default grid size is used. (default is None)

  • endpoint (bool, optional) – If True, stop is the last sample. Otherwise, it is not included. (default is True).

Returns:

A tuple containing two 2-dimensional arrays for x- and y-coordinate axes.

Return type:

tuple

class wf_psf.sims.spatial_varying_psf.PolynomialMatrixHelper[source]

Bases: object

PolynomialMatrixHelper.

Helper class with methods for generating polynomial matrices of positions.

Methods

generate_polynomial_matrix(x, y, x_lims, ...)

Generate polynomial matrix of positions.
static generate_polynomial_matrix(x, y, x_lims, y_lims, d_max)[source]

Generate polynomial matrix of positions.

This method constructs a polynomial matrix representing spatial variations in a two-dimensional field. The polynomial matrix is generated based on the given x and y positions, considering a maximum polynomial degree specified by d_max.

Parameters:

  • x (numpy.ndarray) – A 1-dimensional numpy ndarray denoting a vector of x positions.

  • y (numpy.ndarray) – A 1-dimensional numpy ndarray denoting a vector of y positions.

  • x_lims (list) – Lower and upper limits along the x-axis.

  • y_lims (list) – Lower and upper limits along the y-axis.

  • d_max (int) – The maximum polynomial degree for the spatial variation of the field.

Returns:

Pi – A 2-dimensional polynomial matrix representing the spatial variations.

Return type:

numpy.ndarray

class wf_psf.sims.spatial_varying_psf.SpatialVaryingPSF(psf_simulator, d_max=2, grid_points=[4, 4], grid_size=None, max_order=45, x_lims=[0, 1000.0], y_lims=[0, 1000.0], n_bins=35, lim_max_wfe_rms=None, verbose=False, seed=None)[source]

Bases: object

Spatial Varying PSF.

Generate PSF field with polynomial variations of Zernike coefficients.

Parameters:

  • psf_simulator (PSFSimulator object) – Class instance of the PSFSimulator

  • d_max (int) – Integer representing the maximum polynomial degree for the FOV spatial variation of WFE.

  • grid_points (list) – List defining the size of each axis grid for constructing the (constrained random realisation) polynomial coefficient matrix.

  • grid_size (int or None, optional) – Number of points to generate for the grid. If None, the value from grid_points attribute will be used. (default is None)

  • max_order (int) – The maximum order of Zernike polynomials to be used in the simulation.

  • x_lims (list) – A list representing the lower and upper limits along the x-axis.

  • y_lims (list) – A list representing the lower and upper limits along the y-axis.

  • n_bins (int) – An integer representing the number of equidistant bins to partition the passband to compute polychromatic PSFs.

  • lim_max_wfe_rms (float) – The upper maximum value limit for the Wave Front Error (WFE) Root-Mean-Square (RMS) error.

  • verbose (bool) – A flag to determine whether to print warning messages.

Attributes:
lim_max_wfe_rms

Get the upper limit for Wave Front Error (WFE) Root-Mean-Square (RMS).

Methods

build_polynomial_coeffs()

Build polynomial coefficients for spatial variation.

calculate_wfe_rms(xv, yv, polynomial_coeffs)

Calculate the Wave Front Error (WFE) Root-Mean-Square (RMS).

estimate_polynomial_coeffs(xv, yv, Z)

Estimate polynomial coefficients using least squares.

get_monochromatic_PSF(xv, yv[, lambda_obs])

Calculate the monochromatic Point Spread Function (PSF) at a specific position and wavelength.

get_polychromatic_PSF(xv, yv, SED)

Calculate the polychromatic Point Spread Function (PSF) for a specific position and Spectral Energy Distribution (SED).

plot_WFE_RMS([save_img, save_name])

Plot the Wave Front Error (WFE) Root-Mean-Square (RMS) map.
build_polynomial_coeffs()[source]

Build polynomial coefficients for spatial variation.

This method constructs polynomial coefficients for spatial variation by following these steps: 1. Build a mesh based on the provided limits and grid points. 2. Apply random position shifts to the mesh coordinates. 3. Estimate polynomial coefficients using the shifted positions. 4. Choose anchor points on a regular grid and calculate the Wave Front Error (WFE) Root-Mean-Square (RMS)

on this new grid.

  1. Scale the polynomial coefficients to ensure that the mean WFE RMS over the field of view is 80% of the maximum allowed WFE RMS per position.

  2. Recalculate the Zernike coefficients using the scaled polynomial coefficients.

  3. Calculate and save the WFE RMS map of the polynomial coefficient values.

Return type:

None

calculate_wfe_rms(xv, yv, polynomial_coeffs)[source]

Calculate the Wave Front Error (WFE) Root-Mean-Square (RMS).

This method calculates the WFE RMS for a specific position using the provided x and y coordinates and polynomial coefficients.

Parameters:

  • xv (numpy.ndarray) – A 1-dimensional numpy ndarray representing positions along the x-axis.

  • yv (numpy.ndarray) – A 1-dimensional numpy ndarray representing positions along the y-axis.

  • polynomial_coeffs (numpy.ndarray) – A numpy ndarray containing the polynomial coefficients.

Returns:

An array containing the WFE RMS values for the provided positions.

Return type:

numpy.ndarray

estimate_polynomial_coeffs(xv, yv, Z)[source]

Estimate polynomial coefficients using least squares.

This method estimates the polynomial coefficients using the least squares method based on the provided positions along the x and y axes.

Parameters:

  • xv (numpy.ndarray) – A 1-dimensional numpy ndarray representing positions along the x-axis.

  • yv (numpy.ndarray) – A 1-dimensional numpy ndarray representing positions along the y-axis.

  • Z (numpy.ndarray) – A something numpy ndarray representing the Zernike coefficients.

get_monochromatic_PSF(xv, yv, lambda_obs=0.725)[source]

Calculate the monochromatic Point Spread Function (PSF) at a specific position and wavelength.

This method calculates the monochromatic PSF for a given position and wavelength. It utilizes the Zernike coefficients of the specific field to generate the PSF using the PSF toolkit generator.

Parameters:

  • xv (numpy.ndarray) – 1-dimensional numpy array containing the x positions.

  • yv (numpy.ndarray) – 1-dimensional numpy array containing the y positions.

  • lambda_obs (float, optional) – Wavelength of observation for which the PSF is calculated. Default is 0.725 micrometers.

Returns:

The generated monochromatic PSF.

Return type:

numpy.ndarray

Notes

The PSF generator’s Zernike coefficients are set based on the provided positions before generating the PSF.

get_polychromatic_PSF(xv, yv, SED)[source]

Calculate the polychromatic Point Spread Function (PSF) for a specific position and Spectral Energy Distribution (SED).

This method calculates the polychromatic PSF for a given position and SED. It utilizes the Zernike coefficients of the specific field to generate the PSF using the PSF Simulator generator.

Parameters:

  • xv (numpy.ndarray) – 1-dimensional numpy array containing the x positions.

  • yv (numpy.ndarray) – 1-dimensional numpy array containing the y positions.

  • SED (array_like) – Spectral Energy Distribution (SED) describing the relative intensity of light at different wavelengths.

Returns:

A tuple containing: - polychromatic_psf : numpy.ndarray

The generated polychromatic PSF.

  • zernikesnumpy.ndarray

    The Zernike coefficients corresponding to the specific field.

  • opdnumpy.ndarray

    The Optical Path Difference (OPD) corresponding to the generated PSF.

Return type:

tuple

Notes

The PSF generator’s Zernike coefficients are set based on the provided positions before generating the PSF. The SED is used to compute the polychromatic PSF by integrating the monochromatic PSFs over the spectral range.

property lim_max_wfe_rms

Get the upper limit for Wave Front Error (WFE) Root-Mean-Square (RMS).

If the custom upper limit lim_max_wfe_rms is not set, this property returns the maximum WFE RMS value from the PSF simulator. Otherwise, it returns the custom upper limit.

Returns:

The upper limit for Wave Front Error (WFE) Root-Mean-Square (RMS).

Return type:

float

plot_WFE_RMS(save_img=False, save_name='WFE_field_meshdim')[source]

Plot the Wave Front Error (WFE) Root-Mean-Square (RMS) map.

This method generates a plot of the WFE RMS map for the Point Spread Function (PSF) field. The plot visualizes the distribution of WFE RMS values across the field of view.

Parameters:

  • save_img (bool, optional) – Flag indicating whether to save the plot as an image file. Default is False.

  • save_name (str, optional) – Name of the image file to save. Default is ‘WFE_field_meshdim’.

Return type:

None

class wf_psf.sims.spatial_varying_psf.ZernikeHelper[source]

Bases: object

ZernikeHelper.

Helper class for generating Zernike Polynomials.

Methods

calculate_zernike(xv, yv, x_lims, y_lims, ...)

Calculate Zernikes for a specific position.

generate_zernike_polynomials(xv, yv, x_lims, ...)

Generate Zernike Polynomials.

initialize_Z_matrix(max_order, size[, seed])

Initialize Zernike Matrix.

initialize_normalized_zernike_matrix(...[, seed])

Initialize Normalized Zernike Matrix.

normalize_Z_matrix(Z, lim_max_wfe_rms)

Normalize Zernike Matrix.
static calculate_zernike(xv, yv, x_lims, y_lims, d_max, polynomial_coeffs, verbose=False)[source]

Calculate Zernikes for a specific position.

This method computes Zernike polynomials for given positions (xv, yv). The positions (xv, yv) should lie within the specified limits: [x_lims[0], x_lims[1]] along the x-axis and [y_lims[0], y_lims[1]] along the y-axis. Additionally, the positions should be normalized to the range [-1, +1] along both axes.

Parameters:

  • xv (numpy.ndarray) – Array containing positions along the x-axis.

  • yv (numpy.ndarray) – Array containing positions along the y-axis.

  • x_lims (list) – Lower and upper limits along the x-axis.

  • y_lims (list) – Lower and upper limits along the y-axis.

  • verbose (bool) – Flag to indicate whether to print warning messages when positions are outside the specified limits.

Returns:

Array containing the computed Zernike polynomials for the given positions.

Return type:

numpy.ndarray

static generate_zernike_polynomials(xv, yv, x_lims, y_lims, d_max, polynomial_coeffs)[source]

Generate Zernike Polynomials.

[old name: zernike_poly_gen] This method calculates Zernike polynomials based on the given x and y positions, considering a maximum polynomial degree specified by d_max and a set of polynomial coefficients.

Parameters:

  • xv (np.ndarray (dim,)) – x positions.

  • yv (np.ndarray (dim,)) – y positions.

  • x_lims (list) – Lower and upper limits along the x-axis.

  • y_lims (list) – Lower and upper limits along the y-axis.

  • d_max (int) – The maximum polynomial degree for the spatial variation of the field.s

  • polynomial_coeffs (numpy.ndarray) – An array containing the polynomial coefficients.

Returns:

  • numpy.ndarray – A 1-dimensional numpy ndarray representing the spatial polynomials generated

  • from the given positions and polynomial coefficients.

static initialize_Z_matrix(max_order, size, seed=None)[source]

Initialize Zernike Matrix.

This method initializes a Zernike matrix with a specified size determined by the maximum order of Zernike polynomials and the length of the position vector along the x-coordinate axis. The matrix is populated with random values sampled from a standard normal distribution.

Parameters:

  • max_order (int) – The maximum order of Zernike polynomials to be used in the simulation.

  • size (int) – An integer representing the size of the position vector.

  • seed (int) – Seed for random number generation.

Returns:

  • numpy.ndarray – An array of shape (max_order, size) containing randomly generated values

  • from a standard normal distribution to initialize the Zernike matrix.

static initialize_normalized_zernike_matrix(max_order, size, lim_max_wfe_rms, seed=None)[source]

Initialize Normalized Zernike Matrix.

This method initializes a normalized Zernike matrix.

Parameters:

  • max_order (int) – The maximum order of Zernike polynomials to be used in the simulation.

  • size (int) – An integer representing the size of the position vector.

  • lim_max_wfe_rms (int) – The upper maximum value limit for the Wave Front Error (WFE) Root-Mean-Square (RMS) error.

  • seed (int) – Seed for random number generation.

Returns:

A normalized Zernike matrix.

Return type:

numpy.ndarray

static normalize_Z_matrix(Z, lim_max_wfe_rms)[source]

Normalize Zernike Matrix.

This method performs normalization on the Zernike matrix. It calculates normalization weights as the square root of the sum of squares of the Zernike matrix along the second axis. Each row of the matrix is then divided by its corresponding normalization weight, scaled by the maximum allowed Wave Front Error (WFE) Root-Mean-Square (RMS) error.

Parameters:

  • Z (numpy.ndarray) – A numpy ndarray representing the Zernike matrix.

  • lim_max_wfe_rms (int) – The upper maximum value limit for the Wave Front Error (WFE) Root-Mean-Square (RMS) error.

Returns:

Z – The normalized Zernike matrix after applying the normalization process.

Return type:

numpy.ndarray