iversonnb

APL and J in notebooks: Iverson-language magics and kernels for Jupyter, IPython, and LLM agents

iversonnb brings the Iverson languages to notebooks. It adds %%apl to Jupyter and IPython, which executes code in Dyalog APL, %%j to J, plus persistent APL and J kernels for LLM agents (including MCP). APL runs over the RIDE protocol, the same protocol Dyalog’s own IDE uses, so nothing needs to be loaded into your workspace, output looks exactly like a Dyalog session, and errors are detected reliably. J runs in-process through libj, the engine library that ships with every J install.

See core and j for step by step walkthroughs of how each is built.

Installation

Install the languages you plan to use; nothing starts until a magic first runs, so neither is required.

APL: install Dyalog APL. Dyalog provides a basic license for free. iversonnb is developed against Dyalog 20.0; 18.2 and later may work but are untested.
J: pip install jlanguage, or install it from jsoftware.com – iversonnb finds either.

Then:

pip install iversonnb

Once that’s complete, you can install the magics to all IPython and Jupyter sessions automatically by running in your terminal:

iversonnb_install

An interpreter only starts the first time you run its magic, so having iversonnb installed everywhere costs nothing when you don’t use it.

The `apl` magics

After first running an apl magic in a notebook, the APL language bar by Adám Brudzewsky is automatically added to the current page. (iversonnb bundles a modified copy of Adám’s lb.js; the file header lists the changes. The most visible ones: type a backtick twice in a row to enter triple backticks, get a ⋄ glyph with backtick-q, and use the ▲/▼ button beside the close button to choose whether the bar pushes the page down or overlays it, remembered per site.)

The cell magic (%%apl) runs APL code and displays the session’s own output, rendered in Adám’s SAX2 APL font, so results look exactly as they do in Dyalog:

%%apl
m←3 3⍴⍳9
m×10

10 20 30
40 50 60
70 80 90

Assignments are shy, just like in the Dyalog session, so the m← line above printed nothing. The line magic (%apl) instead evaluates one expression and returns it as a Python value:

%apl 3×⍳4

[3, 6, 9, 12]

%apl ⎕A

'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

Because the line magic returns a value, you can store it in a Python variable. Scalars come back as numbers or strings, vectors as lists, and higher-rank arrays as nested lists:

z = %apl m
z

[[1, 2, 3], [4, 5, 6], [7, 8, 9]]

To suppress a cell’s output, end the last line with a ;:

%%apl
m×10;

⎕← displays a value explicitly, which is how you show something that would otherwise be shy:

%%apl
v←2×⍳5
⎕←v

2 4 6 8 10

To use numpy, just pass the result of %apl into np.array:

import numpy as np

a = %apl m
np.array(a)

array([[1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]])

Example algorithms

The fibonacci sequence:

%apl {⍵,+/¯2↑⍵}⍣15⊢1 1

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597]

Explanation:

1 1: Initial seed (first two Fibonacci numbers)
{⍵,+/¯2↑⍵}: Function that appends the sum of the last two elements
⍣15: Apply the function 15 times
⊢: Identity function, passes the initial argument (1 1) to the iteration

Prime number sieve:

%%apl
primes ← {⍵×2=+⌿0=⍵∘.|⍵}⍳
(primes 50)~0

2 3 5 7 11 13 17 19 23 29 31 37 41 43 47

Explanation:

⍳50 generates integers 1 to 50
⍵∘.|⍵ creates a 50x50 matrix of divisibility (1 if divisible, 0 if not)
0= inverts the matrix (1 for non-divisible)
+⌿ sums columns, counting non-divisors for each number
2= checks if count equals 2 (prime property)
⍵× multiplies result with original numbers, keeping primes
~0 removes zero from the result

The `j` magics

J works the same way: %%j runs code in a persistent J session and displays its output verbatim, and %j expr returns an expression’s value as a Python object. The session keeps nouns and verbs across cells:

%%j
m =: 3 3 $ i. 9
m +/ . * m

15 18  21
42 54  66
69 90 111

z = %j m
z

[[0, 1, 2], [3, 4, 5], [6, 7, 8]]

Under the hood there’s no separate process or protocol: iversonnb loads libj via ctypes, so completion, errors, and interrupts come straight from the engine’s C API. The J session class mirrors Apl – call it to run code, move values in both directions with [], lift verbs into Python callables with fn – see j for the full walkthrough.

Using iversonnb from Python

The magics are a thin layer over the Apl class, which you can use directly in scripts, tests, and other tooling. Calling the session runs code and returns the output exactly as Dyalog formats it (or None if there’s no output); APL errors raise AplError:

from iversonnb import Apl

apl = Apl()
apl('3 3⍴⍳9')

1 2 3
4 5 6
7 8 9

Square brackets move values between Python and the workspace, in both directions, and take any expression:

apl['v'] = [3,1,4,1,5]
apl['{⍵[⍋⍵]}v']

[1, 1, 3, 4, 5]

fn lifts an APL function into a Python callable (one argument applies it monadically, two dyadically):

mean = apl.fn('{(+/⍵)÷≢⍵}')
mean([1,2,3,4])

2.5

Sessions shut themselves down at process exit; use close, or a with Apl() as apl: block, to do it sooner:

apl.close()

The LLM kernels

iversonnb also ships persistent APL and J sessions for LLM agents, built on clikernel’s stream protocol. aplkernel and jkernel run the stdin/stdout workers directly, and aplkernel-mcp/jkernel-mcp wrap them as MCP servers with execute, restart, and interrupt tools. Workspace state persists across calls, and interrupt stops a long computation while keeping it; send )OFF (APL) or exit 0 (J) to stop a worker. If a session has to be replaced mid-conversation (a crash, or the APL incomplete-input bug below), the response starts with a NOTE saying workspace state was lost.

On startup each kernel runs ~/.config/iversonnb/startup.apl or startup.ijs (if it exists) in the session, and reports its source and output in the banner, which the MCP form forwards as the server’s instructions.

Limitations

Keyboard input through ⎕ or ⍞ can’t work in a notebook, so it raises an error. The session survives.
A cell that ends inside an unfinished block, such as an unclosed :If, wedges the Dyalog interpreter with no way back (Dyalog/ride#1401). iversonnb detects this and starts a fresh session, raising an error that says so (with reset set on it), but workspace state is lost when it happens.
%apl transfers values with ⎕JSON, so it’s limited to arrays and scalars that JSON can represent, serializing to at most 32767 characters. For bigger data, write a file from APL instead.
%j transfers values through the engine’s typed-array API, so it’s limited to booleans, integers, floats, and characters; boxed, extended, and rational values raise (display them with %%j instead).
Windows isn’t supported yet: iversonnb configures Dyalog through environment variables, which is the Unix convention, and the J binding is untested there. macOS and Linux are supported.

Learning APL and J

To start learning APL, follow the 17 video series run by Jeremy Howard, and have a look at the study notes. The ] user commands mentioned there, such as ]Help ≠, work in iversonnb too.

For J, start with Learning J and the J wiki, whose NuVoc page is the reference for every primitive.