Manually Installing CIAO 4.12
CIAO 4.12 Science Threads
How to manually install version 4.12 of CIAO, the Chandra Interactive Analysis of Observations software package.
- Installing CIAO ciao-4.12 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: 10 Apr 2020 - updated to use CALDB 4.9.1 and contrib 4.12.2
- 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.12. Additional problems which are seen less frequently are listed on the Installation & Smoke Tests bug page.
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/*
For CIAO versions 4.5 to 4.7, inclusive, the IPyton configuration files used by Sherpa were stored in $HOME/.ipython-ciao4.5/. In CIAO 4.8 this location has changed back to $HOME/.ipython-ciao/, which was used in CIAO 4.0 to 4.4. Any modifications made to files in $HOME/.ipython-ciao45/ will need to be made to those in $HOME/.ipython-ciao/.
A warning message may be displayed the first time that Sherpa is run, indicating that old files (from CIAO 4.4 or earlier) were found in $HOME/.ipython-ciao/, and that they have been moved to avoid a possible conflict.
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 prism run correctly, remove the .fontconfig cache:
unix% rm ~/.fontconfig/*
With the release of CIAO 4.8, there are no longer any 32-bit builds of CIAO, so this issue will only arise if you maintain multiple versions of CIAO.
Downloading the Software
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 all 64-bit Linux w/Python 3.5 macOS 64-bit macOS 10.12 (Sierra through Catalina) w/Python 3.5
Chandra Calibration Database (CALDB) v4.9.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.12-contrib-2.tar.gz
The files are retrieved with wget. In this example, the 64-bit Linux files (<OS>="Linux") 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% mkdir /soft/download/ unix% cd /soft/download unix% wget https://cxc.cfa.harvard.edu/ciao-install/ciao-4.12/Linux/ciao-4.12-bin-core-Linux.tar.gz unix% wget https://cxc.cfa.harvard.edu/ciao-install/ciao-4.12/Linux/ciao-4.12-bin-graphics-Linux.tar.gz unix% wget https://cxc.cfa.harvard.edu/ciao-install/ciao-4.12/Linux/ciao-4.12-bin-obsvis-Linux.tar.gz unix% wget https://cxc.cfa.harvard.edu/ciao-install/ciao-4.12/Linux/ciao-4.12-bin-prism-Linux.tar.gz unix% wget https://cxc.cfa.harvard.edu/ciao-install/ciao-4.12/Linux/ciao-4.12-bin-sherpa-Linux.tar.gz unix% wget https://cxc.cfa.harvard.edu/ciao-install/ciao-4.12/Linux/ciao-4.12-bin-tools-Linux.tar.gz unix% wget https://cxc.cfa.harvard.edu/ciao-install/ciao-4.12/all/ciao-4.12-contrib-2.tar.gz unix% wget ftp://cda.harvard.edu/pub/arcftp/caldb/caldb_4.9.1_main.tar.gz unix% wget ftp://cda.harvard.edu/pub/arcftp/caldb/acis_bkgrnd_4.7.6.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.7.6.tar.gz caldb_4.9.1_main.tar.gz ciao-4.12-bin-core-Linux.tar.gz ciao-4.12-bin-graphics-Linux.tar.gz ciao-4.12-bin-obsvis-Linux.tar.gz ciao-4.12-bin-prism-Linux.tar.gz ciao-4.12-bin-sherpa-Linux.tar.gz ciao-4.12-bin-tools-Linux.tar.gz ciao-4.12-contrib-2.tar.gz
Where should CIAO and CALDB be installed?
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.12 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.12/. This directory (/usr/local/ciao-4.12/) 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 the /soft/ directory.
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:
Installing CIAO as the root user
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.12/ 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.
Installing the CIAO Software
1. Change to the CIAO installation directory
The CIAO 4.12 tarfiles create a directory named ciao-4.12 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/
2. Unpack CIAO ciao-4.12
From the CIAO location just chosen, untar the CIAO 4.12 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.12-bin-core-Linux.tar.gz unix% gtar xzf /soft/download/ciao-4.12-bin-graphics-Linux.tar.gz unix% gtar xzf /soft/download/ciao-4.12-bin-obsvis-Linux.tar.gz unix% gtar xzf /soft/download/ciao-4.12-bin-prism-Linux.tar.gz unix% gtar xzf /soft/download/ciao-4.12-bin-sherpa-Linux.tar.gz unix% gtar xzf /soft/download/ciao-4.12-bin-tools-Linux.tar.gz
When all the files are unpacked, the CIAO directory will look like:
unix% ls -F ciao-4.12 COPYING* README.obsvis VERSION_sherpa config.sub* lib/ COPYING.LIB* VERSION VERSION_tools configure* ots/ INSTALL_BINARY VERSION.prop_tk bin/ configure.in* param/ INSTALL_SOURCE binexe/ contrib/ share/ LICENSE VERSION_core ciao-type data/ test/ LICENSE.SAO VERSION_graphics config/ doc/ Makefile VERSION_obsvis config.guess* include/ README VERSION_prism config.h.in install-sh*
3. Scripts & Modules Package
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.12 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.12-contrib-2.tar.gz ./ciao-4.12/ ./ciao-4.12/contrib/ ./ciao-4.12/contrib/Changes.CIAO_scripts ./ciao-4.12/contrib/README_CIAO_scripts ./ciao-4.12/contrib/VERSION.CIAO_scripts ./ciao-4.12/contrib/bin/ ./ciao-4.12/contrib/bin/acis_bkgrnd_lookup ... ./ciao-4.12/contrib/param/merge_obs.par ./ciao-4.12/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.
4. Run the configuration script
Run the CIAO configuration script:
unix% cd ciao-4.12/ unix% ./configure Running CXC configure, v4.4.1 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 /soft/ciao-4.10/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_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
5. Run the ciao-python-fix script
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.
6. Link to CALDB
Create a link to the calibration data, changing the path to match your system installation:
unix% pwd /soft/ciao-4.12/ unix% ln -s /soft/CALDB CALDB
At this point, your directory should look like:
unix% ls -F CALDB@ README VERSION_prism config.h.in doc/ COPYING* README.obsvis VERSION_sherpa config.log include/ COPYING.LIB* VERSION VERSION_tools config.status* install-sh* INSTALL_BINARY VERSION.prop_tk bin/ config.sub* lib/ INSTALL_SOURCE binexe/ configure* ots/ LICENSE VERSION_core ciao-type configure.in* param/ LICENSE.SAO VERSION_graphics config/ contrib/ share/ Makefile VERSION_obsvis config.guess* data/ test/
7. Create a CIAO alias
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.12/bin/ciao.csh"
bash users should add the following
to their $HOME/.bashrc file.
alias ciao="source /soft/ciao-4.12/bin/ciao.bash"
ksh users should add the following
to their $HOME/.login file.
alias ciao="source /soft/ciao-4.12/bin/ciao.ksh"
Users can create the file if one does not already exist. These are simply text files that can be edited with the users favorite text editor (emacs, vi, gedit, etc.).
Once the alias is defined, you will be able to simply type
and CIAO will be setup and ready to use in that window.
Create the Help File Indexes
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.12 Monday, November 25, 2019 bindir : /soft/ciao-4.12/bin CALDB : 4.9.1 unix% ahelp -r Processing file '/soft/ciao-4.12/doc/xml/Attributes.xml'...OK .... Processed Files : 1013 Succeeded Files : 1013 Failed Files : 0 Purged Duplicates: 0 Creating Key Indexes...DONE Subject DB Size: 1013 Creating Context Indexes...DONE Context DB Size: 1013 Creating Crossreference DB...DONE Crossreferences DB Size: 14744 Creating Seealso DB...DONE Seealso DB Size: 2130
Run the Smoke Tests
A set of smoke tests are packaged with CIAO 4.12. 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.12/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/45] Running test prism-smoke001 .. [2/45] Running test prism-smoke002 ... PASS [3/45] Running test ahelp-smoke001 ... PASS [4/45] Running test obsvis-smoke004 ... PASS ... [43/45] Running test tools-dmstat-smoke001 ... PASS [44/45] Running test tools-dmstat-smoke002 ... PASS [45/45] 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/45] 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 45 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.
Run individual smoke tests
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, 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.
Test the CALDB installation
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 = /soft/ciao-ciao-4.12/CALDB CALDB version = 4.9.1 release date = 2020-03-24T16:00:00 UTC CALDB query completed successfully.
For a more-thorough validation please follow the chkcif steps described on the download CALDB page.
Clean Up the Tarfiles
Finally, you may delete the tarfiles from the original download directory:
unix% rm /soft/download/ciao*tar.gz
Downloading the CALDB: FTP passive mode
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 220.127.116.11 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 18.104.22.168, 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|
|15 Dec 2015||Updated for CIAO 4.8|
|27 Jan 2016||updated to use contrib 4.8.2|
|09 Feb 2016||updated to CIAO 4.8.1 patch|
|29 Feb 2016||updated to note about the CIAO 4.8.2 patch for OSX El Capitan.|
|25 Mar 2016||updated to use CALDB 4.7.1|
|13 Apr 2016||updated to use contrib 4.8.3|
|27 May 2016||updated to use CALDB 4.7.2|
|03 Oct 2016||updated to use contrib 4.8.4|
|14 Dec 2016||updated for CIAO 4.9, CALDB 4.7.3, and contrib 4.9.1.|
|12 Apr 2017||updated to use contrib 4.9.2|
|04 May 2017||updated to use CALDB 4.7.4|
|24 May 2017||updated to use contrib 4.9.3|
|20 Jul 2017||updated to use CALDB 22.214.171.124 and contrib 4.9.4|
|18 Aug 2017||updated to use CALDB 4.7.6|
|14 Dec 2017||updated to use CALDB 4.7.7|
|09 Apr 2018||Updated for CIAO 4.10.|
|15 May 2018||updated to use contrib 4.10.2|
|28 Jun 2018||updated to use CALDB 4.7.9|
|11 Sep 2018||updated to use CALDB 4.8.0|
|25 Oct 2018||updated to use CALDB 4.8.1|
|07 Nov 2018||updated to use contrib 4.10.3|
|20 Feb 2019||Misc. cleanup.|
|29 Apr 2019||updated to use contrib 4.11.2|
|23 May 2019||updated to use contrib 4.11.3 and CALDB 4.8.3|
|07 Aug 2019||updated to use contrib 4.11.4|
|03 Sep 2019||updated to use CALDB 4.8.4|
|11 Dec 2019||CIAO 4.12 updates.|
|24 Feb 2020||Updated to use https://cxc locations for CIAO-4.12 files.|
|10 Apr 2020||updated to use CALDB 4.9.1 and contrib 4.12.2|