		CIAO: Chandra Interactive Analysis of Observations
			       Version 4.17  README
			          December, 2024
  
--------------------------------------------------------------------
Table of contents
--------------------------------------------------------------------
I) Overview
II) Installation

--------------------------------------------------------------------
I) Overview
--------------------------------------------------------------------

This file contains release information and instructions for the
Release of Version 4.17 of CIAO (Chandra Interactive Analysis of
Observations), the Chandra X-Ray Center Data System (CXCDS) data
analysis system.

Release notes can be found at:

  https://cxc.harvard.edu/ciao4.17/releasenotes/

In addition to the tools and applications, the binary distribution
contains all the header files and libraries necessary for compiling
and linking your own programs against the CIAO libraries (e.g., the
Data Model).  You may still wish to download the source distribution
and rebuild CIAO from scratch, but this step is not needed if you wish
to compile and link your own tools with CIAO libraries.

More information is available from:

  https://cxc.harvard.edu/ciao4.17/

System Requirements
-------------------

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 4Gb main
memory and disk space on the order of 5 Gb, as given in (II).

Platforms
---------

As of this release the CIAO binary distributions have been built on:

	RHEL 8.8 64bit
	MacOS 11 - Big Sur (Intel and ARM)

and tested on various Linux platforms and macOS 11-15.

Please be advised that you may experience some problems when trying to
use the package on older (and possibly even on newer) versions of
these platforms.

Each distribution requires the presence of the following:

	X11 
	gzip		(GNU zip package)
	gtar		(GNU tar package)

The Source builds require the presence of the following:

        CMake

Macintosh users will need to install Xquartz from:
    http://xquartz.macosforge.org/landing/

Usage/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 the top of the $ASCDS_INSTALL tree.  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 further governed by the GNU
General Public License and/or the GNU Library General Public License,
both of which are bundled with the software and can be found at the
top of the distribution tree.The software is released under
the GPL v3 (or at your option any later version).

If you have any problems, questions, or suggestions, please contact
the CXC Help Desk at:

  https://cxc.harvard.edu/helpdesk/

--------------------------------------------------------------------
II) Installation
--------------------------------------------------------------------

Software
--------

The CIAO software is distributed through conda or via the ciao-install
wrapper script. The ciao-install wrapper script utilizes 2 packages (ciao
and sherpa) for the binary distibution.

Downloading/unpacking the source is optional as the binary
distributions contain everything needed to install, configure, and
utilize the software. You only need the source distributions should
you wish to rebuild the software on your local machine.

Please see the file INSTALL_BINARY for further installation
instructions and INSTALL_SOURCE for instructions for building CIAO
from source.


Parameter File Interfaces and CIAO
----------------------------------

The use of the parameter file interface within the CIAO command-line tools
presents some non-trivial issues for users.  There are several different
parameter interface implementations in current use, three of the most 
prevalent being from IRAF, FTOOLS, and SAO.  While for the most part each 
implementation is "IRAF-compatible," each differ somewhat in the order in 
which directories are searched for input, on where parameter updates are 
written, and in the names of the environment variables used to determine 
such.  A brief synopsis of three of the more important variables is:

	UPARM	- defined/used by IRAF parameter interface
	PFILES  - introduced by FTOOLS parameter interface, which also
		  supports UPARM; 
	PDIRS	- introduced by SAO parameter interface, which also supports
		  PFILES and UPARM

The location used by CIAO for the users copy of the parameter files is
the $HOME/cxcds_param4 directory.
