ph_survey

NAME

ph_survey - runs beam-center on the same input ray stream for a variety of different pinhole parameters

PARAMETERS

ph_survey uses the standard parameter interface

input filename: This is simply the input file/stream name, i.e., where the rays are coming from.
tag filename: The tag parameter gives the name of the rdb file in which the ph_survey results will be written. (Actually, the filename will be tag _res). The rdb results file will contain the determined beam center and required number of iterations for each beam-center run which ph_survey performs.
xinit real: This is the x-coordinate of the location where the user wishes the ph_survey program to start, i.e., in all of the beam-center runs made using the first (and largest) pinhole diameter, the pinholes will be centered around this x-value. For other pinhole diameters, the pinholes will be centered at the beam's center as determined by the set of runs immediately preceding it.
yinit real: Same as xinit, except in reference to the y-coordinate.
photdens real: This is merely a ``database parameter'', i.e., one that is not necessary for the ph_survey module itself, but which provides information about the input rays which could be useful in the database. For instance, by specifying the photon density explicitly, the same ph_survey run can be performed on ray streams which only differ in photon density, and the database can thus keep records on both runs, and distinguish between them (rather than simply erasing the old data). The photon density should be provided in counts per square millimeter, for clarity.
shell integer: This is another ``database parameter'', which specifies which shell the incoming rays were reflected from. (Please see photdens for my ``definition'' of a ``database parameter'').
version boolean: If set to yes, simply print the version and die.
deug string: This parameter gives the user the option of setting various debug flags in the beam-center module.
mode string: This specifies which parameter mode ph_survey is to be run in. As of now, the only mode is ``a'' mode.

DESCRIPTION

ph_survey is a module which allows the user to run the beam-center procedure on the same input ray stream with many different combinations of pinhole parameters. To be precise, ph_survey varies the number of pinholes used, and their diameter and spacing, using a nested ``for loop'' to run beam-center on every possible combination of these three parameters. It accepts a phot/dpde ray stream as input, and writes a summary of the results in an rdb file, including the determined (x,y) center and required number of iterations (in beam-center), along with the diameter, spacing, number parameter combination, and specifics of the input ray stream (photon density and shell number). The only module that ph_survey calls is beam-center, so this is the only procedure which must have an accessible parameter file in order for ph_survey to run properly. Note that beam-center has many internal parameters which are not set through ph_survey, and which must be set by the user directly, in accordance with preference. These parameters include quickscan, rms_error, xtol, ytol, simultol, max_iter, project, z, ringfract, tma_defaults, focus, rho_f, radius, and delete_output. Not all of these parameters are essential for the running of ph_survey. For example, the rho_f parameter is only used if the user wants the beam-center procedures to be run with project equal to ``ring''.

As mentioned before, ph_survey is basically just a script which calls beam-center many times using many different parameter combinations. It is fairly easy for the user to modify these parameter sets (the pinhole diameter, spacing, and number) which are looped over by ph_survey, although this is not able to be done via the parameter file. The user must actually alter the three lines in the source code which provide these lists. After ph_survey calls beam-center each time, it reads in the determined center from the actual summary file generated by beam-center, and then updates the rdb-formatted results file. The database is updated in the following manner: First, the database is checked to see if there is already an entry with the same input parameters (photon density, shell, and pinhole diameter, spacing, and number), and if so, deletes that old entry. Then the results from the most recent beam-center run are written to the results file.

One final note should be made about the ph_survey procedure. Although the pinholes are initially centered around the user-specified initial x and y coordinates (in those beam-center runs which use the first and largest diameter), a quite different center is used for the other beam-center runs. The situation is as follows: Ideally, we want to adjust the presumed center so that it represents the most accurate guess so far. This adjustment is performed each time the pinhole diameter is changed in the outer loop. Since the direction of pinhole size is from larger to smaller size, this means that typically the presumed center becomes more and more accurate as the survey continues. From empirical observation, it appears that the most accurate centers are determined from the parameter combination of 7 pinholes and 1/2 spacing. Hence the determined center from this run is saved and used as the center for all of those subsequent runs which use the next smallest pinhole diameter.

AUTHOR

C.C. Carpenter