About Chandra Archive Proposer Instruments & Calibration Newsletters Data Analysis HelpDesk Calibration Database NASA Archives & Centers Chandra Science Links

Skip the navigation links
Last modified: 12 Sep 2007
Hardcopy (PDF): A4 | Letter

Installing CIAO 3.4

[CIAO 3.4 Science Threads]


Last Update: 12 Sep 2007 - updated for CALDB 3.4.1


How to install version 3.4 of CIAO, the Chandra Interactive Analysis of Observations software package.

This thread does not explain how to re-compile CIAO yourself. Refer to the CIAO README file for information on that process.

Proceed to the HTML or hardcopy (PDF: A4 | letter) version of the thread.


System Requirements

CIAO is supported on a number of operating systems, which are listed on the Platform Support page. Users may experience some problems when trying to use CIAO on older or newer versions of these platforms.

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 128Mb main memory, and disk space on the order of 1-2 GB.

The software also requires the following versioned software (newer versions are acceptable):


OS X 10.3 (Panther) and 10.4 (Tiger) users should use the version of X11 that came with the operating system. OS X 10.2.x (Jaguar) users will need to install X11; we have tested against X11 for Mac OS X Public Beta 3.

We have also packaged additional X11 libraries needed to run CIAO that are not currently available with convenient packaging. These seem to work fine with the Apple release, and should work with other versions of X available for the Mac.

Motif 2.0.1

Solaris users should have Motif installed by default. Linux and Mac OS X distributions contain the LessTif v0.93.18 libraries, which meet this requirement.


Or version 2.5 of Lynx, a text-based browser.


The GNU zip package.

Downloading the Software

To install CIAO, you need the following packages from the CIAO download pages:

  • Binaries: cxc_bin_<OS_name>.tar.gz.

    There have been two software patches for users running CIAO on Mac OS X. (Solaris and Linux platforms are not affected.)

    Note that each of these patches is a direct upgrade to CIAO 3.4. Intel Mac users do not need to install the CIAO 3.4.1 patch before installing CIAO

    If you are working on either of these platforms, download the appropriate patch binary in addition to the CIAO 3.4 binaries.

  • Auxilary: cxc_aux.tar.gz

  • Chandra Calibration Database (CALDB)

  • Contributed science scripts

Users doing spectral analysis (e.g. line indentification) will also want the Atomic Database (ATOMDB).

Save the tarfiles to a location that is accessible from where you wish to install CIAO. These files were used to install CIAO on a Solaris machine:

unix% ls -1
ciao_3.4.1[.1]_bin_osx.tar.gz  (Mac OS X 10.4 only)


It is suggested that you install the CALDB and ATOMDB (if desired) before starting the CIAO installation, as CIAO has to be linked to the location of these files. Installation instructions are available on the CALDB and ATOMDB websites:

For this thread, we assume that the databases are installed in the /data directory:


Installing the CIAO Software

1. Unzip the files

First we have to uncompress all the gzip'ed files:

unix% gunzip *gz

This process will take a few minutes. When gunzip is done running, there will only be .tar files in the directory:

unix% ls -1
ciao_3.4.1[.1]_bin_osx.tar  (Mac OS X 10.4 only)

2. Create the CIAO root directory

Move to the directory in which you would like the root of the CIAO installation to be located. As mentioned, the directory should have approximately 2 GB free space. If you are installing the software for a local network, this directory must also be visible to all potential CIAO users.

Create a directory for the software root; it can be named whatever you like:

unix% cd /data/
unix% mkdir ciao_3.4
unix% cd ciao_3.4

3. Unpack CIAO 3.4

From within the CIAO root directory just created, untar the CIAO 3.4 binary files.

unix% pwd

unix% tar xvf /some/path/cxc_bin_sun.tar
x COPYING, 17982 bytes, 36 tape blocks
x COPYING.LIB, 25265 bytes, 50 tape blocks
x COPYRIGHT.SAO, 2099 bytes, 5 tape blocks
x COPYRIGHT.SM, 709 bytes, 2 tape blocks
x LICENSE, 1265 bytes, 3 tape blocks
x README, 20999 bytes, 42 tape blocks
x README.cycle7, 2121 bytes, 5 tape blocks
x README.obsvis, 8662 bytes, 17 tape blocks
x README.osx, 2063 bytes, 5 tape blocks
x README.tru64, 3464 bytes, 7 tape blocks
x VERSION, 37 bytes, 1 tape blocks
x VERSION.prop_tk, 36 bytes, 1 tape blocks
x bin, 0 bytes, 0 tape blocks


x ots/slang.v1.4.9/include/slang.h, 67265 bytes, 132 tape blocks
x ots/slang.v1.4.9/include/slcurses.h, 11162 bytes, 22 tape blocks

