YiShape Deep Learning

Pure Java deep learning — no Python, no CUDA toolchain. ONNX Runtime is an optional inference acceleration dependency.

YiShape-DL is a production-grade deep learning library covering the full pipeline of model building → training → ONNX import/export → inference deployment. Computation kernels are powered by YiShape-Math (automatic differentiation, operator fusion, JIT), with GPU acceleration via YiShape-Math-GPU (wgpu / Vulkan / DX12 / Metal) and YiShape-Math-HPC (Rust SIMD), providing automatic GPU → HPC → SIMD → SISD fallback.

All public APIs are accessed through the DL.* facade — no direct instantiation of internal classes needed.

Features


Pure Java	No Python runtime, no CUDA/cuDNN toolchain — just JDK 25+
Cross-platform GPU	NVIDIA, AMD, Intel, Apple Silicon via Rust wgpu (Vulkan / DX12 / Metal)
ONNX → Trainable Module	Import pretrained models as native trainable `Module` — fine-tune and re-export
YSD Deployment	Self-contained ZIP format with structure, weights, and inference metadata
Auto Fallback	GPU → HPC → SIMD → SISD, transparent to the caller
JIT + Fusion	Runtime operator fusion (Conv+BN+ReLU, Linear+Activation) and JIT tracing
Per-sample Gradients	`vmap` for DP-SGD, influence functions, gradient debugging
LoRA / Quant / Prune	Production deployment tools: low-rank adapters, INT8 PTQ, magnitude/channel pruning
18 Facade Wrappers	`DL.nn`, `DL.train`, `DL.loss`, `DL.models`, `DL.onnx`, `DL.dataset`, …
40+ Layers	Linear, Conv2d, BatchNorm, LayerNorm, Transformer, ViT, Mamba, LSTM, UNet, …
20+ Loss Functions	MSE, CrossEntropy, Focal, Dice, CTC, GIoU, KLDiv, BCE variants, …
8 Optimizers	Adam, SGD, AdamW, LAMB, RMSprop, Adagrad, Adadelta, BF16
19 Inference Translators	Classification, detection (YOLO/DETR), segmentation, depth, face, embedding, …
DP-SGD	Built-in differential privacy gradient with per-sample clipping and noise
18 Pretrained ONNX Wrappers	YOLO11m, SCRFD, RetinaFace, DeepLabV3, DINOv2, CLIP, Whisper, ResNet50, …

Quick Start

Maven (GitHub Packages)

In ~/.m2/settings.xml, configure a GitHub PAT with read:packages scope (see .github/maven-settings.example.xml):

<repositories>
  <repository>
    <id>github-dl</id>
    <url>https://maven.pkg.github.com/ScaleFree-Tech/yishape-dl</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.yishape.lab</groupId>
  <artifactId>yishape-dl</artifactId>
  <version>0.1</version>
</dependency>

HPC and GPU acceleration are optional — add them separately if desired:

<!-- Optional: Rust native acceleration -->
<dependency>
  <groupId>com.yishape.lab</groupId>
  <artifactId>yishape-math-hpc</artifactId>
  <version>0.5.0</version>
</dependency>

<!-- Optional: GPU shader acceleration -->
<dependency>
  <groupId>com.yishape.lab</groupId>
  <artifactId>yishape-math-gpu</artifactId>
  <version>0.5.0</version>
</dependency>

Build from Source

No GitHub account required — just JDK 25:

git clone https://github.com/ScaleFree-Tech/yishape-dl.git
cd yishape-dl
./mvnw install -DskipTests

Train a model on MNIST in under 30 lines:

