Installing SSJ on Linux or Unix

Requirements

SSJ requires a Java 2 Virtual Machine.

The Colt library is used by a few SSJ classes. The library, its source code and documentation, can be downloaded for free from its home page. The colt.jar archive is already included in the SSJ distribution and it must be in the CLASSPATH environment variable.

The UNURAN library is used by the class UnuranContinuous, UnuranDiscrete, and UnuranEmpirical in the package called randvar. It can be downloaded for free from its home page. Downloading, compiling and installing UNURAN is optional. It is required only if SSJ must be rebuilt. However, the UNURAN documentation is required to use the SSJ UNURAN interface efficiently.

The linear_algebra library is based on public domain LINPACK routines. They were translated from Fortran to Java by Steve Verrill at the USDA Forest Products Laboratory. This software is also in the public domain and is included in the SSJ distribution as the Blas.jar archive, which must be in the CLASSPATH environment variable. It is used only in the probdist package to compute maximum likelihood estimators.

The optimization package of Steve Verrill includes Java translations of the MINPACK routines for nonlinear least squares problems as well as UNCMIN routines for unconstrained optimization. They were translated from Fortran to Java by Steve Verrill and are in the public domain. They are included in the SSJ distribution as the optimization.jar archive, which must be in the CLASSPATH environment variable. It is used only in the probdist package to compute maximum likelihood estimators.

Unpacking

The user must unpack the ZIP file to any location with the command

   unzip ssj-<DATE>.zip

This will create a ssj subdirectory containing all files of the distribution in the current directory. For example, if the command is called while the current directory is /usr/java, the base directory of SSJ will be /usr/java/ssj.

Set up the environment

To use SSJ, the ssj.jar, colt.jar, Blas.jar and optimization.jar archives, located in the lib subdirectory of the package, must be part of the CLASSPATH environment variable. This variable is a colon-separated list of paths being searched by the Java Virtual Machine for classes. For the native methods (Chrono and UNURAN support) to work properly, the library path must include the lib subdirectory of the SSJ package. Under UNIX/Linux, this can be done by modifying the LD_LIBRARY_PATH environment variable. For convenience, the following scripts are available to setup the environment for the user (the SSJHOME environment variable must be set prior to calling the setup script):

Commands for the C-shell:

   setenv SSJHOME <path to SSJ>
   source $SSJHOME/Ssjrc

Commands for the Bourne shell:

   export SSJHOME=<path to SSJ>
   . $SSJHOME/Ssj.sh

Here, <path to SSJ> must be replaced by the absolute path to the unpacked ssj subdirectory, for example /usr/java/ssj. The command lines should be added to an appropriate startup script for convenience.

Note: Some Java Integrated Development Environments (IDEs) such as Eclipse do not use the standard CLASSPATH environment variable. These environments must be notified about the location of colt.jar and ssj.jar manually. The procedure used to set these parameters can be found in the documentation of the specific Java IDE. If the archives cannot be located, the SSJ programs will not compile or not execute properly.

Documentation

SSJ is bundled with documentation in PDF and HTML formats. It can be found in the $SSJHOME/doc directory. The html subdirectory contains the HTML version processed using Javadoc. It allows to find classes and methods documentation easily, but it is difficult to print and some information is missing. It can be viewed by opening index.html in any Web browser.

The PDF documentation, stored in the pdf subdirectory, can be easily printed using Adobe Reader or any other PDF viewer. It is the most complete documentation, but method descriptions are not accessible through hyperlinks.

The examples subdirectory contains examples of simulation programs using SSJ and can be a useful tool to learn SSJ.