abjad.pattern

abjad.pattern.Pattern([indices, inverted, ...])	Pattern.
abjad.pattern.PatternTuple([items])	Pattern tuple.

class abjad.pattern.Pattern(indices: Any = None, inverted: Any = None, operator: Any = None, patterns: Any = None, payload: Any = None, period: Any = None)

Pattern.

Matches three indices out of every eight:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 True
9 True
10 
11 
12 
13 
14 
15 True

Matches three indices out of every sixteen:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=16,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 
9 
10 
11 
12 
13 
14 
15 

Works with improper indices:

>>> pattern = abjad.Pattern(
...     indices=[16, 17, 23],
...     period=16,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 
9 
10 
11 
12 
13 
14 
15 

Sieve from opening of Xenakis’s Psappha:

>>> sieve_1a = abjad.index([0, 1, 7], 8)
>>> sieve_1b = abjad.index([1, 3], 5)
>>> sieve_1 = sieve_1a & sieve_1b
>>> sieve_2a = abjad.index([0, 1, 2], 8)
>>> sieve_2b = abjad.index([0], 5)
>>> sieve_2 = sieve_2a & sieve_2b
>>> sieve_3 = abjad.index([3], 8)
>>> sieve_4 = abjad.index([4], 8)
>>> sieve_5a = abjad.index([5, 6], 8)
>>> sieve_5b = abjad.index([2, 3, 4], 5)
>>> sieve_5 = sieve_5a & sieve_5b
>>> sieve_6a = abjad.index([1], 8)
>>> sieve_6b = abjad.index([2], 5)
>>> sieve_6 = sieve_6a & sieve_6b
>>> sieve_7a = abjad.index([6], 8)
>>> sieve_7b = abjad.index([1], 5)
>>> sieve_7 = sieve_7a & sieve_7b
>>> sieve = sieve_1 | sieve_2 | sieve_3 | sieve_4 | sieve_5 | sieve_6 | sieve_7

>>> sieve.get_boolean_vector(total_length=40)
[1, 1, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 0, 1, 1, 0, 1, 1, 0, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 0]

Inverted works like this:

Matches three indices out of every eight:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> pattern.inverted is None
True

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 True
9 True
10 
11 
12 
13 
14 
15 True

Pattern that rejects three indices from every eight; equivalently, pattern matches 8-3=5 indices out of every eight:

>>> pattern = abjad.Pattern(indices=[0, 1, 7], period=8, inverted=True)

>>> pattern.inverted
True

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 True
3 True
4 True
5 True
6 True
7 
8 
9 
10 True
11 True
12 True
13 True
14 True
15 

Matches every index that is (one of the first three indices) OR (one of the last three indices):

>>> pattern_1 = abjad.index_first(3)
>>> pattern_2 = abjad.index_last(3)
>>> pattern = pattern_1 | pattern_2
>>> pattern.inverted is None
True

>>> pattern.get_boolean_vector(total_length=16)
[1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1]

Matches every index that is NOT (one of the first three indices) OR (one of the last three indices):

>>> import dataclasses
>>> pattern = dataclasses.replace(pattern, inverted=True)
>>> pattern.inverted
True

>>> pattern.get_boolean_vector(total_length=16)
[0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0]

Payload works like this: Pattern with string payload assigned to three of every eight indices:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     payload="Allegro non troppo",
...     period=8,
... )

>>> total_length = 10
>>> for index in range(10):
...     match = pattern.matches_index(index, total_length)
...     if match:
...         payload = pattern.payload
...     else:
...         payload = ""
...     print(index, repr(payload))
... 
0 'Allegro non troppo'
1 'Allegro non troppo'
2 ''
3 ''
4 ''
5 ''
6 ''
7 'Allegro non troppo'
8 'Allegro non troppo'
9 'Allegro non troppo'

Period works like this:

Pattern with a period of eight:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> pattern.period
8

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 True
9 True
10 
11 
12 
13 
14 
15 True

Same pattern with a period of sixteen:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=16,
... )

>>> pattern.period
16

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 
9 
10 
11 
12 
13 
14 
15 

