Skip to main content

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.

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.
PyTorchClorch Namespace
torchclorch.torch
torch.autogradclorch.autograd
torch.nnclorch.nn
torch.nn.functionalclorch.nn.functional
torch.nn.initclorch.nn.init
torch.nn.parallel.DistributedDataParallelclorch.nn.parallel
torch.optimclorch.optim
torch.ampclorch.amp
torch.distributedclorch.distributed
torch.utils.dataclorch.data
torch.cudaclorch.cuda
torch.distributionsclorch.distributions
torch.linalgclorch.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.
FunctionDescription
tensorCreate a tensor from a Clojure data structure or scalar, with optional :dtype and :device
randnReturn a tensor filled with values drawn from N(0,1)
randReturn a tensor filled with values drawn from Uniform(0,1)
rand-intReturn a tensor of random integers in [low, high)
randpermReturn a random permutation of integers from 0 to n−1
zerosReturn a tensor filled with zeros
onesReturn a tensor filled with ones
emptyReturn an uninitialized tensor of the given shape
fullReturn a tensor filled with a scalar fill value
eyeReturn a 2-D identity matrix
arangeReturn evenly spaced values in a half-open interval
linspaceReturn a 1-D tensor of evenly spaced values between start and end
logspaceReturn a 1-D tensor of values spaced logarithmically
bernoulliReturn a tensor of Bernoulli-sampled 0/1 values
manual-seedSet the random seed for reproducibility
FunctionDescription
addElement-wise addition
subElement-wise subtraction
mulElement-wise multiplication
divElement-wise division
powElement-wise exponentiation
sqrtElement-wise square root
rsqrtElement-wise reciprocal square root
absElement-wise absolute value
negElement-wise negation
expElement-wise natural exponential
logElement-wise natural logarithm
sinElement-wise sine
cosElement-wise cosine
tanhElement-wise hyperbolic tangent
softmaxSoftmax normalization along a given dimension
clamp / clipClamp tensor values to a min/max range
matmulMatrix multiplication with broadcasting
mm2-D matrix multiplication (no broadcast)
bmmBatched matrix multiplication
dotDot product of two 1-D tensors
innerInner product (generalized dot)
outerOuter product of two 1-D tensors
FunctionDescription
sumSum of all elements, or along a dimension
meanMean of all elements, or along a dimension
maxMaximum value (or values + indices along a dim)
minMinimum value (or values + indices along a dim)
argmaxIndex of the maximum value along a dimension
argminIndex of the minimum value along a dimension
topkTop-k values and their indices
sortSort tensor values along a dimension
argsortIndices that sort a tensor along a dimension
gatherGather values along an axis using an index tensor
cumsumCumulative sum along a dimension
logsumexpLog of the sum of exponentials
allTrue if all elements satisfy a condition
anyTrue if any element satisfies a condition
nonzeroIndices of non-zero elements
count-nonzeroNumber of non-zero elements
FunctionDescription
sizeReturn the shape as a vector; optionally query a single dimension
reshapeReturn a tensor with a new shape (may copy)
viewReturn a tensor with a new shape sharing storage
transposeSwap two dimensions
TTranspose shorthand (reverses all dimensions)
swapaxesAlias for transpose
movedimMove a dimension to a new position
unsqueezeInsert a size-1 dimension at the given position
flattenCollapse dimensions into one
unflattenExpand one dimension into multiple
expandBroadcast a tensor to a larger shape
tileTile a tensor by repeating it along dimensions
repeatRepeat tensor data along each dimension
catConcatenate tensors along an existing dimension
stackStack tensors along a new dimension
unbindRemove a dimension, returning its slices as a seq
splitSplit a tensor into chunks along a dimension
chunkSplit a tensor into a fixed number of chunks
FunctionDescription
ixErgonomic Python-style indexer supporting ranges, negative indices, ellipsis, and tensor indices
selectSelect a single slice along a dimension at a given index
index-selectSelect slices along a dimension using an index tensor
masked-fillFill positions where a boolean mask is true with a scalar
take-along-dimGather values using an index tensor, broadcasting along non-indexed dims
scatter-reduceScatter-reduce values into a target tensor
FunctionDescription
eqElement-wise equality
gtElement-wise greater-than
ltElement-wise less-than
geElement-wise greater-than-or-equal
leElement-wise less-than-or-equal
whereSelect elements from two tensors based on a condition
iscloseElement-wise approximate equality within tolerances
allcloseTrue if all elements are approximately equal
isnanElement-wise NaN check
isinfElement-wise infinity check
isfiniteElement-wise finite-value check
FunctionDescription
linalg-choleskyCholesky decomposition of a positive-definite matrix
linalg-invMatrix inverse
linalg-detMatrix determinant
linalg-svdSingular value decomposition
linalg-qrQR decomposition
linalg-solveSolve a system of linear equations AX = B
linalg-lstsqLeast-squares solution
linalg-eigEigenvalue decomposition (general matrix)
linalg-eighEigenvalue decomposition (symmetric/Hermitian matrix)
linalg-normMatrix or vector norm
FunctionDescription
dtypeReturn the element type of a tensor
toMove a tensor to a device or cast to a dtype
to-floatCast a tensor to float32
to-longCast a tensor to int64
item-floatExtract a scalar tensor’s value as a Java double
tprintPretty-print a tensor to stdout
Function / MacroDescription
with-torchMacro: 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
FunctionDescription
precompute-rope-freqsPrecompute cosine/sine frequency tensors for rotary position embeddings given head dimension and sequence length
apply-ropeApply precomputed RoPE frequencies to query or key tensors
top-pFilter logits to the nucleus (top-p) token set
multinomialSample indices from a probability distribution
FunctionDescription
saveSerialize a tensor or model to a file
loadDeserialize a tensor or model from a file
jit-saveSave a TorchScript module to a file
jit-loadLoad a TorchScript module from a file
jit-forwardRun 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.
Function / MacroDescription
backwardCompute gradients by running the reverse-mode pass from a scalar loss
gradReturn the accumulated gradient tensor for a leaf tensor
detachReturn a new tensor sharing storage but detached from the computation graph
no-gradMacro: disable gradient tracking for all operations in the body
set-requires-gradEnable 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.
SymbolDescription
IModuleProtocol defining -forward, -train, and -to for all module types
forwardCall a module’s forward pass
trainSwitch a module between training and evaluation mode
toMove a module’s parameters and buffers to a device or dtype
parametersReturn a flat list of all trainable parameters
named-parametersReturn a list of [name tensor] pairs for all parameters
zero-gradZero the .grad fields of all module parameters
state-dictReturn a map of parameter names to tensors
load-state-dictLoad a state-dict map into a module in place
save-weightsSerialize a module’s weights to a file
load-weightsLoad serialized weights into a module from a file
summaryPrint a table of layer output shapes and parameter counts
applyRecursively apply a function to every sub-module
modulesReturn a flat seq of all sub-modules
clip-grad-norm!Clip the norm of all parameter gradients
SymbolDescription
defmodelMacro: define a named module record with constructor args, registered sub-modules, and a forward form
sequentialCreate a module that chains other modules in order
generateAutoregressive token generation loop
FunctionDescription
linearFully connected linear layer (weight + optional bias)
bilinearBilinear transformation layer
rnnElman recurrent layer
lstmLong short-term memory layer
gruGated recurrent unit layer
embeddingLearnable embedding lookup table
embedding-from-pretrainedInitialize an embedding from a pretrained weight tensor
FunctionDescription
conv1d1-D convolution
conv2d2-D convolution
conv3d3-D convolution
conv-transpose1d1-D transposed convolution
conv-transpose2d2-D transposed convolution
conv-transpose3d3-D transposed convolution
FunctionDescription
batchnorm1dBatch normalization over 2-D or 3-D input
batchnorm2dBatch normalization over 4-D input
batchnorm3dBatch normalization over 5-D input
layernormLayer normalization
groupnormGroup normalization
instancenorm1dInstance normalization over sequences
instancenorm2dInstance normalization over spatial feature maps
instancenorm3dInstance normalization over volumetric inputs
rmsnormRoot-mean-square layer normalization (preferred for LLMs)
FunctionDescription
max-pool1d / max-pool2d / max-pool3dMax pooling for 1-D, 2-D, and 3-D inputs
avg-pool1d / avg-pool2d / avg-pool3dAverage pooling for 1-D, 2-D, and 3-D inputs
adaptive-max-pool1d/2d/3dAdaptive max pooling to a target output size
adaptive-avg-pool1d/2d/3dAdaptive average pooling to a target output size
FunctionDescription
reluRectified linear unit
relu6ReLU clamped at 6
geluGaussian error linear unit
siluSigmoid linear unit (Swish)
mishMish activation
tanhHyperbolic tangent activation module
sigmoidLogistic sigmoid activation
leaky-reluLeaky ReLU with configurable negative slope
elu / selu / celuExponential linear unit variants
hardswish / hardsigmoid / hardtanhHard approximations of smooth activations
softplus / softsignSmooth softplus and softsign units
log-softmaxLog-softmax along a dimension
log-sigmoidLog-sigmoid activation
FunctionDescription
dropoutStandard dropout (randomly zero elements)
dropout2dChannel-wise dropout for 2-D feature maps
alpha-dropoutAlpha-dropout maintaining self-normalizing properties
feature-alpha-dropoutFeature-level alpha-dropout
SymbolDescription
GroupedQueryAttentionMulti-head attention with separate Q and K/V head counts (GQA); supports optional KV cache and RoPE frequencies
SwiGLUSwiGLU feed-forward block (two-gate linear projection with SiLU activation)
FunctionDescription
flattenModule form of torch/flatten
unflattenModule form of torch/unflatten
identityPass-through module
cosine-similarityCosine similarity module
pairwise-distancePairwise distance module
pixel-shuffleRearrange elements for sub-pixel upsampling
pixel-unshuffleInverse of pixel-shuffle
upsampleUpsample 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.
FunctionDescription
linearLinear transform: x @ W.T + b
conv1d / conv2d / conv3dFunctional convolution with explicit weight and bias
batch-normBatch normalization with explicit running stats
layer-normLayer normalization with explicit weight and bias
group-normGroup normalization with explicit weight and bias
relu / gelu / silu / sigmoid / tanhFunctional activation functions
softmax / log-softmaxSoftmax and log-softmax along a dimension
max-pool1d / max-pool2dFunctional max pooling
avg-pool1d / avg-pool2dFunctional average pooling
interpolateResize a tensor using various interpolation modes
padPad a tensor with a constant, reflection, or replication
pixel-shuffle / pixel-unshuffleFunctional sub-pixel operations
cosine-similarityCosine similarity between two tensors
pairwise-distancePairwise distance between two batches of vectors
mse-lossMean squared error loss
l1-lossMean absolute error loss
cross-entropyCross-entropy loss (combines log-softmax and NLL)
nll-lossNegative log-likelihood loss
bce-lossBinary cross-entropy loss
bce-with-logits-lossBCE with an integrated sigmoid for numerical stability
scaled-dot-product-attentionFused scaled-dot-product attention using LibTorch’s kernel dispatcher
dropoutFunctional dropout

