music.transpose_permutation¶

music.transpose_permutation(permutation, step=1)[source]¶

Shifts a permutation up or down by step positions.

Where permutation sends i to j, the result sends i + step to j + step: every cycle keeps its order and its direction, only moved along. A swap of neighbours becomes the swap of the next pair, which is how a change moves along a row of bells.

Parameters:

permutationsympy.combinatorics.Permutation: The permutation to be transposed.
stepint, optional: The number of positions to shift each element of the permutation, by default 1. Negative shifts it down.

Returns:

sympy.combinatorics.Permutation: The shifted permutation, on as many elements as permutation or more if the shifted points need them, so that it still acts on the domain the original did.

Raises:

ValueError: If step would move a point below zero.

Notes

If step is 0, the function returns the original permutation.

It used to return one cycle through the moved points in ascending order, which is right only for a single swap: (0 2 1) came back as (1 2 3), running the other way, and two swaps (0 1)(2 3) as the four-cycle (1 2 3 4). It was also sized to the highest point, so a shifted swap of four bells could not act on a row of four.

Examples

>>> from sympy.combinatorics import Permutation
>>> perm = Permutation([2, 0, 1])
>>> transpose_permutation(perm, 1).array_form
[0, 3, 1, 2]
>>> transpose_permutation(perm, 0).array_form
[2, 0, 1]
>>> transpose_permutation(Permutation(0, 1, size=4)).array_form
[0, 2, 1, 3]