Gets period of pattern that indexs every fourth and fifth element:

>>> pattern_1 = abjad.Pattern([0], period=4)
>>> pattern_2 = abjad.Pattern([0], period=5)
>>> pattern = pattern_1 | pattern_2
>>> pattern
Pattern(indices=None, inverted=None, operator='or', patterns=(Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=4), Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=5)), payload=None, period=20)

>>> pattern.period
20

Returns none when pattern contains acyclic parts:

>>> pattern_1 = abjad.Pattern([0], period=4)
>>> pattern_2 = abjad.Pattern([0])
>>> pattern = pattern_1 | pattern_2
>>> pattern
Pattern(indices=None, inverted=None, operator='or', patterns=(Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=4), Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=None)), payload=None, period=None)

>>> pattern.period is None
True

advance([count])	Advances pattern.
get_boolean_vector([total_length])	Gets boolean vector of pattern applied to input sequence with total_length.
get_matching_items(sequence)	Gets maching items from sequence.
matches_index(index, total_length[, rotation])	Is true when pattern matches index taken under total_length.
reverse()	Reverses pattern.
rotate([n])	Rotates pattern by index n.
weight	Gets weight of pattern.

advance(count: int | None = None) → Pattern

Advances pattern.

>>> pattern = abjad.Pattern([0, 2, 12])

>>> pattern = pattern.advance(8)
>>> pattern
Pattern(indices=(4,), inverted=None, operator=None, patterns=None, payload=None, period=None)

>>> pattern = pattern.advance(8)
>>> pattern
Pattern(indices=(), inverted=None, operator=None, patterns=None, payload=None, period=None)

Returns copy of pattern when count is none:

>>> pattern = abjad.Pattern([0, 2, 12])
>>> pattern.advance()
Pattern(indices=(0, 2, 12), inverted=None, operator=None, patterns=None, payload=None, period=None)

Raises exception on attempt to advance negative pattern:

>>> pattern = abjad.Pattern([-2, -1])
>>> pattern.advance(8)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/trevor/Repositories/Projects/abjad/source/abjad/pattern.py", line 784, in advance
    raise Exception(message)
Exception: can not advance pattern with negative indices (Pattern(indices=(-2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)).

get_boolean_vector(total_length=None) → list[int]

Gets boolean vector of pattern applied to input sequence with total_length.

Returns list of ones and zeroes.

Gets boolean vector of acyclic pattern:

>>> pattern = abjad.Pattern(indices=[4, 5, 6, 7])

>>> pattern.get_boolean_vector(4)
[0, 0, 0, 0]

>>> pattern.get_boolean_vector(8)
[0, 0, 0, 0, 1, 1, 1, 1]

>>> pattern.get_boolean_vector(16)
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]

Sets total length to length of pattern when total_length is none:

>>> pattern.get_boolean_vector()
[0, 0, 0, 0, 1, 1, 1, 1]

Gets vector of cyclic pattern:

>>> pattern = abjad.Pattern(
...     indices=[4, 5, 6, 7],
...     period=20,
... )

>>> pattern.get_boolean_vector(4)
[0, 0, 0, 0]

>>> pattern.get_boolean_vector(8)
[0, 0, 0, 0, 1, 1, 1, 1]

>>> pattern.get_boolean_vector(16)
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]

Sets total length to length of pattern when total_length is none:

>>> pattern.get_boolean_vector()
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Gets vector of inverted pattern:

>>> pattern = abjad.Pattern(
...     indices=[4, 5, 6, 7],
...     period=20,
... )

>>> pattern.get_boolean_vector(4)
[0, 0, 0, 0]

>>> pattern.get_boolean_vector(8)
[0, 0, 0, 0, 1, 1, 1, 1]

>>> pattern.get_boolean_vector(16)
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]

Sets total length to length of pattern when total_length is none:

>>> pattern.get_boolean_vector()
[0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Two-part pattern with logical OR. Matches every index that is (one of the first three indices) OR (one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="or",
...     patterns=[
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...         ),
...     ],
... )