If you prefer less screen output, omit the "v" option from the tar command.

Now repeat the process with the auxilary package:

unix% tar xvf /some/path/cxc_aux.tar 
x data, 0 bytes, 0 tape blocks
x data/hetg.descrip, 87 bytes, 1 tape blocks
x data/letg.descrip, 81 bytes, 1 tape blocks
x data/rolldev.dat, 673 bytes, 2 tape blocks
x data/psfsize_20000830.fits, 2108160 bytes, 4118 tape blocks
x data/psfsize20010416.fits, 1586880 bytes, 3100 tape blocks


x share/slsh/autoload.sl, 134 bytes, 1 tape blocks
x share/slsh/require.sl, 2401 bytes, 5 tape blocks

4. Run the configuration script

Due to licensing restrictions, we are unable to distribute CIAO with support for gzip'ed FITS files enabled. As an end user, if you can comply with the terms of the GNU General Public License, you may enable support by using the --with-gz configuration switch at the time of installation. For information on other options available for use with configure, refer to the "Compiling instructions" section of the CIAO README file.

unix% ./configure --with-gz
creating cache ./config.cache
Running CXC configure, v3.1.1
checking host system type... sparc-sun-solaris2.8
checking target system type... sparc-sun-solaris2.8
checking build system type... sparc-sun-solaris2.8
ccinc = /usr/include
checking for more... /usr/ucb/more
checking for main in -lpthread... yes
configure: warning:   --with-imagerdir not specified, defaulting to /some/path/ciao_3.4/ots/saord
updating cache ./config.cache
creating ./config.status
creating config/system/CXCdefaults
creating share/slsh/local-packages/varmmio.sl
creating bin/ciao.sh
creating bin/ciao.csh
creating bin/ciao.ksh
creating bin/ciao.bash
creating lib/sm/sm.cxcds
creating lib/sm/graphcap.local
creating config.h
config.h is unchanged

5. Link to CALDB and ATOMDB

Create links to the calibration and atomic data, changing the path to match your system installation:

unix% ln -s /data/CALDB CALDB

unix% ln -s /data/ATOMDB ATOMDB

At this point, your directory should look similar to this:

unix% ls
ATOMDB@         README.osx      config.log      install-sh*
CALDB@          README.tru64    config.status*  lib/
COPYING*        VERSION         config.sub*     log
COPYING.LIB*    VERSION.prop_tk configure*      ots/
COPYRIGHT.SAO   bin/            configure.in*   param/
COPYRIGHT.SM    config/         contrib/        quickhelp/
LICENSE         config.cache    data/           share/
README          config.guess*   doc/
README.cycle7   config.h        etc/
README.obsvis   config.h.in     include/

6. Create a CIAO alias

It is strongly suggested that you create a CIAO alias in your $HOME/.cshrc (csh and tcsh users) or $HOME/.login (sh, ksh, and bash users) file. Instructions on how to do so are given in the Running CIAO section of the Starting CIAO thread.

Once the alias is defined, you will be able to simply type

unix% ciao

and CIAO will be setup and ready to use in that window.

Overlay the CIAO patch (Mac OS X 10.4 users only)

The instructions are the same for installing either the CIAO 3.4.1 or the CIAO patch.

The patch is installed from the root directory of the CIAO installation. In our example, this directory is /data/ciao_3.4; if you do not recall where your root directory is, start CIAO and type "cd $ASCDS_INSTALL" to get there.

unix% cd /data/ciao_3.4

From this directory, untar the patch file. This example uses the PowerPC patch file, ciao_3.4.1_bin_osx.tar; change the filename in the tar command to ciao_3.4.1.1_bin_osx.tar if you are installing the Intel patch file:

unix% tar xvf /some/path/ciao_3.4.1_bin_osx.tar.gz
x CIAO_3.4.1, 30 bytes, 1 tape blocks
x CIAO_3.4.1_tmp, 0 bytes, 0 tape blocks
x CIAO_3.4.1_tmp/VERSION, 39 bytes, 1 tape blocks
x CIAO_3.4.1_tmp/bin, 0 bytes, 0 tape blocks
x CIAO_3.4.1_tmp/bin/prism, 517468 bytes, 1011 tape blocks
x CIAO_3.4.1_tmp/bin/filtwin, 353888 bytes, 692 tape blocks
x ciao_cleanup.sh, 93 bytes, 1 tape blocks
x ciao_patch.sh, 5287 bytes, 11 tape blocks
x README_patch3.4.1, 1403 bytes, 3 tape blocks

Next, run the ciao_patch.sh script:

unix% ./ciao_patch.sh

This will move the updated CIAO binaries, parameters and XML files to the correct directories. The replaced files are renamed to "<filename>_CIAO_3.4". These files are necessary if you decide to uninstall the CIAO 3.4.1 patch; see the patch README file for more information.

