mutwo.common_generators §

Object	Documentation
`mutwo.common_generators.random_walk_noise`	Generate an instance of Brownian motion (i.e. the Wiener process).
`mutwo.common_generators.make_bruns_euclidean_algorithm_generator`	Make generator which runs Bruns adaption of the Euclidean algorithm.
`mutwo.common_generators.NonTerminal`	Can be used as a Mixin to define context-free grammar.
`mutwo.common_generators.Terminal`	Can be used as a Mixin to define context-free grammar.
`mutwo.common_generators.ContextFreeGrammarRule`	Describe a context_free_grammar_rule for a `ContextFreeGrammar`
`mutwo.common_generators.ContextFreeGrammar`	Describe a context-free grammar and resolve non-terminals
`mutwo.common_generators.ActivityLevel`	Python implementation of Michael Edwards activity level algorithm.
`mutwo.common_generators.reflected_binary_code`	Make gray code where each tuple has length items with modulus different numbers.
`mutwo.common_generators.Tendency`	Tendency offers an interface for dynamically changing minima / maxima areas.
`mutwo.common_generators.Backtracking`	Abstract base class to implement a backtracking algorithm
`mutwo.common_generators.IndexBasedBacktracking`	Abstract base class for index based backtracking algorithms
`mutwo.common_generators.euclidean`	Return euclidean rhythm as described in a 2005 paper by G. T. Toussaint.
`mutwo.common_generators.paradiddle`	Generates rhythm using the paradiddle method described by G. T. Toussaint.
`mutwo.common_generators.alternating_hands`	Generates rhythm using the alternating hands method described by G. T. Toussaint.

random_walk_noise(x0, n, dt, delta, out=None, random_state=None)[source]§

Generate an instance of Brownian motion (i.e. the Wiener process).

Parameters:

x0 (float) – the initial condition(s) (i.e. position(s)) of the Brownian motion.
n (int) – the number of steps to take
dt (float) – the time step
delta (float) – delta determines the “speed” of the Brownian motion. The random variable of the position at time t, X(t), has a normal distribution whose mean is the position at time t=0 and whose variance is delta**2*t.
out (Optional[array]) – If out is not None, it specifies the array in which to put the result. If out is None, a new numpy array is created and returned.
random_state (Optional[int]) – set the random seed of the pseudo-random generator.

Returns:

A numpy array of floats with shape x0.shape + (n,).

Return type:

array

X(t) = X(0) + N(0, delta**2 * t; 0, t)

where N(a,b; t0, t1) is a normally distributed random variable with mean a and variance b. The parameters t0 and t1 make explicit the statistical independence of N on different time intervals; that is, if [t0, t1) and [t2, t3) are disjoint intervals, then N(a, b; t0, t1) and N(a, b; t2, t3) are independent.

Written as an iteration scheme,

X(t + dt) = X(t) + N(0, delta**2 * dt; t, t+dt)

If x0 is an array (or array-like), each value in x0 is treated as an initial condition, and the value returned is a numpy array with one more dimension than x0.

Note that the initial value x0 is not included in the returned array.

This code has been copied from the scipy cookbook:: https://scipy-cookbook.readthedocs.io/items/BrownianMotion.html

make_bruns_euclidean_algorithm_generator(element_tuple, matrix=array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]), subtraction_index=1)[source]§

Make generator which runs Bruns adaption of the Euclidean algorithm.

Parameters:

element_tuple (tuple[_BrunEuclideanElement, _BrunEuclideanElement, _BrunEuclideanElement]) – The initial elements which gets re-calculated after each step. Type doesn’t matter; objects only need to have the following magic methods: __sub__, __lt__ and __gt__.
matrix (np.array) – The initial matrix.
subtraction_index (Literal[1, 2]) – This parameter has been added for the adaption of the function in make_wilsons_brun_euclidean_algorithm_generator() and is not part of Bruns original algorithm. It describes whether in each step the first element gets subtracted by the second (original) or by the third (Wilson adaption) element.

