Installing SSJ on Windows

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.

Testing if Java is already installed

One might test the installation of Java using the DOS prompt. For Windows 2000/XP/Vista, the DOS prompt can be accessed by Start menu, All programs, Accessories, DOS Prompt. On older versions of Windows, the DOS prompt is accessible in the Programs submenu of the Start menu. This opens a black window in which the user can type text.

See How to get to a MS-DOS prompt if the DOS prompt cannot be reached from the Start menu.

The DOS prompt accepts commands corresponding to program names with arguments, separated by spaces. After writing any command on the DOS prompt, 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 DOS prompt.

Installing or updating Java

The following steps summarizes the installation process for the Oracle's JVM. The Web site Installation Notes provides detailed instructions for installing Java on Windows.

  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 Windows as the Platform.

    If a 64-bits version of Windows XP or Windows Vista is used, one should instead select Windows 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 Windows offline installation.
  7. Save the downloaded file on the hard disk, and execute it.
  8. Follow the on-screen instructions for installation.

For the Java compiler, i.e., javac, to be accessible from a DOS prompt, the bin subdirectory of the JDK must be part of the PATH environment variable. For this, see the Oracle's Installation Notes, or below.


Unpacking

First, by using WinZip or any equivalent program, the user needs to unpack the ZIP file ssj-<DATE>.zip to any location; this will create a ssj subdirectory containing all files of the distribution. For example, if the files are unzipped in C:\Program Files\java, the base directory of SSJ will be C:\Program Files\java\ssj.

Note: Under Windows 2000/XP, a system administrator installing SSJ for every user on a machine or a network might need to alter permissions to make the SSJ directory and its files readable by everyone.


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. Moreover, for the native methods (GlobalCPUTimeChrono and UNURAN support) to work properly, the PATH environment variable must include the lib subdirectory of SSJ (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). Altering the PATH variable is also necessary to make javac, java, and javadoc commands easily accessible from the DOS Prompt. Environment variables are properties passed implicitly to any executed program, including the Java Virtual Machine. The procedure to set these variables depends on the operating system used, and the privileges of the user.

Windows 2000/XP/Vista

Under Windows 2000/XP/Vista, the environment variables must be set manually because there is no startup file.

  1. The System Properties must be accessed by right-clicking on the My Computer icon and selecting Properties. This pops up a dialog box with multiple tabs and caption System Properties.

    The properties may also be accessed by pressing the Windows and Pause keys simultaneously, or double-clicking on the System icon in the Control Panel (in classic view).

  2. From this dialog box named System Properties, the user can access the environment variables by selecting the Advanced tab and clicking on the Environment Variables button that comes up.

    Under Windows Vista, these advanced options can be accessed by clicking on the Advanced system parameters menu item, in the left part of the System Properties dialog box. If a dialog box asking user's authorization pops up, the user must click on the Continue button. The Environment Variables button is then accessible.

    This creates a new window with two lists. The upper list shows the user variables, while the lower list displays the system variables. A user having the Administrator privilege (most home users) can modify the system variables to install SSJ for everyone on the machine while a user with a limited account (most users in a business or a university) can only modify his user variables to install SSJ for himself.

    Here, we assume that the user is Administrator, and installs SSJ for every user of his machine. See below for a procedure that can be applied to users with limited accounts.

  3. The user should create the SSJHOME variable by using the New button below the list of system variables. This pops up a new window prompting the user to enter a variable name along with its value. The text SSJHOME must be entered as the variable name while the value of the variable must be the base directory of the SSJ distribution, e.g., C:\Program Files\java\ssj. The Ok button must be used to close the dialog box, and create the variable. The SSJHOME variable now appears in the list of system variables.

    Tip: the directory name might be copy/pasted from an open Explorer window to avoid error-prone typing.

  4. The user should create the JAVA_HOME variable the same way as SSJHOME. This variable should give the location of the JDK, e.g., C:\Program Files\Java\jdk1.6.0_07.

  5. The CLASSPATH variable must then be edited or created. This variable is a semicolon-separated list of paths being searched by the Java Virtual Machine for classes.

  6. The PATH variable must then be edited. This variable is a semicolon-separated list of paths being searched by Windows when a program or shared library is loaded.

    After the PATH variable is selected in the list of system variables, the user must click on the Edit button, unselect the contents of the value, and append the string ;%SSJHOME%\lib;%JAVA_HOME%\bin to the value.

  7. Every dialog box opened for this procedure can be closed with their Ok button to validate the performed changes.

Changes to the environment variables apply to newly-launched programs only. As a result, if a DOS prompt was active during the setup, it will have to be closed and reopened to access SSJ classes.

Users without administrative privileges

Users without administrative privileges cannot create or edit system environment variables. However, they can create user variables that override system variables when they log on. The only exception to this rule is the PATH variable whose contents is composed of the system and user variables, separated by a semicolon. Consequently, a user with a limited account may apply the following variants to the above procedure.

Windows 95/98/Me

For Windows 95/98/Me, batch files are available to setup the environment for the user. The SSJHOME environment must be set prior to calling the setup batch file. For the Java compiler, the JAVA_HOME variable must also be set up.

Commands for Windows 9x/Me:

   set SSJHOME=<path to SSJ>
   set JAVA_HOME=<path to the JDK>
   set PATH=%PATH%;%JAVA_HOME%\bin
   call %SSJHOME%\Ssj.bat

Here, <path to SSJ> must be replaced by the absolute path to the unpacked ssj subdirectory, for example C:\Program Files\java\ssj. Moreover, <path to the JDK> must be replaced by the absolute path to the JDK, i.e., C:\Program Files\Java\jdk1.6.0_07.

For SSJ to be always available, the above command lines should be added to C:\autoexec.bat file. The computer will have to be restarted for changes in this configuration file to take effect.

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.