Contributed Science Scripts

The contributed 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 3.4 Contributed Scripts Page. Check that page for announcements about new scripts and updates to existing ones.

The CIAO_scripts.tar file is designed to be unpacked in $ASCDS_INSTALL, the root directory of the CIAO installation. In our example, this directory is /data/ciao_3.4; if you do not recall where your root directory is, start CIAO and type "cd $ASCDS_INSTALL" to get there.

unix% cd /data/ciao_3.4

Since this is a new CIAO directory (i.e. not a patch to an existing version of CIAO), we do not need to worry about uninstalling old scripts.

Uncompress the script tarfile:

unix% tar xvf /some/path/CIAO_scripts.tar
x contrib/Changes.CIAO_scripts, 2992 bytes, 6 tape blocks
x contrib/README_CIAO_scripts, 5648 bytes, 12 tape blocks
x contrib/VERSION.CIAO_scripts, 26 bytes, 1 tape blocks
x contrib/param/acis_bkgrnd_lookup.par, 189 bytes, 1 tape blocks


x contrib/uninstall_CIAO_scripts, 7087 bytes, 14 tape blocks
x contrib/uninstall_CIAO_scripts_pre_3.0.2, 7998 bytes, 16 tape b

Note that 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.

Reindexing the Help Files

The script package contains help files not available in the CIAO 3.4 distribution. In order for CIAO to be able to access these files, it is necessary to regenerate the ahelp indices.

Start CIAO and run ahelp -r:

unix% ciao
CIAO configuration is complete... 
 CIAO version     :  CIAO 3.4 Sunday, November 19, 2006
 Proposal Toolkit version :  Cycle 9 Sunday, November 19, 2006
 bin dir          :  /soft/ciao/bin

unix% ahelp -r

Processing file '/some/path/ciao_3.4/doc/xml/ahelp.xml'...OK

Processing file '/some/path/ciao_3.4/doc/xml/onapplication_toolagent.xml'...OK

Processing file '/some/path/ciao_3.4/doc/xml/Conj.tm.xml'...OK


Creating Context Indexes...DONE
Context DB Size: 1055

Creating Crossreference DB...DONE
Crossreferences DB Size: 12214

Creating Seealso  DB...DONE
Seealso DB Size: 1938

The reindexing process took 15 minutes on a Solaris 8 machine with 384 MB of memory.

Clean Up the Tarfiles

Finally, you may delete the tarfiles from the original download directory:

unix% cd /some/path

unix% ls -1 *tar
ciao_3.4.1[.1]_bin_osx.tar  (Mac OS X 10.4 only)

unix% rm *tar


Linux8 package: libgcc_s.so.1

If you are using an older version of Linux with the Redhat 8 build, you may get the following error message when trying to run ChIPS:

unix% chips
chips: error while loading shared libraries: libgcc_s.so.1: 
cannot open shared object file: No such file or directory

Most modern version of Linux come with the libgcc_s.so.1 file already installed, so the version packaged with CIAO is named differently to avoid conflicts.

If you get this message, it means the file is not on your system. Rename the file so that CIAO can access it:

unix% mv $ASCDS_INSTALL/lib/libgcc_s.so.1.save $ASCDS_INSTALL/lib/libgcc_s.so.1

Mac OS X 10.2: Using ds9 v3.0.3

CIAO 3.4 contains ds9 v4.0b7, which runs on OS X 10.3 or higher. If you are using OS X 10.2, you will need to customize your installation to use ds9 v3.0.3 (also packaged with the CIAO 3.4 software).

To switch between the two versions:

unix% cd $ASCDS_INSTALL/ots/saord/ds9_dir
unix% mv ds9 ds9.4.0
unix% mv ds9.3.0.3 ds9

Known Conflicts

There are some known conflicts between CIAO and other software or system libraries and tools. They are documented in the following webpages:

Usage and 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 $ASCDS_INSTALL/COPYRIGHT.SAO. In a nutshell, you may do whatever you please with CIAO, provided you do not remove the copyright statement. Finally, since parts of CIAO utilize GNU-licensed software it is at least in part further governed by the GNU General Public License ($ASCDS_INSTALL/COPYING) and/or the GNU Library General Public License ($ASCDS_INSTALL/COPYING.LIB), both of which are bundled with the software.


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 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
18 Apr 2007 updated version to CALDB 3.4.0
12 Sep 2007 updated for CALDB 3.4.1

Return to Threads Page: Top | All | Intro
Hardcopy (PDF): A4 | Letter
Last modified: 12 Sep 2007

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory.
60 Garden Street, Cambridge, MA 02138 USA.    Email: cxcweb@head.cfa.harvard.edu
Smithsonian Institution, Copyright © 1998-2004. All rights reserved.