Mozart: *Musikalisches Würfelspiel*
===================================

Mozart's dice game is a method for aleatorically generating sixteen-measure-long minuets.  For each measure, two six-sided dice are rolled, and the sum of 
the dice used to look up a measure number in one of two tables (one for each half of the minuet).  The measure number then locates a single measure from a 
collection of musical fragments.  The fragments are concatenated together, and "music" results.

Implementing the dice game in a composition environment is somewhat akin to (although also somewhat more complicated than) the ubiquitous `hello world 
program <http://en.wikipedia.org/wiki/Hello_world_program>`_ which every programming language uses to demonstrate its basic syntax.

.. figure:: images/mozart-tables.png
   :align: center
   :width: 640px

   *Part of a pen-and-paper implementation from the 20th century.*

.. note:: The musical dice game in question (*k516f*) has long been attributed to Mozart, albeit inconclusively.  Its actual provenance is a musicological 
   problem with which we are unconcerned here.

The materials
-------------

At the heart of the dice game is a large collection, *or corpus*, of musical fragments.  Each fragment is a single 3/8 measure, consisting of a treble voice 
and a bass voice.  Traditionally, these fragments are stored in a "score", or "table of measures", and located via two tables of measure numbers, which act 
as lookups, indexing into that collection.

Duplicate measures in the original corpus are common.  Notably, the 8th measure - actually a pair of measures represent the first and second alternate ending 
of the first half of the minuet - are always identical.  The last measure of the piece is similarly limited - there are only two possibilities rather than 
the usual eleven (for the numbers 2 to 12, being all the possible sums of two 6-sided dice).

How might we store this corpus compactly?

Some basic musical information in Abjad can be stored as strings, rather than actual collections of class instances.  Abjad can parse simple LilyPond strings 
via :py:func:`abjad.tools.iotools.parse_lilypond_input_string`, which interprets a subset of LilyPond syntax, and understands basic concepts like notes, 
chords, rests and skips, as well as beams, slurs, ties, and articulations.

::

	lily_string = "c'4 ( d'4 <cs' e'>8 ) -. r8 <g' b' d''>4 ^\marcato ~ <g' b' d''>1"
	abjad> parsed_result = iotools.parse_lilypond_input_string(lily_string)
	LilyPond file written to 'mozart-parsing-example.ly' ...
	abjad> show(parsed_result)

.. image:: images/mozart-parsing-example.png

So, instead of storing our musical information as Abjad components, we'll represent each fragment in the corpus as a pair of strings: one representing the 
bass voice contents, and the other representing the treble.  This pair of strings can be packaged together into a collection.  For this implementation, we'll 
package them into a dictionary.  Python dictionaries are cheap, and often provide more clarity than lists; the composer does not have to rely on remembering 
a convention for what data should appear in which position in a list - they can simply label that data semantically.  In our musical dictionary, the treble 
voice will use the key 't' and the bass voice will use the key 'b'.

::

	abjad> fragment = {'t': "g''8 ( e''8 c''8 )", 'b': '<c e>4 r8'}


Instead of relying on measure number tables to find our fragments - as in the original implementation, we'll package our fragment dictionaries into a list of 
lists of fragment dictionaries.  That is to say, each of the sixteen measures in the piece will be represented by a list of fragment dictionaries.  
Furthermore, the 8th measure, which breaks the pattern, will simply be a list of two fragment dictionaries.  Structuring our information in this way lets 
us avoid using measure number tables entirely; Python's list-indexing affordances will take care of that for us.  The complete corpus looks like this:


::

    measures = [
        [ # measure 1 choices
            {'b': 'c4 r8', 't': "e''8 c''8 g'8"},
            {'b': '<c e>4 r8', 't': "g'8 c''8 e''8"},
            {'b': '<c e>4 r8', 't': "g''8 ( e''8 c''8 )"},
            {'b': '<c e>4 r8', 't': "c''16 b'16 c''16 e''16 g'16 c''16"},
            {'b': '<c e>4 r8', 't': "c'''16 b''16 c'''16 g''16 e''16 c''16"},
            {'b': 'c4 r8', 't': "e''16 d''16 e''16 g''16 c'''16 g''16"},
            {'b': '<c e>4 r8', 't': "g''8 f''16 e''16 d''16 c''16"},
            {'b': '<c e>4 r8', 't': "e''16 c''16 g''16 e''16 c'''16 g''16"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "c''8 g'8 e''8"},
            {'b': '<c e>4 r8', 't': "g''8 c''8 e''8"},
            {'b': 'c8 c8 c8', 't': "<e' c''>8 <e' c''>8 <e' c''>8"},
        ],
        [ # measure 2 choices
            {'b': 'c4 r8', 't': "e''8 c''8 g'8"},
            {'b': '<c e>4 r8', 't': "g'8 c''8 e''8"},
            {'b': '<c e>4 r8', 't': "g''8 e''8 c''8"},
            {'b': '<e g>4 r8', 't': "c''16 g'16 c''16 e''16 g'16 c''16"},
            {'b': '<c e>4 r8', 't': "c'''16 b''16 c'''16 g''16 e''16 c''16"},
            {'b': 'c4 r8', 't': "e''16 d''16 e''16 g''16 c'''16 g''16"},
            {'b': '<c e>4 r8', 't': "g''8 f''16 e''16 d''16 c''16"},
            {'b': '<c e>4 r8', 't': "c''16 g'16 e''16 c''16 g''16 e''16"},
            {'b': '<c e>4 r8', 't': "c''8 g'8 e''8"},
            {'b': '<c e>4 <c g>8', 't': "g''8 c''8 e''8"},
            {'b': 'c8 c8 c8', 't': "<e' c''>8 <e' c''>8 <e' c''>8"},
        ],
        [ # measure 3 choices
            {'b': '<b, g>4 g,8', 't': "d''16 e''16 f''16 d''16 c''16 b'16"},
            {'b': 'g,4 r8', 't': "b'8 d''8 g''8"},
            {'b': 'g,4 r8', 't': "b'8 d''16 b'16 a'16 g'16"},
            {'b': '<g b>4 r8', 't': "f''8 d''8 b'8"},
            {'b': '<b, d>4 r8', 't': "g''16 fs''16 g''16 d''16 b'16 g'16"},
            {'b': '<g b>4 r8', 't': "f''16 e''16 f''16 d''16 c''16 b'16"},
            {'b': '<g, g>4 <b, g>8', 't': "b'16 c''16 d''16 e''16 f''16 d''16"},
            {'b': 'g8 g8 g8', 't': "<b' d''>8 <b' d''>8 <b' d''>8"},
            {'b': 'g,4 r8', 't': "b'16 c''16 d''16 b'16 a'16 g'16"},
            {'b': 'b,4 r8', 't': "d''8 ( b'8 g'8 )"},
            {'b': 'g4 r8', 't': "b'16 a'16 b'16 c''16 d''16 b'16"},
        ],
        [ # measure 4 choices
            {'b': '<c e>4 r8', 't': "c''16 b'16 c''16 e''16 g'8"},
            {'b': 'c4 r8', 't': "e''16 c''16 b'16 c''16 g'8"},
            {'b': '<e g>4 r8', 't': "c''8 ( g'8 e'8 )"},
            {'b': '<e g>4 r8', 't': "c''8 e''8 g'8"},
            {'b': '<e g>4 r8', 't': "c''16 b'16 c''16 g'16 e'16 c'16"},
            {'b': '<c e>4 r8', 't': "c''8 c''16 d''16 e''8"},
            {'b': 'c4 r8', 't': "<c'' e''>8 <c'' e''>16 <d'' f''>16 <e'' g''>8"},
            {'b': '<e g>4 r8', 't': "c''8 e''16 c''16 g'8"},
            {'b': '<e g>4 r8', 't': "c''16 g'16 e''16 c''16 g''8"},
            {'b': '<e g>4 r8', 't': "c''8 e''16 c''16 g''8"},
            {'b': '<e g>4 r8', 't': "c''16 e''16 c''16 g'16 e'8"},
        ],
        [ # measure 5 choices
            {'b': 'c4 r8', 't': "fs''8 a''16 fs''16 d''16 fs''16"},
            {'b': 'c8 c8 c8', 't': "<fs' d''>8 <d'' fs''>8 <fs'' a''>8"},
            {'b': 'c4 r8', 't': "d''16 a'16 fs''16 d''16 a''16 fs''16"},
            {'b': 'c8 c8 c8', 't': "<fs' d''>8 <fs' d''>8 <fs' d''>8"},
            {'b': 'c4 r8', 't': "d''8 a'8 ^\\turn fs''8"},
            {'b': 'c4 r8', 't': "d''16 cs''16 d''16 fs''16 a''16 fs''16"},
            {'b': '<c a>4 <c a>8', 't': "fs''8 a''8 d''8"},
            {'b': '<c fs>8 <c fs>8 <c a>8', 't': "a'8 a'16 d''16 fs''8"},
            {'b': 'c8 c8 c8', 't': "<d'' fs''>8 <d'' fs''>8 <d'' fs''>8"},
            {'b': '<c d>8 <c d>8 <c d>8', 't': "fs''8 fs''16 d''16 a''8"},
            {'b': '<c a>4 r8', 't': "fs''16 d''16 a'16 a''16 fs''16 d''16"},
        ],
        [ # measure 6 choices
            {'b': '<b, d>8 <b, d>8 <b, d>8', 't': "g''16 fs''16 g''16 b''16 d''8"},
            {'b': '<b, d>4 r8', 't': "g''8 b''16 g''16 d''16 b'16"},
            {'b': '<b, d>4 r8', 't': "g''8 b''8 d''8"},
            {'b': '<b, g>4 r8', 't': "a'8 fs'16 g'16 b'16 g''16"},
            {'b': '<b, d>4 <b, g>8', 't': "g''16 fs''16 g''16 d''16 b'16 g'16"},
            {'b': 'b,4 r8', 't': "g''8 b''16 g''16 d''16 g''16"},
            {'b': '<b, g>4 r8', 't': "d''8 g''16 d''16 b'16 d''16"},
            {'b': '<b, g>4 r8', 't': "d''8 d''16 g''16 b''8"},
            {'b': '<b, d>8 <b, d>8 <b, g>8', 't': "a''16 g''16 fs''16 g''16 d''8"},
            {'b': '<b, d>4 r8', 't': "g''8 g''16 d''16 b''8"},
            {'b': '<b, d>4 r8', 't': "g''16 b''16 g''16 d''16 b'8"},
        ],
        [ # measure 7 choices
            {'b': 'c8 d8 d,8', 't': "e''16 c''16 b'16 a'16 g'16 fs'16"},
            {'b': 'c8 d8 d,8', 't': "a'16 e''16 <b' d''>16 <a' c''>16 <g' b'>16 <fs' a'>16"},
            {'b': 'c8 d8 d,8', 't': "<b' d''>16 ( <a' c''>16 ) <a' c''>16 ( <g' b'>16 ) <g' b'>16 ( <fs' a'>16 )"},
            {'b': 'c8 d8 d,8', 't': "e''16 g''16 d''16 c''16 b'16 a'16"},
            {'b': 'c8 d8 d,8', 't': "a'16 e''16 d''16 g''16 fs''16 a''16"},
            {'b': 'c8 d8 d,8', 't': "e''16 a''16 g''16 b''16 fs''16 a''16"},
            {'b': 'c8 d8 d,8', 't': "c''16 e''16 g''16 d''16 a'16 fs''16"},
            {'b': 'c8 d8 d,8', 't': "e''16 g''16 d''16 g''16 a'16 fs''16"},
            {'b': 'c8 d8 d,8', 't': "e''16 c''16 b'16 g'16 a'16 fs'16"},
            {'b': 'c8 d8 d,8', 't': "e''16 c'''16 b''16 g''16 a''16 fs''16"},
            {'b': 'c8 d8 d,8', 't': "a'8 d''16 c''16 b'16 a'16"},
        ],
        [ # measure 8 choices (always using both)
            {'b': 'g,8 g16 f16 e16 d16', 't': "<g' b' d'' g''>4 r8"},
            {'b': 'g,8 b16 g16 fs16 e16', 't': "<g' b' d'' g''>4 r8"}],
        ],
        [ # measure 9 choices
            {'b': 'd4 c8', 't': "fs''8 a''16 fs''16 d''16 fs''16"},
            {'b': '<d fs>4 r8', 't': "d''16 a'16 d''16 fs''16 a''16 fs''16"},
            {'b': '<d a>8 <d fs>8 <c d>8', 't': "fs''8 a''8 fs''8"},
            {'b': '<c a>4 <c a>8', 't': "fs''16 a''16 d'''16 a''16 fs''16 a''16"},
            {'b': 'd4 c8', 't': "d'16 fs'16 a'16 d''16 fs''16 a''16"},
            {'b': 'd,16 d16 cs16 d16 c16 d16', 't': "<a' d'' fs''>8 fs''4 ^\\tr"},
            {'b': '<d fs>4 <c fs>8', 't': "a''8 ( fs''8 d''8 )"},
            {'b': '<d fs>4 <c fs>8', 't': "d'''8 a''16 fs''16 d''16 a'16"},
            {'b': '<d fs>4 r8', 't': "d''16 a'16 d''8 fs''8"},
            {'b': '<c a>4 <c a>8', 't': "fs''16 d''16 a'8 fs''8"},
            {'b': '<d fs>4 <c a>8', 't': "a'8 d''8 fs''8"},
        ],
        [ # measure 10 choices
            {'b': '<b, g>4 r8', 't': "g''8 b''16 g''16 d''8"},
            {'b': 'b,16 d16 g16 d16 b,16 g,16', 't': "g''8 g'8 g'8"},
            {'b': 'b,4 r8', 't': "g''16 b''16 g''16 b''16 d''8"},
            {'b': '<b, d>4 <b, d>8', 't': "a''16 g''16 b''16 g''16 d''16 g''16"},
            {'b': '<b, d>4 <b, d>8', 't': "g''8 d''16 b'16 g'8"},
            {'b': '<b, d>4 <b, d>8', 't': "g''16 b''16 d'''16 b''16 g''8"},
            {'b': '<b, d>4 r8', 't': "g''16 b''16 g''16 d''16 b'16 g'16"},
            {'b': '<b, d>4 <b, d>8', 't': "g''16 d''16 g''16 b''16 g''16 d''16"},
            {'b': '<b, d>4 <b, g>8', 't': "g''16 b''16 g''8 d''8"},
            {'b': 'g,16 b,16 g8 b,8', 't': "g''8 d''4 ^\\tr"},
            {'b': 'b,4 r8', 't': "g''8 b''16 d'''16 d''8"},
        ],
        [ # measure 11 choices
            {'b': "c16 e16 g16 e16 c'16 c16", 't': "<c'' e''>8 <c'' e''>8 <c'' e''>8"},
            {'b': 'e4 e16 c16', 't': "c''16 g'16 c''16 e''16 g''16 <c'' e''>16"},
            {'b': '<c g>4 <c e>8', 't': "e''8 g''16 e''16 c''8"},
            {'b': '<c g>4 r8', 't': "e''16 c''16 e''16 g''16 c'''16 g''16"},
            {'b': '<c g>4 <c g>8', 't': "e''16 g''16 c'''16 g''16 e''16 c''16"},
            {'b': 'c16 b,16 c16 d16 e16 fs16', 't': "<g' c'' e''>8 e''4 ^\\tr"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "e''8 c''8 g'8"},
            {'b': '<c g>4 <c e>8', 't': "e''8 c''16 e''16 g''16 c'''16"},
            {'b': '<c g>4 <c e>8', 't': "e''16 c''16 e''8 g''8"},
            {'b': '<c g>4 <c g>8', 't': "e''16 c''16 g'8 e''8"},
            {'b': '<c g>4 <c e>8', 't': "e''8 ( g''8 c'''8 )"},
        ],
        [ # measure 12 choices
            {'b': 'g4 g,8', 't': "<c'' e''>8 <b' d''>8 r8"},
            {'b': '<g, g>4 g8', 't': "d''16 b'16 g'8 r8"},
            {'b': 'g8 g,8 r8', 't': "<c'' e''>8 <b' d''>16 <g' b'>16 g'8"},
            {'b': 'g4 r8', 't': "e''16 c''16 d''16 b'16 g'8"},
            {'b': 'g8 g,8 r8', 't': "g''16 e''16 d''16 b'16 g'8"},
            {'b': 'g4 g,8', 't': "b'16 d''16 g''16 d''16 b'8"},
            {'b': 'g8 g,8 r8', 't': "e''16 c''16 b'16 d''16 g''8"},
            {'b': '<g b>4 r8', 't': "d''16 b''16 g''16 d''16 b'8"},
            {'b': '<b, g>4 <b, d>8', 't': "d''16 b'16 g'8 g''8"},
            {'b': 'g16 fs16 g16 d16 b,16 g,16', 't': "d''8 g'4"},
        ],
        [ # measure 13 choices
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "e''8 c''8 g'8"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "g'8 c''8 e''8"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "g''8 e''8 c''8"},
            {'b': '<c e>4 <e g>8', 't': "c''16 b'16 c''16 e''16 g'16 c''16"},
            {'b': '<c e>4 <c g>8', 't': "c'''16 b''16 c'''16 g''16 e''16 c''16"},
            {'b': '<c g>4 <c e>8', 't': "e''16 d''16 e''16 g''16 c'''16 g''16"},
            {'b': '<c e>4 r8', 't': "g''8 f''16 e''16 d''16 c''16"},
            {'b': '<c e>4 r8', 't': "c''16 g'16 e''16 c''16 g''16 e''16"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "c''8 g'8 e''8"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "g''8 c''8 e''8"},
            {'b': 'c8 c8 c8', 't': "<e' c''>8 <e' c''>8 <e' c''>8"},
        ],
        [ # measure 14 choices
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "e''8 ( c''8 g'8 )"},
            {'b': '<c e>4 <c g>8', 't': "g'8 ( c''8 e''8 )"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "g''8 e''8 c''8"},
            {'b': '<c e>4 <c e>8', 't': "c''16 b'16 c''16 e''16 g'16 c''16"},
            {'b': '<c e>4 r8', 't': "c'''16 b''16 c'''16 g''16 e''16 c''16"},
            {'b': '<c g>4 <c e>8', 't': "e''16 d''16 e''16 g''16 c'''16 g''16"},
            {'b': '<c e>4 <e g>8', 't': "g''8 f''16 e''16 d''16 c''16"},
            {'b': '<c e>4 r8', 't': "c''16 g'16 e''16 c''16 g''16 e''16"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "c''8 g'8 e''8"},
            {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "g''8 c''8 e''8"},
            {'b': 'c8 c8 c8', 't': "<e' c''>8 <e' c''>8 <e' c''>8"},
        ],
        [ # measure 15 choices
            {'b': "<f a>4 <g d'>8", 't': "d''16 f''16 d''16 f''16 b'16 d''16"},
            {'b': 'f4 g8', 't': "d''16 f''16 a''16 f''16 d''16 b'16"},
            {'b': 'f4 g8', 't': "d''16 f''16 a'16 d''16 b'16 d''16"},
            {'b': 'f4 g8', 't': "d''16 ( cs''16 ) d''16 f''16 g'16 b'16"},
            {'b': 'f8 d8 g8', 't': "f''8 d''8 g''8"},
            {'b': 'f16 e16 d16 e16 f16 g16', 't': "f''16 e''16 d''16 e''16 f''16 g''16"},
            {'b': 'f16 e16 d8 g8', 't': "f''16 e''16 d''8 g''8"},
            {'b': 'f4 g8', 't': "f''16 e''16 d''16 c''16 b'16 d''16"},
            {'b': 'f4 g8', 't': "f''16 d''16 a'8 b'8"},
            {'b': 'f4 g8', 't': "f''16 a''16 a'8 b'16 d''16"},
            {'b': 'f4 g8', 't': "a'8 f''16 d''16 a'16 b'16"},
        ],
        [ # measure 16 choices
            {'b': 'c8 g,8 c,8', 't': "c''4 r8"},
            {'b': 'c4 c,8', 't': "c''8 c'8 r8"},
        ],
    ]