Return type:

Generator

This algorithm has been described by V. Brun in his paper “EUCLIDEAN ALGORITHMS AND MUSICAL THEORY” (1964).

Example:

>>> import fractions
>>> from mutwo.generators import brun
>>> bruns_euclidean_algorithm_generator = brun.make_bruns_euclidean_algorithm_generator(
>>>     (
>>>         fractions.Fraction(2, 1),
>>>         fractions.Fraction(3, 2),
>>>         fractions.Fraction(5, 4),
>>>     )
>>> )
>>> next(bruns_euclidean_algorithm_generator)

reflected_binary_code(length, modulus)[source]§

Make gray code where each tuple has length items with modulus different numbers.

Parameters:

length (int) – how long one code is
modulus (int) – how many different numbers are included

Return type:

tuple[tuple[int, …], …]

Example:

>>> from mutwo.generators import gray
>>> gray.reflected_binary_code(2, 2)
((0, 0), (0, 1), (1, 1), (1, 0))
>>> gray.reflected_binary_code(3, 2)
((0, 0, 0),
(0, 0, 1),
(0, 1, 1),
(0, 1, 0),
(1, 1, 0),
(1, 1, 1),
(1, 0, 1),
(1, 0, 0))
>>> gray.reflected_binary_code(2, 3)
((0, 0), (0, 1), (0, 2), (1, 2), (1, 1), (1, 0), (2, 0), (2, 1), (2, 2))

Basic code has been copied from:: https://yetalengthothermodulusathblog.com/tag/gray-codes/

euclidean(size, distribution)[source]§

Return euclidean rhythm as described in a 2005 paper by G. T. Toussaint.

Parameters:

size (int) – how many beats the rhythm contains
distribution (int) – how many beats are played

Returns:

The rhythm in relative time.

Return type:

tuple[int, …]

Example:

>>> from mutwo.generators import toussaint
>>> toussaint.euclidean(8, 4)
(2, 2, 2, 2)
>>> toussaint.euclidean(7, 5)
(2, 1, 1, 2, 1)

The title of Toussaints paper is “The Euclidean Algorithm Generates Traditional Musical Rhythms”.

paradiddle(size)[source]§

Generates rhythm using the paradiddle method described by G. T. Toussaint.

Parameters:: size (int) – how many beats the resulting rhythm shall last. ‘Size’ has to be divisible by 2 because of the symmetrical structure of the generated rhythm.
Returns:: Return nested tuple that contains two tuple where each tuple represents one rhythm (both rhythms are complementary to each other). The rhythms are encoded in absolute time values.
Return type:: tuple[tuple[int, …], …]

Example:

>>> from mutwo.generators import toussaint
>>> toussaint.paradiddle(8)
((0, 2, 3, 5), (1, 4, 6, 7))
>>> toussaint.paradiddle(6)
((0, 4, 5), (1, 2, 3))

The paradiddle algorithm has been described by Godfried T. Toussaint in his paper ‘Generating “Good” Musical Rhythms Algorithmically’.

alternating_hands(seed_rhythm)[source]§

Generates rhythm using the alternating hands method described by G. T. Toussaint.

Parameters:: seed_rhythm (tuple[int, ...]) – rhythm that shall be distributed on two hands.
Returns:: Return nested tuple that contains two tuple where each tuple represents one rhythm (both rhythms are complementary to each other). The rhythms are encoded in absolute time values.
Return type:: tuple[tuple[int, …], …]

Example:

>>> from mutwo.generators import toussaint
>>> toussaint.alternating_hands((2, 2))
((0, 6), (2, 4))
>>> toussaint.alternating_hands((3, 2, 2))
((0, 5, 10), (3, 7, 12))

The alternating hands algorithm has been described by Godfried T. Toussaint in his paper ‘Generating “Good” Musical Rhythms Algorithmically’.

class NonTerminal[source]§: Can be used as a Mixin to define context-free grammar.

class Terminal[source]§: Can be used as a Mixin to define context-free grammar.

