.. _moduleFiguredBass.realizer:

music21.figuredBass.realizer
============================

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

.. module:: music21.figuredBass.realizer

This module, the heart of fbRealizer, is all about realizing a bass line of (bassNote, notationString) pairs. All it takes to create well-formed realizations of a bass line is a few lines of music21 code, from start to finish. See :class:`~music21.figuredBass.realizer.FiguredBassLine` for more details. 

>>> from music21.figuredBass import realizer
>>> from music21 import note
>>> fbLine = realizer.FiguredBassLine()
>>> fbLine.addElement(note.Note('C3'))
>>> fbLine.addElement(note.Note('D3'), '4,3')
>>> fbLine.addElement(note.Note('C3', quarterLength = 2.0))
>>> allSols = fbLine.realize()
>>> allSols.getNumSolutions()
30 
>>> allSols.generateRandomRealizations(14).show()


.. image:: images/figuredBass/fbRealizer_intro.*
    :width: 500



The same can be accomplished by taking the notes and notations from a :class:`~music21.stream.Stream`. 
See :meth:`~music21.figuredBass.realizer.figuredBassFromStream` for more details. 


>>> from music21 import tinyNotation
>>> s = tinyNotation.TinyNotationStream("C4 D4_4,3 C2")
>>> fbLine = realizer.figuredBassFromStream(s)
>>> allSols2 = fbLine.realize()
>>> allSols2.getNumSolutions()
30 


.. function:: figuredBassFromStream(streamPart)

    Takes a :class:`~music21.stream.Part` (or another :class:`~music21.stream.Stream` subclass) and returns a :class:`~music21.figuredBass.realizer.FiguredBassLine` object whose bass notes have notations taken from the lyrics in the source stream. This method along with the :meth:`~music21.figuredBass.realizer.FiguredBassLine.realize` method provide the easiest way of converting from a notated version of a figured bass (such as in a MusicXML file) to a realized version of the same line. 

    .. note:: This example corresponds to example 1b in "fbREALIZER: AUTOMATIC FIGURED BASS REALIZATION FOR MUSIC INFORMATION RETRIEVAL IN music21," which was submitted for consideration for the 12th International Society for Music Information Retrieval Conference (`ISMIR 2011 <http://ismir2011.ismir.net/>`_). 

    >>> from music21 import tinyNotation
    >>> from music21.figuredBass import realizer
    >>> s = tinyNotation.TinyNotationStream('C4 D8_6 E8_6 F4 G4_7 c1', '4/4')
    >>> fb = realizer.figuredBassFromStream(s)
    >>> fbRules = rules.Rules()
    >>> fbRules.partMovementLimits = [(1,2),(2,12),(3,12)]
    >>> fbRealization = fb.realize(fbRules)
    >>> fbRealization.getNumSolutions()
    13 
    >>> fbRealization.generateRandomRealizations(8).show()


    .. image:: images/figuredBass/fbRealizer_fbStreamPart.*
        :width: 500


.. function:: figuredBassFromStreamPart(streamPart)

    Deprecated. Use :meth:`~music21.figuredBass.realizer.figuredBassFromStream` instead. 

.. function:: addLyricsToBassNote(bassNote, notationString=None)

    Takes in a bassNote and a corresponding notationString as arguments. Adds the parsed notationString as lyrics to the bassNote, which is useful when displaying the figured bass in external software. 

    >>> from music21.figuredBass import realizer
    >>> from music21 import note
    >>> n1 = note.Note('G3')
    >>> realizer.addLyricsToBassNote(n1, "6,4")
    >>> n1.lyrics[0].text
    '6' 
    >>> n1.lyrics[1].text
    '4' 
    >>> n1.show()


    .. image:: images/figuredBass/fbRealizer_lyrics.*
        :width: 100


FiguredBassLine
---------------