>>> pattern.get_boolean_vector(4)
[1, 1, 1, 1]

>>> pattern.get_boolean_vector(8)
[1, 1, 1, 0, 0, 1, 1, 1]

>>> pattern.get_boolean_vector(16)
[1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1]

Two-part pattern with mixed periodic and inverted parts. Matches every index that is (equal to 0 % 2) AND (not one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="and",
...     patterns=[
...         abjad.Pattern(
...             indices=[0],
...             period=2,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...             inverted=True,
...         ),
...     ],
... )

>>> pattern.get_boolean_vector(4)
[1, 0, 0, 0]

>>> pattern.get_boolean_vector(8)
[1, 0, 1, 0, 1, 0, 0, 0]

>>> pattern.get_boolean_vector(16)
[1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 0, 0]

Cyclic pattern that indexes every fourth and fifth item:

>>> pattern_1 = abjad.Pattern([0], period=4)
>>> pattern_2 = abjad.Pattern([0], period=5)
>>> pattern = pattern_1 | pattern_2
>>> pattern
Pattern(indices=None, inverted=None, operator='or', patterns=(Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=4), Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=5)), payload=None, period=20)

>>> pattern.get_boolean_vector(4)
[1, 0, 0, 0]

>>> pattern.get_boolean_vector(8)
[1, 0, 0, 0, 1, 1, 0, 0]

>>> pattern.get_boolean_vector(16)
[1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1]

Sets total length to period of pattern when total_length is none:

>>> pattern.period
20

>>> pattern.get_boolean_vector()
[1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 0]

>>> pattern.period == len(pattern.get_boolean_vector())
True

get_matching_items(sequence)

Gets maching items from sequence.

Returns list.

>>> pattern = abjad.Pattern(
...     indices=[4, 5, 6, 7],
... )

>>> pattern.get_matching_items("abcdefghijklmnopqrstuvwxyz")
['e', 'f', 'g', 'h']

>>> pattern = abjad.Pattern(
...     indices=[8, 9],
...     period=10,
... )

>>> pattern.get_matching_items("abcdefghijklmnopqrstuvwxyz")
['i', 'j', 's', 't']

>>> pattern = abjad.index_first(1) | abjad.index_last(2)

>>> pattern.get_matching_items("abcdefghijklmnopqrstuvwxyz")
['a', 'y', 'z']

matches_index(index, total_length, rotation=None) → bool

Is true when pattern matches index taken under total_length.

Matches three indices out of every eight:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 True
9 True
10 
11 
12 
13 
14 
15 True

Matches three indices out of every eight, offset 1 to the left:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=1,
...     )
...     match = match or ""
...     print(index, match)
... 
0 True
1 
2 
3 
4 
5 
6 True
7 True
8 True
9 
10 
11 
12 
13 
14 True
15 True

Matches three indices out of every eight, offset 2 to the left:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=2,
...     )
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 
4 
5 True
6 True
7 True
8 
9 
10 
11 
12 
13 True
14 True
15 True

Matches three indices out of every sixteen:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=16,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 
9 
10 
11 
12 
13 
14 
15 

Matches three indices out of every sixteen, offset 1 to the left:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=16,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=1,
...     )
...     match = match or ""
...     print(index, match)
... 
0 True
1 
2 
3 
4 
5 
6 True
7 
8 
9 
10 
11 
12 
13 
14 
15 True

Matches three indices out of every sixteen, offset 2 to the left:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=16,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(
...         index,
...         total_length,
...         rotation=2,
...     )
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 
4 
5 True
6 
7 
8 
9 
10 
11 
12 
13 
14 True
15 True

Empty pattern:

>>> pattern = abjad.Pattern()

Total length 16:

>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 

Total length 8:

>>> total_length = 8
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 
4 
5 
6 
7 

Total length 4:

>>> total_length = 4
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 

Matches nothing.

Simple pattern:

Logical OR:

>>> pattern = abjad.Pattern(
...     operator="or",
...     patterns=[
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...     ],
... )
>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 

Logical AND:

>>> pattern = abjad.Pattern(
...     operator="and",
...     patterns=[
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...     ],
... )
>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 

