### Run all shipped examples

Source: https://github.com/antlobach/clorch/blob/main/README.md

Executes the provided example scripts.

```bash
scripts/run-examples.sh
```

--------------------------------

### Clorch Quick Start Example

Source: https://github.com/antlobach/clorch/blob/main/docs/index.md

Demonstrates basic tensor indexing, autograd usage, and neural network module definition.

```clojure
(require '[clorch.torch :as t]
         '[clorch.nn :as nn]
         '[clorch.nn.functional :as F]
         '[clorch.autograd :as autograd])

;; 1. Ergonomic Indexing
(def x (t/tensor [[1 2 3] [4 5 6]]))
(t/ix x :_ [1 3]) ;; → [[2.0, 3.0], [5.0, 6.0]]

;; 2. Seamless Autograd
(def a (t/tensor [2.0] {:requires-grad true}))
(def b (t/pow a 3))
(autograd/backward b)
(autograd/grad a) ;; → [12.0] (d/da a^3 = 3a^2 = 3*4 = 12)

;; 3. Modern Architectures
(def llama-layer (nn/sequential
                   (nn/rmsnorm 128)
                   (nn/linear 128 512)
                   (nn/silu)))

;; 4. Architecture Summary
(nn/summary llama-layer [1 16 128])
```

--------------------------------

### Start the nREPL

Source: https://github.com/antlobach/clorch/blob/main/README.md

Initializes the development environment using the clj tool.

```bash
clj -M:dev
```

--------------------------------

### Start the repository nREPL

Source: https://github.com/antlobach/clorch/blob/main/AGENTS.md

Command to launch the development nREPL environment.

```bash
CLOJURE_DISABLE_RLWRAP=1 clojure -M:dev
```

--------------------------------

### Install CUDA Runtime Packages

Source: https://github.com/antlobach/clorch/blob/main/README.md

Installs required NVIDIA libraries on Ubuntu systems.

```bash
sudo apt-get update
sudo apt-get install cuda-libraries-13-1 libcudnn9-cuda-13 libnccl2
```

--------------------------------

### Start Clojure REPL

Source: https://github.com/antlobach/clorch/blob/main/docs/index.md

Command to launch the Clojure REPL after configuring dependencies.

```bash
clj
```

--------------------------------

### Run repository verification

Source: https://github.com/antlobach/clorch/blob/main/AGENTS.md

Commands for running release checks and example suites.

```bash
# CPU release suite
clojure -Sthreads 1 -M -m clorch.release-check --mode cpu

# Every shipped example
scripts/run-examples.sh

# Cross-language numerical comparison
run_comparison.sh
```

--------------------------------

### Constructing probability distributions

Source: https://github.com/antlobach/clorch/blob/main/docs/distributions.md

Examples of initializing various probability distributions using clorch.distributions.

```clojure
(dist/normal 0.0 1.0)
(dist/log-normal 0.0 0.5)
(dist/bernoulli (t/tensor [0.2 0.8]))
(dist/categorical (t/tensor [0.1 0.2 0.7]))
(dist/binomial 10.0 0.3)
(dist/uniform -1.0 2.0)
(dist/poisson 3.0)
(dist/exponential 2.0)
(dist/cauchy 0.0 1.0)
(dist/geometric 0.4)
(dist/gumbel 0.0 1.0)
(dist/laplace 0.0 1.0)
```

--------------------------------

### Importing clorch distributions

Source: https://github.com/antlobach/clorch/blob/main/docs/distributions.md

Required setup to access distribution functions and torch utilities.

```clojure
(require '[clorch.distributions :as dist]
         '[clorch.torch :as t])
```

--------------------------------

### Configure Environment for GPU Training

Source: https://github.com/antlobach/clorch/blob/main/README.md

Sets environment variables to enable GPU usage and native access before starting the JVM.

```bash
export CLORCH_FORCE_GPU=1
export LD_LIBRARY_PATH="/usr/local/cuda/lib64:${LD_LIBRARY_PATH:-}"
export JAVA_TOOL_OPTIONS="--enable-native-access=ALL-UNNAMED"

CLOJURE_DISABLE_RLWRAP=1 clojure -M:dev
```

--------------------------------

### Load Slicing Examples

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing-examples.md

Executes the validation script for all supported slicing operations.

```clojure
(load-file "examples/slicing_examples.clj")
```

--------------------------------

### Step-Based Slicing

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing-examples.md

Extract elements at specific intervals using [start stop step] syntax.

```clojure
(torch/ix y [nil nil 2])   ; → [0.0, 2.0, 4.0, 6.0, 8.0]  (every 2nd)
(torch/ix y [1 nil 2])      ; → [1.0, 3.0, 5.0, 7.0, 9.0]  (every 2nd, start at 1)
(torch/ix y [1 8 2])        ; → [1.0, 3.0, 5.0, 7.0]        (every 2nd, range 1-8)
(torch/ix y [nil nil 3])    ; → [0.0, 3.0, 6.0, 9.0]        (every 3rd)
```

--------------------------------

### Evaluate Clorch tensor operations

Source: https://github.com/antlobach/clorch/blob/main/AGENTS.md

Example of performing a simple tensor sum within a with-torch scope.

```clojure
(require '[clorch.torch :as t] :reload)
(t/with-torch
  (t/item-float (t/sum (t/tensor [1.0 2.0 3.0]))))
```

--------------------------------

### Basic Range Slicing

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing-examples.md

Extract sub-sequences from a tensor using [start stop] syntax.

```clojure
(def y (torch/tensor (range 10)))  ; [0 1 2 3 4 5 6 7 8 9]

(torch/ix y [2 5])      ; → [2.0, 3.0, 4.0]
(torch/ix y [0 4])      ; → [0.0, 1.0, 2.0, 3.0]
(torch/ix y [6 10])     ; → [6.0, 7.0, 8.0, 9.0]
```