import com.yishape.lab.yishape.dl.DL;
import com.yishape.lab.dl.inference.result.ClassificationResult;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // Optional: enable GPU acceleration
        DL.device.set(DL.device.gpuIfAvailable());

        // Data
        var trainSet = DL.train.mnist("datasets/mnist", true);
        var testSet  = DL.train.mnist("datasets/mnist", false);

        // Model: 784 → 256 → 128 → 10 MLP
        var model = DL.nn.sequential(
            DL.nn.linear(784, 256), DL.nn.relu(),
            DL.nn.dropout(0.2),
            DL.nn.linear(256, 128), DL.nn.relu(),
            DL.nn.linear(128, 10));

        // Train
        var trainer = DL.train.adam(model, DL.loss.crossEntropy());
        trainer.clipNorm(1.0);
        trainer.fit(
            DL.train.dataLoader(trainSet, 128, true), 5,
            DL.train.logger(),
            DL.train.validation(DL.train.dataLoader(testSet, 256)));

        // Save with embedded inference metadata
        String serving =
            "translatorFactory=ImageClassificationTranslator\n" +
            "width=28\n" +
            "normalize=0.1307,0.1307,0.1307,0.3081,0.3081,0.3081\n";
        String synset = "0\n1\n2\n3\n4\n5\n6\n7\n8\n9\n";
        DL.models.saveForInference(model, "mnist_mlp.ysd", serving, synset);

        // One-line inference
        var deployed = DL.models.loadModel("mnist_mlp.ysd");
        ClassificationResult result = (ClassificationResult) deployed.predict(
            DL.dataset.loadImageForInference("test_digit.png", 28));
        result.topK(5).forEach(l ->
            System.out.printf("  %s: %.3f%n", l.label(), l.probability()));
    }
}

Expected output:

Epoch 1/5 | loss: 0.3421 | val_loss: 0.1523 | time: 12.3s
Epoch 2/5 | loss: 0.1205 | val_loss: 0.1032 | time: 11.8s
...
Top-3 Predictions:
  7: 0.982
  1: 0.012
  9: 0.004

More Examples

Object Detection (YOLO)

var model = DL.models.loadModel("models/yolo11m");
var img   = DL.dataset.loadImageForInference("street.jpg", 640);
var result = (DetectionListResult) model.predict(img);

for (var d : result.detections()) {
    System.out.printf("%s %.2f [%.0f,%.0f,%.0f,%.0f]%n",
        d.className(), d.confidence(), d.x1(), d.y1(), d.x2(), d.y2());
}

LoRA Fine-tuning (Import ONNX → Fine-tune → Deploy)

// Import pretrained ResNet50 as trainable Module
Module model = DL.onnx.importAsModule("resnet50.onnx");
model.eval();

// Inject LoRA adapters (trainable parameters: ~2% of original)
Module loraModel = DL.lora.apply(model, rank = 16, alpha = 16.0);

// Train only LoRA parameters
List<Parameter> loraParams = DL.lora.parameters(loraModel);
var trainer = DL.train.adamW(loraModel, DL.loss.crossEntropy());
trainer.fit(loader, 10, DL.train.logger());

// Save small adapter file (distribute separately)
DL.lora.saveAdapters(loraModel, "lora_adapters.bin");

// Merge into main weights and export
DL.lora.merge(loraModel);
DL.onnx.export(model, new long[]{1, 3, 224, 224}, "resnet50_lora.onnx");

Semantic Segmentation (U-Net)

var model = DL.nn.unet(3, 21);  // 3 input channels, 21 classes
var trainer = DL.train.adam(model, DL.loss.dice());
trainer.fit(loader, 20, DL.train.logger(), DL.train.validation(valLoader));

SegmentationMask mask = model.predict(
    DL.dataset.loadImageForInference("scene.jpg", 520));
int[][] classMask = mask.classMask();

GPU Benchmark

var trainer = DL.train.adam(model, DL.loss.crossEntropy());

// CPU baseline
DL.device.set(DL.device.cpu());
long t0 = System.currentTimeMillis();
trainer.fit(loader, 5);
long cpuMs = System.currentTimeMillis() - t0;

// GPU run
DL.device.set(DL.device.gpuIfAvailable());
t0 = System.currentTimeMillis();
trainer.fit(loader, 5);
long gpuMs = System.currentTimeMillis() - t0;

System.out.printf("CPU: %d ms, GPU: %d ms, speedup: %.2fx%n",
    cpuMs, gpuMs, (double) cpuMs / gpuMs);

See com.yishape.lab.dl.model_zoo for 20+ runnable demos: object detection, segmentation, face detection, OCR (CRNN+CTC), Word2Vec, GloVe, Seq2Seq with attention, and more.

Why YiShape-DL

