virtual_fundamental

auxjad.get.virtual_fundamental(pitches: Union[abjad.pitch.segments.PitchSegment, abjad.score.Chord], *, min_fundamental: Optional[abjad.pitch.pitches.Pitch] = None) → abjad.pitch.pitches.NamedPitch

Returns the virtual fundamental (highest common fundamental) for all pitches in a abjad.PitchSegment or abjad.Chord. Return value is of type abjad.NamedPitch.

Basic usage:

This function will look for the highest fundamental whose harmonic series contains all notes in a given collection of pitches. E.g.:

>>> pitches = abjad.PitchSegment(r"c'' g''")
>>> auxjad.get.virtual_fundamental(pitches)
c'

>>> pitches = abjad.PitchSegment(r"c'' e'' g''")
>>> auxjad.get.virtual_fundamental(pitches)
c

>>> pitches = abjad.PitchSegment(r"c'' f'' g''")
>>> auxjad.get.virtual_fundamental(pitches)
f,

>>> pitches = abjad.PitchSegment(r"c'' d'' ef'' fs''")
>>> auxjad.get.virtual_fundamental(pitches)
bf,,

Note

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

>>> pitches = abjad.PitchSegment(r"c'' g''")
>>> auxjad.get.virtual_fundamental(pitches)
c'
>>> abjad.get.virtual_fundamental(pitches)
c'

Input types:

Input types can be abjad.PitchSegment or abjad.Chord:

>>> pitches = abjad.PitchSegment(r"c'' cs'' d'' ef'' e'' fs''")
>>> auxjad.get.virtual_fundamental(pitches)
d,,
>>> chord = abjad.Chord(r"<c'' cs'' d'' ef'' e'' fs''>4")
>>> auxjad.get.virtual_fundamental(chord)
d,,
>>> staff = abjad.Staff(r"r4 <c'' cs'' d'' ef'' e'' fs''>4 r4")
>>> auxjad.get.virtual_fundamental(staff[1])
d,,

min_fundamental:

The partials above the 13th partial can be approximated to include all chromatic pitches. This means that any complex of pitches will have a virtual fundamental, even though they are fairly distant from it. To limit the search of a fundamental by a minimum value, set min_fundamental to a specific pitch:

>>> pitches = abjad.PitchSegment(r"c'' cs'' d'' ef'' e'' fs''")
>>> auxjad.get.virtual_fundamental(
...     pitches,
...     min_fundamental=abjad.NamedPitch(r"c,,,"),
... )
d,,

>>> pitches = abjad.PitchSegment(r"c'' cs'' d'' ef'' e'' fs''")
>>> auxjad.get.virtual_fundamental(
...     pitches,
...     min_fundamental=abjad.NumberedPitch(-48),
... )
d,,

Error

If a fundamental is not found with a given min_fundamental, the function will raise a ValueError exception:

>>> pitches = abjad.PitchSegment(r"c'' cs'' d'' ef'' e'' fs''")
>>> auxjad.get.virtual_fundamental(
...     pitches,
...     min_fundamental=abjad.NamedPitch(r"c'"),
... )
ValueError: No fundamental found above c'