--------------------------------

### Extract Batches from Training Data

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing-examples.md

Calculate start and end indices to slice a specific batch from a dataset.

```clojure
(def batch-data (torch/tensor (range 100)))
(def batch-size 16)
(def batch-idx 2)

(def start (* batch-idx batch-size))
(def end (+ start batch-size))

(torch/ix batch-data [start end])
```

--------------------------------

### Select Device and Initialize Model

Source: https://github.com/antlobach/clorch/blob/main/README.md

Determines the available backend and moves models and tensors to the selected device.

```clojure
(require '[clorch.cuda :as cuda])

(def device (if (cuda/available?) :cuda :cpu))
(def model-on-device (nn/to model device))
(def input (t/randn [32 10] {:device device}))
```

--------------------------------

### Reverse from Index

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing-examples.md

Reverses the tensor starting from a specific index down to the beginning.

```clojure
;; From index 5 to start
(torch/ix t [5 nil -1])    ; → [5.0, 4.0, 3.0, 2.0, 1.0, 0.0]

;; From index 3 to start
(torch/ix t [3 nil -1])    ; → [3.0, 2.0, 1.0, 0.0]
```

--------------------------------

### Run GPU Release Check

Source: https://github.com/antlobach/clorch/blob/main/README.md

Verifies GPU synchronization and configuration.

```bash
CLORCH_FORCE_GPU=1 clojure -Sthreads 1 -M -m clorch.release-check --mode gpu
```

--------------------------------

### Open-Ended Slicing

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing-examples.md

Use nil to represent the start or end of the tensor in slice ranges.

```clojure
(torch/ix y [0 5])     ; → [0.0, 1.0, 2.0, 3.0, 4.0]  (first 5)
(torch/ix y [5 nil])    ; → [5.0, 6.0, 7.0, 8.0, 9.0]  (last 5)
(torch/ix y [nil nil])  ; → [0.0, ..., 9.0]           (all)
```

--------------------------------

### Run CPU release suite

Source: https://github.com/antlobach/clorch/blob/main/README.md

Executes the numerical verification suite in CPU mode.

```bash
clojure -Sthreads 1 -M -m clorch.release-check --mode cpu
```

--------------------------------

### Run GPU release suite

Source: https://github.com/antlobach/clorch/blob/main/README.md

Executes the numerical verification suite in GPU mode on a Linux NVIDIA host.

```bash
clojure -Sthreads 1 -M -m clorch.release-check --mode gpu
```

--------------------------------

### Apply basic tensor initializers

Source: https://github.com/antlobach/clorch/blob/main/docs/init.md

Demonstrates modifying tensor values in-place using constant, ones, zeros, uniform, and normal distributions.

```clojure
(require '[clorch.torch :as t]
         '[clorch.nn.init :as init])

(def x (t/zeros [3 3]))

(init/constant! x 3.14)
(init/ones! x)
(init/zeros! x)
(init/uniform! x -1.0 1.0)
(init/normal! x 0.0 0.01)
```

--------------------------------

### Initialize SGD Optimizer

Source: https://github.com/antlobach/clorch/blob/main/docs/optimizers.md

Creates an SGD optimizer instance with specified learning rate and momentum.

```clojure
(require '[clorch.optim :as optim])

(def opt (optim/sgd (nn/parameters model) 
                    :lr 0.01 
                    :momentum 0.9))
```

--------------------------------

### Launch Local Distributed Training

Source: https://github.com/antlobach/clorch/blob/main/README.md

Executes a distributed training job across specified physical devices.

```clojure
(require '[distributed-training :as training])

(def result
  (training/run-local!
   [0 1]
   {:epochs 4
    :sample-count 1024
    :batch-size 32
    :accumulation 2
    :precision :bfloat16
    :checkpoint-path "/checkpoints/clorch-ddp.pt"}))
```

--------------------------------

### Verify Host GPU Configuration

Source: https://github.com/antlobach/clorch/blob/main/README.md

Checks for visible GPUs and environment information.

```bash
nvidia-smi -L
java -version
clojure -Sdescribe
```

--------------------------------

### Initialize Adam Optimizer

Source: https://github.com/antlobach/clorch/blob/main/docs/optimizers.md

Creates an Adam optimizer instance with specified learning rate and beta parameters.

```clojure
(def opt (optim/adam (nn/parameters model) 
                     :lr 0.001 
                     :betas [0.9 0.999]))
```

--------------------------------

### Optimizer Initialization

Source: https://github.com/antlobach/clorch/blob/main/docs/optimizers.md

Methods to initialize various optimization algorithms for model parameters.

```APIDOC
## optim/sgd
(optim/sgd params :lr 0.01 :momentum 0.9)

## optim/adam
(optim/adam params :lr 0.001 :betas [0.9 0.999])

## optim/adamw
(optim/adamw params :lr 3e-4 :weight-decay 0.01)

## optim/rmsprop
(optim/rmsprop params :lr 0.01 :alpha 0.99)

## optim/adagrad
(optim/adagrad params :lr 0.01)
```

--------------------------------

### start-session! / stop-session!

Source: https://github.com/antlobach/clorch/blob/main/docs/memory.md

Manages long-lived thread-local scopes for pointer management.

```APIDOC
## start-session! / stop-session!

### Description
`start-session!` opens a long-lived scope for the current thread. `stop-session!` closes it and releases pointers created in that session. Starting a new session closes any existing session on that thread.

### Usage
(t/start-session!)
(t/stop-session!)
```

--------------------------------

### Initialize weights in custom models

Source: https://github.com/antlobach/clorch/blob/main/docs/init.md

Shows how to apply initializers to model parameters within a custom model definition.

