qgrid

Classes

`QGrid`	Q-grid.
`QGridContainer`	Q-grid container.
`QGridLeaf`	Q-grid leaf.

class abjadext.nauert.qgrid.QGrid(root_node: QGridLeaf | QGridContainer | None = None, next_downbeat: QGridLeaf | None = None)[source]

Q-grid.

Rhythm-tree-based model for how millisecond attack points collapse onto the offsets generated by a nested rhythmic structure.

>>> q_grid = nauert.QGrid()

>>> q_grid
QGrid(root_node=QGridLeaf(preprolated_duration=Duration(1, 1), q_event_proxies=[], is_divisible=True), next_downbeat=QGridLeaf(preprolated_duration=Duration(1, 1), q_event_proxies=[], is_divisible=True))

QGrids model not only the internal nodes of the nesting structure, but also the downbeat to the “next” QGrid, allowing events which occur very late within one structure to collapse virtually onto the beginning of the next structure.

QEventProxies can be “loaded in” to the node contained by the QGrid closest to their virtual offset:

>>> q_event_a = nauert.PitchedQEvent(250, [0])
>>> q_event_b = nauert.PitchedQEvent(750, [1])
>>> proxy_a = nauert.QEventProxy(q_event_a, 0.25)
>>> proxy_b = nauert.QEventProxy(q_event_b, 0.75)

>>> q_grid.fit_q_events([proxy_a, proxy_b])

