2. Installation

CUBISM runs under IDL, and requires a working version of IDL to function. There are two means of installing CUBISM: as a set of source ‘.pro’ files which IDL finds on its search path, or as a pre-compiled binary, which can be loaded as a single entity. Both versions can be found on the CUBISM home page.

The advantages of a source installation are:

• Access to CUBISM's code for bug fixing or examining algorithms.
• Source level feedback when bugs occur (see section Debugging CUBISM).
• Should continue to function with all future versions of IDL.

The disadvantages of the source installation are:

• Must install the AstroLib dependency library, at the required version. Some (small) risk of future changes in AstroLib causing problems.
• Subject to routine name conflicts (e.g. two routines named ‘routine.pro’ on the path), so you must carefully set your IDL_PATH to be sure CUBISM's files are found first. This should not be a common problem, but users of the staring-mode extraction package SMART may experience routine name conflicts (though not for recent versions; see Source Installation).

The advantages of installing and running a binary version of CUBISM:

• All required routines are included in the compiled file at the required version; no need to install external libraries.
• No routine name conflicts should occur.
• Can be used (sans command line) with the freely available IDL VM, if you don't have access to an IDL license.

and the disadvantages:

• No access to source code level debugging feedback when errors occur, making it harder to track down problems.
• More closely tied to the IDL version; a given binary may not work with all future versions of IDL (though typically binary compatibility between IDL versions within a few versions is quite good).

2.1 Source Installation

The requirements for installing and running CUBISM from source are:

1. A Linux/Solaris/Unix or MacOSX platform. CUBISM may run under the Windows operating system, but has not been tested on a Windows platform.
2. A licensed copy of IDL, version 6.2 or later. Download from RSI (now ITTVIS).
3. The AstroLib library, available from NASA Goddard. Be sure to include it on your IDL_PATH.
4. A compiler for C source, typically gcc, or whatever the IDL routine MAKE_DLL looks for (usually available by default).

The compiler is required to auto-compile a small piece of C code used to speed-up the main cube building algorithm. If this compilation fails, an IDL version of this algorithm will be used, which gives the same results, but operates more slowly.

To install CUBISM from source:

1. Unpack the ‘cubism_vX.XX_src.tgz’ file (where ‘X.XX’ is the version number) in a directory on the IDL path (e.g. ‘~/idl’).
2. Ensure the ‘irs_cubism’ directory which is unpacked is on the IDL_PATH, e.g. by:

   setenv IDL_PATH <IDL_DEFAULT>:+$HOME/idl

System-wide installation is also possible: just install CUBISM in a location accessible by your entire group.

SMART USERS: Users of SMART may experience file name conflicts with CUBISM, in particular in an IDL session started by SMART. As of version 6.2.4, SMART has been modified to avoid such conflicts; upgrading to this version or later is highly recommended.

2.2 Binary Installation

The requirements for CUBISM running as a binary:

1. A Linux/Solaris/Unix or MacOSX platform. CUBISM may run under the Windows operating system, but has not been tested on a Windows platform.
2. A copy of IDL at version 6.2 or later. This can either be a fully licensed copy, or the IDL VM, the freely available virtual machine. Download either from ITTVIS.
3. A compiler for C source, typically gcc, or whatever the IDL routine MAKE_DLL looks for (usually available by default).

Note that running CUBISM from the binary ‘.sav’ file under the free IDL VM does not give you access to an IDL command line, so that only the graphical interface to CUBISM is accessible. With this setup, no analysis can be performed at the command line, though all files, including spectra, maps, and cubes can be output as normal. Running the binary distribution of CUBISM in a licensed version of IDL does not prevent access to the command line.

To install the binary version of CUBISM, simply unpack the ‘cubism_vX.XX_bin.tgz’ file (where ‘X.XX’ is the version number) in a directory on the IDL path (or anywhere else).

2.3 Setup

CUBISM needs very little setup. As long as the binary or source directory structure is left intact, CUBISM automatically discovers all the necessary calibration and other files needed.

One basic setup issue relates to the color mode. By default, IDL uses DECOMPOSED color, in which the RGB value of pixels is directly specified, whereas CUBISM (and most astronomy software) relies on color table indices to specify color. To switch modes, try adding the following to the IDL startup file specified with the environment variable IDL_STARTUP:

device,DECOMPOSED=0,TRUE_COLOR=24,RETAIN=2

You may not need the RETAIN=2 setting depending on your window manager (this forces IDL to keep track of the contents of windows when they need to be redrawn, and is typically required under Linux). The binary distribution of CUBISM performs this operation by default.

Another potential issue relates to the IDL_PATH. If you have a source distribution of CUBISM, you will need to ensure that the directories containing CUBISM as well as the AstroLib installation are on your IDL_PATH. In principle it should not matter where on the path CUBISM is. However, occasionally two different packages will each define the same routine in two files with the same names (a so-called name space conflict). If you encounter this problem, move the directory containing CUBISM higher on your IDL_PATH, or use the binary distribution, which doesn't suffer such name space conflicts.

2.4 Memory Requirements

CUBISM is designed to take advantage of the large memory sizes available on modern computers. Rather than load a small amount of data from disk, operate on it, and return it to disk (e.g. as IRAF might do), CUBISM attempts to keep most data in memory, which enables a variety of features which would not be possible with caching to disk.

For modest sized cubes (with fewer than 100 BCDs contributing), this is not a burden. For very large cubes (many hundreds to many thousands of records), CUBISM's use of roughly 0.5–2MB per record (at maximum) requires at least 1–2GB of RAM to avoid loss of performance. CUBISM can work with large projects using less memory, but performance will suffer dramatically as data is paged to disk. Note that data is loaded on demand, so for instance, viewing a pre-built cube without reloading record data will consume only a small amount of memory.

2.5 Running

How CUBISM is run depends on how it was installed.

2.5.1 Running the Source Distribution

For source distributions, after installation on your IDL path, simply type:

IDL> cubism

and you are prompted to select an existing saved cube project, or create a new one.

2.5.2 Running the Binary Distribution

Running the pre-compiled binary version of CUBISM can be accomplished by putting the ‘cubism_vm.sav’ file in your IDL path and using:

IDL> cubism_vm

Another option allows you to run this binary file from anywhere, not necessarily on your IDL path:

IDL> restore,'/path/to/cubism/bin/cubism_vm.sav'
IDL> cubism

You can also run the compiled file in the free IDL VM, which does not require an IDL license:

% idl -vm=/path/to/cubism_vm.sav

MacOSX users can accomplish the same thing by optionally using the precompiled wrapper ‘Cubism.app’ application: simply double-click (or double-click a ‘.cpj’ CUBISM project file). Note that even under OSX, CUBISM runs as an X11 application, and that ‘Cubism.app’ is simply a wrapper to start IDL in the VM and load CUBISM.

2.6 Upgrading

Upgrading CUBISM is simple and requires replacing the source or binary installation directories with the newer version and restarting IDL. You can always find out what version of CUBISM you are running with the menu Help->About Cubism in the project window. New versions of CUBISM are available at http://sings.stsci.edu/cubism.

This document was generated by JD Smith on July, 14 2009 using texi2html 1.78.