Tree Matching & Grafting

Three components reshape trees, and you will use them constantly. Learn what each does to the structure, not just its name.

Graft pushes every item onto its own new branch. A single list of 20 points becomes a tree of 20 branches, one point each. Why would you want that? Because it changes how the data matches downstream - grafting is how you say 'treat each of these separately, and pair each one against the whole of that other input'. It is the go-to move for making a list behave like a set of independent cases.

Flatten does the opposite: it collapses every branch back into one single list, discarding the path structure entirely. All items, one branch, in order. Flatten is the sledgehammer - wonderfully effective for forcing everything into one clean stream, and dangerous precisely because it throws away the grouping you may have needed. Reach for it deliberately, never reflexively.

Simplify is the gentle one: it removes redundant, shared levels from the paths without moving any item. If every branch is buried under a common prefix like {0;0;0;...}, Simplify strips the parts that don't distinguish anything, turning unreadable deep paths into clean {0}, {1} - while the data stays exactly where it was. It tidies labels, not contents. Together these three - split, merge, tidy - are the vocabulary of every tree fix you will make.

Now the heart of it. When a component has two or more inputs of different lengths - say 3 points and 5 circles - it has to decide how to pair them. Grasshopper follows a data-matching rule, and knowing which rule is in play explains nearly every surprising result.

The default is longest-list: Grasshopper walks the longest input and reuses the last item of the shorter ones to keep up. Pair 3 planes with 5 radii and you get 5 circles - the last plane repeated to cover the extra radii. Usually sensible, occasionally surprising.

Shortest-list matching stops at the end of the shortest input: 3 planes and 5 radii give only 3 circles, and the two extra radii are simply dropped. You opt into this (via the Shortest List component or a component option) when you want strict, one-to-one pairing with no reused leftovers.

Cross reference is the dramatic one: it pairs every item of one input with every item of the other. 3 points crossed with 5 points produces 15 combinations - the full grid. This is enormously useful when you genuinely want all combinations (every column position against every row position to build a grid), and it is the usual culprit when a count explodes far beyond what you expected. If you asked for 20 and got 400, a cross reference - deliberate or accidental - almost certainly happened.

Let's solve the archetypal disaster properly, because understanding it once immunises you. You have 20 points on one wire and 20 points on another, and you feed both into a Line component expecting 20 lines - one connecting each pair. Instead you get 400. What happened?

One of your inputs is a tree and the other is a flat list - and when a tree meets a list, the component often matches the flat list against each branch of the tree, which multiplies. Twenty branches each matched against a 20-item list gives 20 x 20 = 400. Grasshopper didn't misbehave; it faithfully paired every branch with the whole other input. Your two inputs simply had mismatched structures.

The fix is to make the structures agree. If both should be simple parallel lists, Flatten both inputs so each is one 20-item list, and you'll get the 20 one-to-one lines you wanted. If you meant for the pairing to be per-branch, Graft the flat input so it, too, has one item per branch and the branches align one-to-one. The move is always the same diagnosis: open the Param Viewer on both inputs, compare their shapes, and use Graft or Flatten to bring them into alignment. The geometry was never the problem - the data structures were.

A few more tools round out the kit. Trim Tree removes the last N levels of a path, merging the deepest branches back together - the surgical opposite of Graft when you've branched one level too far and want to fold it back without flattening everything. Think of it as 'undo one level of nesting' rather than the total collapse Flatten performs.

Prune Tree (and related tools like Clean Tree) remove empty branches or null items that quietly accumulate and cause off-by-one mismatches later - a good habit before a tricky match. And the Path Mapper is the power tool for those who need to rewrite path structure explicitly, remapping {A;B} to {B} or {A} with a rule; you won't need it often, but it's there when Graft and Flatten aren't precise enough.

The deeper point is to work with intent. Before wiring two things together, ask: what shape is each input, and what pairing do I actually want - one-to-one, one-to-many, or all-combinations? Then set the structures to make that happen: Flatten for one clean stream, Graft to separate cases, Simplify to keep paths readable, Trim to fold a level back. Most 'Grasshopper is fighting me' sessions are really just a mismatch between the pairing you imagined and the one the data structures dictated. Name the pairing you want, shape the trees to match, and the fight ends.

Let's turn all of this into a decision you can make in seconds at the canvas, because in practice the whole skill collapses to one question asked before you wire two things together: what pairing do I actually want?

One-to-one - each item of A with the matching item of B, same count out. Make both inputs the same shape: if both are flat lists of equal length, you're done (longest-list keeps them in step); if one is a tree, Flatten both or Graft both so their branch structures agree. This is the everyday case - 20 planes with 20 radii giving 20 circles.

One-to-many - each item of A combined with the whole of B. Graft A so each of its items sits alone on its own branch; each branch then matches against the entire list B. This is how you say 'for each attractor point, measure the distance to every grid point' - graft the attractors, leave the grid flat.

All-combinations - every item of A with every item of B, N times M results. Use a cross reference (or the grafting that induces one). This is a grid generator: every X coordinate against every Y coordinate. Expect and want the count to multiply here.

Carry a tiny pre-flight checklist: (1) Param Viewer on both inputs - list or tree, how long? (2) name the pairing I want in words; (3) reshape to make the structures deliver it; (4) Simplify to keep paths readable. Four beats, every time. Do this and the 'Grasshopper is fighting me' feeling essentially disappears - you'll have replaced surprise with a deliberate choice, which is exactly what separates someone who uses trees from someone who is used by them.