~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CIAO: Chandra Interactive Analysis of Observations Version 2.0 README December 4, 2000 ==================================================================== I) Overview ==================================================================== This file contains release information and instructions for Release 2.0 of the CIAO (Chandra Interactive Analysis of Observations), the Chandra X-Ray Center Data System (CXCDS) data analysis system. The binary distribution of this CIAO release includes the GUI analysis applications PRISM, FILTER WINDOW and FIRSTLOOK, the SHERPA modeling and fitting application, the CHIPS plotting and imaging application, source detection tools, several instrument specific tools, numerous data manipulation tools (e.g., dmcopy, dmlist, dmextract). More information is available from http://asc.harvard.edu/ciao/ The binary distribution further requires installation of our auxiliary distribution, which contains a number of support files, parameter files and online documentation. In addition to the tools and applications, a number of software libraries (eg, the Data Model, ChIPs) are present within src/lib and src/libdev of the source code distribution, and can be used to build new tools and applications. System Requirements ------------------- Chandra data files are large, which implies that certain processing and analysis operations will work more efficiently when they have access to large amounts of RAM. We recommend a minimum of 96Mb main memory, and disk space or order 100Mb, as given in (II). Platforms --------- As of this release the CIAO binary distributions have been ported to: Solaris 2.6 Solaris 2.7 Redhat Linux 6.x Slackware Linux 7.x Please be advised that you may experience some problems when trying to use the package on older (and possibly even on newer) versions of these platforms. Each distribution requires the presence of the following (or later) versioned software: X11R6 Motif1.2 (OR the LessTif clone, version 0.88.9, or later. Available at www.lesstif.org) Netscape (OR the text-based lynx browser, version 2.5) gzip (GNU zip package) Recent versions of Solaris (ie, at least 2.6 and higher) and Linux will by default contain the necessary X libraries and executables (i.e. X11R6, Motif1.2), but users may need to ensure that their PATH and LD_LIBRARY_PATH are properly configured to find the required files (eg, beneath /usr/openwin on Solaris). Linux users who do not have CDE or KDE installed may find it necessary to install LessTif from the site given above. Two databases are optionally needed: CALDB2.0 if you want to analyze Chandra data; ATOMDB if you want to use the GUIDE spectroscopy package. It is suggested to install the CALDB and ATOMDB databases (if needed) before starting the CIAO installation. They can both be downloaded from the CIAO download page at http://asc.harvard.edu/ciao/download.html Usage/Licensing --------------- All non-OTS source code will be freely available in support of any CIAO release. The software is subject to Smithsonian Institution Copyright, a statement of which can be found in the headers of the source files, as well as at the top of the $ASCDS_INSTALL tree. In a nutshell, you may do whatever you please with CIAO, provided you neither harm others nor remove the copyright statement. Finally, since parts of CIAO utilize GNU software it is at least in part further governed by the GNU General Public License and/or the GNU Library General Public License, both of which are bundled with the software and can be found at the top of the distribution tree. If you have any problems, questions, or suggestions, please contact the CXC Help Desk, by clicking "Help Desk" on the CXC WWW page: asc.harvard.edu ==================================================================== II) Installation ==================================================================== Software -------- The CIAO software is distributed in 4 files per platform, two of which are platform independent, and two of which are not. The platform dependent files are: - The CIAO binary distribution - Third-party "off-the-shelf" (OTS) software utilized by CIAO [optional] The platform independent files are: - Auxiliary distribution (support and parameter files, online documentation) - Source code [optional] Downloading/unpacking the source and OTS is optional, as the binary and auxiliary distributions contain everything needed to install, configure, and utilize the software. You will only need the OTS and source distributions should you wish to rebuild the software on your local machine. Note: You MUST obtain the auxiliary distribution (cxc_aux.tar.gz) if you are downloading EITHER the binary OR source distributions, as this distribution contains essential support, parameter and help files necessary for the operation of the software. The approximate sizes of these distributions for each supported platform are given below. Platform-independent files: aux distribution: 134 Mb src distribution: 104 Mb Platform-specific files: Linux binary distribution: 69 Mb ots distribution: 64 Mb Solaris 2.6, 2.7 binary distribution: 103 Mb ots distribution: 85 Mb Binary Distribution Install Instructions ---------------------------------------- All commands that are to be typed by the user are proceeded with the '>' character. Do not type this character when typing the command. Each tar/zip file is labeled with __ to denote the target platform. As can be guessed, the current mnemonics are 'sun', and 'linux' (e.g., the Solaris binary distributions will be named cxc_bin_sun.tar.gz). Note that if you are using FTP to download the files to your site you must issue the ftp 'binary' command prior to starting the transfer. 0) Expand/uncompress the distributions. The compressed distributions have have a .gz extension, and can be expanded as follows: If you are using our GNU-zipped distributions, and have access to a GNU-compatible version of 'tar' you can combine the commands issued in steps 0 and 2 into 1 command, ie unzip and untar the file using only 1 command. Simply type 'tar --help' or 'gtar --help' to see if the 'z' option is supported in your version of tar, and if so change the 'xvf' given below to 'xvzf'. Also note that the verbose flag (v) is optional. > gunzip cxc_.tar.gz or: > gzip -d cxc_.tar.gz When this is finished only the .tar file will be in the given directory, as the .gz file is automatically deleted. 1) Go to the directory in which you want the root of your CIAO installation to be located. As indicated above, this device should have on the order of 200-270 Mb free space to install the binary and aux distributions for a given platform, and roughly 400 Mb to install everything for that platform. Issue the commands: > mkdir ciao_2.0 ( This name is arbitrary ) > cd ciao_2.0 2) Issue the command: > tar xvf /dev/rmt/0 (or whatever your device name is) (if loading from a tape/CD) OR > tar xvf cxc_bin_.tar (if loading from a downloaded/unzipped tar file) 3) Untar the auxiliary tar/zip file > tar xvf cxc_aux.tar (if loading from a downloaded/unzipped tar file) 4) Run the GNU configuration script: > ./configure 5) Create links to the Calibration and atomic data. > ln -s CALDB > ln -s ATOMDB These links must exist in the $ASCDS_INSTALL directory for the configuration to work correctly. NOTE: Guide will not work if ATOMDB does not exist. 6) It is strongly suggested that you create an alias in your $HOME/.cshrc (c and tc shell users) $HOME/.login (sh and bash shell users) (csh and tcsh users) > alias ciao "source /bin/ciao.csh -d " so if the installation root is in /soft/ciao you would have: alias ciao "source /soft/ciao/bin/ciao.csh -d /soft/ciao" (borne and bash users) > alias ciao ". /bin/ciao.sh -d " so if the installation root is in /soft/ciao you would have: alias ciao ". /soft/ciao/bin/ciao.csh -d /soft/ciao" From that point on when you log in you can just type > ciao and ciao will be setup and ready to use. Note: If you wish to edit your $HOME/.CXCdefaults file and want to make sure that it is not overwritten you may and the -K (Keep files) or the -k switch (Keep newer files) to your alias. alias ciao "source /soft/ciao/bin/ciao.csh -d /soft/ciao -K" If you had an older versions of ciao installed you might want to delete you $HOME/.CXCdefaults file first so it will be replaced with the newer one before you edit. The newer .CXCdefaults file utilizes several fixes to correct some color and display problems. Parameter File Interfaces and CIAO ---------------------------------- The use of the parameter file interface within the CIAO command-line tools presents some non-trivial issues for users. There are several different parameter interface implementations in current use, three of the most prevalent being from IRAF, FTOOLS, and SAO. While for the most part each implementation is "IRAF-compatible," each differ somewhat in the order in which directories are searched for input, on where parameter updates are written, and in the names of the environment variables used to determine such. A brief synopsis of three of the most important variables is: UPARM - defined/used by IRAF parameter interface PFILES - introduced by FTOOLS parameter interface, which also supports UPARM PDIRS - introduced by SAO parameter interface, which also supports PFILES and UPARM It should be clear that standardization amongst the different organizations is needed here, and it is likely that users who concurrently install and use one or more of these software systems will experience runtime problems due to unintended interactions of each parameter interface implementation. Thus the config_cxcds script will ONLY explicitly set in the $HOME/.cxcds.*sh script it generates EACH of these variables that it DOES NOT detect already defined in your environment at configuration time. Conversely, each variable that config_cxcds DOES detect in your environment WILL NOT be added to $HOME/.cxc.*sh, the assumption being you will want to keep those settings rather than have our software override them. If you have installed previous versions of CIAO (such as ciao 1.x) you should DELETE PREVIOUS CIAO PARAMETER FILES, as they sometimes change in content, and a runtime mismatch will occur if the latest software finds files left over from a previous release. ==================================================================== III) Rebuilding CIAO from the source code ==================================================================== Additional Required Software ---------------------------- Rebuilding CIAO from source code requires additional software over and above that mentioned in section (I), namely: Solaris: SUN cc, CC (the Sun C++ compiler), and F77 compilers and libraries (version 4.2 or later) Linux: gcc/g++ (version egcs 2.91.x with fortran) All platforms: Tcl/Tk (version 8.0 or later) The GNU flex/bison parser generation tools To build the software you do not need the binary distribution, however you will need the other three distributions (aux+data, ots, and source). If you have installed the binary distribution, you should remove the smaller ots subtree that was included within it, though if you forget to do this first don't worry -- it's not fatal, but tar may complain or give minor permission warnings when overlaying the new, larger OTS onto the previous subtree. You must download/unpack the source, auxilliary, and OTS CXC distributions (cxc_src.tar, cxc_aux.tar, and cxc_ots_.tar respectively) into the same directory, following the same general instructions as given in (II). Finally, note that due to licensing agreements we are unable to distribute the SM source code. Instead, the sm libraries will need to be downloaded separately when you are rebuilding from the source. Compiling instructions ---------------------- 1) Go to you install directory. > cd ciao_2.0 2) Untar the distributions > tar xf cxc_src.tar > tar xf cxc_aux.tar > tar xf cxc_ots_.tar 3) Run the GNU configure script as follows (except linux): > ./configure --with-comp --with-fits --with-iraf --with-iraflibs If you are building on Redhat 6.0 we do not currently support qpoe files. This should be available in the next release. You need to issue the following command: > ./configure --with-comp --with-fits Note: This is valid on all platforms if you wish to compile without the iraf kernel. 3b) Other switches with configure. With this release of ciao our configure script has been upgraded to accept several option to assist your installation. The default described is the action the switch will take if =xxx is omitted. --with-opt=Ox - set optimization to level x. Default O3 --with-debug - compile with -g (debug) switch --with-top=/ - set the location of $ASCDS_INSTALL (instead of using your current working directory. This switch is useful for installing to a read-only files system where the installer is NOT in the directory the users will see.) --with-tcltk= - set the location to look for the Tcl/TK libraries and includes (lib and include directories). Default is /usr --with-tclver=x Set the version of TclTk to use. Default is 8.0 --with-lesstif= - set the location to look for Lesstif or Motif libraries and includes (lib and include) direcories. Default is /usr/X11R6/LessTif (This is not needed if the files are already in your search paths as the standard Solaris installations) --x-libraries= - Set the location of the X libraries. This is only needed if the automatic detection fails. --x-includes= - Set the location of the X include files. This is only needed if the automatic detection fails. 4) > cd src 5) > make -k install >& ciao_log & Note: The -k switch (to ignore errors) is needed to ignore problems building extraneous files. A future release will correct this oversight. Assuming a successful rebuild, the configuration steps (6) and (7) outlined in section (II) would then be followed to configure for the newly built tree (taking care to ensure that the newly built tree, rather than the previously installed binary distribution, is specified as the root of the CXCDS tree).