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




    >>> 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:: inKey

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


        .. attribute:: inTime

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


    **FiguredBassLine** **methods**

        .. method:: addElement(bassObject, 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 import *
            >>> 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





            >>> from music21 import corpus
            >>> sBach = corpus.parse('bach/bwv307')
            >>> sBach['bass'].measure(0).show("text")
            {0.0} <music21.clef.BassClef>
            {0.0} <music21.key.KeySignature of 2 flats>
            {0.0} <music21.meter.TimeSignature 4/4>
            {0.0} <music21.note.Note B->
            {0.5} <music21.note.Note C>
            >>> fbLine = realizer.figuredBassFromStream(sBach['bass'])
            >>> fbLine.generateBassLine().measure(1).show("text")
            {0.0} <music21.clef.BassClef>
            {0.0} <music21.key.KeySignature of 2 flats>
            {0.0} <music21.meter.TimeSignature 4/4>
            {3.0} <music21.note.Note B->
            {3.5} <music21.note.Note C>



        .. 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 import *
            >>> 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:: overlayPart(music21Part)

            No documentation.


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


            generates the segmentList from an fbList, including any overlayed Segments



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




