JWST's MIRI External Flat Engineering template, available in the Astronomer’s Proposal Tool (APT), is used for calibration observations for the MIRI instrument.  

Introduction

These parameters are required to obtain MIRI External Flat observations. Note that this type of observation cannot be obtained as a parallel to normal science observations, but can be in parallel with slews, except where the parameter LAMP USE = OFF THEN ON, a TARGET NAME is specified, or where DITHER = TRUE.

The MIRI External Flat Engineering template consists of the following parameters:

General Information  

The following parameters are generic to all templates, and are not discussed in this article: Observation Number, Observation Label, Observations Comments, Target Name, Mosaic Properties, and Special Requirements.

Target Name 

Select the TARGET NAME from the list of targets previously entered (see list of targets) or select NONE. If POINTING TYPE=PARALLEL, TARGET NAME=NONE.

Science Exposures

Pointing Type

POINTING TYPE = PARALLEL (default), PRIME

This parameter enables the user to control whether the data will be obtained in parallel like other calibrations, or as a primary observation like regular science.

Note for developers: This field is not saved directly into the database.

If PRIME, make TARGET NAME required, make the default “None Selected,” and remove the NONE option (so the user is prompted to select a target). Give an error if any PARALLEL special requirement is present.

If PARALLEL, set TARGET NAME = NONE (not changeable), set DITHER=FALSE,  hide the DITHER options, set LAMP USE = ON ONLY, and add a PARALLEL SLEW ONLY special requirement. Give an error if the PARALLEL SLEW ONLY special requirement is not present.

Detector 

DETECTOR [DETECTOR] = IMAGER, MRS, ALL

This parameter specifies the detector array(s) on which data will be collected. If IMAGER is selected, data is collected on the single Imager detector array. If the selection is MRS, data is collected on both of the IFU detector arrays.  When the selection is ALL, data is collected from all three detector arrays.

Note for developers: The following tables show what should be displayed in the GUI, along with the appropriate commanding name for the database, for each value of DETECTOR.

Imager Subarray  

IMAGER SUBARRAY [SUBARRAY] = FULL, BRIGHTSKY, SUB256, SUB128, SUB64, SLITLESSPRISM, MASK1550, MASK1140, MASK1065, MASKLYOT

For DETECTOR = IMAGER or DETECTOR = ALL specify the choice of subarray. This parameter specifies the region of the detector that is to be read out (see Table 1).

The value of SUBARRAY for the MRS detectors will always be FULL and will be set to that value by the scripts.

Table 1. Subarrays for MIRI Imager and ALL Flats

Note for developers: users can specify one or more combinations of the parameters below for FLATs.

Dither Patterns

Some MIRI External Flat observations will require dithering; see MIRI Dithering for details.

Dither  

DITHER = TRUE, FALSE

This field indicates if dithering is desired. When set to TRUE, the following fields need to be specified. If POINTING TYPE = PARALLEL, the DITHER options are not available. 

Dither Type  

DITHER TYPE [PATTERN_TYPE] =  4-POINT-SETS (default), 2-POINT, SPARSE-CYCLING, CYCLING, REULEAUX, CYCLING-MICRO, MRS 4-POINT, MRS 2-POINT, LFLAT-CORON1065, LFLAT-CORON1140, LFLAT-CORON1550, LFLAT-CORONLYOT, PFLAT-CORON1065, PFLAT-CORON1140, PFLAT-CORON1550, PFLAT-CORONLYOT 

This parameter specifies the type of dither to be executed. All Dither Types except for 2-POINT and CYCLING-MICRO require additional parameters.

For DETECTOR=MRS, MRS 2-POINT and MRS 4-POINT are the only dither types allowed.

For DETECTOR=ALL, Coron PFLAT and LFLAT dithers are not allowed.

4-point-sets    

This pattern is based on an overall set of 40 points that are grouped into sets of 4 . For the three smallest subarrays a particular four point set will be used automatically (so STARTING SET and NUMBER OF SETS will both need to be 1). There are different dither definitions based on the filter bandpass and setting of OPTIMIZED FOR. These are the five special cases:

1. OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB128
2. OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB256
3. OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB64, SUB128, or SUB256 and FILTER = SHORT
4. OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB64 and FILTER = LONG
5. OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB128, or SUB256 and FILTER = LONG

where:

• SHORT FILTERS = OPAQUE, FLENS, F560W, P750L, F770W, F1000W,F1065C, F1130W, F1140C
• LONG FILTERS = F1280W, FND, F1500W, F1550C, F1800W, F2100W, F2300C, F2550W, F2550WR

