Update MIRI detector cross artifact model; fixes #415

docs/jwst.rst

@@ -418,6 +418,38 @@ however monochromatic PSFS computed for the imager may be used as a reasonable
 proxy for PSF properties at the entrance to the MRS slicers.
 
 
+MIRI detector cross artifact
+-----------------------------
+
+The MIRI imager's Si:As IBC detector exhibits a so-called "cross artifact", particularly at
+short wavelengths (5-8 microns), due to internal diffraction of photons within the detector subtrate
+itself. See `Gaspar et al. 2021 <https://ui.adsabs.harvard.edu/abs/2021PASP..133a4504G/abstract>`_ for details.
+WebbPSF implements a simplified model for this effect, following the approach described by Glasse et al. in
+MIRI technical report MIRI-TN-00076-ATC_Imager_PSF_Issue_4.pdf. The model coefficients have been adjusted to
+better match the cross artifact amplitudes from WebbPSF to the MIRI Calibration Data Product reference PSFs.
+
+.. note:: Where to find Results from the Cross Artifact Model
+
+    The cross artifact is added alongside the geometric distortion step, after the optical propagation. The results
+    are stored in FITS extensions 2 and 3 (ext names OVERDIST and DET_DIST for oversampled and detector sampled, respectively
+    *not* in the default 0th extension which is the raw oversampled PSF.  E.g.::
+
+        miri = webbpsf.MIRI()
+        psf = miri.calc_psf()
+        webbpsf.display_psf(psf, ext=3)
+        result = psf['DET_DIST'].data   # This is the PSF with the cross artifact model included
+
+
+.. figure:: ./jwst_figures/miri_cross_artifact.png
+   :scale: 75 %
+   :align: center
+   :alt: MIRI cross artifact
+
+   Comparison of models for the MIRI detector cross artifact.  Click for full size. Shown are the MIRI Calibration Data
+   Product PSFs (Left), the WebbPSF results (Center) and their difference.
+   The cross artifact is negligible at wavelengths beyond ~12 microns.
+
+
 Coronagraphy
 -------------
 

webbpsf/distortion.py

@@ -356,10 +356,19 @@ def apply_miri_scattering(hdulist_or_filename=None, kernel_amp=None):
                        'F1065C': 0.00010, 'F1140C': 0.00007, 'F1550C': 0.0,
                        'F2300C': 0.0}
 
+    # The above values are from that tech report, but empirically we need higher values to
+    # better match the MIRI CDP PSFS. See e.g. MIRI_FM_MIRIMAGE_F560W_PSF_07.02.00.fits
+    # and https://github.com/spacetelescope/webbpsf/issues/415
+    kernel_amp_corrections = {'F560W': 4.05, 'F770W': 4.1, 'F1000W': 3.8,
+                               'F1130W': 2.5, 'F1280W': 2.5, 'F1065C': 2.5, 'F1140C': 2.5}
+
     # Set values if not already set by a keyword argument
     if kernel_amp is None:
         kernel_amp = kernel_amp_dict[filt]
 
+        if filt in kernel_amp_corrections:
+            kernel_amp *= kernel_amp_corrections[filt]
+
     ext = 1  # edit the oversampled PSF (OVERDIST extension)
 
     # Set over-sample value

webbpsf/tests/test_distortion.py

@@ -207,7 +207,7 @@ def test_apply_miri_scattering():
         if ext == 2:
             value = 5e-7
         else:
-            value = 1e-6
+            value = 1.5e-6
 
         # Show that these corner squares contain very small values
         assert_statement = "should have lower values because the scattering shouldn't be adding much to this region." \