Adding distortion to PSFs

[shanosborne]

This will automatically make calc_psf() produce a 4 extension PSF: over-sampled, detector-sampled, over-sampled and distorted, and detector-sampled and distorted.

This will be the default state, but it can be turned off with the keyword argument add_distortion=False. NIRCam, NIRISS, and FGS also have the keyword crop_psf=True which will make the distorted and un-distorted PSFs be the same size (this is always true for the other instruments).

This closes issue #192

[shanosborne]

How do we include a download of pysiaf in webbpsf? I realize that I'm not sure how do this

[mperrin]

We don’t directly include a download of it - we set it up in the dependencies as another package to include first. Partly this depends on Johannes adding it to astroconda for the easiest installation. But we can install it directly from github as well for the Travis CI test builds.

What’s your schedule today? Could we meet at 11 maybe and I can talk you through how to do this?

[shanosborne]

I actually have a meeting at 11 and one at 1, but I'm free anytime other than that

[mperrin]

Then let’s plan for 2

[mperrin]

Looks like a couple of the test functions are failing. You’ll want to try running those functions locally to try debugging them.

[coveralls]

Coverage increased (+2.0%) to 32.867% when pulling 8cf0a8b25af77f17b622ce438de429ef6faf4a14 on shanosborne:bug_fixes into 481154f284c7fb3551a9de9f870456401030b187 on mperrin:master.

[mperrin]

@JarronL if you've got the time, you might be interested in taking a look at this PR. @shanosborne has implemented geometric distortions of PSFs based on the SIAF distortion coefficients.

I'm mentioning this to you both because I expect you might be interested in using this in pyNRC, and also more generally because it would be nice to have feedback on the tutorial notebook from someone on one of the instrument teams. Please let Shannon and me know if anything's unclear in that tutorial or if you can think of any questions you'd like answered in it. Thanks.

[JarronL]

I was actually looking at this over the weekend. Could you clarify how these distortions relate to information inside si_zernikes_isim_cv3.fits, which we use to apply WFE variations to the PSF? Are these things mutually exclusive or would you use both when generating a location-specific PSF?

[JarronL]

Thinking about this a little more, I'm still unsure if it makes sense to apply these distortions to the PSF. For instance, if I have an off-axis point source at some sky location, the PSF certainly gets distorted, but my impression is that this should already be accounted for in the position-dependent WFE aberrations? I think the SIAF information is perhaps more useful in distorting an input image (such as positions of a star cluster) that are then convolved with the field-dependent PSF? Not exactly sure how I would handle extended sources...

[mperrin]

Not exactly. These are really orthogonal issues, and can both be applied.

• The position-dependent WFE data (and telescope OPD files, etc) reflect changes in wavefront phase at a given location in the pupil.
• The geometric distortion data reflect changes in the apparent locations of each given location.

I find this easier to understand with a concrete example. HST ACS has fairly large distortion, larger than the other HST instruments. This can easily be seen in PSFs, for instance figures 5.15 and 5.16 at http://www.stsci.edu/hst/acs/documents/handbooks/current/c05_imaging7.html#357374. The diffraction spikes are not orthogonal in the output PSF, despite being caused by orthogonal SM supports in the HST OTA pupil. The HST PSF simulator Tiny Tim models this as a transformation of the output PSF to add the distortion, and we're trying here to include a similar treatment for JWST.

The result of geometric distortion is that detector pixels are not ideal square sections of the sky. They're skewed parallelograms. The corresponding effect for JWST is that the PSF diffraction spikes aren't at precisely 60 degree intervals, but ever so slightly off from that. This is a different mapping than the WFE - that affects the amplitude of speckles, this changes their apparent locations.

Diffractively I think the more rigorous way to think about this would be as a distortion of the telescope exit pupil, so the axes of V2 and V3 aren't skew there, and so on for higher order terms. Then that skewed distorted pupil gets Fourier transformed into a skewed PSF. But we can alternatively apply a model of this effect in the image plane too, and that's in practice easier since we have detailed image plane distortion all over the field of view but don't have the equivalent amount of measurements in pupil space.

[mperrin]

For JWST the distortions are pretty small in most cases. Largest for FGS, as can be seen in this figure of the focal plane: https://jwst-docs.stsci.edu/display/JTI/JWST+Field+of+View?preview=/32316043/32316051/JWST%20FOV.png

[JarronL]

Thanks. I think my confusion stems from the fact that I'm unclear exactly how the SI WFE extractions were performed (were these derived from weak lens observations?). Your explanation seems to make sense, especially if I think about it in terms of distortion of the field far away from a given PSF. The HST data clearly demonstrates that the PSF diffraction spikes get skewed when projected on the detector plane. This makes sense in the context of how the SI optics distorts the field.

That being said, I'm still not sure when it's best to add distortion to a simulated observation. For a single point source, it probably doesn't matter. However, if you just distort the PSF, then that will not modify the shape of an extended source unless you have a differently distorted PSF for every pixel. Perhaps the most straightforward approach is to build an undistorted convolved image then apply rotation and image distortion? Either way, the apply_distortion() function seems like it will do the job.

[mperrin]

For where the SI WFE data comes from, see the draft release notes at the URL I emailed you yesterday. There’s a link there to David Aronstein‘s ISIM optics cryotest report, both the exhaustive 200 page NGIN version and the more digestible SPIE paper.

You’re absolutely right that distorting extended sources is more complicated than what this function does. This is just one piece of the puzzle for enabling simulating data just a tiny bit more like what will really be on the detectors...

[mperrin]

@shanosborne anything more you're planning to do on this now, or do you think it's basically ready to merge?

[shanosborne]

@mperrin I think this has everything needed for the distortion functions (and I also updated the MIRI rotation value in this pull request). The only thing is that I haven't gotten a chance to talk to you about the pupil shear values, but that could be done separately.

[mperrin]

Sure, pupil shear can be a separate PR. I'll go ahead and merge this now.