clorch.nn.init — Parameter Initialization

Functions for in-place weight initialization, matching torch.nn.init.
FunctionDescription
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.
Function / MacroDescription
distributed-data-parallelWrap a model with DDP; returns a java.io.Closeable handle
no-syncMacro: 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.
FunctionDescription
sgdStochastic gradient descent with optional momentum and weight decay
adamAdam optimizer
adamwAdamW optimizer (decoupled weight decay)
rmspropRMSprop optimizer
adagradAdagrad optimizer
zero-gradZero the gradients of all parameters held by an optimizer
stepApply one parameter update step

clorch.amp — Automatic Mixed Precision

Implements PyTorch-style AMP with autocast and a dynamic gradient scaler for float16 training.
Function / MacroDescription
autocastMacro: run a body with automatic dtype casting to a lower precision
call-with-autocastFunctional form of autocast
grad-scalerCreate a gradient scaler for float16 dynamic loss scaling
scale-lossMultiply 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-stateReturn 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.
Function / MacroDescription
init-process-group!Initialize this JVM’s default NCCL process group
destroy-process-group!Synchronize and release the native communicator
with-process-groupMacro: initialize a process group for a body and always destroy it on exit
rankReturn this worker’s global rank
world-sizeReturn 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
FunctionDescription
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
sendPoint-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
FunctionDescription
launch!Start one JVM worker per GPU with RANK, WORLD_SIZE, etc. set
job-statusReturn the current status of a launched job
await-job!Block until all workers complete or time out
job-logsReturn stdout/stderr from a specific worker rank
stop-job!Send stop signals to all workers in a launched job
FunctionDescription
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.
SymbolDescription
IDatasetProtocol requiring get-item and get-size implementations
datasetCreate a dataset from :size and :get-item callback functions
defdatasetMacro: define a named dataset type with fields and protocol implementations
tensor-datasetWrap paired feature/label tensors as a dataset
dataloaderWrap a dataset with batching, shuffling, and optional worker threads
get-sizeReturn the number of samples in a dataset
cleanup-data!Release native resources held by a dataset or dataloader
FunctionDescription
distributed-samplerCreate a sampler that partitions indices across ranks deterministically
sample-indicesReturn this rank’s index list for the current epoch
set-epoch!Advance the sampler epoch to reshuffle indices deterministically
sampler-stateReturn 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.
FunctionDescription
available?Return true if CUDA hardware and compatible natives are present
device-countReturn the number of visible NVIDIA GPUs
set-device!Set the active CUDA device for the current thread
current-deviceReturn the index of the currently active CUDA device
synchronizeBlock until all CUDA kernels on the current device have completed
manual-seedSet the CUDA RNG seed for the current device
manual-seed-allSet the CUDA RNG seed on all devices