Feature	YiShape-DL	PyTorch	DJL
Primary language	Java	Python / C++	Java
GPU backend	Rust wgpu (Vulkan / DX12 / Metal)	CUDA	CUDA / MKL
ONNX → trainable Module	Native parsing, no ORT	via torch.onnx	Mostly ORT black-box
No vendor toolchain	Yes	No (CUDA)	No
JIT + operator fusion	Yes	torch.compile	Limited
Deployment format	YSD (ZIP + JSON + weights)	.pt / .pth	Multiple
Training + inference	Both	Both	Both

Typical use cases

Embedding ML inference in enterprise Java / Spring backends without maintaining Python services
Fine-tuning ONNX pretrained models on the JVM and deploying as YSD
Cross-platform GPU (Apple Silicon, AMD, Intel iGPU) without NVIDIA CUDA binding
Education and research: understand training loops, Module system, and computation graphs from scratch

DL Facade at a Glance

Entry point: com.yishape.lab.yishape.dl.DL

Facade	Highlights
`DL.nn`	40+ layers: Linear, Conv2d, BatchNorm, LayerNorm, Transformer, ViT, Mamba, LSTM, UNet, ResNet, LLaMA, GPT-2, NormalizingFlow
`DL.train`	Trainer + 8 optimizers (Adam, SGD, AdamW, LAMB, RMSprop, Adagrad, Adadelta, BF16), AMP, GradScaler, callbacks, LR schedulers, checkpoints, EMA
`DL.loss`	20 losses: MSE, CrossEntropy, Focal, Dice, CTC, GIoU, KLDiv, BCE variants, SmoothL1, LabelSmoothing, Triplet, CosineEmbedding
`DL.dataset`	MNIST, CIFAR-10, FashionMNIST, ImageFolder, TextFolder, AudioFolder, CSV, ARFF, 7 augmentations, inference image loading
`DL.models`	Load ONNX/YSD + Translator, `InferenceEngine` selection (YSD / ORT / AUTO), model summary
`DL.translator`	19 standard translators: classification, detection (YOLO/DETR), segmentation, depth, face (SCRFD/RetinaFace), text/image embedding, BERT
`DL.onnx`	ONNX → trainable Module, export to ONNX/YSD/Safetensors, load Safetensors
`DL.device`	CPU / GPU device management, `gpuIfAvailable()`, thread context, runtime toggle
`DL.optimize`	Recursive operator fusion (Conv+BN+ReLU, Linear+Activation), ONNX graph optimization
`DL.jit`	JIT compilation for inference (trace + skip AD graph), float32 fast path
`DL.lora`	LoRA low-rank fine-tuning: apply, merge, save/load adapters, parameter count
`DL.quantize`	INT8 post-training quantization (with/without calibration), BF16 encode/decode
`DL.prune`	Unstructured magnitude pruning, structured channel pruning, sparsity query
`DL.vmap`	Per-sample gradients, DP-SGD (clip + noise), influence scores, gradient outlier detection, batched forward
`DL.grad`	Functional gradients (`GradFn`), flatten/unflatten parameters for meta-learning (MAML)
`DL.metrics`	Accuracy, F1 (macro/weighted/per-class), Top-K, AUC-ROC, IoU (per-class/mIoU), BLEU
`DL.init`	Xavier (uniform/normal), He (uniform/normal), uniform, normal initialization

Architecture Overview

