Clorch maps closely to PyTorch’s package structure. Each Clojure namespace corresponds to a PyTorch module, making it straightforward to translate Python patterns. This page lists every namespace, its purpose, and the key public symbols it provides. Expand each accordion for the full function catalogue with brief descriptions.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.
| PyTorch | Clorch Namespace |
|---|---|
torch | clorch.torch |
torch.autograd | clorch.autograd |
torch.nn | clorch.nn |
torch.nn.functional | clorch.nn.functional |
torch.nn.init | clorch.nn.init |
torch.nn.parallel.DistributedDataParallel | clorch.nn.parallel |
torch.optim | clorch.optim |
torch.amp | clorch.amp |
torch.distributed | clorch.distributed |
torch.utils.data | clorch.data |
torch.cuda | clorch.cuda |
torch.distributions | clorch.distributions |
torch.linalg | clorch.linalg |
| (eDSL) | clorch.einsum |
clorch.torch — Core Tensor Operations
The primary namespace for creating, transforming, and inspecting tensors. It mirrors torch.* top-level functions, extended with Clojure-idiomatic memory-management utilities and LLM-specific primitives.
Tensor creation
Tensor creation
| Function | Description |
|---|---|
tensor | Create a tensor from a Clojure data structure or scalar, with optional :dtype and :device |
randn | Return a tensor filled with values drawn from N(0,1) |
rand | Return a tensor filled with values drawn from Uniform(0,1) |
rand-int | Return a tensor of random integers in [low, high) |
randperm | Return a random permutation of integers from 0 to n−1 |
zeros | Return a tensor filled with zeros |
ones | Return a tensor filled with ones |
empty | Return an uninitialized tensor of the given shape |
full | Return a tensor filled with a scalar fill value |
eye | Return a 2-D identity matrix |
arange | Return evenly spaced values in a half-open interval |
linspace | Return a 1-D tensor of evenly spaced values between start and end |
logspace | Return a 1-D tensor of values spaced logarithmically |
bernoulli | Return a tensor of Bernoulli-sampled 0/1 values |
manual-seed | Set the random seed for reproducibility |
Core math operations
Core math operations
| Function | Description |
|---|---|
add | Element-wise addition |
sub | Element-wise subtraction |
mul | Element-wise multiplication |
div | Element-wise division |
pow | Element-wise exponentiation |
sqrt | Element-wise square root |
rsqrt | Element-wise reciprocal square root |
abs | Element-wise absolute value |
neg | Element-wise negation |
exp | Element-wise natural exponential |
log | Element-wise natural logarithm |
sin | Element-wise sine |
cos | Element-wise cosine |
tanh | Element-wise hyperbolic tangent |
softmax | Softmax normalization along a given dimension |
clamp / clip | Clamp tensor values to a min/max range |
matmul | Matrix multiplication with broadcasting |
mm | 2-D matrix multiplication (no broadcast) |
bmm | Batched matrix multiplication |
dot | Dot product of two 1-D tensors |
inner | Inner product (generalized dot) |
outer | Outer product of two 1-D tensors |
Reduction operations
Reduction operations
| Function | Description |
|---|---|
sum | Sum of all elements, or along a dimension |
mean | Mean of all elements, or along a dimension |
max | Maximum value (or values + indices along a dim) |
min | Minimum value (or values + indices along a dim) |
argmax | Index of the maximum value along a dimension |
argmin | Index of the minimum value along a dimension |
topk | Top-k values and their indices |
sort | Sort tensor values along a dimension |
argsort | Indices that sort a tensor along a dimension |
gather | Gather values along an axis using an index tensor |
cumsum | Cumulative sum along a dimension |
logsumexp | Log of the sum of exponentials |
all | True if all elements satisfy a condition |
any | True if any element satisfies a condition |
nonzero | Indices of non-zero elements |
count-nonzero | Number of non-zero elements |
Shape operations
Shape operations
| Function | Description |
|---|---|
size | Return the shape as a vector; optionally query a single dimension |
reshape | Return a tensor with a new shape (may copy) |
view | Return a tensor with a new shape sharing storage |
transpose | Swap two dimensions |
T | Transpose shorthand (reverses all dimensions) |
swapaxes | Alias for transpose |
movedim | Move a dimension to a new position |
unsqueeze | Insert a size-1 dimension at the given position |
flatten | Collapse dimensions into one |
unflatten | Expand one dimension into multiple |
expand | Broadcast a tensor to a larger shape |
tile | Tile a tensor by repeating it along dimensions |
repeat | Repeat tensor data along each dimension |
cat | Concatenate tensors along an existing dimension |
stack | Stack tensors along a new dimension |
unbind | Remove a dimension, returning its slices as a seq |
split | Split a tensor into chunks along a dimension |
chunk | Split a tensor into a fixed number of chunks |
Indexing and slicing
Indexing and slicing
| Function | Description |
|---|---|
ix | Ergonomic Python-style indexer supporting ranges, negative indices, ellipsis, and tensor indices |
select | Select a single slice along a dimension at a given index |
index-select | Select slices along a dimension using an index tensor |
masked-fill | Fill positions where a boolean mask is true with a scalar |
take-along-dim | Gather values using an index tensor, broadcasting along non-indexed dims |
scatter-reduce | Scatter-reduce values into a target tensor |
Comparison operations
Comparison operations
| Function | Description |
|---|---|
eq | Element-wise equality |
gt | Element-wise greater-than |
lt | Element-wise less-than |
ge | Element-wise greater-than-or-equal |
le | Element-wise less-than-or-equal |
where | Select elements from two tensors based on a condition |
isclose | Element-wise approximate equality within tolerances |
allclose | True if all elements are approximately equal |
isnan | Element-wise NaN check |
isinf | Element-wise infinity check |
isfinite | Element-wise finite-value check |
Linear algebra (linalg-* prefix)
Linear algebra (linalg-* prefix)
| Function | Description |
|---|---|
linalg-cholesky | Cholesky decomposition of a positive-definite matrix |
linalg-inv | Matrix inverse |
linalg-det | Matrix determinant |
linalg-svd | Singular value decomposition |
linalg-qr | QR decomposition |
linalg-solve | Solve a system of linear equations AX = B |
linalg-lstsq | Least-squares solution |
linalg-eig | Eigenvalue decomposition (general matrix) |
linalg-eigh | Eigenvalue decomposition (symmetric/Hermitian matrix) |
linalg-norm | Matrix or vector norm |
Dtype and device utilities
Dtype and device utilities
| Function | Description |
|---|---|
dtype | Return the element type of a tensor |
to | Move a tensor to a device or cast to a dtype |
to-float | Cast a tensor to float32 |
to-long | Cast a tensor to int64 |
item-float | Extract a scalar tensor’s value as a Java double |
tprint | Pretty-print a tensor to stdout |
Native memory management
Native memory management
| Function / Macro | Description |
|---|---|
with-torch | Macro: allocate tensors inside a scope; release all on exit |
retain! | Prevent a tensor from being released when its scope exits |
release! | Manually release a tensor’s native memory |
start-session! | Begin a long-lived REPL memory session |
stop-session! | End a REPL session and release all session-owned tensors |
gc! | Trigger native memory collection |
LLM-specific primitives
LLM-specific primitives
| Function | Description |
|---|---|
precompute-rope-freqs | Precompute cosine/sine frequency tensors for rotary position embeddings given head dimension and sequence length |
apply-rope | Apply precomputed RoPE frequencies to query or key tensors |
top-p | Filter logits to the nucleus (top-p) token set |
multinomial | Sample indices from a probability distribution |
Serialization and JIT
Serialization and JIT
| Function | Description |
|---|---|
save | Serialize a tensor or model to a file |
load | Deserialize a tensor or model from a file |
jit-save | Save a TorchScript module to a file |
jit-load | Load a TorchScript module from a file |
jit-forward | Run a forward pass through a loaded TorchScript module |
clorch.autograd — Automatic Differentiation
Provides the five core autograd operations. Mirrors torch.autograd and the .grad attribute pattern from PyTorch.
Autograd functions
Autograd functions
| Function / Macro | Description |
|---|---|
backward | Compute gradients by running the reverse-mode pass from a scalar loss |
grad | Return the accumulated gradient tensor for a leaf tensor |
detach | Return a new tensor sharing storage but detached from the computation graph |
no-grad | Macro: disable gradient tracking for all operations in the body |
set-requires-grad | Enable or disable gradient accumulation on a tensor in place |
clorch.nn — Neural Network Modules
The module system, layer zoo, and model-building macros. Mirrors torch.nn.
Module protocol and lifecycle
Module protocol and lifecycle
| Symbol | Description |
|---|---|
IModule | Protocol defining -forward, -train, and -to for all module types |
forward | Call a module’s forward pass |
train | Switch a module between training and evaluation mode |
to | Move a module’s parameters and buffers to a device or dtype |
parameters | Return a flat list of all trainable parameters |
named-parameters | Return a list of [name tensor] pairs for all parameters |
zero-grad | Zero the .grad fields of all module parameters |
state-dict | Return a map of parameter names to tensors |
load-state-dict | Load a state-dict map into a module in place |
save-weights | Serialize a module’s weights to a file |
load-weights | Load serialized weights into a module from a file |
summary | Print a table of layer output shapes and parameter counts |
apply | Recursively apply a function to every sub-module |
modules | Return a flat seq of all sub-modules |
clip-grad-norm! | Clip the norm of all parameter gradients |
Model building
Model building
| Symbol | Description |
|---|---|
defmodel | Macro: define a named module record with constructor args, registered sub-modules, and a forward form |
sequential | Create a module that chains other modules in order |
generate | Autoregressive token generation loop |
Linear and recurrent layers
Linear and recurrent layers
| Function | Description |
|---|---|
linear | Fully connected linear layer (weight + optional bias) |
bilinear | Bilinear transformation layer |
rnn | Elman recurrent layer |
lstm | Long short-term memory layer |
gru | Gated recurrent unit layer |
embedding | Learnable embedding lookup table |
embedding-from-pretrained | Initialize an embedding from a pretrained weight tensor |
Convolutional layers
Convolutional layers
| Function | Description |
|---|---|
conv1d | 1-D convolution |
conv2d | 2-D convolution |
conv3d | 3-D convolution |
conv-transpose1d | 1-D transposed convolution |
conv-transpose2d | 2-D transposed convolution |
conv-transpose3d | 3-D transposed convolution |
Normalization layers
Normalization layers
| Function | Description |
|---|---|
batchnorm1d | Batch normalization over 2-D or 3-D input |
batchnorm2d | Batch normalization over 4-D input |
batchnorm3d | Batch normalization over 5-D input |
layernorm | Layer normalization |
groupnorm | Group normalization |
instancenorm1d | Instance normalization over sequences |
instancenorm2d | Instance normalization over spatial feature maps |
instancenorm3d | Instance normalization over volumetric inputs |
rmsnorm | Root-mean-square layer normalization (preferred for LLMs) |
Pooling layers
Pooling layers
| Function | Description |
|---|---|
max-pool1d / max-pool2d / max-pool3d | Max pooling for 1-D, 2-D, and 3-D inputs |
avg-pool1d / avg-pool2d / avg-pool3d | Average pooling for 1-D, 2-D, and 3-D inputs |
adaptive-max-pool1d/2d/3d | Adaptive max pooling to a target output size |
adaptive-avg-pool1d/2d/3d | Adaptive average pooling to a target output size |
Activation layers
Activation layers
| Function | Description |
|---|---|
relu | Rectified linear unit |
relu6 | ReLU clamped at 6 |
gelu | Gaussian error linear unit |
silu | Sigmoid linear unit (Swish) |
mish | Mish activation |
tanh | Hyperbolic tangent activation module |
sigmoid | Logistic sigmoid activation |
leaky-relu | Leaky ReLU with configurable negative slope |
elu / selu / celu | Exponential linear unit variants |
hardswish / hardsigmoid / hardtanh | Hard approximations of smooth activations |
softplus / softsign | Smooth softplus and softsign units |
log-softmax | Log-softmax along a dimension |
log-sigmoid | Log-sigmoid activation |
Dropout layers
Dropout layers
| Function | Description |
|---|---|
dropout | Standard dropout (randomly zero elements) |
dropout2d | Channel-wise dropout for 2-D feature maps |
alpha-dropout | Alpha-dropout maintaining self-normalizing properties |
feature-alpha-dropout | Feature-level alpha-dropout |
LLM custom modules
LLM custom modules
| Symbol | Description |
|---|---|
GroupedQueryAttention | Multi-head attention with separate Q and K/V head counts (GQA); supports optional KV cache and RoPE frequencies |
SwiGLU | SwiGLU feed-forward block (two-gate linear projection with SiLU activation) |
Utility layers
Utility layers
| Function | Description |
|---|---|
flatten | Module form of torch/flatten |
unflatten | Module form of torch/unflatten |
identity | Pass-through module |
cosine-similarity | Cosine similarity module |
pairwise-distance | Pairwise distance module |
pixel-shuffle | Rearrange elements for sub-pixel upsampling |
pixel-unshuffle | Inverse of pixel-shuffle |
upsample | Upsample a tensor using nearest, bilinear, or bicubic interpolation |
clorch.nn.functional — Stateless Functional API
Stateless function counterparts for all clorch.nn layer types. Use these when you want to pass weights explicitly rather than maintain module objects.
Functional operations
Functional operations
| Function | Description |
|---|---|
linear | Linear transform: x @ W.T + b |
conv1d / conv2d / conv3d | Functional convolution with explicit weight and bias |
batch-norm | Batch normalization with explicit running stats |
layer-norm | Layer normalization with explicit weight and bias |
group-norm | Group normalization with explicit weight and bias |
relu / gelu / silu / sigmoid / tanh | Functional activation functions |
softmax / log-softmax | Softmax and log-softmax along a dimension |
max-pool1d / max-pool2d | Functional max pooling |
avg-pool1d / avg-pool2d | Functional average pooling |
interpolate | Resize a tensor using various interpolation modes |
pad | Pad a tensor with a constant, reflection, or replication |
pixel-shuffle / pixel-unshuffle | Functional sub-pixel operations |
cosine-similarity | Cosine similarity between two tensors |
pairwise-distance | Pairwise distance between two batches of vectors |
mse-loss | Mean squared error loss |
l1-loss | Mean absolute error loss |
cross-entropy | Cross-entropy loss (combines log-softmax and NLL) |
nll-loss | Negative log-likelihood loss |
bce-loss | Binary cross-entropy loss |
bce-with-logits-loss | BCE with an integrated sigmoid for numerical stability |
scaled-dot-product-attention | Fused scaled-dot-product attention using LibTorch’s kernel dispatcher |
dropout | Functional dropout |
clorch.nn.init — Parameter Initialization
Functions for in-place weight initialization, matching torch.nn.init.
Initialization functions
Initialization functions
| Function | Description |
|---|---|
xavier-uniform! | Fill a 2-D tensor with Xavier uniform values |
xavier-normal! | Fill a 2-D tensor with Xavier normal values |
kaiming-uniform! | Fill with Kaiming uniform values (He initialization) |
kaiming-normal! | Fill with Kaiming normal values (He initialization) |
normal! | Fill in-place with values from N(mean, std) |
uniform! | Fill in-place with values from Uniform(a, b) |
constant! | Fill in-place with a constant scalar |
zeros! | Fill in-place with zeros |
ones! | Fill in-place with ones |
clorch.nn.parallel — DistributedDataParallel
Wraps a model for synchronous data-parallel training across NCCL ranks.
DDP functions
DDP functions
| Function / Macro | Description |
|---|---|
distributed-data-parallel | Wrap a model with DDP; returns a java.io.Closeable handle |
no-sync | Macro: suppress gradient synchronization for a block (used with gradient accumulation) |
optimizer-step! | Step the optimizer with optional AMP scaler integration; handles DDP barrier |
clorch.optim — Optimizers
Gradient-based parameter update algorithms, matching torch.optim.
Optimizer functions
Optimizer functions
| Function | Description |
|---|---|
sgd | Stochastic gradient descent with optional momentum and weight decay |
adam | Adam optimizer |
adamw | AdamW optimizer (decoupled weight decay) |
rmsprop | RMSprop optimizer |
adagrad | Adagrad optimizer |
zero-grad | Zero the gradients of all parameters held by an optimizer |
step | Apply one parameter update step |
clorch.amp — Automatic Mixed Precision
Implements PyTorch-style AMP with autocast and a dynamic gradient scaler for float16 training.
AMP functions
AMP functions
| Function / Macro | Description |
|---|---|
autocast | Macro: run a body with automatic dtype casting to a lower precision |
call-with-autocast | Functional form of autocast |
grad-scaler | Create a gradient scaler for float16 dynamic loss scaling |
scale-loss | Multiply a loss by the current scale factor |
backward! | Scale the loss and run backward; updates the scaler’s state |
step! | Unscale gradients and step the optimizer if no infinities detected |
scaler-state | Return a serializable map of scaler state |
load-scaler-state! | Restore scaler state from a checkpoint map |
clorch.distributed — Distributed Training
NCCL-backed collective operations and the managed worker launcher.
Process group lifecycle and metadata
Process group lifecycle and metadata
| Function / Macro | Description |
|---|---|
init-process-group! | Initialize this JVM’s default NCCL process group |
destroy-process-group! | Synchronize and release the native communicator |
with-process-group | Macro: initialize a process group for a body and always destroy it on exit |
rank | Return this worker’s global rank |
world-size | Return the number of ranks in the process group |
rank-zero? | Return true for global rank zero |
initialized? | Return true when a live default process group exists |
Collectives
Collectives
| Function | Description |
|---|---|
all-reduce! | All-reduce a tensor across all ranks in-place |
broadcast! | Broadcast a tensor from a root rank to all other ranks |
reduce! | Reduce tensors to a single root rank in-place |
all-gather-into! | Gather equal-sized inputs from all ranks into a preallocated output tensor |
reduce-scatter-into! | Reduce an input tensor and scatter equal chunks into an output tensor |
all-to-all-single! | Perform an all-to-all collective into a preallocated output with optional split sizes |
send | Point-to-point send CUDA tensors to a destination rank |
receive! | Point-to-point receive CUDA tensors from a source rank in-place |
barrier! | Block until all ranks reach this call |
Worker launcher
Worker launcher
| Function | Description |
|---|---|
launch! | Start one JVM worker per GPU with RANK, WORLD_SIZE, etc. set |
job-status | Return the current status of a launched job |
await-job! | Block until all workers complete or time out |
job-logs | Return stdout/stderr from a specific worker rank |
stop-job! | Send stop signals to all workers in a launched job |
Checkpointing
Checkpointing
| Function | Description |
|---|---|
save-checkpoint! | Atomically write model, optimizer, sampler, scaler, and state from rank zero |
load-checkpoint! | Load a checkpoint file into the provided model, optimizer, and scaler handles |
clorch.data — Data Loading
Dataset protocols, the DataLoader, and distributed sampling.
Datasets and loaders
Datasets and loaders
| Symbol | Description |
|---|---|
IDataset | Protocol requiring get-item and get-size implementations |
dataset | Create a dataset from :size and :get-item callback functions |
defdataset | Macro: define a named dataset type with fields and protocol implementations |
tensor-dataset | Wrap paired feature/label tensors as a dataset |
dataloader | Wrap a dataset with batching, shuffling, and optional worker threads |
get-size | Return the number of samples in a dataset |
cleanup-data! | Release native resources held by a dataset or dataloader |
Distributed sampling
Distributed sampling
| Function | Description |
|---|---|
distributed-sampler | Create a sampler that partitions indices across ranks deterministically |
sample-indices | Return this rank’s index list for the current epoch |
set-epoch! | Advance the sampler epoch to reshuffle indices deterministically |
sampler-state | Return a serializable map of sampler state |
load-sampler-state! | Restore sampler state from a checkpoint map |
clorch.cuda — CUDA Utilities
Device discovery, selection, and seeding.
CUDA functions
CUDA functions
| Function | Description |
|---|---|
available? | Return true if CUDA hardware and compatible natives are present |
device-count | Return the number of visible NVIDIA GPUs |
set-device! | Set the active CUDA device for the current thread |
current-device | Return the index of the currently active CUDA device |
synchronize | Block until all CUDA kernels on the current device have completed |
manual-seed | Set the CUDA RNG seed for the current device |
manual-seed-all | Set the CUDA RNG seed on all devices |
clorch.distributions — Probability Distributions
Probability distribution objects for sampling and log-probability computation.
Distributions
Distributions
| Function | Description |
|---|---|
normal | Create a Normal distribution with given mean and standard deviation |
log-normal | Create a Log-Normal distribution with given loc and scale |
bernoulli | Create a Bernoulli distribution with a given probability |
categorical | Create a Categorical distribution from unnormalized logits or probabilities |
binomial | Create a Binomial distribution with total-count and probability |
uniform | Create a Uniform distribution over [low, high) |
poisson | Create a Poisson distribution with a given rate |
exponential | Create an Exponential distribution with a given rate |
cauchy | Create a Cauchy distribution with given loc and scale |
geometric | Create a Geometric distribution with a given probability |
gumbel | Create a Gumbel distribution with given loc and scale |
laplace | Create a Laplace distribution with given loc and scale |
gamma | Create a Gamma distribution with given concentration and rate |
beta | Create a Beta distribution with given concentration1 and concentration0 |
dirichlet | Create a Dirichlet distribution with given concentration vector |
student-t | Create a Student-t distribution with given degrees of freedom, loc, and scale |
chi2 | Create a Chi-squared distribution with given degrees of freedom |
fisher-f | Create a Fisher-F distribution with given df1 and df2 |
weibull | Create a Weibull distribution with given scale and concentration |
pareto | Create a Pareto distribution with given scale and alpha |
logistic | Create a Logistic distribution with given loc and scale |
negative-binomial | Create a Negative Binomial distribution with given total-count and probs |
sample | Draw one or more samples from a distribution |
log-prob | Compute the log-probability of a value under a distribution |
mean | Return the analytical mean of a distribution |
variance | Return the analytical variance of a distribution |
clorch.linalg — Linear Algebra
A dedicated namespace mirroring torch.linalg, grouping all decomposition and solving operations.
Linear algebra operations
Linear algebra operations
| Function | Description |
|---|---|
cholesky | Cholesky decomposition of a batch of positive-definite matrices |
inv | Matrix inverse (batched) |
det | Matrix determinant (batched) |
svd | Singular value decomposition returning U, S, Vh |
qr | QR decomposition returning Q and R |
solve | Solve AX = B for X |
lstsq | Least-squares solution to AX ≈ B |
eig | Eigenvalue decomposition for general (possibly complex) matrices |
eigh | Eigenvalue decomposition for real symmetric or complex Hermitian matrices |
norm | Matrix or vector norm with configurable ord and dimension |
matrix-exp | Matrix exponential |
matrix-power | Integer matrix power |
clorch.einsum — Einsum eDSL
A Clojure macro-based eDSL for expressing tensor contractions declaratively, without string-notation index labels.
Einsum eDSL
Einsum eDSL
| Symbol | Description |
|---|---|
ein | Macro: express a tensor contraction using declared index symbols and := syntax. Supports matrix-vector products, outer products, traces, scaled contractions, and arbitrary multi-tensor einsum expressions. Index variables must be declared before use. |