.. _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. 