```clojure
(nn/defmodel MyModel [in out]
  [l1 (nn/linear in out)]
  (forward [x]
    (nn/forward l1 x)))

(def model (MyModel 128 64))
(init/kaiming-normal! (.weight (:l1 model)) :non-linearity :relu)
(init/zeros! (.bias (:l1 model)))
```

--------------------------------

### Standard Tensor Initializers

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Initialize tensors using standard LibTorch factory methods for zeros, ones, identity matrices, ranges, and random distributions.

```clojure
;; Zeros and Ones
(t/zeros [3 3])
(t/ones [2 5])

;; Identity Matrix
(t/eye 3)

;; Range
(t/arange 10)       ;; 0 to 9
(t/arange 1 11)     ;; 1 to 10
(t/arange 0 1 0.1)  ;; 0 to 0.9 with step 0.1

;; Spacing
(t/linspace 0 10 5) ;; [0.0, 2.5, 5.0, 7.5, 10.0]
(t/logspace 0 2 3)  ;; [1.0, 10.0, 100.0] (base 10 by default)

;; Constant Value
(t/full [2 2] 3.14)

;; Random
(t/randn [3 3])     ;; Normal distribution (mean 0, std 1)
(t/rand-int 0 10 [5]) ;; Random integers between 0 and 10
(t/randperm 5)      ;; Random permutation of [0, 1, 2, 3, 4]
```

--------------------------------

### Training Step Implementation

Source: https://github.com/antlobach/clorch/blob/main/docs/optimizers.md

A complete training step function demonstrating gradient clearing, forward pass, backpropagation, and weight updates.

```clojure
(defn train-step [model optimizer batch]
  (optim/zero-grad optimizer)
  (let [pred (nn/forward model (:data batch))
        loss (F/mse-loss pred (:target batch))]
    (autograd/backward loss)
    (optim/step optimizer)
    (t/item-float loss)))
```

--------------------------------

### Initialize AdamW Optimizer

Source: https://github.com/antlobach/clorch/blob/main/docs/optimizers.md

Creates an AdamW optimizer instance, recommended for Transformer and LLM training due to decoupled weight decay.

```clojure
(def opt (optim/adamw (nn/parameters model) 
                      :lr 3e-4 
                      :weight-decay 0.01))
```

--------------------------------

### Xavier (Glorot) Initialization

Source: https://github.com/antlobach/clorch/blob/main/docs/init.md

Initializers designed for layers with symmetric activation functions.

```APIDOC
## (init/xavier-uniform! weight)
## (init/xavier-normal! weight)

### Description
Initializes weights using Xavier (Glorot) method, suitable for tanh or sigmoid activations.

### Parameters
- **weight** (Tensor) - The weight tensor to initialize.
```

--------------------------------

### Create Linear Layers

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Initialize dense layers with optional bias configuration.

```clojure
(require '[clorch.nn :as nn])

;; Linear(in_features=10, out_features=5)
(nn/linear 10 5)

;; Linear without bias
(nn/linear 10 5 :bias false)
```

--------------------------------

### Manage Device Placement

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Explicitly place tensors on CPU or CUDA devices.

```clojure
(require '[clorch.cuda :as cuda]
         '[clorch.nn :as nn])

(def device (if (cuda/available?) :cuda :cpu))
(def x (t/randn [32 128] {:device device}))
(def y (t/to existing-tensor device))
```

--------------------------------

### Apply Xavier (Glorot) initializers

Source: https://github.com/antlobach/clorch/blob/main/docs/init.md

Use these initializers for layers with symmetric activation functions like tanh or sigmoid.

```clojure
;; Xavier Uniform
(init/xavier-uniform! weight)

;; Xavier Normal
(init/xavier-normal! weight)
```

--------------------------------

### with-torch / retain!

Source: https://github.com/antlobach/clorch/blob/main/docs/memory.md

Scope-based memory management and pointer retention.

```APIDOC
## with-torch / retain!

### Description
`with-torch` releases block-local pointers except those reachable from the final result. `retain!` (or `rescue-pointers!`) keeps a pointer or pointers in a collection alive across scope closure.
```

--------------------------------

### Distribution Constructors

Source: https://github.com/antlobach/clorch/blob/main/docs/distributions.md

Functions to initialize various probability distributions.

```APIDOC
## Constructors

- `dist/normal [loc scale]` - Creates a Normal distribution.
- `dist/log-normal [loc scale]` - Creates a Log-Normal distribution.
- `dist/bernoulli [probs]` - Creates a Bernoulli distribution.
- `dist/categorical [probs]` - Creates a Categorical distribution.
- `dist/binomial [total-count probs]` - Creates a Binomial distribution.
- `dist/uniform [low high]` - Creates a Uniform distribution.
- `dist/poisson [rate]` - Creates a Poisson distribution.
- `dist/exponential [rate]` - Creates an Exponential distribution.
- `dist/cauchy [loc scale]` - Creates a Cauchy distribution.
- `dist/geometric [probs]` - Creates a Geometric distribution.
- `dist/gumbel [loc scale]` - Creates a Gumbel distribution.
- `dist/laplace [loc scale]` - Creates a Laplace distribution.
```

--------------------------------

### Format Clojure files

Source: https://github.com/antlobach/clorch/blob/main/AGENTS.md

Command to format Clojure or EDN files using cljfmt.

```bash
clj -Sdeps '{:deps {dev.weavejester/cljfmt {:mvn/version "0.13.0"}}}' -M -m cljfmt.main fix path/to/file.clj
```

--------------------------------

### Optimizer Lifecycle Methods

Source: https://github.com/antlobach/clorch/blob/main/docs/optimizers.md

Methods for managing gradient state and applying parameter updates.

```APIDOC
## optim/zero-grad
(optim/zero-grad opt)
Clears previous gradients before computing the loss.

## optim/step
(optim/step opt)
Updates model parameters after backpropagation.
```