>>> for q_event_proxy in q_grid.root_node.q_event_proxies:
...     q_event_proxy
... 
QEventProxy(q_event=PitchedQEvent(offset=Offset((250, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=()), offset=Offset((1, 4)))

>>> for q_event_proxy in q_grid.next_downbeat.q_event_proxies:
...     q_event_proxy
... 
QEventProxy(q_event=PitchedQEvent(offset=Offset((750, 1)), pitches=(NamedPitch("cs'"),), index=None, attachments=()), offset=Offset((3, 4)))

Used internally by the quantize function.

Attributes Summary

`__call__`	Calls q-grid.
`__copy__`	Copies q-grid.
`__eq__`	True if argument is a q-grid with root node and next downbeat equal to those of this q-grid.
`__hash__`	Hashes q-grid.
`__repr__`	Gets repr.
`distance`	The computed total distance (divided by the number of `QEventProxy` s) of the offset of each `QEventProxy` contained by the `QGrid` to the offset of the `QGridLeaf` to which the `QEventProxy` is attached.
`fit_q_events`	Fit each `QEventProxy` in `q_event_proxies` onto the contained `QGridLeaf` whose offset is nearest.
`leaves`	All of the leaf nodes in the QGrid, including the next downbeat's node.
`next_downbeat`	The node representing the "next" downbeat after the contents of the QGrid's tree.
`offsets`	The offsets between 0 and 1 of all of the leaf nodes in the QGrid.
`pretty_rtm_format`	The pretty RTM-format of the root node of the `QGrid`.
`regroup_leaves_with_unencessary_divisions`	Regroup leaves that belong to the same parent in which only the first leaf contains q_event_prox[y\|ies].
`root_node`	The root node of the `QGrid`.
`rtm_format`	The RTM format of the root node of the `QGrid`.
`sort_q_events_by_index`	Sort `QEventProxies` attached to each `QGridLeaf` in a `QGrid` by their index.
`subdivide_leaf`	Replace the `QGridLeaf` `leaf` contained in a `QGrid` by a `QGridContainer` containing `QGridLeaves` with durations equal to the ratio described in `subdivisions`
`subdivide_leaves`	Given a sequence of leaf-index:subdivision-ratio pairs `pairs`, subdivide the `QGridLeaves` described by the indices into `QGridContainers` containing `QGridLeaves` with durations equal to their respective subdivision-ratios.

Special methods

overridden __call__(beatspan: Duration | tuple[int, int] | int) → list[Note | Tuplet] | list[Leaf | Tuplet][source]: Calls q-grid.

__copy__(*arguments: None) → QGrid[source]

Copies q-grid.

Returns new q-grid.

overridden __eq__(argument) → bool[source]

True if argument is a q-grid with root node and next downbeat equal to those of this q-grid. Otherwise false.

Returns true or false.

overridden __hash__() → int[source]

Hashes q-grid.

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

Returns integer.

overridden __repr__()[source]: Gets repr.

Methods

fit_q_events(q_event_proxies: Sequence[QEventProxy]) → None[source]

Fit each QEventProxy in q_event_proxies onto the contained QGridLeaf whose offset is nearest.

Returns None

regroup_leaves_with_unencessary_divisions() → None[source]: Regroup leaves that belong to the same parent in which only the first leaf contains q_event_prox[y|ies].

sort_q_events_by_index() → None[source]

Sort QEventProxies attached to each QGridLeaf in a QGrid by their index.

Returns None.

subdivide_leaf(leaf: QGridLeaf, subdivisions: Sequence[Duration | tuple[int, int] | int]) → list[QEventProxy][source]

Replace the QGridLeaf leaf contained in a QGrid by a QGridContainer containing QGridLeaves with durations equal to the ratio described in subdivisions

Returns the QEventProxies attached to leaf.

subdivide_leaves(pairs: Sequence[tuple[int, tuple[int, int]]]) → list[QEventProxy][source]

Given a sequence of leaf-index:subdivision-ratio pairs pairs, subdivide the QGridLeaves described by the indices into QGridContainers containing QGridLeaves with durations equal to their respective subdivision-ratios.

Returns the QEventProxies attached to thus subdivided QGridLeaf.

Read-only properties

distance

The computed total distance (divided by the number of QEventProxy s) of the offset of each QEventProxy contained by the QGrid to the offset of the QGridLeaf to which the QEventProxy is attached.

Return Duration instance.

>>> q_grid = nauert.QGrid()

>>> q_event_a = nauert.PitchedQEvent(250, [0], ["A"])
>>> q_event_b = nauert.PitchedQEvent(750, [1], ["B"])
>>> proxy_a = nauert.QEventProxy(q_event_a, 0.25)
>>> proxy_b = nauert.QEventProxy(q_event_b, 0.75)
>>> q_grid.fit_q_events([proxy_a, proxy_b])
>>> print(q_grid.rtm_format)
1

>>> for index, (leaf, offset) in enumerate(zip(q_grid.leaves, q_grid.offsets)):
...     for q_event_proxy in leaf.q_event_proxies:
...         q_event = q_event_proxy.q_event
...         print(
...             "leaf's index: {}, leaf's offset: {}, q_event: {}".format(
...                 index, offset, q_event.attachments
...             )
...         )
... 
leaf's index: 0, leaf's offset: 0, q_event: ('A',)
leaf's index: 1, leaf's offset: 1, q_event: ('B',)

>>> q_grid.distance
Duration(1, 4)

>>> q_events = q_grid.subdivide_leaves([(0, (1, 1))])
>>> q_grid.fit_q_events(q_events)
>>> q_events = q_grid.subdivide_leaves([(0, (1, 1))])
>>> q_grid.fit_q_events(q_events)
>>> print(q_grid.rtm_format)
(1 ((1 (1 1)) 1))

>>> for index, (leaf, offset) in enumerate(zip(q_grid.leaves, q_grid.offsets)):
...     for q_event_proxy in leaf.q_event_proxies:
...         q_event = q_event_proxy.q_event
...         print(
...             "leaf's index: {}, leaf's offset: {}, q_event: {}".format(
...                 index, offset, q_event.attachments
...             )
...         )
... 
leaf's index: 1, leaf's offset: 1/4, q_event: ('A',)
leaf's index: 2, leaf's offset: 1/2, q_event: ('B',)

>>> q_grid.distance
Duration(1, 8)

leaves

All of the leaf nodes in the QGrid, including the next downbeat’s node.

Returns tuple of QGridLeaf instances.

next_downbeat

The node representing the “next” downbeat after the contents of the QGrid’s tree.

Return QGridLeaf instance.

offsets

The offsets between 0 and 1 of all of the leaf nodes in the QGrid.

Returns tuple of Offset instances.

pretty_rtm_format

The pretty RTM-format of the root node of the QGrid.

Returns string.

root_node

The root node of the QGrid.

Return QGridLeaf or QGridContainer.

rtm_format

The RTM format of the root node of the QGrid.

Returns string.

class abjadext.nauert.qgrid.QGridContainer(children=None, preprolated_duration=Duration(1, 1), name=None)[source]

Q-grid container.

>>> nauert.QGridContainer()
QGridContainer((1, 1))

Used internally by QGrid.

Attributes Summary

leaves

Get leaves.

Special methods

(RhythmTreeContainer).__add__(argument) → RhythmTreeContainer

Concatenate containers self and argument. The operation c = a + b returns a new RhythmTreeContainer c with the content of both a and b, and a preprolated_duration equal to the sum of the durations of a and b. The operation is non-commutative: the content of the first operand will be placed before the content of the second operand.

>>> a = abjad.rhythmtrees.RhythmTreeParser()("(1 (1 1 1))")[0]
>>> b = abjad.rhythmtrees.RhythmTreeParser()("(2 (3 4))")[0]
>>> c = a + b
>>> c.preprolated_duration
Duration(3, 1)

>>> for _ in c:
...     _
... 
RhythmTreeLeaf(preprolated_duration=Duration(1, 1), is_pitched=True)
RhythmTreeLeaf(preprolated_duration=Duration(1, 1), is_pitched=True)
RhythmTreeLeaf(preprolated_duration=Duration(1, 1), is_pitched=True)
RhythmTreeLeaf(preprolated_duration=Duration(3, 1), is_pitched=True)
RhythmTreeLeaf(preprolated_duration=Duration(4, 1), is_pitched=True)

(RhythmTreeContainer).__call__(pulse_duration) → list[Leaf | Tuplet]

Makes list of leaves and /or tuplets equal to pulse_duration.

>>> string = "(1 (1 (2 (1 1 1)) 2))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]

>>> components = tree((1, 4))
>>> components
[Tuplet('5:4', "c'16 { 2/3 c'16 c'16 c'16 } c'8")]

>>> staff = abjad.Staff(components)
>>> abjad.show(staff)  

(UniqueTreeContainer).__contains__(expr)

(UniqueTreeList).__delitem__(i)

(UniqueTreeList).__getitem__(expr)

(RhythmTreeContainer).__graph__(**keywords) → Graph

Graphs rhythm-tree container.

>>> string = "(1 (1 (2 (1 1 1)) 2))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]
>>> graph = tree.__graph__()
>>> print(format(graph, "graphviz"))
digraph G {
    graph [bgcolor=transparent,
        truecolor=true];
    node_0 [label="1",
        shape=triangle];
    node_1 [label="1",
        shape=box];
    node_2 [label="2",
        shape=triangle];
    node_3 [label="1",
        shape=box];
    node_4 [label="1",
        shape=box];
    node_5 [label="1",
        shape=box];
    node_6 [label="2",
        shape=box];
    node_0 -> node_1;
    node_0 -> node_2;
    node_0 -> node_6;
    node_2 -> node_3;
    node_2 -> node_4;
    node_2 -> node_5;
}

>>> abjad.graph(graph)  

(UniqueTreeContainer).__iter__()

(UniqueTreeContainer).__len__()

(RhythmTreeContainer).__radd__(argument) → RhythmTreeContainer: Concatenates containers argument and self.

(RhythmTreeContainer).__repr__() → str: Gets interpreter representation of rhythm-tree container.

(UniqueTreeList).__setitem__(i, new_items)

Methods

(UniqueTreeList).append(expr)

(UniqueTreeContainer).depth_first(top_down=True, prototype=None)

(UniqueTreeList).extend(expr)

(UniqueTreeList).index(expr)

(UniqueTreeList).insert(i, expr)

(UniqueTreeList).pop(i=-1)

(UniqueTreeContainer).recurse(prototype=None)

(UniqueTreeList).remove(node)

Read/write properties

(UniqueTreeNode).name

(RhythmTreeMixin).preprolated_duration

Gets node duration in pulses.

>>> node = abjad.rhythmtrees.RhythmTreeLeaf(abjad.Duration(1))
>>> node.preprolated_duration
Duration(1, 1)

>>> node.preprolated_duration = abjad.Duration(2)
>>> node.preprolated_duration
Duration(2, 1)

>>> node = abjad.rhythmtrees.RhythmTreeLeaf((2, 4))
>>> node.preprolated_duration
(2, 4)

Read-only properties

(UniqueTreeContainer).children

(UniqueTreeNode).depth

(RhythmTreeMixin).duration

Gets node duration.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]

>>> tree.duration
Duration(1, 1)

>>> tree[1].duration
Duration(1, 2)

>>> tree[1][1].duration
Duration(1, 4)

(UniqueTreeNode).graph_order

Get graph-order tuple for node.

>>> from uqbar.containers import UniqueTreeList, UniqueTreeNode
>>> root_container = UniqueTreeList(name="root")
>>> outer_container = UniqueTreeList(name="outer")
>>> inner_container = UniqueTreeList(name="inner")
>>> node_a = UniqueTreeNode(name="a")
>>> node_b = UniqueTreeNode(name="b")
>>> node_c = UniqueTreeNode(name="c")
>>> node_d = UniqueTreeNode(name="d")
>>> root_container.extend([node_a, outer_container])
>>> outer_container.extend([inner_container, node_d])
>>> inner_container.extend([node_b, node_c])

>>> for node in root_container.depth_first():
...     print(node.name, node.graph_order)
... 
a (0,)
outer (1,)
inner (1, 0)
b (1, 0, 0)
c (1, 0, 1)
d (1, 1)

leaves: Get leaves.

(RhythmTreeMixin).pair: Gets preprolated duration as pair.

(UniqueTreeNode).parent

(UniqueTreeNode).parentage

(RhythmTreeMixin).parentage_ratios

A sequence describing the relative durations of the nodes in a node’s improper parentage.

The first item in the sequence is the preprolated_duration of the root node, and subsequent items are pairs of the preprolated duration of the next node in the parentage and the total preprolated_duration of that node and its siblings:

>>> a = abjad.rhythmtrees.RhythmTreeContainer(
...     preprolated_duration=abjad.Duration(1)
... )
>>> b = abjad.rhythmtrees.RhythmTreeContainer(
...     preprolated_duration=abjad.Duration(2)
... )
>>> c = abjad.rhythmtrees.RhythmTreeLeaf(preprolated_duration=abjad.Duration(3))
>>> d = abjad.rhythmtrees.RhythmTreeLeaf(preprolated_duration=abjad.Duration(4))
>>> e = abjad.rhythmtrees.RhythmTreeLeaf(preprolated_duration=abjad.Duration(5))

>>> a.extend([b, c])
>>> b.extend([d, e])

>>> a.parentage_ratios
(Duration(1, 1),)

>>> for item in b.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(2, 1), Duration(5, 1))