class ContextFreeGrammarRule(left_side, right_side)[source]§

Describe a context_free_grammar_rule for a ContextFreeGrammar

Public Methods:

`__init__`(left_side, right_side)
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Parameters:

left_side (NonTerminal) –
right_side (tuple[Union[mutwo.common_generators.chomksy.NonTerminal, mutwo.common_generators.chomksy.Terminal], ...]) –

left_side: NonTerminal§

right_side: tuple[Union[mutwo.common_generators.chomksy.NonTerminal, mutwo.common_generators.chomksy.Terminal], ...]§

class ContextFreeGrammar(context_free_grammar_rule_sequence)[source]§

Describe a context-free grammar and resolve non-terminals

Parameters:: context_free_grammar_rule_sequence (Sequence[ContextFreeGrammarRule]) – A sequence of ContextFreeGrammarRule objects. It is allowed to provide multiple context_free_grammar_rules with the same :attribute:`left_side`.

This is a very reduced implementation of a context-free grammar which only provides the most basic functions. It is not made for the purpose of parsing text but rather as a technique to generate algorithmic data (for the sake of art creation). Therefore it is all about the resolution of start objects to variants of this start.

Public Data Attributes:

`non_terminal_tuple`
`terminal_tuple`
`context_free_grammar_rule_tuple`	Get all defined rules

Public Methods:

`__init__`(context_free_grammar_rule_sequence)
`get_context_free_grammar_rule_tuple`(non_terminal)	Find all defined context_free_grammar_rules for the provided `NonTerminal`.
`resolve_one_layer`(tree)	Resolve all leaves of the tree.
`resolve`(start[, limit])	Resolve until only `Terminal` are left or the limit is reached.

get_context_free_grammar_rule_tuple(non_terminal)[source]§

Find all defined context_free_grammar_rules for the provided NonTerminal.

Parameters:: non_terminal (NonTerminal) – The left side element of the ContextFreeGrammarRule.
Return type:: tuple[mutwo.common_generators.chomksy.ContextFreeGrammarRule, …]

resolve(start, limit=None)[source]§

Resolve until only Terminal are left or the limit is reached.

Parameters:

start (NonTerminal) – The start value.
limit (Optional[int]) – The maximum node levels until the function returns a tree. If it is set to None it will only stop once all nodes are Terminal.

Return type:

Tree

resolve_one_layer(tree)[source]§

Resolve all leaves of the tree.

Parameters:: tree (treelib.Tree) – The tree from which all leaves should be resolved.
Returns:: True if any leaf has been resolved and False if no resolution has happened (e.g. if there are only Terminal left).
Return type:: bool

property context_free_grammar_rule_tuple: tuple[mutwo.common_generators.chomksy.ContextFreeGrammarRule, ...]§: Get all defined rules

property non_terminal_tuple: tuple[mutwo.common_generators.chomksy.NonTerminal, ...]§

property terminal_tuple: tuple[mutwo.common_generators.chomksy.Terminal, ...]§

class ActivityLevel(start_at=0)[source]§

Python implementation of Michael Edwards activity level algorithm.

Parameters:: start_at (int) – from which pattern per level shall be started (can be either 0, 1 or 2)

Activity Levels is a concept derived from Michael Edwards. Quoting Michael Edwards, Activity Levels are an “object for determining (deterministically) on a call-by-call basis whether a process is active or not (boolean). This is determined by nine 10-element lists (actually three versions of each) of hand-coded 1s and 0s, each list representing an ‘activity-level’ (how active the process should be). The first three 10-element lists have only one 1 in them, the rest being zeros. The second three have two 1s, etc. Activity-levels of 0 and 10 would return never active and always active respectively.”.

Example:

>>> from mutwo.generators import edwards
>>> activity_levels = edwards.ActivityLevel()
>>> activity_levels(0)  # activity level 0 will always return False
False
>>> activity_levels(10)  # activity level 10 will always return True
True
>>> activity_levels(7)  # activity level 7 will mostly return True
True
>>> tuple(activity_levels(7) for _ in range(10))
(True, False, True, True, False, True, True, False, True, True)

