Skip to content

Patterns

Pattern classes for generating sequences of values.

This module provides pattern classes inspired by SuperCollider's pattern system for generating sequences, random selections, and non-repeating random selections from lists of values.

Classes:

Name Description
Pseq

Sequential pattern that cycles through a list
Prand

Random pattern that selects randomly from a list

Pxrand

Exclusive random pattern that avoids immediate repetition

PVoiceAllocator

Voice allocator for managing polyphonic voice assignments.

PVoiceAllocator keeps track of busy and free voices for polyphonic synthesis, allowing for efficient voice allocation and deallocation.

Attributes:

Name Type Description
num_voices

Total number of voices available
busy_list

List tracking the status of each voice (-1 for free, otherwise holds the note number)
Source code in mmm_src/Patterns.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
class PVoiceAllocator:
    """
    Voice allocator for managing polyphonic voice assignments.

    PVoiceAllocator keeps track of busy and free voices for
    polyphonic synthesis, allowing for efficient voice allocation
    and deallocation.

    Attributes:
        num_voices: Total number of voices available
        busy_list: List tracking the status of each voice (-1 for free,
                   otherwise holds the note number)
    """
    def __init__(self, num_voices):
        self.num_voices = num_voices
        self.busy_list = [-1] * num_voices
        self.counter = 0
        self.voice_seq = Pseq(list(range(num_voices)))

    def get_free_voice(self, note):
        counter = 0
        found = False
        while not found and counter < 8:
            voice = self.voice_seq.next()
            if self.busy_list[voice] == -1:
                self.busy_list[voice] = note
                found = True
                return voice
            counter += 1
        return -1  # all voices are busy

    def release_voice(self, note):
        counter = 0
        found = False
        while not found and counter < self.num_voices:
            if self.busy_list[counter] == note:
                self.busy_list[counter] = -1
                return (True, counter)
            counter += 1
        return (False, -1)

Prand

Random pattern that selects values randomly from a list.

Prand generates values by randomly selecting from a list with equal probability for each element. The same value can be selected consecutively.

Attributes:

Name Type Description
list

The list of values to select from randomly
Example 
pattern = Prand([1, 2, 3, 4])
print(pattern.next())  # Random selection: 1, 2, 3, or 4
print(pattern.next())  # Another random selection
Source code in mmm_src/Patterns.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
class Prand:
    """
    Random pattern that selects values randomly from a list.

    Prand generates values by randomly selecting from a list with
    equal probability for each element. The same value can be
    selected consecutively.

    Attributes:
        list: The list of values to select from randomly

    Example:
        ```python
        pattern = Prand([1, 2, 3, 4])
        print(pattern.next())  # Random selection: 1, 2, 3, or 4
        print(pattern.next())  # Another random selection
        ```
    """
    def __init__(self, list: list[float]):
        """
        Initialize a random pattern.

        Args:
            list: A list of values to select from randomly
        """
        self.list = list

    def next(self) -> Optional[float]:
        """
        Get a random value from the list.

        Returns:
            A randomly selected value from the list. Returns None
            if the list is empty.
        """
        if not self.list:
            return None
        return choice(self.list)

__init__(list)

Initialize a random pattern.

Parameters:

Name Type Description Default
list list[float]

A list of values to select from randomly

 required
Source code in mmm_src/Patterns.py 
91
92
93
94
95
96
97
98
def __init__(self, list: list[float]):
    """
    Initialize a random pattern.

    Args:
        list: A list of values to select from randomly
    """
    self.list = list

next()

Get a random value from the list.

Returns:

Type Description
Optional[float]

A randomly selected value from the list. Returns None
Optional[float]

if the list is empty.
Source code in mmm_src/Patterns.py 
100
101
102
103
104
105
106
107
108
109
110
def next(self) -> Optional[float]:
    """
    Get a random value from the list.

    Returns:
        A randomly selected value from the list. Returns None
        if the list is empty.
    """
    if not self.list:
        return None
    return choice(self.list)

Pseq

Sequential pattern that cycles through a list of values.

Pseq generates values by iterating through a list sequentially, wrapping back to the beginning when it reaches the end.

Attributes:

Name Type Description
list

The list of values to cycle through
index

Current position in the list (starts at -1)
Example 
pattern = Pseq([1, 2, 3])
print(pattern.next())  # 1
print(pattern.next())  # 2
print(pattern.next())  # 3
print(pattern.next())  # 1 (cycles back)
Source code in mmm_src/Patterns.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class Pseq:
    """
    Sequential pattern that cycles through a list of values.

    Pseq generates values by iterating through a list sequentially,
    wrapping back to the beginning when it reaches the end.

    Attributes:
        list: The list of values to cycle through
        index: Current position in the list (starts at -1)

    Example:
        ```python
        pattern = Pseq([1, 2, 3])
        print(pattern.next())  # 1
        print(pattern.next())  # 2
        print(pattern.next())  # 3
        print(pattern.next())  # 1 (cycles back)
        ```
    """
    def __init__(self, list: list[float]):
        """
        Initialize a sequential pattern.

        Args:
            list: A list of values to cycle through sequentially
        """
        self.list = list
        self.index = -1

    def next(self) -> Optional[float]:
        """
        Get the next value in the sequence.

        Returns:
            The next value in the list, cycling back to the beginning
            when reaching the end. Returns None if the list is empty.
        """
        if not self.list:
            return None
        self.index = (self.index + 1) % len(self.list)
        if self.index > len(self.list):
            self.index = 0
        return self.list[self.index]

    def go_back(self, n=1):
        """
        Move the sequence index back by n steps.

        Args:
            n: Number of steps to move back in the sequence
        """
        if not self.list:
            return
        self.index = (self.index - n) % len(self.list)

