Getting started

NuTorch puts GPU tensors in your shell. A daemon (nutorchd) owns the tensors and the GPU; the torch CLI sends it one operation per invocation and prints a handle — a plain string — to stdout. Handles flow through ordinary pipelines, so tensor programs compose the way shell programs always have.

Install

brew tap astrohackerlabs/nutorch
brew trust astrohackerlabs/nutorch
brew install astrohackerlabs/nutorch/nutorch

Homebrew builds NuTorch from source and may install build dependencies, so installation can take a few minutes. Requires an Apple-silicon Mac — every tensor lives on the GPU via Metal (MPS), and that is the point of the library. (No Homebrew? See installing from source.)

First tensors

For Nushell or ahsh, first add the module directory to config.nu and run use nutorch.nu *, following Nushell setup.

a=$(torch tensor '[1,2,3]')
b=$(torch tensor '[4,5,6]')
torch add $a $b | torch value
# [5.0,7.0,9.0]   computed on the GPU

let a = (torch tensor [1 2 3])
let b = (torch tensor [4 5 6])
torch add $a $b | torch value
# [5.0, 7.0, 9.0] — a native list, on the GPU

Three things just happened:

The daemon started itself. Any torch command auto-starts nutorchd if it isn’t running. You never manage it (but you can — the daemon).
You got handles, not data. $a is a string like tensor://6c0e3f…. The tensor itself never left the GPU.
The pipeline composed. torch add $a $b printed a new handle; torch value read it from stdin and printed the data as JSON.

Every operation accepts its leftmost tensor from the pipeline or as an argument — both of these work, in both shells:

torch add $a $b           # argument form
echo $a | torch add $b    # pipeline form: stdin fills the leftmost slot

torch add $a $b     # argument form
$a | torch add $b   # pipeline form: $in fills the leftmost slot

A taste of more

m=$(torch randn '[3,3]')
torch mm $m $m | torch mean | torch value     # matrix product, then mean

w=$(torch randn '[3]' --requires_grad)        # autograd is built in
loss=$(torch mul $w $w | torch sum)
torch backward $loss
torch grad $w | torch value

let m = (torch randn [3 3])
print (torch mm $m $m | torch mean | torch value)   # matrix product, then mean

let w = (torch randn [3] --requires_grad)               # autograd is built in
let loss = (torch mul $w $w | torch sum)
torch backward $loss
print (torch grad $w | torch value)

Run torch ops to list every operation (185 of them) and torch <op> --help for any one.

Where to go next

To upgrade an existing installation:

brew update
brew upgrade astrohackerlabs/nutorch/nutorch

The canonical Homebrew tap installs NuTorch independently of TermSurf. Publishing a release does not install it on your machine.

The daemon — lifecycle, idle TTL, status.
Tensors and handles — the dual input pattern, export/import, freeing memory.
Autograd and neural networks — training, from the shell.
Nushell — structured data in and out.

The daemon →