>>> for item in c.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(3, 1), Duration(5, 1))

>>> for item in d.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(2, 1), Duration(5, 1))
(Duration(4, 1), Duration(9, 1))

>>> for item in e.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(2, 1), Duration(5, 1))
(Duration(5, 1), Duration(9, 1))

Returns tuple.

(RhythmTreeMixin).pretty_rtm_format

Gets pretty-printed RTM format of node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]
>>> print(tree.pretty_rtm_format)
(1 (
    (1 (
        1
        1))
    (1 (
        1
        1))))

Returns string.

(RhythmTreeMixin).prolation: Gets node prolation.

(RhythmTreeMixin).prolations: Prolations of rhythm tree node.

(UniqueTreeNode).root

(RhythmTreeContainer).rtm_format

Gets rhythm-tree container RTM format.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]
>>> tree.rtm_format
'(1 ((1 (1 1)) (1 (1 1))))'

(RhythmTreeMixin).start_offset

Gets node start offset.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]

>>> tree.start_offset
Offset((0, 1))

>>> tree[1].start_offset
Offset((1, 2))

>>> tree[0][1].start_offset
Offset((1, 4))

(RhythmTreeMixin).stop_offset: Gets node stop offset.

class abjadext.nauert.qgrid.QGridLeaf(preprolated_duration: Duration | tuple[int, int] = Duration(1, 1), q_event_proxies: Sequence[QEventProxy] | None = None, is_divisible: bool = True)[source]

