Manually Installing CIAO 4.7
CIAO 4.7 Science Threads
How to manually install version 4.7 of CIAO, the Chandra Interactive Analysis of Observations software package. This information is also available in the INSTALL_BINARY file that is packaged with CIAO.
- Installing CIAO ciao-4.7 using the ciao-install script: use the ciao-install tool to automate the installation of CIAO and the CALDB (the recommended method for installing the software)
Last Update: 25 Mar 2016 - updated to use CALDB 4.7.1
- System Requirements
- Installation Issues
- Downloading the Software
- Where should CIAO and CALDB be installed?
- Installing the CIAO Software
- Create the Help File Indexes
- Run the Smoke Tests
- Test the CALDB installation
- Clean Up the Tarfiles
CIAO is supported on a number of operating systems, which are listed on the Platform Support page. Certain system requirements are necessary to successfully install and run CIAO; review these system requirements before continuing with the installation.
Users should be aware of these installation items before installing CIAO 4.7. Additional problems which are seen less frequently are listed on the Installation & Smoke Tests bug page.
Remove the .fontconfig cache
When switching from a 32-bit to 64-bit build (or vice versa), incompatible .fontconfig files are cached on the user's system. To ensure that the graphical applications such as ChIPS run correctly, remove the .fontconfig cache:
unix% rm ~/.fontconfig/*
Remove old parameter files
With every new CIAO release, some parameter files have changed: new parameters may be added and occasionally old ones removed or renamed. Deleting or renaming the local parameter directory ensures that the correct parameter files will be accessed the first time a tool is run:
unix% rm ~/cxcds_param4/*
If upgrading from CIAO 4.4 or earlier, the current version of CIAO includes a newer version of IPython which is incompatible with previous versions. If you have made modifications to the files in ~/.ipython-ciao, you will need to manually migrate those changes into ~/.ipython-ciao4.5
For a standard CIAO installation, you need the following packages:
Contains the CIAO tools, libraries, parameter files, and help files. Also contains the pre-compiled off-the-shelf (OTS) programs required to run CIAO.
The relationship between <OS> and the supported operating systems is given in the following table:
<OS> Operating system Linux 32-bit Linux Linux64 64-bit Linux osx64 64-bit OS-X 10.6 or 10.7 (Snow Lepord or Lion) osxml64 64-bit OS-X 10.8, 10.9, 10.10 (Mountain Lion, Mavericks, or Yosemite)
Chandra Calibration Database (CALDB) v4.7.1
Some calibration products are packaged separately, due to the larger file size and specific analysis uses for them. Users may opt to include the ACIS background files and/or HRC background files when installing the CALDB. This thread includes only the ACIS background tarfile.
Scripts and Modules Package ciao-4.7-contrib-4.tar.gz
The files are retrieved with wget. In this example, the 64-bit Linux files (<OS>="Linux64") are retrieved; change the <OS> value to match your operating system. Save the tarfiles to a location - /soft/download/ in this example - that is accessible from where you wish to install CIAO.
If you get an error about being unable to download the CALDB files, please refer to the Downloading the CALDB: FTP passive mode note at the end of this thread.
unix% wget -nH -nd -r -P/soft/download/ ftp://cxc.harvard.edu/pub/ciao4.7/Linux64/ unix% wget -P/soft/download/ ftp://cxc.harvard.edu/pub/ciao4.7/all/ciao-4.7-contrib-4.tar.gz unix% wget -P/soft/download/ ftp://cda.harvard.edu/pub/arcftp/caldb/caldb_4.7.1_main.tar.gz unix% wget -P/soft/download/ ftp://cda.harvard.edu/pub/arcftp/caldb/acis_bkgrnd_4.6.9.tar.gz
The following files were used to install CIAO on a 64-bit Linux (CentOS) machine:
unix% ls -1 /soft/download/ acis_bkgrnd_4.6.9.tar.gz caldb_4.7.1_main.tar.gz ciao-4.7-patch-bin-Linux64.tar.gz ciao-4.7-bin-chips-Linux64.tar.gz ciao-4.7-bin-core-Linux64.tar.gz ciao-4.7-bin-graphics-Linux64.tar.gz ciao-4.7-bin-obsvis-Linux64.tar.gz ciao-4.7-bin-prism-Linux64.tar.gz ciao-4.7-bin-sherpa-Linux64.tar.gz ciao-4.7-bin-tools-Linux64.tar.gz ciao-4.7-contrib-4.tar.gz
The CIAO software package and the Chandra Calibration Database (CALDB) can be installed in any location and do not need to be installed with root or super-user privileges.
CIAO unpacks into a directory called ciao-<version>/, i.e. ciao-4.7 for this release. If the current version of CIAO were to be installed into /usr/local/, the full path to CIAO would be /usr/local/ciao-4.7/. This directory (/usr/local/ciao-4.7/) is referred to as the root directory of CIAO in the rest of this thread. It is also the value that the $ASCDS_INSTALL environment variable is set to once CIAO has been started.
In the rest of this thread we will assume CIAO is being installed into /soft/.
CALDB may be installed in two ways:
- within the CIAO installation, in the directory $ASCDS_INSTALL/CALDB
- in a separate directory, in which case $ASCDS_INSTALL/CALDB will be a soft link to the actual CALDB location.
This thread assumes that you have installed the CALDB before starting the CIAO installation, as CIAO has to be linked to the location of those files. Installation instructions are available on the CALDB website:
It is is strongly suggested that CIAO be installed as a non-privileged, regular user and not as the root user. If CIAO must be installed in a directory owned by root and you are following the manual process, then
- create the ciao-4.7/ directory in the desired location, as the root user;
- use the chown utility to change ownership of this directory to the installer's username;
- unpack CIAO into the newly-created directory as the installer, not as the root user.
The CIAO 4.7 tarfiles create a directory named ciao-4.7 for the software installation. It is not necessary to create the CIAO directory before starting the installation.
Move to the directory in which you would like the top level of the CIAO installation to be located. If you are installing the software for a local network, this directory must also be visible to all potential CIAO users.
This thread will use the /soft directory:
unix% cd /soft/
From the CIAO location just chosen, untar the CIAO 4.7 binary packages. (If you prefer more screen output, add the "v" option to the gtar command.)
unix% pwd /soft unix% gtar xzf /soft/download/ciao-4.7-bin-chips-Linux64.tar.gz unix% gtar xzf /soft/download/ciao-4.7-bin-core-Linux64.tar.gz unix% gtar xzf /soft/download/ciao-4.7-bin-graphics-Linux64.tar.gz unix% gtar xzf /soft/download/ciao-4.7-bin-obsvis-Linux64.tar.gz unix% gtar xzf /soft/download/ciao-4.7-bin-prism-Linux64.tar.gz unix% gtar xzf /soft/download/ciao-4.7-bin-sherpa-Linux64.tar.gz unix% gtar xzf /soft/download/ciao-4.7-bin-tools-Linux64.tar.gz
When all the files are unpacked, the CIAO directory will look like:
unix% ls -F ciao-4.7 COPYING* README VERSION_sherpa config.status* lib/ COPYING.LIB* README.obsvis VERSION_tools config.sub* ots/ INSTALL_BINARY VERSION bin/ configure* param/ INSTALL_SOURCE VERSION.prop_tk binexe/ configure.in* share/ LICENSE VERSION_chips ciao-type contrib/ test/ LICENSE.SAO VERSION_core config/ data/ Linux_build.html VERSION_graphics config.guess* doc/ Mac_build.html VERSION_obsvis config.h.in include/ Makefile VERSION_prism config.log install-sh*
The science scripts are written and maintained by local CIAO users at the CXC. More information on each of the scripts is available from the CIAO 4.7 Scripts Page. Check that page for announcements about new scripts and updates to existing ones.
The tarfile is designed to be unpacked from the same directory as the CIAO software.
unix% pwd /soft/
Unpack the script tarfile:
unix% tar xzvf /soft/download/ciao-4.7-contrib-4.tar.gz ./ciao-4.7/ ./ciao-4.7/contrib/ ./ciao-4.7/contrib/Changes.CIAO_scripts ./ciao-4.7/contrib/README_CIAO_scripts ./ciao-4.7/contrib/VERSION.CIAO_scripts ./ciao-4.7/contrib/bin/ ./ciao-4.7/contrib/bin/acis_bkgrnd_lookup ... ./ciao-4.7/contrib/param/merge_obs.par ./ciao-4.7/contrib/param/specextract.par
The tarfile contains a VERSION.CIAO_scripts file. Compare the timestamp in this file to the "Last Updated" date on the Scripts page to determine when you need to update your local scripts installation.
Run the CIAO configuration script:
unix% cd ciao-4.7/ unix% ./configure Running CXC configure, v4.3.16 checking build system type... x86_64-unknown-linux-gnu checking host system type... x86_64-unknown-linux-gnu checking target system type... x86_64-unknown-linux-gnu checking for more... /bin/more checking for main in -lpthread... no --with-imagerdir not specified, defaulting to /export/ciaot_install/ciao47b2/ciao-4.7/ots/bin configure: creating ./config.status config.status: creating bin/ciao_setup.csh config.status: creating bin/ciao_setup.sh config.status: creating bin/ciao.sh config.status: creating bin/ciao.csh config.status: creating bin/ciao.ksh config.status: creating bin/ciao.bash config.status: creating bin/setup_obsvis.sh config.status: creating bin/setup_obsvis.csh config.status: creating bin/setup_chips.sh config.status: creating bin/setup_chips.csh config.status: creating bin/setup_sherpa.sh config.status: creating bin/setup_sherpa.csh config.status: creating bin/setup_tools.sh config.status: creating bin/setup_tools.csh config.status: creating bin/ciao-python-fix config.status: creating test/smoke/bin/setup.sh config.status: creating test/Makefile config.status: creating ots/etc/pango/pangorc config.status: creating ots/etc/pango/pango.modules config.status: creating ots/etc/gtk-2.0/gtk.immodules
Next, the ciao-python-fix script needs to be run. Despite it's name, it does more than just stuff related to python. On Linux platforms (both 32 and 64 bit), its runs a program that will set the location of various CIAO and off-the-shelf (OTS) libraries.
unix% bash bin/ciao-python-fix
Once this script is run, the CIAO installation cannot be moved or relocated to a different directory without repeating the configure and ciao-python-fix steps.
Create a link to the calibration data, changing the path to match your system installation:
unix% pwd /soft/ciao-4.7/ unix% ln -s /soft/CALDB CALDB
At this point, your directory should look like:
unix% ls -F CALDB@ Makefile VERSION_prism config.log install-sh* COPYING* README VERSION_sherpa config.status* lib/ COPYING.LIB* README.obsvis VERSION_tools config.sub* ots/ INSTALL_BINARY VERSION bin/ configure* param/ INSTALL_SOURCE VERSION.prop_tk binexe/ configure.in* share/ LICENSE VERSION_chips ciao-type contrib/ test/ LICENSE.SAO VERSION_core config/ data/ Linux_build.html VERSION_graphics config.guess* doc/ Mac_build.html VERSION_obsvis config.h.in include/
It is strongly suggested that you create a CIAO alias before continuing.
The alias syntax depends on the shell (tcsh, csh, bash); see this FAQ for help in determining which shell you are using.
csh/tcsh users should add the following
to their $HOME/.cshrc file.
alias ciao "source /soft/ciao-4.7/bin/ciao.csh"
bash users should add the following
to their $HOME/.bashrc file.
alias ciao="source /soft/ciao-4.7/bin/ciao.bash"
ksh users should add the following
to their $HOME/.login file.
alias ciao=". /soft/ciao-4.7/bin/ciao.ksh"
Once the alias is defined, you will be able to simply type
and CIAO will be setup and ready to use in that window.
In order for CIAO to be able to access the help files packaged with the software, it is necessary to create the ahelp database indexes. This step must be run by the user who owns the CIAO installation.
Start CIAO and run ahelp -r:
unix% ciao CIAO configuration is complete... CIAO 4.7 Thursday, December 4, 2014 bindir : /soft/ciao-4.7/bin CALDB : 4.6.9 unix% ahelp -r Processing file '/soft/ciao-4.7/doc/xml/ChipsId.xml'...OK Processing file '/soft/ciao-4.7/doc/xml/Attributes.xml'...OK Processing file '/soft/ciao-4.7/doc/xml/ChipsDictionary.xml'...OK .... rocessed Files : 1206 Succeeded Files : 1206 Failed Files : 0 Purged Duplicates: 0 Creating Key Indexes...DONE Subject DB Size: 1206 Creating Context Indexes...DONE Context DB Size: 1206 Creating Crossreference DB...DONE Crossreferences DB Size: 15908 Creating Seealso DB...DONE Seealso DB Size: 2223
A set of smoke tests are packaged with CIAO 4.7. The tests are designed to spot-check the installation for critical problems, not to run a complete regression test of the system. The output created by the new installation of CIAO is compared against a baseline set of files included in the package.
The smoke tests include tests of a number of the GUI applications in CIAO, windows will appear and disappear during these tests. This can make using your computer difficult, since these windows may take the mouse focus or overlap your working windows.
unix% cd $ASCDS_INSTALL/test unix% pwd /soft/ciao-4.7/test
The smoke test syntax depends on the shell (tcsh, csh, bash); see this FAQ for help in determining which shell you are using.
unix% make -k test |& tee ~/ciao_test.log
bash or ksh users:
unix% make -k test 2>&1 | tee ~/ciao_test.log
The screen output provides a count of how many tests have been run:
unix% make -k test |& tee ~/ciao_test.log Requested test suite includes 42 tests [1/42] Running test prism-smoke001 .. [2/42] Running test prism-smoke002 ... PASS [3/42] Running test ahelp-smoke001 ... PASS [4/42] Running test obsvis-smoke004 ... PASS [5/42] Running test chips-smoke001 ... PASS [6/42] Running test chips-smoke002 ... PASS ... [40/42] Running test tools-dmstat-smoke001 ... PASS [41/42] Running test tools-dmstat-smoke002 ... PASS [42/42] Running test tools-dmstat-smoke003 ... PASS All smoke tests PASSED.
Verifying test successes
A successful test is logged with a "... PASS", while an unsuccessful test reports:
[7/42] Running test <testname> ... FAIL Review /tmp/smoke.username/<testname>/diff.log for details
The smoke tests print a summary of successful and failed tests. If all tests were successful:
All smoke tests PASSED.
or if any failed:
1 out of 42 smoke tests FAILED. !! CIAO MAY HAVE FAILED TO INSTALL PROPERLY !! Please check http://cxc.harvard.edu/ciao/bugs/smoke.html for a list of known issues before contacting the Help Desk.
To run (or re-run) an individual smoke test you have to use the runtests Makefile target as shown here
unix% cd $ASCDS_INSTALL/test unix% make test-PACKAGE runtests
Where PACKAGE can be: ahelp, chips, crates, dm, ds9, obsvis, sherpa, tools, or ui. For example to just re-run the sherpa smoke tests, run the following command:
unix% cd $ASCDS_INSTALL/test unix% make test-sherpa runtests Requested test suite includes 1 test [1/1] Running test sherpa-smoke001 ... PASS All smoke tests PASSED.
The scripts package contains a tool - check_ciao_caldb - that performs a simple check of the Chandra CALDB installation. Running the tool should produce screen output like the following:
unix% check_ciao_caldb CALDB environment variable = /falafel.real/ciao_download_tests/ciao4.7/ciao-4.7/CALDB CALDB version = 4.6.9 release date = 2015-09-23T15:00:00 UTC CALDB query completed successfully.
For a more-thorough validation please follow the chkcif steps described on the download CALDB page.
Finally, you may delete the tarfiles from the original download directory:
unix% rm /soft/download/ciao*tar.gz
Some users are unable to download the CALDB via ciao-install or wget. This is because the user's FTP has defaulted to extended passive mode for the file transfer. Extended passive mode is not supported for the Archive web server, which hosts the CALDB tarfiles.
The workaround is for users to create a $HOME/.netrc file containing the following:
default macdef init epsv4 off
Note that there is a blank line after the "epsv4 off" entry. If the above fails, an additional line "passive off" may also be needed, so that the .netrc file appears as:
default macdef init epsv4 off passive off
Using the "--no-passive-ftp" flag with wget may also resolve the issue.
The CIAO installation is now complete. For help getting started with the software, read the Introductory science threads.
|12 Aug 2005||original version, new for CIAO 3.2.2|
|14 Nov 2005||updated for CIAO 3.3: added Linux8 package: renaming libgcc_s.so.1 and Mac OS X 10.2: Using ds9 v3.0.3 notes.|
|12 Jan 2006||updated to include CIAO 188.8.131.52 patch instructions|
|01 Dec 2006||updated for CIAO 3.4 and CALDB 3.3.0|
|29 Jan 2007||updated to include CIAO 3.4.1[.1] patch instructions|
|14 Dec 2007||updated for CIAO 4.0: tarfile creates a directory into which it unpacks; CIAO is shipped with gzip support enabled (no longer need to specify an option in the configure step); smoke tests are included in the AUX tarfile; CALDB 3.4.2 is used|
|21 Feb 2008||updated to include CIAO 4.0.1 patch instructions|
|26 Feb 2008||consistently use "/soft" as the installation directory|
|05 Mar 2008||renamed "Reindexing the Help Files" section to "Create the Help File Indices"|
|10 Mar 2008||system requirements moved to a separate page; "Create the Help File Indices" should be "Create the Help File Indexes"; CIAO does not need to be installed by the root user; "ahelp -r" must be run as user who owns installation; Mac users need to add xrdb to the PATH; FC7 expected smoke test failure|
|16 Apr 2008||updated to include CIAO 4.0.2 patch instructions; location of CIAO alias updated for bash users|
|08 Sep 2008||corrected ChIPS test number in Fedora Core 7 smoke test error (test 3 prints the error, not test 5)|
|15 Dec 2008||updated for CIAO 4.1: CALDB 4.1.0 is used, new supported platform (FC8 instead of FC7); added Known Smoke Test Issues section; removed the "setting xrdb path" section (needed for .CXCdefaults file, which the GUIs no longer use)|
|15 Jan 2009||updated to include CIAO 4.1.1 patch instructions; include full alias syntax in CIAO alias section; added bash syntax in Run the Smoke Tests section|
|29 Jan 2009||added "Installing CIAO as root user" information to Choose a CIAO installation directory section|
|20 Apr 2009||updated to include CIAO 4.1.2 patch instructions; CALDB version updated to 4.1.2; added the test the CALDB installation step; there is a new tool - ciao-install - that automates the installation of CIAO and CALDB|
|15 Dec 2009||updated for the CIAO 4.2 release: CALDB 4.2, new supported platforms, updates to filenames, "unzip the files" step replaced by using the "z" option to gtar. The scripts package unpacks from the same level as CIAO software.|
|30 Dec 2009||Added Snow Leopard workaround|
|22 Feb 2010||tarfiles are downloaded with wget instead of ciao-install|
|16 Mar 2010||Added Downloading the CALDB: FTP passive mode note|
|05 Apr 2010||updated for CALDB 4.2.1: version number of CALDB main and ACIS background tarfiles|
|19 Apr 2010||updated for CALDB 4.2.2: version number of CALDB main and ACIS background tarfiles|
|27 Sep 2010||updated for CALDB 4.3.1: version number of CALDB main|
|15 Dec 2010||updated for the CIAO 4.3 and CALDB 4.4.1 releases: minor changes to screen output|
|15 Dec 2011||reviewed for the CIAO 4.4 and CALDB 4.4.7 releases: minor changes to screen output|
|15 Jun 2012||reviewed for the CIAO 4.4.1 and CALDB 4.4.10 releases: minor changes to screen output|
|31 Jul 2012||updated to use CALDB 4.5.1|
|15 Oct 2012||updated to use CALDB 4.5.3|
|03 Dec 2012||Review for CIAO 4.5; updated INSTALL_SOURCE and _BINARY;|
|05 Mar 2013||updated to use CALDB 4.5.6|
|11 Jun 2013||updated to use CALDB 4.5.7 and contrib 3|
|30 Jul 2013||updated to use contrib 4|
|19 Aug 2013||updated to use CALDB 4.5.8|
|18 Oct 2013||updated to use contrib 5|
|25 Nov 2013||Reviewed for CIAO 4.6. Added new section for ciao-python-fix script.|
|26 Mar 2014||updated for CalDB 4.6.1, Sherpa patch, and contrib 4.6.3|
|09 Apr 2014||updated for CalDB 184.108.40.206, Sherpa patch, and contrib 4.6.4|
|16 Jun 2014||updated to use contrib 4.6.5|
|09 Jul 2014||updated to use CALDB 4.6.2|
|29 Aug 2014||updated to use CALDB 4.6.3|
|24 Sep 2014||updated to use contrib 4.6.6|
|04 Nov 2014||updated to use contrib 4.6.7|
|11 Dec 2014||Updated for CIAO 4.7. Added information about manually running an individual smoke test.|
|23 Feb 2015||updated to use CALDB 4.6.7|
|07 Apr 2015||updated to use contrib 4.7.2|
|01 Jul 2015||updated to use CALDB 4.6.8 and contrib 4.7.3|
|23 Sep 2015||updated to use CALDB 4.6.9 and contrib 4.7.4|
|25 Mar 2016||updated to use CALDB 4.7.1|