# Statistical Machine Intelligence & Learning Engine SMILE [![Maven Central](https://img.shields.io/maven-central/v/com.github.haifengl/smile-core)](https://central.sonatype.com/artifact/com.github.haifengl/smile-core) [![CI](https://github.com/haifengl/smile/actions/workflows/ci.yml/badge.svg)](https://github.com/haifengl/smile/actions/workflows/ci.yml) 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](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 1. [Features](#features) 2. [Module Map](#module-map) 3. [Installation](#installation) - [Maven](#maven) - [SBT (Scala)](#sbt-scala) - [Gradle (Kotlin)](#gradle-kotlin) - [Native Libraries (BLAS / LAPACK)](#native-libraries-blas--lapack) 4. [Quick Start](#quick-start) 5. [SMILE Studio & Shell](#smile-studio--shell) 6. [Model Serialization](#model-serialization) 7. [Visualization](#visualization) 8. [License](#license) 9. [Issues & Discussions](#issues--discussions) 10. [Contributing](#contributing) 11. [Maintainers](#maintainers) 12. [Gallery](#gallery) --- ## Features | Area | Highlights | |---|---| | **LLM** | LLaMA-3 inference, tiktoken BPE tokenizer, OpenAI-compatible REST server, SSE chat streaming | | **Deep Learning** | LibTorch/GPU backend, EfficientNet-V2 image classification, custom layer API | | **Classification** | SVM, Decision Trees, Random Forest, AdaBoost, Gradient Boosting, Logistic Regression, Neural Networks, RBF Networks, MaxEnt, KNN, Naïve Bayes, LDA/QDA/RDA | | **Regression** | SVR, Gaussian Process, Regression Trees, GBDT, Random Forest, RBF, OLS, LASSO, ElasticNet, Ridge | | **Clustering** | BIRCH, CLARANS, DBSCAN, DENCLUE, Deterministic Annealing, K-Means, X-Means, G-Means, Neural Gas, Growing Neural Gas, Hierarchical, SIB, SOM, Spectral, Min-Entropy | | **Manifold Learning** | IsoMap, LLE, Laplacian Eigenmap, t-SNE, UMAP, PCA, Kernel PCA, Probabilistic PCA, GHA, Random Projection, ICA | | **Feature Engineering** | Genetic Algorithm selection, Ensemble selection, TreeSHAP, SNR, Sum-Squares ratio, data transformations, formula API | | **NLP** | Sentence / word tokenization, Bigram test, Phrase & Keyword extraction, Stemmer, POS tagging, Relevance ranking | | **Association Rules** | FP-growth frequent itemset mining | | **Sequence Learning** | Hidden Markov Model, Conditional Random Field | | **Nearest Neighbor** | BK-Tree, Cover Tree, KD-Tree, SimHash, LSH | | **Numerical Methods** | Linear algebra, numerical optimization (BFGS, L-BFGS), interpolation, wavelets, RBF, distributions, hypothesis tests | | **Visualization** | Swing plots (scatter, line, bar, box, histogram, surface, heatmap, contour, …) and declarative Vega-Lite charts | --- ## Module Map Each module has its own detailed user guide. Click the **README** link for the module overview, or drill into individual topic guides. ### `base/` — Foundation > Data structures, math, linear algebra, statistical utilities, I/O | Document | Topics | |---|---| | [README](base/README.md) | Module overview and dependency setup | | [DATA_FRAME.md](base/DATA_FRAME.md) | DataFrame API — creation, selection, transformation | | [DATA_IO.md](base/DATA_IO.md) | CSV, JSON, Parquet, Arrow, JDBC, Avro readers/writers | | [DATA_TRANSFORMATION.md](base/DATA_TRANSFORMATION.md) | Scalers, encoders, imputers, feature transforms | | [DATASET.md](base/DATASET.md) | Built-in benchmark and real-world datasets | | [FORMULA.md](base/FORMULA.md) | R-style formula language for model matrices | | [DISTRIBUTIONS.md](base/DISTRIBUTIONS.md) | Probability distributions (Normal, Poisson, Beta, …) | | [HYPOTHESIS_TESTING.md](base/HYPOTHESIS_TESTING.md) | t-test, chi-squared, ANOVA, KS-test, … | | [DISTANCES.md](base/DISTANCES.md) | Euclidean, Mahalanobis, Hamming, edit distance, … | | [NEAREST_NEIGHBOR.md](base/NEAREST_NEIGHBOR.md) | KD-Tree, Cover Tree, BK-Tree, LSH | | [KERNELS.md](base/KERNELS.md) | Gaussian, polynomial, Laplacian, and other kernel functions | | [RBF.md](base/RBF.md) | Radial basis function networks | | [INTERPOLATION.md](base/INTERPOLATION.md) | Linear, cubic spline, bilinear, bicubic | | [GRAPH.md](base/GRAPH.md) | Adjacency list/matrix graph, BFS/DFS, spanning trees | | [SORT.md](base/SORT.md) | Quick sort, heap sort, counting sort, index sort | | [HASH.md](base/HASH.md) | Locality-sensitive hashing, SimHash | | [RNG.md](base/RNG.md) | Random number generators, sampling, permutations | | [BFGS.md](base/BFGS.md) | L-BFGS and BFGS numerical optimizers | | [ICA.md](base/ICA.md) | Independent Component Analysis | | [TENSOR.md](base/TENSOR.md) | N-dimensional array (CPU tensor without LibTorch) | | [WAVELET.md](base/WAVELET.md) | DWT, CWT, and wavelet families | | [GAP.md](base/GAP.md) | GAP statistic for optimal cluster count estimation | | [COMPRESSED_SENSING.md](base/COMPRESSED_SENSING.md) | Compressed sensing and basis pursuit | ### `core/` — Machine Learning Algorithms > Classification, regression, clustering, manifold learning, and more | Document | Topics | |---|---| | [README](core/README.md) | Module overview | | [CLASSIFICATION.md](core/CLASSIFICATION.md) | SVM, Random Forest, AdaBoost, GBDT, KNN, Naïve Bayes, LDA, … | | [REGRESSION.md](core/REGRESSION.md) | SVR, Gaussian Process, LASSO, Ridge, ElasticNet, GBDT, … | | [CLUSTERING.md](core/CLUSTERING.md) | K-Means, DBSCAN, BIRCH, SOM, Spectral Clustering, … | | [FEATURE_ENGINEERING.md](core/FEATURE_ENGINEERING.md) | Feature selection, PCA, ICA, projection, encoding | | [MANIFOLD.md](core/MANIFOLD.md) | t-SNE, UMAP, IsoMap, LLE, Laplacian Eigenmap | | [ANOMALY_DETECTION.md](core/ANOMALY_DETECTION.md) | IsolationForest, one-class SVM, local outlier factor | | [ASSOCIATION_RULE_MINING.md](core/ASSOCIATION_RULE_MINING.md) | FP-growth, association rules, frequent itemsets | | [SEQUENCE.md](core/SEQUENCE.md) | HMM (Baum-Welch, Viterbi), CRF | | [TIME_SERIES.md](core/TIME_SERIES.md) | ARIMA, box-plots, autocorrelation | | [REGRESSION.md](core/REGRESSION.md) | Full regression API reference | | [TRAINING.md](core/TRAINING.md) | Cross-validation, bootstrap, hyper-parameter search | | [VALIDATION.md](core/VALIDATION.md) | Hold-out, k-fold, leave-one-out evaluation | | [VALIDATION_METRICS.md](core/VALIDATION_METRICS.md) | Accuracy, AUC, F1, RMSE, MAE, confusion matrix | | [HYPER_PARAMETER_OPTIMIZATION.md](core/HYPER_PARAMETER_OPTIMIZATION.md) | Grid search, random search, Bayesian optimization | | [VECTOR_QUANTIZATION.md](core/VECTOR_QUANTIZATION.md) | LVQ, Neural Gas, SOM as vector quantizers | | [ONNX.md](core/ONNX.md) | Exporting and importing models via ONNX | ### `deep/` — Deep Learning & LLMs > LibTorch-backed GPU/CPU tensor operations, neural network layers, LLaMA-3 inference, EfficientNet | Document | Topics | |---|---| | [README](deep/README.md) | Full deep-learning & LLM user guide (tensors, layers, loss, optimizer, EfficientNet, LLaMA) | 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.model.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 > Text normalization, tokenization, POS tagging, stemming, relevance ranking | Document | Topics | |---|---| | [README](nlp/README.md) | Module overview | | [TOKENIZER.md](nlp/TOKENIZER.md) | Sentence splitter, word tokenizer, regex tokenizer | | [POS.md](nlp/POS.md) | Part-of-speech tagging (Brill tagger, HMM tagger) | | [STEM.md](nlp/STEM.md) | Porter, Lancaster, Lovins stemmers; lemmatization | | [COLLOCATION.md](nlp/COLLOCATION.md) | Bigram/trigram statistical tests, phrase extraction | | [RELEVANCE.md](nlp/RELEVANCE.md) | TF-IDF, BM25, keyword extraction | | [TAXONOMY.md](nlp/TAXONOMY.md) | WordNet integration, synsets, hypernyms | ### `plot/` — Data Visualization > Swing-based interactive plots and declarative Vega-Lite charts | Document | Topics | |---|---| | [README](plot/README.md) | Swing plotting API — scatter, line, bar, box, histogram, heatmap, surface, contour, wireframe | | [VEGA.md](plot/VEGA.md) | Declarative `smile.plot.vega` (Vega-Lite) — JSON spec generation, web/Jupyter rendering | ### `serve/` — Inference Server > Quarkus-based REST inference service with OpenAI-compatible API and SSE streaming | Document | Topics | |---|---| | [README](serve/README.md) | Building and running the server, `/chat/completions` endpoint, SSE streaming, configuration | ### `studio/` — Interactive Shell & Desktop IDE > An agentic IDE for data science using Python or SMILE | Document | Topics | |-------------------------------|---| | [README.md](studio/README.md) | Desktop Studio UX | | [CLI](studio/CLI.md) | CLI entry points (`smile`, `smile shell`, `smile scala`, `smile serve`) | ### `scala/` — Scala API > Idiomatic Scala shim — concise wrappers, symbolic operators, Scala collections integration | Document | Topics | |---|---| | [README](scala/README.md) | API overview, `smile.classification`, `smile.regression`, `smile.clustering`, `smile.plot` in Scala | ### `kotlin/` — Kotlin API > Idiomatic Kotlin shim — extension functions, named parameters, builder DSLs | Document | Topics | |---|---| | [README](kotlin/README.md) | API overview, extension functions, Kotlin-style builders | | [packages.md](kotlin/packages.md) | Full package-by-package listing of all Kotlin extension functions | ### `json/` — JSON Library (Scala) > Lightweight zero-dependency JSON library for Scala with a clean DSL | Document | Topics | |---|---| | [README](json/README.md) | Parsing, building, pattern matching, path navigation, serialization | ### `spark/` — Apache Spark Integration > Use SMILE models inside Spark ML pipelines | Document | Topics | |---|---| | [README](spark/README.md) | `SmileTransformer`, `SmileClassifier`, `SmileRegressor`; training and scoring in Spark DataFrames | --- ## Installation ### Maven ```xml com.github.haifengl smile-core 6.3.0 com.github.haifengl smile-deep 6.3.0 com.github.haifengl smile-nlp 6.3.0 com.github.haifengl smile-plot 6.3.0 ``` ### SBT (Scala) ```scala libraryDependencies += "com.github.haifengl" %% "smile-scala" % "6.3.0" ``` ### Gradle (Kotlin) ```kotlin dependencies { implementation("com.github.haifengl:smile-kotlin:6.3.0") } ``` ### Native Libraries (BLAS / LAPACK) Several algorithms (manifold learning, Gaussian Process, MLP, some clustering) require BLAS and LAPACK. **Linux (Ubuntu / Debian)** ```shell sudo apt update sudo apt install libopenblas-dev libarpack2-dev ``` **macOS (Homebrew)** ```shell 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](https://github.com/haifengl/smile/releases). 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 ```java 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](deep/README.md). For visualization examples, see [plot/README.md](plot/README.md). --- ## SMILE Studio SMILE Studio is an agentic IDE for data science using Python or [SMILE](https://haifengl.github.io/) on JVM. See [studio/README.md](studio/README.md) for full documentation. Download a pre-packaged release from the [releases page](https://github.com/haifengl/smile/releases), then: ```shell path/to/smile/bin/setup # install required native dependencies path/to/smile/bin/smile # launch SMILE Studio from your project directory ``` Other entry points: | Command | Description | |-----------------|------------------------------------------------| | `smile` | Desktop agentic IDE | | `smile shell` | Java REPL with all SMILE packages pre-imported | | `smile scala` | Scala REPL | | `smile train` | Train a supervised learning model | | `smile predict` | Predict on a file using a saved model | | `smile serve` | Start the LLM inference server | To increase the JVM heap: ```shell path/to/smile/bin/smile -J-Xmx30G ``` --- ## Model Serialization 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: ```java // 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 SMILE provides two visualization layers: - **`smile.plot.swing`** — Swing-based interactive 2D/3D plots. See [plot/README.md](plot/README.md). - **`smile.plot.vega`** — Declarative Vega-Lite charts for browsers and Jupyter. See [plot/VEGA.md](plot/VEGA.md). ```xml com.github.haifengl smile-plot 6.3.0 ``` --- ## License 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](https://github.com/haifengl/smile/blob/master/LICENSE). To acquire a commercial license, contact **smile.sales@outlook.com**. --- ## Issues & Discussions | Channel | Purpose | |---|---| | [GitHub Discussions](https://github.com/haifengl/smile/discussions) | Questions, ideas, show-and-tell | | [Stack Overflow `[smile]`](http://stackoverflow.com/questions/tagged/smile) | Technical Q&A | | [Issue Tracker](https://github.com/haifengl/smile/issues/new) | Bug reports and feature requests | | [Online Docs](https://haifengl.github.io/) | Tutorials and programming guides | | [Java API](https://haifengl.github.io/api/java/index.html) · [Scala API](https://haifengl.github.io/api/scala/index.html) · [Kotlin API](https://haifengl.github.io/api/kotlin/index.html) · [Clojure API](https://haifengl.github.io/api/clojure/index.html) | API Javadoc | --- ## Contributing Please read [CONTRIBUTING.md](CONTRIBUTING.md) for build and test instructions. --- ## Maintainers - Haifeng Li ([@haifengl](https://github.com/haifengl)) - Karl Li ([@kklioss](https://github.com/kklioss)) --- ## Gallery
SPLOM

Scatterplot Matrix

Scatter

Scatter Plot

Heart

Line Plot

Surface

Surface Plot

Scatter

Bar Plot

Box Plot

Box Plot

Histogram

Histogram Heatmap

Rolling

Rolling Average

Map

Geo Map

UMAP

UMAP

Text

Text Plot

Contour

Heatmap with Contour

Hexmap

Hexmap

IsoMap

IsoMap

LLE

LLE

Kernel PCA

Kernel PCA

Neural Network

Neural Network

SVM

SVM

Hierarchical Clustering

Hierarchical Clustering

SOM

SOM

DBSCAN

DBSCAN

Neural Gas

Neural Gas

Wavelet

Wavelet

Mixture

Exponential Family Mixture

Teapot

Teapot Wireframe

Interpolation

Grid Interpolation