__init__(list)

Initialize a sequential pattern.

Parameters:

Name Type Description Default
list list[float]

A list of values to cycle through sequentially

 required
Source code in mmm_src/Patterns.py 
37
38
39
40
41
42
43
44
45
def __init__(self, list: list[float]):
    """
    Initialize a sequential pattern.

    Args:
        list: A list of values to cycle through sequentially
    """
    self.list = list
    self.index = -1

go_back(n=1)

Move the sequence index back by n steps.

Parameters:

Name Type Description Default
n

Number of steps to move back in the sequence

 1
Source code in mmm_src/Patterns.py 
62
63
64
65
66
67
68
69
70
71
def go_back(self, n=1):
    """
    Move the sequence index back by n steps.

    Args:
        n: Number of steps to move back in the sequence
    """
    if not self.list:
        return
    self.index = (self.index - n) % len(self.list)

next()

Get the next value in the sequence.

Returns:

Type Description
Optional[float]

The next value in the list, cycling back to the beginning
Optional[float]

when reaching the end. Returns None if the list is empty.
Source code in mmm_src/Patterns.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def next(self) -> Optional[float]:
    """
    Get the next value in the sequence.

    Returns:
        The next value in the list, cycling back to the beginning
        when reaching the end. Returns None if the list is empty.
    """
    if not self.list:
        return None
    self.index = (self.index + 1) % len(self.list)
    if self.index > len(self.list):
        self.index = 0
    return self.list[self.index]

Pxrand

Exclusive random pattern that avoids immediate repetition.

Pxrand generates values by randomly selecting from a list while ensuring that the same value is never selected twice in a row. This is useful for creating varied sequences without consecutive duplicates.

Attributes:

Name Type Description
list

The list of values to select from
last_index

Index of the previously selected value
Note

This pattern requires a list with at least 2 elements to function properly and avoid repetition.

Example 
pattern = Pxrand([1, 2, 3, 4])
print(pattern.next())  # Random selection: 1, 2, 3, or 4
print(pattern.next())  # Different from previous selection
Source code in mmm_src/Patterns.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
class Pxrand:
    """
    Exclusive random pattern that avoids immediate repetition.

    Pxrand generates values by randomly selecting from a list while
    ensuring that the same value is never selected twice in a row.
    This is useful for creating varied sequences without consecutive
    duplicates.

    Attributes:
        list: The list of values to select from
        last_index: Index of the previously selected value

    Note:
        This pattern requires a list with at least 2 elements to
        function properly and avoid repetition.

    Example:
        ```python
        pattern = Pxrand([1, 2, 3, 4])
        print(pattern.next())  # Random selection: 1, 2, 3, or 4
        print(pattern.next())  # Different from previous selection
        ```
    """
    def __init__(self, list: list[float]):
        """
        Initialize an exclusive random pattern.

        Args:
            list: A list of values to select from (should have at least 
                  2 elements for proper exclusive behavior)
        """
        self.list = list
        self.last_index = -1

    def next(self) -> Optional[float]:
        """
        Get a random value that differs from the previous selection.

        Returns:
            A randomly selected value from the list that is guaranteed
            to be different from the previous selection. Returns None
            if the list is empty.
        """
        if not self.list:
            return None
        self.last_index = (self.last_index + randint(1, len(self.list) - 1)) % len(self.list)
        return self.list[self.last_index]

__init__(list)

Initialize an exclusive random pattern.

Parameters:

Name Type Description Default
list list[float]

A list of values to select from (should have at least 2 elements for proper exclusive behavior)

 required
Source code in mmm_src/Patterns.py 
136
137
138
139
140
141
142
143
144
145
def __init__(self, list: list[float]):
    """
    Initialize an exclusive random pattern.

    Args:
        list: A list of values to select from (should have at least 
              2 elements for proper exclusive behavior)
    """
    self.list = list
    self.last_index = -1

next()

Get a random value that differs from the previous selection.

Returns:

Type Description
Optional[float]

A randomly selected value from the list that is guaranteed
Optional[float]

to be different from the previous selection. Returns None
Optional[float]

if the list is empty.
Source code in mmm_src/Patterns.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
def next(self) -> Optional[float]:
    """
    Get a random value that differs from the previous selection.

    Returns:
        A randomly selected value from the list that is guaranteed
        to be different from the previous selection. Returns None
        if the list is empty.
    """
    if not self.list:
        return None
    self.last_index = (self.last_index + randint(1, len(self.list) - 1)) % len(self.list)
    return self.list[self.last_index]