.. _moduleFiguredBass.resolution:

music21.figuredBass.resolution
==============================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.figuredBass.resolution


.. note:: The terminology, V43, viio, iv, etc. are explained more fully in *The Music Theory Handbook*
     by Marjorie Merryman.


This module contains methods which can properly resolve
`dominant seventh <http://en.wikipedia.org/wiki/Dominant_seventh_chord>`_,
`diminished seventh <http://en.wikipedia.org/wiki/Diminished_seventh_chord>`_, and
`augmented sixth <http://en.wikipedia.org/wiki/Augmented_sixth_chord>`_
chords expressed as possibilities (See :mod:`~music21.figuredBass.possibility`).
Although these methods can stand alone, they are speed-enhanced for instances
of :class:`~music21.figuredBass.segment.Segment`, where there are many
possibilities formed around the same chord. If provided with additional
arguments, the methods only :meth:`~music21.pitch.Pitch.transpose` each
:class:`~music21.pitch.Pitch` in a possibility by the appropriate interval.




.. function:: augmentedSixthToDominant(augSixthPossib, augSixthType=None, augSixthChordInfo=None)


    Resolves French (augSixthType = 1), German (augSixthType = 2), and Swiss (augSixthType = 3)
    augmented sixth chords to the root position dominant triad.


    Proper Italian augmented sixth resolutions not supported within this method.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> Bb2 = pitch.Pitch('B-2')
    >>> D4 = pitch.Pitch('D4')
    >>> E4 = pitch.Pitch('E4')
    >>> Es4 = pitch.Pitch('E#4')
    >>> F4 = pitch.Pitch('F4')
    >>> G4 = pitch.Pitch('G4')
    >>> Gs4 = pitch.Pitch('G#4')
    >>> iv6 = (G4, D4, D4, Bb2)
    >>> itAug6 = (Gs4, D4, D4, Bb2)
    >>> frAug6 = (Gs4, E4, D4, Bb2)
    >>> grAug6 = (Gs4, F4, D4, Bb2)
    >>> swAug6 = (Gs4, Es4, D4, Bb2)
    >>> frRes = resolution.augmentedSixthToDominant(frAug6)
    >>> frRes
    (A4, E4, C#4, A2)
    >>> grRes = resolution.augmentedSixthToDominant(grAug6)
    >>> grRes
    (A4, E4, C#4, A2)
    >>> swRes = resolution.augmentedSixthToDominant(swAug6)
    >>> swRes
    (A4, E4, C#4, A2)
    >>> resolution.showResolutions(frAug6, frRes, grAug6, grRes, swAug6, swRes)




        .. image:: images/figuredBass/fbResolution_a6toV.*
                :width: 700



    Above: French, German, and Swiss resolutions, respectively.



.. function:: augmentedSixthToMajorTonic(augSixthPossib, augSixthType=None, augSixthChordInfo=None)


    Resolves French (augSixthType = 1), German (augSixthType = 2), and Swiss (augSixthType = 3)
    augmented sixth chords to the major tonic 6,4.


    Proper Italian augmented sixth resolutions not supported within this method.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> Bb2 = pitch.Pitch('B-2')
    >>> D4 = pitch.Pitch('D4')
    >>> E4 = pitch.Pitch('E4')
    >>> Es4 = pitch.Pitch('E#4')
    >>> F4 = pitch.Pitch('F4')
    >>> G4 = pitch.Pitch('G4')
    >>> Gs4 = pitch.Pitch('G#4')
    >>> iv6 = (G4, D4, D4, Bb2)
    >>> itAug6 = (Gs4, D4, D4, Bb2)
    >>> frAug6 = (Gs4, E4, D4, Bb2)
    >>> grAug6 = (Gs4, F4, D4, Bb2)
    >>> swAug6 = (Gs4, Es4, D4, Bb2)
    >>> frRes = resolution.augmentedSixthToMajorTonic(frAug6)
    >>> frRes
    (A4, F#4, D4, A2)
    >>> grRes = resolution.augmentedSixthToMajorTonic(grAug6)
    >>> grRes
    (A4, F#4, D4, A2)
    >>> swRes = resolution.augmentedSixthToMajorTonic(swAug6)
    >>> swRes
    (A4, F#4, D4, A2)
    >>> resolution.showResolutions(frAug6, frRes, grAug6, grRes, swAug6, swRes)




        .. image:: images/figuredBass/fbResolution_a6toI.*
                :width: 700



    Above: French, German, and Swiss resolutions, respectively.



.. function:: augmentedSixthToMinorTonic(augSixthPossib, augSixthType=None, augSixthChordInfo=None)


    Resolves French (augSixthType = 1), German (augSixthType = 2), and Swiss (augSixthType = 3)
    augmented sixth chords to the minor tonic 6,4.


    Proper Italian augmented sixth resolutions not supported within this method.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> Bb2 = pitch.Pitch('B-2')
    >>> D4 = pitch.Pitch('D4')
    >>> E4 = pitch.Pitch('E4')
    >>> Es4 = pitch.Pitch('E#4')
    >>> F4 = pitch.Pitch('F4')
    >>> G4 = pitch.Pitch('G4')
    >>> Gs4 = pitch.Pitch('G#4')
    >>> iv6 = (G4, D4, D4, Bb2)
    >>> itAug6 = (Gs4, D4, D4, Bb2)
    >>> frAug6 = (Gs4, E4, D4, Bb2)
    >>> grAug6 = (Gs4, F4, D4, Bb2)
    >>> swAug6 = (Gs4, Es4, D4, Bb2)
    >>> frRes = resolution.augmentedSixthToMinorTonic(frAug6)
    >>> frRes
    (A4, F4, D4, A2)
    >>> grRes = resolution.augmentedSixthToMinorTonic(grAug6)
    >>> grRes
    (A4, F4, D4, A2)
    >>> swRes = resolution.augmentedSixthToMinorTonic(swAug6)
    >>> swRes
    (A4, F4, D4, A2)
    >>> resolution.showResolutions(frAug6, frRes, grAug6, grRes, swAug6, swRes)




        .. image:: images/figuredBass/fbResolution_a6toIm.*
                :width: 700



    Above: French, German, and Swiss resolutions, respectively.



.. function:: dominantSeventhToMajorTonic(domPossib, resolveV43toI6=False, domChordInfo=None)


    Resolves a dominant seventh chord in root position or any of its
    inversions to the major tonic, in root position or first inversion.


    The second inversion (4,3) dominant seventh chord can resolve to
    the tonic in either inversion. This is controlled by
    resolveV43toI6, and is set to True by :meth:`~music21.figuredBass.segment.Segment.resolveDominantSeventhSegment`
    only when the :attr:`~music21.figuredBass.segment.Segment.segmentChord`
    of a :class:`~music21.figuredBass.segment.Segment`
    spells out a dominant seventh chord in second inversion.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> G2 = pitch.Pitch('G2')
    >>> C3 = pitch.Pitch('C3')
    >>> E3 = pitch.Pitch('E3')
    >>> G3 = pitch.Pitch('G3')
    >>> Bb3 = pitch.Pitch('B-3')
    >>> B3 = pitch.Pitch('B3')
    >>> C4 = pitch.Pitch('C4')
    >>> F4 = pitch.Pitch('F4')
    >>> Bb4 = pitch.Pitch('B-4')
    >>> D5 = pitch.Pitch('D5')
    >>> E5 = pitch.Pitch('E5')
    >>> domPossibA1 = (D5, F4, B3, G2)
    >>> resPossibA1 = resolution.dominantSeventhToMajorTonic(domPossibA1)
    >>> resPossibA1
    (C5, E4, C4, C3)
    >>> resolution.showResolutions(domPossibA1, resPossibA1)




    .. image:: images/figuredBass/fbResolution_V7toI_1.*
                :width: 150




    >>> domPossibA2 = (Bb3, G3, E3, C3)
    >>> resPossibA2 = resolution.dominantSeventhToMajorTonic(domPossibA2)
    >>> resPossibA2
    (A3, F3, F3, F3)
    >>> resolution.showResolutions(domPossibA2, resPossibA2)




    .. image:: images/figuredBass/fbResolution_V7toI_2.*
                :width: 150




    >>> domPossibA3 = (E5, Bb4, C4, G3)
    >>> resPossibA3a = resolution.dominantSeventhToMajorTonic(domPossibA3, False)
    >>> resPossibA3a
    (F5, A4, C4, F3)
    >>> resPossibA3b = resolution.dominantSeventhToMajorTonic(domPossibA3, True)
    >>> resPossibA3b
    (F5, C5, C4, A3)
    >>> resolution.showResolutions(domPossibA3, resPossibA3a, domPossibA3, resPossibA3b)




    .. image:: images/figuredBass/fbResolution_V7toI_3.*
                :width: 200




.. function:: dominantSeventhToMinorTonic(domPossib, resolveV43toi6=False, domChordInfo=None)


    Resolves a dominant seventh chord in root position or any of its
    inversions to the minor tonic, in root position or first inversion,
    accordingly.


    The second inversion (4,3) dominant seventh chord can resolve to
    the tonic in either inversion. This is controlled by
    resolveV43toi6, and is set to True by :meth:`~music21.figuredBass.segment.Segment.resolveDominantSeventhSegment`
    only when the :attr:`~music21.figuredBass.segment.Segment.segmentChord`
    of a :class:`~music21.figuredBass.segment.Segment`
    spells out a dominant seventh chord in second inversion.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> G2 = pitch.Pitch('G2')
    >>> C3 = pitch.Pitch('C3')
    >>> E3 = pitch.Pitch('E3')
    >>> G3 = pitch.Pitch('G3')
    >>> Bb3 = pitch.Pitch('B-3')
    >>> B3 = pitch.Pitch('B3')
    >>> C4 = pitch.Pitch('C4')
    >>> F4 = pitch.Pitch('F4')
    >>> Bb4 = pitch.Pitch('B-4')
    >>> D5 = pitch.Pitch('D5')
    >>> E5 = pitch.Pitch('E5')
    >>> domPossibA1 = (D5, F4, B3, G2)
    >>> resPossibA1 = resolution.dominantSeventhToMinorTonic(domPossibA1)
    >>> resPossibA1
    (C5, E-4, C4, C3)
    >>> resolution.showResolutions(domPossibA1, resPossibA1)




    .. image:: images/figuredBass/fbResolution_V7toIm_1.*
                :width: 150




    >>> domPossibA2 = (Bb3, G3, E3, C3)
    >>> resPossibA2 = resolution.dominantSeventhToMinorTonic(domPossibA2)
    >>> resPossibA2
    (A-3, F3, F3, F3)
    >>> resolution.showResolutions(domPossibA2, resPossibA2)




    .. image:: images/figuredBass/fbResolution_V7toIm_2.*
                :width: 150




    >>> domPossibA3 = (E5, Bb4, C4, G3)
    >>> resPossibA3a = resolution.dominantSeventhToMinorTonic(domPossibA3, False)
    >>> resPossibA3a
    (F5, A-4, C4, F3)
    >>> resPossibA3b = resolution.dominantSeventhToMinorTonic(domPossibA3, True)
    >>> resPossibA3b
    (F5, C5, C4, A-3)
    >>> resolution.showResolutions(domPossibA3, resPossibA3a, domPossibA3, resPossibA3b)




    .. image:: images/figuredBass/fbResolution_V7toIm_3.*
                :width: 200




.. function:: dominantSeventhToMajorSubmediant(domPossib, domChordInfo=None)


    Resolves a dominant seventh chord in root position to the
    major submediant (VI) in root position.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> G2 = pitch.Pitch('G2')
    >>> B3 = pitch.Pitch('B3')
    >>> F4 = pitch.Pitch('F4')
    >>> D5 = pitch.Pitch('D5')
    >>> domPossibA1 = (D5, F4, B3, G2)
    >>> resPossibA1 = resolution.dominantSeventhToMajorSubmediant(domPossibA1)
    >>> resPossibA1
    (C5, E-4, C4, A-2)
    >>> resolution.showResolutions(domPossibA1, resPossibA1)




    .. image:: images/figuredBass/fbResolution_V7toVI.*
                :width: 150




.. function:: dominantSeventhToMinorSubmediant(domPossib, domChordInfo=None)


    Resolves a dominant seventh chord in root position to the
    minor submediant (vi) in root position.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> G2 = pitch.Pitch('G2')
    >>> B3 = pitch.Pitch('B3')
    >>> F4 = pitch.Pitch('F4')
    >>> D5 = pitch.Pitch('D5')
    >>> domPossibA1 = (D5, F4, B3, G2)
    >>> resPossibA1 = resolution.dominantSeventhToMinorSubmediant(domPossibA1)
    >>> resPossibA1
    (C5, E4, C4, A2)
    >>> resolution.showResolutions(domPossibA1, resPossibA1)




    .. image:: images/figuredBass/fbResolution_V7toVIm.*
                :width: 150




.. function:: dominantSeventhToMajorSubdominant(domPossib, domChordInfo=None)


    Resolves a dominant seventh chord in root position
    to the major subdominant (IV) in first inversion.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> G2 = pitch.Pitch('G2')
    >>> B3 = pitch.Pitch('B3')
    >>> F4 = pitch.Pitch('F4')
    >>> D5 = pitch.Pitch('D5')
    >>> domPossibA1 = (D5, F4, B3, G2)
    >>> resPossibA1 = resolution.dominantSeventhToMajorSubdominant(domPossibA1)
    >>> resPossibA1
    (C5, F4, C4, A2)
    >>> resolution.showResolutions(domPossibA1, resPossibA1)




    .. image:: images/figuredBass/fbResolution_V7toIV.*
                :width: 150




.. function:: dominantSeventhToMinorSubdominant(domPossib, domChordInfo=None)


    Resolves a dominant seventh chord in root position
    to the minor subdominant (iv) in first inversion.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> G2 = pitch.Pitch('G2')
    >>> B3 = pitch.Pitch('B3')
    >>> F4 = pitch.Pitch('F4')
    >>> D5 = pitch.Pitch('D5')
    >>> domPossibA1 = (D5, F4, B3, G2)
    >>> resPossibA1 = resolution.dominantSeventhToMinorSubdominant(domPossibA1)
    >>> resPossibA1
    (C5, F4, C4, A-2)
    >>> resolution.showResolutions(domPossibA1, resPossibA1)




    .. image:: images/figuredBass/fbResolution_V7toIVm.*
                :width: 150




.. function:: diminishedSeventhToMajorTonic(dimPossib, doubledRoot=False, dimChordInfo=None)


    Resolves a fully diminished seventh chord to the major tonic,
    in root position or either inversion.


    The resolution of the diminished seventh chord can have a
    doubled third (standard resolution) or a doubled root
    (alternate resolution), because the third of the diminished
    chord can either rise or fall. The desired resolution is
    attained using doubledRoot, and is set by
    :meth:`~music21.figuredBass.segment.Segment.resolveDiminishedSeventhSegment`.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> Cs3 = pitch.Pitch('C#3')
    >>> G3 = pitch.Pitch('G3')
    >>> E4 = pitch.Pitch('E4')
    >>> Bb4 = pitch.Pitch('B-4')
    >>> dimPossibA = (Bb4, E4, G3, Cs3)
    >>> resPossibAa = resolution.diminishedSeventhToMajorTonic(dimPossibA, False)
    >>> resPossibAa
    (A4, F#4, F#3, D3)
    >>> resPossibAb = resolution.diminishedSeventhToMajorTonic(dimPossibA, True)
    >>> resPossibAb
    (A4, D4, F#3, D3)
    >>> resolution.showResolutions(dimPossibA, resPossibAa, dimPossibA, resPossibAb)




    .. image:: images/figuredBass/fbResolution_vii7toI.*
                :width: 200




.. function:: diminishedSeventhToMinorTonic(dimPossib, doubledRoot=False, dimChordInfo=None)


    Resolves a fully diminished seventh chord to the minor tonic,
    in root position or either inversion.


    The resolution of the diminished seventh chord can have a
    doubled third (standard resolution) or a doubled root
    (alternate resolution), because the third of the diminished
    chord can either rise or fall. The desired resolution is
    attained using doubledRoot, and is set by
    :meth:`~music21.figuredBass.segment.Segment.resolveDiminishedSeventhSegment`.



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> Cs3 = pitch.Pitch('C#3')
    >>> G3 = pitch.Pitch('G3')
    >>> E4 = pitch.Pitch('E4')
    >>> Bb4 = pitch.Pitch('B-4')
    >>> dimPossibA = (Bb4, E4, G3, Cs3)
    >>> resPossibAa = resolution.diminishedSeventhToMinorTonic(dimPossibA, False)
    >>> resPossibAa
    (A4, F4, F3, D3)
    >>> resPossibAb = resolution.diminishedSeventhToMinorTonic(dimPossibA, True)
    >>> resPossibAb
    (A4, D4, F3, D3)
    >>> resolution.showResolutions(dimPossibA, resPossibAa, dimPossibA, resPossibAb)




    .. image:: images/figuredBass/fbResolution_vii7toIm.*
                :width: 200




.. function:: diminishedSeventhToMajorSubdominant(dimPossib, dimChordInfo=None)


    Resolves a fully diminished seventh chord to the
    major subdominant (IV).



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> Cs3 = pitch.Pitch('C#3')
    >>> G3 = pitch.Pitch('G3')
    >>> E4 = pitch.Pitch('E4')
    >>> Bb4 = pitch.Pitch('B-4')
    >>> dimPossibA = (Bb4, E4, G3, Cs3)
    >>> resPossibA = resolution.diminishedSeventhToMajorSubdominant(dimPossibA)
    >>> resPossibA
    (B4, D4, G3, D3)
    >>> resolution.showResolutions(dimPossibA, resPossibA)




    .. image:: images/figuredBass/fbResolution_vii7toIV.*
                :width: 150




.. function:: diminishedSeventhToMinorSubdominant(dimPossib, dimChordInfo=None)


    Resolves a fully diminished seventh chord to the
    minor subdominant (iv).



    >>> from music21 import pitch
    >>> from music21.figuredBass import resolution
    >>> Cs3 = pitch.Pitch('C#3')
    >>> G3 = pitch.Pitch('G3')
    >>> E4 = pitch.Pitch('E4')
    >>> Bb4 = pitch.Pitch('B-4')
    >>> dimPossibA = (Bb4, E4, G3, Cs3)
    >>> resPossibA = resolution.diminishedSeventhToMinorSubdominant(dimPossibA)
    >>> resPossibA
    (B-4, D4, G3, D3)
    >>> resolution.showResolutions(dimPossibA, resPossibA)




    .. image:: images/figuredBass/fbResolution_vii7toIVm.*
                :width: 150




.. function:: showResolutions(*allPossib)


    Takes in possibilities as arguments and adds them in order
    to a :class:`~music21.stream.Score` which is then displayed
    in external software.



