CACTus readme v.1.2.1 Written: Gareth Lawrence (ROB) Apr 29 2005 Modified: Gareth Lawrence (ROB) May 05 2006 David Berghmans (ROB) May 15 2006 Eva Robbrecht (ROB) May 15 2006 This file explains how to run the Computer Aided Cme Tracking (CACTus) software developed originally by David Berghmans (Royal Observatory of Belgium)(*1) between 2001-2004 (work partly undertaken at ESA-ESTEC via ESA funding). The routines have been substantially rewritten and improved by Eva Robbrecht (ROB) since 2003. The conversion to Solarsoft(*2) was done by Gareth Lawrence (ROB) in 2005, with modifications thereafter. (*1) http://sidc.oma.be/cactus/ (*2) http://www.lmsal.com/solarsoft/ A full description of CACTus and its performance can be found in: Robbrecht, E. & Berghmans, D., 2004, Astron. Astroph., 425, 1097 which the user is encouraged to use as a citation reference. Earlier versions of the CACTus software are described in e.g.: Berghmans, D., Foing, B.H., Fleck, B, 2002, Proc. of SOHO 11, ESA SP-508, p437 In its present form CACTus runs on SOHO(*3)-LASCO(*4) C2 and C3 white-light broadband coronagraph images. The user is required to have a fully operational SolarSoft installation available, as well as an archive of LASCO images located in the 'usual' place (see SolarSoft setup notes for details). Reading from the LASCO archive is done by means of a dedicated routine and alternatives for other coronagraph datasets are easily written. The archive-reading routine is easily adapted to read from a specified directory should an archive not be available to the user. (*3) http://sohowww.nascom.nasa.gov/ (*4) http://lasco-www.nrl.navy.mil/lasco.html Once the string 'cactus' has been added to $SSW_INSTR, and the local SSW installation upgraded to download the routines, there should be a file at the following location: $SSW/packages/cactus/setup/setup.cactus_env : containing the following definitions setenv CACTUSDIR $SSW_CACTUS, $SSW/packages/cactus/ setenv CACTUSBIN $CACTUSDIR/bin/ setenv CACTUSVAR $CACTUSDIR/var/ setenv CACTUSREAD $LZ_IMG/level_05/ setenv CACTUSOUT $HOME/cactusout/, $HOME setenv CACTUSWRITE $CACTUSOUT, $HOME setenv CACTUSLOG $CACTUSOUT, $CACTUSOUT/log/, $HOME/log/ and the user may create a ~/cactusout/ directory in their home directory, to which the output will be directed. Of course, the user is free to set these environmental variables and directories however they choose to do so. Within the $SSW_CACTUS/idl/ directory are 20 .pro files, and in $SSW_CACTUS/bin/ two shared objects (.so files) containing the pre-compiled C files that are called externally in two of the IDL routines, and two C files, included for reference. The main calling routine is cactus_cmes.pro. Additionally, $SSW_CACTUS/var/ contains some parameters that are restored during runtime. The calling syntax is as follows: IDL> cactus_cmes [, startdate, enddate] [,LOGFILE = J] [/BOX_PLOTS] where J =0 is default (screen) J = 1 writes to $CACTUSOUT/cactus_log_DD-MMM-YYYY_HHMM.txt J = 2 writes one log file per routine to $CACTUSOUT The user is prompted for start and end dates by a widget application. CACTus can be run in batch mode allowing the user to specify dates in the calling sequence and skip the widget. These dates _must_ be in YYMMDD format or the software will crash. Also, either no dates or two dates must be specified, any other number will crash the software. Currently, the checking/correction procedure for date input is not rigorous, this may be improved in future versions. Note also that the logging procedure is to always append the existing logfile (which is created if it does not yet exist). CACTus never deletes log files; it is the user's responsibility to delete them as and when they choose to do so. Also, if LOGFILE=1 is set then the date and particularly time appended to the logfile name are those at the end of runtime, and not the start. Note that if LOGFILE ne 0 then not all information is sent to the log files; some details, primarily parameter returned by READFITS will still be sent to the screen. For this reason if CACTus is run in batch mode it is necessary to specify a target for standard output, eg $HOME/cactus_standard_output.txt, or /dev/null CACTus output nominally consists of a text file cmecat.txt and a PNG file detectionmap.png. These contain, respectively, the parameters of all CMEs detected including start time, position angle, angular span and a linear estimation of the velocity (along with associated errors), and a graphical representation of all CMEs on a [angle,time] plot. Time runs vertically upward and the left and right edges correspond to the position of the LASCO pylon (when SOHO is not rotated). Additionally, a directory is created per detected CME and an intensity-time plot written, with graphical information about the detection of each event. As well as this, the user can use the /BOX_PLOTS keyword which will create a velocity box plot (*5,*6) for each CME in its directory. (*5) Appendix A in Robbrecht, E. & Berghmans, D., 2004, A&A 425, 1097 (*6) http://en.wikipedia.org/wiki/Box-and-whisker_diagram NOTE A: Memory requirements CACTus is extremely memory intensive as a result of multiple transforms and iterations, and the typically large datasets that will be passed to it. A computer with 2 GB of RAM available to IDL can process up to one month of LASCO data. 1 GB is sufficient for 2 weeks of images. Most users will not want to analyse such a large quantity in one go since it is time intensive to do so, and a catalogue of CACTus results is already available at: http://sidc.oma.be/cactus/scan/scan.htm NOTE B: Data requirements CACTus expects to have access to both, LASCO C2 and LASCO C3 images. Performance on only one of these datasets has not been rigorously tested. However, if the outer edge of the field-of view is restricted to 15 Rsun (as is the case for STEREO/SECCHI Cor-2), the software runs satisfactorily. As a very basic rule of thumb, in order to be detected any given CME needs to be visible in at least 8 different images. Also, when the cadence is much lower than normal, fewer CMEs are detected. Before use, CACTus tests the image-header for quality. If it is found to be too low, the image is rejected. However, since not all information is included in the image-header, it remains possible that 'bad' images enter the detection module and cause a 'false detection'. NOTE C: Performance Since the final stage of the calculation is to look for patterns in a transformed datacube, spurious detections and/or inaccurate parametrisations are to be expected at the beginning and end of the data set. Please add a day before and after your period of interest to ensure that the results for that period are reliable. Furthermore, CACTus should be given at least three days' worth of data to analyse, again to ensure reliable results. Also, during periods of exceptionally low coronal activity CACTus can make spurious detections as a result of noise patterns and exposure time fluctuations, especially close to the LASCO C3 pylon. This will be improved in future releases. NOTE D: Data sources As stated above, CACTus presently only works with SOHO-LASCO C2 and C3 images. In future its capability will be expanded to work with data, such as STEREO/SECCHI Cor-1 and Cor-2 from late 2006. While the software team will modify the routines to provide the ability to select the data source, it will remain the user's responsibility to ensure that these data are located in the 'normal' location so that CACTus can read them. The default is presently to look for the chosen dates within the LASCO Level_05 data archive; to change this to eg the LASCO Quicklook archive or your private data then please change the definition of $CACTUSREAD in $SSW/packages/cactus/setup/setup.cactus_env accordingly. Greater flexibility will be incorporated in future releases. NOTE E: Upgrades Please bear in mind that CACTus is a work in progress so modifications and enhancements to the routines are to be expected. Please be sure to upgrade your SSW regularly in order to remain up to date.