flowchart TD
    subgraph UserAPI["User API Layer — DL Facade"]
        direction LR
        A1["DL.nn"]
        A2["DL.train"]
        A3["DL.loss"]
        A4["DL.models"]
        A5["DL.onnx"]
        A6["DL.dataset"]
        A7["DL.translator"]
        A8["DL.device"]
        A9["DL.optimize"]
        A10["DL.jit / DL.lora / DL.quantize / DL.prune / DL.vmap / DL.grad / DL.metrics"]
    end

    subgraph CoreLib["Core Library Layer"]
        direction LR
        B1["nn/\nModule, Conv, Transformer, Mamba"]
        B2["train/\nTrainer, Optimizer, DataLoader"]
        B3["loss/\n20+ Loss Functions"]
        B4["onnx/\nImport, Export, Safetensors"]
        B5["inference/\nTranslator, UnifiedModel"]
        B6["datasets/\nVision, Text, Audio, Tabular"]
        B7["model_zoo/\nCV, NLP, 18 ONNX Wrappers"]
        B8["device/ quantize/ vmap/ grad/\nmetrics/ prune/ lora/"]
    end

    subgraph ComputeLayer["Computation Layer — YiShape-Math"]
        direction LR
        C1["Autodiff Engine"]
        C2["Operator Fusion"]
        C3["JIT Compiler"]
        C4["vmap / VJP"]
    end

    subgraph Backend["Hardware Backend — Auto Fallback"]
        direction LR
        D1["GPU\nwgpu / Vulkan / DX12 / Metal\nRust + Java FFM"]
        D2["HPC\nRust SIMD\nRust + Java FFM"]
        D3["CPU\nJava SISD"]
    end

    UserAPI --> CoreLib
    CoreLib --> ComputeLayer
    ComputeLayer -->|"GPU available &\nscale ≥ threshold"| Backend
    ComputeLayer -.->|"fallback"| Backend

    style UserAPI fill:#4A90D9,color:#fff,stroke:#2C5F8A,stroke-width:2px
    style CoreLib fill:#6BBF59,color:#fff,stroke:#3D8B30,stroke-width:2px
    style ComputeLayer fill:#F5A623,color:#fff,stroke:#C78410,stroke-width:2px
    style Backend fill:#E87E7E,color:#fff,stroke:#B94A4A,stroke-width:2px

Training data flow: DataLoader → Module.forward(IDiffTensor) → LossFunction → backward() → Optimizer.step()

Inference data flow: User input → Translator.preprocess() → Model.predict() → Translator.postprocess() → Structured result

Compilation chain: Java → yishape-math (AD + fusion) → yishape-math-gpu (wgpu shaders) or yishape-math-hpc (Rust SIMD)

Relationship with YiShape-Math: YiShape-DL is the deep learning layer built on top of YiShape-Math. YiShape-Math provides the mathematical foundation — automatic differentiation, tensor operations, operator fusion, and JIT compilation — while YiShape-DL adds neural network abstractions (Module, layers, loss functions, Trainer, ONNX I/O, inference translators). The GPU (YiShape-Math-GPU) and HPC (YiShape-Math-HPC) backends are transitive dependencies pulled in automatically. End users only need to declare yishape-dl in their build.

Project Structure

src/main/java/com/yishape/lab/
├── yishape/dl/          # DL facade (DL.java and *Wrapper classes)
└── dl/
    ├── nn/              # Module system, 40+ layers, Transformer, ViT, Mamba, fusion
    │   ├── activation/      17 activation functions
    │   ├── conv/           Conv1d/2d, ConvTranspose2d, DepthwiseConv, im2col
    │   ├── norm/           BatchNorm, LayerNorm, GroupNorm, InstanceNorm, RMSNorm
    │   ├── pooling/        MaxPool, AvgPool, AdaptivePool
    │   ├── transformer/    Transformer, MultiheadAttention, FlashAttention, KV Cache
    │   ├── rnn/            RNN, LSTM, GRU
    │   ├── mamba/          Mamba-1, Mamba-2, Jamba
    │   ├── nlp/            Embedding, Word2Vec, Seq2Seq, Attention
    │   └── vision/         ROIAlign, Upsample, VisionTransformer
    ├── train/           # Trainer, 8 optimizers, DataLoader, callbacks, AMP, EMA
    ├── loss/            # 20 loss functions
    ├── onnx/            # ONNX import/export, 304-node verified YOLO v11, Safetensors
    ├── inference/       # Translator, UnifiedModel, ORT bridge, 19 result types
    │   └── tokenizer/    # BPE, WordPiece
    ├── datasets/        # Vision, text, audio, tabular datasets & augmentation
    ├── model_zoo/       # Reference implementations
    │   ├── cv/           ObjectDetection, Segmentation, FaceDetector, CRNN+CTC, Keypoints
    │   ├── nlp/          Word2Vec, GloVe, Seq2Seq with attention
    │   └── inference/    18 ONNX model wrappers (YOLO, DETR, DeepLabV3, DINOv2, CLIP, Whisper…)
    ├── device/          # Device abstraction (GPU/CPU)
    ├── quantize/        # INT8 PTQ, BF16
    ├── vmap/            # Per-sample gradients, DP-SGD, influence functions
    ├── grad/            # Functional gradients (GradFn), MAML support
    ├── metrics/         # Accuracy, F1, AUC-ROC, Top-K, BLEU, IoU
    ├── prune/           # Magnitude pruning, channel pruning
    └── lora/            # LoRA adapters

