Clorch is a Clojure deep-learning library backed by LibTorch, the C++ engine that powers PyTorch. It brings PyTorch-style tensors, automatic differentiation, neural-network modules, optimizers, data loading, explicit CPU/CUDA device placement, NCCL distributed training, and a growing set of LLM primitives to the Clojure ecosystem — all through a REPL-friendly API designed to feel natural alongside idiomatic Clojure code.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/antlobach/clorch/llms.txt
Use this file to discover all available pages before exploring further.
Key Highlights
Tensor & Training APIs
Full tensor operations, autograd, losses, optimizers, data loaders, state dictionaries, AMP, and native-memory scopes with
with-torch.Model Building
Standard layers, custom
nn/defmodel modules, architecture summaries via nn/summary, and checkpoint loading for portable model serialization.Distributed CUDA
NCCL collectives, managed rank processes, distributed sampling, synchronous DDP, gradient accumulation, and rank-zero checkpoints across multiple GPUs.
LLM Components
RMSNorm, RoPE, grouped-query attention, SwiGLU, fused scaled-dot-product attention, causal masks, KV caches, and autoregressive generation built-in.
REPL-Friendly Design Philosophy
Clorch is built for interactive development. Every tensor and module is a first-class Clojure value — you can inspect shapes, run forward passes, and inspect gradients directly in a REPL session without any boilerplate setup. Thewith-torch macro provides scoped native memory management so that large batches or generation loops do not silently accumulate tensors on the native heap, while start-session! and stop-session! offer a looser interactive mode suited for exploratory work.
Because LibTorch allocates tensors outside the JVM heap, the garbage collector cannot measure native memory pressure on its own. The discipline is simple: keep long-lived models and optimizers outside with-torch scopes, and wrap each allocating batch step or generation call inside one. Return a JVM scalar or nil from the scope unless a tensor must escape.
PyTorch Namespace Mapping
Clorch follows PyTorch’s module boundaries closely. If you know where to find something in Python, you know the corresponding Clorch namespace.| PyTorch concept | Clorch namespace |
|---|---|
torch | clorch.torch |
torch.cuda | clorch.cuda |
torch.amp | clorch.amp |
torch.distributed | clorch.distributed |
DistributedDataParallel | clorch.nn.parallel |
torch.autograd | clorch.autograd |
torch.nn | clorch.nn |
torch.nn.functional | clorch.nn.functional |
torch.optim | clorch.optim |
torch.distributions | clorch.distributions |
torch.linalg | clorch.linalg |
Dataset / DataLoader | clorch.data |
Clorch follows PyTorch concepts but does not expose every PyTorch symbol. Check the API documentation or source before translating a Python call directly. The
llms.txt machine-readable index at antlobach.github.io/clorch/llms.txt is also useful for AI-assisted translation.Project Status
The cross-language comparison suite currently passes 40 of 40 numerical scenarios, validating numerical parity with PyTorch across tensor operations, autograd, and neural network primitives. The tracked feature catalog predates the PyTorch 2.10 distributed-training milestone; a version-pinned recount is planned before the next breadth percentage is published. Read the PyTorch Parity guide for the capability table and roadmap.Explore the Documentation
Installation
Add Clorch to your
deps.edn, configure the JVM, and verify your CPU or CUDA backend in minutes.Quickstart
Tensors, autograd, a simple neural network, a custom
defmodel, and a full training loop — all in one guided walkthrough.Tensors & Operations
Creation, dtypes, shapes, math, reductions, slicing, and advanced indexing with
ix.Neural Networks
Modules, custom models with
defmodel, standard layers, and architecture summaries.Distributed Training
NCCL workers, DDP, AMP, gradient accumulation, distributed sampling, and checkpoints.
Memory Management
Native allocation scopes,
with-torch, retain!, release!, and long-lived REPL sessions.