NAME

PARAMETERS

input filename

This is simply the input file/stream name, i.e., where the rays are coming from.

outfile filename

This is the name of the rdb file in which the qshut_focus results are to be placed.

bcdiam real

This simply tells the beam-centering procedure what diameter pinholes should be used (in mm).

bcspacing real

This provides the beam-centering procedure with the particular pinhole spacing to use, i.e., the distance between pinhole centers (in mm).

bcnumholes integer

This parameter informs the beam-centering procedure how many pinholes to use for each scan.

bcdie boolean

This parameter tells qshut_focus whether or not to die if the beam-centering procedure reaches its iteration limit. If it is set to no, then qshut_focus continues on, using whatever value the beam-centering procedure had determined as the center when the iteration limit was reached.

imcen_x real

The user can dictate where the mcp detector should be placed for the initial centering of the entire beam. Hence this parameter represents the user's best guess at the x coordinate (in mm) of the image center.

imcen_y real

Same as imcen_x, except in reference to the y-coordinate.

zguess real

The detector must be started off at some z-location, which is what this parameter provides (in mm). One hopes that the user will be able to make an educated guess so that this initial image plane is somewhere in the vicinity of the actual focal plane.

tol real

qshut_focus is an iterative process in which the detector position is adjusted after each focus error is determined. This parameter tells qshut_focus what the tolerance should be for these focal corrections (in mm), i.e., exactly how close is close enough?

wedge_x real

This parameter and the following two parameters tell qshut_focus where to place the center of the quadrant shutter apparatus (in mm). (wedge_x, wedge_y) thus marks the wedge_point, as all wedge quadrants extend from this point. wedge_z represents the axial location of the wedge (quadrant-shutter) plane.

wedge_y real

This is the y-coordinate of the wedge point. (See wedge_x).

wedge_z real

This is the z-coordinate of the wedge plane. (See wedge_x).

plot boolean

If set to yes, this option will provide the user with scatter-plots for the mcp run-through, and plots of the aperture fluxes if the slit binning option has been selected. Note : plots are not displayed of the aperture fluxes if the pinhole binning option is selected, because an onerous 3-D plot would need to be generated.

hsi_bin enumerated string

This parameter tells qshut_focus whether to use slits or pinholes for the binning apertures. In either case, there are a number of aperture- specific binning parameters (listed later on) which must also be set.

rclip real

For the centroiding which is performed during the first quadrant-shutter iteration (with the mcp detector), the user must specify a clipping radius (in mm). If no clipping is desired, the user should simply choose an extremely large clipping radius.

shell string

This parameter must be specified so that the correct mirror radius can be used (for the focal error determinations). The shell can be set to either 1, 3, 4, 6, 1346, or tma.

npinholes integer

If pinhole binning has been selected, this parameter tells qshut_focus how many pinholes should be laid down in each direction of the square grid.

phole_diam real

If pinhole binning has been selected, the user must specify the diameter of these pinholes.

hslitwidth integer

If slit binning has been selected, this parameter indicates what the width of the horizontal slits should be (in microns).

hslitlength integer

If slit binning has been selected, this parameter indicates what the length of the horizontal slits should be (in microns).

hslitnum integer

This parameter tells qshut_focus how many horizontal slits to lay down in the vertical direction. Note that if slitoverlap is turned on, twice the number of slits must be used in order to cover the same amount of area.

vslitwidth integer

If slit binning has been requested, the user must input the width of the vertical slits to be used (in microns).

vslitlength integer

If slit binning has been requested, the user must input the length of the vertical slits to be used (in microns).

vslitnum integer

This parameter tells qshut_focus how many vertical slits to lay down in the horizontal direction. Note that if slitoverlap is turned on, twice the number of slits must be used in order to cover the same amount of area.

slitoverlap boolean

