SSJ

Stochastic Simulation in Java

SSJ is a Java library for stochastic simulation, developed under the supervision of Pierre L'Ecuyer in the Department of Computer Science and Operations Research at Université de Montréal. It provides facilities for:

random number and random variate generation
stochastic process simulation
discrete-event simulation
computations with several types of probability distributions
randomized quasi-Monte Carlo methods
collecting and reporting statistics from simulations
goodness-of-fit tests
and much more.

Starting from version 3.1.0, SSJ is released under the Apache 2.0 License, and the package names have changed from umontreal.iro.lecuyer.* to umontreal.ssj.*.

Documentation and tutorial

The SSJ User's Guide includes:

the API documentation; and
a tutorial with documented examples.

Installation

You can install SSJ either by adding it as a dependency for your Maven- or Gradle-based project, by downloading a binary release or by compiling it from scratch.

SSJ is compatible with Java SE8 and later versions of Java. It requires the Java Development Kit (JDK), whose latest version is available at Oracle with installation instructions. It must be installed before installing SSJ.

It is also useful to install an integrated development environments (IDE) such as Eclipse, NetBeans, IntelliJ IDEA, for example, to write, compile, and run your Java code.

Using Maven

(Simplest approach)

SSJ packages are hosted on Bintray and on Maven Central. If your Java project uses Maven or Gradle, all you need to do is add ca.umontreal.iro.simul:ssj:+ to the Maven dependencies of your project, then you can start working on your SSJ-based project right-away.

IDE integration

Most IDEs support Maven. In Eclipse, NetBeans, or IntelliJ IDEA, for example, it suffices to create your project as a Maven project instead of a Java project.
After creating your project, add SSJ to its Maven dependencies (refer to your IDE documentation), with the following parameters:

Group Id: ca.umontreal.iro.simul;
Artifact Id: ssj;
Version: any valid release number for SSJ, e.g., 3.3.2,

and you are ready to go!

In Eclipse, for example, click: File -> New -> Project -> Maven -> Maven Project. Click the box "Create a simple project", then Next. In the next window, enter whatever names you want, such as:

Group Id: UdeM;
Artifact Id: mesdevoirs;
Version: 0.0.1-SNAPSHOT;
Packaging: jar;
Name: mesdevoirs-ift6561;
Description: Code Java pour mes devoirs de IFT6561;
Parent project: Leave empty; Then Finish.

After that, right-click on the new project name mesdevoirs and click on Maven -> Maven Dependencies and add the SSJ dependency as mentioned earlier:

Group Id: ca.umontreal.iro.simul;
Artifact Id: ssj;
Version: 3.3.2.

If you want to use other Maven Java libraries than SSJ in your code, just add them in the same way. For example, if you want to use the tools of jfreechart (used inside SSJ) directly in your code, you can add the dependency:

Group Id: org.jfree;
Artifact Id: jfreechart;
Version: 1.5.3

All the dependencies will appear in the pom.xml file of your project. You can also edit this xml file directly if you prefer.

Binary releases

For those who want to download the binaries and install them manually, we provide below some general instructions for configuring a project to use SSJ.

Download a binary archive

Pre-compiled binaries are available as archives on the releases page. They include:

the main SSJ JAR file (under ssj/lib);
JAR files for the Java libraries used by SSJ (the dependencies) (under ssj/lib);
dependencies and the JNI shared libraries (under the ssj/lib directory);
the user's guide (under ssj/doc/html); and
example source files (under ssj/doc/examples).

You can download the latest archive and extract the files in a location of your choice.

Set the Java class path

You add to the Java class path every JAR file found under the ssj/lib directory of the binary archive.

On the command line

If you use Java from the command line, add the full path of every JAR file under ssj/lib to the CLASSPATH environment variable, separated with : under Linux or MacOS, or by ; under Windows. Means of doing this depends on the system you are using. For example, under Linux with a Bash-compatible shell, one could use something like:

for f in /full/path/to/ssj/lib/*.jar; do
    CLASSPATH=$f:$CLASSPATH
done
export CLASSPATH

In Eclipse

In Eclipse, under Window â€£ Preferences â€£ Java â€£ Build Path â€£ User Libraries, click Newâ€¦. Set the name to SSJ and click OK. Click Add External JARsâ€¦ navigate to the ssj/lib folder of the extracted binary archive, select all JAR files, and click OK. You can now add the SSJ library you have created from any project, by right-clicking on your project name in the Package Explorer, by selecting Build Path â€£ Add Librariesâ€¦ â€£ User Library under your project tree and by choosing SSJ.

In NetBeans

In NetBeans, under Tools â€£ Libraries, press New Libraryâ€¦. Set the name to SSJ and click OK. Click Add JAR/Folderâ€¦, navigate to the ssj/lib folder of the extracted binary archive, select all JAR files, and click Add JAR/Folder. You can now add the SSJ library you have created from any project, by right-clicking on Libraries under your project tree in the Projects tab and by choosing SSJ.

Compiling the source code

You do not need to compile the source code to use SSJ if you have already installed it using Maven or a binary release. But in case you want to change the source for some reason, here is how you can recompile.

The SSJ library uses Gradle as its build system. You do not need to download it, since the Gradle wrapper executable program is provided with the source code as the gradlew file for Linux and MacOS platforms, and as gradlew.bat for Windows platforms. The build.gradle and gradle.properties files at the root of the source tree contain the configuration for Gradle. In the instructions below, Windows users should replace instances of ./gradlew with gradlew.bat.

SSJ and the current Gradle version work with Java SE (or JDK) version 8 or later.

Using Gradle

The general syntax for Gradle is ./gradlew <task> where <task> is the name of a Gradle task (run ./gradlew tasks to obtain a list of available tasks).

On the command line, from the root of the source tree, type:

./gradlew check to build and test the library;
./gradlew examples (optionally) to run additional examples;
./gradlew distZip or ./gradlew distTar to create an binary archive of the SSJ library, including the SSJ JAR file and its dependencies;
./gradlew --gui to launch the Gradle graphical user interface and choose from more options.

All files generated during the build process are placed under the build subdirectory. The generated binary archives can be found under build/distributions.

Building the documentation

(Optional)

The SSJ library uses Doxygen as its documentation system. If Doxygen is available on your system, you can build the documentation simply with the command doxygen from the main ssj directory. The html documentation will be built in the directory ssj/build/docs/html.

You can also tell Gradle to build the documentation by adding line

buildDocs

in gradle.properties, then run Gradle as explained above. Before that, you may want (or need) to change some Doxygen environments variables in the file Doxyfile.

JNI classes