Prof Richard Massey
Dark Matter cartographer

This page describes an IDL/java implementation of an algorithm to correct images from the Hubble Space Telescope's ACS/WFC camera (Massey et al. 2010a, 2010b, Rhodes et al. 2010). It works fine, but takes about 25 minutes per ACS exposure on one CPU. As described in Massey et al. (2014), a faster implementation in C is now available, thanks to Oliver Cordes and Ole Marggraf.

Charge transfer inefficiency due to radiation damage

All electronics gradually degrade in space, as they are bombarded with high energy radiation. This manifests itself in CCD detectors used in cameras via the generation of "charge trap" defects within the silicon lattice. During detector readout, electrons (the photoelectrons created when light falls on the detector) are temporarily captured and held in place. When these electrons are subsequently released, the rest of the image has moved closer to the readout register, so they form trails behind objects. The net effect is known as "Charge Transfer Inefficiency" (CTI). Fortunately, by modelling the process of readout and trapping, it is possible to reverse the effect, and move the electrons back to where they belong. Because the readout is the final process preformed in space, this correction should be the first analysis step performed on the ground.

Install the correction code

1. Download the core java CTI correction code, uncompress it (tar xvzf CTI_correct_java_v1.0.tar.gz), and place it somewhere convenient - let's say ~/bin/snapSim-current-20090328.230001/.
   
2. Download the front-end IDL CTI correction code, uncompress it, and make sure IDL can find it (print,!path in IDL, and check with doc_library,"acs_clock_charge").
   • acs_find_data.pro locates *_raw.fits files.
   • acs_split.pro converts *_raw.fits images to/from units of electrons by mimicking half of CALACS. The four amplifiers are written to separate files.
   • acs_clock_charge.pro runs images through the software CCD readout (calling the Java code), or undoes its effects via an iterative process.
   • acs_correct_cte.pro is a wrapper that can process many images, manging jobs across a computer cluster if necessary.
3. The code is trivially parallelisable (to e.g. correct images from a large survey). If you plan to run it on a large cluster farm, make sure both paths can be accessed from all nodes. If you have root access to the master node, it may help^* to run
   
   • sudo sysctl -w kern.maxproc=400 ; sudo sysctl -w kern.maxprocperuid=400
4. Optionally, to save entering the same details many times in the future, you can hardwire
   • The location of the java code as the java_dir variable inside the IDL routine acs_clock_charge.pro.
   • A default data directory as data_dir in acs_find_data.pro.
   • Names of cluster nodes as cluster_nodes in acs_correct_cte.pro.
   • Number of processors at each node as cluster_processors in acs_correct_cte.pro.
   • Location of scratch space accessible from each node (this can be a single string or one for each node) as cluster_tempdirs in acs_correct_cte.pro.

Additional instructions are also available in the headers of the IDL *.pro files.

Prepare the data

1. Place all the *_raw.fits files you want to correct (maybe first try two or three files) into one directory - let's say /data/acs/.
2. Here is some sample data that I know works fine.
   • Output *_cte.fits files will also be written here, so make sure there's plenty of free disk space.
   • It would also be (easily) possible to start from *_flt.fits images, which are the output of CALACS, by tinkering with acs_split.pro. However, that wrapper doesn't yet exist.
3. Place the relevant superbias *_bia.fits files into the same directory.

Process the data

• To perform the correction using only one processor, start IDL and run
  acs_correct_cte,DATA_DIR="/data/acs/",JAVA_DIR="~/bin/snapSim-current-20090328.230001/"
  • If the run is interrupted for any reason, just enter the command again and it will continue from where it left off. To start over from scratch, add the /DELETE_OLD flag.
  • IDL commands can be run directly from a shell prompt via idl -e acs_correct_cte,DATA_DIR=\"/data/acs/\"…

• To farm it out onto machines called "cow", "pig", etc, each with multiple processors, run
  acs_correct_cte,/CLUSTER_FARM,DATA_DIR="/data/acs/",CLUSTER_NODES=["cow","pig",…,"sheep"],CLUSTER_PROCESSORS=[2,2,…,4],CLUSTER_TEMPDIRS="/scr/"
  • The node names can include full username or IP address information, such as username@node.university.edu.
  • Simultaneous jobs on the master node can be run by just supplying its name and the desired number of processes.

• To run the java code directly from a shell prompt (e.g. if IDL is not available), run
  ~/bin/snapSim-current-20090328.230001/eagRunner.sh ~/bin/snapSim-current-20090328.230001/ gov.fnal.eag.sim.pixel.ClockCharge input_file output_file
  plus options
  • --help displays all the options.
  • -Xmx2048m lets java use 2Gb of RAM. Adjust the value to be a little bit less than the memory on your machine. Once java starts running out of memory, it bogs everything down.
  • --quantizeCharge false True forces electrons to be released (or not released) from charge traps discretely; false lets a little out each clock cycle.
  • --quantizeTraps true True uses a (fast) model with individual charge traps; false uses a (less noisy) model with a smooth continuum of traps in each pixel.
  • --nLevels 3 Sets the fineness of the continuum, or multiplies the density of discrete traps, but divides the number of electrons in each. High values reduce noise but are slow.
  • --serialTrapsPerPixel 0 Sets the charge trap density in the readout register. For ACS/WFC, this is negligible.
  • --parallelTrapsPerPixel "0.408,0.136" Density of (up to four) species of charge traps, in units of traps per pixel.
  • --parallelTrapLifetime "10.4,0.88" Characteristic release time of charge traps, in units of CCD clock cycles.
  • --parallelFullWell 84700 Number of electrons that can occupy each pixel before it overflows, w.
  • --parallelNotchDepth 96.5 Number of electrons that can occupy the supplementary buried channel in each pixel, d.
  • --parallelPower 0.576 Power law index governing the rate at which the pixel potential well fills up, α.
  • --trapLocationRandomSeed x Random seed governing where model traps are placed within CCD.
  • --trapDecayRandomSeed x Random seed governing when traps release an electron (only used if quantizeCharge is true).
  • --verbosity 1 Displays progress to stdout during operation.
  • --showStopwatch 1 Displays timers to stdout at end.

Assess the level of improvement

1. Blink _raw and _cte versions of the same image in DS9.
   • I think you'll be surprised how obvious the trailing was.
2. Run acs_measure_cte,pixelsR,trailsR,DATA_DIR="/data/acs/",SUFFIX="_raw",/FIND,/PLOTS.
   • Routines in the measurement/ subdirectory were used to measure the CTI trails, and can also be used to measure their absence!
3. Run acs_measure_cte,pixelsC,trailsC,DATA_DIR="/data/acs/",SUFFIX="_cte",/FIND,/PLOTS.
   • You might need to .reset in between, to free up memory.

^* The correction software manages multiple slave machines from one master node, keeping (several) processes active on the master node while each image is being corrected. Any unix-like machine has a maximum number of processes that it can run. By default, the number allocated to each user is set rather low, because it is expected that multiple users may log in. The CTE code will detect this limit, and stay under it by pausing occasionally if the limit is neared. However, if you know that you will be the only user, you can safely increase your own process quota.

It is also possible to completely detach child processes to the slave machines (or a queueing system) so that the master node could forget about them. However, this requires the slave machines to be able to log back into the master node to return the results. The current method worked best for my cluster, because it is behind a firewall, but I have alternative versions if they would be better for yours.