[ulfarsson]

Adds the rotational cut, a strategy for permutation classes closed under rotation, and hints, which tell a TileScope user when a simpler class is worth searching for instead. Permuta#207 proposed this as an enumeration strategy in Permuta; it was closed because it belongs in Tilings as strategies, and this moves it here.

The idea

A rotation here is the cyclic shift that moves a permutation's first entry to its end (Perm.shift_left), not the quarter turn of Perm.rotate. The n rotations of a permutation of length n are distinct, and exactly one of them starts with its minimum. So a class closed under rotation has n times as many permutations of length n as its min cut, the permutations p for which the class has 1 followed by p raised by one, has of length n − 1. Exactly one rotation ends with the maximum too, so the max cut (p followed by a new maximum) counts the class the same way, and it can be a different class. A class closed under the same shift of its values has the same two cuts.

What it adds

• RotationalCutFactory and RotationalCutStrategy (tilings/strategies/rotation.py): for a 1x1 tiling without assumptions whose class is closed under rotation, of its positions or of its values (the whole class, or its nonempty permutations), the rule to the min cut, and to the max cut when that is a different class. In a search, a cut that is closed under rotation again is cut again. The rule counts, generates and samples objects, so Rule.sanity_check checks all three.
• RotationalCutRule, a NonBijectiveRule as FusionRule is: its forward map sends the n rotations to one object of the cut, and tells them apart by their index among the rotations, so a bijection between specifications through a cut is one to one.
• TileScopePack.add_rotational_cuts and the tilescope spec flag -r/--rotational-cuts.
• tilings.hints: hints_for(basis) returns the hints (Hint) for a class. The first is for a class closed under rotation: it names the class to search for instead, the cut, cut again while it is closed under rotation, and how its counts and generating function give the class's. tilescope spec logs the hints that its pack does not follow.
• tilescope spec no longer ends with an error when it cannot compute the generating function of the specification it found; it says so. That happens for every specification with a rotational cut, as comb_spec_searcher's get_genf cannot solve an equation with a derivative, and also for develop's specifications with catalytic variables (as with --fusion on Av(123)).
• The public helpers is_rotationally_stable, rotation_kind, min_cut, max_cut and max_cut_differs, and README and CHANGELOG entries.

Why a rule, not a verification

The cut is searched for like any other class, and the rule has an equation, generates objects and samples. A verification strategy would instead promise that a nested search enumerates the class. As comb_spec_searcher cannot compute a generating function through the rule, the hint points to the cut instead, whose generating function gives the class's.

Who will use it

TileScope users with a class closed under rotation: the hint tells them which simpler class to run, and the strategy cuts such classes wherever a search meets them. Henning's TileScope runs use it.

Tests

In tests/strategies/test_rotation.py, tests/test_hints.py, and the encoding and pack tests:

• the cuts count the classes, against brute force; every rule passes its sanity check, for the whole class and its nonempty part, including a class closed only under rotation of its values, Av(12, 21), and a class closed under both;
• the maps are inverse, and a bijection through a cut maps a specification to itself one to one;
• the equation, also for a cut that is not a geometric series;
• where the strategy does not apply, a basis that is not minimal, and the strategy's flags and JSON;
• the chain of cuts, the hints and the class they name, and tilescope spec's hint logging, its flag, and its message when it cannot compute a generating function;
• every pack in the pack tests with add_rotational_cuts, through JSON;
• a search with point_placements().add_rotational_cuts() on [1234] = Av(1234, 2341, 3412, 4123), which finds a specification with a rotational cut in about a second, with counts 1, 1, 2, 6, 20, 65, 198, 560, 1480. Its generating function, derived from the cut's (Av(123, 3412)), is (1 - 8x + 27x^2 - 48x^3 + 49x^4 - 27x^5 + 6x^6 - 4x^7)/((1 - 2x)^2 (1 - x)^5).

How it was checked

Before submission, by an automated reviewer, against develop of all three libraries:

• flake8, mypy, pylint and black pass, and on CPython 3.14 and PyPy 3.11 all 3,863 tests pass;
• a brute-force check of every class made of one or two rotation orbits of patterns of lengths 3 and 4: the cuts count the class, each rule passes its sanity check, and the indexed maps are a bijection;
• an independent implementation of the hint's chain of cuts, on 106 classes and in random sweeps of thousands more: the class it names, its counts and its generating function agree with brute force;
• bijections between specifications through cuts, of positions and of values, min and max cuts, whole and nonempty, and after a JSON round trip, are one to one;
• mutation testing of the changed code, and timing of standard packs on develop and on this branch, which run equally fast.

---

AI assistance: written with Claude Code (Opus 5.5) as the TileScope agent, and reviewed before submission by Claude Code (Opus 5.5) as an automated reviewer; Henning Ulfarsson checked and opened it.