--------------------------------

### Define and run neural networks

Source: https://github.com/antlobach/clorch/blob/main/README.md

Construct a sequential neural network and perform a forward pass.

```clojure
(require '[clorch.nn :as nn])

(def model
  (nn/sequential
    (nn/linear 10 20)
    (nn/relu)
    (nn/linear 20 1)))

(nn/forward model (t/randn [4 10]))
```

--------------------------------

### Checkpoint Management

Source: https://github.com/antlobach/clorch/blob/main/docs/distributed.md

Saves and loads model, optimizer, and training state. Rank zero handles atomic file operations, while all ranks restore state.

```clojure
(dist/save-checkpoint!
 "/checkpoints/model.pt"
 {:model model
  :optimizer optimizer
  :sampler sampler
  :scaler scaler
  :state {:epoch epoch :global-step step}})

(def training-state
  (dist/load-checkpoint!
   "/checkpoints/model.pt"
   {:model model
  :optimizer optimizer
  :sampler sampler
  :scaler scaler}))
```

--------------------------------

### Core Operations

Source: https://github.com/antlobach/clorch/blob/main/docs/distributions.md

Methods for interacting with distribution objects.

```APIDOC
## Core Operations

- `dist/sample [dist shape]` - Generates samples from the distribution given a shape.
- `dist/log-prob [dist value]` - Calculates the log probability of a value.
- `dist/mean [dist]` - Returns the mean of the distribution.
- `dist/variance [dist]` - Returns the variance of the distribution.
```

--------------------------------

### Configure Model Device and Dtype

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Move model parameters to specific hardware devices or cast them to different data types.

```clojure
(nn/to model :cuda)    ;; Move entire model to GPU
(nn/to model :float64) ;; Convert all parameters to Double
```

--------------------------------

### Inspect model summary

Source: https://github.com/antlobach/clorch/blob/main/README.md

Display the layer shapes and parameter counts for a model.

```clojure
(nn/summary custom-model [4 10])
```

--------------------------------

### Profiling Memory Usage

Source: https://github.com/antlobach/clorch/blob/main/docs/profiling.md

Commands to monitor native memory and JVM heap usage.

```bash
clojure -M test/profiler.clj
```

```bash
ps -o rss -p <PID>
```

--------------------------------

### Apply Pooling and Padding

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Utility layers for spatial pooling and various padding strategies.

```clojure
;; Pooling
(nn/max-pool2d 2)
(nn/avg-pool2d 2)
(nn/adaptive-avg-pool2d [7 7])

;; Padding
(nn/zeropad2d 1)
(nn/reflection-pad2d 2)
(nn/constant-pad2d 1 3.14)
```

--------------------------------

### Kaiming (He) Initialization

Source: https://github.com/antlobach/clorch/blob/main/docs/init.md

Initializers designed for layers with non-symmetric activations like ReLU.

```APIDOC
## (init/kaiming-uniform! weight & options)
## (init/kaiming-normal! weight & options)

### Description
Initializes weights using Kaiming (He) method, essential for deep networks.

### Parameters
- **weight** (Tensor) - The weight tensor to initialize.
- **:a** (Number) - Negative slope of the rectifier.
- **:mode** (Keyword) - :fan-in or :fan-out.
- **:non-linearity** (Keyword) - :relu, :leaky-relu, :tanh, :sigmoid, or :linear.
```

--------------------------------

### Check CUDA Availability from REPL

Source: https://github.com/antlobach/clorch/blob/main/README.md

Queries the current CUDA status and device count.

```clojure
(require '[clorch.cuda :as cuda]
         '[clorch.torch :as t])

{:available (cuda/available?)
 :devices (cuda/device-count)}
;; => {:available true, :devices 2}
```

--------------------------------

### Create Recurrent Layers

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Initialize LSTM or GRU layers with support for multiple layers and bidirectionality.

```clojure
;; LSTM(input_size=10, hidden_size=20)
(nn/lstm 10 20)

;; Bidirectional with multiple layers
(nn/gru 10 20 :num-layers 2 :bidirectional true :dropout 0.1)
```

--------------------------------

### ELU Activation

Source: https://github.com/antlobach/clorch/blob/main/docs/activations.md

Exponential Linear Unit implementation.

```clojure
(nn/elu 1.0)
(F/elu x 1.0)
```

--------------------------------

### Integrate Autograd in Training Loops

Source: https://github.com/antlobach/clorch/blob/main/docs/autograd.md

Standard workflow for updating model parameters involves clearing gradients, performing backpropagation, and stepping the optimizer.

```clojure
(optim/zero-grad optimizer) ;; Clear previous gradients
(autograd/backward loss)  ;; Compute current gradients
(optim/step optimizer)    ;; Update weights
```

--------------------------------

### Manage native memory with with-torch

Source: https://github.com/antlobach/clorch/blob/main/README.md

Wrap batch processing or generation steps in with-torch to ensure native memory is released correctly after the scope completes.

```clojure
(doseq [batch dataloader]
  (let [loss-value
        (t/with-torch
          (let [loss (train-step model optimizer batch)]
            (t/item-float loss)))]
    (println "Loss:" loss-value)))
```

--------------------------------

### Initialize process group and collective operations

Source: https://github.com/antlobach/clorch/blob/main/docs/distributed.md

Initializes a process group using the specified backend and performs collective operations. Collectives mutate tensors in place and require consistent ordering across all ranks.

```clojure
(require '[clorch.distributed :as dist])

(dist/with-process-group {:backend :nccl}
  (dist/all-reduce! tensor {:op :sum})
  (dist/barrier!))
```

--------------------------------

### Generate Model Summary

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Perform a dry-run forward pass to trace execution and display layer output shapes and parameter counts.

