Fixing 'make_rotated_aperture' In Hcipy: A Bug Report

It appears there's an ongoing issue with the make_rotated_aperture function in the hcipy package. Users have reported that while the initial, unrotated aperture displays correctly, the rotated version often returns all zeros or produces errors. Let's dive into the details, explore the problem, and discuss potential workarounds.

Understanding the Issue

The core of the problem lies within how make_rotated_aperture handles the rotation of the aperture. Several users have noted that after applying this function, the resulting pupil or aperture field becomes completely black (all zeros), indicating that the rotation process isn't working as expected. This is particularly evident when trying to visualize the rotated aperture using hcipy.imshow_field.

The initial bug report, as mentioned, was addressed in pull request #265. However, subsequent reports suggest the issue persists in version 0.7.0 of hcipy. This indicates that either the fix was incomplete, or a regression has occurred.

Code Examples Demonstrating the Bug

To illustrate the problem, let's revisit the code snippets provided by the users. These examples clearly showcase the unexpected behavior.

Example 1

This code snippet demonstrates the issue with a Keck aperture. The unrotated aperture displays correctly, but the rotated version returns all zeros.

import matplotlib.pyplot as plt 
import hcipy
import numpy as np

if __name__ == "__main__":
    angle = 30
    angle_rad = angle*np.pi/180

    pupil_grid = hcipy.make_pupil_grid(256, 12) 
    aperture = hcipy.aperture.make_keck_aperture(normalized=False)
    rot_aperture = hcipy.aperture.make_rotated_aperture(aperture, angle_rad)

    #unrotated
    telescope_pupil = hcipy.evaluate_supersampled(aperture, pupil_grid, 8)
    #rotated
    rot_telescope_pupil = hcipy.evaluate_supersampled(rot_aperture, pupil_grid, 8)

    #first iteration works, second fails
    for pup in [telescope_pupil, rot_telescope_pupil]:
        im = hcipy.imshow_field(pup, cmap='gray')
        plt.colorbar()
        plt.xlabel('x / D')
        plt.ylabel('y / D')
        plt.show()

When you run this code, the first plot (unrotated) will show the Keck aperture as expected. However, the second plot (rotated) will be completely black, indicating all values are zero. This is not the intended behavior.

Example 2

This example uses a LUVOIR-A aperture and demonstrates a similar issue. The unrotated aperture displays correctly, but the rotated version causes an error.

import matplotlib.pyplot as plt 
import hcipy
import numpy as np

    aperture = hcipy.aperture.make_luvoir_a_aperture(normalized=True)
    grid = hcipy.make_pupil_grid(1000,1)
    angle = 45

    plt.figure()
    hcipy.imshow_field(aperture(grid), cmap = "gray") ## no error
    plt.show()

    #still doesn't work
    rot_aperture = hcipy.aperture.make_rotated_aperture(aperture, angle*np.pi/180)
    
    plt.figure()
    hcipy.imshow_field(rot_aperture(grid), cmap = "gray") ## causes error
    plt.show()

In this case, the imshow_field function, when applied to the rotated aperture, may raise an error or simply display a blank image. This further confirms the issue with the make_rotated_aperture function.

Possible Causes and Debugging Strategies

Several factors could contribute to this issue. Here are some potential causes and debugging strategies:

1. Incorrect Angle Conversion: Ensure that the angle is correctly converted to radians before being passed to the make_rotated_aperture function. Although the provided examples do this correctly, it's always good to double-check.
2. Grid Resolution: The resolution of the pupil grid could be a factor. If the grid is too coarse, the rotation might introduce aliasing or other artifacts that lead to incorrect results. Try increasing the number of pixels in the pupil grid.
3. Supersampling Issues: If you're using supersampling, ensure that it's being applied correctly. Incorrect supersampling can lead to the rotated aperture being incorrectly evaluated.
4. Underlying Bug in hcipy: As indicated by the initial bug report, there might be an underlying issue within the hcipy library itself. If none of the above strategies work, this is the most likely cause.

Debugging Tips

• Inspect Intermediate Values: Print out the values of the aperture and rotated aperture fields to see if there are any obvious issues.
• Simplify the Code: Reduce the complexity of the code to isolate the problem. For example, try a simple circular aperture instead of a complex telescope aperture.
• Check for Updates: Ensure you're using the latest version of hcipy. If the issue has been fixed in a newer version, upgrading might resolve the problem. However, in this case, the user is already on version 0.7.0, which should include the fix from PR #265.

Workarounds and Potential Solutions

If you're encountering this issue and need a workaround, here are a few potential solutions:

1. Manual Rotation: Instead of using make_rotated_aperture, you could manually rotate the aperture field using NumPy or SciPy functions. This gives you more control over the rotation process and might avoid the bug in hcipy.

   from scipy.ndimage import rotate
   
   # Assuming 'aperture_field' is your aperture field on a grid
   rotated_aperture_field = rotate(aperture_field, angle, reshape=False)
   

   Note that you'll need to ensure that the rotation is performed around the center of the grid and that the grid is sufficiently large to accommodate the rotated aperture.

2. Coordinate Transformation: Another approach is to transform the coordinates of the pupil grid before evaluating the aperture. This involves rotating the coordinates in the opposite direction of the desired aperture rotation.

   # Create a rotated grid
   rotated_grid = pupil_grid.rotated(-angle_rad)
   
   # Evaluate the aperture on the rotated grid
   rotated_aperture = aperture(rotated_grid)
   

   This method can be more efficient than rotating the entire aperture field, especially for high-resolution grids.

3. Contribute to hcipy: If you're comfortable with Python and have some experience with scientific computing, consider contributing to the hcipy project. You could investigate the make_rotated_aperture function, identify the bug, and submit a pull request with a fix. This would not only help you but also benefit the entire hcipy community.

Conclusion

The make_rotated_aperture function in hcipy appears to have a persistent issue, causing rotated apertures to return all zeros or produce errors. While the initial bug report was supposedly addressed, users continue to encounter this problem in version 0.7.0. By understanding the issue, exploring potential causes, and implementing workarounds like manual rotation or coordinate transformation, you can mitigate the problem and continue your work. It's crucial to stay updated with the latest version of hcipy and contribute to the community by reporting bugs and suggesting fixes. By working together, we can improve the reliability and usability of this valuable tool for high-contrast imaging.

For more information about hcipy and its functionalities, you can visit the official hcipy documentation. This is a great resource for understanding the library's capabilities and finding solutions to common problems.