Logical XOR; matches every index that is (one of the first three indices); ignores operator:

>>> pattern = abjad.Pattern(
...     operator="xor",
...     patterns=[
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...     ],
... )
>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 

Two-part pattern with logical OR; matches every index that is (one of the first three indices) OR (one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="or",
...     patterns=[
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...         ),
...     ],
... )

Total length 16:

>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 True
14 True
15 True

Total length 8:

>>> total_length = 8
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 
5 True
6 True
7 True

Total length 4:

>>> total_length = 4
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 True

Two-part pattern with logical AND; matches every index that is (one of the first three indices) AND (one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="and",
...     patterns=[
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...         ),
...     ],
... )

Total length 16:

>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 

Total length 8:

>>> total_length = 8
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 
4 
5 
6 
7 

Total length 4:

>>> total_length = 4
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 True
2 True
3 

Two-part pattern with logical XOR; matches every index that is (one of the first three indices) XOR (one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="xor",
...     patterns=[
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...         ),
...     ],
... )

Total length 16:

>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 True
14 True
15 True

Total length 8:

>>> total_length = 8
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 
5 True
6 True
7 True

Total length 4:

>>> total_length = 4
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 
2 
3 True

Two-part pattern with mixed periodic and inverted parts; matches every index that is (equal to 0 % 2) AND (not one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="and",
...     patterns=[
...         abjad.Pattern(
...             indices=[0],
...             period=2,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...             inverted=True,
...         ),
...     ],
... )

Total length 16:

>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 
2 True
3 
4 True
5 
6 True
7 
8 True
9 
10 True
11 
12 True
13 
14 
15 

Total length 8:

>>> total_length = 8
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 
2 True
3 
4 True
5 
6 
7 

Total length 4:

>>> total_length = 4
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 
2 
3 

Complex pattern with compound and simple parts; matches every index that is ((equal to 0 % 2) AND (not one of the last three indices)) OR is (one of the first three indices):

>>> pattern = abjad.Pattern(
...     operator="and",
...     patterns=[
...         abjad.Pattern(
...             indices=[0],
...             period=2,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...             inverted=True,
...         ),
...     ],
... )
>>> pattern = abjad.Pattern(
...     operator="or",
...     patterns=[
...         pattern,
...         abjad.Pattern(
...             indices=[0, 1, 2],
...         ),
...     ],
... )
>>> pattern
Pattern(indices=None, inverted=None, operator='or', patterns=(Pattern(indices=None, inverted=None, operator='and', patterns=(Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=2), Pattern(indices=(-3, -2, -1), inverted=True, operator=None, patterns=None, payload=None, period=None)), payload=None, period=None), Pattern(indices=(0, 1, 2), inverted=None, operator=None, patterns=None, payload=None, period=None)), payload=None, period=None)

Total length 16:

>>> total_length = 16
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 True
5 
6 True
7 
8 True
9 
10 True
11 
12 True
13 
14 
15 

Total length 8:

>>> total_length = 8
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 
4 True
5 
6 
7 

Total length 4:

>>> total_length = 4
>>> for index in range(total_length):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 True
3 

reverse() → Pattern

Reverses pattern.

Matches three indices out of every eight:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 True
9 True
10 
11 
12 
13 
14 
15 True

Reverses pattern:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> pattern = pattern.reverse()
>>> pattern
Pattern(indices=(-1, -2, -8), inverted=None, operator=None, patterns=None, payload=None, period=8)

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 
2 
3 
4 
5 
6 True
7 True
8 True
9 
10 
11 
12 
13 
14 True
15 True

Matches every index that is (equal to 0 % 2) AND (not one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="and",
...     patterns=[
...         abjad.Pattern(
...             indices=[0],
...             period=2,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...             inverted=True,
...         ),
...     ],
... )
>>> pattern
Pattern(indices=None, inverted=None, operator='and', patterns=(Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=2), Pattern(indices=(-3, -2, -1), inverted=True, operator=None, patterns=None, payload=None, period=None)), payload=None, period=None)