.. class:: FiguredBassLine(inKey=C major, inTime=4/4)

    A FiguredBassLine is an interface for realization of a line of (bassNote, notationString) pairs. Currently, only 1:1 realization is supported, meaning that every bassNote is realized and the :attr:`~music21.note.GeneralNote.quarterLength` or duration of a realization above a bassNote is identical to that of the bassNote. 

    

    >>> from music21.figuredBass import realizer
    >>> from music21 import key
    >>> from music21 import meter
    >>> fbLine = realizer.FiguredBassLine(key.Key('B'), meter.TimeSignature('3/4'))
    >>> fbLine.inKey
    <music21.key.Key of B major> 
    >>> fbLine.inTime
    <music21.meter.TimeSignature 3/4> 

    **FiguredBassLine** **attributes**

        .. attribute:: inTime

            A :class:`~music21.meter.TimeSignature` which specifies the time signature of realizations outputted to a :class:`~music21.stream.Score`. 

        .. attribute:: inKey

            A :class:`~music21.key.Key` which implies a scale value, scale mode, and key signature for a :class:`~music21.figuredBass.realizerScale.FiguredBassScale`. 

    **FiguredBassLine** **methods**

        .. method:: addElement(bassNote, notationString=None)

            Use this method to add (bassNote, notationString) pairs to the bass line. Elements are realized in the order they are added. 

            

            >>> from music21.figuredBass import realizer
            >>> from music21 import key
            >>> from music21 import meter
            >>> from music21 import note
            >>> fbLine = realizer.FiguredBassLine(key.Key('B'), meter.TimeSignature('3/4'))
            >>> fbLine.addElement(note.Note('B2'))
            >>> fbLine.addElement(note.Note('C#3'), "6")
            >>> fbLine.addElement(note.Note('D#3'), "6")
            >>> fbLine.generateBassLine().show()


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


        .. method:: generateBassLine()

            Generates the bass line as a :class:`~music21.stream.Score`. 

            >>> from music21.figuredBass import realizer
            >>> from music21 import key
            >>> from music21 import meter
            >>> from music21 import note
            >>> fbLine = realizer.FiguredBassLine(key.Key('B'), meter.TimeSignature('3/4'))
            >>> fbLine.addElement(note.Note('B2'))
            >>> fbLine.addElement(note.Note('C#3'), "6")
            >>> fbLine.addElement(note.Note('D#3'), "6")
            >>> fbLine.generateBassLine().show()


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


        .. method:: realize(fbRules=<music21.figuredBass.rules Rules>, numParts=4, maxPitch=B5)

            Creates a :class:`~music21.figuredBass.segment.Segment` for each (bassNote, notationString) pair added using :meth:`~music21.figuredBass.realizer.FiguredBassLine.addElement`. Each Segment is associated with the :class:`~music21.figuredBass.rules.Rules` object provided, meaning that rules are universally applied across all Segments. The number of parts in a realization (including the bass) can be controlled through numParts, and the maximum pitch can likewise be controlled through maxPitch. Returns a :class:`~music21.figuredBass.realizer.Realization`. 

            If this methods is called without having provided any (bassNote, notationString) pairs, a FiguredBassLineException is raised. If only one pair is provided, the Realization will contain :meth:`~music21.figuredBass.segment.Segment.allCorrectConsecutivePossibilities` for the one note. 

            >>> from music21.figuredBass import realizer
            >>> from music21.figuredBass import rules
            >>> from music21 import key
            >>> from music21 import meter
            >>> from music21 import note
            >>> fbLine = realizer.FiguredBassLine(key.Key('B'), meter.TimeSignature('3/4'))
            >>> fbLine.addElement(note.Note('B2'))
            >>> fbLine.addElement(note.Note('C#3'), "6")
            >>> fbLine.addElement(note.Note('D#3'), "6")
            >>> fbRules = rules.Rules()
            >>> r1 = fbLine.realize(fbRules)
            >>> r1.getNumSolutions()
            208 
            >>> fbRules.forbidVoiceOverlap = False
            >>> r2 = fbLine.realize(fbRules)
            >>> r2.getNumSolutions()
            7908 

        .. method:: generateRandomRealization()

            Generates a random realization of a figured bass as a :class:`~music21.stream.Score`, with the default rules set **and** a soprano line limited to stepwise motion. 

            .. note:: Deprecated. Use :meth:`~music21.figuredBass.realizer.FiguredBassLine.realize` which returns a :class:`~music21.figuredBass.realizer.Realization`. Then, call :meth:`~music21.figuredBass.realizer.Realization.generateRandomRealization`. 

        .. method:: showAllRealizations()

            Displays all realizations of a figured bass as a musicxml in external software, with the default rules set **and** a soprano line limited to stepwise motion. 

            .. note:: Deprecated. Use :meth:`~music21.figuredBass.realizer.FiguredBassLine.realize` which returns a :class:`~music21.figuredBass.realizer.Realization`. Then, call :meth:`~music21.figuredBass.realizer.Realization.generateAllRealizations` followed by a call to :meth:`~music21.base.Music21Object.show`. 

            .. warning:: This method is unoptimized, and may take a prohibitive amount of time for a Realization which has more than tens of unique realizations. 

        .. method:: showRandomRealization()

            Displays a random realization of a figured bass as a musicxml in external software, with the default rules set **and** a soprano line limited to stepwise motion. 

            .. note:: Deprecated. Use :meth:`~music21.figuredBass.realizer.FiguredBassLine.realize` which returns a :class:`~music21.figuredBass.realizer.Realization`. Then, call :meth:`~music21.figuredBass.realizer.Realization.generateRandomRealization` followed by a call to :meth:`~music21.base.Music21Object.show`. 


