smile Documentation

Statistical Machine Intelligence & Learning Engine

SMILE (Statistical Machine Intelligence & Learning Engine) is a comprehensive,
high-performance machine learning framework for the JVM. SMILE v5+ requires
Java 25; v4.x requires Java 21; all previous versions require Java 8.
SMILE also provides idiomatic APIs for Scala and Kotlin.
With advanced data structures and algorithms, SMILE delivers state-of-the-art
performance across every aspect of machine learning.

SMILE Studio is an agentic IDE for data science using Python, Java, or Scala.
See studio/README.md how to get your first project up and
start interacting with your data with natural language in a few minutes.

Table of Contents Copy Chapter

1. Features
2. Module Map
3. Installation
   • Maven
   • SBT (Scala)
   • Gradle (Kotlin)
   • Native Libraries (BLAS / LAPACK)
4. Quick Start
5. SMILE Studio & Shell
6. Model Serialization
7. Visualization
8. License
9. Issues & Discussions
10. Contributing
11. Maintainers
12. Gallery

Features Copy Chapter

Module Map Copy Chapter

Each module has its own detailed user guide. Click the README link for
the module overview, or drill into individual topic guides.

`base/` — Foundation Copy Section

Data structures, math, linear algebra, statistical utilities, I/O

`core/` — Machine Learning Algorithms Copy Section

Classification, regression, clustering, manifold learning, and more

`deep/` — Deep Learning & LLMs Copy Section

LibTorch-backed GPU/CPU tensor operations, neural network layers, LLaMA-3 inference, EfficientNet

The deep/README.md covers:

• smile.deep.tensor — Tensor factory, indexing, arithmetic, AutoScope memory management, dtype/device
• smile.deep.layer — Linear, Conv2d, pooling, normalization (BN/GN/RMS), dropout, embedding, sequential blocks
• smile.deep.activation — ReLU, GELU, SiLU, Tanh, Sigmoid, Softmax, GLU, HardShrink, …
• smile.deep.Loss — MSE, cross-entropy, BCE, Huber, KL, hinge, and more
• smile.deep.Optimizer — SGD, Adam, AdamW, RMSprop
• smile.deep.Model — Abstract base class + training loop
• smile.deep.metric — Accuracy, Precision, Recall, F1Score with macro/micro/weighted averaging
• smile.llm — Message, Role, FinishReason, ChatCompletion records; sinusoidal & RoPE positional encodings
• smile.llm.tokenizer — Tokenizer interface, Tiktoken BPE implementation (LLaMA-3 compatible)
• smile.llm.llama — Full LLaMA-3 stack: Llama.build(), generate(), chat(), streaming via SubmissionPublisher
• smile.vision — VisionModel, ImageDataset, EfficientNet.V2S/M/L() pretrained models, ImageNet labels
• smile.vision.transform — Transform interface, ImageClassification pipeline, resize/crop/toTensor helpers

`nlp/` — Natural Language Processing Copy Section

Text normalization, tokenization, POS tagging, stemming, relevance ranking

`plot/` — Data Visualization Copy Section

Swing-based interactive plots and declarative Vega-Lite charts

`serve/` — Inference Server Copy Section

Quarkus-based REST inference service with OpenAI-compatible API and SSE streaming

`studio/` — Interactive Shell & Desktop IDE Copy Section

An agentic IDE for data science using Python or SMILE

`scala/` — Scala API Copy Section

Idiomatic Scala shim — concise wrappers, symbolic operators, Scala collections integration

`kotlin/` — Kotlin API Copy Section

Idiomatic Kotlin shim — extension functions, named parameters, builder DSLs

`json/` — JSON Library (Scala) Copy Section

Lightweight zero-dependency JSON library for Scala with a clean DSL

`spark/` — Apache Spark Integration Copy Section

Use SMILE models inside Spark ML pipelines

Installation Copy Chapter

Maven Copy Section

<dependency>
  <groupId>com.github.haifengl</groupId>
  <artifactId>smile-core</artifactId>
  <version>6.3.0</version>
</dependency>


<dependency>
  <groupId>com.github.haifengl</groupId>
  <artifactId>smile-deep</artifactId>
  <version>6.3.0</version>
</dependency>