This parameter gives the user the option of overlapping the slits in both directions. If it is turned off, then the slits are simply placed side by side, but if it is turned on, then the slits are laid down in 1/2 overlap style, i.e., each half of a given slit has complete overlap on that side, so that the centers of each slit are spaced half a slitwidth apart. When slitoverlap is turned on, hslitwidth and vslitwidth must both be even numbers, because the 1/2 overlap must be an integral number of microns.

debug string

This parameter gives the user the option of setting various debug flags. As of now, there are no particular debug options in qshut_focus.

version boolean

If set to yes, simply print the version and die.

mode string

This specifies which parameter mode qshut_focus is to be run in. As of now, the only mode is ``a'' mode.

DESCRIPTION

This routine accepts a phot/dpde ray stream as input, and writes a summary of the results (including the centroids, tilts, and focal errors for each quad-shutter iteration) to an rdb file. qshut_focus is a perl script which calls a number of different modules during execution. All necessary parameters are either initialized internally, or else can be set through the qshut_focus parameter file. The following modules must have accessible parameter files when qshut_focus is invoked: bpipe2phot, phot2bpipe, wedge, projray, spatquant, img_slitsim, centroid, pinhole, mcp2, and beam-center. It is, however, true that not all of these modules will be called in any one run of qshut_focus, as some of them are dependent on the binning mechanism chosen (which is either slits or pinholes).

On the first iteration, qshut_focus uses the mcp as its detector. (Note: An iteration refers to the entire process of focal adjustment as described in the opening paragraph). First the mcp routine is called with user- input initial x,y,z coordinates, and the entire beam is binned. Then centroid is called in order to locate the center of the beam, so that in the subsequent quadrant shutter runs, the mcp detector can be centered properly. After this, the rays are passed though each of the four quadrants (actually 88 degree sectors) by a call to wedge and projray, and are binned and centroided by the mcp and centroid modules. The (x,y) centroids which were found for each of the four quadrants are then used to compute the x and y tilts and focal errors, and this information is written to the output rdb file. The average focal error (i.e., between x and y) is then added as a correction factor to the initial zguess , and the average focal error is compared with the user- specified tolerance.

If the average focal error exceeds the tolerance (as it probably will unless the initial zguess is remarkably close to the actual focus, or the tolerance is ridiculously large), then qshut_focus will undergo further iterations, each one characterized by the following sequence. The beam-center module will be called (with parameters as set in the qshut_focus par file) in order to re-determine the (x,y) beam center at the new axial location. Then the rays will be passed through each of the four quadrant apertures, and binned in accordance with the user-specified aperture binning mechanism. If hsi_bin has been set to slits, then spatquant and img_slitsim will be called to bin the rays, while if hsi_bin has been set to pinholes, the pinhole module will take care of the binning. (More on these two binning mechanisms later). In either case, centroids will be computed for each quadrant (using the aperture data), and the rest of the iteration will be carried out in the same fashion as the first iteration (as was explained in the last paragraph).

Now, as promised, here is a word about both the slit and pinhole binning mechanisms. For slit binning, spatquant is called with 1 micron x 1 micron pixels, and is given an image size as determined from the slit binning parameters in qshut_focus (i.e., the horizontal and vertical slit width, length, number, and overlap). An image is created which is centered at the location as determined from the latest call to beam-center, and which is clipped to the size of the mcp detector. Then img_slitsim is called to sample the image with slits and generate files listing the photon counts in each of the slits. This output is then parsed, and the horizontal slits are used to find the y centroid, while the vertical slits are used to find the x centroid. The pinhole binning mechanism is somewhat simpler. An n x n grid of pinholes is centered about beam-center's most recent result (with end to end spacing, and diameter & number as set by the user). This is of course accomplished through the use of the pinhole module, which produces a report file which can easily be parsed. The (x,y) centroid is hence determined from this file.

Although this description is somewhat brief, much information can be gleaned from simply reading the many parameter descriptions and (for internal details) from reading documentation on the particular modules which qshut_focus calls.

AUTHOR