Installing CIAO 4.17 Using the ciao-install Script

Quick Start: Running ciao-install

Just looking for a reminder on how to run the ciao-install script? Here is it:

unix% bash /<path>/ciao-install

or, as described further below,

unix% bash /<path>/ciao-install --help

For a detailed description of running the script, read the rest of this thread.

System Requirements

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.

Installation Issues

Users should be aware of these installation items before installing CIAO 4.17. 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/*

Download the ciao-install script

download the ciao-install script.

Note

Note: If you download multiple copies of ciao-install it is likely that your browser will append a number onto the file name, eg "ciao-install(1)". Be sure to check that you are using the last/correct version of this file.

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.

Installing the CIAO Software

ciao-install may be run from any location. The script prompts for required information. Here are the prompts and sample answers for a user named "ciaouser"; each prompt is explained in the following section:

unix% bash /<path>/ciao-install
Script Log file is /soft/download/ciao-install-23-12-04.10.20.52.log

Download directory for tar files (/soft/download): /soft/download
CIAO installation directory (/home/ciaouser): /soft
Delete the cache after install? (y|n) (n): 
Run smoke tests? (y|n) (y): 
Save these settings? (y|n) (y): 
Downloading Conda...
Verifying Conda...
Installing: ciao sherpa contrib caldb 
For Linux
Downloading environment files for Linux...
Installing segments...
Fixing install...
Fixing top to: /soft/ciao-4.17
DONE!
CIAO configuration is complete... 
CIAO 4.17.0 Friday, December 06, 2024
  bindir      : /soft/ciao-4.17/bin
  CALDB       : 4.11.6
Re-indexing ahelp system
Running smoke tests
 Requested test suite includes 37 tests
   [1/37] Running test ahelp-smoke001 ... PASS
   [2/37] Running test dm-smoke001 ... PASS
   [3/37] Running test dm-smoke002 ... PASS
   [4/37] Running test dm-smoke003 ... PASS
   [5/37] Running test dm-smoke004 ... PASS
   [6/37] Running test dm-smoke005 ... PASS
   [7/37] Running test dm-smoke006 ... PASS
   [8/37] Running test dm-smoke007 ... PASS
   [9/37] Running test ds9-smoke001 ... PASS
   [10/37] Running test ipython-smoke001 ... PASS
   [11/37] Running test ipython-smoke002 ... PASS
   [12/37] Running test obsvis-smoke001 ... PASS
   [13/37] Running test sherpa-smoke001 ... PASS
   [14/37] Running test tools-ape-smoke001 ... PASS
   [15/37] Running test tools-arfcorr-smoke001 ... PASS
   [16/37] Running test tools-asphist-smoke001 ... PASS
   [17/37] Running test tools-asphist-smoke002 ... PASS
   [18/37] Running test tools-csmooth-smoke001 ... PASS
   [19/37] Running test tools-dmcoords-smoke001 ... PASS
   [20/37] Running test tools-dmcoords-smoke002 ... PASS
   [21/37] Running test tools-dme-smoke001 ... PASS
   [22/37] Running test tools-dme-smoke002 ... PASS
   [23/37] Running test tools-dmstat-smoke001 ... PASS
   [24/37] Running test tools-dmstat-smoke002 ... PASS
   [25/37] Running test tools-dmstat-smoke003 ... PASS
   [26/37] Running test tools-hpe-smoke001 ... PASS
   [27/37] Running test tools-mkacisrmf-smoke001 ... PASS
   [28/37] Running test tools-mkacisrmf-smoke002 ... PASS
   [29/37] Running test tools-mkacisrmf-smoke003 ... PASS
   [30/37] Running test tools-mkwarf-smoke001 ... PASS
   [31/37] Running test tools-mkwarf-smoke002 ... PASS
   [32/37] Running test tools-tcm-smoke001 ... PASS
   [33/37] Running test tools-tgdetect-smoke001 ... PASS
   [34/37] Running test tools-tge-smoke001 ... PASS
   [35/37] Running test tools-tge2-smoke001 ... PASS
   [36/37] Running test tools-tre-smoke001 ... PASS
   [37/37] Running test tools-wav-smoke001 ... PASS
 37 smoke tests run: 37 PASSED, 0 FAILED, 0 SKIPPED
To use the install:
	(t)csh: $> source /soft/ciao-4.17/bin/ciao.csh
	bash/zsh: $> source /soft/ciao-4.17/bin/ciao.sh

Download directory for tar files (/soft/download): /soft/download

CIAO installation directory (/home/ciaouser): /soft

Delete the cache after install? (y|n) (n): 

Run smoke tests? (y|n) (y): 

Save these settings? (y|n) (y): 

Installing: ciao sherpa contrib caldb

For Linux

At this point, the script begins to download the software.

Downloading environment files for Linux...
Installing segments...
Fixing install...
Fixing top to: /soft/ciao-4.17
DONE!

After the files are downloaded and unpacked, the script configures CIAO and reindexes the CIAO help files ("ahelp"):

CIAO configuration is complete... 
CIAO 4.17.0 Friday, December 06, 2024
  bindir      : /soft/ciao-4.17/bin
  CALDB       : 4.11.6
Re-indexing ahelp system

The script will then run the smoke tests. Since 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.

The screen output provides a count of how many tests have been run:

Running smoke tests
 Requested test suite includes 37 tests
   [1/37] Running test ahelp-smoke001 ... PASS
   [2/37] Running test dm-smoke001 ... PASS
   [3/37] Running test dm-smoke002 ... PASS
...

This will continue until all the tests have finished, at which point you should see

   [36/37] Running test tools-tre-smoke001 ... PASS
   [37/37] Running test tools-wav-smoke001 ... PASS
 37 smoke tests run: 37 PASSED, 0 FAILED, 0 SKIPPED

Verifying test successes

A successful test is logged with a "... PASS", while an unsuccessful test reports:

   [7/37] 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:

 37 smoke tests run: 37 PASSED, 0 FAILED, 0 SKIPPED

or if any failed:

 37 smoke tests run: 36 PASSED, 1 FAILED, 0 SKIPPED

       !! 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.

Finished!

The script finished by printing the installation location.

To use the install:
	(t)csh: $> source /soft/ciao-4.17/bin/ciao.csh
	bash/zsh: $> source /soft/ciao-4.17/bin/ciao.sh

Known Smoke Test Issues

There is a bug page for known installation and smoke test issues. If you experience a problem that isn't listed there, submit it to CXC Helpdesk.

You can now proceed to the creating a CIAO alias step.

Create a CIAO alias

It is strongly suggested that you create an alias to make it easy to set up and use CIAO.

The syntax for the alias command depends on the shell (tcsh/csh, bash/zsh/ksh); see this FAQ for help in determining which shell you are using. The actual command to alias will depend on whether CIAO was installed using conda install or with the ciao-install script.

Bourne shell and variants: bash, dash, zsh, and ksh

If CIAO was installed using conda create, then the alias command will be either

alias ciao="conda activate ciao-4.17"
  -or-
alias ciao="source activate ciao-4.17"

Which one depends on how conda is setup on your system.

If CIAO was installed using the ciao-install script then the alias command is

alias ciao="source /soft/ciao-4.17/bin/ciao.sh"

Users should add these alias commands to their startup scripts: bash use $HOME/.bashrc, dash use $HOME/.profile, zsh use $HOME/.zshrc, and ksh use $HOME/.kshrc.

C shell and variants: tcsh

If CIAO was installed using conda create, then the alias command will be

alias ciao "conda activate ciao-4.17"

If CIAO was installed using the ciao-install script then the alias command is

alias ciao "source /soft/ciao-4.17/bin/ciao.csh"

Users should add these alias commands to their startup scripts: csh use $HOME/.cshrc, tcsh use $HOME/.tcshrc (or $HOME/.cshrc if already present).

Users can create the startup 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.). The startup files are sourced when you open a new terminal; if you want to start using the alias in a terminal window that is already open then you have to manually source it.

$ source FILENAME

More information is given in 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.

Clean Up

Finally, you may delete the tarfiles from the original download directory. For this example we would say:

unix% cd /soft/download
unix% /bin/rm -rf conda_constructors conda_installers conda_loc-linux-64 env_files

You may also delete the log file(s) - e.g. ciao-install-<date>.log - once you have reviewed them for errors.

Customizing installation

The ciao-install script has several options. Use --help to review them.

unix% bash /path/ciao-install --help
Usage: ciao-install [options...]

  -h --help          Print this message
  --download-only    Download only (do not install)
  --install-only     Install only (do not download)
  --cache <dir>      Cache directory to use
  --pkg-cache <dir>  (Optional) Override the default package cache
  --prefix <dir>     Install directory
  --with-top <dir>   Fix the install to think it is here
  --link-caldb <dir> Location of CALDB to link in
  --system <system>  System to install
     (linux, macos, or macos-arm)
  --delete-cache     Delete the download cache
  --add <segment>    Add additional segment to CIAO
  --remove <segment> Skip segment.
  --skip-tests       Skip tests after install
  --small-files      Use smaller files to install where possible.
  --force            Overwrite existing install
  --update           Update existing install
  --with-top <dir>   (non-standard) Fix the init scripts
                     to think they are elsewhere
                     (eg. cluster install)
  --download-all <dir> 
                     (non-standard) Generates a complete
                     cache of all products required for install
                     for all supported platforms.
                     Forces --download-only
  --logdir <dir>     Log file directory (defaults to current dir)
  -v, --verbose      Includes more progress output to the screen

unix% yes | bash ciao-install --prefix /soft --cache /soft/download

unix% bash ciao-install --prefix /net --with-top /soft --cache /soft/download

unix% bash ciao-install --add acis 
  -or-
unix% bash ciao-install --add hrc 
  -or-
unix% bash ciao-install --add acis --add hrc

unix% mkdir -p /soft/CALDB
unix% cd /soft/CALDB

unix% wget https://cxc.cfa.harvard.edu/cdaftp/arcftp/caldb/caldb_4.11.6_main.tar.gz
  -or-
unix% curl -O https://cxc.cfa.harvard.edu/cdaftp/arcftp/caldb/caldb_4.11.6_main.tar.gz

unix% tar xfz caldb_4.11.6_main.tar.gz
unix% rm caldb_4.11.6_main.tar.gz   # (optionally cleanup when done)

unix% bash ciao-install --link-caldb /soft/CALDB
…
Linking CALDB from: /soft/CALDB
To: /soft/ciao-4.17/CALDB
…

unix% bash ciao-install --add ciao-src
   -or-
unix% bash ciao-install --add sherpa-src
   -or-
unix% bash ciao-install --add ciao-src --add sherpa-src

unix% bash ciao-install --system linux 
   -or-
unix% bash ciao-install --system macos       # Intel/x86
   -or-
unix% bash ciao-install --system macos-arm   # ARM/M1/M2/M3

unix% ciao
unix% cd $ASCDS_INSTALL
unix% bash test/smoke/bin/run_smoke_tests.sh

unix% ciao
unix% ahelp -r

unix% bash ciao-install --remove sherpa …
   -or-
unix% bash ciao-install --remove ciao-contrib …
   -or-
unix% bash ciao-install --remove caldb …

unix% bash ciao-installl --remove sherpa --remove ciao-contrib --remove caldb …

Relocating Installation

It is strongly recommended that users not relocate their CIAO installation after it has been installed. If this is unavoidable, then users can follow the steps outlined below.

1. After CIAO has been installed and before it is moved/relocated, users need to run the ciao-configure script to reconfigure their installation:

   unix% cd $ASCDS_INSTALL
   unix% bash bin/ciao-configure /<New_Path>/
   Fixing top to: <New/Path/>
   DONE!
   

   Note: <New/Path/> does not need to exist at the time ciao-configure is run.

2. After it has been reconfigured, then the CIAO installation can be moved

   unix% cd $HOME
   unix% mv $ASCDS_INSTALL /<New_Path>/
   

3. Users can then source the CIAO setup script an use CIAO from the new location

   unix% source /<New_Path>/bin/ciao.sh -o     # or ciao.csh for tcsh shell users
   CIAO configuration is complete... 
   The CIAO setup for this window has changed from
   CIAO 4.16.0 Tuesday, December 05, 2023
     bindir      : /soft/ciao-4.16/bin
     CALDB       : 4.11.6
   To:
   CIAO 4.17.0 Friday, December 06, 2024
     bindir      : /soft/ciao-4.17/bin
     CALDB       : 4.11.6
   

Alternative Download Options

Users on slow internet or wireless connections may experience problems downloading the large data files associated with the Chandra CALDB and the XSPEC models. Often users will be able to simply retry again successfully; however, sometimes the server timeouts are persistent.

Installing CIAO via conda allows for more customization of the download process which may work better for slower connections. However, if the ciao-install format is necessary, the necessary files are also available to download from Google Drive and install manually.

unix% bash ciao-4.17.0-macOS.sh -b -p ciao-4.17

unix% bash ciao-4.17.0-Linux.sh -b -p ciao-4.17

unix% cd ciao-4.17/
unix% ./bin/ciao-configure

unix% source bin/ciao.sh

unix% source bin/ciao.csh

unix% ahelp -r