Realization
-----------



.. class:: Realization(**fbLineOutputs)

    Returned by :class:`~music21.figuredBass.realizer.FiguredBassLine` after calling :meth:`~music21.figuredBass.realizer.FiguredBassLine.realize`. Allows for the generation of realizations as a :class:`~music21.stream.Score`. 

    See the :mod:`~music21.figuredBass.examples` module for examples on the generation of realizations. 

    .. note:: A possibility progression is a valid progression through a string of :class:`~music21.figuredBass.segment.Segment` instances. See :mod:`~music21.figuredBass.possibility` for more details on possibilities. 

    **Realization** **attributes**

        .. attribute:: keyboardStyleOutput

            True by default. If True, generated realizations are represented in keyboard style, with two staves. If False, realizations are represented in chorale style with n staves, where n is the number of parts. SATB if n = 4. 

    **Realization** **methods**

        .. method:: getNumSolutions()

            Returns the number of solutions (unique realizations) to a Realization by calculating the total number of paths through a string of :class:`~music21.figuredBass.segment.Segment` movements. This is faster and more efficient than compiling each unique realization into a list, adding it to a master list, and then taking the length of the master list. 

            >>> from music21.figuredBass import examples
            >>> fbLine = examples.exampleB()
            >>> fbRealization = fbLine.realize()
            >>> fbRealization.getNumSolutions()
            422 
            >>> fbLine2 = examples.exampleC()
            >>> fbRealization2 = fbLine2.realize()
            >>> fbRealization2.getNumSolutions()
            833 

        .. method:: generateRandomRealization()

            Generates a random unique realization as a :class:`~music21.stream.Score`. 

        .. method:: generateRandomRealizations(amountToGenerate=20)

            Generates *amountToGenerate* unique realizations as a :class:`~music21.stream.Score`. 

            .. warning:: This method is unoptimized, and may take a prohibitive amount of time if amountToGenerate is more than 100. 

        .. method:: generateAllRealizations()

            Generates all unique realizations as a :class:`~music21.stream.Score`. 

            .. warning:: This method is unoptimized, and may take a prohibitive amount of time for a Realization which has more than 100 solutions. 

        .. method:: getAllPossibilityProgressions()

            Compiles each unique possibility progression, adding it to a master list. Returns the master list. 

            .. warning:: This method is unoptimized, and may take a prohibitive amount of time for a Realization which has more than 200,000 solutions. 

        .. method:: getRandomPossibilityProgression()

            Returns a random unique possibility progression. 

        .. method:: generateRealizationFromPossibilityProgression(possibilityProgression)

            Generates a realization as a :class:`~music21.stream.Score` given a possibility progression. 