clorch.distributions — Probability Distributions

Probability distribution objects for sampling and log-probability computation.
FunctionDescription
normalCreate a Normal distribution with given mean and standard deviation
log-normalCreate a Log-Normal distribution with given loc and scale
bernoulliCreate a Bernoulli distribution with a given probability
categoricalCreate a Categorical distribution from unnormalized logits or probabilities
binomialCreate a Binomial distribution with total-count and probability
uniformCreate a Uniform distribution over [low, high)
poissonCreate a Poisson distribution with a given rate
exponentialCreate an Exponential distribution with a given rate
cauchyCreate a Cauchy distribution with given loc and scale
geometricCreate a Geometric distribution with a given probability
gumbelCreate a Gumbel distribution with given loc and scale
laplaceCreate a Laplace distribution with given loc and scale
gammaCreate a Gamma distribution with given concentration and rate
betaCreate a Beta distribution with given concentration1 and concentration0
dirichletCreate a Dirichlet distribution with given concentration vector
student-tCreate a Student-t distribution with given degrees of freedom, loc, and scale
chi2Create a Chi-squared distribution with given degrees of freedom
fisher-fCreate a Fisher-F distribution with given df1 and df2
weibullCreate a Weibull distribution with given scale and concentration
paretoCreate a Pareto distribution with given scale and alpha
logisticCreate a Logistic distribution with given loc and scale
negative-binomialCreate a Negative Binomial distribution with given total-count and probs
sampleDraw one or more samples from a distribution
log-probCompute the log-probability of a value under a distribution
meanReturn the analytical mean of a distribution
varianceReturn the analytical variance of a distribution

clorch.linalg — Linear Algebra

A dedicated namespace mirroring torch.linalg, grouping all decomposition and solving operations.
FunctionDescription
choleskyCholesky decomposition of a batch of positive-definite matrices
invMatrix inverse (batched)
detMatrix determinant (batched)
svdSingular value decomposition returning U, S, Vh
qrQR decomposition returning Q and R
solveSolve AX = B for X
lstsqLeast-squares solution to AX ≈ B
eigEigenvalue decomposition for general (possibly complex) matrices
eighEigenvalue decomposition for real symmetric or complex Hermitian matrices
normMatrix or vector norm with configurable ord and dimension
matrix-expMatrix exponential
matrix-powerInteger matrix power

clorch.einsum — Einsum eDSL

A Clojure macro-based eDSL for expressing tensor contractions declaratively, without string-notation index labels.
SymbolDescription
einMacro: 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.
Example forms:
;; Matrix-vector product
(ein [i] := (* (A i j) (x j)))

;; Outer product
(ein [i j] := (* (x i) (y j)))

;; Trace (scalar result)
(ein [] := (A i i))

;; Scaled contraction
(ein [i] := (* 0.5 (A i j) (x j)))

Build docs developers (and LLMs) love