Last modified: December 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/ciao-install.html
AHELP for CIAO 4.16

ciao-install

Context: concept

Synopsis

Download and install CIAO, CALDB, and the contributed script files

Syntax

bash ciao-install
bash ciao-install --help

Description

The ciao-install script is designed to simplify and automate the installation and upgrade of the CIAO software and of the Chandra Calibration DataBase (CALDB). It downloads the necessary files, verifies and installs them, configures the installation, and then runs a quick test of the system (the smoke tests). It is strongly suggested that these tests are run to check that the installation succeeded.

The ciao-install script is downloaded from the ciao-install download page. After downloading, it must be run using the bash shell. The default settings provide a full installation with the base calibration database (without the ACIS or HRC blank sky background files), but this selection can be changed via the command-line options to the script. Please check the Platform support page for information on the systems for which CIAO is available.

If there are any problems installing CIAO, such as smoke tests failures, please refer to the Installation and Smoke Tests bugs page and, if this does not help you, the CXC Help Desk.


Examples

Example 1

$ bash ciao-install

Without any command line parameter the script will prompt the user for the download directory and the installation directory (which may be the same directory, and can be set to "." to use the current working directory).

Download directory for tar files: ./download
CIAO installation directory: /opt/install_dir
Downloading Conda...
Verifying Conda...
Installing: ciao sherpa contrib caldb 
For Linux
Downloading environment files for Linux...
Installing segments...
Fixing install...
Fixing top to: /opt/install_dir/ciao-4.16
DONE!
CIAO configuration is complete... 
CIAO 4.16.0 Monday, November 13, 2023
  bindir      : /opt/install_dir/ciao-4.16/bin
  CALDB       : 4.10.7
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-smoke004 ... 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
Script Log file is /opt/install_dir/ciao-install-23-11-15.13.45.36.log
To use the install:
        (t)csh: $> source /opt/install_dir/ciao-4.16/bin/ciao.csh
        bash/zsh: $> source /opt/install_dir/ciao-4.16/bin/ciao.sh

Example 2

$ bash ciao-install --prefix ./install_dir --cache ./cache_dir

Since the "prefix" and "cache" directories have been specified on the command line the script will begin the installation without prompting the user.

Example 3

$ bash ciao-install --add acis

The ACIS blank sky background files will now be added to the list of packages to install. Similarly using "--add hrc" will download the HRC blank sky background files.

Example 4

$ bash ciao-install --add ciao-src --add sherpa-src

In addition to the standard packages, the CIAO and Sherpa source code will also be installed.

Example 5

$ bash ciao-install --link-caldb /Applications/CALDB

Instead of installing the CALDB, the script will setup the necessary links to the /Applications/CALDB directory.


Command line options

The following are the available command line option flags

  -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)
  --save-cache       Keep the download cache
  --add <segment>    Add additional segment to CIAO
  --remove <segment> Skip segment.
  --skip-tests       Skip tests after install
  --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

Default segments

The default segments installed by the script are

ciao sherpa contrib caldb

and these can be changed with the --add or --remove arguments.

ACIS blank-sky background files

The ACIS blank-sky background files will be added by adding the

--add acis

command-line flag.

HRC blank-sky background files

The HRC blank-sky background files will be added by adding the

--add hrc

command-line flag.

CIAO and Sherpa source code

The source code for CIAO or Sherpa can also be included using either, or both, of the following command-line flags:

--add ciao-src 
--add sherpa-src

Installing updates

Updates are installed using the same ciao-install command. This includes updates to CIAO, Sherpa, CALDB, and the CIAO contributed scripts.

$ bash ciao-install --prefix /opt/install_dir --cache ./
/opt/install_dir/ciao-4.16 already exists. Update? (y/n): 
...

The script will prompt the user update an existing installation (unless the "--update" option is used, in which case the update will begin automatically).

Alternative installation: conda

Since CIAO 4.12 it has been possible to install CIAO with the conda system. See the Installing CIAO with conda page for more information.

Changes in CIAO 4.16

The ciao-install script is now downloaded directly from the ciao-install download page without the need to configure the settings. The command-line options described above are used to change the behaviour.

macOS ARM support

CIAO 4.16 is the first release that provides native support for the macOS ARM system. The ciao-install script will automatically pick up this version if supported by the OS, but it can also be selected with the --system macos-arm command-line option.


Bugs

If there are any problems installing CIAO, such as smoke tests failures, please refer to the Installation and Smoke Tests bugs page and, if this does not help you, the CXC Help Desk.

Refer to the CIAO bug pages for an up-to-date listing of known issues.

See Also

calibration
caldb
chandra
coords, level, pileup, times
concept
autoname, ciao, history, parameter, stack, subspace
dm
dm, dmascii, dmbinning, dmfiltering, dmmasks, dmopt, dmregions
paramio
paramio