Public Methods:

`__init__`([start_at])
`__repr__`()	Return repr(self).
`__call__`(level)	Return current state (is active or not) of entered activity level.

Private Data Attributes:

_allowed_range_tuple

class Tendency(minima_curve, maxima_curve, random_seed=100)[source]§

Tendency offers an interface for dynamically changing minima / maxima areas.

Parameters:

minima_curve (core_events.Envelope) – The curve which describes the smallest allowed value over the time axis.
maxima_curve (core_events.Envelope) – The curve which describes the biggest allowed value over the time axis.
random_seed (int) – The random seed which shall be set.

The class is based on Gottfried Michael Koenigs algorithm of “Tendenz-Masken” in his program “Projekt 2” where those minima / maxima areas represent probability fields.

Example:

>>> import core_events
>>> from mutwo.generators import koenig
>>> minima_curve = core_events.Envelope.from_points((0, 0), (1, 1), (2, 0))
>>> maxima_curve = core_events.Envelope.from_points((0, 1), (1, 2), (2, 3))
>>> my_tendency = koenig.Tendency(minima_curve, maxima_curve)
>>> my_tendency.value_at(0.5)
0.6456692551041303
>>> my_tendency.value_at(0.5)
0.9549270045140213

Public Data Attributes:

`minima_curve`
`maxima_curve`

Public Methods:

`__init__`(minima_curve, maxima_curve[, ...])
`__repr__`()	Return repr(self).
`range_at`(time)	Get minima / maxima range at requested time.
`value_at`(time)	Get value at requested time.

range_at(time)[source]§

Get minima / maxima range at requested time.

Parameters:: time (float) –
Return type:: Range

value_at(time)[source]§

Get value at requested time.

Parameters:: time (float) –
Return type:: float

property maxima_curve: Envelope§

property minima_curve: Envelope§

class Backtracking[source]§

Abstract base class to implement a backtracking algorithm

By inheriting from this class, various backtracking algorithms can be implemented. In order to do so the user has to override a set of abstract methods. The abstract methods include:

:abstractmethod:`Backtracking.is_valid`

:abstractmethod:`Backtracking.solution_count`

:abstractmethod:`Backtracking.append_new_element`

:abstractmethod:`Backtracking.update_last_element`

:abstractmethod:`Backtracking.can_last_element_be_updated`

Furthermore it may be helpful to override the following method (even though there is a valid working implementation):

:method:`Backtracking.element_list_to_solution`

Please see the methods documentation for more details.

The implementation of this backtracking algorithm makes a distinction between an element list and a solution. A solution is created by an element list. A solution is the output a user wants to get, but an element list is an object which is used internally in order to solve the problem. When implementing a backtracking algorithm by using this interface the user doesn’t have to make the distinction between both (and in this case treat both in the same way).

The most common use case for this distinction is by having a set of items which can appear in the solution and a list of indices which item of set shall be used. In this case the element_list is actually a list of indices. This use case is implemented in the IndexBasedBacktracking class.

Bitner and Reingold [2] credit Derrick H. Lehmer with first using the term ‘backtrack’ in the 1950s..

Public Data Attributes:

solution_count

Return expected solution size

Public Methods:

`is_valid`(element_list)	Checks if an element list provides an acceptable solution.
`append_new_element`(element_list)	Append new element to element list.
`update_last_element`(element_list)	Increments value of the last element in an element_list.
`can_last_element_be_updated`(element_list)	Checks if the last element of the list can be incremented.
`element_list_to_solution`(element_list)	Converts an element list to the final solution
`solve`([return_element_list])	Apply backtracking algorithm.

Private Data Attributes:

_abc_impl

Inherited from ABC

_abc_impl

abstract append_new_element(element_list)[source]§

Append new element to element list.

Parameters:: element_list (list[Any]) – The element list to which a new element shall be appended.