Note to developer: OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB64 should not be allowed.

Starting Set 

Select the STARTING SET [STARTING_SET] of dither points. The range is 1-10.

Note for developers: multiply STARTING_SET  -1 by 4 and add one to get the first dither index point.

Number of Sets  

Select the NUMBER OF SETS [NUMBER_OF_SETS] which is the number of 4-point dither sets. The range is 1-10.

Note for developers: multiply this number by 4 to get the number of index points to use.

Optimized For  

OPTIMIZED FOR [OPTIMIZED_FOR] = POINT SOURCE (default), EXTENDED SOURCE

Select the type of science that the dither is optimized for. If a target is chosen before a dither is created the default is POINT SOURCE unless the target was marked EXTENDED in which case the default is EXTENDED SOURCE. If SUBARRAY=SUB64 then OPTIMIZED FOR = EXTENDED SOURCE is not available.

After OPTIMIZED FOR has a selected value, it will not change if a target is selected, a target's EXTENDED value is changed, or a new target is selected. The user must manually change the value.

 Note for developers: If the target is marked EXTENDED, change the default value to EXTENDED SOURCE.

Direction  

DIRECTION [DIRECTION] = POSITIVE (default), NEGATIVE

Select the direction of the dither. For DITHER TYPE=MRS 2-POINT or MRS 4-POINT, if OPTIMIZED FOR=EXTENDED SOURCE,  DIRECTION must be NEGATIVE. 

Note for developers: DIRECTION = NEGATIVE means that the X-offset in the dither table is multiplied by -1.

Note for developers: see Appendix F1 for dithering details.

2-point 

This is a simple 2-point pattern.

Sparse Cycling 

The Sparse-Cycling pattern uses the same list of 311 pointing positions as described for Cycling below, but any sub set of the points may be specified.

Points 

Type a monotonically increasing list of POINTS [POINTS] which are indices from the Cycle Table using commas and dashes (i.e. 3, 5, 7-9, 15-19).

Cycling 

The Cycling pattern consists of a list of 311 pointing positions where the x- and y-offset distributions (from the central position) are well-described by a Gaussian; the pattern is drawn from the Spitzer IRAC Cycling pattern. Observations may begin at any position in the cycling pattern and include an arbitrary number of dithers.

Starting Point 

STARTING POINT [STARTING_POINT] = 1, 2, 3, …, 310, 311

This parameter specifies the index of the first dither position.

Number of Points 

NUMBER OF POINTS [NUMBER_OF_POINTS] = 4, 5, 6,...

This parameter specifies the number of dither positions of the cycling pattern to execute in sequence.

If the combination of STARTING POINT and NUMBER OF POINTS exceeds 312, the pattern cycles back to use points 1, 2, 3, etc.

No explicit maximum is set on the number of points.  The number of points, however, is effectively limited by the maximum allowed visit duration.

Reuleaux 

The Reuleaux pattern is a set of 12 dither positions that defines a Reuleaux triangle; the pattern is drawn from the Spitzer IRAC 12-point Reuleaux pattern.

Pattern Size

PATTERN SIZE [PATTERN_SIZE] = DEFAULT (default), SMALL, MEDIUM, or LARGE

This parameter, which only applies to CYCLING, SPARSE-CYCLING  and REULEAUX, specifies the relative extent of the dither pattern (SMALL, MEDIUM, or LARGE). The choice of SUBARRAY restricts the available options for PATTERN TYPE and PATTERN SIZE as indicated in Table 2.

  Table 2. Allowed Dither Types and Patterns Sizes by Subarray 

When the PATTERN SIZE is not specified by the user the DEFAULT pattern will be used based upon the choice of filter, pattern and subarray according to the following rules:

• For SUBARRAY = FULL, BRIGHTSKY and SUB256, the default PATTERN SIZE for Cycling, Sparse Cycling and Reuleaux is LARGE.
• For SUBARRAY = SUB128, and SUB64, the default (and only legal) PATTERN SIZE for Cycling and Sparse Cycling is SMALL.
• The default values for Reuleaux for SUBARRAY = SUB128 and SUB64 vary and are listed below:

•  For SUBARRAY = SLITLESSPRISM, the default PATTERN SIZE for Cycling, Sparse Cycling and Reuleaux is SMALL.

Cycling-micro

The Cycling-micro pattern is a sub-pixel dither pattern used in checking Point Spread Function during commissioning.