```clojure
;; 1. Simple input shape
(nn/summary model [1 784])

;; 2. Complex input (e.g. for LLMs or models with multiple arguments)
(nn/summary gpt {:idx (torch/zeros [8 4] {:dtype :int64}) 
                 :mask (torch/ones [4 4])})
```

--------------------------------

### Apply Kaiming (He) initializers

Source: https://github.com/antlobach/clorch/blob/main/docs/init.md

Use these initializers for layers with non-symmetric activations like ReLU or Leaky ReLU.

```clojure
;; Kaiming Uniform
(init/kaiming-uniform! weight :non-linearity :relu)

;; Kaiming Normal
(init/kaiming-normal! weight :non-linearity :leaky-relu)
```

--------------------------------

### Create custom models with defmodel

Source: https://github.com/antlobach/clorch/blob/main/README.md

Define custom neural network architectures using the defmodel macro.

```clojure
(require '[clorch.nn.functional :as F])

(nn/defmodel CustomMLP [in hidden out]
  [l1 (nn/linear in hidden)
   l2 (nn/linear hidden out)]
  (forward [x]
    (nn/forward l2 (F/relu (nn/forward l1 x)))))

(def custom-model (CustomMLP 10 32 1))
(t/size (nn/forward custom-model (t/randn [4 10]))) ; => [4 1]
```

--------------------------------

### Tensor Creation

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Methods for creating tensors from Clojure data structures or using standard LibTorch initializers.

```APIDOC
## (t/tensor data & options)

### Description
Creates a new tensor from vectors, nested vectors, or sequences.

### Parameters
- **data** (vector/sequence) - Required - The data to initialize the tensor with.
- **options** (map) - Optional - Configuration map including :dtype (e.g., :float64) or :requires-grad (boolean).

## (t/zeros shape), (t/ones shape), (t/eye n), (t/arange start end step), (t/linspace start end steps), (t/full shape value), (t/randn shape)

### Description
Standard factory methods for creating tensors with specific values or distributions.
```

--------------------------------

### Launch distributed worker jobs

Source: https://github.com/antlobach/clorch/blob/main/docs/distributed.md

Initiates a distributed job using a namespace-qualified worker function and monitors its status.

```clojure
(require '[clorch.distributed :as dist])

(def job
  (dist/launch!
   {:nproc-per-node 2
    :devices [0 1]
    :main 'my.training/train-worker
    :args {:epochs 10}
    :timeout-ms 300000}))

(dist/job-status job)
(dist/await-job! job)
(dist/job-logs job 0)
```

--------------------------------

### gc!

Source: https://github.com/antlobach/clorch/blob/main/docs/memory.md

Triggers a manual request for JVM garbage collection and finalization.

```APIDOC
## gc!

### Description
Calls `System/gc` and `System/runFinalization`. Use it for interactive diagnostics or recovery, not as normal loop memory management.

### Usage
(t/gc!)
```

--------------------------------

### Perform Backward Pass in Training Loop

Source: https://github.com/antlobach/clorch/blob/main/docs/losses.md

Demonstrates calculating loss and triggering the autograd backward pass.

```clojure
(def loss (F/cross-entropy pred target))
(autograd/backward loss)
```

--------------------------------

### nn/to

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Moves the model to a specific device or converts parameters to a specific data type.

```APIDOC
## (nn/to model target)

### Description
Transfers the model to a device or casts parameters to a specific dtype.

### Parameters
- **model** (Object) - Required - The model instance.
- **target** (Keyword) - Required - The target device (e.g., :cuda) or dtype (e.g., :float64).
```

--------------------------------

### PReLU Activation

Source: https://github.com/antlobach/clorch/blob/main/docs/activations.md

Parametric ReLU usage, noting that functional form requires manual weight management.

```clojure
;; Stateful
(nn/prelu {:num-parameters 1 :init 0.25})

;; Functional (requires manual weight management)
(F/prelu x weight)
```

--------------------------------

### Basic Initializers

Source: https://github.com/antlobach/clorch/blob/main/docs/init.md

Functions to modify tensor values in-place using basic statistical distributions or constants.

```APIDOC
## (init/constant! tensor value)
## (init/ones! tensor)
## (init/zeros! tensor)
## (init/uniform! tensor a b)
## (init/normal! tensor mean std)

### Description
Modifies the input tensor in-place with specified values or distributions.

### Parameters
- **tensor** (Tensor) - The tensor to initialize.
- **value** (Number) - The constant value to set.
- **a** (Number) - Lower bound for uniform distribution.
- **b** (Number) - Upper bound for uniform distribution.
- **mean** (Number) - Mean of the normal distribution.
- **std** (Number) - Standard deviation of the normal distribution.
```

--------------------------------

### nn/linear

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Creates a linear (dense) layer.

```APIDOC
## nn/linear

### Description
Creates a linear (dense) layer with specified input and output features.

### Signature
(nn/linear in_features out_features & {:keys [bias]})

### Parameters
- **in_features** (int) - Number of input features
- **out_features** (int) - Number of output features
- **bias** (boolean) - Optional, defaults to true. Set to false to disable bias.
```

--------------------------------

### Performing core distribution operations

Source: https://github.com/antlobach/clorch/blob/main/docs/distributions.md

Common operations including sampling, log-probability calculation, and retrieving distribution statistics.

```clojure
(def d (dist/normal 0.0 1.0))

(dist/sample d [4 3])   ;; sample-shape
(dist/log-prob d 0.0)   ;; tensor or scalar
(dist/mean d)
(dist/variance d)
```

--------------------------------

### Manage Model Lifecycle Modes

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Toggle between training and evaluation modes to control behaviors like dropout and batch normalization.

```clojure
(nn/train model true)  ;; Set to training mode (enables dropout/batchnorm updates)
(nn/train model false) ;; Set to evaluation mode
```

--------------------------------