Documentation

Document	Description
Quick Start	End-to-end MNIST tutorial, Maven/Gradle setup, FAQ
Model Guide	Module system, all 40+ layer APIs, YSD format, custom layers
Training Guide	Optimizers, losses, callbacks, AMP, LR scheduling, checkpoints, resume
Inference Guide	Model loading, Translator, serving.properties, engine selection (YSD/ORT/AUTO)
ONNX Guide	Import for fine-tuning, export, graph fusion, Safetensors
Data Guide	Datasets, transforms, augmentation, inference image loading
GPU Guide	Device management, performance tuning, multi-platform, troubleshooting
Advanced Guide	LoRA, quantization, pruning, JIT, vmap, metrics, GradFn

Model Zoo

com.yishape.lab.dl.model_zoo contains 20+ runnable reference implementations:

Demo	Task
`ObjectDetectionDemo`	SSD-style detection with anchors, FocalLoss, GIoULoss, NMS
`SegmentationDemo`	U-Net encoder-decoder with skip connections, DiceLoss
`FaceDetectorDemo`	Multi-scale sliding window face detection
`KeypointDetectionDemo`	Heatmap regression with Gaussian targets
`CRNNWithCTCDemo`	CRNN + CTC for OCR
`Word2VecDemo`	Skip-gram with negative sampling
`GloVeDemo`	Co-occurrence matrix training
`Seq2SeqDemo`	Encoder-decoder with Bahdanau attention, beam search
`InferenceDemo`	End-to-end inference with 18 pretrained ONNX models

Plus 18 pretrained model wrappers under model_zoo.inference: YOLO11m (detect/segment/pose), DETR, SCRFD, RetinaFace, DeepLabV3, SAM, MiDaS, DINOv2, CLIP (vision+text), Whisper, ResNet50, ArcFace, MAE, and more.

Building from Source

git clone https://github.com/ScaleFree-Tech/yishape-dl.git
cd yishape-dl
./mvnw install -DskipTests

Run unit tests:

./mvnw test
# Full integration test suite
./mvnw test -Pfull-test

Note: GPU and HPC acceleration libraries are optional dependencies. Use GpuSwitch.enable() and DL.device.set(DL.device.gpuIfAvailable()) to enable them at runtime.

Contributing

Contributions are welcome — bug reports, feature requests, documentation improvements, and pull requests.

Fork and clone the repository
Create a feature branch (git checkout -b feat/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feat/amazing-feature)
Open a Pull Request

Please read CONTRIBUTING.md for coding conventions, the gradient flow rules, and the pre-commit hook setup.

License

Apache License 2.0 — see LICENSE for details.

Related Projects

YiShape-Math — Automatic differentiation and tensor operations
YiShape-Math-GPU — wgpu compute shaders
YiShape-Math-HPC — Native CPU acceleration via Java FFM

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.githooks		.githooks
.github		.github
.mvn/wrapper		.mvn/wrapper
datasets		datasets
docs		docs
scripts		scripts
src		src
tools		tools
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
jitpack.yml		jitpack.yml
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

YiShape Deep Learning

Contents

Features

Quick Start

Maven (GitHub Packages)

Build from Source

More Examples

Object Detection (YOLO)

LoRA Fine-tuning (Import ONNX → Fine-tune → Deploy)

Semantic Segmentation (U-Net)

GPU Benchmark

Why YiShape-DL

DL Facade at a Glance

Architecture Overview

Project Structure

Documentation

Model Zoo

Building from Source

Contributing

License

Related Projects

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

YiShape Deep Learning

Contents

Features

Quick Start

Maven (GitHub Packages)

Build from Source

More Examples

Object Detection (YOLO)

LoRA Fine-tuning (Import ONNX → Fine-tune → Deploy)

Semantic Segmentation (U-Net)

GPU Benchmark

Why YiShape-DL

DL Facade at a Glance

Architecture Overview

Project Structure

Documentation

Model Zoo

Building from Source

Contributing

License

Related Projects

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages