Installation

Fast installation

If you want to only feel Breeze and give it a chance and you don't want to bother with installation, run sbt, configure a new project and run interactive console:

$ sbt
set scalaVersion := "2.13.3"
set libraryDependencies += "org.scalanlp" %% "breeze" % "1.1"
set libraryDependencies += "org.scalanlp" %% "breeze-viz" % "1.1"
set resolvers += "Sonatype Releases" at "https://oss.sonatype.org/content/repositories/releases/"
console

That's all! Now, you can go to Quickstart or read the instruction for recommended installation way:

Recommended installation

We assume, that you have installed SBT 0.13.x or later. Add these lines to your SBT project definition:

libraryDependencies  ++= Seq(
  // other dependencies here
  "org.scalanlp" %% "breeze" % "1.1",
  // native libraries are not included by default. add this if you want them (as of 0.7)
  // native libraries greatly improve performance, but increase jar sizes. 
  // It also packages various blas implementations, which have licenses that may or may not
  // be compatible with the Apache License. No GPL code, as best I know.
  "org.scalanlp" %% "breeze-natives" % "1.1",
  // the visualization library is distributed separately as well. 
  // It depends on LGPL code.
  "org.scalanlp" %% "breeze-viz" % "1.1"
)

scalaVersion := "2.13.3"

Then run sbt update so SBT will download them from maven central.

Maven

Maven looks like this:

<dependency>
  <groupId>org.scalanlp</groupId>
  <artifactId>breeze_2.12</artifactId> <!-- or 2.13 -->
  <version>1.1</version>
</dependency>

Other build tools

http://mvnrepository.com/artifact/org.scalanlp/breeze_2.13/1.1 (as an example) is a great resource for finding other configuration examples for other build tools.

Enabling Native Code

Underneath the hood, Breeze uses netlib-java for its linear algebra routines. Netlib-java can be configured with a variety of underlying calculation libraries, and these affect your ultimate performance. From fastest to slowest, your possible strategies are:

1. Native, machine-optimized, system libraries (e.g. .so; .dll);

2. Java wrapper around the (Fortran) reference implementation of netlib;

3. A pure-Java implementation of netlib; this is based on the F2J Fortran-to-Java transpilation tool.

See the netlib-java repo for more information.

FAQ: if you are on Linux and having trouble getting native libraries to work, make sure libgfortran3 is installed. (e.g. apt-get install libgfortran3)

Windows and MKL

Intel provides a netlib-compatible system library called Intel Math Kernel Library - MKL. MKL is a commercial product but free licensing is available for non-commercial use. Here is how to setup MKL as the underlying native engine under Windows:

1. Download and install MKL;

2. Locate the folder containing the relevant (64-bit or 32-bit) DLLs - e.g. C:\Program Files (x86)\IntelSWTools\compilers_and_libraries\windows\redist\intel64_win\mkl - and add this to your PATH;

3. Ensure that you have an sbt library dependency on the breeze-natives library;

4. Add -Dcom.github.fommil.netlib.NativeSystemBLAS.natives=mkl_rt.dll to your JVM startup script - note that this file is found in the location of your PATH entry;

5. Write and run test Scala code as below.

build.sbt:

name := "Breeze1"
version := "1.0"
scalaVersion := "2.11.8"
libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.1" % "test"
libraryDependencies += "org.scalanlp" % "breeze_2.11" % "0.12"
libraryDependencies += "org.scalanlp" % "breeze-natives_2.11" % "0.12"
libraryDependencies += "org.slf4j" % "slf4j-api" % "1.7.22"
libraryDependencies += "org.slf4j" % "slf4j-simple" % "1.7.22"
resolvers += "Sonatype Releases" at "https://oss.sonatype.org/content/repositories/releases/"
fork in run := true
fork in test := true
javaOptions in run += "-Dcom.github.fommil.netlib.NativeSystemBLAS.natives=mkl_rt.dll"
javaOptions in test += "-Dcom.github.fommil.netlib.NativeSystemBLAS.natives=mkl_rt.dll"

Breeze1.scala:

import breeze.linalg.DenseVector
import com.github.fommil.netlib.BLAS
import org.slf4j.LoggerFactory

object Breeze1 {
  def main(args:Array[String]): Unit = {
    println("Init logging...")
    System.setProperty(org.slf4j.impl.SimpleLogger.DEFAULT_LOG_LEVEL_KEY, "TRACE");
    val log = LoggerFactory.getLogger("main")
    log.trace("Starting...")
    val b = BLAS.getInstance()
    log.trace(s"BLAS = $b")
    val v = DenseVector(1,2,3,4)
    log.trace("Ending.")
  }
}

If mkl is successfully enabled, you should see console logging which includes the following:

Dec 30, 2016 2:48:21 PM com.github.fommil.jni.JniLoader liberalLoad
INFO: successfully loaded C:\Program Files x86)\IntelSWTools\compilers_and_libraries\windows\redist\intel64_win\mkl\mkl_rt.dll
[main] TRACE main - BLAS = com.github.fommil.netlib.NativeSystemBLAS@2d554825

Building Breeze

You should not need to build Breeze yourself but in the case you do, here are the steps:

Breeze is hosted on github and is built with sbt.

Set up sbt following their instructions, and then run sbt. The following targets are useful:

• compile -- Builds the library
• test -- Runs the unit tests
• doc -- Builds scaladoc for the public API
• publish-local -- Copies jars to local Ivy repository.
• assembly -- Builds a distributable jar
• console -- starts a scala repl

Note: you might need more than the default amount of memory to get Breeze to build. The following environment variable is known to work well:

export SBT_OPTS="-Xmx3g -XX:+CMSClassUnloadingEnabled -XX:PermSize=256M -XX:MaxPermSize=512M"