searchtrees

Abstract Classes

SearchTree

Abstract search tree.

abstract class nauert.searchtrees.SearchTree(definition: dict | None = None)[source]

Abstract search tree.

SearchTrees encapsulate strategies for generating collections of QGrids, given a set of QEventProxy instances as input.

They allow composers to define the degree and quality of nested rhythmic subdivisions in the quantization output. That is to say, they allow composers to specify what sorts of tuplets and ratios of pulses may be contained within other tuplets, to arbitrary levels of nesting.

Attributes Summary

`__call__`	Calls search tree.
`__eq__`	Is true when argument is a search tree with definition equal to that of this search tree.
`__hash__`	Hashes search tree.
`__repr__`	Gets interpreter representation.
`default_definition`	Gets default search tree definition.
`definition`	Gets search tree definition.

Special methods

overridden __call__(q_grid: QGrid) → list[QGrid][source]: Calls search tree.

overridden __eq__(argument) → bool[source]: Is true when argument is a search tree with definition equal to that of this search tree. Otherwise false.

overridden __hash__() → int[source]

Hashes search tree.

Required to be explicitly redefined on Python 3 if __eq__ changes.

overridden __repr__() → str[source]: Gets interpreter representation.

Read-only properties

default_definition: Gets default search tree definition.

definition: Gets search tree definition.

Classes

`UnweightedSearchTree`	Unweighted search tree based on Paul Nauert's model.
`WeightedSearchTree`	Weighted search tree.

class nauert.searchtrees.UnweightedSearchTree(definition: dict | None = None)[source]

Unweighted search tree based on Paul Nauert’s model.

>>> import pprint
>>> search_tree = nauert.UnweightedSearchTree()
>>> pprint.pprint(search_tree.definition)
{2: {2: {2: {2: None}, 3: None}, 3: None, 5: None, 7: None},
 3: {2: {2: None}, 3: None, 5: None},
 5: {2: None, 3: None},
 7: {2: None},
 11: None,
 13: None}

The search tree defines how nodes in a QGrid may be subdivided, if they happen to contain QEvents (or, in actuality, QEventProxy instances which reference QEvents, but rescale their offsets between 0 and 1).

In the default definition, the root node of the QGrid may be subdivided into 2, 3, 5, 7, 11 or 13 equal parts. If divided into 2 parts, the divisions of the root node may be divided again into 2, 3, 5 or 7, and so forth.

This definition is structured as a collection of nested dictionaries, whose keys are integers, and whose values are either the sentinel None indicating no further permissable divisions, or dictionaries obeying these same rules, which then indicate the possibilities for further division.

Calling a UnweightedSearchTree with a QGrid instance will generate all permissable subdivided QGrids, according to the definition of the called search tree:

>>> q_event_a = nauert.PitchedQEvent(abjad.duration.offset(130), [0, 1, 4])
>>> q_event_b = nauert.PitchedQEvent(abjad.duration.offset(150), [2, 3, 5])
>>> proxy_a = nauert.QEventProxy(q_event_a, abjad.duration.offset(1, 2))
>>> proxy_b = nauert.QEventProxy(q_event_b, abjad.duration.offset(2, 3))
>>> q_grid = nauert.QGrid()
>>> q_grid.fit_q_events([proxy_a, proxy_b])
>>> q_grids = search_tree(q_grid)
>>> for grid in q_grids:
...     print(grid.rtm_format())
... 
(1 (1 1))
(1 (1 1 1))
(1 (1 1 1 1 1))
(1 (1 1 1 1 1 1 1))
(1 (1 1 1 1 1 1 1 1 1 1 1))
(1 (1 1 1 1 1 1 1 1 1 1 1 1 1))

A custom UnweightedSearchTree may be defined by passing in a dictionary, as described above. The following search tree only permits divisions of the root node into 2s and 3s, and if divided into 2, a node may be divided once more into 2 parts:

>>> definition = {2: {2: None}, 3: None}
>>> search_tree = nauert.UnweightedSearchTree(definition)

>>> q_grids = search_tree(q_grid)
>>> for grid in q_grids:
...     print(grid.rtm_format())
... 
(1 (1 1))
(1 (1 1 1))

Attributes Summary

default_definition

The default search tree definition, based on the search tree given by Paul Nauert:

Special methods

(SearchTree).__call__(q_grid: QGrid) → list[QGrid]: Calls search tree.

(SearchTree).__eq__(argument) → bool: Is true when argument is a search tree with definition equal to that of this search tree. Otherwise false.

(SearchTree).__hash__() → int

Hashes search tree.

Required to be explicitly redefined on Python 3 if __eq__ changes.

(SearchTree).__repr__() → str: Gets interpreter representation.

Read-only properties

overridden default_definition

The default search tree definition, based on the search tree given by Paul Nauert:

>>> import pprint
>>> search_tree = nauert.UnweightedSearchTree()
>>> pprint.pprint(search_tree.default_definition)
{2: {2: {2: {2: None}, 3: None}, 3: None, 5: None, 7: None},
 3: {2: {2: None}, 3: None, 5: None},
 5: {2: None, 3: None},
 7: {2: None},
 11: None,
 13: None}

(SearchTree).definition: Gets search tree definition.

class nauert.searchtrees.WeightedSearchTree(definition: dict | None = None)[source]

Weighted search tree.

Allows for dividing nodes in a q-grid into parts with unequal weights.

>>> search_tree = nauert.WeightedSearchTree()
>>> search_tree.definition
{'divisors': (2, 3, 5, 7), 'max_depth': 3, 'max_divisions': 2}

In WeightedSearchTree’s definition:

divisors controls the sum of the parts of the ratio a node
may be divided into,

max_depth controls how many levels of tuplet nesting
are permitted, and

max_divisions controls the maximum permitted length of the
weights in the ratio.

Thus, the default WeightedSearchTree permits the following ratios:

>>> for composition in search_tree.all_compositions:
...     composition
... 
(1, 1)
(2, 1)
(1, 2)
(4, 1)
(3, 2)
(2, 3)
(1, 4)
(6, 1)
(5, 2)
(4, 3)
(3, 4)
(2, 5)
(1, 6)

Attributes Summary

`all_compositions`	Gets all compositions of weighted search tree.
`default_definition`	Gets default definition of weighted search tree.

Special methods

(SearchTree).__call__(q_grid: QGrid) → list[QGrid]: Calls search tree.

(SearchTree).__eq__(argument) → bool: Is true when argument is a search tree with definition equal to that of this search tree. Otherwise false.

(SearchTree).__hash__() → int

Hashes search tree.

Required to be explicitly redefined on Python 3 if __eq__ changes.

(SearchTree).__repr__() → str: Gets interpreter representation.

Read-only properties

all_compositions: Gets all compositions of weighted search tree.

overridden default_definition: Gets default definition of weighted search tree.

(SearchTree).definition: Gets search tree definition.