QGrid

class quantizationtools.QGrid(root_node=None, next_downbeat=None)

Q-grid.

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

>>> import abjad
>>> from abjad.tools import quantizationtools
>>> q_grid = quantizationtools.QGrid()
>>> f(q_grid)
quantizationtools.QGrid(
    root_node=quantizationtools.QGridLeaf(
        preprolated_duration=abjad.Duration(1, 1),
        is_divisible=True,
        ),
    next_downbeat=quantizationtools.QGridLeaf(
        preprolated_duration=abjad.Duration(1, 1),
        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 = quantizationtools.PitchedQEvent(250, [0])
>>> q_event_b = quantizationtools.PitchedQEvent(750, [1])
>>> proxy_a = quantizationtools.QEventProxy(q_event_a, 0.25)
>>> proxy_b = quantizationtools.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:
...     f(q_event_proxy)
...
quantizationtools.QEventProxy(
    quantizationtools.PitchedQEvent(
        offset=abjad.Offset(250, 1),
        pitches=(
            abjad.NamedPitch("c'"),
            ),
        ),
    abjad.Offset(1, 4)
    )
>>> for q_event_proxy in q_grid.next_downbeat.q_event_proxies:
...     f(q_event_proxy)
...
quantizationtools.QEventProxy(
    quantizationtools.PitchedQEvent(
        offset=abjad.Offset(750, 1),
        pitches=(
            abjad.NamedPitch("cs'"),
            ),
        ),
    abjad.Offset(3, 4)
    )

Used internally by the Quantizer.

Lineage

digraph InheritanceGraph { graph [background=transparent, bgcolor=transparent, color=lightslategrey, fontname=Arial, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, root="__builtin__.object", splines=spline, style="dotted, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=12, penwidth=2, style="filled, rounded"]; edge [color=lightsteelblue2, penwidth=2]; subgraph cluster_abctools { graph [label=abctools]; "abjad.tools.abctools.AbjadObject.AbjadObject" [color=1, group=0, label=AbjadObject, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" [color=1, group=0, label=AbstractBase, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" -> "abjad.tools.abctools.AbjadObject.AbjadObject"; } subgraph cluster_quantizationtools { graph [label=quantizationtools]; "abjad.tools.quantizationtools.QGrid.QGrid" [color=black, fontcolor=white, group=2, label=<<B>QGrid</B>>, shape=box, style="filled, rounded"]; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=2, group=1, label=object, shape=box]; } "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.quantizationtools.QGrid.QGrid"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

distance The computed total distance 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(q_event_proxies) 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.
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(leaf, subdivisions) Replace the QGridLeaf leaf contained in a QGrid
subdivide_leaves(pairs) 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.
__call__(beatspan) Calls q-grid.
__copy__(*arguments) Copies q-grid.
__eq__(argument) True if argument is a q-grid with root node and next downbeat equal to those of this q-grid.
__format__([format_specification]) Formats q-event.
__hash__() Hashes q-grid.
__ne__(argument) Is true when Abjad object does not equal argument.
__repr__() Gets interpreter representation of Abjad object.

Read-only properties

QGrid.distance

The computed total distance 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.

QGrid.leaves

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

Returns tuple of QGridLeaf instances.

QGrid.next_downbeat

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

Return QGridLeaf instance.

QGrid.offsets

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

Returns tuple of Offset instances.

QGrid.pretty_rtm_format

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

Returns string.

QGrid.root_node

The root node of the QGrid.

Return QGridLeaf or QGridContainer.

QGrid.rtm_format

The RTM format of the root node of the QGrid.

Returns string.

Methods

QGrid.fit_q_events(q_event_proxies)

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

Returns None

QGrid.sort_q_events_by_index()

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

Returns None.

QGrid.subdivide_leaf(leaf, subdivisions)

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.

QGrid.subdivide_leaves(pairs)

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.

Special methods

QGrid.__call__(beatspan)

Calls q-grid.

QGrid.__copy__(*arguments)

Copies q-grid.

Returns new q-grid.

QGrid.__eq__(argument)

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.

QGrid.__format__(format_specification='')

Formats q-event.

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

QGrid.__hash__()

Hashes q-grid.

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

Returns integer.

(AbjadObject).__ne__(argument)

Is true when Abjad object does not equal argument. Otherwise false.

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.