Q-grid leaf.

>>> nauert.QGridLeaf()
QGridLeaf(preprolated_duration=Duration(1, 1), q_event_proxies=[], is_divisible=True)

Used internally by QGrid.

Attributes Summary

`__call__`	Calls q-grid leaf.
`__graph__`	Graphviz graph of q-grid leaf.
`__repr__`	Gets repr.
`is_divisible`	Flag for whether the node may be further divided under some search tree.
`preceding_q_event_proxies`	Preceding q-event proxies of q-grid leaf.
`q_event_proxies`	Q-event proxies of q-grid leaf.
`rtm_format`	RTM format of q-grid leaf.
`succeeding_q_event_proxies`	Succeeding q-event proxies of q-grid leaf.

Special methods

overridden __call__(pulse_duration: Duration | tuple[int, int] | int) → list[Note | Tuplet][source]: Calls q-grid leaf.

__graph__(**keywords: None) → Graph[source]

Graphviz graph of q-grid leaf.

Returns Graphviz graph.

overridden __repr__()[source]: Gets repr.

Read/write properties

is_divisible: Flag for whether the node may be further divided under some search tree.

(UniqueTreeNode).name

(RhythmTreeMixin).preprolated_duration

Gets node duration in pulses.

>>> node = abjad.rhythmtrees.RhythmTreeLeaf(abjad.Duration(1))
>>> node.preprolated_duration
Duration(1, 1)