abstract can_last_element_be_updated(element_list)[source]§

Checks if the last element of the list can be incremented.

Parameters:: element_list (list[Any]) – The element list which last value shall be checked.
Return type:: bool

element_list_to_solution(element_list)[source]§

Converts an element list to the final solution

Parameters:: element_list (list[Any]) – The element list to be converted.
Return type:: tuple[Any, …]

abstract is_valid(element_list)[source]§

Checks if an element list provides an acceptable solution.

Returns:: True if the solution is acceptable and False if the solution is rejected.
Parameters:: element_list (list[Any]) –
Return type:: bool

solve(return_element_list=False)[source]§

Apply backtracking algorithm.

Parameters:: return_element_list (bool) – If set to True the function will not only return the solution, but also the element list.
Return type:: Union[tuple[Any, …], tuple[tuple[Any, …], list[Any]]]

abstract update_last_element(element_list)[source]§

Increments value of the last element in an element_list.

Parameters:: element_list (list[Any]) – The element list which last value shall be updated.

This function should raise an Exception in case the last element can’t be updated.

abstract property solution_count: int§: Return expected solution size

class IndexBasedBacktracking[source]§

Abstract base class for index based backtracking algorithms

This class implements concrete solutions for the following methods which are inherited from the parent class Backtracking:

:abstractmethod:`Backtracking.append_new_element`

:abstractmethod:`Backtracking.update_last_element`

:abstractmethod:`Backtracking.can_last_element_be_updated`

The following methods still have to be implemented:

:abstractmethod:`Backtracking.is_valid`

:abstractmethod:`Backtracking.solution_count`

(Please consult for more information the documentation of Backtracking).

Furthermore the class adds new abstract methods to be implemented by child classes:

:abstractmethod:`IndexBasedBacktracking.element_index_to_item_sequence`

Example:

>>> import itertools
>>> from mutwo import common_generators
>>> class QueenProblem8(common_generators.IndexBasedBacktracking):
        point_list = list(itertools.combinations_with_replacement(range(queen_count), 2))
        point_list.extend(
            [tuple(reversed(point)) for point in point_list if len(set(point)) == 2]
        )
        def element_index_to_item_sequence(self, element_index, element_list):
            return self.point_list
        @property
        def solution_count(self):
            # 8 queens problem!
            return 8
        def is_valid(self, element_list):
            solution = self.element_list_to_solution(element_list)
            for queen0, queen1 in itertools.combinations(solution, 2):
                # x != x, y != y
                is_valid = all(value0 != value1 for value0, value1 in zip(queen0, queen1))
                difference_x, difference_y = (value0 - value1 for value0, value1 in zip(queen0, queen1))
                is_valid = is_valid and (difference_x != difference_y)
                if not is_valid: return False
            return True
>>> queen_problem_8 = QueenProblem8()
>>> queen_problem_8.solve()

Public Data Attributes:

Inherited from Backtracking

solution_count

Return expected solution size

Public Methods:

`element_index_to_item_sequence`(...)	Get a sequence of items to choose from for a specific element
`append_new_element`(element_list)	Append new element to element list.
`update_last_element`(element_list)	Increments value of the last element in an element_list.
`can_last_element_be_updated`(element_list)	Checks if the last element of the list can be incremented.
`element_list_to_solution`(element_list)	Converts an element list to the final solution

Inherited from Backtracking

`is_valid`(element_list)	Checks if an element list provides an acceptable solution.
`append_new_element`(element_list)	Append new element to element list.
`update_last_element`(element_list)	Increments value of the last element in an element_list.
`can_last_element_be_updated`(element_list)	Checks if the last element of the list can be incremented.
`element_list_to_solution`(element_list)	Converts an element list to the final solution
`solve`([return_element_list])	Apply backtracking algorithm.

Private Data Attributes:

_abc_impl

Inherited from Backtracking

_abc_impl

Inherited from ABC

_abc_impl

append_new_element(element_list)[source]§

Append new element to element list.

