+import abc
+
+import abjad
+
+
+
+[docs]
+class AttackPointOptimizer(abc.ABC):
+ """
+ Abstract attack-point optimizer.
+
+ Attack-point optimizers may alter the number, order, and individual
+ durations of leaves in a logical tie, but may not alter the overall
+ duration of that logical tie.
+
+ They effectively "clean up" notation, post-quantization.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ @abc.abstractmethod
+ def __call__(self, argument):
+ """
+ Calls attack-point optimizer.
+ """
+ raise NotImplementedError
+
+
+
+
+
+[docs]
+class MeasurewiseAttackPointOptimizer(AttackPointOptimizer):
+ r"""
+ Measurewise attack-point optimizer.
+
+ Attempts to optimize attack points in an expression with regard to the
+ effective time signature of that expression.
+
+ Only acts on measures.
+
+ .. container:: example
+
+ >>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 b'8 c''8")
+ >>> abjad.show(staff) # doctest: +SKIP
+
+ >>> source_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> q_events = nauert.QEventSequence.from_tempo_scaled_leaves(
+ ... staff[:],
+ ... tempo=source_tempo,
+ ... )
+ >>> target_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+ >>> q_schema = nauert.MeasurewiseQSchema(tempo=target_tempo)
+
+ .. container:: example
+
+ Without the measure-wise attack-point optimizer:
+
+ >>> voice = nauert.quantize(q_events, q_schema=q_schema)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=54
+ \time 4/4
+ c'16..
+ d'64
+ ~
+ \tuplet 5/4
+ {
+ d'8
+ e'32
+ ~
+ }
+ \tuplet 7/4
+ {
+ e'8
+ ~
+ e'32
+ f'16
+ ~
+ }
+ \tuplet 5/4
+ {
+ f'16.
+ g'16
+ ~
+ }
+ g'16
+ a'16
+ ~
+ \tuplet 5/4
+ {
+ a'16
+ b'16.
+ ~
+ }
+ \tuplet 7/4
+ {
+ b'16
+ c''8
+ ~
+ c''32
+ ~
+ }
+ \tuplet 5/4
+ {
+ c''32
+ r32
+ r32
+ r32
+ r32
+ }
+ }
+ }
+
+ .. container:: example
+
+ With the measure-wise attack-point optimizer:
+
+ >>> optimizer = nauert.MeasurewiseAttackPointOptimizer()
+ >>> voice = nauert.quantize(
+ ... q_events,
+ ... attack_point_optimizer=optimizer,
+ ... q_schema=q_schema,
+ ... )
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=54
+ \time 4/4
+ c'16..
+ d'64
+ ~
+ \tuplet 5/4
+ {
+ d'16.
+ ~
+ d'32
+ e'32
+ ~
+ }
+ \tuplet 7/4
+ {
+ e'16.
+ ~
+ e'16
+ f'16
+ ~
+ }
+ \tuplet 5/4
+ {
+ f'16.
+ g'16
+ ~
+ }
+ g'16
+ a'16
+ ~
+ \tuplet 5/4
+ {
+ a'16
+ b'32
+ ~
+ b'16
+ ~
+ }
+ \tuplet 7/4
+ {
+ b'16
+ c''32
+ ~
+ c''8
+ ~
+ }
+ \tuplet 5/4
+ {
+ c''32
+ r16
+ r16
+ }
+ }
+ }
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(
+ self,
+ argument: abjad.Container,
+ time_signature: abjad.TimeSignature | None = None,
+ ) -> None:
+ """
+ Calls measurewise attack-point optimizer.
+ """
+ assert isinstance(argument, abjad.Container)
+ if time_signature is None:
+ leaf = abjad.get.leaf(argument, 0)
+ time_signature = abjad.get.indicator(leaf, abjad.TimeSignature)
+ assert isinstance(time_signature, abjad.TimeSignature), repr(time_signature)
+ all_annotations = self._get_attachment_annotations_of_logical_ties(argument[:])
+ rtc = abjad.meter.make_best_guess_rtc(time_signature.pair)
+ meter = abjad.Meter(rtc)
+ meter.rewrite(argument[:], boundary_depth=1)
+ plts = list(abjad.iterate.logical_ties(argument[:], pitched=True))
+ assert len(all_annotations) == len(plts)
+ self._reannotate_logical_ties(argument[:], all_annotations)
+
+
+ @staticmethod
+ def _get_attachment_annotations_of_logical_ties(components):
+ all_annotations = []
+ for plt in abjad.iterate.logical_ties(components, pitched=True):
+ first_leaf = abjad.get.leaf(plt, 0)
+ annotation = abjad.get.annotation(first_leaf, "q_event_attachments")
+ all_annotations.append(annotation)
+ return all_annotations
+
+ @staticmethod
+ def _reannotate_logical_ties(components, all_annotations):
+ plts = abjad.iterate.logical_ties(components, pitched=True)
+ for plt, annotation in zip(plts, all_annotations, strict=True):
+ leaf = abjad.get.leaf(plt, 0)
+ abjad.annotate(leaf, "q_event_attachments", annotation)
+
+
+
+
+[docs]
+class NaiveAttackPointOptimizer(AttackPointOptimizer):
+ r"""
+ Naive attack-point optimizer. (The default attack-point optimizer)
+
+ Optimizes attack points by fusing tie leaves within logical ties with leaf
+ durations decreasing monotonically.
+
+ Logical ties will be partitioned into sub-logical-ties if leaves are found
+ with metronome marks attached.
+
+ .. container:: example
+
+ >>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 b'8 c''8")
+ >>> abjad.show(staff) # doctest: +SKIP
+
+ >>> source_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> q_events = nauert.QEventSequence.from_tempo_scaled_leaves(
+ ... staff[:],
+ ... tempo=source_tempo,
+ ... )
+ >>> target_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+ >>> q_schema = nauert.MeasurewiseQSchema(tempo=target_tempo)
+
+ .. container:: example
+
+ >>> optimizer = nauert.NaiveAttackPointOptimizer()
+ >>> voice = nauert.quantize(
+ ... q_events,
+ ... attack_point_optimizer=optimizer,
+ ... q_schema=q_schema,
+ ... )
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=54
+ \time 4/4
+ c'16..
+ d'64
+ ~
+ \tuplet 5/4
+ {
+ d'8
+ e'32
+ ~
+ }
+ \tuplet 7/4
+ {
+ e'8
+ ~
+ e'32
+ f'16
+ ~
+ }
+ \tuplet 5/4
+ {
+ f'16.
+ g'16
+ ~
+ }
+ g'16
+ a'16
+ ~
+ \tuplet 5/4
+ {
+ a'16
+ b'16.
+ ~
+ }
+ \tuplet 7/4
+ {
+ b'16
+ c''8
+ ~
+ c''32
+ ~
+ }
+ \tuplet 5/4
+ {
+ c''32
+ r32
+ r32
+ r32
+ r32
+ }
+ }
+ }
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(self, argument):
+ """
+ Calls naive attack-point optimizer.
+ """
+ lts = abjad.iterate.logical_ties(argument, grace=False, reverse=True)
+ for lt in lts:
+ sub_logical_ties = []
+ current_sub_logical_tie = []
+ for leaf in lt:
+ tempos = leaf._get_indicators(abjad.MetronomeMark)
+ if tempos:
+ if current_sub_logical_tie:
+ current_sub_logical_tie = abjad.LogicalTie(
+ current_sub_logical_tie
+ )
+ sub_logical_ties.append(current_sub_logical_tie)
+ current_sub_logical_tie = []
+ current_sub_logical_tie.append(leaf)
+ if current_sub_logical_tie:
+ current_sub_logical_tie = abjad.LogicalTie(current_sub_logical_tie)
+ sub_logical_ties.append(current_sub_logical_tie)
+ for sub_logical_tie in sub_logical_ties:
+ abjad.mutate._fuse_leaves_by_immediate_parent(sub_logical_tie)
+
+
+
+
+
+[docs]
+class NullAttackPointOptimizer(AttackPointOptimizer):
+ r"""
+ Null attack-point optimizer.
+
+ Performs no attack-point optimization.
+
+ .. container:: example
+
+ >>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 b'8 c''8")
+ >>> abjad.show(staff) # doctest: +SKIP
+
+ >>> source_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> q_events = nauert.QEventSequence.from_tempo_scaled_leaves(
+ ... staff[:],
+ ... tempo=source_tempo,
+ ... )
+ >>> target_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+ >>> q_schema = nauert.MeasurewiseQSchema(tempo=target_tempo)
+
+ .. container:: example
+
+ >>> optimizer = nauert.NullAttackPointOptimizer()
+ >>> voice = nauert.quantize(
+ ... q_events,
+ ... attack_point_optimizer=optimizer,
+ ... q_schema=q_schema,
+ ... )
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=54
+ \time 4/4
+ c'16
+ ~
+ c'32
+ ~
+ c'64
+ d'64
+ ~
+ \tuplet 5/4
+ {
+ d'32
+ ~
+ d'32
+ ~
+ d'32
+ ~
+ d'32
+ e'32
+ ~
+ }
+ \tuplet 7/4
+ {
+ e'32
+ ~
+ e'32
+ ~
+ e'32
+ ~
+ e'32
+ ~
+ e'32
+ f'32
+ ~
+ f'32
+ ~
+ }
+ \tuplet 5/4
+ {
+ f'32
+ ~
+ f'32
+ ~
+ f'32
+ g'32
+ ~
+ g'32
+ ~
+ }
+ g'16
+ a'16
+ ~
+ \tuplet 5/4
+ {
+ a'32
+ ~
+ a'32
+ b'32
+ ~
+ b'32
+ ~
+ b'32
+ ~
+ }
+ \tuplet 7/4
+ {
+ b'32
+ ~
+ b'32
+ c''32
+ ~
+ c''32
+ ~
+ c''32
+ ~
+ c''32
+ ~
+ c''32
+ ~
+ }
+ \tuplet 5/4
+ {
+ c''32
+ r32
+ r32
+ r32
+ r32
+ }
+ }
+ }
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### SPECIAL METHODS ###
+
+
+
+
+
+import abc
+import typing
+
+import abjad
+
+from . import qevents as _qevents
+
+
+
+[docs]
+class GraceHandler(abc.ABC):
+ """
+ Abstract grace-handler.
+
+ Determines what pitch, if any, will be selected from a list of ``QEvents``
+ to be applied to an attack-point generated by a ``QGrid``, and whether
+ there should be a ``BeforeGraceContainer`` attached to that attack-point.
+
+ When called on a sequence of ``QEvents``, ``GraceHandler`` subclasses
+ should return a pair, where the first item of the pair is a sequence of
+ pitch tokens or ``None``, and where the second item of the pair is a
+ ``BeforeGraceContainer`` instance or None.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### INITIALIZER ###
+
+ def __init__(self):
+ pass
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ @abc.abstractmethod
+ def __call__(self, q_events) -> tuple[
+ tuple[abjad.NamedPitch, ...],
+ typing.Optional[tuple],
+ typing.Optional[abjad.BeforeGraceContainer],
+ ]:
+ """
+ Calls grace handler.
+ """
+ raise NotImplementedError
+
+
+
+
+
+[docs]
+class CollapsingGraceHandler(GraceHandler):
+ r"""
+ Collapsing grace-handler.
+
+ Collapses pitch information into a single chord rather than creating a
+ grace container.
+
+ .. container:: example
+
+ >>> durations = [1000, 1, 1, 997]
+ >>> pitches = [0, 7, 4, 0]
+ >>> method = nauert.QEventSequence.from_millisecond_pitch_pairs
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> q_event_sequence = method(pairs)
+ >>> grace_handler = nauert.CollapsingGraceHandler()
+ >>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ <c' e' g'>4
+ r4
+ r4
+ }
+ }
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(
+ self, q_events: typing.Sequence[_qevents.QEvent]
+ ) -> tuple[tuple[abjad.NamedPitch, ...], tuple, None]:
+ """
+ Calls collapsing grace handler.
+ """
+ pitches: list[abjad.NamedPitch] = []
+ attachments: list[typing.Any] = []
+ for q_event in q_events:
+ if isinstance(q_event, _qevents.PitchedQEvent):
+ pitches.extend(q_event.pitches)
+ attachments.extend(q_event.attachments)
+ return tuple(pitches), tuple(attachments), None
+
+
+
+
+
+[docs]
+class ConcatenatingGraceHandler(GraceHandler):
+ r"""
+ Concatenating grace-handler.
+
+ Concatenates all but the final ``QEvent`` attached to a ``QGrid`` offset
+ into a ``BeforeGraceContainer``, using a fixed leaf duration ``duration``.
+
+ .. container:: example
+
+ When called, it returns pitch information of final ``QEvent``, and the
+ generated ``BeforeGraceContainer``, if any:
+
+ >>> durations = [1000, 1, 999]
+ >>> pitches = [0, 2, 0]
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+ >>> grace_handler = nauert.ConcatenatingGraceHandler()
+ >>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ \grace {
+ d'16
+ }
+ c'4
+ r4
+ r4
+ }
+ }
+
+ .. container:: example
+
+ When ``discard_grace_rest`` is set to ``True`` (the default), all the
+ grace rests are discarded:
+
+ >>> durations = [1000, 1, 999]
+ >>> pitches = [0, None, 0]
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+ >>> grace_handler = nauert.ConcatenatingGraceHandler()
+ >>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ c'4
+ r4
+ r4
+ }
+ }
+
+ .. container:: example
+
+ When ``discard_grace_rest`` is set to ``False``, grace rests are not
+ discarded:
+
+ >>> grace_handler = nauert.ConcatenatingGraceHandler(discard_grace_rest=False)
+ >>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ \grace {
+ r16
+ }
+ c'4
+ r4
+ r4
+ }
+ }
+
+ .. container:: example
+
+ When ``replace_rest_with_final_grace_note`` is set to ``False``, grace
+ notes are allowed to be attached to a rest:
+
+ >>> durations = [1000, 1, 999, 1000]
+ >>> pitches = [0, 0, None, 0]
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+ >>> grace_handler = nauert.ConcatenatingGraceHandler(
+ ... replace_rest_with_final_grace_note=False
+ ... )
+ >>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ \grace {
+ c'16
+ }
+ r4
+ c'4
+ r4
+ }
+ }
+
+ .. container:: example
+
+ When ``replace_rest_with_final_grace_note`` is set to ``True`` (the
+ default behavior), any rest with grace notes attached to it is replaced
+ by the last pitched grace note in the grace container:
+
+ >>> grace_handler = nauert.ConcatenatingGraceHandler()
+ >>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ c'4
+ c'4
+ r4
+ }
+ }
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = (
+ "_discard_grace_rest",
+ "_grace_duration",
+ "_replace_rest_with_final_grace_note",
+ )
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ discard_grace_rest: bool = True,
+ grace_duration: abjad.Duration = abjad.Duration(1, 16),
+ replace_rest_with_final_grace_note: bool = True,
+ ) -> None:
+ assert isinstance(discard_grace_rest, bool), repr(discard_grace_rest)
+ assert isinstance(grace_duration, abjad.Duration), repr(grace_duration)
+ assert isinstance(replace_rest_with_final_grace_note, bool)
+ self._discard_grace_rest = discard_grace_rest
+ assert grace_duration.is_dyadic_rational
+ self._grace_duration = grace_duration
+ self._replace_rest_with_final_grace_note = replace_rest_with_final_grace_note
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(self, q_events: typing.Sequence[_qevents.QEvent]) -> tuple[
+ tuple[abjad.NamedPitch, ...],
+ typing.Optional[tuple],
+ typing.Optional[abjad.BeforeGraceContainer],
+ ]:
+ """
+ Calls concatenating grace handler.
+ """
+ grace_events, final_event = q_events[:-1], q_events[-1]
+ attachments: tuple | None
+ if grace_events and self._replace_rest_with_final_grace_note:
+ index = self._find_last_pitched_q_event(q_events)
+ grace_events, final_event = q_events[:index], q_events[index]
+ if isinstance(final_event, _qevents.PitchedQEvent):
+ # TODO: we are only supporting preserving attachments for PitchedQEvent
+ pitches = final_event.pitches
+ attachments = final_event.attachments
+ else:
+ pitches = ()
+ attachments = None
+ grace_events_list = list(grace_events)
+ if self._discard_grace_rest:
+ for q_event in grace_events_list:
+ if isinstance(q_event, _qevents.SilentQEvent):
+ grace_events_list.remove(q_event)
+ grace_events = tuple(grace_events_list)
+ grace_container: abjad.BeforeGraceContainer | None
+ if grace_events:
+ grace_container = abjad.BeforeGraceContainer()
+ for q_event in grace_events:
+ leaf: abjad.Leaf
+ if isinstance(q_event, _qevents.PitchedQEvent):
+ if len(q_event.pitches) == 1:
+ leaf = abjad.Note(q_event.pitches[0], self.grace_duration)
+ else:
+ leaf = abjad.Chord(q_event.pitches, self.grace_duration)
+ else:
+ leaf = abjad.Rest(self.grace_duration)
+ q_event_attachments = (
+ None if not hasattr(q_event, "attachments") else q_event.attachments
+ )
+ if q_event_attachments is not None:
+ abjad.annotate(leaf, "q_event_attachments", q_event_attachments)
+ grace_container.append(leaf)
+ else:
+ grace_container = None
+
+ return tuple(pitches), attachments, grace_container
+
+
+ ### PRIVATE METHODS ###
+
+ @staticmethod
+ def _find_last_pitched_q_event(q_events: typing.Sequence[_qevents.QEvent]) -> int:
+ for index, q_event in enumerate(reversed(q_events)):
+ if isinstance(q_event, _qevents.PitchedQEvent):
+ return len(q_events) - index - 1
+ raise ValueError("There should be at least one PitchedQEvent in q_events")
+
+ ### PUBLIC METHODS ###
+
+
+[docs]
+ def handle_orphaned_q_event_proxies(self, last_leaf, q_event_proxies):
+ r"""
+ Embeds orphaned ``QEvents`` into an ``AfterGraceContainer`` and
+ attaches it to ``last_leaf``.
+
+ .. container:: example
+
+ >>> durations = [1000, 1000, 1000, 400, 50, 50]
+ >>> pitches = range(len(durations))
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> method = nauert.QEventSequence.from_millisecond_pitch_pairs
+ >>> q_event_sequence = method(pairs)
+ >>> search_tree = nauert.UnweightedSearchTree()
+ >>> attack_point_optimizer = nauert.MeasurewiseAttackPointOptimizer()
+ >>> q_schema = nauert.MeasurewiseQSchema(
+ ... search_tree=search_tree,
+ ... time_signature=(7, 8),
+ ... use_full_measure=True,
+ ... )
+ >>> result = nauert.quantize(
+ ... q_event_sequence,
+ ... q_schema=q_schema,
+ ... attach_tempos=True,
+ ... attack_point_optimizer=attack_point_optimizer,
+ ... )
+ >>> staff = abjad.Staff([result])
+ >>> score = abjad.Score([staff], name="Score")
+ >>> abjad.show(staff) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(staff)
+ >>> print(string)
+ \new Staff
+ {
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 7/8
+ c'4
+ cs'8
+ ~
+ cs'8
+ d'8
+ ~
+ d'8
+ \afterGrace
+ ef'8
+ {
+ e'16
+ f'16
+ }
+ }
+ }
+ }
+
+ """
+ grace_container = abjad.AfterGraceContainer() if q_event_proxies else None
+ for proxy in q_event_proxies:
+ q_event = proxy.q_event
+ if isinstance(q_event, _qevents.PitchedQEvent):
+ if len(q_event.pitches) == 1:
+ leaf = abjad.Note(q_event.pitches[0], self.grace_duration)
+ else:
+ leaf = abjad.Chord(q_event.pitches, self.grace_duration)
+ abjad.annotate(leaf, "q_event_attachments", q_event.attachments)
+ assert grace_container is not None
+ grace_container.append(leaf)
+ if 0 < len(grace_container):
+ abjad.attach(grace_container, last_leaf)
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def discard_grace_rest(self) -> bool:
+ """
+ Boolean of whether to discard grace rests or not.
+ """
+ return self._discard_grace_rest
+
+ @property
+ def grace_duration(self) -> abjad.Duration:
+ """
+ Grace duration of concantenating grace handler.
+ """
+ return self._grace_duration
+
+ @property
+ def replace_rest_with_final_grace_note(self) -> bool:
+ """
+ Boolean of whether to replace the rest with the final (pitched) grace
+ note.
+ """
+ return self._replace_rest_with_final_grace_note
+
+
+
+
+[docs]
+class DiscardingGraceHandler(GraceHandler):
+ r"""
+ Discarding grace-handler.
+
+ Discards all but final q-event attached to an offset.
+
+ Does not create grace containers.
+
+ .. container:: example
+
+ >>> durations = [1000, 1, 1, 998]
+ >>> pitches = [0, 1, 2, 3]
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+ >>> grace_handler = nauert.DiscardingGraceHandler()
+ >>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ ef'4
+ r4
+ r4
+ }
+ }
+
+ >>> for pqe in grace_handler.discarded_q_events[0]:
+ ... pqe
+ PitchedQEvent(offset=Offset((1000, 1)), pitches=(NamedPitch("cs'"),), ...)
+ PitchedQEvent(offset=Offset((1001, 1)), pitches=(NamedPitch("d'"),), ...)
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_discarded_q_events",)
+
+ ### INITIALIZER ###
+
+ def __init__(self) -> None:
+ self._discarded_q_events: list[typing.Sequence[_qevents.QEvent]] = []
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(
+ self, q_events: typing.Sequence[_qevents.QEvent]
+ ) -> tuple[tuple[abjad.NamedPitch, ...], tuple, None]:
+ """
+ Calls discarding grace handler.
+ """
+ if q_events[:-1]:
+ self._discarded_q_events.append(q_events[:-1])
+ q_event = q_events[-1]
+ if isinstance(q_event, _qevents.PitchedQEvent):
+ return tuple(q_event.pitches), tuple(q_event.attachments), None
+ return (), (), None
+
+
+ @property
+ def discarded_q_events(self) -> list[typing.Sequence[_qevents.QEvent]]:
+ """
+ Gets discarded QEvents.
+ """
+ return self._discarded_q_events
+
+
+import abc
+
+from . import qgrid as _qgrid
+from . import qtargetitems as _qtargetitems
+
+
+
+[docs]
+class Heuristic(abc.ABC):
+ """
+ Abstract heuristic.
+
+ Heuristics rank Q-grids according to the criteria they encapsulate.
+
+ Heuristics provide the means by which the quantizer selects a single
+ ``QGrid`` from all computed ``QGrids`` for any given ``QTargetBeat`` to
+ represent that beat.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### INITIALIZER ###
+
+ def __init__(self):
+ pass
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(
+ self, q_target_beats: tuple[_qtargetitems.QTargetBeat, ...]
+ ) -> tuple[_qtargetitems.QTargetBeat, ...]:
+ """
+ Calls heuristic.
+ """
+ assert len(q_target_beats)
+ assert all(isinstance(x, _qtargetitems.QTargetBeat) for x in q_target_beats)
+ return self._process(q_target_beats)
+
+
+ ### PRIVATE METHODS ###
+
+ @abc.abstractmethod
+ def _process(
+ self, q_target_beats: tuple[_qtargetitems.QTargetBeat, ...]
+ ) -> tuple[_qtargetitems.QTargetBeat, ...]:
+ raise NotImplementedError
+
+
+
+
+[docs]
+class DistanceHeuristic(Heuristic):
+ r"""
+ Distance heuristic.
+
+ Considers only the computed distance of each ``QGrid`` and the number of
+ leaves of that ``QGrid`` when choosing the optimal ``QGrid`` for a given
+ ``QTargetBeat``.
+
+ The ``QGrid`` with the smallest distance and fewest number of leaves will
+ be selected.
+
+ .. container:: example
+
+ >>> durations = [1000] * 8
+ >>> pitches = range(8)
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+ >>> heuristic = nauert.DistanceHeuristic()
+ >>> voice = nauert.quantize(q_event_sequence, heuristic=heuristic)
+ >>> staff = abjad.Staff([voice])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(voice)
+ >>> print(string)
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ cs'4
+ d'4
+ ef'4
+ }
+ {
+ e'4
+ f'4
+ fs'4
+ g'4
+ }
+ }
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### PRIVATE METHODS ###
+
+ def _process(
+ self, q_target_beats: tuple[_qtargetitems.QTargetBeat, ...]
+ ) -> tuple[_qtargetitems.QTargetBeat, ...]:
+ for q_target_beat in q_target_beats:
+ q_grids = q_target_beat.q_grids
+ if q_grids:
+ sorted_q_grids = sorted(
+ q_grids, key=lambda x: (x.distance, len(x.leaves))
+ )
+ q_target_beat._q_grid = sorted_q_grids[0]
+ else:
+ q_target_beat._q_grid = _qgrid.QGrid()
+ return q_target_beats
+
+
+import abc
+import multiprocessing
+import pickle
+import typing
+
+from . import quantizationjob as _quantizationjob
+
+
+
+[docs]
+class JobHandler(abc.ABC):
+ """
+ Abstact job-handler.
+
+ ``JobHandlers`` control how ``QuantizationJob`` instances are processed by
+ the ``quantize`` function, either serially or in parallel.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### INITIALIZER ###
+
+ def __init__(self):
+ pass
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ @abc.abstractmethod
+ def __call__(self, jobs):
+ """
+ Calls job handler.
+ """
+ raise NotImplementedError
+
+
+
+
+
+[docs]
+class ParallelJobHandlerWorker(multiprocessing.Process):
+ """
+ Parallel job-handler worker.
+
+ Worker process which runs ``QuantizationJobs``.
+
+ Not composer-safe.
+
+ Used internally by ``ParallelJobHandler``.
+ """
+
+ ### INITIALIZER ###
+
+ def __init__(self, job_queue=None, result_queue=None) -> None:
+ multiprocessing.Process.__init__(self)
+ job_queue = job_queue or ()
+ result_queue = result_queue or ()
+ self.job_queue = job_queue
+ self.result_queue = result_queue
+
+ ### PUBLIC METHODS ###
+
+
+[docs]
+ def run(self) -> None:
+ """
+ Runs parallel job handler worker.
+ """
+ while True:
+ job = None
+ if hasattr(self.job_queue, "get"):
+ job = self.job_queue.get()
+ if job is None:
+ # poison pill causes worker shutdown
+ # print '{}: Exiting'.format(process_name)
+ assert hasattr(self.job_queue, "task_done")
+ self.job_queue.task_done()
+ break
+ # print '{}: {!r}'.format(process_name, job)
+ job = pickle.loads(job)
+ job()
+ self.job_queue.task_done()
+ assert hasattr(self.result_queue, "put")
+ self.result_queue.put(pickle.dumps(job, protocol=0))
+ return
+
+
+
+
+
+[docs]
+class ParallelJobHandler(JobHandler):
+ """
+ Parallel job-handler.
+
+ Processes ``QuantizationJob`` instances in parallel, based on the number of
+ CPUs available.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(self, jobs):
+ """
+ Calls parallel job handler.
+ """
+ finished_jobs = []
+ job_queue = multiprocessing.JoinableQueue()
+ result_queue = multiprocessing.Queue()
+ workers = [
+ ParallelJobHandlerWorker(job_queue, result_queue)
+ for i in range(multiprocessing.cpu_count() * 2)
+ ]
+ for worker in workers:
+ worker.start()
+ for job in jobs:
+ job_queue.put(pickle.dumps(job, protocol=0))
+ for i in range(len(jobs)):
+ finished_jobs.append(pickle.loads(result_queue.get()))
+ for worker in workers:
+ job_queue.put(None)
+ job_queue.join()
+ result_queue.close()
+ job_queue.close()
+ for worker in workers:
+ worker.join()
+ return finished_jobs
+
+
+
+
+
+[docs]
+class SerialJobHandler(JobHandler):
+ """
+ Serial job-handler.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(
+ self, jobs: typing.Sequence[_quantizationjob.QuantizationJob]
+ ) -> typing.Sequence[_quantizationjob.QuantizationJob]:
+ """
+ Calls serial job handler.
+ """
+ for job in jobs:
+ job()
+ return jobs
+
+
+
+import typing
+
+import abjad
+
+from . import qevents as _qevents
+
+
+
+[docs]
+class QEventProxy:
+ """
+ Q-event proxy.
+
+ Maps Q-event offset with the range of its beatspan to the range 0-1.
+
+ .. container:: example
+
+ >>> q_event = nauert.PitchedQEvent(abjad.Offset(130), [0, 1, 4])
+ >>> nauert.QEventProxy(q_event, abjad.Offset(0.5))
+ QEventProxy(q_event=PitchedQEvent(offset=Offset((130, 1)), pitches=...)
+
+ Not composer-safe.
+
+ Used internally by the ``quantize`` function.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_offset", "_q_event")
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ q_event: _qevents.QEvent | None = None,
+ *offsets: abjad.Offset,
+ ) -> None:
+ assert all(isinstance(_, abjad.Offset) for _ in offsets), repr(offsets)
+ if len(offsets) == 1:
+ offset = abjad.Offset(offsets[0])
+ assert isinstance(q_event, _qevents.QEvent)
+ assert 0 <= offset <= 1
+ elif len(offsets) == 2:
+ minimum, maximum = (
+ abjad.Offset(offsets[0]),
+ abjad.Offset(offsets[1]),
+ )
+ assert isinstance(q_event, _qevents.QEvent)
+ assert minimum <= q_event.offset <= maximum
+ offset = (q_event.offset - minimum) / (maximum - minimum)
+ elif len(offsets) == 0:
+ assert q_event is None
+ offset = abjad.Offset(0)
+ else:
+ message = f"can not initialize {type(self).__name__}: {offsets!r}."
+ raise ValueError(message)
+ self._q_event = q_event
+ self._offset = abjad.Offset(offset)
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true when `argument` is a q-event proxy with offset and q-event
+ equal to those of this q-event proxy. Otherwise false.
+ """
+ if type(self) is type(argument):
+ if self.offset == argument.offset:
+ if self.q_event == argument.q_event:
+ return True
+ return False
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes q-event proxy.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(QEventProxy, self).__hash__()
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ class_name = type(self).__name__
+ string = f"{class_name}(q_event={self.q_event!r}, offset={self.offset!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def index(self) -> typing.Optional[int]:
+ """
+ Gets index of q-event proxy.
+ """
+ assert self._q_event is not None, "There is no QEvent is this proxy."
+ return self._q_event.index
+
+ @property
+ def offset(self) -> abjad.Offset:
+ """
+ Gets offset of q-event proxy.
+ """
+ return self._offset
+
+ @property
+ def q_event(self) -> typing.Optional[_qevents.QEvent]:
+ """
+ Gets q-event of q-event proxy.
+ """
+ return self._q_event
+
+
+import abc
+import collections
+import numbers
+import typing
+
+import abjad
+
+
+
+[docs]
+class QEvent(abc.ABC):
+ """
+ Abstract Q-event.
+
+ Represents an attack point to be quantized.
+
+ All ``QEvents`` possess a rational offset in milliseconds, and an optional
+ index for disambiguating events which fall on the same offset in a
+ ``QGrid``.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_attachments", "_index", "_offset")
+
+ ### INITIALIZER ###
+
+ @abc.abstractmethod
+ def __init__(
+ self,
+ offset: abjad.Offset = abjad.Offset(0),
+ index: int | None = None,
+ attachments: typing.Iterable = (),
+ ) -> None:
+ assert isinstance(offset, abjad.Offset), repr(offset)
+ assert isinstance(attachments, collections.abc.Iterable), repr(attachments)
+ self._offset = offset
+ self._index = index
+ self._attachments = tuple(attachments)
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __lt__(self, argument) -> bool:
+ """
+ Is true when `epxr` is a q-event with offset greater than that of this
+ q-event. Otherwise false.
+ """
+ if type(self) is type(self):
+ if self.offset < argument.offset:
+ return True
+ return False
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ class_name = type(self).__name__
+ string = f"{class_name}(offset={self.offset!r}, index={self.index!r}"
+ string += f", attachments={self.attachments!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def attachments(self) -> tuple:
+ """
+ The attachments of the QEvent.
+ """
+ return self._attachments
+
+ @property
+ def index(self) -> typing.Optional[int]:
+ """
+ The optional index, for sorting QEvents with identical offsets.
+ """
+ return self._index
+
+ @property
+ def offset(self) -> abjad.Offset:
+ """
+ The offset in milliseconds of the event.
+ """
+ return self._offset
+
+
+[docs]
+ @classmethod
+ def from_offset_pitches_attachments(
+ class_, offset, pitches, attachments
+ ) -> "QEvent":
+ assert isinstance(attachments, collections.abc.Iterable), repr(attachments)
+ match pitches:
+ case collections.abc.Iterable():
+ assert all(isinstance(_, numbers.Number) for _ in pitches)
+ return PitchedQEvent(offset, pitches, attachments)
+ case None:
+ return SilentQEvent(offset, attachments)
+ case int() | float():
+ return PitchedQEvent(offset, [pitches], attachments)
+ case _:
+ raise TypeError(type(pitches))
+
+
+
+
+
+[docs]
+class PitchedQEvent(QEvent):
+ """
+ Pitched q-event.
+
+ Indicates the onset of a period of pitched material in a q-event sequence.
+
+ .. container:: example
+
+ >>> pitches = [0, 1, 4]
+ >>> nauert.PitchedQEvent(abjad.Offset(1000), pitches)
+ PitchedQEvent(offset=Offset((1000, 1)), pitches=...)
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_attachments", "_index", "_offset", "_pitches")
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ offset: abjad.Offset = abjad.Offset(0),
+ pitches: typing.Iterable[int | float] = (),
+ attachments: typing.Iterable = (),
+ index: int | None = None,
+ ):
+ assert isinstance(offset, abjad.Offset), repr(offset)
+ QEvent.__init__(self, offset=offset, index=index)
+ self._pitches = tuple([abjad.NamedPitch(x) for x in pitches])
+ self._attachments = tuple(attachments)
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true when `argument` is a pitched q-event with offset, pitches,
+ attachments and index equal to those of this pitched q-event. Otherwise
+ false.
+ """
+ if (
+ type(self) is type(argument)
+ and self.offset == argument.offset
+ and self.pitches == argument.pitches
+ and self.attachments == argument.attachments
+ and self.index == argument.index
+ ):
+ return True
+ return False
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes pitched q-event.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(PitchedQEvent, self).__hash__()
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(offset={self.offset!r},"
+ string += f" pitches={self.pitches!r}, index={self.index!r},"
+ string += f" attachments={self.attachments!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def attachments(self) -> tuple:
+ """
+ Gets attachments of pitched q-event.
+ """
+ return self._attachments
+
+ @property
+ def pitches(self) -> tuple[abjad.NamedPitch, ...]:
+ """
+ Gets pitches of pitched q-event.
+ """
+ return self._pitches
+
+
+
+
+[docs]
+class SilentQEvent(QEvent):
+ """
+ Silent q-event.
+
+ .. container:: example
+
+ >>> q_event = nauert.SilentQEvent(abjad.Offset(1000))
+ >>> q_event
+ SilentQEvent(offset=Offset((1000, 1)), index=None, attachments=())
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_attachments",)
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ offset: abjad.Offset = abjad.Offset(0),
+ attachments: typing.Iterable = (),
+ index: int | None = None,
+ ):
+ assert isinstance(offset, abjad.Offset), repr(offset)
+ QEvent.__init__(self, offset=offset, index=index)
+ if attachments is None:
+ attachments = ()
+ else:
+ attachments = tuple(attachments)
+ self._attachments = attachments
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true when `argument` is a silent q-event with offset, attachments
+ and index equal to those of this silent q-event. Otherwise false.
+ """
+ if (
+ type(self) is type(argument)
+ and self._offset == argument._offset
+ and self._attachments == argument._attachments
+ and self._index == argument._index
+ ):
+ return True
+ return False
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes silent q-event.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(SilentQEvent, self).__hash__()
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def attachments(self) -> tuple:
+ """
+ Gets attachments of silent q-event.
+ """
+ return self._attachments
+
+
+
+
+[docs]
+class TerminalQEvent(QEvent):
+ """
+ Terminal q-event.
+
+ .. container:: example
+
+ >>> nauert.TerminalQEvent(abjad.Offset(1000))
+ TerminalQEvent(offset=Offset((1000, 1)), index=None, attachments=())
+
+ Carries no significance outside the context of a ``QEventSequence``.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_offset",)
+
+ ### INITIALIZER ###
+
+ def __init__(self, offset: abjad.Offset = abjad.Offset(0)) -> None:
+ assert isinstance(offset, abjad.Offset), repr(offset)
+ QEvent.__init__(self, offset=offset)
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true when `argument` is a terminal q-event with offset equal to that
+ of this terminal q-event. Otherwise false.
+ """
+ if type(self) is type(argument) and self.offset == argument.offset:
+ return True
+ return False
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes terminal q-event.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(TerminalQEvent, self).__hash__()
+
+
+
+import collections
+import copy
+import itertools
+import numbers
+import typing
+
+import abjad
+
+from . import qevents as _qevents
+
+
+
+[docs]
+class QEventSequence:
+ r"""
+ Q-event sequence.
+
+ Contains only pitched q-events and silent q-events, and terminates with a
+ single terminal q-event.
+
+ A q-event sequence is the primary input to the quantizer.
+
+ .. container:: example
+
+ A q-event sequence provides a number of convenience functions to assist
+ with instantiating new sequences:
+
+ >>> durations = (1000, -500, 1250, -500, 750)
+ >>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+ >>> for q_event in sequence:
+ ... q_event
+ ...
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ TerminalQEvent(...)
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_sequence",)
+
+ ### INITIALIZER ###
+
+ def __init__(self, sequence):
+ q_event_classes = (_qevents.PitchedQEvent, _qevents.SilentQEvent)
+ if sequence is None:
+ self._sequence = ()
+ return
+ else:
+ assert 1 < len(sequence)
+ assert all(
+ isinstance(q_event, q_event_classes) for q_event in sequence[:-1]
+ )
+ assert isinstance(sequence[-1], _qevents.TerminalQEvent)
+ offsets = [x.offset for x in sequence]
+ offset_sequence = list(offsets)
+ assert abjad.sequence.is_increasing(offset_sequence, strict=False)
+ assert 0 <= sequence[0].offset
+ self._sequence = tuple(sequence)
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __contains__(self, argument) -> bool:
+ """
+ Is true when q-event sequence contains ``argument``. Otherwise false.
+ """
+ return argument in self._sequence
+
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true when q-event sequence equals ``argument``. Otherwise false.
+ """
+ if type(self) is type(argument):
+ if self.sequence == argument.sequence:
+ return True
+ return False
+
+
+ @typing.overload
+ def __getitem__(self, argument: int) -> _qevents.QEvent:
+ pass
+
+ @typing.overload
+ def __getitem__(self, argument: slice) -> tuple[_qevents.QEvent, ...]:
+ pass
+
+
+[docs]
+ def __getitem__(
+ self, argument: int | slice
+ ) -> _qevents.QEvent | tuple[_qevents.QEvent, ...]:
+ """
+ Gets item or slice identified by `argument`.
+
+ Returns item or slice.
+ """
+ return self._sequence.__getitem__(argument)
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes q-event sequence.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(QEventSequence, self).__hash__()
+
+
+
+[docs]
+ def __iter__(self) -> typing.Iterator[_qevents.QEvent]:
+ """
+ Iterates q-event sequence.
+ """
+ for x in self._sequence:
+ yield x
+
+
+
+[docs]
+ def __len__(self) -> int:
+ """
+ Gets length of q-event sequence.
+ """
+ return len(self._sequence)
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def duration_in_ms(self) -> abjad.Duration:
+ r"""
+ Get duration ``QEventSequence`` in milliseconds:
+
+ >>> durations = (1000, -500, 1250, -500, 750)
+ >>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+ >>> sequence.duration_in_ms
+ Duration(4000, 1)
+
+ """
+ return abjad.Duration(self[-1].offset)
+
+ @property
+ def sequence(self) -> tuple:
+ r"""
+ Gets sequence of q-events.
+
+ >>> durations = (1000, -500, 1250, -500, 750)
+ >>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+ >>> for q_event in sequence.sequence:
+ ... q_event
+ ...
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ TerminalQEvent(...)
+
+ """
+ return self._sequence
+
+ ### PUBLIC METHODS ###
+
+
+[docs]
+ @classmethod
+ def from_millisecond_durations(
+ class_,
+ milliseconds: typing.Sequence[int | float],
+ fuse_silences: bool = False,
+ ) -> "QEventSequence":
+ r"""
+ Changes sequence of millisecond ``durations`` to ``QEventSequence``:
+
+ >>> durations = [-250, 500, -1000, 1250, -1000]
+ >>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+ >>> for q_event in sequence:
+ ... q_event
+ ...
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ TerminalQEvent(...)
+
+ """
+ durations: typing.Sequence[int | float]
+ if fuse_silences:
+ durations = [
+ _ for _ in abjad.sequence.sum_by_sign(milliseconds, sign=[-1]) if _
+ ]
+ else:
+ durations = milliseconds
+ sums = abjad.math.cumulative_sums([abs(_) for _ in durations])
+ offsets = [abjad.Offset(_) for _ in sums]
+ q_events: list[_qevents.QEvent] = []
+ for offset, duration in zip(offsets, durations):
+ q_event: _qevents.QEvent
+ if duration < 0:
+ q_event = _qevents.SilentQEvent(offset)
+ else:
+ q_event = _qevents.PitchedQEvent(offset, [0])
+ q_events.append(q_event)
+ q_event = _qevents.TerminalQEvent(offsets[-1])
+ q_events.append(q_event)
+ return class_(q_events)
+
+
+
+[docs]
+ @classmethod
+ def from_millisecond_offsets(
+ class_, offsets: typing.Sequence[abjad.Offset]
+ ) -> "QEventSequence":
+ r"""
+ Changes millisecond ``offsets`` to ``QEventSequence``:
+
+ >>> numbers = [0, 250, 750, 1750, 3000, 4000]
+ >>> offsets = [abjad.Offset(_) for _ in numbers]
+ >>> sequence = nauert.QEventSequence.from_millisecond_offsets(offsets)
+ >>> for q_event in sequence:
+ ... q_event
+ ...
+ PitchedQEvent(...)
+ PitchedQEvent(...)
+ PitchedQEvent(...)
+ PitchedQEvent(...)
+ PitchedQEvent(...)
+ TerminalQEvent(...)
+
+ """
+ assert all(isinstance(_, abjad.Offset) for _ in offsets), repr(offsets)
+ q_events: list[_qevents.QEvent] = []
+ q_events.extend([_qevents.PitchedQEvent(_, [0]) for _ in offsets[:-1]])
+ q_events.append(_qevents.TerminalQEvent(offsets[-1]))
+ return class_(q_events)
+
+
+
+[docs]
+ @classmethod
+ def from_millisecond_pitch_attachment_tuples(
+ class_, tuples: typing.Iterable[tuple]
+ ) -> "QEventSequence":
+ r"""
+ Changes (millisecond-duration, pitch, attachment) ``tuples`` into
+ ``QEventSequence``:
+
+ >>> durations = [250, 500, 1000, 1250, 1000]
+ >>> pitches = [(0,), None, (2, 3), None, (1,)]
+ >>> attachments = [("foo",), (), (), (), ("foobar", "foo")]
+ >>> tuples = tuple(zip(durations, pitches, attachments))
+ >>> method = nauert.QEventSequence.from_millisecond_pitch_attachment_tuples
+ >>> sequence = method(tuples)
+ >>> for q_event in sequence:
+ ... q_event
+ ...
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ TerminalQEvent(...)
+
+ """
+ assert isinstance(tuples, collections.abc.Iterable)
+ assert all(isinstance(_, collections.abc.Iterable) for _ in tuples)
+ assert all(len(_) == 3 for _ in tuples)
+ assert all(0 < duration for duration, _, _ in tuples)
+ pitch_prototype = (numbers.Number, type(None), collections.abc.Sequence)
+ for _, pitches, attachments in tuples:
+ if attachments is None:
+ raise Exception(attachments)
+ assert isinstance(pitches, pitch_prototype)
+ if isinstance(pitches, collections.abc.Sequence):
+ assert 0 < len(pitches)
+ assert all(isinstance(_, numbers.Number) for _ in pitches)
+ if pitches is None:
+ assert not attachments, repr(attachments)
+ # fuse silences
+ g = itertools.groupby(tuples, lambda _: _[1] is not None)
+ groups = []
+ for value, group in g:
+ if value:
+ groups.extend(list(group))
+ else:
+ duration = sum(_[0] for _ in group)
+ groups.append((duration, None, ()))
+ # find offsets
+ offsets = abjad.math.cumulative_sums([abs(_[0]) for _ in groups])
+ offsets = [abjad.Offset(_) for _ in offsets]
+ # build QEvents
+ q_events = [
+ _qevents.QEvent.from_offset_pitches_attachments(
+ offset, pitches, attachments
+ )
+ for offset, (_, pitches, attachments) in zip(offsets, groups)
+ ]
+ q_events.append(_qevents.TerminalQEvent(offsets[-1]))
+ return class_(q_events)
+
+
+
+[docs]
+ @classmethod
+ def from_millisecond_pitch_pairs(
+ class_, pairs: typing.Iterable[tuple]
+ ) -> "QEventSequence":
+ r"""
+ Changes (millisecond-duration, pitch) ``pairs`` into ``QEventSequence``:
+
+ >>> durations = [250, 500, 1000, 1250, 1000]
+ >>> pitches = [(0,), None, (2, 3), None, (1,)]
+ >>> pairs = tuple(zip(durations, pitches))
+ >>> sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+ >>> for q_event in sequence:
+ ... q_event
+ ...
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ TerminalQEvent(...)
+
+ """
+ assert isinstance(pairs, collections.abc.Iterable)
+ assert all(isinstance(_, collections.abc.Iterable) for _ in pairs)
+ assert all(len(_) == 2 for _ in pairs)
+ assert all(0 < duration for duration, _ in pairs)
+ pitch_prototype = (numbers.Number, type(None), collections.abc.Sequence)
+ for _, pitches in pairs:
+ assert isinstance(pitches, pitch_prototype)
+ if isinstance(pitches, collections.abc.Sequence):
+ assert 0 < len(pitches)
+ assert all(isinstance(_, numbers.Number) for _ in pitches)
+ return class_.from_millisecond_pitch_attachment_tuples(
+ [(duration, pitches, ()) for duration, pitches in pairs]
+ )
+
+
+
+[docs]
+ @classmethod
+ def from_tempo_scaled_durations(
+ class_,
+ durations: typing.Sequence[abjad.typings.Duration],
+ tempo: abjad.MetronomeMark,
+ ) -> "QEventSequence":
+ r"""
+ Changes ``durations``, scaled by ``tempo`` into a ``QEventSequence``:
+
+ .. container:: example
+
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 174)
+ >>> pairs = [(1, 4), (-3, 16), (1, 16), (-1, 2)]
+ >>> durations = [abjad.Duration(_) for _ in pairs]
+ >>> method = nauert.QEventSequence.from_tempo_scaled_durations
+ >>> sequence = method(durations, tempo=tempo)
+ >>> for q_event in sequence:
+ ... q_event
+ ...
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ TerminalQEvent(...)
+
+ """
+ assert all(isinstance(_, abjad.Duration) for _ in durations), repr(durations)
+ assert isinstance(tempo, abjad.MetronomeMark)
+ durations = [x for x in abjad.sequence.sum_by_sign(durations, sign=[-1]) if x]
+ durations = [tempo.duration_to_milliseconds(_) for _ in durations]
+ offsets = abjad.math.cumulative_sums([abs(_) for _ in durations])
+ offsets = [abjad.Offset(_) for _ in offsets]
+ q_events = []
+ for offset, duration in zip(offsets, durations):
+ offset = abjad.Offset(offset)
+ assert isinstance(duration, abjad.Duration)
+ q_event: _qevents.QEvent
+ # negative duration indicates silence
+ if duration < 0:
+ q_event = _qevents.SilentQEvent(offset)
+ # otherwise use middle C
+ else:
+ q_event = _qevents.PitchedQEvent(offset, [0])
+ q_events.append(q_event)
+ # insert terminating silence _qevents.QEvent
+ q_events.append(_qevents.TerminalQEvent(offsets[-1]))
+ return class_(q_events)
+
+
+
+[docs]
+ @classmethod
+ def from_tempo_scaled_leaves(class_, leaves, tempo=None) -> "QEventSequence":
+ r"""
+ Changes ``leaves``, optionally with ``tempo`` into a ``QEventSequence``:
+
+ >>> staff = abjad.Staff("c'4 <d' fs'>8. r16 gqs'2")
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 72)
+ >>> sequence = nauert.QEventSequence.from_tempo_scaled_leaves(staff[:], tempo)
+ >>> for q_event in sequence:
+ ... q_event
+ ...
+ PitchedQEvent(...)
+ PitchedQEvent(...)
+ SilentQEvent(...)
+ PitchedQEvent(...)
+ TerminalQEvent(...)
+
+ If ``tempo`` is ``None``, all leaves in ``leaves`` must have an
+ effective, non-imprecise tempo. The millisecond-duration of each leaf
+ will be determined by its effective tempo.
+ """
+ assert len(leaves)
+ match tempo:
+ case None:
+ prototype = abjad.MetronomeMark
+ assert abjad.get.effective(leaves[0], prototype) is not None
+ case abjad.MetronomeMark():
+ tempo = copy.deepcopy(tempo)
+ case tuple():
+ tempo = abjad.MetronomeMark(*tempo)
+ case _:
+ raise TypeError(tempo)
+ # sort by silence and tied leaves
+ groups = []
+ for rvalue, rgroup in itertools.groupby(
+ leaves, lambda x: isinstance(x, (abjad.Rest, abjad.Skip))
+ ):
+ if rvalue:
+ groups.append(list(rgroup))
+ else:
+ for tvalue, tgroup in itertools.groupby(
+ rgroup, lambda x: abjad._iterlib._get_logical_tie_leaves(x)
+ ):
+ groups.append(list(tgroup))
+ # calculate lists of pitches and durations
+ durations = []
+ pitches = []
+ for group in groups:
+ # get millisecond cumulative duration
+ if tempo is not None:
+ duration = sum(
+ tempo.duration_to_milliseconds(x._get_duration()) for x in group
+ )
+ else:
+ duration = sum(
+ abjad.get.effective(
+ x, abjad.MetronomeMark
+ ).duration_to_milliseconds(x._get_duration())
+ for x in group
+ )
+ durations.append(duration)
+ pitch: typing.Any
+ # get pitch of first leaf in group
+ if isinstance(group[0], (abjad.Rest, abjad.Skip)):
+ pitch = None
+ elif isinstance(group[0], abjad.Note):
+ assert group[0].written_pitch is not None
+ pitch = group[0].written_pitch.number
+ # chord
+ else:
+ pitch = [x.written_pitch.number for x in group[0].note_heads]
+ pitches.append(pitch)
+ # convert durations and pitches to QEvents and return
+ return class_.from_millisecond_pitch_pairs(tuple(zip(durations, pitches)))
+
+
+
+import bisect
+import copy
+import typing
+
+import abjad
+import uqbar.containers
+import uqbar.graphs
+
+from . import qeventproxy as _qeventproxy
+
+
+
+[docs]
+class QGridLeaf(abjad.rhythmtrees.RhythmTreeNode, uqbar.containers.UniqueTreeNode):
+ """
+ Q-grid leaf.
+
+ .. container:: example
+
+ >>> nauert.QGridLeaf()
+ QGridLeaf((1, 1), q_event_proxies=[], is_divisible=True)
+
+ Used internally by ``QGrid``.
+ """
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ preprolated_duration: abjad.typings.Duration = abjad.Duration(1),
+ q_event_proxies: typing.Sequence[_qeventproxy.QEventProxy] = (),
+ is_divisible: bool = True,
+ ) -> None:
+ assert isinstance(preprolated_duration, abjad.Duration), repr(
+ preprolated_duration
+ )
+ assert q_event_proxies is not None, repr(q_event_proxies)
+ assert all(isinstance(x, _qeventproxy.QEventProxy) for x in q_event_proxies)
+ assert isinstance(is_divisible, bool), repr(is_divisible)
+ uqbar.containers.UniqueTreeNode.__init__(self)
+ abjad.rhythmtrees.RhythmTreeNode.__init__(self, preprolated_duration.pair)
+ self._q_event_proxies = list(q_event_proxies)
+ self._is_divisible = is_divisible
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(
+ self, pulse_duration: abjad.Duration
+ ) -> list[abjad.Note | abjad.Tuplet]:
+ """
+ Calls q-grid leaf.
+ """
+ assert isinstance(pulse_duration, abjad.Duration), repr(pulse_duration)
+ total_duration = pulse_duration * abjad.Duration(self.pair)
+ return abjad.makers.make_notes(0, total_duration)
+
+
+
+[docs]
+ def __graph__(self, **keywords: None) -> uqbar.graphs.Graph:
+ """
+ Graphviz graph of q-grid leaf.
+ """
+ graph = uqbar.graphs.Graph(name="G")
+ label = str(self.pair)
+ node = uqbar.graphs.Node(attributes={"label": label, "shape": "box"})
+ graph.append(node)
+ return graph
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}({self.pair!r},"
+ string += f" q_event_proxies={self.q_event_proxies!r},"
+ string += f" is_divisible={self.is_divisible!r})"
+ return string
+
+
+ ### PRIVATE PROPERTIES ###
+
+ @property
+ def _pretty_rtm_format_pieces(self) -> list[str]:
+ numerator, denominator = self.pair
+ assert denominator == 1, repr(denominator)
+ return [str(numerator)]
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def is_divisible(self) -> bool:
+ """
+ Flag for whether the node may be further divided
+ under some search tree.
+ """
+ return self._is_divisible
+
+ @is_divisible.setter
+ def is_divisible(self, argument):
+ self._is_divisible = bool(argument)
+
+ @property
+ def preceding_q_event_proxies(self) -> list[_qeventproxy.QEventProxy]:
+ """
+ Gets preceding q-event proxies of q-grid leaf.
+ """
+ return [x for x in self._q_event_proxies if x.offset < self.start_offset]
+
+ @property
+ def q_event_proxies(self) -> list[_qeventproxy.QEventProxy]:
+ """
+ Gets q-event proxies of q-grid leaf.
+ """
+ return self._q_event_proxies
+
+ @property
+ def rtm_format(self) -> str:
+ """
+ Gets RTM format of q-grid leaf.
+ """
+ numerator, denominator = self.pair
+ assert denominator == 1, repr(denominator)
+ return str(numerator)
+
+ @property
+ def succeeding_q_event_proxies(self) -> list[_qeventproxy.QEventProxy]:
+ """
+ Gets succeeding q-event proxies of q-grid leaf.
+ """
+ return [x for x in self._q_event_proxies if self.start_offset <= x.offset]
+
+
+
+
+[docs]
+class QGridContainer(abjad.rhythmtrees.RhythmTreeContainer):
+ """
+ Q-grid container.
+
+ .. container:: example
+
+ >>> nauert.QGridContainer((1, 1))
+ QGridContainer((1, 1))
+
+ Used internally by ``QGrid``.
+ """
+
+ ### PRIVATE PROPERTIES ###
+
+ @property
+ def _leaf_class(self) -> type:
+ return QGridLeaf
+
+ @property
+ def _node_class(self) -> tuple[type, type]:
+ return (type(self), QGridLeaf)
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def leaves(self) -> tuple[QGridLeaf, ...]:
+ """
+ Gets leaves.
+ """
+ return tuple(_ for _ in self.depth_first() if isinstance(_, QGridLeaf))
+
+
+
+
+[docs]
+class QGrid:
+ """
+ Q-grid.
+
+ Rhythm-tree-based model for how millisecond attack points collapse onto the
+ offsets generated by a nested rhythmic structure.
+
+ .. container:: example
+
+ ``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_grid = nauert.QGrid()
+ >>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0])
+ >>> q_event_b = nauert.PitchedQEvent(abjad.Offset(750), [1])
+ >>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+ >>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(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(...)
+
+ >>> for q_event_proxy in q_grid.next_downbeat.q_event_proxies:
+ ... q_event_proxy
+ ...
+ QEventProxy(...)
+
+ Used internally by the ``quantize`` function.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_next_downbeat", "_root_node")
+
+ ### INITIALIZATION ###
+
+ def __init__(
+ self,
+ root_node: QGridLeaf | QGridContainer | None = None,
+ next_downbeat: QGridLeaf | None = None,
+ ) -> None:
+ if root_node is None:
+ root_node = QGridLeaf(abjad.Duration(1, 1))
+ assert isinstance(
+ root_node,
+ (QGridLeaf, QGridContainer),
+ )
+ if next_downbeat is None:
+ next_downbeat = QGridLeaf(abjad.Duration(1, 1))
+ assert isinstance(next_downbeat, QGridLeaf)
+ self._root_node = root_node
+ self._next_downbeat = next_downbeat
+ self._next_downbeat._offset = abjad.Offset(1)
+ self._next_downbeat._offsets_are_current = True
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(self, beatspan: abjad.Duration) -> list[abjad.Leaf | abjad.Tuplet]:
+ """
+ Calls q-grid.
+ """
+ assert isinstance(beatspan, abjad.Duration), repr(beatspan)
+ result = []
+ components = self.root_node(beatspan)
+ voice = abjad.Voice(components)
+ for tuplet in abjad.select.components(voice, abjad.Tuplet):
+ assert isinstance(tuplet, abjad.Tuplet)
+ if tuplet.trivial():
+ abjad.mutate.extract(tuplet)
+ components_ = abjad.mutate.eject_contents(voice)
+ for component in components_:
+ assert isinstance(component, abjad.Leaf | abjad.Tuplet)
+ result.append(component)
+ result_logical_ties = list(abjad.iterate.logical_ties(result))
+ for logical_tie, q_grid_leaf in zip(result_logical_ties, self.leaves[:-1]):
+ if q_grid_leaf.q_event_proxies:
+ q_events = [
+ q_event_proxy.q_event
+ for q_event_proxy in q_grid_leaf.q_event_proxies
+ ]
+ q_events.sort(
+ key=lambda x: 0 if x is None or x.index is None else x.index
+ )
+ annotation = {"q_events": tuple(q_events)}
+ leaf = abjad.get.leaf(logical_tie, 0)
+ abjad.attach(annotation, leaf)
+ return result
+
+
+
+[docs]
+ def __copy__(self, *arguments: None) -> "QGrid":
+ """
+ Copies q-grid.
+ """
+ root_node, next_downbeat = self._root_node, self._next_downbeat
+ return type(self)(copy.deepcopy(root_node), copy.deepcopy(next_downbeat))
+
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true if `argument` is a q-grid with root node and next downbeat
+ equal to those of this q-grid. Otherwise false.
+ """
+ if type(self) is type(argument):
+ if self.root_node == argument.root_node:
+ if self.next_downbeat == argument.next_downbeat:
+ return True
+ return False
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes q-grid.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(QGrid, self).__hash__()
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(root_node={self.root_node!r},"
+ string += f" next_downbeat={self.next_downbeat!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def distance(self) -> typing.Optional[abjad.Duration]:
+ r"""
+ The computed total distance (divided by the number of ``QEventProxy``
+ objects) of the offset of each ``QEventProxy`` contained by the
+ ``QGrid`` to the offset of the ``QGridLeaf`` to which the
+ ``QEventProxy`` is attached.
+
+ .. container:: example
+
+ >>> q_grid = nauert.QGrid()
+ >>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0], ["A"])
+ >>> q_event_b = nauert.PitchedQEvent(abjad.Offset(750), [1], ["B"])
+ >>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+ >>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.75))
+ >>> q_grid.fit_q_events([proxy_a, proxy_b])
+ >>> print(q_grid.rtm_format)
+ 1
+
+ >>> pairs = zip(q_grid.leaves, q_grid.offsets, strict=True)
+ >>> for index, (leaf, offset) in enumerate(pairs):
+ ... 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))
+
+ >>> pairs = zip(q_grid.leaves, q_grid.offsets, strict=True)
+ >>> for index, (leaf, offset) in enumerate(pairs):
+ ... 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)
+
+ """
+ count = 0
+ absolute_distance = abjad.Duration(0)
+ for leaf, offset in zip(self.leaves, self.offsets):
+ for q_event_proxy in leaf.q_event_proxies:
+ absolute_distance += abs(q_event_proxy.offset - offset)
+ count += 1
+ if count:
+ return absolute_distance / count
+ return None
+
+ @property
+ def leaves(self) -> tuple[QGridLeaf, ...]:
+ """
+ Gets all of the leaf nodes in the QGrid, including the next downbeat's
+ node.
+ """
+ if isinstance(self._root_node, QGridLeaf):
+ return (self._root_node, self._next_downbeat)
+ return self._root_node.leaves + (self._next_downbeat,)
+
+ @property
+ def next_downbeat(self) -> QGridLeaf:
+ """
+ Gets the node representing the "next" downbeat after the contents of
+ the QGrid's tree.
+ """
+ return self._next_downbeat
+
+ @property
+ def offsets(self) -> tuple[abjad.Offset, ...]:
+ """
+ Gets the offsets between 0 and 1 of all of the leaf nodes in the QGrid.
+ """
+ return tuple([x.start_offset for x in self.leaves[:-1]] + [abjad.Offset(1)])
+
+ @property
+ def pretty_rtm_format(self) -> str:
+ """
+ Gets the pretty RTM-format of the root node of the ``QGrid``.
+ """
+ return self._root_node.pretty_rtm_format
+
+ @property
+ def root_node(self) -> QGridLeaf | QGridContainer:
+ """
+ Gets the root node of the ``QGrid``.
+ """
+ return self._root_node
+
+ @property
+ def rtm_format(self) -> str:
+ """
+ Gets the RTM format of the root node of the ``QGrid``.
+ """
+ return self._root_node.rtm_format
+
+ ### PUBLIC METHODS ###
+
+
+[docs]
+ def fit_q_events(
+ self, q_event_proxies: typing.Sequence[_qeventproxy.QEventProxy]
+ ) -> None:
+ """
+ Fits each ``QEventProxy`` in ``q_event_proxies`` onto the contained
+ ``QGridLeaf`` whose offset is nearest.
+ """
+ assert all(isinstance(x, _qeventproxy.QEventProxy) for x in q_event_proxies)
+ leaves, offsets = self.leaves, self.offsets
+ for q_event_proxy in q_event_proxies:
+ idx = bisect.bisect_left(offsets, q_event_proxy.offset)
+ if q_event_proxy.offset == offsets[idx]:
+ leaves[idx].q_event_proxies.append(q_event_proxy)
+ else:
+ left, right = offsets[idx - 1], offsets[idx]
+ left_diff = abs(left - q_event_proxy.offset)
+ right_diff = abs(right - q_event_proxy.offset)
+ if right_diff < left_diff:
+ leaves[idx].q_event_proxies.append(q_event_proxy)
+ else:
+ leaves[idx - 1].q_event_proxies.append(q_event_proxy)
+
+
+
+[docs]
+ def regroup_leaves_with_unencessary_divisions(self) -> None:
+ """
+ Regroups leaves that belong to the same parent in which only the first
+ leaf contains q_event_prox[y|ies].
+ """
+ index = 0
+ while True:
+ leaf = self.leaves[index]
+ parent = leaf.parent
+ if isinstance(parent, QGridContainer):
+ leaves = parent.leaves
+ if len(leaves) > 1 and all(
+ [_leaf.q_event_proxies == [] for _leaf in leaves[1:]]
+ ):
+ new_leaf = QGridLeaf(
+ preprolated_duration=abjad.Duration(parent.pair),
+ q_event_proxies=leaves[0].q_event_proxies,
+ )
+ index = parent.parent.index(parent)
+ parent.parent[index] = [new_leaf]
+ index += 1
+ if index == len(self.leaves):
+ break
+
+
+
+[docs]
+ def sort_q_events_by_index(self) -> None:
+ """
+ Sorts ``QEventProxies`` attached to each ``QGridLeaf`` in a ``QGrid``
+ by their index.
+ """
+ for leaf in self.leaves:
+ leaf.q_event_proxies.sort(key=lambda x: 0 if x.index is None else x.index)
+
+
+
+[docs]
+ def subdivide_leaf(
+ self,
+ leaf: QGridLeaf,
+ subdivisions: typing.Sequence[abjad.typings.Duration | int],
+ ) -> list[_qeventproxy.QEventProxy]:
+ """
+ Replaces 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``.
+ """
+ children = []
+ for subdivision in subdivisions:
+ if isinstance(subdivision, int):
+ subdivision = abjad.Duration(subdivision)
+ child = QGridLeaf(preprolated_duration=subdivision)
+ children.append(child)
+ container = QGridContainer(
+ leaf.pair,
+ children=[
+ QGridLeaf(preprolated_duration=abjad.Duration(subdivision))
+ for subdivision in subdivisions
+ ],
+ )
+ if leaf.parent is not None:
+ index = leaf.parent.index(leaf)
+ leaf.parent[index] = [container]
+ # otherwise, our root node if just a QGridLeaf
+ else:
+ self._root_node = container
+ return leaf.q_event_proxies
+
+
+
+[docs]
+ def subdivide_leaves(
+ self, pairs: typing.Sequence[tuple[int, tuple[int, int]]]
+ ) -> list[_qeventproxy.QEventProxy]:
+ r"""
+ 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``.
+ """
+ pairs = sorted(dict(pairs).items())
+ leaf_indices = [pair[0] for pair in pairs]
+ subdivisions = [pair[1] for pair in pairs]
+ all_leaves = self.leaves
+ leaves_to_subdivide = [all_leaves[idx] for idx in leaf_indices]
+ q_event_proxies = []
+ for i, leaf in enumerate(leaves_to_subdivide):
+ next_leaf = all_leaves[all_leaves.index(leaf) + 1]
+ if next_leaf is self.next_downbeat:
+ next_leaf_offset = abjad.Offset(1)
+ else:
+ next_leaf_offset = next_leaf.start_offset
+
+ q_event_proxies.extend(self.subdivide_leaf(leaf, subdivisions[i]))
+ for q_event_proxy in tuple(next_leaf.q_event_proxies):
+ if q_event_proxy.offset < next_leaf_offset:
+ idx = next_leaf.q_event_proxies.index(q_event_proxy)
+ q_event_proxies.append(next_leaf.q_event_proxies.pop(idx))
+ return q_event_proxies
+
+
+
+import abc
+import typing
+
+import abjad
+
+from . import searchtrees as _searchtrees
+
+
+
+[docs]
+class QSchemaItem(abc.ABC):
+ """
+ Abstract q-schema item.
+
+ Represents a change of state in the timeline of a quantization process.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_search_tree", "_tempo")
+
+ ### INITIALIZER ###
+
+ @abc.abstractmethod
+ def __init__(
+ self,
+ search_tree: _searchtrees.SearchTree | None = None,
+ tempo: abjad.MetronomeMark | None = None,
+ ) -> None:
+ if search_tree is not None:
+ assert isinstance(search_tree, _searchtrees.SearchTree)
+ self._search_tree = search_tree
+ if tempo is not None:
+ assert isinstance(tempo, abjad.MetronomeMark), repr(tempo)
+ assert not tempo.is_imprecise
+ self._tempo = tempo
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def search_tree(self) -> typing.Optional[_searchtrees.SearchTree]:
+ """
+ The optionally defined search tree.
+ """
+ return self._search_tree
+
+ @property
+ def tempo(self) -> typing.Optional[abjad.MetronomeMark]:
+ """
+ The optionally defined tempo.
+ """
+ return self._tempo
+
+
+
+
+[docs]
+class BeatwiseQSchemaItem(QSchemaItem):
+ """
+ Beatwise q-schema item.
+
+ .. container:: example
+
+ Represents a change of state in the timeline of an unmetered
+ quantization process:
+
+ >>> nauert.BeatwiseQSchemaItem()
+ BeatwiseQSchemaItem(beatspan=None, search_tree=None, tempo=None)
+
+ .. container:: example
+
+ Defines a change in tempo:
+
+ >>> metronome_mark = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> nauert.BeatwiseQSchemaItem(tempo=metronome_mark)
+ BeatwiseQSchemaItem(...)
+
+ .. container:: example
+
+ Defines a change in beatspan:
+
+ >>> nauert.BeatwiseQSchemaItem(beatspan=abjad.Duration(1, 8))
+ BeatwiseQSchemaItem(beatspan=Duration(1, 8), search_tree=None, tempo=None)
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_beatspan",)
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ beatspan: abjad.Duration | None = None,
+ search_tree: _searchtrees.SearchTree | None = None,
+ tempo: abjad.MetronomeMark | None = None,
+ ) -> None:
+ if beatspan is not None:
+ assert isinstance(beatspan, abjad.Duration), repr(beatspan)
+ QSchemaItem.__init__(self, search_tree=search_tree, tempo=tempo)
+ if beatspan is not None:
+ beatspan = abjad.Duration(beatspan)
+ assert 0 < beatspan
+ self._beatspan = beatspan
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(beatspan={self.beatspan!r},"
+ string += f" search_tree={self.search_tree!r}, tempo={self.tempo!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def beatspan(self) -> typing.Optional[abjad.Duration]:
+ """
+ The optionally defined beatspan duration.
+ """
+ return self._beatspan
+
+
+
+
+[docs]
+class MeasurewiseQSchemaItem(QSchemaItem):
+ r"""
+ Measurewise q-schema item.
+
+ Represents a change of state in the timeline of a metered quantization process.
+
+ >>> q_schema_item = nauert.MeasurewiseQSchemaItem()
+
+ .. container:: example
+
+ Defines a change in tempo:
+
+ >>> metronome_mark = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> mark = nauert.MeasurewiseQSchemaItem(tempo=metronome_mark).tempo
+ >>> abjad.lilypond(mark)
+ '\\tempo 4=60'
+
+ .. container:: example
+
+ Defines a change in time signature:
+
+ >>> time_signature = abjad.TimeSignature((6, 8))
+ >>> nauert.MeasurewiseQSchemaItem(time_signature=time_signature).time_signature
+ TimeSignature(pair=(6, 8), hide=False, partial=None)
+
+ .. container:: example
+
+ Tests for beatspan given a defined time signature:
+
+ >>> time_signature = abjad.TimeSignature((6, 8))
+ >>> nauert.MeasurewiseQSchemaItem(time_signature=time_signature).beatspan
+ Duration(1, 8)
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_time_signature", "_use_full_measure")
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ search_tree: _searchtrees.SearchTree | None = None,
+ tempo: abjad.MetronomeMark | None = None,
+ time_signature: abjad.TimeSignature | None = None,
+ use_full_measure: bool | None = None,
+ ):
+ if time_signature is not None:
+ assert isinstance(time_signature, abjad.TimeSignature), repr(time_signature)
+ QSchemaItem.__init__(self, search_tree=search_tree, tempo=tempo)
+ self._time_signature: abjad.TimeSignature | None
+ if isinstance(time_signature, abjad.TimeSignature):
+ self._time_signature = abjad.TimeSignature(time_signature.pair)
+ elif isinstance(time_signature, tuple):
+ self._time_signature = abjad.TimeSignature(time_signature)
+ else:
+ assert time_signature is None
+ self._time_signature = None
+ if use_full_measure is not None:
+ use_full_measure = bool(use_full_measure)
+ self._use_full_measure = use_full_measure
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(search_tree={self.search_tree!r},"
+ string += f" tempo={self.tempo!r}, time_signature={self.time_signature!r},"
+ string += f" use_full_measure={self.use_full_measure!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def beatspan(self) -> typing.Optional[abjad.Duration]:
+ """
+ The beatspan duration, if a time signature was defined.
+ """
+ if self.time_signature is not None:
+ if self.use_full_measure:
+ return self.time_signature.duration
+ else:
+ return abjad.Duration(1, self.time_signature.denominator)
+ return None
+
+ @property
+ def time_signature(self) -> typing.Optional[abjad.TimeSignature]:
+ """
+ The optionally defined time signature.
+ """
+ return self._time_signature
+
+ @property
+ def use_full_measure(self) -> typing.Optional[bool]:
+ """
+ If true, use the full measure as the beatspan.
+ """
+ return self._use_full_measure
+
+
+import abc
+import bisect
+import copy
+
+import abjad
+
+from . import qschemaitems as _qschemaitems
+from . import qtargetitems as _qtargetitems
+from . import qtargets as _qtargets
+from . import searchtrees as _searchtrees
+
+
+
+[docs]
+class QSchema(abc.ABC):
+ """
+ Abstract Q-schema.
+
+ ``QSchema`` allows for the specification of quantization settings
+ diachronically, at any time-step of the quantization process.
+
+ In practice, this provides a means for the composer to change the tempo,
+ search-tree, time-signature etc., effectively creating a template into
+ which quantized rhythms can be "poured", without yet knowing what those
+ rhythms might be, or even how much time the ultimate result will take. Like
+ Abjad indicators the settings made at any given time-step via a ``QSchema``
+ instance are understood to persist until changed.
+
+ All concrete ``QSchema`` subclasses strongly implement default values for
+ all of their parameters.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_items", "_lookups")
+
+ _keyword_argument_names: tuple[str, ...] = ()
+
+ _search_tree = _searchtrees.UnweightedSearchTree()
+
+ _tempo = abjad.MetronomeMark()
+
+ ### INITIALIZER ###
+
+ @abc.abstractmethod
+ def __init__(self, *arguments, **keywords):
+ if 1 == len(arguments) and isinstance(arguments[0], type(self)):
+ items = copy.deepcopy(arguments[0].items)
+ elif 1 == len(arguments) and isinstance(arguments[0], dict):
+ items = list(arguments[0].items())
+ if abjad.math.all_are_pairs_of_types(items, int, dict):
+ items = [(x, self.item_class(**y)) for x, y in items]
+ assert abjad.math.all_are_pairs_of_types(items, int, self.item_class)
+ items = dict(items)
+ elif abjad.math.all_are_pairs_of_types(arguments, int, self.item_class):
+ items = dict(arguments)
+ elif abjad.math.all_are_pairs_of_types(arguments, int, dict):
+ items = [(x, self.item_class(**y)) for x, y in arguments]
+ items = dict(items)
+ elif all(isinstance(x, self.item_class) for x in arguments):
+ items = [(i, x) for i, x in enumerate(arguments)]
+ items = dict(items)
+ elif all(isinstance(x, dict) for x in arguments):
+ items = [(i, self.item_class(**x)) for i, x in enumerate(arguments)]
+ items = dict(items)
+ else:
+ raise ValueError
+ if items:
+ assert 0 <= min(items)
+ self._items = dict(items)
+ self._lookups = self._create_lookups()
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(self, duration: abjad.Duration) -> _qtargets.QTarget:
+ """
+ Calls QSchema on ``duration``.
+ """
+ assert isinstance(duration, abjad.Duration), repr(duration)
+ target_items = []
+ idx, current_offset = 0, abjad.Offset(0)
+ duration = abjad.Duration(duration)
+ while current_offset < duration:
+ lookup = self[idx]
+ lookup["offset_in_ms"] = current_offset
+ target_item = self.target_item_class(**lookup)
+ target_items.append(target_item)
+ current_offset += target_item.duration_in_ms
+ idx += 1
+ return self.target_class(target_items)
+
+
+
+[docs]
+ def __getitem__(self, argument: int) -> dict:
+ """
+ Gets item or slice identified by `argument`.
+ """
+ assert isinstance(argument, int) and 0 <= argument
+ result = {}
+ for field in self._lookups:
+ lookup = self._lookups[field].get(argument)
+ if lookup is not None:
+ result[field] = lookup
+ else:
+ keys = sorted(self._lookups[field].keys())
+ idx = bisect.bisect(keys, argument)
+ if len(keys) == idx:
+ key = keys[-1]
+ elif argument < keys[idx]:
+ key = keys[idx - 1]
+ result[field] = self._lookups[field][key]
+ return result
+
+
+ ### PRIVATE METHODS ###
+
+ def _create_lookups(self) -> dict[str, dict]:
+ names = self._keyword_argument_names
+ lookups = {}
+ for name in names:
+ lookups[name] = {0: getattr(self, name)}
+ for position, item in self.items.items():
+ value = getattr(item, name)
+ if value is not None:
+ lookups[name][position] = value
+ lookups[name] = dict(lookups[name])
+ return dict(lookups)
+
+ ### PUBLIC PROPERTIES ###
+
+ @abc.abstractproperty
+ def item_class(self):
+ """
+ Gets schema's item class.
+ """
+ raise NotImplementedError
+
+ @property
+ def items(self) -> dict[int, _qschemaitems.QSchemaItem]:
+ """
+ Gets items dictionary.
+ """
+ return self._items
+
+ @property
+ def search_tree(self) -> _searchtrees.SearchTree:
+ """
+ Gets default search tree.
+ """
+ return self._search_tree
+
+ @abc.abstractproperty
+ def target_class(self):
+ """
+ Gets schema's target class.
+ """
+ raise NotImplementedError
+
+ @abc.abstractproperty
+ def target_item_class(self):
+ """
+ Gets schema's target class' item class.
+ """
+ raise NotImplementedError
+
+ @property
+ def tempo(self) -> abjad.MetronomeMark:
+ """
+ Gets default tempo.
+ """
+ return self._tempo
+
+
+
+
+[docs]
+class BeatwiseQSchema(QSchema):
+ r"""
+ Beatwise q-schema.
+
+ Treats beats as timestep unit.
+
+ >>> q_schema = nauert.BeatwiseQSchema()
+
+ Without arguments, it uses smart defaults:
+
+ .. container:: example
+
+ Each time-step in a ``BeatwiseQSchema`` is composed of three settings:
+
+ * ``beatspan``
+ * ``search_tree``
+ * ``tempo``
+
+ These settings can be applied as global defaults for the schema via keyword
+ arguments, which persist until overridden:
+
+ >>> beatspan = abjad.Duration(5, 16)
+ >>> search_tree = nauert.UnweightedSearchTree({7: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+ >>> q_schema = nauert.BeatwiseQSchema(
+ ... beatspan=beatspan,
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... )
+
+ .. container:: example
+
+ The computed value at any non-negative time-step can be found by
+ subscripting:
+
+ >>> index = 0
+ >>> for key, value in sorted(q_schema[index].items()):
+ ... print("{}:".format(key), value)
+ ...
+ beatspan: 5/16
+ search_tree: UnweightedSearchTree(definition={7: None})
+ tempo: MetronomeMark(...)
+
+ >>> index = 1000
+ >>> for key, value in sorted(q_schema[index].items()):
+ ... print("{}:".format(key), value)
+ ...
+ beatspan: 5/16
+ search_tree: UnweightedSearchTree(definition={7: None})
+ tempo: MetronomeMark(...)
+
+ .. container:: example
+
+ Per-time-step settings can be applied in a variety of ways.
+
+ Instantiating the schema via ``*arguments`` with a series of either
+ ``BeatwiseQSchemaItem`` instances, or dictionaries which could be used to
+ instantiate ``BeatwiseQSchemaItem`` instances, will apply those settings
+ sequentially, starting from time-step ``0``:
+
+ >>> a = {"beatspan": abjad.Duration(5, 32)}
+ >>> b = {"beatspan": abjad.Duration(3, 16)}
+ >>> c = {"beatspan": abjad.Duration(1, 8)}
+
+ >>> q_schema = nauert.BeatwiseQSchema(a, b, c)
+
+ >>> q_schema[0]["beatspan"]
+ Duration(5, 32)
+
+ >>> q_schema[1]["beatspan"]
+ Duration(3, 16)
+
+ >>> q_schema[2]["beatspan"]
+ Duration(1, 8)
+
+ >>> q_schema[3]["beatspan"]
+ Duration(1, 8)
+
+ .. container:: example
+
+ Similarly, instantiating the schema from a single dictionary, consisting
+ of integer:specification pairs, or a sequence via ``*arguments`` of (integer,
+ specification) pairs, allows for applying settings to non-sequential
+ time-steps:
+
+ >>> a = {"search_tree": nauert.UnweightedSearchTree({2: None})}
+ >>> b = {"search_tree": nauert.UnweightedSearchTree({3: None})}
+
+ >>> settings = {
+ ... 2: a,
+ ... 4: b,
+ ... }
+
+ >>> q_schema = nauert.BeatwiseQSchema(settings)
+
+ >>> import pprint
+ >>> ust = q_schema[0]["search_tree"]
+ >>> pprint.pprint(ust.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}
+
+ >>> ust = q_schema[1]["search_tree"]
+ >>> pprint.pprint(ust.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}
+
+ >>> q_schema[2]["search_tree"]
+ UnweightedSearchTree(definition={2: None})
+
+ >>> q_schema[3]["search_tree"]
+ UnweightedSearchTree(definition={2: None})
+
+ >>> q_schema[4]["search_tree"]
+ UnweightedSearchTree(definition={3: None})
+
+ >>> q_schema[1000]["search_tree"]
+ UnweightedSearchTree(definition={3: None})
+
+ .. container:: example
+
+ The following is equivalent to the above schema definition:
+
+ >>> q_schema = nauert.BeatwiseQSchema(
+ ... (2, {"search_tree": nauert.UnweightedSearchTree({2: None})}),
+ ... (4, {"search_tree": nauert.UnweightedSearchTree({3: None})}),
+ ... )
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_beatspan", "_items", "_lookups", "_search_tree", "_tempo")
+
+ _keyword_argument_names = ("beatspan", "search_tree", "tempo")
+
+ ### INITIALIZER ###
+
+ def __init__(self, *arguments, **keywords):
+ self._beatspan = abjad.Duration(keywords.get("beatspan", (1, 4)))
+ search_tree = keywords.get("search_tree", _searchtrees.UnweightedSearchTree())
+ assert isinstance(search_tree, _searchtrees.SearchTree)
+ self._search_tree = search_tree
+ tempo = keywords.get("tempo", (abjad.Duration(1, 4), 60))
+ if isinstance(tempo, tuple):
+ tempo = abjad.MetronomeMark(*tempo)
+ self._tempo = tempo
+ QSchema.__init__(self, *arguments, **keywords)
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(beatspan={self.beatspan!r},"
+ string += f" search_tree={self.search_tree!r}, tempo={self.tempo!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def beatspan(self) -> abjad.Duration:
+ """
+ Gets default beatspan of beatwise q-schema.
+ """
+ return self._beatspan
+
+ @property
+ def item_class(self) -> type[_qschemaitems.BeatwiseQSchemaItem]:
+ """
+ Gets schema's item class.
+ """
+ return _qschemaitems.BeatwiseQSchemaItem
+
+ @property
+ def target_class(self) -> type[_qtargets.BeatwiseQTarget]:
+ """
+ Gets target class of beatwise q-schema.
+ """
+ return _qtargets.BeatwiseQTarget
+
+ @property
+ def target_item_class(self) -> type[_qtargetitems.QTargetBeat]:
+ """
+ Gets target item class of beatwise q-schema.
+ """
+ return _qtargetitems.QTargetBeat
+
+
+
+
+[docs]
+class MeasurewiseQSchema(QSchema):
+ r"""
+ Measurewise q-schema.
+
+ Treats measures as its timestep unit.
+
+ >>> q_schema = nauert.MeasurewiseQSchema()
+
+ .. container:: example
+
+ Without arguments, it uses smart defaults:
+
+ >>> import pprint
+ >>> pprint.pprint(q_schema.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}
+
+ .. container:: example
+
+ Each time-step in a ``MeasurewiseQSchema`` is composed of four settings:
+
+ * ``search_tree``
+ * ``tempo``
+ * ``time_signature``
+ * ``use_full_measure``
+
+ These settings can be applied as global defaults for the schema via keyword
+ arguments, which persist until overridden:
+
+ >>> search_tree = nauert.UnweightedSearchTree({7: None})
+ >>> time_signature = abjad.TimeSignature((3, 4))
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+ >>> use_full_measure = True
+ >>> q_schema = nauert.MeasurewiseQSchema(
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... use_full_measure=use_full_measure,
+ ... )
+
+ All of these settings are self-descriptive, except for
+ ``use_full_measure``, which controls whether the measure is subdivided
+ by the ``quantize`` function into beats according to its time
+ signature.
+
+ If ``use_full_measure`` is ``False``, the time-step's measure will be
+ divided into units according to its time-signature. For example, a 4/4
+ measure will be divided into 4 units, each having a beatspan of 1/4.
+
+ On the other hand, if ``use_full_measure`` is set to ``True``, the
+ time-step's measure will not be subdivided into independent
+ quantization units. This usually results in full-measure tuplets.
+
+ .. container:: example
+
+ The computed value at any non-negative time-step can be found by
+ subscripting:
+
+ >>> index = 0
+ >>> for key, value in sorted(q_schema[index].items()):
+ ... print("{}:".format(key), value)
+ ...
+ search_tree: UnweightedSearchTree(definition={7: None})
+ tempo: MetronomeMark(...)
+ time_signature: TimeSignature(pair=(3, 4), hide=False, partial=None)
+ use_full_measure: True
+
+ >>> index = 1000
+ >>> for key, value in sorted(q_schema[index].items()):
+ ... print("{}:".format(key), value)
+ ...
+ search_tree: UnweightedSearchTree(definition={7: None})
+ tempo: MetronomeMark(...)
+ time_signature: TimeSignature(pair=(3, 4), hide=False, partial=None)
+ use_full_measure: True
+
+ .. container:: example
+
+ Per-time-step settings can be applied in a variety of ways.
+
+ Instantiating the schema via ``*arguments`` with a series of either
+ ``MeasurewiseQSchemaItem`` instances, or dictionaries which could be
+ used to instantiate ``MeasurewiseQSchemaItem`` instances, will apply
+ those settings sequentially, starting from time-step ``0``:
+
+ >>> a = {"search_tree": nauert.UnweightedSearchTree({2: None})}
+ >>> b = {"search_tree": nauert.UnweightedSearchTree({3: None})}
+ >>> c = {"search_tree": nauert.UnweightedSearchTree({5: None})}
+
+ >>> q_schema = nauert.MeasurewiseQSchema(a, b, c)
+
+ >>> q_schema[0]["search_tree"]
+ UnweightedSearchTree(definition={2: None})
+
+ >>> q_schema[1]["search_tree"]
+ UnweightedSearchTree(definition={3: None})
+
+ >>> q_schema[2]["search_tree"]
+ UnweightedSearchTree(definition={5: None})
+
+ >>> q_schema[1000]["search_tree"]
+ UnweightedSearchTree(definition={5: None})
+
+ .. container:: example
+
+ Similarly, instantiating the schema from a single dictionary,
+ consisting of integer:specification pairs, or a sequence via
+ ``*arguments`` of (integer, specification) pairs, allows for applying
+ settings to non-sequential time-steps:
+
+ >>> a = {"time_signature": abjad.TimeSignature((7, 32))}
+ >>> b = {"time_signature": abjad.TimeSignature((3, 4))}
+ >>> c = {"time_signature": abjad.TimeSignature((5, 8))}
+
+ >>> settings = {
+ ... 2: a,
+ ... 4: b,
+ ... 6: c,
+ ... }
+
+ >>> q_schema = nauert.MeasurewiseQSchema(settings)
+
+ >>> q_schema[0]["time_signature"]
+ TimeSignature(pair=(4, 4), hide=False, partial=None)
+
+ >>> q_schema[1]["time_signature"]
+ TimeSignature(pair=(4, 4), hide=False, partial=None)
+
+ >>> q_schema[2]["time_signature"]
+ TimeSignature(pair=(7, 32), hide=False, partial=None)
+
+ >>> q_schema[3]["time_signature"]
+ TimeSignature(pair=(7, 32), hide=False, partial=None)
+
+ >>> q_schema[4]["time_signature"]
+ TimeSignature(pair=(3, 4), hide=False, partial=None)
+
+ >>> q_schema[5]["time_signature"]
+ TimeSignature(pair=(3, 4), hide=False, partial=None)
+
+ >>> q_schema[6]["time_signature"]
+ TimeSignature(pair=(5, 8), hide=False, partial=None)
+
+ >>> q_schema[1000]["time_signature"]
+ TimeSignature(pair=(5, 8), hide=False, partial=None)
+
+ .. container:: example
+
+ The following is equivalent to the above schema definition:
+
+ >>> q_schema = nauert.MeasurewiseQSchema(
+ ... (2, {"time_signature": abjad.TimeSignature((7, 32))}),
+ ... (4, {"time_signature": abjad.TimeSignature((3, 4))}),
+ ... (6, {"time_signature": abjad.TimeSignature((5, 8))}),
+ ... )
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = (
+ "_items",
+ "_lookups",
+ "_search_tree",
+ "_tempo",
+ "_time_signature",
+ "_use_full_measure",
+ )
+
+ _keyword_argument_names = (
+ "search_tree",
+ "tempo",
+ "time_signature",
+ "use_full_measure",
+ )
+
+ ### INITIALIZER ###
+
+ def __init__(self, *arguments, **keywords):
+ search_tree = keywords.get("search_tree", _searchtrees.UnweightedSearchTree())
+ assert isinstance(search_tree, _searchtrees.SearchTree)
+ self._search_tree = search_tree
+ tempo = keywords.get("tempo", (abjad.Duration(1, 4), 60))
+ if isinstance(tempo, tuple):
+ tempo = abjad.MetronomeMark(*tempo)
+ self._tempo = tempo
+ time_signature = keywords.get("time_signature", (4, 4))
+ if isinstance(time_signature, abjad.TimeSignature):
+ self._time_signature = abjad.TimeSignature(time_signature.pair)
+ elif isinstance(time_signature, tuple):
+ self._time_signature = abjad.TimeSignature(time_signature)
+ else:
+ raise TypeError(time_signature)
+ self._use_full_measure = bool(keywords.get("use_full_measure"))
+ QSchema.__init__(self, *arguments, **keywords)
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(search_tree={self.search_tree!r},"
+ string += f" tempo={self.tempo!r}, time_signature={self.time_signature!r},"
+ string += f" use_full_measure={self.use_full_measure})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def item_class(self) -> type[_qschemaitems.MeasurewiseQSchemaItem]:
+ """
+ Gets item class of measurewise q-schema.
+ """
+ return _qschemaitems.MeasurewiseQSchemaItem
+
+ @property
+ def target_class(self) -> type[_qtargets.MeasurewiseQTarget]:
+ """
+ Gets target class of measurewise q-schema.
+ """
+ return _qtargets.MeasurewiseQTarget
+
+ @property
+ def target_item_class(self) -> type[_qtargetitems.QTargetMeasure]:
+ """
+ Gets target item class of measurewise q-schema.
+ """
+ return _qtargetitems.QTargetMeasure
+
+ @property
+ def time_signature(self) -> abjad.TimeSignature:
+ """
+ Gets default time signature of measurewise q-schema.
+
+ .. container:: example
+
+ >>> q_schema = nauert.MeasurewiseQSchema(
+ ... time_signature=abjad.TimeSignature((3, 4))
+ ... )
+ >>> q_schema.time_signature
+ TimeSignature(pair=(3, 4), hide=False, partial=None)
+
+ .. container:: example
+
+ If there are multiple time signatures in the QSchema, this returns
+ the default time signature of (4, 4).
+
+ >>> a = {"time_signature": abjad.TimeSignature((7, 32))}
+ >>> b = {"time_signature": abjad.TimeSignature((3, 4))}
+ >>> c = {"time_signature": abjad.TimeSignature((5, 8))}
+
+ >>> settings = {
+ ... 2: a,
+ ... 4: b,
+ ... 6: c,
+ ... }
+
+ >>> q_schema = nauert.MeasurewiseQSchema(settings)
+ >>> q_schema.time_signature
+ TimeSignature(pair=(4, 4), hide=False, partial=None)
+
+ """
+ return self._time_signature
+
+ @property
+ def use_full_measure(self) -> bool:
+ """
+ Is true when class uses full-measure-as-beatspan default.
+ """
+ return self._use_full_measure
+
+
+import abc
+import typing
+
+import abjad
+
+from . import qeventproxy as _qeventproxy
+from . import qevents as _qevents
+from . import qgrid as _qgrid
+from . import quantizationjob as _quantizationjob
+from . import searchtrees as _searchtrees
+
+
+
+[docs]
+class QTargetItem(abc.ABC):
+ """
+ Abstract class for QTargetBeat and QTargetMeasure.
+ """
+
+ @abc.abstractproperty
+ def offset_in_ms(self) -> abjad.Offset:
+ raise NotImplementedError
+
+ @abc.abstractproperty
+ def duration_in_ms(self) -> abjad.Duration:
+ raise NotImplementedError
+
+
+
+
+[docs]
+class QTargetBeat(QTargetItem):
+ """
+ Q-target beat.
+
+ Represents a single beat in a quantization target.
+
+ .. container:: example
+
+ >>> beatspan = abjad.Duration(1, 8)
+ >>> offset_in_ms = abjad.Offset(1500)
+ >>> search_tree = nauert.UnweightedSearchTree({3: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+ >>> q_target_beat = nauert.QTargetBeat(
+ ... beatspan=beatspan,
+ ... offset_in_ms=offset_in_ms,
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... )
+
+ Not composer-safe.
+
+ Used internally by the ``quantize`` function.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = (
+ "_beatspan",
+ "_grouping",
+ "_offset_in_ms",
+ "_q_events",
+ "_q_grid",
+ "_q_grids",
+ "_search_tree",
+ "_tempo",
+ )
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ beatspan: abjad.Duration = abjad.Duration(0),
+ offset_in_ms: abjad.Offset = abjad.Offset(0),
+ search_tree: _searchtrees.SearchTree | None = None,
+ tempo: abjad.MetronomeMark = abjad.MetronomeMark(abjad.Duration(1, 4), 60),
+ ):
+ assert isinstance(beatspan, abjad.Duration), repr(beatspan)
+ assert isinstance(offset_in_ms, abjad.Offset), repr(offset_in_ms)
+ if search_tree is None:
+ search_tree = _searchtrees.UnweightedSearchTree()
+ assert isinstance(search_tree, _searchtrees.SearchTree)
+ assert isinstance(tempo, abjad.MetronomeMark), repr(tempo)
+ assert not tempo.is_imprecise
+ q_events: list[_qevents.QEvent] = []
+ q_grids: tuple[_qgrid.QGrid, ...] = ()
+ self._beatspan = beatspan
+ self._offset_in_ms = offset_in_ms
+ self._q_events = q_events
+ self._q_grid: _qgrid.QGrid | None = None
+ self._q_grids = q_grids
+ self._search_tree = search_tree
+ self._tempo = tempo
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(
+ self, job_id: int
+ ) -> typing.Optional[_quantizationjob.QuantizationJob]:
+ """
+ Calls q-target beat.
+ """
+ if not self.q_events:
+ return None
+ assert all(isinstance(x, _qevents.QEvent) for x in self.q_events)
+ q_event_proxies = []
+ for q_event in self.q_events:
+ q_event_proxy = _qeventproxy.QEventProxy(
+ q_event,
+ self.offset_in_ms,
+ self.offset_in_ms + self.duration_in_ms,
+ )
+ q_event_proxies.append(q_event_proxy)
+ return _quantizationjob.QuantizationJob(
+ job_id, self.search_tree, q_event_proxies
+ )
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(beatspan={self.beatspan!r},"
+ string += f" offset_in_ms={self.offset_in_ms!r},"
+ string += f" search_tree={self.search_tree!r}, tempo={self.tempo!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def beatspan(self) -> abjad.Duration:
+ """
+ Beatspan of q-target beat.
+
+ >>> beatspan = abjad.Duration(1, 8)
+ >>> offset_in_ms = abjad.Offset(1500)
+ >>> search_tree = nauert.UnweightedSearchTree({3: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+
+ >>> q_target_beat = nauert.QTargetBeat(
+ ... beatspan=beatspan,
+ ... offset_in_ms=offset_in_ms,
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... )
+
+ >>> q_target_beat.beatspan
+ Duration(1, 8)
+
+ """
+ return self._beatspan
+
+ @property
+ def duration_in_ms(self) -> abjad.Duration:
+ """
+ Duration in milliseconds of the q-target beat.
+
+ >>> beatspan = abjad.Duration(1, 8)
+ >>> offset_in_ms = abjad.Offset(1500)
+ >>> search_tree = nauert.UnweightedSearchTree({3: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+
+ >>> q_target_beat = nauert.QTargetBeat(
+ ... beatspan=beatspan,
+ ... offset_in_ms=offset_in_ms,
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... )
+
+ >>> q_target_beat.duration_in_ms
+ Duration(3750, 7)
+
+ """
+ return self.tempo.duration_to_milliseconds(self.beatspan)
+
+ @property
+ def offset_in_ms(self) -> abjad.Offset:
+ """
+ Offset in milliseconds of q-target beat.
+
+ >>> beatspan = abjad.Duration(1, 8)
+ >>> offset_in_ms = abjad.Offset(1500)
+ >>> search_tree = nauert.UnweightedSearchTree({3: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+
+ >>> q_target_beat = nauert.QTargetBeat(
+ ... beatspan=beatspan,
+ ... offset_in_ms=offset_in_ms,
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... )
+
+ >>> q_target_beat.offset_in_ms
+ Offset((1500, 1))
+
+ """
+ return self._offset_in_ms
+
+ @property
+ def q_events(self) -> list[_qevents.QEvent]:
+ """
+ A list for storing ``QEventProxy`` instances.
+
+ Used internally by the ``quantize`` function.
+ """
+ return self._q_events
+
+ @property
+ def q_grid(self) -> typing.Optional[_qgrid.QGrid]:
+ """
+ The ``QGrid`` instance selected by a ``Heuristic``.
+
+ Used internally by the ``quantize`` function.
+ """
+ return self._q_grid
+
+ @property
+ def q_grids(self) -> tuple[_qgrid.QGrid, ...]:
+ """
+ A tuple of ``QGrids`` generated by a ``QuantizationJob``.
+
+ Used internally by the ``quantize`` function.
+ """
+ return self._q_grids
+
+ @property
+ def search_tree(
+ self,
+ ) -> _searchtrees.SearchTree | _searchtrees.UnweightedSearchTree:
+ """
+ Search tree of q-target beat.
+
+ >>> beatspan = abjad.Duration(1, 8)
+ >>> offset_in_ms = abjad.Offset(1500)
+ >>> search_tree = nauert.UnweightedSearchTree({3: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+
+ >>> q_target_beat = nauert.QTargetBeat(
+ ... beatspan=beatspan,
+ ... offset_in_ms=offset_in_ms,
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... )
+
+ >>> q_target_beat.search_tree
+ UnweightedSearchTree(definition={3: None})
+
+ """
+ return self._search_tree
+
+ @property
+ def tempo(self) -> abjad.MetronomeMark:
+ r"""
+ Gets tempo of q-target beat.
+
+ >>> beatspan = abjad.Duration(1, 8)
+ >>> offset_in_ms = abjad.Offset(1500)
+ >>> search_tree = nauert.UnweightedSearchTree({3: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+ >>> q_target_beat = nauert.QTargetBeat(
+ ... beatspan=beatspan,
+ ... offset_in_ms=offset_in_ms,
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... )
+ >>> abjad.lilypond(q_target_beat.tempo)
+ '\\tempo 4=56'
+
+ """
+ return self._tempo
+
+
+
+
+[docs]
+class QTargetMeasure(QTargetItem):
+ """
+ Q-target measure.
+
+ Represents a single measure in a measurewise quantization target.
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ .. container:: example
+
+ ``QTargetMeasures`` group ``QTargetBeats``:
+
+ >>> for q_target_beat in q_target_measure.beats:
+ ... print(q_target_beat.offset_in_ms, q_target_beat.duration_in_ms)
+ 1000 1000
+ 2000 1000
+ 3000 1000
+ 4000 1000
+
+ .. container:: example
+
+ If ``use_full_measure`` is set, the ``QTargetMeasure`` will only ever
+ contain a single ``QTargetBeat`` instance:
+
+ >>> another_q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... use_full_measure=True,
+ ... )
+
+ >>> for q_target_beat in another_q_target_measure.beats:
+ ... print(q_target_beat.offset_in_ms, q_target_beat.duration_in_ms)
+ 1000 4000
+
+ Not composer-safe.
+
+ Used internally by the ``quantize`` function.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = (
+ "_beats",
+ "_offset_in_ms",
+ "_search_tree",
+ "_tempo",
+ "_time_signature",
+ "_use_full_measure",
+ )
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ offset_in_ms: abjad.Offset = abjad.Offset(0),
+ search_tree: _searchtrees.SearchTree | None = None,
+ time_signature: abjad.TimeSignature = abjad.TimeSignature((4, 4)),
+ tempo: abjad.MetronomeMark = abjad.MetronomeMark(abjad.Duration(4, 4)),
+ use_full_measure: bool = False,
+ ):
+ assert isinstance(offset_in_ms, abjad.Offset), repr(offset_in_ms)
+ if search_tree is None:
+ search_tree = _searchtrees.UnweightedSearchTree()
+ assert isinstance(search_tree, _searchtrees.SearchTree)
+ assert isinstance(time_signature, abjad.TimeSignature), repr(time_signature)
+ assert isinstance(tempo, abjad.MetronomeMark), repr(tempo)
+ assert not tempo.is_imprecise
+ _time_signature = abjad.TimeSignature(time_signature.pair)
+ use_full_measure = bool(use_full_measure)
+ beats = []
+ if use_full_measure:
+ beatspan = _time_signature.duration
+ beat = QTargetBeat(
+ beatspan=beatspan,
+ offset_in_ms=offset_in_ms,
+ search_tree=search_tree,
+ tempo=tempo,
+ )
+ beats.append(beat)
+ else:
+ beatspan = abjad.Duration(1, _time_signature.denominator)
+ current_offset_in_ms = offset_in_ms
+ beatspan_duration_in_ms = tempo.duration_to_milliseconds(beatspan)
+ for i in range(_time_signature.numerator):
+ beat = QTargetBeat(
+ beatspan=beatspan,
+ offset_in_ms=current_offset_in_ms,
+ search_tree=search_tree,
+ tempo=tempo,
+ )
+ beats.append(beat)
+ current_offset_in_ms += beatspan_duration_in_ms
+ self._beats = tuple(beats)
+ self._offset_in_ms = offset_in_ms
+ self._search_tree = search_tree
+ self._tempo = tempo
+ self._time_signature = _time_signature
+ self._use_full_measure = use_full_measure
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(offset_in_ms={self.offset_in_ms!r},"
+ string += f" search_tree={self.search_tree!r}, tempo={self.tempo!r},"
+ string += f" use_full_measure={self.use_full_measure!r})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def beats(self) -> tuple:
+ """
+ Gets the tuple of ``QTargetBeats`` contained by the ``QTargetMeasure``.
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ >>> for q_target_beat in q_target_measure.beats:
+ ... q_target_beat.offset_in_ms
+ ...
+ Offset((1000, 1))
+ Offset((2000, 1))
+ Offset((3000, 1))
+ Offset((4000, 1))
+
+ """
+ return self._beats
+
+ @property
+ def duration_in_ms(self) -> abjad.Duration:
+ """
+ Gets duration in milliseconds of the ``QTargetMeasure``:
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ >>> q_target_measure.duration_in_ms
+ Duration(4000, 1)
+
+ """
+ return self.tempo.duration_to_milliseconds(self.time_signature.duration)
+
+ @property
+ def offset_in_ms(self) -> abjad.Offset:
+ """
+ Gets offset in milliseconds of the ``QTargetMeasure``:
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ >>> q_target_measure.offset_in_ms
+ Offset((1000, 1))
+
+ """
+ return self._offset_in_ms
+
+ @property
+ def search_tree(self) -> _searchtrees.SearchTree:
+ """
+ Gets the search tree of ``QTargetMeasure``:
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ >>> q_target_measure.search_tree
+ UnweightedSearchTree(definition={2: None})
+
+ """
+ return self._search_tree
+
+ @property
+ def tempo(self) -> abjad.MetronomeMark:
+ r"""
+ Gets the tempo of ``QTargetMeasure``:
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ >>> abjad.lilypond(q_target_measure.tempo)
+ '\\tempo 4=60'
+
+ """
+ return self._tempo
+
+ @property
+ def time_signature(self) -> abjad.TimeSignature:
+ """
+ Gets the time signature of the ``QTargetMeasure``:
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ >>> q_target_measure.time_signature
+ TimeSignature(pair=(4, 4), hide=False, partial=None)
+
+ """
+ return self._time_signature
+
+ @property
+ def use_full_measure(self) -> bool:
+ """
+ Is true when ``QTargetMeasure`` uses full measures:
+
+ .. container:: example
+
+ >>> search_tree = nauert.UnweightedSearchTree({2: None})
+ >>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+ >>> time_signature = abjad.TimeSignature((4, 4))
+
+ >>> q_target_measure = nauert.QTargetMeasure(
+ ... offset_in_ms=abjad.Offset(1000),
+ ... search_tree=search_tree,
+ ... tempo=tempo,
+ ... time_signature=time_signature,
+ ... )
+
+ >>> q_target_measure.use_full_measure
+ False
+
+ """
+ return self._use_full_measure
+
+
+import abc
+import bisect
+import copy
+import typing
+
+import abjad
+
+from . import attackpointoptimizers as _attackpointoptimizers
+from . import gracehandlers as _gracehandlers
+from . import heuristics as _heuristics
+from . import jobhandlers as _jobhandlers
+from . import qeventproxy as _qeventproxy
+from . import qevents as _qevents
+from . import qeventsequence as _qeventsequence
+from . import qtargetitems as _qtargetitems
+
+
+
+[docs]
+class QTarget(abc.ABC):
+ """
+ Q-target.
+
+ ``QTarget`` is created by a concrete ``QSchema`` instance.
+
+ ``QTarget`` represents the mold into which the timepoints contained by a
+ ``QSequence`` instance will be poured, as structured by that ``QSchema``
+ instance.
+
+ Not composer-safe.
+
+ Used internally by the ``quantize`` function.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_items",)
+
+ ### INITIALIZATION ###
+
+ def __init__(self, items: typing.Sequence[_qtargetitems.QTargetItem] | None = None):
+ items = [] if items is None else items
+ assert all(isinstance(x, self.item_class) for x in items)
+ self._items: typing.Sequence[_qtargetitems.QTargetItem] = ()
+ if len(items) > 0:
+ self._items = tuple(sorted(items, key=lambda x: x.offset_in_ms))
+
+ ### SPECIAL METHODS ###
+
+ # TODO: typehint
+
+[docs]
+ def __call__(
+ self,
+ q_event_sequence: _qeventsequence.QEventSequence,
+ grace_handler: _gracehandlers.GraceHandler | None = None,
+ heuristic: _heuristics.Heuristic | None = None,
+ job_handler: _jobhandlers.JobHandler | None = None,
+ attack_point_optimizer: (
+ _attackpointoptimizers.AttackPointOptimizer | None
+ ) = None,
+ attach_tempos: bool = True,
+ ):
+ """
+ Calls q-target.
+ """
+ assert isinstance(q_event_sequence, _qeventsequence.QEventSequence)
+ if grace_handler is None:
+ grace_handler = _gracehandlers.ConcatenatingGraceHandler()
+ assert isinstance(grace_handler, _gracehandlers.GraceHandler)
+ if heuristic is None:
+ heuristic = _heuristics.DistanceHeuristic()
+ assert isinstance(heuristic, _heuristics.Heuristic)
+ if job_handler is None:
+ job_handler = _jobhandlers.SerialJobHandler()
+ assert isinstance(job_handler, _jobhandlers.JobHandler)
+ if attack_point_optimizer is None:
+ attack_point_optimizer = _attackpointoptimizers.NaiveAttackPointOptimizer()
+ assert isinstance(
+ attack_point_optimizer, _attackpointoptimizers.AttackPointOptimizer
+ )
+ if isinstance(self, BeatwiseQTarget) and isinstance(
+ attack_point_optimizer,
+ _attackpointoptimizers.MeasurewiseAttackPointOptimizer,
+ ):
+ message = "{} is not supposed to be used together with {}.".format(
+ self.__class__.__name__, attack_point_optimizer.__class__.__name__
+ )
+ raise TypeError(message)
+ # parcel QEvents out to each beat
+ beats = self.beats
+ offsets = sorted([beat.offset_in_ms for beat in beats])
+ for q_event in q_event_sequence:
+ index = bisect.bisect(offsets, q_event.offset) - 1
+ beat = beats[index]
+ beat.q_events.append(q_event)
+ # generate QuantizationJobs and process with the JobHandler
+ jobs = [beat(i) for i, beat in enumerate(beats)]
+ jobs = [job for job in jobs if job]
+ jobs = job_handler(jobs)
+ for job in jobs:
+ assert job is not None
+ beats[job.job_id]._q_grids = job.q_grids
+ # select the best QGrid for each beat, according to the Heuristic
+ beats = heuristic(beats)
+ # shift QEvents attached to each QGrid's "next downbeat"
+ # over to the next QGrid's first leaf - the real downbeat
+ orphaned_q_events_proxies = self._shift_downbeat_q_events_to_next_q_grid()
+ # TODO: handle a final QGrid with QEvents attached to its next_downbeat
+ # TODO: remove a final QGrid with no QEvents
+ self._regroup_q_grid_with_unnecessary_divisions()
+ # convert the QGrid representation into notation,
+ # handling grace-note behavior with the GraceHandler
+ notation = self._notate(
+ attach_tempos=attach_tempos,
+ attack_point_optimizer=attack_point_optimizer,
+ grace_handler=grace_handler,
+ )
+ handle_orphaned_q_events = getattr(
+ grace_handler, "handle_orphaned_q_event_proxies", None
+ )
+ if callable(handle_orphaned_q_events) and orphaned_q_events_proxies:
+ last_leaf = abjad.get.leaf(notation, -1)
+ handle_orphaned_q_events(last_leaf, orphaned_q_events_proxies)
+ return notation
+
+
+ ### PRIVATE METHODS ###
+
+ @abc.abstractmethod
+ def _notate(
+ self,
+ grace_handler: _gracehandlers.GraceHandler,
+ attack_point_optimizer: _attackpointoptimizers.AttackPointOptimizer,
+ attach_tempos: bool = True,
+ ) -> abjad.Voice:
+ raise NotImplementedError
+
+ def _notate_leaves(
+ self,
+ grace_handler: _gracehandlers.GraceHandler,
+ voice: abjad.Voice | None = None,
+ ):
+ for leaf in abjad.iterate.leaves(voice):
+ if leaf._has_indicator(dict):
+ annotation = leaf._get_indicator(dict)
+ q_events = annotation["q_events"]
+ pitches, attachments, grace_container = grace_handler(q_events)
+ new_leaf: abjad.Leaf
+ if not pitches:
+ new_leaf = abjad.Rest(leaf)
+ elif 1 < len(pitches):
+ new_leaf = abjad.Chord(leaf)
+ new_leaf.written_pitches = pitches
+ else:
+ new_leaf = abjad.Note(leaf)
+ new_leaf.written_pitch = pitches[0]
+ if attachments is not None:
+ abjad.annotate(new_leaf, "q_event_attachments", attachments)
+ if grace_container:
+ abjad.attach(grace_container, new_leaf)
+ abjad.mutate.replace(leaf, new_leaf)
+ if not isinstance(new_leaf, abjad.Rest):
+ abjad.annotate(new_leaf, "tie_to_next", True)
+ elif abjad.get.indicator(new_leaf, abjad.Tie):
+ abjad.detach(abjad.Tie, new_leaf)
+ else:
+ previous_leaf = abjad._iterlib._get_leaf(leaf, -1)
+ if isinstance(previous_leaf, abjad.Rest):
+ new_leaf = type(previous_leaf)(leaf.written_duration)
+ elif isinstance(previous_leaf, abjad.Note):
+ new_leaf = type(previous_leaf)(
+ previous_leaf.written_pitch, leaf.written_duration
+ )
+ else:
+ new_leaf = type(previous_leaf)(
+ previous_leaf.written_pitches, leaf.written_duration
+ )
+ abjad.mutate.replace(leaf, new_leaf)
+ if abjad.get.annotation(previous_leaf, "tie_to_next") is True:
+ leaves = [previous_leaf, new_leaf]
+ abjad.tie(leaves)
+ abjad.annotate(new_leaf, "tie_to_next", True)
+ if leaf._has_indicator(abjad.MetronomeMark):
+ tempo = leaf._get_indicator(abjad.MetronomeMark)
+ abjad.detach(abjad.MetronomeMark, leaf)
+ abjad.detach(abjad.MetronomeMark, new_leaf)
+ abjad.attach(tempo, new_leaf)
+ if leaf._has_indicator(abjad.TimeSignature):
+ time_signature = leaf._get_indicator(abjad.TimeSignature)
+ abjad.detach(abjad.TimeSignature, leaf)
+ abjad.detach(abjad.TimeSignature, new_leaf)
+ abjad.attach(time_signature, new_leaf)
+
+ def _regroup_q_grid_with_unnecessary_divisions(self):
+ for beat in self.beats:
+ beat.q_grid.regroup_leaves_with_unencessary_divisions()
+
+ def _shift_downbeat_q_events_to_next_q_grid(self) -> list[_qeventproxy.QEventProxy]:
+ beats = self.beats
+ assert beats[-1].q_grid is not None
+ for one, two in abjad.sequence.nwise(beats):
+ one_q_events = one.q_grid.next_downbeat.q_event_proxies
+ two_q_events = two.q_grid.leaves[0].q_event_proxies
+ while one_q_events:
+ two_q_events.insert(0, one_q_events.pop())
+ return [
+ proxy
+ for proxy in beats[-1].q_grid.next_downbeat.q_event_proxies
+ if not isinstance(proxy.q_event, _qevents.TerminalQEvent)
+ ]
+
+ ### PUBLIC PROPERTIES ###
+
+ @abc.abstractproperty
+ def beats(self) -> tuple[_qtargetitems.QTargetBeat, ...]:
+ """
+ Gets beats of q-target.
+ """
+ raise NotImplementedError
+
+ @property
+ def duration_in_ms(self) -> abjad.Duration:
+ """
+ Gets duration of q-target in milliseconds.
+ """
+ last_item = self._items[-1]
+ return last_item.offset_in_ms + last_item.duration_in_ms
+
+ @abc.abstractproperty
+ def item_class(self):
+ """
+ Gets item class of q-target.
+ """
+ raise NotImplementedError
+
+ @property
+ def items(self):
+ """
+ Gets items of q-target.
+ """
+ return self._items
+
+
+
+
+[docs]
+class BeatwiseQTarget(QTarget):
+ """
+ Beatwise q-target.
+
+ Not composer-safe.
+
+ Used internally by the ``quantize`` function.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### INITIALIZATION ###
+
+ def __init__(self, items: typing.Sequence[_qtargetitems.QTargetBeat] | None = None):
+ items = [] if items is None else items
+ self._items: typing.Sequence[_qtargetitems.QTargetBeat]
+ super().__init__(items)
+
+ ### PRIVATE METHODS ###
+
+ def _notate(
+ self,
+ grace_handler: _gracehandlers.GraceHandler,
+ attack_point_optimizer: _attackpointoptimizers.AttackPointOptimizer,
+ attach_tempos: bool = True,
+ ) -> abjad.Voice:
+ voice = abjad.Voice()
+ # generate the first
+ beat = self._items[0]
+ assert isinstance(beat, _qtargetitems.QTargetBeat) and beat.q_grid is not None
+ components = beat.q_grid(beat.beatspan)
+ voice.extend(components)
+ if attach_tempos:
+ attachment_target: abjad.Component = components[0]
+ leaves = abjad.select.leaves(attachment_target)
+ if isinstance(attachment_target, abjad.Container):
+ attachment_target = leaves[0]
+ tempo = copy.deepcopy(beat.tempo)
+ abjad.attach(tempo, attachment_target)
+ # generate the rest pairwise, comparing tempi
+ for beat_one, beat_two in abjad.sequence.nwise(self.items):
+ components = beat_two.q_grid(beat_two.beatspan)
+ voice.extend(components)
+ if (beat_two.tempo != beat_one.tempo) and attach_tempos:
+ attachment_target = components[0]
+ leaves = abjad.select.leaves(attachment_target)
+ if isinstance(attachment_target, abjad.Container):
+ attachment_target = leaves[0]
+ tempo = copy.deepcopy(beat_two.tempo)
+ abjad.attach(tempo, attachment_target)
+ # apply logical ties, pitches, grace containers
+ self._notate_leaves(grace_handler=grace_handler, voice=voice)
+ # partition logical ties in voice
+ attack_point_optimizer(voice)
+ return voice
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def beats(self) -> tuple[_qtargetitems.QTargetBeat, ...]:
+ """
+ Gets beats of beatwise q-target.
+ """
+ return tuple(self._items)
+
+ @property
+ def item_class(self) -> type[_qtargetitems.QTargetBeat]:
+ """
+ Gets item class of beatwise q-target.
+ """
+ return _qtargetitems.QTargetBeat
+
+
+
+
+[docs]
+class MeasurewiseQTarget(QTarget):
+ """
+ Measurewise quantization target.
+
+ Not composer-safe.
+
+ Used internally by the ``quantize`` function.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### INITIALIZATION ###
+
+ def __init__(
+ self, items: typing.Sequence[_qtargetitems.QTargetMeasure] | None = None
+ ):
+ super().__init__(items)
+
+ ### PRIVATE METHODS ###
+
+ def _notate(
+ self,
+ grace_handler: _gracehandlers.GraceHandler,
+ attack_point_optimizer: _attackpointoptimizers.AttackPointOptimizer,
+ attach_tempos: bool = True,
+ ) -> abjad.Voice:
+ voice = abjad.Voice()
+ # generate the first
+ q_target_measure = self._items[0]
+ assert isinstance(q_target_measure, _qtargetitems.QTargetMeasure)
+ time_signature = q_target_measure.time_signature
+ measure = abjad.Container()
+ for beat in q_target_measure.beats:
+ components = beat.q_grid(beat.beatspan)
+ measure.extend(components)
+ voice.append(measure)
+ leaf = abjad.get.leaf(measure, 0)
+ abjad.attach(time_signature, leaf)
+ if attach_tempos:
+ tempo = copy.deepcopy(q_target_measure.tempo)
+ leaf = abjad.get.leaf(measure, 0)
+ abjad.attach(tempo, leaf)
+ # generate the rest pairwise, comparing tempi
+ pairs = abjad.sequence.nwise(self.items)
+ for q_target_measure_one, q_target_measure_two in pairs:
+ measure = abjad.Container()
+ voice.append(measure)
+ for beat in q_target_measure_two.beats:
+ measure.extend(beat.q_grid(beat.beatspan))
+ if (
+ q_target_measure_two.time_signature
+ != q_target_measure_one.time_signature
+ ):
+ time_signature = q_target_measure_two.time_signature
+ leaf = abjad.get.leaf(measure, 0)
+ abjad.attach(time_signature, leaf)
+ if (
+ q_target_measure_two.tempo != q_target_measure_one.tempo
+ ) and attach_tempos:
+ tempo = copy.deepcopy(q_target_measure_two.tempo)
+ leaf = abjad.get.leaf(measure, 0)
+ abjad.attach(tempo, leaf)
+ # apply logical ties, pitches, grace containers
+ self._notate_leaves(grace_handler=grace_handler, voice=voice)
+ # partition logical ties in each measure
+ for index, measure in enumerate(voice):
+ if isinstance(
+ attack_point_optimizer,
+ _attackpointoptimizers.MeasurewiseAttackPointOptimizer,
+ ):
+ # then we need to pass the time signature of each measure
+ attack_point_optimizer(measure, self.items[index].time_signature)
+ else:
+ attack_point_optimizer(measure)
+ return voice
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def beats(self) -> tuple[_qtargetitems.QTargetBeat, ...]:
+ """
+ Gets beats of measurewise q-target.
+ """
+ return tuple([beat for item in self.items for beat in item.beats])
+
+ @property
+ def item_class(self) -> type[_qtargetitems.QTargetMeasure]:
+ """
+ Gets item class of measurewise q-target.
+ """
+ return _qtargetitems.QTargetMeasure
+
+
+import typing
+
+from . import qeventproxy as _qeventproxy
+from . import qgrid as _qgrid
+from . import searchtrees as _searchtrees
+
+
+
+[docs]
+class QuantizationJob:
+ r"""
+ Quantization job.
+
+ Copiable, picklable class for generating all ``QGrids`` which are valid
+ under a given ``SearchTree`` for a sequence of ``QEventProxies``.
+
+ .. container:: example
+
+ >>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0, 1])
+ >>> q_event_b = nauert.SilentQEvent(abjad.Offset(500))
+ >>> q_event_c = nauert.PitchedQEvent(abjad.Offset(750), [3, 7])
+ >>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+ >>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.5))
+ >>> proxy_c = nauert.QEventProxy(q_event_c, abjad.Offset(0.75))
+
+ >>> definition = {2: {2: None}, 3: None, 5: None}
+ >>> search_tree = nauert.UnweightedSearchTree(definition)
+
+ >>> job = nauert.QuantizationJob(
+ ... 1, search_tree, [proxy_a, proxy_b, proxy_c])
+
+ .. container:: example
+
+ ``QuantizationJob`` generates ``QGrids`` when called, and stores those
+ ``QGrids`` on its ``q_grids`` attribute, allowing them to be recalled
+ later, even if pickled:
+
+ >>> job()
+ >>> for q_grid in job.q_grids:
+ ... print(q_grid.rtm_format)
+ 1
+ (1 (1 1 1 1 1))
+ (1 (1 1 1))
+ (1 (1 1))
+ (1 ((1 (1 1)) (1 (1 1))))
+
+ ``QuantizationJob`` is intended to be useful in multiprocessing-enabled
+ environments.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_job_id", "_q_event_proxies", "_q_grids", "_search_tree")
+
+ ### INITIALIZER ###
+
+ def __init__(
+ self,
+ job_id: int = 1,
+ search_tree: _searchtrees.SearchTree | None = None,
+ q_event_proxies: typing.Sequence[_qeventproxy.QEventProxy] | None = None,
+ q_grids: typing.Sequence[_qgrid.QGrid] | None = None,
+ ):
+ search_tree = search_tree or _searchtrees.UnweightedSearchTree()
+ q_event_proxies = q_event_proxies or []
+ assert isinstance(search_tree, _searchtrees.SearchTree)
+ assert all(isinstance(x, _qeventproxy.QEventProxy) for x in q_event_proxies)
+ self._job_id = job_id
+ self._search_tree = search_tree
+ self._q_event_proxies = tuple(q_event_proxies)
+ self._q_grids: tuple[_qgrid.QGrid, ...]
+ if q_grids is None:
+ self._q_grids = ()
+ else:
+ assert all(isinstance(x, _qgrid.QGrid) for x in q_grids)
+ self._q_grids = tuple(q_grids)
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(self) -> None:
+ """
+ Calls quantization job.
+ """
+ # print('XXX')
+ # print(format(self.q_event_proxies[0]))
+ q_grid = _qgrid.QGrid()
+ q_grid.fit_q_events(self.q_event_proxies)
+ # print(format(q_grid))
+ old_q_grids = []
+ new_q_grids = [q_grid]
+ while new_q_grids:
+ q_grid = new_q_grids.pop()
+ search_results = self.search_tree(q_grid)
+ # print q_grid.rtm_format
+ # for x in search_results:
+ # print '\t', x.rtm_format
+ new_q_grids.extend(search_results)
+ old_q_grids.append(q_grid)
+ # for q_grid in old_q_grids:
+ # print('\t', q_grid)
+ # print()
+
+ self._q_grids = tuple(old_q_grids)
+
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true when `argument` is a quantization job with job ID, search tree,
+ q-event proxies and q-grids equal to those of this quantization job.
+ Otherwise false.
+ """
+ if type(self) is type(argument):
+ if self.job_id == argument.job_id:
+ if self.search_tree == argument.search_tree:
+ if self.q_event_proxies == argument.q_event_proxies:
+ if self.q_grids == argument.q_grids:
+ return True
+ return False
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes quantization job.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(QuantizationJob, self).__hash__()
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets repr.
+ """
+ string = f"{type(self).__name__}(job_id={self.job_id!r},"
+ string += f" search_tree={self.search_tree!r},"
+ string += f" q_event_proxies={self.q_event_proxies!r}, q_grids={self.q_grids})"
+ return string
+
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def job_id(self) -> int:
+ """
+ Gets the job id of the ``QuantizationJob``.
+
+ Only meaningful when the job is processed via multiprocessing, as the
+ job id is necessary to reconstruct the order of jobs.
+ """
+ return self._job_id
+
+ @property
+ def q_event_proxies(self) -> tuple[_qeventproxy.QEventProxy, ...]:
+ r"""
+ Gets the ``QEventProxies`` the ``QuantizationJob`` was instantiated with.
+
+ >>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0, 1])
+ >>> q_event_b = nauert.SilentQEvent(abjad.Offset(500))
+ >>> q_event_c = nauert.PitchedQEvent(abjad.Offset(750), [3, 7])
+ >>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+ >>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.5))
+ >>> proxy_c = nauert.QEventProxy(q_event_c, abjad.Offset(0.75))
+
+ >>> definition = {2: {2: None}, 3: None, 5: None}
+ >>> search_tree = nauert.UnweightedSearchTree(definition)
+
+ >>> job = nauert.QuantizationJob(
+ ... 1, search_tree, [proxy_a, proxy_b, proxy_c])
+ >>> job()
+
+ >>> for q_event_proxy in job.q_event_proxies:
+ ... print(type(q_event_proxy.q_event).__name__)
+ ...
+ PitchedQEvent
+ SilentQEvent
+ PitchedQEvent
+
+ """
+ return self._q_event_proxies
+
+ @property
+ def q_grids(self) -> tuple[_qgrid.QGrid, ...]:
+ r"""
+ Gets generated ``QGrids``.
+
+ >>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0, 1])
+ >>> q_event_b = nauert.SilentQEvent(abjad.Offset(500))
+ >>> q_event_c = nauert.PitchedQEvent(abjad.Offset(750), [3, 7])
+ >>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+ >>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.5))
+ >>> proxy_c = nauert.QEventProxy(q_event_c, abjad.Offset(0.75))
+ >>> definition = {2: {2: None}, 3: None, 5: None}
+ >>> search_tree = nauert.UnweightedSearchTree(definition)
+ >>> job = nauert.QuantizationJob(1, search_tree, [proxy_a, proxy_b, proxy_c])
+ >>> job()
+
+ >>> for q_grid in job.q_grids:
+ ... print(q_grid.rtm_format)
+ 1
+ (1 (1 1 1 1 1))
+ (1 (1 1 1))
+ (1 (1 1))
+ (1 ((1 (1 1)) (1 (1 1))))
+
+ """
+ return self._q_grids
+
+ @property
+ def search_tree(self) -> _searchtrees.SearchTree:
+ """
+ Gets search tree ``QuantizationJob`` was instantiated with.
+ """
+ return self._search_tree
+
+
+import abjad
+
+from . import attackpointoptimizers as _attackpointoptimizers
+from . import gracehandlers as _gracehandlers
+from . import heuristics as _heuristics
+from . import jobhandlers as _jobhandlers
+from . import qeventsequence as _qeventsequence
+from . import qschemas as _qschemas
+
+
+
+[docs]
+def quantize(
+ q_event_sequence: _qeventsequence.QEventSequence,
+ q_schema: _qschemas.QSchema | None = None,
+ grace_handler: _gracehandlers.GraceHandler | None = None,
+ heuristic: _heuristics.Heuristic | None = None,
+ job_handler: _jobhandlers.JobHandler | None = None,
+ attack_point_optimizer: _attackpointoptimizers.AttackPointOptimizer | None = None,
+ attach_tempos: bool = True,
+) -> abjad.Voice:
+ r"""
+ Quantizer function.
+
+ Quantizes sequences of attack-points, encapsulated by ``QEventSequences``,
+ into score trees.
+
+ .. container:: example
+
+ >>> durations = [1000] * 8
+ >>> pitches = range(8)
+ >>> pairs = tuple(zip(durations, pitches, strict=True))
+ >>> method = nauert.QEventSequence.from_millisecond_pitch_pairs
+ >>> q_event_sequence = method(pairs)
+
+ .. container:: example
+
+ Quantization defaults to outputting into a 4/4, quarter=60 musical structure:
+
+ >>> result = nauert.quantize(q_event_sequence)
+ >>> staff = abjad.Staff([result])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(score)
+ >>> print(string)
+ \new Score
+ <<
+ \new Staff
+ {
+ \new Voice
+ {
+ {
+ \tempo 4=60
+ \time 4/4
+ c'4
+ cs'4
+ d'4
+ ef'4
+ }
+ {
+ e'4
+ f'4
+ fs'4
+ g'4
+ }
+ }
+ }
+ >>
+
+ .. container:: example
+
+ However, the behavior of the ``quantize`` function can be modified at
+ call-time. Passing a ``QSchema`` instance will alter the
+ macro-structure of the output.
+
+ Here, we quantize using settings specified by a ``MeasurewiseQSchema``,
+ which will cause the ``quantize`` function to group the output into
+ measures with different tempi and time signatures:
+
+ >>> measurewise_q_schema = nauert.MeasurewiseQSchema(
+ ... {
+ ... "tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 78),
+ ... "time_signature": abjad.TimeSignature((2, 4)),
+ ... },
+ ... {
+ ... "tempo": abjad.MetronomeMark(abjad.Duration(1, 8), 57),
+ ... "time_signature": abjad.TimeSignature((5, 4)),
+ ... },
+ ... )
+ >>> result = nauert.quantize(
+ ... q_event_sequence,
+ ... q_schema=measurewise_q_schema,
+ ... )
+ >>> staff = abjad.Staff([result])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(score)
+ >>> print(string)
+ \new Score
+ <<
+ \new Staff
+ {
+ \new Voice
+ {
+ {
+ \tempo 4=78
+ \time 2/4
+ c'4
+ ~
+ \tuplet 5/4 {
+ c'16.
+ cs'8..
+ ~
+ }
+ }
+ {
+ \tuplet 7/4 {
+ \tempo 8=57
+ \time 5/4
+ cs'16.
+ d'8
+ ~
+ }
+ \tuplet 5/4 {
+ d'16
+ ef'16.
+ ~
+ }
+ \tuplet 3/2 {
+ ef'16
+ e'8
+ ~
+ }
+ \tuplet 7/4 {
+ e'16
+ f'8
+ ~
+ f'32
+ ~
+ }
+ f'32
+ fs'16.
+ ~
+ \tuplet 5/4 {
+ fs'32
+ g'8
+ ~
+ }
+ \tuplet 7/4 {
+ g'32
+ r32
+ r16
+ r16
+ r16
+ r16
+ r16
+ r16
+ }
+ r4
+ }
+ }
+ }
+ >>
+
+ .. container:: example
+
+ Here we quantize using settings specified by a ``BeatwiseQSchema``,
+ which keeps the output of the ``quantize`` function "flattened",
+ without measures or explicit time signatures. The default beat-wise
+ settings of quarter=60 persists until the third "beatspan":
+
+ >>> beatwise_q_schema = nauert.BeatwiseQSchema(
+ ... {
+ ... 2: {"tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 120)},
+ ... 5: {"tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 90)},
+ ... 7: {"tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 30)},
+ ... })
+
+ >>> result = nauert.quantize(
+ ... q_event_sequence,
+ ... q_schema=beatwise_q_schema,
+ ... )
+ >>> staff = abjad.Staff([result])
+ >>> score = abjad.Score([staff])
+ >>> abjad.show(score) # doctest: +SKIP
+
+ .. docs::
+
+ >>> string = abjad.lilypond(score)
+ >>> print(string)
+ \new Score
+ <<
+ \new Staff
+ {
+ \new Voice
+ {
+ \tempo 4=60
+ c'4
+ cs'4
+ \tempo 4=120
+ d'2
+ ef'4
+ ~
+ \tempo 4=90
+ ef'8.
+ e'4
+ ~
+ e'16
+ ~
+ \tuplet 3/2 {
+ \tempo 4=30
+ e'32
+ f'8.
+ fs'8
+ ~
+ fs'32
+ ~
+ }
+ \tuplet 3/2 {
+ fs'32
+ g'8.
+ r32
+ r8
+ }
+ }
+ }
+ >>
+
+ Note that ``TieChains`` are generally fused together in the above
+ example, but break at tempo changes.
+
+ .. container::
+
+ The use of `BeatwiseQSchema` and `MeasurewiseAttackPointOptimizer` is
+ not supported. Please raise an issue if you would like this to be
+ supported in the future.
+
+ >>> q_schema = nauert.BeatwiseQSchema()
+ >>> attack_point_optimizer = nauert.MeasurewiseAttackPointOptimizer()
+ >>> result = nauert.quantize(
+ ... q_event_sequence,
+ ... attack_point_optimizer=attack_point_optimizer,
+ ... q_schema=q_schema,
+ ... )
+ Traceback (most recent call last):
+ ...
+ TypeError: BeatwiseQTarget is not ... with MeasurewiseAttackPointOptimizer.
+
+ Other keyword arguments are:
+
+ * ``grace_handler``: a ``GraceHandler`` instance controls whether and
+ how grace notes are used in the output. Options currently include
+ ``CollapsingGraceHandler``, ``ConcatenatingGraceHandler`` and
+ ``DiscardingGraceHandler``.
+
+ * ``heuristic``: a ``Heuristic`` instance controls how output rhythms
+ are selected from a pool of candidates. Options currently include
+ the ``DistanceHeuristic`` class.
+
+ * ``job_handler``: a ``JobHandler`` instance controls whether or not
+ parallel processing is used during the quantization process.
+ Options include the ``SerialJobHandler`` and ``ParallelJobHandler``
+ classes.
+
+ * ``attack_point_optimizer``: an ``AttackPointOptimizer`` instance
+ controls whether and how logical ties are re-notated.
+ Options currently include ``MeasurewiseAttackPointOptimizer``,
+ ``NaiveAttackPointOptimizer`` and ``NullAttackPointOptimizer``.
+
+ Refer to the reference pages for ``BeatwiseQSchema`` and
+ ``MeasurewiseQSchema`` for more information on controlling the ``quantize``
+ function's output, and to the reference on ``SearchTree`` for information
+ on controlling the rhythmic complexity of that same output.
+ """
+ # TODO: assert isinstance(q_event_sequence, QEventSequence)
+ q_event_sequence = _qeventsequence.QEventSequence(q_event_sequence)
+ if q_schema is None:
+ q_schema = _qschemas.MeasurewiseQSchema()
+ assert isinstance(q_schema, _qschemas.QSchema)
+ q_target = q_schema(q_event_sequence.duration_in_ms)
+ notation = q_target(
+ q_event_sequence,
+ grace_handler=grace_handler,
+ heuristic=heuristic,
+ job_handler=job_handler,
+ attack_point_optimizer=attack_point_optimizer,
+ attach_tempos=attach_tempos,
+ )
+ return notation
+
+
+import abc
+import copy
+
+import abjad
+
+from . import qgrid as _qgrid
+
+
+
+[docs]
+class SearchTree(abc.ABC):
+ """
+ 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.
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_definition",)
+
+ ### INITIALIZER ###
+
+ def __init__(self, definition: dict | None = None):
+ if definition is None:
+ definition = self.default_definition
+ else:
+ assert self._is_valid_definition(definition)
+ self._definition = definition
+
+ ### SPECIAL METHODS ###
+
+
+[docs]
+ def __call__(self, q_grid: _qgrid.QGrid) -> list[_qgrid.QGrid]:
+ """
+ Calls search tree.
+ """
+ assert isinstance(q_grid, _qgrid.QGrid)
+ new_q_grids = []
+ commands = self._generate_all_subdivision_commands(q_grid)
+ for command in commands:
+ new_q_grid = copy.deepcopy(q_grid)
+ q_events = new_q_grid.subdivide_leaves(command)
+ new_q_grid.fit_q_events(q_events)
+ new_q_grids.append(new_q_grid)
+ return new_q_grids
+
+
+
+[docs]
+ def __eq__(self, argument) -> bool:
+ """
+ Is true when `argument` is a search tree with definition equal to that of
+ this search tree. Otherwise false.
+ """
+ if type(self) is type(argument):
+ if self.definition == argument.definition:
+ return True
+ return False
+
+
+
+[docs]
+ def __hash__(self) -> int:
+ """
+ Hashes search tree.
+
+ Required to be explicitly redefined on Python 3 if __eq__ changes.
+ """
+ return super(SearchTree, self).__hash__()
+
+
+
+[docs]
+ def __repr__(self) -> str:
+ """
+ Gets interpreter representation.
+ """
+ return f"{type(self).__name__}(definition={self.definition!r})"
+
+
+ ### PRIVATE METHODS ###
+
+ def _find_divisible_leaf_indices_and_subdivisions(
+ self, q_grid: _qgrid.QGrid
+ ) -> tuple[list[int], list[tuple[tuple[int, ...], ...]]]:
+ # TODO: This should actually check for all QEvents which fall
+ # within the leaf's duration,
+ # including QEvents attached to the next leaf
+ # It may be prudent to actually store QEvents in two lists:
+ # before_offset and after_offset
+ indices, subdivisions = [], []
+ leaves = list(q_grid.leaves)
+ i = 0
+ for leaf_one, leaf_two in abjad.sequence.nwise(leaves):
+ if leaf_one.is_divisible:
+ succeeding_proxies = leaf_one.succeeding_q_event_proxies
+ preceding_proxies = leaf_two.preceding_q_event_proxies
+ if not preceding_proxies and all(
+ proxy.offset == leaf_one.start_offset
+ for proxy in succeeding_proxies
+ ):
+ # proxies align perfectly with this leaf
+ pass
+ elif preceding_proxies or succeeding_proxies:
+ parentage_ratios = leaf_one._get_parentage_ratios()
+ leaf_subdivisions = self._find_leaf_subdivisions(parentage_ratios)
+ if leaf_subdivisions:
+ indices.append(i)
+ subdivisions.append(tuple(leaf_subdivisions))
+ i += 1
+ return indices, subdivisions
+
+ @abc.abstractmethod
+ def _find_leaf_subdivisions(
+ self, parentage_ratios: tuple
+ ) -> tuple[tuple[int, ...], ...]:
+ raise NotImplementedError
+
+ def _generate_all_subdivision_commands(
+ self, q_grid: _qgrid.QGrid
+ ) -> tuple[tuple[tuple[int, tuple[int, int]], ...], ...]:
+ indices, subdivisions = self._find_divisible_leaf_indices_and_subdivisions(
+ q_grid
+ )
+ if not indices:
+ return ()
+ combinations = abjad.enumerate.outer_product(subdivisions)
+ combinations = [tuple(_) for _ in combinations]
+ return tuple(tuple(zip(indices, combo)) for combo in combinations)
+
+ @abc.abstractmethod
+ def _is_valid_definition(self, definition: dict) -> bool:
+ raise NotImplementedError
+
+ ### PUBLIC PROPERTIES ###
+
+ @abc.abstractproperty
+ def default_definition(self) -> dict:
+ """
+ Gets default search tree definition.
+ """
+ raise NotImplementedError
+
+ @property
+ def definition(self) -> dict:
+ """
+ Gets search tree definition.
+ """
+ return self._definition
+
+
+
+
+[docs]
+class UnweightedSearchTree(SearchTree):
+ r"""
+ Unweighted search tree based on Paul Nauert's model.
+
+ .. container:: example
+
+ >>> 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}
+
+ .. container:: example
+
+ 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.Offset(130), [0, 1, 4])
+ >>> q_event_b = nauert.PitchedQEvent(abjad.Offset(150), [2, 3, 5])
+ >>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.5))
+ >>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.667))
+ >>> 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))
+
+ .. container:: example
+
+ 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))
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ()
+
+ ### PRIVATE METHODS ###
+
+ def _find_leaf_subdivisions(
+ self, parentage_ratios: tuple
+ ) -> tuple[tuple[int, ...], ...]:
+ parentage = [x[1] for x in parentage_ratios[1:]]
+ if not parentage:
+ return tuple((1,) * x for x in sorted(self._definition.keys()))
+ node = self._definition[parentage[0]]
+ for item in parentage[1:]:
+ node = node[item]
+ if node is None:
+ return ()
+ if node is None:
+ return ()
+ return tuple((1,) * x for x in sorted(node.keys()))
+
+ def _is_valid_definition(self, definition: dict) -> bool:
+ def recurse(n):
+ results = []
+ for key in n:
+ if (
+ not isinstance(key, int)
+ or not 0 < key
+ or not abjad.math.divisors(key) == [1, key]
+ ):
+ results.append(False)
+ elif not isinstance(n[key], (dict, type(None))):
+ results.append(False)
+ elif isinstance(n[key], dict) and not recurse(n[key]):
+ results.append(False)
+ else:
+ results.append(True)
+ return results
+
+ if not isinstance(definition, dict) or not len(definition):
+ return False
+ return all(recurse(definition))
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def default_definition(self) -> dict:
+ """
+ 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}
+
+ """
+ return {
+ 2: { # 1/2
+ 2: {2: {2: None}, 3: None}, # 1/4 # 1/8 # 1/16 # 1/12
+ 3: None, # 1/6
+ 5: None, # 1/10
+ 7: None, # 1/14
+ },
+ 3: {2: {2: None}, 3: None, 5: None}, # 1/3 # 1/6 # 1/12 # 1/9 # 1/15
+ 5: {2: None, 3: None}, # 1/5 # 1/10 # 1/15
+ 7: {2: None}, # 1/7 # 1/14
+ 11: None, # 1/11
+ 13: None, # 1/13
+ }
+
+
+
+
+[docs]
+class WeightedSearchTree(SearchTree):
+ r"""
+ Weighted search tree.
+
+ .. container:: example
+
+ 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}
+
+ .. container:: example
+
+ 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)
+
+ """
+
+ ### CLASS VARIABLES ###
+
+ __slots__ = ("_all_compositions", "_compositions", "_definition")
+
+ ### INITIALIZER ###
+
+ def __init__(self, definition: dict | None = None):
+ SearchTree.__init__(self, definition)
+ self._compositions = self._precompute_compositions()
+ all_compositions = []
+ for value in list(self._compositions.values()):
+ all_compositions.extend(value)
+ self._all_compositions = tuple(all_compositions)
+
+ ### PRIVATE METHODS ###
+
+ def _find_leaf_subdivisions(
+ self, parentage_ratios: tuple
+ ) -> tuple[tuple[int, ...], ...]:
+ if len(parentage_ratios[1:]) < self._definition["max_depth"]:
+ return self._all_compositions
+ return ()
+
+ def _is_valid_definition(self, definition: dict) -> bool:
+ if not isinstance(definition, dict):
+ return False
+ elif "divisors" not in definition:
+ return False
+ elif not len(definition["divisors"]):
+ return False
+ elif not all(isinstance(x, int) and 1 < x for x in definition["divisors"]):
+ return False
+ elif not all(abjad.math.divisors(x) == [1, x] for x in definition["divisors"]):
+ return False
+ elif "max_depth" not in definition:
+ return False
+ elif not isinstance(definition["max_depth"], int):
+ return False
+ elif not 0 < definition["max_depth"]:
+ return False
+ elif "max_divisions" not in definition:
+ return False
+ elif not isinstance(definition["max_divisions"], int):
+ return False
+ elif not 1 < definition["max_divisions"]:
+ return False
+ return True
+
+ def _precompute_compositions(
+ self,
+ ) -> dict[int, list[tuple[int, ...]]]:
+ compositions = {}
+ max_divisions = self._definition["max_divisions"]
+ for divisor in self._definition["divisors"]:
+ compositions[divisor] = [
+ tuple(x)
+ for x in abjad.math.yield_all_compositions_of_integer(divisor)
+ if 1 < len(x) <= max_divisions
+ ]
+ return compositions
+
+ ### PUBLIC PROPERTIES ###
+
+ @property
+ def all_compositions(self) -> tuple[tuple[int, ...], ...]:
+ """
+ Gets all compositions of weighted search tree.
+ """
+ return self._all_compositions
+
+ @property
+ def default_definition(self) -> dict:
+ """
+ Gets default definition of weighted search tree.
+ """
+ return {"divisors": (2, 3, 5, 7), "max_depth": 3, "max_divisions": 2}
+
+' + + '' + + _("Hide Search Matches") + + "
" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/_static/uqbar.css b/_static/uqbar.css new file mode 100644 index 0000000..789fa39 --- /dev/null +++ b/_static/uqbar.css @@ -0,0 +1,73 @@ +p.rubric.section-header { + font-family: "Roboto Slab", "ff-tisa-web-pro", "Georgia", Arial, sans-serif; + font-size: 125%; + font-weight: 700; + margin-bottom: 24px; +} + +p.rubric.class-header { + font-family: "Roboto Slab", "ff-tisa-web-pro", "Georgia", Arial, sans-serif; + font-size: 100%; + font-weight: 700; + margin-bottom: 24px !important; +} + +.rst-content table.field-list td.field-body > a { + line-height: 24px; +} + +.rst-content table.field-list td.field-body > p { + line-height: 24px; +} + +.rst-content table.field-list td.field-body > p > a { + font-size: 90%; +} + +.uqbar-book { + margin-bottom: 24px; +} + +.uqbar-book > object, .uqbar-book > img { + max-width: 100%; + height: auto; +} + +div.example { + -moz-border-radius: 2px; + -moz-box-shadow: 0px 0px 10px #eee; + -webkit-border-radius: 2px; + -webkit-box-shadow: 0px 0px 10px #eee; + border-radius: 2px; + border: 1px solid #ddd; + box-shadow: 0px 0px 10px #eee; + margin-bottom: 24px; + padding: 24px; + } + +div.example :last-child { + margin-bottom: 0; + } + +tt.attribute { + color: #fff; + font-size: 0.75em; + margin: 0 1em 0 0; + padding: 0.5em; + } + +tt.abstract { + background-color: #666; + } + +tt.classmethod { + background-color: #c96; + } + +tt.inherited { + background-color: #6cc; + } + +tt.staticmethod { + background-color: #69c; + } diff --git a/api/index.html b/api/index.html new file mode 100644 index 0000000..a477c93 --- /dev/null +++ b/api/index.html @@ -0,0 +1,378 @@ + + + + + + + + +Extension for quantizing rhythm, based on Paul Nauert’s Q-Grid technique.
+Abstract Classes
+| + | Abstract attack-point optimizer. |
+
Classes
+| + | Measurewise attack-point optimizer. |
+
| + | Naive attack-point optimizer. |
+
| + | Null attack-point optimizer. |
+
Abstract Classes
+| + | Abstract grace-handler. |
+
Classes
+| + | Collapsing grace-handler. |
+
| + | Concatenating grace-handler. |
+
| + | Discarding grace-handler. |
+
Abstract Classes
+| + | Abstract heuristic. |
+
Classes
+| + | Distance heuristic. |
+
Abstract Classes
+| + | Abstact job-handler. |
+
Classes
+| + | Parallel job-handler. |
+
| + | Parallel job-handler worker. |
+
| + | Serial job-handler. |
+
Classes
+| + | Q-event proxy. |
+
Abstract Classes
+| + | Abstract Q-event. |
+
Classes
+| + | Pitched q-event. |
+
| + | Silent q-event. |
+
| + | Terminal q-event. |
+
Classes
+| + | Q-event sequence. |
+
Classes
+| + | Q-grid. |
+
| + | Q-grid container. |
+
| + | Q-grid leaf. |
+
Abstract Classes
+| + | Abstract q-schema item. |
+
Classes
+| + | Beatwise q-schema item. |
+
| + | Measurewise q-schema item. |
+
Abstract Classes
+| + | Abstract Q-schema. |
+
Classes
+| + | Beatwise q-schema. |
+
| + | Measurewise q-schema. |
+
Abstract Classes
+| + | Abstract class for QTargetBeat and QTargetMeasure. |
+
Classes
+| + | Q-target beat. |
+
| + | Q-target measure. |
+
Abstract Classes
+| + | Q-target. |
+
Classes
+| + | Beatwise q-target. |
+
| + | Measurewise quantization target. |
+
Classes
+| + | Quantization job. |
+
Functions
+| + | Quantizer function. |
+
Abstract Classes
+| + | Abstract search tree. |
+
Classes
+| + | Unweighted search tree based on Paul Nauert's model. |
+
| + | Weighted search tree. |
+
Abstract Classes
+| + | Abstract attack-point optimizer. |
+
Abstract attack-point optimizer.
+Attack-point optimizers may alter the number, order, and individual +durations of leaves in a logical tie, but may not alter the overall +duration of that logical tie.
+They effectively “clean up” notation, post-quantization.
+Attributes Summary
+| + | Calls attack-point optimizer. |
+
Special methods
+ + +Classes
+| + | Measurewise attack-point optimizer. |
+
| + | Naive attack-point optimizer. |
+
| + | Null attack-point optimizer. |
+
Measurewise attack-point optimizer.
+Attempts to optimize attack points in an expression with regard to the +effective time signature of that expression.
+Only acts on measures.
+>>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 b'8 c''8")
+>>> abjad.show(staff)
+
+>>> source_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> q_events = nauert.QEventSequence.from_tempo_scaled_leaves(
+... staff[:],
+... tempo=source_tempo,
+... )
+>>> target_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+>>> q_schema = nauert.MeasurewiseQSchema(tempo=target_tempo)
+Without the measure-wise attack-point optimizer:
+>>> voice = nauert.quantize(q_events, q_schema=q_schema)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+With the measure-wise attack-point optimizer:
+>>> optimizer = nauert.MeasurewiseAttackPointOptimizer()
+>>> voice = nauert.quantize(
+... q_events,
+... attack_point_optimizer=optimizer,
+... q_schema=q_schema,
+... )
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Attributes Summary
+| + | Calls measurewise attack-point optimizer. |
+
Special methods
+ + +Naive attack-point optimizer. (The default attack-point optimizer)
+Optimizes attack points by fusing tie leaves within logical ties with leaf +durations decreasing monotonically.
+Logical ties will be partitioned into sub-logical-ties if leaves are found +with metronome marks attached.
+>>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 b'8 c''8")
+>>> abjad.show(staff)
+
+>>> source_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> q_events = nauert.QEventSequence.from_tempo_scaled_leaves(
+... staff[:],
+... tempo=source_tempo,
+... )
+>>> target_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+>>> q_schema = nauert.MeasurewiseQSchema(tempo=target_tempo)
+>>> optimizer = nauert.NaiveAttackPointOptimizer()
+>>> voice = nauert.quantize(
+... q_events,
+... attack_point_optimizer=optimizer,
+... q_schema=q_schema,
+... )
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Attributes Summary
+| + | Calls naive attack-point optimizer. |
+
Special methods
+ + +Null attack-point optimizer.
+Performs no attack-point optimization.
+>>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 b'8 c''8")
+>>> abjad.show(staff)
+
+>>> source_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> q_events = nauert.QEventSequence.from_tempo_scaled_leaves(
+... staff[:],
+... tempo=source_tempo,
+... )
+>>> target_tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+>>> q_schema = nauert.MeasurewiseQSchema(tempo=target_tempo)
+>>> optimizer = nauert.NullAttackPointOptimizer()
+>>> voice = nauert.quantize(
+... q_events,
+... attack_point_optimizer=optimizer,
+... q_schema=q_schema,
+... )
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Attributes Summary
+| + | Calls null attack-point optimizer. |
+
Special methods
+ + +Abstract Classes
+| + | Abstract grace-handler. |
+
Abstract grace-handler.
+Determines what pitch, if any, will be selected from a list of QEvents
+to be applied to an attack-point generated by a QGrid, and whether
+there should be a BeforeGraceContainer attached to that attack-point.
When called on a sequence of QEvents, GraceHandler subclasses
+should return a pair, where the first item of the pair is a sequence of
+pitch tokens or None, and where the second item of the pair is a
+BeforeGraceContainer instance or None.
Attributes Summary
+| + | Calls grace handler. |
+
Special methods
+ + +Classes
+| + | Collapsing grace-handler. |
+
| + | Concatenating grace-handler. |
+
| + | Discarding grace-handler. |
+
Collapsing grace-handler.
+Collapses pitch information into a single chord rather than creating a +grace container.
+>>> durations = [1000, 1, 1, 997]
+>>> pitches = [0, 7, 4, 0]
+>>> method = nauert.QEventSequence.from_millisecond_pitch_pairs
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> q_event_sequence = method(pairs)
+>>> grace_handler = nauert.CollapsingGraceHandler()
+>>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Attributes Summary
+| + | Calls collapsing grace handler. |
+
Special methods
+ + +Concatenating grace-handler.
+Concatenates all but the final QEvent attached to a QGrid offset
+into a BeforeGraceContainer, using a fixed leaf duration duration.
When called, it returns pitch information of final QEvent, and the
+generated BeforeGraceContainer, if any:
>>> durations = [1000, 1, 999]
+>>> pitches = [0, 2, 0]
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+>>> grace_handler = nauert.ConcatenatingGraceHandler()
+>>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+When discard_grace_rest is set to True (the default), all the
+grace rests are discarded:
>>> durations = [1000, 1, 999]
+>>> pitches = [0, None, 0]
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+>>> grace_handler = nauert.ConcatenatingGraceHandler()
+>>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+When discard_grace_rest is set to False, grace rests are not
+discarded:
>>> grace_handler = nauert.ConcatenatingGraceHandler(discard_grace_rest=False)
+>>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+When replace_rest_with_final_grace_note is set to False, grace
+notes are allowed to be attached to a rest:
>>> durations = [1000, 1, 999, 1000]
+>>> pitches = [0, 0, None, 0]
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+>>> grace_handler = nauert.ConcatenatingGraceHandler(
+... replace_rest_with_final_grace_note=False
+... )
+>>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+When replace_rest_with_final_grace_note is set to True (the
+default behavior), any rest with grace notes attached to it is replaced
+by the last pitched grace note in the grace container:
>>> grace_handler = nauert.ConcatenatingGraceHandler()
+>>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Attributes Summary
+| + | Calls concatenating grace handler. |
+
| + | Boolean of whether to discard grace rests or not. |
+
| + | Grace duration of concantenating grace handler. |
+
| + | Embeds orphaned |
+
| + | Boolean of whether to replace the rest with the final (pitched) grace note. |
+
Special methods
+Calls concatenating grace handler.
+Methods
+Embeds orphaned QEvents into an AfterGraceContainer and
+attaches it to last_leaf.
>>> durations = [1000, 1000, 1000, 400, 50, 50]
+>>> pitches = range(len(durations))
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> method = nauert.QEventSequence.from_millisecond_pitch_pairs
+>>> q_event_sequence = method(pairs)
+>>> search_tree = nauert.UnweightedSearchTree()
+>>> attack_point_optimizer = nauert.MeasurewiseAttackPointOptimizer()
+>>> q_schema = nauert.MeasurewiseQSchema(
+... search_tree=search_tree,
+... time_signature=(7, 8),
+... use_full_measure=True,
+... )
+>>> result = nauert.quantize(
+... q_event_sequence,
+... q_schema=q_schema,
+... attach_tempos=True,
+... attack_point_optimizer=attack_point_optimizer,
+... )
+>>> staff = abjad.Staff([result])
+>>> score = abjad.Score([staff], name="Score")
+>>> abjad.show(staff)
+
+Read-only properties
+Boolean of whether to discard grace rests or not.
+Grace duration of concantenating grace handler.
+Boolean of whether to replace the rest with the final (pitched) grace +note.
+Discarding grace-handler.
+Discards all but final q-event attached to an offset.
+Does not create grace containers.
+>>> durations = [1000, 1, 1, 998]
+>>> pitches = [0, 1, 2, 3]
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+>>> grace_handler = nauert.DiscardingGraceHandler()
+>>> voice = nauert.quantize(q_event_sequence, grace_handler=grace_handler)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+>>> for pqe in grace_handler.discarded_q_events[0]:
+... pqe
+...
+PitchedQEvent(offset=Offset((1000, 1)), pitches=(NamedPitch("cs'"),), index=None, attachments=())
+PitchedQEvent(offset=Offset((1001, 1)), pitches=(NamedPitch("d'"),), index=None, attachments=())
+Attributes Summary
+| + | Calls discarding grace handler. |
+
| + | Gets discarded QEvents. |
+
Special methods
+Calls discarding grace handler.
+Read-only properties
+Gets discarded QEvents.
+Abstract Classes
+| + | Abstract heuristic. |
+
Abstract heuristic.
+Heuristics rank Q-grids according to the criteria they encapsulate.
+Heuristics provide the means by which the quantizer selects a single
+QGrid from all computed QGrids for any given QTargetBeat to
+represent that beat.
Attributes Summary
+| + | Calls heuristic. |
+
Special methods
+Calls heuristic.
+Classes
+| + | Distance heuristic. |
+
Distance heuristic.
+Considers only the computed distance of each QGrid and the number of
+leaves of that QGrid when choosing the optimal QGrid for a given
+QTargetBeat.
The QGrid with the smallest distance and fewest number of leaves will
+be selected.
>>> durations = [1000] * 8
+>>> pitches = range(8)
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+>>> heuristic = nauert.DistanceHeuristic()
+>>> voice = nauert.quantize(q_event_sequence, heuristic=heuristic)
+>>> staff = abjad.Staff([voice])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Special methods
+Heuristic).__call__(q_target_beats: tuple[QTargetBeat, ...]) tuple[QTargetBeat, ...]Calls heuristic.
+Extension for quantizing rhythm, based on Paul Nauert’s Q-Grid technique.
+Subpackages
+| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
Abstract Classes
+| + | Abstact job-handler. |
+
Abstact job-handler.
+JobHandlers control how QuantizationJob instances are processed by
+the quantize function, either serially or in parallel.
Attributes Summary
+| + | Calls job handler. |
+
Special methods
+ + +Classes
+| + | Parallel job-handler. |
+
| + | Parallel job-handler worker. |
+
| + | Serial job-handler. |
+
Parallel job-handler.
+Processes QuantizationJob instances in parallel, based on the number of
+CPUs available.
Attributes Summary
+| + | Calls parallel job handler. |
+
Special methods
+ + +Parallel job-handler worker.
+Worker process which runs QuantizationJobs.
Not composer-safe.
+Used internally by ParallelJobHandler.
Attributes Summary
+| + | Runs parallel job handler worker. |
+
Special methods
+BaseProcess).__repr__()Return repr(self).
+Methods
+BaseProcess).close()Close the Process object.
+This method releases resources held by the Process object. It is +an error to call this method if the child process is still running.
+BaseProcess).is_alive()Return whether process is alive
+BaseProcess).join(timeout=None)Wait until child process terminates
+BaseProcess).kill()Terminate process; sends SIGKILL signal or uses TerminateProcess()
+BaseProcess).start()Start child process
+BaseProcess).terminate()Terminate process; sends SIGTERM signal or uses TerminateProcess()
+Read/write properties
+BaseProcess).authkeyBaseProcess).daemonReturn whether process is a daemon
+BaseProcess).nameRead-only properties
+BaseProcess).exitcodeReturn exit code of process or None if it has yet to stop
+BaseProcess).identReturn identifier (PID) of process or None if it has yet to start
+BaseProcess).pidReturn identifier (PID) of process or None if it has yet to start
+BaseProcess).sentinelReturn a file descriptor (Unix) or handle (Windows) suitable for +waiting for process termination.
+Serial job-handler.
+Attributes Summary
+| + | Calls serial job handler. |
+
Special methods
+Calls serial job handler.
+Classes
+| + | Q-event proxy. |
+
Q-event proxy.
+Maps Q-event offset with the range of its beatspan to the range 0-1.
+>>> q_event = nauert.PitchedQEvent(abjad.Offset(130), [0, 1, 4])
+>>> nauert.QEventProxy(q_event, abjad.Offset(0.5))
+QEventProxy(q_event=PitchedQEvent(offset=Offset((130, 1)), pitches=(NamedPitch("c'"), NamedPitch("cs'"), NamedPitch("e'")), index=None, attachments=()), offset=Offset((1, 2)))
+Not composer-safe.
+Used internally by the quantize function.
Attributes Summary
+| + | Is true when argument is a q-event proxy with offset and q-event equal to those of this q-event proxy. |
+
| + | Hashes q-event proxy. |
+
| + | Gets repr. |
+
| + | Gets index of q-event proxy. |
+
| + | Gets offset of q-event proxy. |
+
| + | Gets q-event of q-event proxy. |
+
Special methods
+Is true when argument is a q-event proxy with offset and q-event +equal to those of this q-event proxy. Otherwise false.
+Hashes q-event proxy.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Read-only properties
+Gets index of q-event proxy.
+Gets offset of q-event proxy.
+Gets q-event of q-event proxy.
+Abstract Classes
+| + | Abstract Q-event. |
+
Abstract Q-event.
+Represents an attack point to be quantized.
+All QEvents possess a rational offset in milliseconds, and an optional
+index for disambiguating events which fall on the same offset in a
+QGrid.
Attributes Summary
+| + | Is true when epxr is a q-event with offset greater than that of this q-event. |
+
| + | Gets repr. |
+
| + | The attachments of the QEvent. |
+
| + | + |
| + | The optional index, for sorting QEvents with identical offsets. |
+
| + | The offset in milliseconds of the event. |
+
Special methods
+Is true when epxr is a q-event with offset greater than that of this +q-event. Otherwise false.
+Class & static methods
+ + +Read-only properties
+The attachments of the QEvent.
+The optional index, for sorting QEvents with identical offsets.
+The offset in milliseconds of the event.
+Classes
+| + | Pitched q-event. |
+
| + | Silent q-event. |
+
| + | Terminal q-event. |
+
Pitched q-event.
+Indicates the onset of a period of pitched material in a q-event sequence.
+>>> pitches = [0, 1, 4]
+>>> nauert.PitchedQEvent(abjad.Offset(1000), pitches)
+PitchedQEvent(offset=Offset((1000, 1)), pitches=(NamedPitch("c'"), NamedPitch("cs'"), NamedPitch("e'")), index=None, attachments=())
+Attributes Summary
+| + | Is true when argument is a pitched q-event with offset, pitches, attachments and index equal to those of this pitched q-event. |
+
| + | Hashes pitched q-event. |
+
| + | Gets repr. |
+
| + | Gets attachments of pitched q-event. |
+
| + | Gets pitches of pitched q-event. |
+
Special methods
+Is true when argument is a pitched q-event with offset, pitches, +attachments and index equal to those of this pitched q-event. Otherwise +false.
+Hashes pitched q-event.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Class & static methods
+Read-only properties
+Gets attachments of pitched q-event.
+Gets pitches of pitched q-event.
+Silent q-event.
+>>> q_event = nauert.SilentQEvent(abjad.Offset(1000))
+>>> q_event
+SilentQEvent(offset=Offset((1000, 1)), index=None, attachments=())
+Attributes Summary
+| + | Is true when argument is a silent q-event with offset, attachments and index equal to those of this silent q-event. |
+
| + | Hashes silent q-event. |
+
| + | Gets attachments of silent q-event. |
+
Special methods
+Is true when argument is a silent q-event with offset, attachments +and index equal to those of this silent q-event. Otherwise false.
+Hashes silent q-event.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Class & static methods
+Read-only properties
+Gets attachments of silent q-event.
+Terminal q-event.
+>>> nauert.TerminalQEvent(abjad.Offset(1000))
+TerminalQEvent(offset=Offset((1000, 1)), index=None, attachments=())
+Carries no significance outside the context of a QEventSequence.
Attributes Summary
+| + | Is true when argument is a terminal q-event with offset equal to that of this terminal q-event. |
+
| + | Hashes terminal q-event. |
+
Special methods
+Is true when argument is a terminal q-event with offset equal to that +of this terminal q-event. Otherwise false.
+Hashes terminal q-event.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Class & static methods
+Read-only properties
+ + + +Classes
+| + | Q-event sequence. |
+
Q-event sequence.
+Contains only pitched q-events and silent q-events, and terminates with a +single terminal q-event.
+A q-event sequence is the primary input to the quantizer.
+A q-event sequence provides a number of convenience functions to assist +with instantiating new sequences:
+>>> durations = (1000, -500, 1250, -500, 750)
+>>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+>>> for q_event in sequence:
+... q_event
+...
+PitchedQEvent(offset=Offset((0, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((1000, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((1500, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((2750, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((3250, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+TerminalQEvent(offset=Offset((4000, 1)), index=None, attachments=())
+Attributes Summary
+| + | Is true when q-event sequence contains |
+
| + | Is true when q-event sequence equals |
+
| + | Gets item or slice identified by argument. |
+
| + | Hashes q-event sequence. |
+
| + | Iterates q-event sequence. |
+
| + | Gets length of q-event sequence. |
+
| + | Get duration |
+
| + | Changes sequence of millisecond |
+
| + | Changes millisecond |
+
| + | Changes (millisecond-duration, pitch, attachment) |
+
| + | Changes (millisecond-duration, pitch) |
+
| + | Changes |
+
| + | Changes |
+
| + | Gets sequence of q-events. |
+
Special methods
+Is true when q-event sequence contains argument. Otherwise false.
Is true when q-event sequence equals argument. Otherwise false.
Gets item or slice identified by argument.
+Returns item or slice.
+Hashes q-event sequence.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Class & static methods
+Changes sequence of millisecond durations to QEventSequence:
>>> durations = [-250, 500, -1000, 1250, -1000]
+>>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+>>> for q_event in sequence:
+... q_event
+...
+SilentQEvent(offset=Offset((0, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((250, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((750, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((1750, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((3000, 1)), index=None, attachments=())
+TerminalQEvent(offset=Offset((4000, 1)), index=None, attachments=())
+Changes millisecond offsets to QEventSequence:
>>> numbers = [0, 250, 750, 1750, 3000, 4000]
+>>> offsets = [abjad.Offset(_) for _ in numbers]
+>>> sequence = nauert.QEventSequence.from_millisecond_offsets(offsets)
+>>> for q_event in sequence:
+... q_event
+...
+PitchedQEvent(offset=Offset((0, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+PitchedQEvent(offset=Offset((250, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+PitchedQEvent(offset=Offset((750, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+PitchedQEvent(offset=Offset((1750, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+PitchedQEvent(offset=Offset((3000, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+TerminalQEvent(offset=Offset((4000, 1)), index=None, attachments=())
+Changes (millisecond-duration, pitch, attachment) tuples into
+QEventSequence:
>>> durations = [250, 500, 1000, 1250, 1000]
+>>> pitches = [(0,), None, (2, 3), None, (1,)]
+>>> attachments = [("foo",), (), (), (), ("foobar", "foo")]
+>>> tuples = tuple(zip(durations, pitches, attachments))
+>>> method = nauert.QEventSequence.from_millisecond_pitch_attachment_tuples
+>>> sequence = method(tuples)
+>>> for q_event in sequence:
+... q_event
+...
+PitchedQEvent(offset=Offset((0, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=('foo',))
+SilentQEvent(offset=Offset((250, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((750, 1)), pitches=(NamedPitch("d'"), NamedPitch("ef'")), index=None, attachments=())
+SilentQEvent(offset=Offset((1750, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((3000, 1)), pitches=(NamedPitch("cs'"),), index=None, attachments=('foobar', 'foo'))
+TerminalQEvent(offset=Offset((4000, 1)), index=None, attachments=())
+Changes (millisecond-duration, pitch) pairs into QEventSequence:
>>> durations = [250, 500, 1000, 1250, 1000]
+>>> pitches = [(0,), None, (2, 3), None, (1,)]
+>>> pairs = tuple(zip(durations, pitches))
+>>> sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(pairs)
+>>> for q_event in sequence:
+... q_event
+...
+PitchedQEvent(offset=Offset((0, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((250, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((750, 1)), pitches=(NamedPitch("d'"), NamedPitch("ef'")), index=None, attachments=())
+SilentQEvent(offset=Offset((1750, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((3000, 1)), pitches=(NamedPitch("cs'"),), index=None, attachments=())
+TerminalQEvent(offset=Offset((4000, 1)), index=None, attachments=())
+Changes durations, scaled by tempo into a QEventSequence:
>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 174)
+>>> pairs = [(1, 4), (-3, 16), (1, 16), (-1, 2)]
+>>> durations = [abjad.Duration(_) for _ in pairs]
+>>> method = nauert.QEventSequence.from_tempo_scaled_durations
+>>> sequence = method(durations, tempo=tempo)
+>>> for q_event in sequence:
+... q_event
+...
+PitchedQEvent(offset=Offset((0, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((10000, 29)), index=None, attachments=())
+PitchedQEvent(offset=Offset((17500, 29)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((20000, 29)), index=None, attachments=())
+TerminalQEvent(offset=Offset((40000, 29)), index=None, attachments=())
+Changes leaves, optionally with tempo into a QEventSequence:
>>> staff = abjad.Staff("c'4 <d' fs'>8. r16 gqs'2")
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 72)
+>>> sequence = nauert.QEventSequence.from_tempo_scaled_leaves(staff[:], tempo)
+>>> for q_event in sequence:
+... q_event
+...
+PitchedQEvent(offset=Offset((0, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+PitchedQEvent(offset=Offset((2500, 3)), pitches=(NamedPitch("d'"), NamedPitch("fs'")), index=None, attachments=())
+SilentQEvent(offset=Offset((4375, 3)), index=None, attachments=())
+PitchedQEvent(offset=Offset((5000, 3)), pitches=(NamedPitch("gqs'"),), index=None, attachments=())
+TerminalQEvent(offset=Offset((10000, 3)), index=None, attachments=())
+If tempo is None, all leaves in leaves must have an
+effective, non-imprecise tempo. The millisecond-duration of each leaf
+will be determined by its effective tempo.
Read-only properties
+Get duration QEventSequence in milliseconds:
>>> durations = (1000, -500, 1250, -500, 750)
+>>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+>>> sequence.duration_in_ms
+Duration(4000, 1)
+Gets sequence of q-events.
+>>> durations = (1000, -500, 1250, -500, 750)
+>>> sequence = nauert.QEventSequence.from_millisecond_durations(durations)
+>>> for q_event in sequence.sequence:
+... q_event
+...
+PitchedQEvent(offset=Offset((0, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((1000, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((1500, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+SilentQEvent(offset=Offset((2750, 1)), index=None, attachments=())
+PitchedQEvent(offset=Offset((3250, 1)), pitches=(NamedPitch("c'"),), index=None, attachments=())
+TerminalQEvent(offset=Offset((4000, 1)), index=None, attachments=())
+Classes
+| + | Q-grid. |
+
| + | Q-grid container. |
+
| + | Q-grid leaf. |
+
Q-grid.
+Rhythm-tree-based model for how millisecond attack points collapse onto the +offsets generated by a nested rhythmic structure.
+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_grid = nauert.QGrid()
+>>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0])
+>>> q_event_b = nauert.PitchedQEvent(abjad.Offset(750), [1])
+>>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+>>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(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
+| + | Calls q-grid. |
+
| + | Copies q-grid. |
+
| + | Is true if argument is a q-grid with root node and next downbeat equal to those of this q-grid. |
+
| + | Hashes q-grid. |
+
| + | Gets repr. |
+
| + | The computed total distance (divided by the number of |
+
| + | Fits each |
+
| + | Gets all of the leaf nodes in the QGrid, including the next downbeat's node. |
+
| + | Gets the node representing the "next" downbeat after the contents of the QGrid's tree. |
+
| + | Gets the offsets between 0 and 1 of all of the leaf nodes in the QGrid. |
+
| + | Gets the pretty RTM-format of the root node of the |
+
| + | Regroups leaves that belong to the same parent in which only the first leaf contains q_event_prox[y|ies]. |
+
| + | Gets the root node of the |
+
| + | Gets the RTM format of the root node of the |
+
| + | Sorts |
+
| + | Replaces the |
+
| + | Given a sequence of leaf-index:subdivision-ratio pairs |
+
Special methods
+ + + + +Is true if argument is a q-grid with root node and next downbeat +equal to those of this q-grid. Otherwise false.
+Hashes q-grid.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Methods
+Fits each QEventProxy in q_event_proxies onto the contained
+QGridLeaf whose offset is nearest.
Regroups leaves that belong to the same parent in which only the first +leaf contains q_event_prox[y|ies].
+Sorts QEventProxies attached to each QGridLeaf in a QGrid
+by their index.
Replaces 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.
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
+The computed total distance (divided by the number of QEventProxy
+objects) of the offset of each QEventProxy contained by the
+QGrid to the offset of the QGridLeaf to which the
+QEventProxy is attached.
>>> q_grid = nauert.QGrid()
+>>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0], ["A"])
+>>> q_event_b = nauert.PitchedQEvent(abjad.Offset(750), [1], ["B"])
+>>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+>>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.75))
+>>> q_grid.fit_q_events([proxy_a, proxy_b])
+>>> print(q_grid.rtm_format)
+1
+>>> pairs = zip(q_grid.leaves, q_grid.offsets, strict=True)
+>>> for index, (leaf, offset) in enumerate(pairs):
+... 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))
+>>> pairs = zip(q_grid.leaves, q_grid.offsets, strict=True)
+>>> for index, (leaf, offset) in enumerate(pairs):
+... 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)
+Gets all of the leaf nodes in the QGrid, including the next downbeat’s +node.
+Gets the node representing the “next” downbeat after the contents of +the QGrid’s tree.
+Gets the offsets between 0 and 1 of all of the leaf nodes in the QGrid.
+Gets the pretty RTM-format of the root node of the QGrid.
Gets the root node of the QGrid.
Gets the RTM format of the root node of the QGrid.
Q-grid container.
+>>> nauert.QGridContainer((1, 1))
+QGridContainer((1, 1))
+Used internally by QGrid.
Attributes Summary
+| + | Gets leaves. |
+
Special methods
+RhythmTreeContainer).__add__(rtc: RhythmTreeContainer) RhythmTreeContainerConcatenates self and rtc.
The operation a + b = c returns a new rhythm-tree container c
+with the contents of a followed by the contents of b; the
+operation is noncommutative.
>>> rtc_a = abjad.rhythmtrees.parse("(1 (1 1 1))")[0]
+>>> components = rtc_a(abjad.Duration(1, 2))
+>>> voice = abjad.Voice(components)
+>>> leaf = abjad.select.leaf(voice, 0)
+>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
+>>> abjad.show(voice)
+
+>>> rtc_b = abjad.rhythmtrees.parse("(1 (3 4))")[0]
+>>> components = rtc_b(abjad.Duration(1, 2))
+>>> voice = abjad.Voice(components)
+>>> leaf = abjad.select.leaf(voice, 0)
+>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
+>>> abjad.show(voice)
+
+>>> rtc_c = rtc_a + rtc_b
+>>> components = rtc_c(abjad.Duration(1, 2))
+>>> voice = abjad.Voice(components)
+>>> leaf = abjad.select.leaf(voice, 0)
+>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
+>>> abjad.show(voice)
+
+The pair of c equals the sum of the pairs of a and b:
>>> rtc_a.pair
+(1, 1)
+>>> rtc_b.pair
+(1, 1)
+>>> rtc_c.pair
+(2, 1)
+RhythmTreeContainer).__call__(duration: Duration) list[Leaf | Tuplet]Makes list of leaves and / or tuplets equal to duration.
>>> string = "(1 (1 (2 (1 1 1)) 2))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> components = rtc(abjad.Duration(1, 1))
+>>> voice = abjad.Voice(components)
+>>> abjad.setting(voice[0]).proportionalNotationDuration = "#1/12"
+>>> abjad.show(voice)
+
+UniqueTreeContainer).__contains__(expr)UniqueTreeList).__delitem__(i)UniqueTreeList).__getitem__(expr)RhythmTreeContainer).__graph__(**keywords) GraphGraphs rhythm-tree container.
+>>> string = "(1 (1 (2 (1 1 1)) 2))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> abjad.graph(rtc)
+
UniqueTreeContainer).__iter__()UniqueTreeContainer).__len__()RhythmTreeContainer).__radd__(rtc) RhythmTreeContainerAdds rtc and self.
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).nameRhythmTreeNode).pairGets pair of rhythm-tree node.
+>>> abjad.rhythmtrees.RhythmTreeLeaf((1, 1)).pair
+(1, 1)
+>>> abjad.rhythmtrees.RhythmTreeLeaf((2, 4)).pair
+(2, 4)
+Read-only properties
+UniqueTreeContainer).childrenUniqueTreeNode).depthRhythmTreeNode).durationGets duration of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> components = rtc(abjad.Duration(1, 1))
+>>> voice = abjad.Voice(components)
+>>> score = abjad.Score([voice])
+>>> abjad.setting(score).proportionalNotationDuration = "#1/12"
+>>> abjad.show(score)
+
+>>> rtc.duration
+Duration(1, 1)
+>>> rtc[1].duration
+Duration(1, 2)
+>>> rtc[1][1].duration
+Duration(1, 4)
+UniqueTreeNode).graph_orderGet 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)
+Gets leaves.
+UniqueTreeNode).parentUniqueTreeNode).parentageRhythmTreeNode).pretty_rtm_formatGets pretty-printed RTM format of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> print(rtc.pretty_rtm_format)
+(1 (
+ (1 (
+ 1
+ 1))
+ (1 (
+ 1
+ 1))))
+>>> print(rtc[0].pretty_rtm_format)
+(1 (
+ 1
+ 1))
+>>> print(rtc[0][0].pretty_rtm_format)
+1
+RhythmTreeNode).prolationGets prolation of rhythm-tree node.
+RhythmTreeNode).prolationsGets prolations of rhythm-tree node.
+UniqueTreeNode).rootRhythmTreeContainer).rtm_formatGets RTM format of rhythm-tree container.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> rtc.rtm_format
+'(1 ((1 (1 1)) (1 (1 1))))'
+>>> rtc[0].rtm_format
+'(1 (1 1))'
+>>> rtc[0][0].rtm_format
+'1'
+RhythmTreeNode).start_offsetGets start offset of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> rtc.start_offset
+Offset((0, 1))
+>>> rtc[1].start_offset
+Offset((1, 2))
+>>> rtc[1][1].start_offset
+Offset((3, 4))
+RhythmTreeNode).stop_offsetGets stop offset of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> rtc.stop_offset
+Offset((1, 1))
+>>> rtc[0].stop_offset
+Offset((1, 2))
+>>> rtc[0][0].stop_offset
+Offset((1, 4))
+Q-grid leaf.
+>>> nauert.QGridLeaf()
+QGridLeaf((1, 1), q_event_proxies=[], is_divisible=True)
+Used internally by QGrid.
Attributes Summary
+| + | Calls q-grid leaf. |
+
| + | Graphviz graph of q-grid leaf. |
+
| + | Gets repr. |
+
| + | Flag for whether the node may be further divided under some search tree. |
+
| + | Gets preceding q-event proxies of q-grid leaf. |
+
| + | Gets q-event proxies of q-grid leaf. |
+
| + | Gets RTM format of q-grid leaf. |
+
| + | Gets succeeding q-event proxies of q-grid leaf. |
+
Special methods
+ + + + + + +Read/write properties
+Flag for whether the node may be further divided +under some search tree.
+UniqueTreeNode).nameRhythmTreeNode).pairGets pair of rhythm-tree node.
+>>> abjad.rhythmtrees.RhythmTreeLeaf((1, 1)).pair
+(1, 1)
+>>> abjad.rhythmtrees.RhythmTreeLeaf((2, 4)).pair
+(2, 4)
+Read-only properties
+UniqueTreeNode).depthRhythmTreeNode).durationGets duration of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> components = rtc(abjad.Duration(1, 1))
+>>> voice = abjad.Voice(components)
+>>> score = abjad.Score([voice])
+>>> abjad.setting(score).proportionalNotationDuration = "#1/12"
+>>> abjad.show(score)
+
+>>> rtc.duration
+Duration(1, 1)
+>>> rtc[1].duration
+Duration(1, 2)
+>>> rtc[1][1].duration
+Duration(1, 4)
+UniqueTreeNode).graph_orderGet 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)
+UniqueTreeNode).parentUniqueTreeNode).parentageGets preceding q-event proxies of q-grid leaf.
+RhythmTreeNode).pretty_rtm_formatGets pretty-printed RTM format of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> print(rtc.pretty_rtm_format)
+(1 (
+ (1 (
+ 1
+ 1))
+ (1 (
+ 1
+ 1))))
+>>> print(rtc[0].pretty_rtm_format)
+(1 (
+ 1
+ 1))
+>>> print(rtc[0][0].pretty_rtm_format)
+1
+RhythmTreeNode).prolationGets prolation of rhythm-tree node.
+RhythmTreeNode).prolationsGets prolations of rhythm-tree node.
+Gets q-event proxies of q-grid leaf.
+UniqueTreeNode).rootGets RTM format of q-grid leaf.
+RhythmTreeNode).start_offsetGets start offset of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> rtc.start_offset
+Offset((0, 1))
+>>> rtc[1].start_offset
+Offset((1, 2))
+>>> rtc[1][1].start_offset
+Offset((3, 4))
+RhythmTreeNode).stop_offsetGets stop offset of rhythm-tree node.
+>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
+>>> rtc = abjad.rhythmtrees.parse(string)[0]
+>>> rtc.stop_offset
+Offset((1, 1))
+>>> rtc[0].stop_offset
+Offset((1, 2))
+>>> rtc[0][0].stop_offset
+Offset((1, 4))
+Gets succeeding q-event proxies of q-grid leaf.
+Abstract Classes
+| + | Abstract q-schema item. |
+
Abstract q-schema item.
+Represents a change of state in the timeline of a quantization process.
+Attributes Summary
+| + | The optionally defined search tree. |
+
| + | The optionally defined tempo. |
+
Read-only properties
+The optionally defined search tree.
+The optionally defined tempo.
+Classes
+| + | Beatwise q-schema item. |
+
| + | Measurewise q-schema item. |
+
Beatwise q-schema item.
+Represents a change of state in the timeline of an unmetered +quantization process:
+>>> nauert.BeatwiseQSchemaItem()
+BeatwiseQSchemaItem(beatspan=None, search_tree=None, tempo=None)
+Defines a change in tempo:
+>>> metronome_mark = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> nauert.BeatwiseQSchemaItem(tempo=metronome_mark)
+BeatwiseQSchemaItem(beatspan=None, search_tree=None, tempo=MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=60, textual_indication=None, custom_markup=None, decimal=False, hide=False))
+Defines a change in beatspan:
+>>> nauert.BeatwiseQSchemaItem(beatspan=abjad.Duration(1, 8))
+BeatwiseQSchemaItem(beatspan=Duration(1, 8), search_tree=None, tempo=None)
+Attributes Summary
+| + | Gets repr. |
+
| + | The optionally defined beatspan duration. |
+
Special methods
+ + +Read-only properties
+The optionally defined beatspan duration.
+QSchemaItem).search_treeThe optionally defined search tree.
+QSchemaItem).tempoThe optionally defined tempo.
+Measurewise q-schema item.
+Represents a change of state in the timeline of a metered quantization process.
+>>> q_schema_item = nauert.MeasurewiseQSchemaItem()
+Defines a change in tempo:
+>>> metronome_mark = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> mark = nauert.MeasurewiseQSchemaItem(tempo=metronome_mark).tempo
+>>> abjad.lilypond(mark)
+'\\tempo 4=60'
+Defines a change in time signature:
+>>> time_signature = abjad.TimeSignature((6, 8))
+>>> nauert.MeasurewiseQSchemaItem(time_signature=time_signature).time_signature
+TimeSignature(pair=(6, 8), hide=False, partial=None)
+Tests for beatspan given a defined time signature:
+>>> time_signature = abjad.TimeSignature((6, 8))
+>>> nauert.MeasurewiseQSchemaItem(time_signature=time_signature).beatspan
+Duration(1, 8)
+Attributes Summary
+| + | Gets repr. |
+
| + | The beatspan duration, if a time signature was defined. |
+
| + | The optionally defined time signature. |
+
| + | If true, use the full measure as the beatspan. |
+
Special methods
+ + +Read-only properties
+The beatspan duration, if a time signature was defined.
+QSchemaItem).search_treeThe optionally defined search tree.
+QSchemaItem).tempoThe optionally defined tempo.
+The optionally defined time signature.
+If true, use the full measure as the beatspan.
+Abstract Classes
+| + | Abstract Q-schema. |
+
Abstract Q-schema.
+QSchema allows for the specification of quantization settings
+diachronically, at any time-step of the quantization process.
In practice, this provides a means for the composer to change the tempo,
+search-tree, time-signature etc., effectively creating a template into
+which quantized rhythms can be “poured”, without yet knowing what those
+rhythms might be, or even how much time the ultimate result will take. Like
+Abjad indicators the settings made at any given time-step via a QSchema
+instance are understood to persist until changed.
All concrete QSchema subclasses strongly implement default values for
+all of their parameters.
Attributes Summary
+| + | Calls QSchema on |
+
| + | Gets item or slice identified by argument. |
+
| + | Gets schema's item class. |
+
| + | Gets items dictionary. |
+
| + | Gets default search tree. |
+
| + | Gets schema's target class. |
+
| + | Gets schema's target class' item class. |
+
| + | Gets default tempo. |
+
Special methods
+ + + + +Read-only properties
+Gets schema’s item class.
+Gets items dictionary.
+Gets default search tree.
+Gets schema’s target class.
+Gets schema’s target class’ item class.
+Gets default tempo.
+Classes
+| + | Beatwise q-schema. |
+
| + | Measurewise q-schema. |
+
Beatwise q-schema.
+Treats beats as timestep unit.
+++++>>> q_schema = nauert.BeatwiseQSchema() +Without arguments, it uses smart defaults:
+
Each time-step in a BeatwiseQSchema is composed of three settings:
+++
+- +
beatspan- +
search_tree- +
tempo
These settings can be applied as global defaults for the schema via keyword +arguments, which persist until overridden:
+>>> beatspan = abjad.Duration(5, 16)
+>>> search_tree = nauert.UnweightedSearchTree({7: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+>>> q_schema = nauert.BeatwiseQSchema(
+... beatspan=beatspan,
+... search_tree=search_tree,
+... tempo=tempo,
+... )
+The computed value at any non-negative time-step can be found by +subscripting:
+>>> index = 0
+>>> for key, value in sorted(q_schema[index].items()):
+... print("{}:".format(key), value)
+...
+beatspan: 5/16
+search_tree: UnweightedSearchTree(definition={7: None})
+tempo: MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=54, textual_indication=None, custom_markup=None, decimal=False, hide=False)
+>>> index = 1000
+>>> for key, value in sorted(q_schema[index].items()):
+... print("{}:".format(key), value)
+...
+beatspan: 5/16
+search_tree: UnweightedSearchTree(definition={7: None})
+tempo: MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=54, textual_indication=None, custom_markup=None, decimal=False, hide=False)
+Per-time-step settings can be applied in a variety of ways.
+Instantiating the schema via *arguments with a series of either
+BeatwiseQSchemaItem instances, or dictionaries which could be used to
+instantiate BeatwiseQSchemaItem instances, will apply those settings
+sequentially, starting from time-step 0:
>>> a = {"beatspan": abjad.Duration(5, 32)}
+>>> b = {"beatspan": abjad.Duration(3, 16)}
+>>> c = {"beatspan": abjad.Duration(1, 8)}
+>>> q_schema = nauert.BeatwiseQSchema(a, b, c)
+>>> q_schema[0]["beatspan"]
+Duration(5, 32)
+>>> q_schema[1]["beatspan"]
+Duration(3, 16)
+>>> q_schema[2]["beatspan"]
+Duration(1, 8)
+>>> q_schema[3]["beatspan"]
+Duration(1, 8)
+Similarly, instantiating the schema from a single dictionary, consisting
+of integer:specification pairs, or a sequence via *arguments of (integer,
+specification) pairs, allows for applying settings to non-sequential
+time-steps:
>>> a = {"search_tree": nauert.UnweightedSearchTree({2: None})}
+>>> b = {"search_tree": nauert.UnweightedSearchTree({3: None})}
+>>> settings = {
+... 2: a,
+... 4: b,
+... }
+>>> q_schema = nauert.BeatwiseQSchema(settings)
+>>> import pprint
+>>> ust = q_schema[0]["search_tree"]
+>>> pprint.pprint(ust.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}
+>>> ust = q_schema[1]["search_tree"]
+>>> pprint.pprint(ust.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}
+>>> q_schema[2]["search_tree"]
+UnweightedSearchTree(definition={2: None})
+>>> q_schema[3]["search_tree"]
+UnweightedSearchTree(definition={2: None})
+>>> q_schema[4]["search_tree"]
+UnweightedSearchTree(definition={3: None})
+>>> q_schema[1000]["search_tree"]
+UnweightedSearchTree(definition={3: None})
+The following is equivalent to the above schema definition:
+>>> q_schema = nauert.BeatwiseQSchema(
+... (2, {"search_tree": nauert.UnweightedSearchTree({2: None})}),
+... (4, {"search_tree": nauert.UnweightedSearchTree({3: None})}),
+... )
+Attributes Summary
+| + | Gets repr. |
+
| + | Gets default beatspan of beatwise q-schema. |
+
| + | Gets schema's item class. |
+
| + | Gets target class of beatwise q-schema. |
+
| + | Gets target item class of beatwise q-schema. |
+
Special methods
+ + + + +Read-only properties
+Gets default beatspan of beatwise q-schema.
+Gets schema’s item class.
+Gets target class of beatwise q-schema.
+Gets target item class of beatwise q-schema.
+Measurewise q-schema.
+Treats measures as its timestep unit.
+>>> q_schema = nauert.MeasurewiseQSchema()
+Without arguments, it uses smart defaults:
+>>> import pprint
+>>> pprint.pprint(q_schema.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}
+Each time-step in a MeasurewiseQSchema is composed of four settings:
+++
+- +
search_tree- +
tempo- +
time_signature- +
use_full_measure
These settings can be applied as global defaults for the schema via keyword +arguments, which persist until overridden:
+>>> search_tree = nauert.UnweightedSearchTree({7: None})
+>>> time_signature = abjad.TimeSignature((3, 4))
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 54)
+>>> use_full_measure = True
+>>> q_schema = nauert.MeasurewiseQSchema(
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... use_full_measure=use_full_measure,
+... )
+All of these settings are self-descriptive, except for
+use_full_measure, which controls whether the measure is subdivided
+by the quantize function into beats according to its time
+signature.
If use_full_measure is False, the time-step’s measure will be
+divided into units according to its time-signature. For example, a 4/4
+measure will be divided into 4 units, each having a beatspan of 1/4.
On the other hand, if use_full_measure is set to True, the
+time-step’s measure will not be subdivided into independent
+quantization units. This usually results in full-measure tuplets.
The computed value at any non-negative time-step can be found by +subscripting:
+>>> index = 0
+>>> for key, value in sorted(q_schema[index].items()):
+... print("{}:".format(key), value)
+...
+search_tree: UnweightedSearchTree(definition={7: None})
+tempo: MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=54, textual_indication=None, custom_markup=None, decimal=False, hide=False)
+time_signature: TimeSignature(pair=(3, 4), hide=False, partial=None)
+use_full_measure: True
+>>> index = 1000
+>>> for key, value in sorted(q_schema[index].items()):
+... print("{}:".format(key), value)
+...
+search_tree: UnweightedSearchTree(definition={7: None})
+tempo: MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=54, textual_indication=None, custom_markup=None, decimal=False, hide=False)
+time_signature: TimeSignature(pair=(3, 4), hide=False, partial=None)
+use_full_measure: True
+Per-time-step settings can be applied in a variety of ways.
+Instantiating the schema via *arguments with a series of either
+MeasurewiseQSchemaItem instances, or dictionaries which could be
+used to instantiate MeasurewiseQSchemaItem instances, will apply
+those settings sequentially, starting from time-step 0:
>>> a = {"search_tree": nauert.UnweightedSearchTree({2: None})}
+>>> b = {"search_tree": nauert.UnweightedSearchTree({3: None})}
+>>> c = {"search_tree": nauert.UnweightedSearchTree({5: None})}
+>>> q_schema = nauert.MeasurewiseQSchema(a, b, c)
+>>> q_schema[0]["search_tree"]
+UnweightedSearchTree(definition={2: None})
+>>> q_schema[1]["search_tree"]
+UnweightedSearchTree(definition={3: None})
+>>> q_schema[2]["search_tree"]
+UnweightedSearchTree(definition={5: None})
+>>> q_schema[1000]["search_tree"]
+UnweightedSearchTree(definition={5: None})
+Similarly, instantiating the schema from a single dictionary,
+consisting of integer:specification pairs, or a sequence via
+*arguments of (integer, specification) pairs, allows for applying
+settings to non-sequential time-steps:
>>> a = {"time_signature": abjad.TimeSignature((7, 32))}
+>>> b = {"time_signature": abjad.TimeSignature((3, 4))}
+>>> c = {"time_signature": abjad.TimeSignature((5, 8))}
+>>> settings = {
+... 2: a,
+... 4: b,
+... 6: c,
+... }
+>>> q_schema = nauert.MeasurewiseQSchema(settings)
+>>> q_schema[0]["time_signature"]
+TimeSignature(pair=(4, 4), hide=False, partial=None)
+>>> q_schema[1]["time_signature"]
+TimeSignature(pair=(4, 4), hide=False, partial=None)
+>>> q_schema[2]["time_signature"]
+TimeSignature(pair=(7, 32), hide=False, partial=None)
+>>> q_schema[3]["time_signature"]
+TimeSignature(pair=(7, 32), hide=False, partial=None)
+>>> q_schema[4]["time_signature"]
+TimeSignature(pair=(3, 4), hide=False, partial=None)
+>>> q_schema[5]["time_signature"]
+TimeSignature(pair=(3, 4), hide=False, partial=None)
+>>> q_schema[6]["time_signature"]
+TimeSignature(pair=(5, 8), hide=False, partial=None)
+>>> q_schema[1000]["time_signature"]
+TimeSignature(pair=(5, 8), hide=False, partial=None)
+The following is equivalent to the above schema definition:
+>>> q_schema = nauert.MeasurewiseQSchema(
+... (2, {"time_signature": abjad.TimeSignature((7, 32))}),
+... (4, {"time_signature": abjad.TimeSignature((3, 4))}),
+... (6, {"time_signature": abjad.TimeSignature((5, 8))}),
+... )
+Attributes Summary
+| + | Gets repr. |
+
| + | Gets item class of measurewise q-schema. |
+
| + | Gets target class of measurewise q-schema. |
+
| + | Gets target item class of measurewise q-schema. |
+
| + | Gets default time signature of measurewise q-schema. |
+
| + | Is true when class uses full-measure-as-beatspan default. |
+
Special methods
+ + + + +Read-only properties
+Gets item class of measurewise q-schema.
+Gets target class of measurewise q-schema.
+Gets target item class of measurewise q-schema.
+Gets default time signature of measurewise q-schema.
+>>> q_schema = nauert.MeasurewiseQSchema(time_signature=abjad.TimeSignature((3, 4)))
+>>> q_schema.time_signature
+TimeSignature(pair=(3, 4), hide=False, partial=None)
+If there are multiple time signatures in the QSchema, this returns +the default time signature of (4, 4).
+>>> a = {"time_signature": abjad.TimeSignature((7, 32))}
+>>> b = {"time_signature": abjad.TimeSignature((3, 4))}
+>>> c = {"time_signature": abjad.TimeSignature((5, 8))}
+>>> settings = {
+... 2: a,
+... 4: b,
+... 6: c,
+... }
+>>> q_schema = nauert.MeasurewiseQSchema(settings)
+>>> q_schema.time_signature
+TimeSignature(pair=(4, 4), hide=False, partial=None)
+Is true when class uses full-measure-as-beatspan default.
+Abstract Classes
+| + | Abstract class for QTargetBeat and QTargetMeasure. |
+
Abstract class for QTargetBeat and QTargetMeasure.
+Attributes Summary
+| + | + |
| + | + |
Read-only properties
+Classes
+| + | Q-target beat. |
+
| + | Q-target measure. |
+
Q-target beat.
+Represents a single beat in a quantization target.
+>>> beatspan = abjad.Duration(1, 8)
+>>> offset_in_ms = abjad.Offset(1500)
+>>> search_tree = nauert.UnweightedSearchTree({3: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+>>> q_target_beat = nauert.QTargetBeat(
+... beatspan=beatspan,
+... offset_in_ms=offset_in_ms,
+... search_tree=search_tree,
+... tempo=tempo,
+... )
+Not composer-safe.
+Used internally by the quantize function.
Attributes Summary
+| + | Calls q-target beat. |
+
| + | Gets repr. |
+
| + | Beatspan of q-target beat. |
+
| + | Duration in milliseconds of the q-target beat. |
+
| + | Offset in milliseconds of q-target beat. |
+
| + | A list for storing |
+
| + | The |
+
| + | A tuple of |
+
| + | Search tree of q-target beat. |
+
| + | Gets tempo of q-target beat. |
+
Special methods
+Calls q-target beat.
+Read-only properties
+Beatspan of q-target beat.
+>>> beatspan = abjad.Duration(1, 8)
+>>> offset_in_ms = abjad.Offset(1500)
+>>> search_tree = nauert.UnweightedSearchTree({3: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+>>> q_target_beat = nauert.QTargetBeat(
+... beatspan=beatspan,
+... offset_in_ms=offset_in_ms,
+... search_tree=search_tree,
+... tempo=tempo,
+... )
+>>> q_target_beat.beatspan
+Duration(1, 8)
+Duration in milliseconds of the q-target beat.
+>>> beatspan = abjad.Duration(1, 8)
+>>> offset_in_ms = abjad.Offset(1500)
+>>> search_tree = nauert.UnweightedSearchTree({3: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+>>> q_target_beat = nauert.QTargetBeat(
+... beatspan=beatspan,
+... offset_in_ms=offset_in_ms,
+... search_tree=search_tree,
+... tempo=tempo,
+... )
+>>> q_target_beat.duration_in_ms
+Duration(3750, 7)
+Offset in milliseconds of q-target beat.
+>>> beatspan = abjad.Duration(1, 8)
+>>> offset_in_ms = abjad.Offset(1500)
+>>> search_tree = nauert.UnweightedSearchTree({3: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+>>> q_target_beat = nauert.QTargetBeat(
+... beatspan=beatspan,
+... offset_in_ms=offset_in_ms,
+... search_tree=search_tree,
+... tempo=tempo,
+... )
+>>> q_target_beat.offset_in_ms
+Offset((1500, 1))
+A list for storing QEventProxy instances.
Used internally by the quantize function.
The QGrid instance selected by a Heuristic.
Used internally by the quantize function.
A tuple of QGrids generated by a QuantizationJob.
Used internally by the quantize function.
Search tree of q-target beat.
+>>> beatspan = abjad.Duration(1, 8)
+>>> offset_in_ms = abjad.Offset(1500)
+>>> search_tree = nauert.UnweightedSearchTree({3: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+>>> q_target_beat = nauert.QTargetBeat(
+... beatspan=beatspan,
+... offset_in_ms=offset_in_ms,
+... search_tree=search_tree,
+... tempo=tempo,
+... )
+>>> q_target_beat.search_tree
+UnweightedSearchTree(definition={3: None})
+Gets tempo of q-target beat.
+>>> beatspan = abjad.Duration(1, 8)
+>>> offset_in_ms = abjad.Offset(1500)
+>>> search_tree = nauert.UnweightedSearchTree({3: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 56)
+>>> q_target_beat = nauert.QTargetBeat(
+... beatspan=beatspan,
+... offset_in_ms=offset_in_ms,
+... search_tree=search_tree,
+... tempo=tempo,
+... )
+>>> abjad.lilypond(q_target_beat.tempo)
+'\\tempo 4=56'
+Q-target measure.
+Represents a single measure in a measurewise quantization target.
+>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+QTargetMeasures group QTargetBeats:
>>> for q_target_beat in q_target_measure.beats:
+... print(q_target_beat.offset_in_ms, q_target_beat.duration_in_ms)
+...
+1000 1000
+2000 1000
+3000 1000
+4000 1000
+If use_full_measure is set, the QTargetMeasure will only ever
+contain a single QTargetBeat instance:
>>> another_q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... use_full_measure=True,
+... )
+>>> for q_target_beat in another_q_target_measure.beats:
+... print(q_target_beat.offset_in_ms, q_target_beat.duration_in_ms)
+...
+1000 4000
+Not composer-safe.
+Used internally by the quantize function.
Attributes Summary
+| + | Gets repr. |
+
| + | Gets the tuple of |
+
| + | Gets duration in milliseconds of the |
+
| + | Gets offset in milliseconds of the |
+
| + | Gets the search tree of |
+
| + | Gets the tempo of |
+
| + | Gets the time signature of the |
+
| + | Is true when |
+
Special methods
+ + +Read-only properties
+Gets the tuple of QTargetBeats contained by the QTargetMeasure.
>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+>>> for q_target_beat in q_target_measure.beats:
+... q_target_beat.offset_in_ms
+...
+Offset((1000, 1))
+Offset((2000, 1))
+Offset((3000, 1))
+Offset((4000, 1))
+Gets duration in milliseconds of the QTargetMeasure:
>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+>>> q_target_measure.duration_in_ms
+Duration(4000, 1)
+Gets offset in milliseconds of the QTargetMeasure:
>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+>>> q_target_measure.offset_in_ms
+Offset((1000, 1))
+Gets the search tree of QTargetMeasure:
>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+>>> q_target_measure.search_tree
+UnweightedSearchTree(definition={2: None})
+Gets the tempo of QTargetMeasure:
>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+>>> abjad.lilypond(q_target_measure.tempo)
+'\\tempo 4=60'
+Gets the time signature of the QTargetMeasure:
>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+>>> q_target_measure.time_signature
+TimeSignature(pair=(4, 4), hide=False, partial=None)
+Is true when QTargetMeasure uses full measures:
>>> search_tree = nauert.UnweightedSearchTree({2: None})
+>>> tempo = abjad.MetronomeMark(abjad.Duration(1, 4), 60)
+>>> time_signature = abjad.TimeSignature((4, 4))
+>>> q_target_measure = nauert.QTargetMeasure(
+... offset_in_ms=abjad.Offset(1000),
+... search_tree=search_tree,
+... tempo=tempo,
+... time_signature=time_signature,
+... )
+>>> q_target_measure.use_full_measure
+False
+Abstract Classes
+| + | Q-target. |
+
Q-target.
+QTarget is created by a concrete QSchema instance.
QTarget represents the mold into which the timepoints contained by a
+QSequence instance will be poured, as structured by that QSchema
+instance.
Not composer-safe.
+Used internally by the quantize function.
Attributes Summary
+| + | Calls q-target. |
+
| + | Gets beats of q-target. |
+
| + | Gets duration of q-target in milliseconds. |
+
| + | Gets item class of q-target. |
+
| + | Gets items of q-target. |
+
Special methods
+Calls q-target.
+Read-only properties
+Gets beats of q-target.
+Gets duration of q-target in milliseconds.
+Gets item class of q-target.
+Gets items of q-target.
+Classes
+| + | Beatwise q-target. |
+
| + | Measurewise quantization target. |
+
Beatwise q-target.
+Not composer-safe.
+Used internally by the quantize function.
Attributes Summary
+| + | Gets beats of beatwise q-target. |
+
| + | Gets item class of beatwise q-target. |
+
Special methods
+QTarget).__call__(q_event_sequence: QEventSequence, grace_handler: GraceHandler | None = None, heuristic: Heuristic | None = None, job_handler: JobHandler | None = None, attack_point_optimizer: AttackPointOptimizer | None = None, attach_tempos: bool = True)Calls q-target.
+Read-only properties
+Gets beats of beatwise q-target.
+Gets item class of beatwise q-target.
+Measurewise quantization target.
+Not composer-safe.
+Used internally by the quantize function.
Attributes Summary
+| + | Gets beats of measurewise q-target. |
+
| + | Gets item class of measurewise q-target. |
+
Special methods
+QTarget).__call__(q_event_sequence: QEventSequence, grace_handler: GraceHandler | None = None, heuristic: Heuristic | None = None, job_handler: JobHandler | None = None, attack_point_optimizer: AttackPointOptimizer | None = None, attach_tempos: bool = True)Calls q-target.
+Read-only properties
+Gets beats of measurewise q-target.
+Gets item class of measurewise q-target.
+Classes
+| + | Quantization job. |
+
Quantization job.
+Copiable, picklable class for generating all QGrids which are valid
+under a given SearchTree for a sequence of QEventProxies.
>>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0, 1])
+>>> q_event_b = nauert.SilentQEvent(abjad.Offset(500))
+>>> q_event_c = nauert.PitchedQEvent(abjad.Offset(750), [3, 7])
+>>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+>>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.5))
+>>> proxy_c = nauert.QEventProxy(q_event_c, abjad.Offset(0.75))
+>>> definition = {2: {2: None}, 3: None, 5: None}
+>>> search_tree = nauert.UnweightedSearchTree(definition)
+>>> job = nauert.QuantizationJob(1, search_tree, [proxy_a, proxy_b, proxy_c])
+QuantizationJob generates QGrids when called, and stores those
+QGrids on its q_grids attribute, allowing them to be recalled
+later, even if pickled:
>>> job()
+>>> for q_grid in job.q_grids:
+... print(q_grid.rtm_format)
+...
+1
+(1 (1 1 1 1 1))
+(1 (1 1 1))
+(1 (1 1))
+(1 ((1 (1 1)) (1 (1 1))))
+QuantizationJob is intended to be useful in multiprocessing-enabled
+environments.
Attributes Summary
+| + | Calls quantization job. |
+
| + | Is true when argument is a quantization job with job ID, search tree, q-event proxies and q-grids equal to those of this quantization job. |
+
| + | Hashes quantization job. |
+
| + | Gets repr. |
+
| + | Gets the job id of the |
+
| + | Gets the |
+
| + | Gets generated |
+
| + | Gets search tree |
+
Special methods
+ + +Is true when argument is a quantization job with job ID, search tree, +q-event proxies and q-grids equal to those of this quantization job. +Otherwise false.
+Hashes quantization job.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Read-only properties
+Gets the job id of the QuantizationJob.
Only meaningful when the job is processed via multiprocessing, as the +job id is necessary to reconstruct the order of jobs.
+Gets the QEventProxies the QuantizationJob was instantiated with.
>>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0, 1])
+>>> q_event_b = nauert.SilentQEvent(abjad.Offset(500))
+>>> q_event_c = nauert.PitchedQEvent(abjad.Offset(750), [3, 7])
+>>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+>>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.5))
+>>> proxy_c = nauert.QEventProxy(q_event_c, abjad.Offset(0.75))
+>>> definition = {2: {2: None}, 3: None, 5: None}
+>>> search_tree = nauert.UnweightedSearchTree(definition)
+>>> job = nauert.QuantizationJob(1, search_tree, [proxy_a, proxy_b, proxy_c])
+>>> job()
+>>> for q_event_proxy in job.q_event_proxies:
+... print(type(q_event_proxy.q_event).__name__)
+...
+PitchedQEvent
+SilentQEvent
+PitchedQEvent
+Gets generated QGrids.
>>> q_event_a = nauert.PitchedQEvent(abjad.Offset(250), [0, 1])
+>>> q_event_b = nauert.SilentQEvent(abjad.Offset(500))
+>>> q_event_c = nauert.PitchedQEvent(abjad.Offset(750), [3, 7])
+>>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.25))
+>>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.5))
+>>> proxy_c = nauert.QEventProxy(q_event_c, abjad.Offset(0.75))
+>>> definition = {2: {2: None}, 3: None, 5: None}
+>>> search_tree = nauert.UnweightedSearchTree(definition)
+>>> job = nauert.QuantizationJob(1, search_tree, [proxy_a, proxy_b, proxy_c])
+>>> job()
+>>> for q_grid in job.q_grids:
+... print(q_grid.rtm_format)
+...
+1
+(1 (1 1 1 1 1))
+(1 (1 1 1))
+(1 (1 1))
+(1 ((1 (1 1)) (1 (1 1))))
+Gets search tree QuantizationJob was instantiated with.
Functions
+| + | Quantizer function. |
+
Quantizer function.
+Quantizes sequences of attack-points, encapsulated by QEventSequences,
+into score trees.
>>> durations = [1000] * 8
+>>> pitches = range(8)
+>>> pairs = tuple(zip(durations, pitches, strict=True))
+>>> method = nauert.QEventSequence.from_millisecond_pitch_pairs
+>>> q_event_sequence = method(pairs)
+Quantization defaults to outputting into a 4/4, quarter=60 musical structure:
+>>> result = nauert.quantize(q_event_sequence)
+>>> staff = abjad.Staff([result])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+However, the behavior of the quantize function can be modified at
+call-time. Passing a QSchema instance will alter the
+macro-structure of the output.
Here, we quantize using settings specified by a MeasurewiseQSchema,
+which will cause the quantize function to group the output into
+measures with different tempi and time signatures:
>>> measurewise_q_schema = nauert.MeasurewiseQSchema(
+... {
+... "tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 78),
+... "time_signature": abjad.TimeSignature((2, 4)),
+... },
+... {
+... "tempo": abjad.MetronomeMark(abjad.Duration(1, 8), 57),
+... "time_signature": abjad.TimeSignature((5, 4)),
+... },
+... )
+>>> result = nauert.quantize(
+... q_event_sequence,
+... q_schema=measurewise_q_schema,
+... )
+>>> staff = abjad.Staff([result])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Here we quantize using settings specified by a BeatwiseQSchema,
+which keeps the output of the quantize function “flattened”,
+without measures or explicit time signatures. The default beat-wise
+settings of quarter=60 persists until the third “beatspan”:
>>> beatwise_q_schema = nauert.BeatwiseQSchema(
+... {
+... 2: {"tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 120)},
+... 5: {"tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 90)},
+... 7: {"tempo": abjad.MetronomeMark(abjad.Duration(1, 4), 30)},
+... }
+... )
+>>> result = nauert.quantize(
+... q_event_sequence,
+... q_schema=beatwise_q_schema,
+... )
+>>> staff = abjad.Staff([result])
+>>> score = abjad.Score([staff])
+>>> abjad.show(score)
+
+Note that TieChains are generally fused together in the above
+example, but break at tempo changes.
The use of BeatwiseQSchema and MeasurewiseAttackPointOptimizer is +not supported. Please raise an issue if you would like this to be +supported in the future.
+>>> q_schema = nauert.BeatwiseQSchema()
+>>> attack_point_optimizer = nauert.MeasurewiseAttackPointOptimizer()
+>>> result = nauert.quantize(
+... q_event_sequence,
+... attack_point_optimizer=attack_point_optimizer,
+... q_schema=q_schema,
+... )
+Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ File "/Users/trevor/Repositories/Projects/nauert/source/nauert/quantizer.py", line 285, in quantize
+ notation = q_target(
+ q_event_sequence,
+ ...<4 lines>...
+ attach_tempos=attach_tempos,
+ )
+ File "/Users/trevor/Repositories/Projects/nauert/source/nauert/qtargets.py", line 85, in __call__
+ raise TypeError(message)
+TypeError: BeatwiseQTarget is not supposed to be used together with MeasurewiseAttackPointOptimizer.
+Other keyword arguments are:
++++
+- +
grace_handler: aGraceHandlerinstance controls whether and +how grace notes are used in the output. Options currently include +CollapsingGraceHandler,ConcatenatingGraceHandlerand +DiscardingGraceHandler.- +
heuristic: aHeuristicinstance controls how output rhythms +are selected from a pool of candidates. Options currently include +theDistanceHeuristicclass.- +
job_handler: aJobHandlerinstance controls whether or not +parallel processing is used during the quantization process. +Options include theSerialJobHandlerandParallelJobHandler+classes.- +
attack_point_optimizer: anAttackPointOptimizerinstance +controls whether and how logical ties are re-notated. +Options currently includeMeasurewiseAttackPointOptimizer, +NaiveAttackPointOptimizerandNullAttackPointOptimizer.
Refer to the reference pages for BeatwiseQSchema and
+MeasurewiseQSchema for more information on controlling the quantize
+function’s output, and to the reference on SearchTree for information
+on controlling the rhythmic complexity of that same output.
Abstract Classes
+| + | Abstract search tree. |
+
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
+| + | Calls search tree. |
+
| + | Is true when argument is a search tree with definition equal to that of this search tree. |
+
| + | Hashes search tree. |
+
| + | Gets interpreter representation. |
+
| + | Gets default search tree definition. |
+
| + | Gets search tree definition. |
+
Special methods
+ + +Is true when argument is a search tree with definition equal to that of +this search tree. Otherwise false.
+Hashes search tree.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+Read-only properties
+Gets default search tree definition.
+Gets search tree definition.
+Classes
+| + | Unweighted search tree based on Paul Nauert's model. |
+
| + | Weighted search tree. |
+
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.Offset(130), [0, 1, 4])
+>>> q_event_b = nauert.PitchedQEvent(abjad.Offset(150), [2, 3, 5])
+>>> proxy_a = nauert.QEventProxy(q_event_a, abjad.Offset(0.5))
+>>> proxy_b = nauert.QEventProxy(q_event_b, abjad.Offset(0.667))
+>>> 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
+| + | 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) boolIs true when argument is a search tree with definition equal to that of +this search tree. Otherwise false.
+SearchTree).__hash__() intHashes search tree.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+SearchTree).__repr__() strGets interpreter representation.
+Read-only properties
+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).definitionGets search tree definition.
+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:
+++
+- +
+
+divisorscontrols the sum of the parts of the ratio a node- +
may be divided into,
+- +
+
+max_depthcontrols how many levels of tuplet nesting- +
are permitted, and
+- +
+
+max_divisionscontrols 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
+| + | Gets all compositions of weighted search tree. |
+
| + | Gets default definition of weighted search tree. |
+
Special methods
+SearchTree).__call__(q_grid: QGrid) list[QGrid]Calls search tree.
+SearchTree).__eq__(argument) boolIs true when argument is a search tree with definition equal to that of +this search tree. Otherwise false.
+SearchTree).__hash__() intHashes search tree.
+Required to be explicitly redefined on Python 3 if __eq__ changes.
+SearchTree).__repr__() strGets interpreter representation.
+Read-only properties
+Gets all compositions of weighted search tree.
+Gets default definition of weighted search tree.
+SearchTree).definitionGets search tree definition.
+| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + | + |
| + |
| + |
|
+
|
+
| + | + |
| + |
| + |
| + n | ||
| + |
+ nauert | + |
| + |
+ nauert.attackpointoptimizers | + |
| + |
+ nauert.gracehandlers | + |
| + |
+ nauert.heuristics | + |
| + |
+ nauert.jobhandlers | + |
| + |
+ nauert.qeventproxy | + |
| + |
+ nauert.qevents | + |
| + |
+ nauert.qeventsequence | + |
| + |
+ nauert.qgrid | + |
| + |
+ nauert.qschemaitems | + |
| + |
+ nauert.qschemas | + |
| + |
+ nauert.qtargetitems | + |
| + |
+ nauert.qtargets | + |
| + |
+ nauert.quantizationjob | + |
| + |
+ nauert.quantizer | + |
| + |
+ nauert.searchtrees | + |
