HSTPSF

Name

hstpsf

Purpose (one Line)

Find or create a HST PSF file using Tiny Tim.

Description

See Tiny Tim User's Manual, Version 6.1 Alpha, for details.

Calling Sequence

hstpsf, x, y, date, filter, bmvnum, psf, xmax, ymax

Inputs

x, y : Chip position.
date : Date of observation (YYMMDD format) (not used by ACS/HRC).
filter : Filter name. May be f439w or f555w. Case-insensitive.
bmvnum : TinyTim Color Index (B-V) number (integer) OR a directory name
(string) in which a user-specified spectrum file will be found.
If this argument is a B-V number, it may be:
BMVNUM TYPE B-V
1 O5 -0.34
2 O8F -0.32
3 O6 -0.31
4 B1V -0.27
5 B3V -0.21
6 B6V -0.12
7 A0V -0.04
8 A5V 0.12
9 F6V 0.37
10 F8V 0.48
11 G2V 0.56
12 G5V 0.66
13 G8V 0.75
14 K4V 0.92
15 K7V 1.28
16 M1.5V 1.45
17 M3V 1.44
If this argument is a directory name, it must be just a name,
not a path. The directory must exist just below the instrument
directory. The spectrum file in the directory must have the
directory name as its root and must end in '.dat' . For example,
if the bmvnum argument is 'example' the example directory
(within the camera directory) must cantain a spectrum file named
'example.dat'. The contents of the spectrum file must be in
TinyTim ASCII format (See Appendix C in the TinyTim manual).

Optional Input Parameters

Keyword Input Parameters

CAMERA = TinyTim Camera Number. Required. May be:
2 for Planetary Camera (WFPC1) (f/30.0) (see restrictions),
6 for Planetary Camera (WFPC2) or
16 for ACS - High Resolution Channel (f/72)
19 for NICMOS Camera 1 + cryocooler
20 for NICMOS Camera 2 + cryocooler
22 for WFC3 UVIS channel
23 for WFC3 IR channel
CHIP = May be 5, 6, 7, or 8 (default: 6) for WFPC1.
May be 1 or 2 (default: 1) for WFC3/UVISx
Not used if camera is 16 or 6. (ACS/HRC, WFPC2).
Ignored for WFC3/IR
FLUSH = If set, flushes the local cache before beginning PSF search.
GRID = Grid spacing for nearest PSF location. Default=50 pixels.
HSTPATH = The starting directory path for the location of the PSF'S.
Current default is /net/frakir/raid/buie/hstpsf. An empty
string denotes the current directory. Used, primarily, for
maintenance.
MISSING = If set, HSTPSF will not compute or return any psf's but reports
if the disk cache is not populated for the grid point. This
is a convenience when gathering psf trees from multiple sources.
NOCHECKPAR= If set, the .par file is not checked when returning
a PSF from the disk cache (used only for camera=2).
PSFSIZE = Size of requested PSF, in arcseconds (default: 5).
SAMPFACT = Sample factor (default: 2). Not used with ACS/HRC or WFC3.
VERBOSE = If set, displays informational messages, as well as
the output of tiny1. Leaving VERBOSE unset does not suppress
warning messages that might arise during the precheck of the
.par file (see NOCHECKPAR).
Z4 = The value to use for the fourth Zernike coefficient. Default
is 0.0 (scalar).

Keyword Output Parameters

PSFROOTNAME - returns the name of the psfroot (with path, no suffix)
BPSF - blurred and distorted PSF, WFC3 only.

Outputs

psf : The generated PSF array.
xmax : Interpolated maximum x-location.
ymax : Interpolated maximum y-location.

Common Blocks

hstpsf_com : Local. Holds a chosen number of PSF's in memory cache
(see variable ncache).

Side Effects

Restrictions

