quantizer

Functions

quantize

Quantizer function.
abjadext.nauert.quantizer.quantize(q_event_sequence, q_schema=None, grace_handler=None, heuristic=None, job_handler=None, attack_point_optimizer=None, attach_tempos=True)[source]

Quantizer function.

Quantizes sequences of attack-points, encapsulated by QEventSequences, into score trees.

>>> durations = [1000] * 8
>>> pitches = range(8)
>>> q_event_sequence = nauert.QEventSequence.from_millisecond_pitch_pairs(
...     tuple(zip(durations, pitches))
... )

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": ((1, 4), 78), "time_signature": (2, 4)},
...     {"tempo": ((1, 8), 57), "time_signature": (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": ((1, 4), 120)},
...         5: {"tempo": ((1, 4), 90)},
...         7: {"tempo": ((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/abjad-ext-nauert/abjadext/nauert/quantizer.py", line 280, in quantize
    notation = q_target(
               ^^^^^^^^^
  File "/Users/trevor/abjad-ext-nauert/abjadext/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: 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.

Return type:

Voice