Stochastic Simulation in Java
SSJ is a Java library for stochastic simulation, developed under the supervision of Pierre L'Ecuyer in the Simulation and Optimization Laboratory, 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
Documentation and tutorial
The SSJ User's Guide includes:
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.
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.
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:
- Artifact Id:
- Version: any valid release number for SSJ,
and you are ready to go!
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. Less experienced users can find more detailed instructions on the SSJ page.
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
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
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
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.
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
SSJ and the current Gradle version work with Java SE (or JDK) version 8 or later.
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. You may want (or need) to change some Doxygen environments variables in the file Doxyfile.
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.