SciSim 4.0 Installation

Contents

These instructions cover the installation of SciSim. For latest information about installation, you may also visit the on-line documentation.

• Binary installation
• Source installation
• Catalogues
• Documentation
• Uninstall
• Upgrade

Binary installation

• Requirements
• Installation
• Environment
• Installation test
• Trouble shooting

Requirements

Binary distributions of SciSim are available on-line for download, and created on the following platforms:

• Linux (ELF) on PC using the RedHat 9.0 and RedHat Enterprise distributions.
• Linux (ELF) on PC using the SuSe 8.2 distribution.
• Solaris 2.6 and 2.8 on Sun Sparc.

Installation

We assume that you want to install SciSim in /usr/local/scisim-x.y.z. After downloading, you should unpack the compressed distribution with the command:

    $ cd /usr/local
    $ gunzip -c scisim-x.y.z.tgz | tar xf -
  

Environment

In order to run SciSim you need to define the following environment variables:

• SCISIM_DIR - location of the distribution
• SCISIM_PATH - [optional] alternative directories to look for additional data. By default it is set to the current directory.

Assuming we have installed SciSim in /usr/local/scisim-x.y.z, you should specify:

tcsh / csh:

    > setenv SCISIM_DIR /usr/local/scisim-x.y.z
    > source $SCISIM_DIR/setup
  

ksh / bash / sh:

    $ SCISIM_DIR=/usr/local/scisim-x.y.z
    $ export SCISIM_DIR
    $ . $SCISIM_DIR/setup.sh
  

You may also add these commands to your .login (for csh or tcsh) or .profile (for sh, bash or ksh).

Installation test

After you have gone through the steps above, you should be able to start-up SciSim in a directory with write-access:

    $ mkdir $HOME/tmp
    $ cd $HOME/tmp
    $ scisim
  

A Graphical User Interface (Window) of SciSim will appear.

Trouble shooting

If the above does not work, your system may not have the appropriate shared libraries (e.g. Qt). For this reason, you can download extra packages of the form: scisim-x.y.z-libextern.tgz.
You should download and unpack these packages as described for the SciSim's core binary distribution:

    $ cd /usr/local
    $ gunzip -c scisim-x.y.z-libextern.tgz | tar xf -
  

<< Go to top of the page

Source installation

• Requirements
  • Platforms and Operating systems
  • Software
  • Environment
• Configuration
• Building

Requirements

We build SciSim across several platforms on a daily basis.

Platforms and Operating systems

The following platforms are involved:

• Sun Sparc Ultra running Solaris 2.6
• Sun Sparc Ultra running Solaris 2.8
• i686 running RedHat 9.0
• i686 running RedHat Enterprise
• i686 running SuSe 8.2

Software

Next to basic UNIX facilities (bash,sh,csh,cp,mkdir,grep,sed etc...), you will need:

• GNU GCC 3.2.x or 3.3.x
• NAGWare Fortran 95 compiler Release 4.2
• GNU Make 3.79.1 or higher
• Perl 5.005, 5.6 or higher
• Trolltech Qt3 library
• HEASARC CFISTIO 2.4.x library or higher
• LaTeX2HTML 2K.1 or higher
• Documentation generators, such as latex,dvips,gs
• System assembler archiver and linker (as,ar,ld); preferably the GNU binutils equivalent.

Except for the commercial f95 compiler, ready made binary distributions are available for most systems:

• RedHat and Rpmfind (Linux)
• SuSe (Linux)
• Sun Freeware (Solaris 2.x)

Environment

The following environment variables are used when running SciSim:

• PATH - directories that contain all programs needed
• CPLUS_INCLUDE_PATH - inclusion of the Qt and CFITSIO headers at C++ compile stage
• C_INCLUDE_PATH - inclusion of the CFITSIO headers at C compile stage
• LIBRARY_PATH - lookup path for libraries needed at linking stage of the build
• LD_LIBRARY_PATH - lookup path for libraries needed at run-time
• COMPILER_PATH - [optional] lookup path for pre-installed GCC, in order to pick up GNU binutils instead of native ld, as etc... (necessary for Sun Solaris)

For example, a PC running RedHat 9.0 is using the following environment:

  PATH=/usr/local/f95/bin:/usr/lib/qt-3.1/bin:/usr/local/bin:/bin:\
       /usr/bin:/usr/X11R6/bin:/sbin:/usr/sbin
  LD_LIBRARY_PATH=/usr/lib/qt-3.1.2/lib
  LIBRARY_PATH=/usr/local/f95/lib:/usr/local/cfitsio-2.430/lib:/usr/lib/qt-3.1.2/lib
  CPLUS_INCLUDE_PATH=/usr/lib/qt-3.1.2/include:/usr/local/cfitsio-2.430/include
  C_INCLUDE_PATH=/usr/local/cfitsio-1.42
  

Configuration

