Stochastic Simulation in Java
SSJ is a Java library for stochastic simulation, developed at Pierre L'Ecuyer's Simulation and Optimization Laboratory, located at the Department of Computer Science and Operations Research of Université de Montréal. It provides facilities for:
- generating uniform and nonuniform random variates;
- computing different measures related to probability distributions;
- performing goodness-of-fit tests;
- applying quasi-Monte Carlo methods;
- collecting (elementary) statistics; and
- performing event-based discrete-event simulation.
As of version 3.1.0, SSJ is released under the Apache 2.0 License.
WARNING: all package names have changed from
The SSJ User's Guide includes:
SSJ packages are hosted
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.
The following integrated development environments (IDEs) are known to support Maven (there may be more): Eclipse, NetBeans, IntelliJ IDEA. When using these, simply create your project as a Maven project instead of a Java project. Then you can add SSJ to the Maven dependencies of the project (refer to your editor's documentation), with the following parameters:
- Group Id:
- Artifact Id:
- Version: any valid release number,
SSJ is compatible with Java SE6 (JDK 6) and later versions of Java. The latest Java platform is available at Oracle with installation instructions.
We provide below very general instructions for configuring a project to use SSJ. Less experienced users can find detailed instructions on the SSJ page at the Stochastic Simulation and Optimization Laboratory.
Download a binary archive
Pre-compiled binaries are available as archives on the releases page. They include:
- the main SSJ JAR file
- JAR files for the Java libraries used by SSJ (the dependencies)
- dependencies and the JNI
shared libraries (under the
- the user's guide (under
- example source files (under
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
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
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
for f in /full/path/to/ssj/lib/*.jar; do CLASSPATH=$f:$CLASSPATH done export CLASSPATH
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, under Tools ‣ Libraries, press New Library…. Set the name to
SSJ and click OK. Click Add JAR/Folder…, navigate to the
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
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.
gradle.properties files at the root of the source tree
contain the configuration for Gradle.
Although SSJ works with Java SE versions 5 and later, the current Gradle version requires Java SE version 6 or later.
In the instructions below, Windows users should replace instances of
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 checkto build and test the library;
./gradlew examples(optionally) to run additional examples;
./gradlew distTarto create an binary archive of the SSJ library, including the SSJ JAR file and its dependencies;
./gradlew --guito launch the Gradle graphical user interface and choose from more options.
All files generated during the build process are placed under the
The generated binary archives can be found under
Building the documentation
The SSJ library uses Doxygen as its
If Doxygen is available on your system, you can tell Gradle to build the
documentation by adding the following line in
Then, run Gradle as explained above.
The classes UnuranContinuous, UnuranDiscreteInt, UnuranEmpirical and GlobalCPUTimeChrono make use of native libraries through the Java Native Interface (JNI). These libraries must be compiled with a C compiler (known to work with GCC).
Note that if you want to build and use the UNU.RAN interface provided with SSJ, you must first install UNU.RAN.
To tell Gradle to build the JNI libraries, add the following lines in
ssjutil.jni.build randvar.jni.build unuran.prefix = "/path/to/unuran"
Make sure to replace
/path/to/unuran in the above with the installation
prefix of UNU.RAN, i.e., the path under which
include/unuran.h can be found.
Then, run Gradle as explained above.
(For experts only!)
To enable cross-compilation with Gradle, add the following lines in
crossCompile unuran.prefix.linux64 = "/path/to/unuran" unuran.prefix.win32 = "/path/to/unuran-mingw32"
Make sure to replace
/path/to/unuran-mingw32 with the
installation prefixes of UNU.RAN compiled for 64-bit Linux and for 32-bit
SSJ depends on the following libraries. You do not need to download them manually if you're using SSJ with Maven or from a binary release.
If you intend to compile the source code of SSJ, Gradle will take care of downloading the Java dependencies for you. Optionally, if you want to use the UNU.RAN interface in SSJ, you need to install the UNU.RAN before compiling the associated JNI shared library in SSJ.
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 optimization package of Steve Verrill includes Java translations of the
MINPACK nonlinear least squares routines 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
X.Y.Z represents a version number.
The UNURAN library is used by the classes
UnuranEmpirical in the package called
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.