We can then use the :py:func:`~abjad.tools.iotools.parse_lilypond_input_string` function we saw earlier to "build" the treble and bass components of a 
measure like this:

::

    def build_one_mozart_measure(measure_dict):
        # parse the contents of a measure definition dictionary
        treble = iotools.parse_lilypond_input_string(measure_dict['t'])
        bass = iotools.parse_lilypond_input_string(measure_dict['b'])
        return treble, bass

::

	my_measure_dict = {'b': 'c4 ^\tr r8', 't': "e''8 ( c''8 g'8 )"}
	abjad> treble, bass = build_one_mozart_measure(my_measure_dict)
	abjad> f(treble)
	{
		e''8 (
		c''8
		g'8 )
	}
	abjad> f(bass)
	{
		c4 ^\tr
		r8
	}


The structure
-------------

After storing all of the musical fragments into a corpus, concatenating those elements into a musical structure is relatively trivial.  We'll use the 
:py:func:`~random.choice` function from Python's `random` module.  :py:func:`random.choice` randomly selects one element from an input list.

::

	abjad> import random
	abjad> my_list = [1, 'b', 3]
	abjad> my_result = [random.choice(my_list) for i in range(20)]
	abjad> print my_result
	[1, 3, 3, 3, 1, 1, 1, 'b', 3, 'b', 1, 'b', 'b', 1, 3, 'b', 3, 1, 'b', 1]


Our corpus is a list comprising sixteen sublists, one for each measure in the minuet.  To build our musical structure, we can simply iterate through the 
corpus and call `choice` on each sublist, appending the chosen results to another list.  The only catch is that the *eighth* measure of our minuet is 
actually the first-and-second-ending for the repeat of the first phrase.  The sublist of the corpus for measure eight contains *only* the first and second 
ending definitions, and both of those measures should appear in the final piece, always in the same order.  We'll have to intercept that sublist while we 
iterate through the corpus and apply some different logic.

The easist way to intercept measure eight is to use the Python builtin `enumerate`, which allows you to iterate through a collection while also 
getting the index of each element in that collection:

::

    def choose_mozart_measures( ):
        chosen_measures = [ ]
        for i, choices in enumerate(measures):
            if i == 7: # get both alternative endings for mm. 8
                chosen_measures.extend(choices)
            else:
                choice = random.choice(choices)
                chosen_measures.append(choice)
        return chosen_measures

.. note:: In `choose_mozart_measures` we test for index *7*, rather then *8*, because list indices count from *0* instead of *1*.

The result will be a *seventeen*-item-long list of measure definitions:

::

	abjad> choices = choose_mozart_measures( )
	abjad> for i, measure in enumerate(choices): print i, measure
	0 {'b': '<c e>4 r8', 't': "e''16 c''16 g''16 e''16 c'''16 g''16"}
	1 {'b': 'c8 c8 c8', 't': "<e' c''>8 <e' c''>8 <e' c''>8"}
	2 {'b': 'g,4 r8', 't': "b'8 d''8 g''8"}
	3 {'b': '<e g>4 r8', 't': "c''16 g'16 e''16 c''16 g''8"}
	4 {'b': 'c4 r8', 't': "d''8 a'8 ^\\turn fs''8"}
	5 {'b': '<b, g>4 r8', 't': "a'8 fs'16 g'16 b'16 g''16"}
	6 {'b': 'c8 d8 d,8', 't': "e''16 a''16 g''16 b''16 fs''16 a''16"}
	7 {'b': 'g,8 g16 f16 e16 d16', 't': "<g' b' d'' g''>4 r8"}
	8 {'b': 'g,8 b16 g16 fs16 e16', 't': "<g' b' d'' g''>4 r8"}
	9 {'b': 'd4 c8', 't': "d'16 fs'16 a'16 d''16 fs''16 a''16"}
	10 {'b': '<b, d>4 <b, g>8', 't': "g''16 b''16 g''8 d''8"}
	11 {'b': '<c g>4 <c g>8', 't': "e''16 g''16 c'''16 g''16 e''16 c''16"}
	12 {'b': 'g4 g,8', 't': "b'16 d''16 g''16 d''16 b'8"}
	13 {'b': 'c8 c8 c8', 't': "<e' c''>8 <e' c''>8 <e' c''>8"}
	14 {'b': '<c e>16 g16 <c e>16 g16 <c e>16 g16', 't': "e''8 ( c''8 g'8 )"}
	15 {'b': 'f4 g8', 't': "f''16 d''16 a'8 b'8"}
	16 {'b': 'c8 g,8 c,8', 't': "c''4 r8"}


The score
---------

Now that we have our raw materials, and a way to organize them, we can start building our score.  The tricky part here is figuring out how to implement 
LilyPond's repeat structure in Abjad.  LilyPond structures its repeats something like this:

::

    \repeat volta n {
        music to be repeated
    }

    \alternative {
        { ending 1 }
        { ending 2 }
        { ending n }
    }
    
    ...music after the repeat...

What you see above is really just two containers, each with a little text ("\repeat volta n" and "alternative") prepended to their opening curly brace.  To 
create that structure in Abjad, we'll need to use the :py:class:`~abjad.tools.marktools.LilyPondCommandMark` class, which allows you to place LilyPond 
commands like "\break" relative to any score component:

::

	abjad> con = Container("c'4 d'4 e'4 f'4")
	abjad> marktools.LilyPondCommandMark('before-the-container', 'before')(con)
	abjad> marktools.LilyPondCommandMark('after-the-container', 'after')(con)
	abjad> marktools.LilyPondCommandMark('opening-of-the-container', 'opening')(con)
	abjad> marktools.LilyPondCommandMark('closing-of-the-container', 'closing')(con)
	abjad> marktools.LilyPondCommandMark('to-the-right-of-a-note', 'right')(con[2])
	abjad> f(con)
	\before-the-container
	{
		\opening-of-the-container
		c'4
		d'4
		e'4 \to-the-right-of-a-note
		f'4
		\closing-of-the-container
	}
	\after-the-container


Notice the second argument to each :py:class:`~abjad.tools.marktools.LilyPondCommandMark` above, like `before` and `closing`.  These are format slot 
indications, which control where the command is placed in the LilyPond code relative to the score element it is attached to.  To mimic LilyPond's repeat 
syntax, we'll have to create two :py:class:`~abjad.tools.marktools.LilyPondCommandMark` instances, both using the "before" format slot, insuring that their 
command is placed before their container's opening curly brace.

Now let's take a look at the code that puts our score together:

::

    def build_mozart_piano_staff( ):
        treble_staff = Staff([ ])
        bass_staff = Staff([ ])

        # select the measures to use
        choices = choose_mozart_measures( )

        # create and populate the volta containers
        treble_volta = Container([ ])
        bass_volta = Container([ ])
        for choice in choices[:7]:
            treble, bass = build_one_mozart_measure(choice)
            treble_volta.append(treble)
            bass_volta.append(bass)

        # add marks to the volta containers
        marktools.LilyPondCommandMark('repeat volta 2', 'before')(treble_volta)
        marktools.LilyPondCommandMark('repeat volta 2', 'before')(bass_volta)

        # add the volta containers to our staves
        treble_staff.append(treble_volta)
        bass_staff.append(bass_volta)

        # create and populate the alternative ending containers
        treble_alternative = Container([ ])
        bass_alternative = Container([ ])
        for choice in choices[7:9]:
            treble, bass = build_one_mozart_measure(choice)
            treble_alternative.append(treble)
            bass_alternative.append(bass)

        # add marks to the alternative containers
        marktools.LilyPondCommandMark('alternative', 'before')(treble_alternative)
        marktools.LilyPondCommandMark('alternative', 'before')(bass_alternative)

        # add the alternative containers to our staves
        treble_staff.append(treble_alternative)
        bass_staff.append(bass_alternative)

        # create the remaining measures
        for choice in choices[9:]:
            treble, bass = build_one_mozart_measure(choice)
            treble_staff.append(treble)
            bass_staff.append(bass)

        # add meter
        contexttools.TimeSignatureMark((3, 8))(treble_staff)

        # add bass clef
        contexttools.ClefMark('bass')(bass_staff)

        # add the final double bar line at the end of each final measure
        marktools.BarLine('|.')(treble_staff[-1])
        marktools.BarLine('|.')(bass_staff[-1])

        # combine into a PianoStaff           
        piano_staff = scoretools.PianoStaff([treble_staff, bass_staff])

        # add an instrument name via contexttools.InstrumentMark
        contexttools.InstrumentMark('Katzenklavier', 'kk.',
            target_context = scoretools.PianoStaff)(piano_staff)

        return piano_staff

::

	abjad> piano_staff = build_mozart_piano_staff( )
	LilyPond file written to 'mozart-piano-staff.ly' ...
	abjad> show(piano_staff)

.. image:: images/mozart-piano-staff.png

.. note:: Our instrument name got cut off!  Looks like we need to do a little formatting.  Keep reading...

The document
------------

As you can see above, we've now got our randomized minuet.  However, we can still go a bit further.  LilyPond provides a wide variety of settings for 
controlling the overall *look* of a musical document, often through its `\header`, `\layout` and `\paper` blocks.  Abjad, in turn, gives us object-oriented 
access to these settings through the its `lilypondfiletools` module.

We'll use :py:func:`abjad.tools.lilypondfiletools.make_basic_lilypond_file` to wrap our :py:class:`~abjad.tools.scoretools.PianoStaff` inside a
:py:class:`~abjad.tools.lilypondfiletools.LilyPondFile` instance.  From there we can access the other "blocks" of our document to add a title, a composer's name, 
change the global staff size, paper size, staff spacing and so forth.

::

    def build_mozart_lily(piano_staff):

        # wrap the PianoStaff with a LilyPondFile
        lily = lilypondfiletools.make_basic_lilypond_file(piano_staff)

        # create some markup to use in our header block
        title = markuptools.Markup('\\bold \\sans "Ein Musikalisches Wuerfelspiel"')
        composer = schemetools.SchemeString("W. A. Mozart (maybe?)")

        # change various settings 
        lily.global_staff_size = 12
        lily.header_block.title = title
        lily.header_block.composer = composer
        lily.layout_block.ragged_right = True
        lily.paper_block.markup_system_spacing__basic_distance = 8
        lily.paper_block.paper_width = 180
    
        return lily

::

	abjad> lily = build_mozart_lily(piano_staff)
	abjad> print lily
	LilyPondFile(PianoStaff<<2>>)


::

	abjad> print lily.header_block
	HeaderBlock(2)
	abjad> f(lily.header_block)
	\header {
		composer = #"W. A. Mozart (maybe?)"
		title = \markup { \bold \sans "Ein Musikalisches Wuerfelspiel" }
	}


::

	abjad> print lily.layout_block
	LayoutBlock(1)
	abjad> f(lily.layout_block)
	\layout {
		ragged-right = ##t
	}


::

	abjad> print lily.paper_block
	PaperBlock(2)
	abjad> f(lily.paper_block)
	\paper {
		markup-system-spacing #'basic-distance = #20
		paper-width = #180
	}


And now the final result:

::

	LilyPond file written to 'mozart-lily.ly' ...
	abjad> show(lily)

.. image:: images/mozart-lily.png