### 1D Tensor Indexing in PyTorch and Clorch

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing.md

Basic indexing for 1D tensors using PyTorch and Clorch.

```python
# PyTorch
x = torch.tensor([10, 11, 12, 13, 14])
x[0]      # → tensor(10)
x[-1]     # → tensor(14)
```

```clojure
;; Clorch
(def x (torch/tensor [10 11 12 13 14]))
(torch/ix x 0)       ;; → 10.0
(torch/ix x -1)      ;; → 14.0
```

--------------------------------

### Enable Gradients for Tensors

Source: https://github.com/antlobach/clorch/blob/main/docs/autograd.md

Tensors must be initialized with :requires-grad true to be tracked by the autograd engine.

```clojure
(require '[clorch.torch :as t]
         '[clorch.autograd :as autograd])

(def x (t/tensor [2.0] {:requires-grad true}))
(def y (t/pow x 2)) ;; y = x^2
```

--------------------------------

### Perform Interpolation and Padding

Source: https://github.com/antlobach/clorch/blob/main/docs/functional.md

Resize tensors or apply padding modes to input data.

```clojure
;; Resize image-like tensors
(F/interpolate input :size [224 224] :mode :nearest)

;; Advanced Padding
;; pad is a vector of [left right top bottom ...]
(F/pad input [1 1 1 1] :mode :reflect)
```

--------------------------------

### Define Sequential Models

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Stack layers linearly to create a feed-forward model.

```clojure
(def model (nn/sequential
             (nn/linear 10 20)
             (nn/relu)
             (nn/dropout 0.5)
             (nn/linear 20 1)))
```

--------------------------------

### Access and Load Model Parameters

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Retrieve model parameters as a vector or state dictionary, and load weights from a saved state.

```clojure
;; Get all parameters as a native TensorVector
(nn/parameters model)

;; Get a nested map of all weights/biases
(nn/state-dict model)

;; Load weights from a state dict
(nn/load-state-dict model saved-sd)
```

--------------------------------

### Distributed Data Sampling

Source: https://github.com/antlobach/clorch/blob/main/docs/distributed.md

Configures a deterministic, disjoint sample stream for each rank. Call set-epoch! before each epoch to ensure unique permutations.

```clojure
(require '[clorch.data :as data])

(def sampler
  (data/distributed-sampler
   dataset-size
   {:num-replicas (dist/world-size)
    :rank (dist/rank)
    :seed 1337
    :shuffle? true
    :drop-last? false}))

(data/set-epoch! sampler epoch)
(doseq [indices (partition-all batch-size (data/sample-indices sampler))]
  (train-batch! indices))
```

--------------------------------

### Run local distributed training

Source: https://github.com/antlobach/clorch/blob/main/docs/distributed.md

Executes a distributed training job locally across specified CUDA devices.

```clojure
(require '[distributed-training :as training])

(training/run-local!
 [0 1]
 {:epochs 4
  :sample-count 1024
  :batch-size 32
  :accumulation 2
  :precision :bfloat16
  :checkpoint-path "/tmp/clorch-ddp.pt"})
```

--------------------------------

### Implement a deterministic training loop with with-torch

Source: https://github.com/antlobach/clorch/blob/main/docs/memory.md

Use with-torch to scope temporary tensors within a training loop, ensuring native memory is reclaimed after each iteration.

```clojure
(require '[clorch.torch :as t]
         '[clorch.nn :as nn]
         '[clorch.nn.functional :as F]
         '[clorch.autograd :as autograd]
         '[clorch.optim :as optim])

(let [model (create-model)
      optimizer (optim/adam (nn/parameters model))]
  (doseq [{:keys [data target]} dataloader]
    (let [loss-value
          (t/with-torch
            (optim/zero-grad optimizer)
            (let [prediction (nn/forward model data)
                  loss (F/cross-entropy prediction target)]
              (autograd/backward loss)
              (optim/step optimizer)
              (t/item-float loss)))]
      (println "Loss:" loss-value))))
```

--------------------------------

### Apply Normalization Layers

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Standard normalization layers including batch, layer, RMS, and group normalization.

```clojure
(nn/batchnorm2d 64)
(nn/layernorm 128)
(nn/rmsnorm 512) ;; High-performance RMSNorm for LLMs
(nn/groupnorm 8 64)
```

--------------------------------

### GLU Activation

Source: https://github.com/antlobach/clorch/blob/main/docs/activations.md

Gated Linear Unit implementation.

```clojure
(nn/glu -1)
(F/glu x -1)
```

--------------------------------

### Calculate Smooth L1 Loss in Clojure

Source: https://github.com/antlobach/clorch/blob/main/docs/losses.md

Huber loss implementation that combines MSE and L1 for stability and robustness.

```clojure
(F/smooth-l1-loss input target)
```

--------------------------------

### Train/Test Split

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing-examples.md

Divide a dataset into training and testing subsets using a split point.

```clojure
(def data (torch/tensor (range 100)))
(def split-point 80)

(def train (torch/ix data [0 split-point]))
(def test (torch/ix data [split-point nil]))
```

--------------------------------

### Perform tensor operations and autograd

Source: https://github.com/antlobach/clorch/blob/main/README.md

Create tensors and compute gradients using the autograd module.

```clojure
(require '[clorch.torch :as t]
         '[clorch.autograd :as autograd])

(def x (t/tensor [2.0] {:requires-grad true}))
(def y (t/pow x 3))

(autograd/backward y)
(autograd/grad x) ; => [12.0]
```

--------------------------------

### Define Custom Models with defmodel

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Create reusable model constructors with custom forward passes.