Support for the WFPC, WFPC2, and ACS/HRC using TinyTim Version 6.2.
Support for the F439W and F555W filters.
Requires IDL 5.6 or later.
Does not segregate PSF's by sampling factor (ie, sampling factor is
not a component of the directory path). If you use a new SAMPFACT you
need to manually remove all the files from the disk cache that pertain,
or place the PSF's in another path via HSTPATH.
The same comment applies to PSFSIZE.
On WFPC2, an inconsistency in SAMPFACT or PSFSIZE should be caught
by the .par check, assuming NOCHECKPAR is not specified.
If HSTPSF is killed while running TinyTim, a .par file is left behind
at that point in the disk cache without a PSF file. A subsequent access
to that grid point causes HSTPSF to throw an error, which is cleared
by removing the .par file manually and running HSTPSF again.

Procedure

A nearest grid position is computed from the input chip position and the
z4 value using the specified, or default, grid spacing.
If a PSF has been previously computed at that grid position (matching the
other input parameters), that file is loaded into the caller's PSF array.
On WFPC2, unless the option is suppressed with NOCHECKPAR, the .par
file used by TinyTim is checked in this case to see if it is consistent
with the parameters of the psf requested. If not, a warning message is
printed, with all outputs returned normally.
Otherwise, a new PSF is created, placed into the appropriate
sub-directory, and loaded into the caller's PSF array.

Modification History

Written by Doug Loucks, Lowell Observatory, August, September, 1993.
12/1/93, DWL, Modified to work with Tiny Tim Version 2.4.
12/9/93, DWL, Modified to hold one copy of a PSF in common. If the
requested PSF is the same as that in common, a disk-access is avoided and
the memory copy is returned.
12/16/93, DWL, Added VERBOSE keyword. If set, displays informational
messages.
1/12/94, DWL, Added cache for two psf's.
1/21/94, DWL, Added cache for n psf's. See local variable ncache.
1/21/94, DWL, Added code to compuite and store each psf's interpolated
maximum. Also, added FLUSH keyword.
2003/01/15, DWL, Added keywords CAMERA, CHIP, PSFSIZE, and
SAMPFACT. These allow continued, but minimal support for calls from
P6MODEL. The new TinyTim (Version 6.1 Alpha) does not generate the same
output as the old TinyTim, for the old planetary camera. The
modifications allow for return of a P6 PSF array, if called from P6MODEL
and the old PSF file is available in disk cache; new P6 PSF's are
not generated for calls from P6MODEL.
Updated to use TinyTim Version 6.1 Alpha.
Added support for the new ACS/HRC HST camera. The new
HRC code will be used if called from the new routine HRCMODEL (CAMERA=16).
Modified the local common block to use a single anonymous
structure whose tags manage the PSF memory cache.
2003/07/23, MWB, cosmetic tweaks, changed message to print and tucked
a few more things behind the verbose keyword control.
2004/02/11, DWL, added keyword Z4, which specifies a value for the
fourth Zernike term.
2004/02/17, DWL, changed file handling to put temporary files in the
the main psf directory rather than in the current directory.
2004/02/18, MWB, changed handling of Z4 and removed all chmod calls.
2006/11/20, Peter L. Collins, Lowell Observatory. Changed default
HSTPATH to frakir location (post-gryll), bug in
computing nearest grid point when x or y integer., and
changed directory testing to skip current directory case.
2007/06/12, PLC, added support for WFPC2 and recomputation of psfs for
WFPC1 (now with TinyTim6.2). Probably enhanced the
interaction with tiny1.
2007/06/15,PLC, the subdirectory below WFPC2 is now PC instead of PC6,
which continues to be used for WFPC.
2007/06/24,PLC, add .par file check for WFPC2, along with keywords
NOCHECKPAR and MISSING.
2009/09/01, MWB, modified to use TinyTim 7.0 and add WFC3-UVISx support
and BPSF keyword output. Old modes should work but they
are untested.
2010/07/23, MWB, added camera 19, NIC1+cooler.
2010/08/25, MWB, added camera 20, NIC2+cooler.
2011/03/11, MWB, modified to support TinyTim 7.1. The new Z4 adjustment
in v7.1 is not used by this program. Z4 is directly
modified by this routine as was always done.
2011/03/22, MWB, added support for WFC3/IR