<dependency>
  <groupId>com.github.haifengl</groupId>
  <artifactId>smile-nlp</artifactId>
  <version>6.3.0</version>
</dependency>


<dependency>
  <groupId>com.github.haifengl</groupId>
  <artifactId>smile-plot</artifactId>
  <version>6.3.0</version>
</dependency>

SBT (Scala) Copy Section

libraryDependencies += "com.github.haifengl" %% "smile-scala" % "6.3.0"

Gradle (Kotlin) Copy Section

dependencies {
    implementation("com.github.haifengl:smile-kotlin:6.3.0")
}

Native Libraries (BLAS / LAPACK) Copy Section

Several algorithms (manifold learning, Gaussian Process, MLP, some clustering)
require BLAS and LAPACK.

Linux (Ubuntu / Debian)

sudo apt update
sudo apt install libopenblas-dev libarpack2-dev

macOS (Homebrew)

brew install arpack
# If macOS SIP strips DYLD_LIBRARY_PATH, create a symlink to the dylib in your working dir:
ln -s /opt/homebrew/lib/libarpack.dylib .

Windows — pre-built DLLs are included in the bin/ directory of the
release package.
Add that directory to PATH.

GPU (CUDA) — make sure the LibTorch CUDA native libraries are on
PATH (Windows) or LD_LIBRARY_PATH (Linux).

Quick Start Copy Chapter

import smile.classification.RandomForest;
import smile.data.formula.Formula;
import smile.io.Read;

// Load data
var data = Read.csv("src/test/resources/iris.csv");

// Train a random forest
var forest = RandomForest.fit(Formula.lhs("species"), data);

// Predict
int label = forest.predict(data.get(0));
System.out.println("Predicted class: " + label);

For deep learning and LLM examples, see deep/README.md.
For visualization examples, see plot/README.md.

SMILE Studio Copy Chapter

SMILE Studio is an agentic IDE for data science using Python or SMILE on JVM.
See studio/README.md for full documentation.

Download a pre-packaged release from the
releases page, then:

path/to/smile/bin/setup      # install required native dependencies
path/to/smile/bin/smile      # launch SMILE Studio from your project directory

Other entry points:

To increase the JVM heap:

path/to/smile/bin/smile -J-Xmx30G

Model Serialization Copy Chapter

Most SMILE models implement java.io.Serializable. You can serialize a
trained model to disk and load it in a production environment or inside a
Spark job:

// Save
try (var out = new ObjectOutputStream(new FileOutputStream("model.ser"))) {
    out.writeObject(forest);
}

// Load
try (var in = new ObjectInputStream(new FileInputStream("model.ser"))) {
    var loaded = (RandomForest) in.readObject();
}

Visualization Copy Chapter

SMILE provides two visualization layers:

• smile.plot.swing — Swing-based interactive 2D/3D plots. See plot/README.md.
• smile.plot.vega — Declarative Vega-Lite charts for browsers and Jupyter. See plot/VEGA.md.

<dependency>
  <groupId>com.github.haifengl</groupId>
  <artifactId>smile-plot</artifactId>
  <version>6.3.0</version>
</dependency>

License Copy Chapter

SMILE employs a dual license model designed to meet the development
and distribution needs of both commercial distributors (OEMs, ISVs, VARs)
and open source projects. For details, see
LICENSE.
To acquire a commercial license, contact [email protected].

Issues & Discussions Copy Chapter

Contributing Copy Chapter

Please read CONTRIBUTING.md for build and test instructions.

Maintainers Copy Chapter

• Haifeng Li (@haifengl)
• Karl Li (@kklioss)

Gallery Copy Chapter

|
Scatterplot Matrix | | |

| --- | --- | --- |
|
Scatter Plot |
Line Plot |
Surface Plot |
|
Bar Plot |
Box Plot |
Histogram Heatmap |
|
Rolling Average |
Geo Map |
UMAP |
|
Text Plot |
Heatmap with Contour |
Hexmap |
|
IsoMap |
LLE |
Kernel PCA |
|
Neural Network |
SVM |
Hierarchical Clustering |
|
SOM |
DBSCAN |
Neural Gas |
|
Wavelet |
Exponential Family Mixture |
Teapot Wireframe |
|
Grid Interpolation | | |