```clojure
(require '[clorch.torch :as t]
         '[clorch.nn :as nn]
         '[clorch.nn.functional :as F])

(nn/defmodel MyClassifier [in-dim hidden-dim num-classes]
  [l1 (nn/linear in-dim hidden-dim)
   l2 (nn/linear hidden-dim num-classes)]
  (forward [x]
    (nn/forward l2 (F/relu (nn/forward l1 x)))))

(def classifier (MyClassifier 784 256 10))
(def logits (nn/forward classifier (t/randn [32 784])))
(t/size logits) ; => [32 10]
```

--------------------------------

### Create Convolutional Layers

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Define 2D convolutions and transpose variants with support for stride, padding, and dilation.

```clojure
;; Conv2d(in_channels=3, out_channels=16, kernel_size=3)
(nn/conv2d 3 16 3)

;; Advanced parameters
(nn/conv2d 3 16 [3 5] :stride 2 :padding 1 :dilation 2 :groups 1)

;; Transpose Convolution
(nn/conv-transpose2d 16 3 3 :stride 2)
```

--------------------------------

### Interpolation and Padding

Source: https://github.com/antlobach/clorch/blob/main/docs/functional.md

Functional interfaces for tensor resizing and padding.

```APIDOC
## (F/interpolate input & {:keys [size mode]})
## (F/pad input pad & {:keys [mode]})

### Description
Provides utilities for resizing tensors and applying padding.
```

--------------------------------

### nn/summary

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Performs a dry run of the model to display layer shapes and parameter counts.

```APIDOC
## (nn/summary model input)

### Description
Traces the model execution to provide a summary of output shapes and parameter counts.

### Parameters
- **model** (Object) - Required - The model instance.
- **input** (Vector/Map) - Required - The input shape or map of arguments for the forward pass.
```

--------------------------------

### Mixed Precision Training

Source: https://github.com/antlobach/clorch/blob/main/docs/distributed.md

Uses grad-scaler and autocast to manage float16 precision. Autocast automatically restores thread settings after execution.

```clojure
(require '[clorch.amp :as amp])

(def scaler (amp/grad-scaler {:initial-scale 65536.0}))

(let [loss (amp/autocast {:device :cuda :dtype :float16}
             (compute-loss parallel-model batch))]
  (amp/backward! scaler loss)
  (ddp/optimizer-step! parallel-model optimizer {:scaler scaler}))
```

--------------------------------

### Activation Functions API

Source: https://github.com/antlobach/clorch/blob/main/docs/activations.md

Overview of available activation functions in Clorch, categorized by their implementation in the nn and functional namespaces.

```APIDOC
## Activation Functions API

### Description
Clorch provides activation functions in two namespaces: `clorch.nn` for stateful modules and `clorch.nn.functional` for functional operations.

### Standard Activations
- **ReLU**: `(nn/relu)` / `(F/relu x)`
- **Sigmoid**: `(nn/sigmoid)` / `(F/sigmoid x)`
- **Tanh**: `(nn/tanh)` / `(F/tanh x)`
- **GeLU**: `(nn/gelu)` / `(F/gelu x)`
- **SiLU**: `(nn/silu)` / `(F/silu x)`
- **Softmax**: `(nn/softmax dim)` / `(F/softmax x dim)`

### Enhanced & Specialized
- **LeakyReLU**: `(nn/leaky-relu slope)` / `(F/leaky-relu x slope)`
- **PReLU**: `(nn/prelu {:num-parameters n :init val})` / `(F/prelu x weight)`
- **ELU**: `(nn/elu alpha)` / `(F/elu x alpha)`
- **GLU**: `(nn/glu dim)` / `(F/glu x dim)`

### Shrinkage Functions
- **Hardshrink**: `(nn/hardshrink lambda)`
- **Softshrink**: `(nn/softshrink lambda)`
- **Tanhshrink**: `(nn/tanhshrink)`

### Modern & Experimental
- **Mish**: `(nn/mish)` / `(F/mish x)`
- **Hardswish**: `(nn/hardswish)` / `(F/hardswish x)`
- **Hardsigmoid**: `(nn/hardsigmoid)` / `(F/hardsigmoid x)`
- **Hardtanh**: `(nn/hardtanh min max)` / `(F/hardtanh x min max)`
```

--------------------------------

### nn/conv2d

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Creates a 2D convolutional layer.

```APIDOC
## nn/conv2d

### Description
Creates a 2D convolutional layer.

### Signature
(nn/conv2d in_channels out_channels kernel_size & {:keys [stride padding dilation groups]})

### Parameters
- **in_channels** (int) - Number of input channels
- **out_channels** (int) - Number of output channels
- **kernel_size** (int or vector) - Size of the convolving kernel
```

--------------------------------

### nn/load-state-dict

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Loads weights into the model from a provided state dictionary.

```APIDOC
## (nn/load-state-dict model saved-sd)

### Description
Updates the model parameters using the provided state dictionary.

### Parameters
- **model** (Object) - Required - The model instance.
- **saved-sd** (Map) - Required - The state dictionary to load.
```

--------------------------------

### Trigger JVM garbage collection

Source: https://github.com/antlobach/clorch/blob/main/docs/memory.md

Calls System/gc and System/runFinalization for diagnostics. Do not use this for standard loop memory management as it cannot release reachable tensors.

```clojure
(t/gc!)
```

--------------------------------

### Basic Tensor Slicing

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing.md

Perform standard range-based slicing on tensors.

```python
# PyTorch
y = torch.arange(10)  # [0,1,2,3,4,5,6,7,8,9]
y[2:5]    # → tensor([2, 3, 4])
y[:4]     # → tensor([0, 1, 2, 3])
y[6:]     # → tensor([6, 7, 8, 9])
```

```clojure
;; Clorch
(def y (torch/tensor (range 10)))
(torch/ix y [2 5])    ;; → [2.0, 3.0, 4.0]
(torch/ix y [0 4])    ;; → [0.0, 1.0, 2.0, 3.0]
(torch/ix y [6 10])   ;; → [6.0, 7.0, 8.0, 9.0]
```