You will need to build SciSim in a separate build directory. For example, if the unpacked source directory is $HOME/tmp/scisim-src, create a directory $HOME/tmp/scisim-obj to put the object files in. This allows you to remove the whole build directory in case an error occurs.

From your object directory, run the shell script configure found in the platform directory of the source tree. In the example above, you'd type:

     $ ../scisim-src/platform/configure
  

configure can take quite a few options, but most important is --prefix.
The --prefix option tells configure where you want SciSim installed. By default this is $HOME/tmp/scisim, but it can be anything:

     $ ../scisim-src/platform/configure --prefix=/usr/local/scisim-x.y.z
  

If configure does not end properly, you're are missing one or more of the prerequisites.

Building

To build the library and related programs, type:

     $ make
  

You can build the documentation with:

     $ make doc
  

The source distribution is accompanied with test programs. You can run them with the command:

     $ make test
  

If make bails out with an error, something is wrong. Otherwise your build is successful.

<< Go to top of the page

Catalogues

SciSim is able to work with some Start Catalogues. It is able to extract sources from these catalogues, and use them as input to the Simulators.
If you wish to use the catalogues extraction feature, it is necessary to install and preprocess the catalogues.

The catalogues are not distributed with SciSim as they are very large. The preprocessing is needed to create fast look-up tables.
 

1. Obtain the following star catalogues:
   • WGA of ROSAT point sources (heasarc_wgacat.tdat) from Goddard Space Flight Center.
   • Tycho input catalogue (tic1, tic2, tic3 and tic4) from CDS in Strasbourg.
   • Guide Star catalogue V 1.1, which can be purchased in CDROM format from the Astronomical Society of the Pacific.
   
   
2. Install these in a suitable directory. In this example we will use /usr/local/data/catalogue for the location of all original catalogues, and /usr/local/scisim-x.y.z for the installation directory of SciSim.
   
3. Copy the init file /usr/local/scisim-x.y.z/bin/catalogue/process.ini to your working directory, and adapt it to your local settings. In our example we specify:

     OutputDir=/usr/local/scisim-x.y.z/data/catalogue
     RawWgaFile=/usr/local/data/catalogue/wga/heasarc_wgacat.tdat
     RawTicDir=/usr/local/data/catalogue/tic
     RawGscDir=/usr/local/data/catalogue/gsc/vol1
     

   If you do not have a catalogue installed, you simply uncomment that line:

     OutputDir=/usr/local/scisim-x.y.z/data/catalogue
     RawWgaFile=/usr/local/data/catalogue/wga/heasarc_wgacat.tdat
     RawTicDir=/usr/local/data/catalogue/tic
     #RawGscDir=/usr/local/data/catalogue/gsc/vol1
     

4. Preprocess the catalogues:

     /usr/local/scisim-x.y.z/bin/catalogue/process
     

5. The last step requires that SciSim can find the created lookup tables of WGA, TIC and GSC catalogues. The installer has to specify their full path in the csim_config section of /usr/local/scisim-x.y.z/config/scisim.cfg:

       gsc_regions /usr/local/scisim-x.y.z/data/catalogue/gsc.regions
       tic_data    /usr/local/scisim-x.y.z/data/catalogue/TICcat.dat
       wga_data    /usr/local/scisim-x.y.z/data/catalogue/WGAcat.dat
   

   Alternatively, users may create a file .scisimrc-3 in their $HOME directory, containing:

       begin
         csim_config begin
           gsc_regions /usr/local/scisim-x.y.z/data/catalogue/gsc.regions
           tic_data    /usr/local/scisim-x.y.z/data/catalogue/TICcat.dat
           wga_data    /usr/local/scisim-x.y.z/data/catalogue/WGAcat.dat
         end
       end
   
   

<< Go to top of the page

Documentation

SciSim comes with documentation that is accessible with an HTML-3.2 compliant browser, such as Netscape.

The SciSim 'Help' menu provides access to the on-line documentation from the Graphical User Interface. This type of excess only works with Netscape.
Note: If SciSim and Netscape are running on different machines, SciSim should be installed on a file system which is visible (i.e. mounted) on both machines.

If you use a different web browser, simply invoke the browser on file:///usr/local/scisim-x.y.z/help/help.html (depending on where you have installed SciSim). Create a hot-link so that you find it again easily.

<< Go to top of the page

Uninstall

All the SciSim files are installed in a single directory (e.g. /usr/local/scisim-x.y.z).
To uninstall it, simply delete the directory.

Don't forget to remove the environment variables!

<< Go to top of the page

Upgrade

When upgrading to a new version of SciSim, all users should delete the .scisimrc-3 file from their home directory, since there could be minor changes in format between releases.

If you want to keep multiple version of SciSim (or multiple platforms), you may want to rename the $SCISIM_DIR to indicate that  (e.g. scisim-${VERSION}-${OSTYPE}). A symbolic link "scisim" can be used to refer to the latest version.

<< Go to top of the page