Installing SSJ on Linux, Unix or Mac Os X

These installation instructions should apply for any UNIX variant on which Java 5 or later is available. We include specific instructions for GNU/Linux, and Apple's Mac OS X.

The installation is a three-steps process: install a Java Virtual Machine, unpack SSJ, and set up the environment. This page shows these steps in more details. Note that if SSJ is already installed, an update can be performed simply by unpacking the new version at the same location as the old version. There is no need to redo the Java installation and environment setup.

Valid XHTML 1.0 Strict

Requirements

SSJ requires a Java 2 Virtual Machine.

All the following packages are already included in the SSJ distribution:

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 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. 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. It is used only in the probdist package to compute maximum likelihood estimators.

The JFreeChart library is used by the SSJ package charts to draw curves, histograms and different kinds of plots. JFreeChart is copyrighted under the GNU LGPL License. It is included in the SSJ distribution as the jfreechart-1.0.10.jar and the jcommon-1.0.13.jar.

The UNURAN library is used by the classes UnuranContinuous, UnuranDiscrete, and UnuranEmpirical in package 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.


Installing a Java Virtual Machine

Before using SSJ, one should install a Java Virtual Machine (JVM) which is needed to execute any Java program. The recommended JVM is Oracle's Java Runtime Environment, and can be found on the Oracle's Java SE downloads page. It is sufficient to download and install JRE for using precompiled programs, but JDK is necessary for programming using the SSJ library. On Mac OS X, however, one must use the Apple's JVM.

Testing if Java is already installed

One might test the installation of Java using a console. A console can be accessed several ways on GNU/Linux. For example, the GNOME Terminal can be accessed from GNOME by using the Terminal command in menu Applications, submenu Accessories. This opens a window allowing the user to type commands. On Mac OS X, the Terminal can be accessed by switching to the Finder, and double-clicking on the icon representing the hard drive (named Macintosh HD), the Applications folder, the Utilities subfolder, and the Terminal icon, in that order. The Utilities subfolder can also be accessed by pressing the keys Shfit, Command, and U simultaneously while the Finder is active.

The console runs a shell which accepts commands corresponding to program names with arguments, separated by spaces. After writing any command on the console, the user needs to press the Enter key to execute it. The command java -version may be used to verify that the Java Virtual Machine is properly installed. Here, the program name is java while -version is an argument passed to the java program. The above command should produce an information message similar to the following one.

java version "1.6.0"
Java(TM) SE Runtime Environment (build 1.6.0-b105)
Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode, sharing)

The displayed version should be at least be 1.5.0. Java is not properly installed on the system if the above command produces an error message indicating that java is not a recognized command.

The command javac can also be used to test if a Java compiler is properly installed. It should display a message similar to Usage: javac <options> <source files>, followed by the list of allowed arguments.

The exit command can be used to leave the console.

Installing or updating Java

For some GNU/Linux distributions, Java can be installed easily by using the builtin package manager. For example, with Ubuntu 7.04 and newer versions, the user simply needs to install the sun-java6-jdk package using the Synaptic package manager, or the apt-get command. The user might also have to type the command sudo update-java-alternatives -s java-6-sun on a console to set the default VM to Oracle's rather than to GCJ. Using such an automated procedure to install JDK is recommended.

The Apple's version of the JDK is integrated into Mac OS X, and an update to Java often requires an upgrade of the operating system. In particular, Java 5 is only available through an update compatible with Mac OS X 10.4 (also named Tiger). Java 5 is integrated with Mac OS X 10.5 (named Leopard), while Java 6 is available as an update. Java for these versions of Mac OS X is available on Apple's Web site.

If JDK is not available as a package for one's GNU/Linux distribution, or if a more recent JDK than the one offered by the Linux distribution is needed, the manual installation procedure can be used. The following steps summarizes this generic installation process for the Oracle's JVM. The Web site Installation Notes provides detailed instructions for installing Java on GNU/Linux.

  1. Go to Oracle's Java SE downloads page.
  2. Click on the Download button next to JDK.

    This should correspond to the first Download button on the page.

  3. Select Linux as the Platform.

    If the command uname -m displays x86_64, one should instead select Linux x64 as the platform.

  4. Click on the check box to accept the license agreement.
  5. Click on the Continue button.
  6. Click on the link corresponding to the self-extracting file.
  7. Save the downloaded file on the hard disk.

    For example, the file can be called /tmp/jdk-6u2-linux-i586.bin.

  8. On a console, type the following commands as root.
    mkdir /usr/local/java
    cd /usr/local/java
    chmod a+x /tmp/jdk-6u2-linux-i586.bin
    /tmp/jdk-6u2-linux-i586.bin
    

    One may need to adapt the filenames and directories. It can also be necessary to prefix every line with sudo followed by a space to run the commands as root.

  9. Modify startup scripts to add the bin subdirectory in the PATH environment variable.

    For example, with Fedora Core, this can be done by creating a /etc/profile.d/java.sh file with contents

    #/bin/sh
    
    export JAVA_HOME=/usr/local/java/jdk1.6.0_02
    export PATH=$JAVA_HOME/bin:$PATH

    The path assigned to JAVA_HOME must be replaced with the true location of the JDK. For Ubuntu, this must be added to /etc/bash.bashrc.


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/local/java, the base directory of SSJ will be /usr/local/java/ssj.

Alternatively, any graphical Unzip utility such as File Roller might be used to unpack SSJ.

Note: If the library is unpacked by the root user to be installed for every user on a machine, the root user may need to adjust file permissions.


Setting up the environment

When using SSJ or any other third-party Java library, the user needs to tell Java how to locate the classes forming the library by configuring the CLASSPATH environment variable. Environment variables are properties passed implicitly to any executed program, including the Java Virtual Machine. The procedure to set these variables depends on the used shell. Most recent distributions of GNU/Linux and Mac OS X use Bash by default, which is a kind of Bourne shell. Several UNIX flavors also use some types of Bourne shell. Older UNIX and GNU/Linux systems use C-Shell by default.

The echo $SHELL command can be used to obtain the currently used shell.

To use SSJ, the ssj.jar and the colt.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. Moreover, for the native methods (GlobalCPUTimeChrono and UNURAN support) to work properly, the PATH environment variable must include the lib subdirectory of the SSJ package (however, few users need to care about this as there are Chrono classes that are programmed directly in Java and only a few classes need UNURAN). 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
  

These lines must be added in the .cshrc file in the user's home directory. If the file (or its equivalent) does not exist, it must be created and include the above lines. Here, <path to SSJ> must be replaced by the absolute path to the unpacked ssj subdirectory.

Commands for the Bourne shell

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

These lines must be added in the .bashrc file in the user's home directory. If the file does not exist, it must be created and include the above lines. Here, <path to SSJ> must be replaced by the absolute path to the unpacked ssj subdirectory.

On Mac Os X, if none of the files .bash_profile, .bash_login, .profile exist in the user's home directory, then one of them should be created and include the line

   if [ -f ~/.bashrc ]; then
      . ~/.bashrc
   fi

Note on Java IDEs

Some Java Integrated Development Environments (IDEs) such as Eclipse and NetBeans 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 complicated mathematical formulae do not display properly. 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.