>>> node.preprolated_duration = abjad.Duration(2)
>>> node.preprolated_duration
Duration(2, 1)

>>> node = abjad.rhythmtrees.RhythmTreeLeaf((2, 4))
>>> node.preprolated_duration
(2, 4)

Read-only properties

(UniqueTreeNode).depth

(RhythmTreeMixin).duration

Gets node duration.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]

>>> tree.duration
Duration(1, 1)

>>> tree[1].duration
Duration(1, 2)

>>> tree[1][1].duration
Duration(1, 4)

(UniqueTreeNode).graph_order

Get graph-order tuple for node.

>>> from uqbar.containers import UniqueTreeList, UniqueTreeNode
>>> root_container = UniqueTreeList(name="root")
>>> outer_container = UniqueTreeList(name="outer")
>>> inner_container = UniqueTreeList(name="inner")
>>> node_a = UniqueTreeNode(name="a")
>>> node_b = UniqueTreeNode(name="b")
>>> node_c = UniqueTreeNode(name="c")
>>> node_d = UniqueTreeNode(name="d")
>>> root_container.extend([node_a, outer_container])
>>> outer_container.extend([inner_container, node_d])
>>> inner_container.extend([node_b, node_c])

>>> for node in root_container.depth_first():
...     print(node.name, node.graph_order)
... 
a (0,)
outer (1,)
inner (1, 0)
b (1, 0, 0)
c (1, 0, 1)
d (1, 1)

(RhythmTreeMixin).pair: Gets preprolated duration as pair.

(UniqueTreeNode).parent

(UniqueTreeNode).parentage

(RhythmTreeMixin).parentage_ratios

A sequence describing the relative durations of the nodes in a node’s improper parentage.

The first item in the sequence is the preprolated_duration of the root node, and subsequent items are pairs of the preprolated duration of the next node in the parentage and the total preprolated_duration of that node and its siblings:

>>> a = abjad.rhythmtrees.RhythmTreeContainer(
...     preprolated_duration=abjad.Duration(1)
... )
>>> b = abjad.rhythmtrees.RhythmTreeContainer(
...     preprolated_duration=abjad.Duration(2)
... )
>>> c = abjad.rhythmtrees.RhythmTreeLeaf(preprolated_duration=abjad.Duration(3))
>>> d = abjad.rhythmtrees.RhythmTreeLeaf(preprolated_duration=abjad.Duration(4))
>>> e = abjad.rhythmtrees.RhythmTreeLeaf(preprolated_duration=abjad.Duration(5))

>>> a.extend([b, c])
>>> b.extend([d, e])

>>> a.parentage_ratios
(Duration(1, 1),)

>>> for item in b.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(2, 1), Duration(5, 1))

>>> for item in c.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(3, 1), Duration(5, 1))

>>> for item in d.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(2, 1), Duration(5, 1))
(Duration(4, 1), Duration(9, 1))

>>> for item in e.parentage_ratios:
...     item
... 
Duration(1, 1)
(Duration(2, 1), Duration(5, 1))
(Duration(5, 1), Duration(9, 1))

Returns tuple.

preceding_q_event_proxies: Preceding q-event proxies of q-grid leaf.

(RhythmTreeMixin).pretty_rtm_format

Gets pretty-printed RTM format of node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]
>>> print(tree.pretty_rtm_format)
(1 (
    (1 (
        1
        1))
    (1 (
        1
        1))))

Returns string.

(RhythmTreeMixin).prolation: Gets node prolation.

(RhythmTreeMixin).prolations: Prolations of rhythm tree node.

q_event_proxies: Q-event proxies of q-grid leaf.

(UniqueTreeNode).root

rtm_format: RTM format of q-grid leaf.

(RhythmTreeMixin).start_offset

Gets node start offset.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> tree = abjad.rhythmtrees.RhythmTreeParser()(string)[0]

>>> tree.start_offset
Offset((0, 1))

>>> tree[1].start_offset
Offset((1, 2))

>>> tree[0][1].start_offset
Offset((1, 4))

(RhythmTreeMixin).stop_offset: Gets node stop offset.

succeeding_q_event_proxies: Succeeding q-event proxies of q-grid leaf.