Starting CIAO

Setup for CIAO 4.17

To use the CIAO software, you must first source a setup script. Creating an alias allows users to run a single, simple command with minimal typing. There are a few things to note about setting up the alias:

• These examples have CIAO installed in the directory /soft/ciao-4.17/. The location of the CIAO software on your system may be different.

• If CIAO 4.17 was installed using conda, these examples assume the environment was called "ciao-4.17" (without quotes).

• If you have more than one version of CIAO installed, you may wish to version the alias to distinguish between them.

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

Then you can just type "ciao" to start the software. CIAO installed with conda will look like this:

$ ciao
(ciao-4.17) $

or, CIAO installed with ciao-install will look like this:

$ ciao 
CIAO 4.17.0 Friday, December 06, 2024
  bindir      : /soft/ciao-4.17/bin
  CALDB       : 4.11.6

It is only necessary to do this once per terminal/window. The ciaover command can be used to get additional version information (from either installation method)

(ciao-4.17) $ ciaover -v
The current environment is configured for:
  CIAO        : CIAO 4.17.0 Friday, December 06, 2024
  Contrib     : Package release 0  Tuesday, December 10, 2024
  bindir      : /soft/ciao-4.17/bin
  Python path : /soft/ciao-4.17/bin
  CALDB       : 4.11.6

System information:
Linux is.awesome.edu 4.18.0-477.13.1.el8_8.x86_64 #1 SMP Thu May 18 10:27:05 EDT 2023 x86_64 x86_64 x86_64 GNU/Linux

Repeating setup CIAO 4.17 setup command

In general, we do not recommend that users source the same CIAO setup command in the same terminal more than once. This may leave the shell environment in an unexpected state.

If CIAO was installed using ciao-install, the startup script will not allow you to restart CIAO in a session, instead reporting the following:

unix% ciao
ERROR: The current environment is configured for:
CIAO 4.17 Friday, December 06, 2024
  bindir      : /soft/ciao-4.17/bin
  CALDB       : 4.11.6
Please use the '-o' option to override the previous setup.

If you wish to restart CIAO, then you should either start CIAO in a different window or use the override option ("-o"):

unix% ciao -o
CIAO configuration is complete... 
The CIAO setup for this window has changed from
CIAO 4.16 Tuesday, December 05, 2023
  bindir      : /soft/ciao-4.16/bin
  CALDB       : 4.11.6
To:
CIAO 4.17 Friday, December 06, 2024
  bindir      : /soft/ciao-4.17/bin
  CALDB       : 4.11.6

If CIAO was installed using conda and you repeat the activate command, it will replace the current CIAO environment with the same environment.

% conda activate ciao-4.17
(ciao-4.17) % conda activate ciao-4.17
(ciao-4.17) % 

Switching between CIAO 4.16 and CIAO 4.17

Users have to be careful about switching between different version of CIAO because of differences in parameter files and IPython startup scripts. The default local parameter file directory name is the same in CIAO, which makes it more tricky to run both CIAO 4.16 and CIAO 4.17 in separate terminal windows. For example, assuming CIAO 4.16 is installed in /soft/ciao-4.16 and CIAO 4.17 in /soft/ciao-4.17:

unix% alias oldciao 'source /soft/ciao-4.16/bin/ciao.csh'
unix% oldciao
CIAO configuration is complete...
CIAO 4.16 Tuesday, December 05, 2023
  bindir      : /soft/ciao-4.16/bin
  CALDB       : 4.11.6

unix% echo $PFILES
/home/username/cxcds_param4;/soft/ciao4.16/contrib/param:/soft/ciao4.16/param

unix% paccess dmgti
/home/username/cxcds_param/param/dmgti.par

and in a different window, using the suggested alias to start CIAO 4.17:

unix% ciao
unix% echo $PFILES
/home/username/cxcds_param4;/soft/ciao-4.17/contrib/param:/soft/ciao-4.17/param

unix% paccess dmgti
/home/username/cxcds_param4/dmgti.par

You can see that the information is being read from the same parameter file locations. If there are changes to the parameter file (parameters added or deleted) then CIAO may have problems updating to the correct version.

CIAO and FTOOLS

Both CIAO and FTOOLS use parameter files to store parameter values for tools, and provide tools for manipulating these files (e.g. plist, pset, punlearn; they have the same name in both systems). The location of the parameter files is taken from the $PFILES environment variables for CIAO and FTOOLS.

We recommend that you start FTOOLS before CIAO. Here is an example of starting version 6.x of FTOOLS and CIAO 4.17:

unix% setenv HEADAS /soft/lheasoft/headas/x86_64-pc-linux; \
      source $HEADAS/headas-init.csh
unix% ciao

Change the HEADAS path to match your local installation. Note this syntax applies only to C Shell variants (csh, tcsh); for further details on starting FTOOLS, including other shells, refer to the Installing HEAsoft instructions.

The $PFILES variable has been set up to use both the CIAO and FTOOLS directories:

unix% echo $PFILES
/home/username/cxcds_param4:/home/username/pfiles;/soft/ciao-4.17/contrib/param:
/soft/ciao-4.17/param:/soft/lheasoft/headas/x86_64-pc-linux/syspfiles 

Caveat: Conflicts with Other Software Packages

There are some known conflicts between CIAO and other software or system libraries and tools. Be sure to read the "Other Software Packages" bug page for a list of these issues.