ArtificialHarmonic

class auxjad.ArtificialHarmonic(*arguments, multiplier: Optional[Union[abjad.duration.Duration, Tuple[int, int]]] = None, tag: Optional[abjad.tag.Tag] = None, style: str = "#'harmonic", is_parenthesized: bool = False, markup: Optional[str] = None, centre_markup: bool = True, direction: Union[str, abjad.enums.VerticalAlignment] = 'up')

Creates a chord with a tweaked top note head for notating artificial harmonics. This is a child class of abjad.Chord.

Basic usage:

Usage is similar to abjad.Chord:

>>> harm = auxjad.ArtificialHarmonic("<g c'>4")
>>> harm.style
"#'harmonic"
>>> abjad.show(harm)

And similarly to abjad.Chord, pitch and duration can be input in many different ways:

>>> harm1 = auxjad.ArtificialHarmonic(r"<g c'>4")
>>> harm2 = auxjad.ArtificialHarmonic(["g", "c'"], 1 / 4)
>>> harm3 = auxjad.ArtificialHarmonic([-5, 0], 0.25)
>>> harm4 = auxjad.ArtificialHarmonic([-5, 0], abjad.Duration(1, 4))
>>> staff = abjad.Staff([harm1, harm2, harm3, harm4])
>>> abjad.show(staff)

Error

It is important to note that this class can only be initialised with exactly two pitches. Any other number of pitches will raise a ValueError:

>>> auxjad.ArtificialHarmonic(r"<g c' d'>4")
ValueError: 'ArtificialHarmonic' requires exactly two
'written_pitches' for initialisation

style:

When instantiating this class, use the keyword argument style to set a different type of note head for the top note, such as "#'harmonic-mixed":

>>> harm = auxjad.ArtificialHarmonic(r"<g c'>4",
...                                  style="#'harmonic-mixed",
...                                  )
>>> harm.style
"#'harmonic-mixed"
>>> abjad.show(harm)

is_parenthesized:

To notate natural harmonics with a parenthesised pitch for the open string at the bottom of the interval, set the keyword is_parenthesized to True.

>>> harm = auxjad.ArtificialHarmonic(r"<g c'>4",
...                                  is_parenthesized=True,
...                                  )
>>> harm.is_parenthesized
True
>>> abjad.show(harm)

multiplier:

Similarly to abjad.Chord, this class can take multipliers:

>>> harm = auxjad.ArtificialHarmonic(r"<g c'>4",
...                                  multiplier=(2, 3),
...                                  )
>>> harm.multiplier
abjad.Multiplier(2, 3)
>>> abjad.show(harm)

Properties:

All properties of abjad.Chord are also available to be read. This class also includes two new properties named style and is_parenthesized:

>>> harm = auxjad.ArtificialHarmonic(r"<g c'>4")
>>> harm.written_pitches
"g c'"
>>> harm.written_duration
1/4
>>> harm.style
"#'harmonic"
>>> harm.is_parenthesized
False

All these properties can be set to different values after initialisation:

>>> harm.written_pitches = [-5, 2]
>>> harm.written_duration = abjad.Duration(1, 8)
>>> harm.style = "#'harmonic-mixed"
>>> harm.is_parenthesized = True
>>> harm.written_pitches
"g d'"
>>> harm.written_duration
1/8
>>> harm.style
"#'harmonic-mixed"
>>> harm.is_parenthesized
True

sounding_pitch() and sounding_note():

The methods sounding_pitch() and sounding_note() return the sounding pitch and sounding note, respectively. Their types are abjad.Pitch and abjad.Note, respectively.

>>> harmonics = [ArtificialHarmonic(r"<g b>4"),
...              ArtificialHarmonic(r"<g c'>4"),
...              ArtificialHarmonic(r"<g d'>4"),
...              ArtificialHarmonic(r"<g e'>4"),
...              ArtificialHarmonic(r"<g g'>4"),
...              ]
>>> for harmonic in harmonics:
...     print(harmonic.sounding_pitch())
b''
g''
d''
b''
g'
>>> for harmonic in harmonics:
...     print(harmonic.sounding_note())
b''4
g''4
d''4
b''4
g'4

sounding_note() and indicators:

The note created by sounding_note() inherits all indicators of the artificial harmonic.

>>> harm = auxjad.ArtificialHarmonic(r"<g c'>4-.\pp")
>>> abjad.show(harm.sounding_note())

Error

Both sounding_pitch() and sounding_note() methods raise a ValueError exception when it cannot calculate the sounding pitch for the given interval.

>>> harm = auxjad.ArtificialHarmonic(r"<g ef'>4")
>>> harm.sounding_pitch()
ValueError: cannot calculate sounding pitch for given interval
>>> harm.sounding_note()
ValueError: cannot calculate sounding pitch for given interval

markup:

To add a markup expression to the artificial harmonic, use the markup optional keyword argument, which takes strings. By default, the markup position is above the harmonic note, but this can be overridden using the keyword direction, which can take strings as well as abjad.Up and abjad.Down:

>>> harm1 = auxjad.ArtificialHarmonic(r"<a d'>1")
>>> harm2 = auxjad.ArtificialHarmonic(r"<a d'>1",
...                                   markup='I.',
...                                   )
>>> harm3 = auxjad.ArtificialHarmonic(r"<a d'>1",
...                                   markup='I.',
...                                   direction=abjad.Down)
>>> staff = abjad.Staff([harm1, harm2, harm3])
>>> abjad.show(staff)

Setting markup to None will remove the markup from the note.

>>> harm = auxjad.ArtificialHarmonic(r"<a d'>1",
...                                  markup='I.',
...                                  )
>>> harm.markup = None
>>> abjad.show(harm)

centre_markup:

When a markup expression is added to the harmonic note by using the markup optional keyword argument, it will be automatically centred above the note (as the main purpose of this markup is to show string numbers). To disable this behaviour, set centre_markup to False. Compare:

>>> harm1 = auxjad.ArtificialHarmonic(r"<a d'>1",
...                                   markup='III.',
...                                   )
>>> abjad.show(harm1)

>>> harm2 = auxjad.ArtificialHarmonic(r"<a d'>1",
...                                   markup='III.',
...                                   centre_markup=False,
...                                   )
>>> abjad.show(harm2)

Error

If another markup is attached to the harmonic note, trying to set the markup property to None will raise an Exception:

>>> harm = auxjad.ArtificialHarmonic(r"<a d'>1")
>>> abjad.attach(abjad.Markup('test'), harm)
>>> harm.markup = 'I.'
>>> harm.markup = None
Exception: multiple indicators attached to client.

Methods

__init__(*arguments[, multiplier, tag, style])	Initialises self.
__repr__()	Gets interpreter representation.
sounding_note()	Returns the sounding note of the harmonic as an abjad.Note.
sounding_pitch()	Returns the sounding pitch of the harmonic as an abjad.Pitch.

Attributes

centre_markup	Tweaks the markup of the harmonic note head to be centred or not as LilyPond doesn’t centralises markups above note heads by default.
direction	The direction of the harmonic note head.
is_parenthesized	Whether the bottom note head is parenthesised or not.
markup	The markup of the harmonic note head.
multiplier	Gets multiplier.
note_heads	Gets note-heads in chord.
style	The style of the upper note head.
tag	Gets component tag.
written_duration	Gets and sets written duration of chord.
written_pitches	The written pitches of the two note heads.

__init__(*arguments, multiplier: Optional[Union[abjad.duration.Duration, Tuple[int, int]]] = None, tag: Optional[abjad.tag.Tag] = None, style: str = "#'harmonic", is_parenthesized: bool = False, markup: Optional[str] = None, centre_markup: bool = True, direction: Union[str, abjad.enums.VerticalAlignment] = 'up') → None

Initialises self.

__repr__() → str

Gets interpreter representation.

property centre_markup: bool

Tweaks the markup of the harmonic note head to be centred or not as LilyPond doesn’t centralises markups above note heads by default.

property direction: Union[str, abjad.enums.VerticalAlignment]

The direction of the harmonic note head.

property is_parenthesized: bool

Whether the bottom note head is parenthesised or not.

property markup: str

The markup of the harmonic note head.

property multiplier: Optional[Union[abjad.duration.Multiplier, abjad.duration.NonreducedFraction]]

Gets multiplier.

property note_heads

Gets note-heads in chord.

Gets note-heads in chord:

>>> chord = abjad.Chord("<g' c'' e''>4")
>>> abjad.show(chord) 

>>> string = abjad.storage(chord.note_heads)
>>> print(string)
abjad.NoteHeadList(
    [
        abjad.NoteHead(
            written_pitch=abjad.NamedPitch("g'"),
            ),
        abjad.NoteHead(
            written_pitch=abjad.NamedPitch("c''"),
            ),
        abjad.NoteHead(
            written_pitch=abjad.NamedPitch("e''"),
            ),
        ]
    )

Sets note-heads with pitch names:

>>> chord = abjad.Chord("<g' c'' e''>4")
>>> abjad.show(chord) 

>>> chord.note_heads = "c' d' fs'"
>>> abjad.show(chord) 

Sets note-heads with pitch numbers:

>>> chord = abjad.Chord("<g' c'' e''>4")
>>> abjad.show(chord) 

>>> chord.note_heads = [16, 17, 19]
>>> abjad.show(chord) 

Set note-heads with any iterable.

Returns note-head list.

sounding_note() → abjad.score.Note

Returns the sounding note of the harmonic as an abjad.Note.

sounding_pitch() → abjad.pitch.pitches.Pitch

Returns the sounding pitch of the harmonic as an abjad.Pitch.

property style: str

The style of the upper note head.

property tag: Optional[abjad.tag.Tag]

Gets component tag.

property written_duration: abjad.duration.Duration

Gets and sets written duration of chord.

Get written duration:

>>> chord = abjad.Chord("<e' cs'' f''>4")
>>> abjad.show(chord) 

>>> chord.written_duration
Duration(1, 4)

Set written duration:

>>> chord = abjad.Chord("<e' cs'' f''>4")
>>> abjad.show(chord) 

>>> chord.written_duration = abjad.Duration(1, 16)
>>> abjad.show(chord) 

property written_pitches: abjad.pitch.segments.PitchSegment

The written pitches of the two note heads.