Richard MASSEY
Astronomy Fellow

CTI correction code

The core is written in java for speed, and a front-end user interface is provided in IDL. Additional instructions are also available in the full headers of the IDL code. Correction takes about 25 minutes per ACS exposure, but is trivially parallelisable to multiple processors.

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. If you plan to run the code 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 will 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.

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.