Clorch Namespace Map: Every Public Symbol Explained

Every Clorch namespace, its purpose, and the key public symbols it exports — from core tensor ops to distributed training, AMP, and the einsum eDSL.

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.

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

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

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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)))