Transformations¶
What it is¶
A transformation takes a grid and returns a new grid. The library ships
eleven pure transformations that change the whole grid at once, and a
Program that composes them.
- A transformation is a function
Grid -> Grid. It does not touch the input: the output is a new grid. - A program is an ordered list of transformations.
Program.apply(g)runs them one after the other. - Verification (
Program.verify(pairs)) checks a program against a list of(input, output)pairs and returns the fraction it solves. It is the number a search uses to choose between candidates.
Why use it: a program that is a list of small pure functions is easy to compose, compare and verify. The eleven transformations of this page are the building blocks a search over ARC-AGI tasks combines.
The example on this page is a 2 by 3 grid on which rot90, hmirror and a
composition of hmirror and vmirror are applied.
1. One transformation¶
Each transformation takes a grid and returns a new grid. rot90 turns the
grid a quarter turn counter-clockwise.
from dense_armor.core.graph import Grid, rot90
g = Grid.from_list([
[1, 2, 3],
[4, 5, 6],
])
out = rot90(g)
print(g.shape(), out.shape())
print(out.to_list())
The input has shape 2 rows by 3 columns, the output 3 by 2. The colour of
(0, 0) in the input (which is 1) lands in (2, 0) of the output: the
rotation is counter-clockwise, so the top-left corner goes to the
bottom-left.
2. Compose them with Program¶
Program(steps) is a list of transformations. apply(g) runs them in order.
from dense_armor.core.graph import Grid, Program, hmirror, vmirror
g = Grid.from_list([
[1, 2, 3],
[4, 5, 6],
])
p = Program([hmirror, vmirror])
print(p.apply(g).to_list())
hmirror reverses each row, vmirror reverses the rows. The two together
are a 180-degree rotation of the grid: every cell moves to the opposite
corner. Program.apply calls the first step, then the second on the result,
and so on. The object is immutable: a step that tries to change its input
would not work; every step returns a new grid.

The grid of this page, then hmirror(g), then vmirror(hmirror(g)). The
first step reverses each row, the second reverses the rows.
3. Verify a program against pairs¶
verify(pairs) takes a list of (input, output) pairs and returns the
fraction the program solves.
from dense_armor.core.graph import Grid, Program, hmirror, rot90
g = Grid.from_list([
[1, 2, 3],
[4, 5, 6],
])
pairs = [(g, rot90(g))]
print(Program([rot90]).verify(pairs))
print(Program([hmirror]).verify(pairs))
The first program solves the pair: rot90(g) is the expected output. The
second does not: hmirror(g) is a different grid. verify returns a number
between 0.0 and 1.0; an empty list gives 0.0.
4. A step that fails¶
If a step raises ValueError or IndexError on a pair, that pair counts as
not solved. This is on purpose: a composition of primitives may not be
defined for every grid, and a search should treat a failure as a wrong answer,
not as an error.
from dense_armor.core.graph import Grid, Program
def broken(g):
raise ValueError("boom")
g = Grid.from_list([[1, 2], [3, 4]])
print(Program([broken]).verify([(g, g)]))
A program with a step that raises gives 0.0 on every pair, because every pair
hits the exception. The exception does not propagate out of verify.
5. The full menu¶
The eleven grid transformations are: rot90, rot180, rot270, hmirror,
vmirror, dmirror, fill, recolor, shift, upscale, downscale.
dmirror is the transpose. fill(g, color, mask=None) writes one colour on
a set of cells or on the whole grid. recolor(g, from_color, to_color)
replaces one colour with another. shift(g, dr, dc, fill_color=0) moves the
grid by (dr, dc). upscale(g, k) and downscale(g, k) scale by an integer
factor.
Six more primitives act on the objects of a grid, not on the grid as a whole:
fill_objects, recolor_objects, move_objects, delete_objects,
crop_to_object, apply_per_object. They take a predicate on ArcObject and
apply a change to the objects that match. The page Grids and
objects explains what an object is. These six are not exported from
dense_armor.core.graph; import them from dense_armor.core.graph.dsl:
from dense_armor.core.graph import Grid
from dense_armor.core.graph.dsl import fill_objects
g = Grid.from_list([
[1, 0, 2],
[0, 0, 2],
])
out = fill_objects(g, 5, lambda o: o.color == 2)
print(out.to_list())
The predicate lambda o: o.color == 2 selects the object of colour 2, and
fill_objects paints it with colour 5. A None predicate selects every
foreground object (every object whose colour is not 0).
default_primitives() returns the twenty-one primitives used as the default
menu by the search: the eleven grid transformations (with fixed parameters,
e.g. lambda g: upscale(g, 2)), the six object primitives (with fixed
predicates), and a few more, each named. Import it from
dense_armor.core.graph.dsl:
from dense_armor.core.graph.dsl import default_primitives
prims = default_primitives()
print(len(prims), [p.__name__ for p in prims[:5]])
The name of each primitive is readable with __name__. This is how the
Program.__repr__ shows the steps of a program: by their names, not by
their code.
Details¶
dsl.py is a module of pure functions. Every function takes a Grid and
returns a new Grid; the input is never changed. rot90, rot180,
rot270, dmirror, hmirror and vmirror have no parameters. fill,
recolor, shift, upscale, downscale have one or more parameters, and
the six object primitives take a Predicate (a function ArcObject -> bool)
plus one or more parameters.
Program is a small class with three methods: apply, verify, and the
standard __eq__, __hash__, __repr__. apply runs the steps in order;
verify calls apply on each pair and counts the ones that match the
expected output; __repr__ shows the step names as Program(rot90,
hmirror).
verify catches ValueError and IndexError from a step and treats the
pair as not solved. It does not catch other exceptions: a bug in a
transformation is still a bug, and verify does not hide it.
The module has no dependency beyond Grid and ArcObject. The primitives
use list comprehensions over g.at(r, c); there is no NumPy inside the
functions, so a transformation is easy to read and to test one cell at a
time.
References¶
The eleven grid transformations follow the arc-dsl writeup (Hodel,
"The ARC-DSL", Section 2.3) for the names and the meaning. The writeup uses
plain data structures; this module uses Grid and ArcObject so the
results stay immutable and hashable.
The Program and verify design follows the idea of a program as a
sequence of pure functions (Section 3.2.3 of Joffe and Eliasmith 2025,
arXiv:2511.08747, for the answer deduction, where the program is a set of
rules; here the program is a sequence of transformations and the rules are
the transformations themselves). The verification score is the feedback
signal of the refinement loop described in ARC Prize 2025, arXiv:2601.10904,
page 5.
Choices stated explicitly¶
- Counter-clockwise is
rot90. The name follows the arc-dsl writeup, whererot90is a quarter-turn counter-clockwise.rot270is the clockwise quarter-turn. verifycounts a step that raises as not solved. The docstring ofverifysays so. A program with a step that raises on every pair gives 0.0, not an exception.- Only the eleven grid transformations are in the public
__all__. The six object primitives anddefault_primitivesare indsl.pybut not re-exported fromdense_armor.core.graph. The guide on this page shows the import fromdense_armor.core.graph.dslfor them. A follow-up change may add them to the package__all__the same way the five relations were added.