> ## Documentation Index
> Fetch the complete documentation index at: https://antlobach-clorch-182a83cb.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Clorch: LibTorch Deep Learning Bindings for Clojure

> Explore Clorch's PyTorch-style tensor ops, autograd, nn modules, distributed CUDA training, and LLM components — all from an idiomatic Clojure REPL.

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.

## Key Highlights

<CardGroup cols={2}>
  <Card title="Tensor & Training APIs" icon="layer-group">
    Full tensor operations, autograd, losses, optimizers, data loaders, state dictionaries, AMP, and native-memory scopes with `with-torch`.
  </Card>

  <Card title="Model Building" icon="cubes">
    Standard layers, custom `nn/defmodel` modules, architecture summaries via `nn/summary`, and checkpoint loading for portable model serialization.
  </Card>

  <Card title="Distributed CUDA" icon="server">
    NCCL collectives, managed rank processes, distributed sampling, synchronous DDP, gradient accumulation, and rank-zero checkpoints across multiple GPUs.
  </Card>

  <Card title="LLM Components" icon="brain">
    RMSNorm, RoPE, grouped-query attention, SwiGLU, fused scaled-dot-product attention, causal masks, KV caches, and autoregressive generation built-in.
  </Card>
</CardGroup>

## 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. The `with-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` |

<Note>
  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](https://antlobach.github.io/clorch/llms.txt) is also useful for AI-assisted translation.
</Note>

## 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](https://antlobach.github.io/clorch/docs/pytorch-parity) guide for the capability table and roadmap.

## Explore the Documentation

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Add Clorch to your `deps.edn`, configure the JVM, and verify your CPU or CUDA backend in minutes.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Tensors, autograd, a simple neural network, a custom `defmodel`, and a full training loop — all in one guided walkthrough.
  </Card>

  <Card title="Tensors & Operations" icon="table" href="https://antlobach.github.io/clorch/docs/tensors">
    Creation, dtypes, shapes, math, reductions, slicing, and advanced indexing with `ix`.
  </Card>

  <Card title="Neural Networks" icon="network-wired" href="https://antlobach.github.io/clorch/docs/nn">
    Modules, custom models with `defmodel`, standard layers, and architecture summaries.
  </Card>

  <Card title="Distributed Training" icon="diagram-project" href="https://antlobach.github.io/clorch/docs/distributed">
    NCCL workers, DDP, AMP, gradient accumulation, distributed sampling, and checkpoints.
  </Card>

  <Card title="Memory Management" icon="memory" href="https://antlobach.github.io/clorch/docs/memory">
    Native allocation scopes, `with-torch`, `retain!`, `release!`, and long-lived REPL sessions.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.