Parameters:: element_list (list[Any]) – The element list to which a new element shall be appended.

can_last_element_be_updated(element_list)[source]§

Checks if the last element of the list can be incremented.

Parameters:: element_list (list[Any]) – The element list which last value shall be checked.
Return type:: bool

abstract element_index_to_item_sequence(element_index, element_list)[source]§

Get a sequence of items to choose from for a specific element

Parameters:

element_index (int) – The index of the element for which a sequence of solutions shall be returned.
element_list (list[Any]) – The current element list

Return type:

Sequence[Any]

element_list_to_solution(element_list)[source]§

Converts an element list to the final solution

Parameters:: element_list (list[Any]) – The element list to be converted.
Return type:: tuple[Any, …]

abstract is_valid(element_list)§

Checks if an element list provides an acceptable solution.

Returns:: True if the solution is acceptable and False if the solution is rejected.
Parameters:: element_list (list[Any]) –
Return type:: bool

solve(return_element_list=False)§

Apply backtracking algorithm.

Parameters:: return_element_list (bool) – If set to True the function will not only return the solution, but also the element list.
Return type:: Union[tuple[Any, …], tuple[tuple[Any, …], list[Any]]]

update_last_element(element_list)[source]§

Increments value of the last element in an element_list.

Parameters:: element_list (list[Any]) – The element list which last value shall be updated.

This function should raise an Exception in case the last element can’t be updated.

abstract property solution_count: int§: Return expected solution size

mutwo.common_generators.constants §

Constants which are used in mutwo.common_generators.

ACTIVITY_LEVEL_TUPLE = (((0,), (0,), (0,)), ((1, 0, 0, 0, 0, 0, 0, 0, 0, 0), (0, 0, 0, 1, 0, 0, 0, 0, 0, 0), (0, 0, 0, 0, 0, 0, 1, 0, 0, 0)), ((1, 0, 0, 0, 0, 0, 1, 0, 0, 0), (0, 0, 0, 1, 0, 1, 0, 0, 0, 0), (0, 0, 0, 0, 0, 0, 1, 1, 0, 0)), ((1, 0, 0, 0, 1, 0, 1, 0, 0, 0), (0, 0, 0, 1, 0, 1, 1, 0, 0, 0), (0, 0, 1, 0, 0, 0, 1, 1, 0, 0)), ((1, 0, 0, 0, 1, 0, 1, 1, 0, 0), (0, 1, 0, 1, 0, 1, 1, 0, 0, 0), (0, 0, 1, 0, 0, 0, 1, 1, 0, 1)), ((1, 1, 0, 0, 1, 0, 1, 1, 0, 0), (0, 1, 0, 1, 0, 1, 1, 0, 0, 1), (0, 0, 1, 0, 1, 0, 1, 1, 0, 1)), ((1, 1, 0, 1, 1, 0, 1, 1, 0, 0), (0, 1, 0, 1, 0, 1, 1, 0, 1, 1), (0, 1, 1, 0, 1, 0, 1, 1, 0, 1)), ((1, 1, 0, 1, 1, 0, 1, 1, 0, 1), (1, 1, 0, 1, 0, 1, 1, 0, 1, 1), (1, 1, 1, 0, 1, 0, 1, 1, 0, 1)), ((1, 1, 0, 1, 1, 1, 1, 1, 0, 1), (1, 1, 1, 1, 0, 1, 1, 0, 1, 1), (1, 1, 1, 0, 1, 1, 1, 1, 0, 1)), ((1, 1, 0, 1, 1, 1, 1, 1, 1, 1), (1, 1, 1, 1, 0, 1, 1, 1, 1, 1), (1, 1, 1, 1, 1, 1, 1, 1, 0, 1)), ((1,), (1,), (1,)))§: Definition of activity level pattern. Pattern are copied from Michael Edwards Common Lisp composition software ‘slippery-chicken’.

mutwo.common_generators§

mutwo.common_generators.constants§

mutwo.common_generators §

mutwo.common_generators.constants §