Reverses pattern; new pattern matches every index that is (equal to -1 % 2) AND (not one of the first three indices):

>>> pattern = pattern.reverse()
>>> pattern
Pattern(indices=None, inverted=None, operator='and', patterns=(Pattern(indices=(-1,), inverted=None, operator=None, patterns=None, payload=None, period=2), Pattern(indices=(2, 1, 0), inverted=True, operator=None, patterns=None, payload=None, period=None)), payload=None, period=None)

rotate(n=0) → Pattern

Rotates pattern by index n.

Matches three indices out of every eight:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 True
9 True
10 
11 
12 
13 
14 
15 True

Rotates pattern two elements to the right:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> pattern = pattern.rotate(n=2)
>>> pattern
Pattern(indices=(2, 3, 9), inverted=None, operator=None, patterns=None, payload=None, period=8)

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 True
2 True
3 True
4 
5 
6 
7 
8 
9 True
10 True
11 True
12 
13 
14 
15 

Matches three indices out of every eight with negative indices:

>>> pattern = abjad.Pattern(
...     indices=[-3, -2, -1],
...     period=8,
... )

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 
1 
2 
3 
4 
5 True
6 True
7 True
8 
9 
10 
11 
12 
13 True
14 True
15 True

Rotates pattern two elements to the right:

>>> pattern = abjad.Pattern(
...     indices=[-3, -2, -1],
...     period=8,
... )

>>> pattern = pattern.rotate(n=2)
>>> pattern
Pattern(indices=(-1, 0, 1), inverted=None, operator=None, patterns=None, payload=None, period=8)

>>> total_length = 16
>>> for index in range(16):
...     match = pattern.matches_index(index, total_length)
...     match = match or ""
...     print(index, match)
... 
0 True
1 True
2 
3 
4 
5 
6 
7 True
8 True
9 True
10 
11 
12 
13 
14 
15 True

Matches every index that is (equal to 0 % 2) AND (not one of the last three indices):

>>> pattern = abjad.Pattern(
...     operator="and",
...     patterns=[
...         abjad.Pattern(
...             indices=[0],
...             period=2,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...             inverted=True,
...         ),
...     ],
... )
>>> pattern
Pattern(indices=None, inverted=None, operator='and', patterns=(Pattern(indices=(0,), inverted=None, operator=None, patterns=None, payload=None, period=2), Pattern(indices=(-3, -2, -1), inverted=True, operator=None, patterns=None, payload=None, period=None)), payload=None, period=None)

Rotates pattern two elements to the right; new pattern matches every index that is (equal to 2 % 2) AND (not the first, second or last index in the pattern):

>>> pattern = pattern.rotate(n=2)
>>> pattern
Pattern(indices=None, inverted=None, operator='and', patterns=(Pattern(indices=(2,), inverted=None, operator=None, patterns=None, payload=None, period=2), Pattern(indices=(-1, 0, 1), inverted=True, operator=None, patterns=None, payload=None, period=None)), payload=None, period=None)

weight

Gets weight of pattern.

Gets weight of cyclic pattern:

>>> pattern = abjad.Pattern(
...     indices=[0, 1, 7],
...     period=8,
... )

>>> pattern.weight
3

Gets weight of acyclic pattern:

>>> pattern = abjad.Pattern(
...     indices=[0, 2, 3],
... )

>>> pattern.weight
3

Weight defined equal to number of indices in pattern.

Returns nonnegative integer.

class abjad.pattern.PatternTuple(items: Sequence = ())

Pattern tuple.

Three patterns:

>>> patterns = abjad.PatternTuple(
...     [
...         abjad.Pattern(
...             indices=[0, 1, 7],
...             period=10,
...         ),
...         abjad.Pattern(
...             indices=[-2, -1],
...         ),
...         abjad.Pattern(
...             indices=[2],
...             period=3,
...         ),
...     ]
... )
>>> patterns
PatternTuple(items=(Pattern(indices=(0, 1, 7), inverted=None, operator=None, patterns=None, payload=None, period=10), Pattern(indices=(-2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None), Pattern(indices=(2,), inverted=None, operator=None, patterns=None, payload=None, period=3)))

Two patterns:

>>> patterns = abjad.PatternTuple(
...     [
...         abjad.Pattern(
...             indices=[1],
...             period=2,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...         ),
...     ]
... )
>>> patterns
PatternTuple(items=(Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2), Pattern(indices=(-3, -2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)))

get_matching_pattern(index, total_length[, ...])	Gets pattern matching index.
get_matching_payload(index, total_length[, ...])	Gets payload attached to pattern matching index.

get_matching_pattern(index, total_length, rotation=None) → Pattern | None

Gets pattern matching index.

Two patterns:

>>> patterns = abjad.PatternTuple(
...     [
...         abjad.Pattern(
...             indices=[1],
...             period=2,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...         ),
...     ]
... )

Gets patterns that match the first ten indices; last three indices match the second pattern:

>>> for i in range(10):
...     match = patterns.get_matching_pattern(i, 10)
...     print(i, match)
... 
0 None
1 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
2 None
3 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
4 None
5 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
6 None
7 Pattern(indices=(-3, -2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)
8 Pattern(indices=(-3, -2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)
9 Pattern(indices=(-3, -2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)

Gets patterns that match next ten indices; last three indices no longer match the second pattern:

>>> for i in range(10, 20):
...     match = patterns.get_matching_pattern(i, 10)
...     print(i, match)
... 
10 None
11 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
12 None
13 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
14 None
15 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
16 None
17 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
18 None
19 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)

Gets patterns that match the first ten indices, with rotation set to 1; matching indices of first pattern offset by 1:

>>> for i in range(10):
...     match = patterns.get_matching_pattern(i, 10, rotation=1)
...     print(i, match)
... 
0 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
1 None
2 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
3 None
4 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
5 None
6 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
7 Pattern(indices=(-3, -2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)
8 Pattern(indices=(-3, -2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)
9 Pattern(indices=(-3, -2, -1), inverted=None, operator=None, patterns=None, payload=None, period=None)

Gets patterns that match next ten indices with rotation set to 1; matching indices of first pattern offset by 1:

>>> for i in range(10, 20):
...     match = patterns.get_matching_pattern(i, 10, rotation=1)
...     print(i, match)
... 
10 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
11 None
12 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
13 None
14 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
15 None
16 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
17 None
18 Pattern(indices=(1,), inverted=None, operator=None, patterns=None, payload=None, period=2)
19 None

With inverted patterns:

>>> patterns = abjad.PatternTuple(
...     [
...         abjad.Pattern(
...             indices=[-3],
...             inverted=True,
...         ),
...     ]
... )

>>> for i in range(10):
...     match = patterns.get_matching_pattern(i, 10)
...     print(i, match)
... 
0 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
1 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
2 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
3 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
4 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
5 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
6 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
7 None
8 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)
9 Pattern(indices=(-3,), inverted=True, operator=None, patterns=None, payload=None, period=None)

get_matching_payload(index, total_length, rotation=None)

Gets payload attached to pattern matching index.

Two patterns. Underlying notes with even divisions assigned to the last three indices:

>>> patterns = abjad.PatternTuple(
...     [
...         abjad.Pattern(
...             indices=[0],
...             payload="staccato",
...             period=1,
...         ),
...         abjad.Pattern(
...             indices=[-3, -2, -1],
...             payload="tenuto",
...         ),
...     ]
... )

Over ten indices:

>>> for i in range(10):
...     match = patterns.get_matching_payload(i, 10)
...     print(i, match)
... 
0 staccato
1 staccato
2 staccato
3 staccato
4 staccato
5 staccato
6 staccato
7 tenuto
8 tenuto
9 tenuto

Over fifteen indices:

>>> for i in range(15):
...     match = patterns.get_matching_payload(i, 15)
...     print(i, match)
... 
0 staccato
1 staccato
2 staccato
3 staccato
4 staccato
5 staccato
6 staccato
7 staccato
8 staccato
9 staccato
10 staccato
11 staccato
12 tenuto
13 tenuto
14 tenuto