--------------------------------

### release!

Source: https://github.com/antlobach/clorch/blob/main/docs/memory.md

Immediately deallocates a pointer or recursively releases pointers in map values and collections.

```APIDOC
## release!

### Description
Immediately deallocates a pointer or recursively releases pointers in map values and collections. After release, the wrapper is invalid and must not be used.

### Usage
(t/release! x)
```

--------------------------------

### Clorch Project Dependency Configuration

Source: https://github.com/antlobach/clorch/blob/main/docs/index.md

Add this dependency to your deps.edn file to include Clorch in your Clojure project.

```clojure
{:paths ["src"]
 :deps {io.github.antlobach/clorch
        {:git/tag "v0.1.0"
         :git/sha "25a6b1005b7ada7259aaca680e9507d7eb4b03ac"}}}
```

--------------------------------

### Mathematical Operations

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Element-wise math, linear algebra, and reduction operations.

```APIDOC
## (t/add a b), (t/sub a b), (t/mul a b), (t/div a b)

### Description
Performs element-wise arithmetic operations on tensors or between a tensor and a scalar.

## (t/matmul a b), (t/mm a b), (t/outer a b)

### Description
Linear algebra operations including matrix multiplication and outer products.

## (t/sum x dim), (t/mean x dim), (t/max x dim), (t/min x dim)

### Description
Reduces a tensor along a dimension or globally. Supports :keepdim option.
```

--------------------------------

### Sampling & Search

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Operations for searching tensor values and sampling from distributions.

```APIDOC
## (t/argmax x), (t/argmin x), (t/topk x k), (t/multinomial probs num-samples), (t/top-p probs p)

### Description
Methods for finding indices of specific values or performing probabilistic sampling, including Nucleus (top-p) sampling.
```

--------------------------------

### Apply Dropout Regularization

Source: https://github.com/antlobach/clorch/blob/main/docs/functional.md

Use dropout or spatial dropout to zero out elements based on a probability during training.

```clojure
;; p is the probability of an element to be zeroed
(F/dropout x 0.5 :training? true)

;; Spatial Dropout
(F/dropout2d x 0.5 :training? true)
```

--------------------------------

### Invoke Models

Source: https://github.com/antlobach/clorch/blob/main/docs/nn.md

Models generated by defmodel are callable directly.

```clojure
(classifier (t/randn [32 784]))
```

--------------------------------

### Nucleus (Top-p) Sampling

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Filter probability mass to the top p percentile for sampling.

```clojure
(t/top-p (t/tensor [[0.1 0.8 0.1]]) 0.9)
```

--------------------------------

### Calculate Binary Cross Entropy in Clojure

Source: https://github.com/antlobach/clorch/blob/main/docs/losses.md

Loss functions for binary classification, including a numerically stable version that combines sigmoid and BCE.

```clojure
;; Expects probabilities (after sigmoid)
(F/bce-loss input target)

;; More numerically stable: combines sigmoid + BCE
(F/bce-with-logits-loss input target)
```

--------------------------------

### Linear Algebra Operations

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Perform matrix multiplication and outer products.

```clojure
(def m1 (t/randn [3 5]))
(def m2 (t/randn [5 2]))

(t/matmul m1 m2) ;; [3 2]
(t/mm m1 m2)     ;; Shorthand for matmul

(def v1 (t/tensor [1 2 3]))
(def v2 (t/tensor [4 5 6]))
(t/outer v1 v2)  ;; Outer product
```

--------------------------------

### Perform Element-wise Math

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Execute basic arithmetic operations on tensors, including scalar broadcasting.

```clojure
(def a (t/tensor [1 2 3]))
(def b (t/tensor [4 5 6]))

(t/add a b) ;; [5, 7, 9]
(t/sub a b) ;; [-3, -3, -3]
(t/mul a b) ;; [4, 10, 18]
(t/div a b) ;; [0.25, 0.4, 0.5]

;; Scalar broadcasting
(t/add a 10) ;; [11, 12, 13]
```

--------------------------------

### Multi-dimensional Tensor Indexing in PyTorch and Clorch

Source: https://github.com/antlobach/clorch/blob/main/docs/slicing.md

Indexing and slicing operations for multi-dimensional tensors in PyTorch and Clorch.

```python
# PyTorch
x = torch.tensor([[1, 2, 3], 
                  [4, 5, 6], 
                  [7, 8, 9]])
x[0, 1]    # → tensor(2)
x[0]       # → tensor([1, 2, 3])
x[:, 1]    # → tensor([2, 5, 8])
```

```clojure
;; Clorch
(def x (torch/tensor [[1 2 3] 
                      [4 5 6] 
                      [7 8 9]]))
(torch/ix x 0 1)      ;; → 2.0
(torch/ix x 0)        ;; → [1.0, 2.0, 3.0]
(torch/ix x :all 1)   ;; → [2.0, 5.0, 8.0]
```

--------------------------------

### Calculate Cross Entropy Loss in Clojure

Source: https://github.com/antlobach/clorch/blob/main/docs/losses.md

Combines LogSoftmax and NLLLoss for multi-class classification.

```clojure
(F/cross-entropy logits targets)
```

--------------------------------

### Create Tensors from Clojure Data

Source: https://github.com/antlobach/clorch/blob/main/docs/tensors.md

Create tensors from vectors or sequences, with options for specifying data types and enabling gradients.

```clojure
(require '[clorch.torch :as t])

;; 1D tensor
(t/tensor [1 2 3])

;; 2D tensor
(t/tensor [[1 2] [3 4]])

;; Specify dtype
(t/tensor [1 2 3] {:dtype :float64})

;; Enable gradients
(t/tensor [1.0 2.0] {:requires-grad true})
```