respell_augmented_unisons

auxjad.mutate.respell_augmented_unisons(selection: abjad.select.Selection, *, include_multiples: bool = False, respell_by_pitch_class: bool = False) → None

Mutates an input abjad.Selection in place and has no return value; this function changes the accidentals of individual pitches of all chords in a container in order to avoid augmented unisons.

Basic usage:

To use this function, apply it to a selection that contains chords that have augmented unisons.

>>> container = abjad.Container(r"c'4 r4 <ef' e'>4 g'4 <c' cs'>4 r2.")
>>> abjad.show(container)

>>> auxjad.mutate.respell_augmented_unisons(container[:])
>>> abjad.show(container)

This can be useful when using tuples of integers to create chords that contain minor seconds:

>>> pitches = [(0, 1), (8, 9, 12), (0, 4, 5, 6), (-1, 5, 6)]
>>> durations = [(1, 8), (3, 8), (7, 16), (1, 16)]
>>> maker = abjad.LeafMaker()
>>> chords = maker(pitches, durations)
>>> staff = abjad.Staff(chords)
>>> literal = abjad.LilyPondLiteral(r'\accidentalStyle dodecaphonic')
>>> abjad.attach(literal, staff)
>>> abjad.show(staff)

>>> auxjad.mutate.respell_augmented_unisons(staff[:])
>>> abjad.show(staff)

Note

Auxjad automatically adds this function as an extension function to abjad.mutate. It can thus be used from either auxjad.mutate or abjad.mutate namespaces. Therefore, the two lines below are equivalent:

>>> auxjad.mutate.respell_augmented_unisons(staff[:])
>>> abjad.mutate.respell_augmented_unisons(staff[:])

2-note chords:

The example below shows first the default spelling of 2-note chords in Abjad followed by the respelt 2-note chords.

>>> staff = abjad.Staff()
>>> for pitch in range(12):
...     staff.append(abjad.Chord([pitch, pitch + 1], (1, 16)))
>>> literal = abjad.LilyPondLiteral(r'\accidentalStyle dodecaphonic')
>>> abjad.attach(literal, staff)
>>> abjad.show(staff)

>>> auxjad.mutate.respell_augmented_unisons(staff[:])
>>> abjad.show(staff)

augmented unissons in chords with 3 or more pitches:

The function looks for all augmented unissons in chords of 3 or more pitches:

>>> staff = abjad.Staff(r"<a c' cs' f'>1")
>>> abjad.show(staff)

>>> auxjad.mutate.respell_augmented_unisons(staff[:])
>>> abjad.show(staff)

include_multiples:

By default, this function only changes spelling for pitches that are 1 semitone apart.

>>> staff = abjad.Staff(r"<c' cs''>1")
>>> abjad.show(staff)

>>> auxjad.mutate.respell_augmented_unisons(staff[:])
>>> abjad.show(staff)

To consider pitches in different octaves (thus including augmented unisons, augmented octaves, augmented fifteenths, etc.), call this function with the keyword argument include_multiples set to True.

>>> staff = abjad.Staff(r"<c' cs''>1")
>>> auxjad.mutate.respell_augmented_unisons(
...     staff[:],
...     include_multiples=True,
... )

respell_by_pitch_class:

By default, when this function changes the spelling of a pitch, it does not change the spelling of all other pitches with the same pitch-class.

>>> staff = abjad.Staff(r"<c' cs' cs''>1")
>>> abjad.show(staff)

>>> auxjad.mutate.respell_augmented_unisons(staff[:])
>>> abjad.show(staff)

To alter all pitch-classes, call this function with the keyword argument respell_by_pitch_class set to True.

>>> staff = abjad.Staff(r"<c' cs' cs''>1")
>>> auxjad.mutate.respell_augmented_unisons(
...     staff[:],
...     respell_by_pitch_class=True,
... )
>>> abjad.show(staff)