Lamp Use  

LAMP USE = OFF THEN ON, ON ONLY, OFF ONLY

This field indicates if the calibration is to be executed twice; first with the calibration lamp OFF, then with the calibration lamp ON. This is done in order to permit subtraction of external objects from the lamp on data.  Note that if OFF THEN ON is requested, you will be prompted separately for the NUMBER OF INTEGRATIONS and NUMBER OF GROUPS for the OFF exposures and the ON exposures. If POINTING TYPE = PARALLEL, LAMP USE=ON ONLY.

Note for developers: If LAMP USE = ON ONLY, then populate Lamp Power field in the exposure spec [LAMP_POWER] with ON. If LAMP USE = OFF THEN ON, then populate Lamp Power field in the exposure spec [LAMP_POWER] with all the OFF exposures then all the ON exposures. The same value of READOUT PATTERN should be used for the lamp off exposures as was specified for the lamp on exposures.

Maximum lamp on time

 The Lamp On Time for an observation is limited to 7080 seconds for one lamp, or 3300 seconds for both lamps. The number of lamps depends on the selected DETECTOR: One lamp for IMAGER or MRS, and both lamps for ALL. Maximum Lamp On Time is defined in the PRD observing_limitations table as max_lamp_on_duration_miri_single and max_lamp_on_duration_miri_dual.

 Observations that use a lamp (LAMP USE = OFF THEN ON or ON ONLY) must fit into a single visit.

Grating Wheel Direction

GRATING WHEEL DIRECTION = ALLOW AUTO REORDER (default), DISALLOW AUTO REORDER

Select the rule for ordering exposures. 

For approved proposals, the Long Range Plan (LRP) may reorder exposures according to their WAVELENGTH RANGE which may be Long, Medium, or Short (L-M-S). This is done to optimize mechanical moves of the MIRI Grating Wheel. 

To prevent the LRP from reordering exposures, select DISALLOW AUTO REORDER. Exposures may be reordered by the user.

• ALLOW AUTO REORDER -  Allows the LRP (Long Range Plan) to reorder exposures. Note that the sequence of wavelength ranges must be a full grating wheel rotation such as L-M-S or S-M-L to actually be auto reordered by the LRP.
• DISALLOW AUTO REORDER -  Directs the LRP not to reorder exposures, and retains the exposure order set by the user. 

Exposure Specifications 

For each exposure to be executed, specify the FILTER (for DETECTOR = IMAGER or ALL), WAVELENGTH (for DETECTOR = MRS or ALL), READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, NUMBER OF INTEGRATIONS/EXPOSURE, and the NUMBER OF EXPOSURES/DITHER.

Filter  

For DETECTOR = IMAGER or DETECTOR = ALL, select the name of each FILTER (see Table 2) you wish to use.

Table 2. Filters Available for MIRI Imager External Flat Observations

Wavelength  

WAVELENGTH1&4 = SHORT (A), MEDIUM (B), LONG (C)

WAVELENGTH2&3 = SHORT (A), MEDIUM (B), LONG (C)

For DETECTOR = MRS or DETECTOR = ALL select each pair of wavelength region (see Table 3) you wish to use for channels 1 and 4, and for channels 2 and 3.

Table 3. Wavelength Regions Available for MIRI MRS Flat Observations 

Readout Pattern  

READOUT PATTERN [READOUT PATTERN] =  FASTR1, FASTR100, SLOWR1, FAST, SLOW

This field specifies the readout pattern to be used to obtain the data.

FASTR100 is allowed only when SUBARRAY=SUB64

SLOW and SLOWR1 are allowed only when SUBARRAY=FULL and DETECTOR=IMAGER

Number of Groups/Integration   

NUMBER OF GROUPS/INTEGRATION specifies the number of groups in an integration. The default value is 4.  Values 1-3 are allowed but not recommended (warning).

 MIRI integration duration may not be greater than 2000 seconds. Integration time = (Frame time * NUMBER OF GROUPS/INTEGRATION). Frame time is a property of the selected READOUT PATTERN. For more information, see MIRI Detector Readout Overview.

Note to developer: Maximum MIRI integration duration is specified in the PRD as max_integration_duration_miri  in the observing_limitations table.

Number of Integrations/Exposure   

This field specifies the NUMBER OF INTEGRATIONS/EXPOSURE to be obtained.

Number of Exposures/Dither   

NUMBER OF EXPOSURES/DITHER [NEXP] specifies the number of times the flat exposure is to be repeated. The default value is 1.

Change log