Bartók's *Wandering*
====================

This example reconstructs the last five measures of Bartók's *Wandering* from Mikrokosmos vol. III.  It demonstrates the use of many of the main classes in Abjad. The end result is just a few measures long, but the example covert most of the basic features you'll usually need.

Here is what we want to end up with:

.. image :: images/bartok_final.png

Keep that image in mind as you go through this example.

We will construct the fragment `top-down`, going from the high level containers to the details. We could have done it the other way around, but it will be easier to keep the big picture in mind this way. We encourage you to try rebuilding the example `bottom-down` as an exercise. 
First let's create the high level framework of the score:

<abjad>
piano = PianoStaff([ ])
upper_staff = Staff([ ])
lower_staff = Staff([ ])
piano.append(upper_staff)
piano.append(lower_staff)
</abjad>

Here we created an empty :class:`~abjad.staffgroup.pianostaff.PianoStaff` container and we've assigned it to the `piano` variable. Then we created two :class:`~abjad.Staff` objects and we assigned them to the `upper_staff` and `lower_staff` variables. Finally, we appended the staves to the :class:`~abjad.staffgroup.pianostaff.PianoStaff` container.  

Now let's add some measures to the framework.

<abjad>
m1 = RigidMeasure((2, 4), [ ])
m2 = RigidMeasure((3, 4), [ ])
m3 = RigidMeasure((2, 4), [ ])
m4 = RigidMeasure((2, 4), [ ])
m5 = RigidMeasure((2, 4), [ ])
upper_measures = [m1, m2, m3, m4, m5]
lower_measures = clone.covered(upper_measures)
upper_staff.extend(upper_measures)
lower_staff.extend(lower_measures)
</abjad>

Notice that the `lower_measures` are simply copies of the `upper_measures`. 

.. note::
   The :mod:`~abjad.tools.clone` package houses the different copying functions that Abjad provides for object duplication. The difference between them resides in the way each handles spanners attached to Components during the duplication process. See XXX for details.

Notice also that the measures are added to their corresponding :class:`~abjad.Staff` via the ``extend`` method. 

.. note::
   Remember that ``extend`` is used for appending multiple objects that are grouped together in an iterable (i.e. a list, tuple, set, etc.) while ``append`` is used for single objects.

Now lets actually start adding some notes. Let's begin with the upper staff:


<abjad>
upper_measures[0].extend([Note(i, (1, 8)) for i in [9, 7, 5, 4]])
upper_measures[1].extend(construct.notes([2,7,5,4,2], [(1, 4)]+[(1, 8)]*4))
notes = construct.notes([0,2,4,5,4], [(1, 8), (1, 16), (1, 16), (1, 8), (1, 8)])
upper_measures[2].extend(notes)
upper_measures[3].append(Note(2, (1, 2)))
upper_measures[4].append(Note(2, (1, 2)))
</abjad>

Let's now create the notes for the lower staff. This will be a more intricate process that that needed for the upper staff. Notice that, for the upper staff, we simply added notes directly to the measures. This will not be possible for the lower staff due to the parallel `threads` (voices or melodic lines) found in the last two measures. 

.. note::
   The usual term for a melodic line is `voice`. Generally speaking, the language developed in Abjad uses the term *thread* to refer to this notion. A `thread` however, has a more concrete interpretation in Abjad. Please refer to the :doc:`/chapters/fundamentals/threads/index` section for a complete explanation of `threads`.
   The term Voice (with upper case) we use specifically for either the :class:`~abjad.Voice` class or an instance of the class. 

When two or more melodic lines are simultaneously present in the same :class:`~abjad.Staff`, we need some way of grouping notes to disambiguate the paths of the possible melodic lines. We do this by creating explicit threads via the instantiation of the :class:`~abjad.Voice` class. Here we create two threads: one called `main_voice` the other called `appendix_voice`. The threads are made explicit by instantiating :class:`~abjad.Voice` classes and by naming them appropriately.  

Lets move measure by measure in the construction of the lower staff:

<abjad>
main_voice_m1 = Voice(construct.notes([-1, 2, 0], [(1, 4), (1, 8), (1, 8)]))
main_voice_m1.name = 'main_voice'
lower_measures[0].append(main_voice_m1)
</abjad>

<abjad>
main_voice_m2 = Voice(construct.notes([-1, -3, -4, 0, -2], [(1, 8), (1, 8), (1, 4), (1, 8), (1, 8)]))
main_voice_m2.name = 'main_voice'   
lower_measures[1].append(main_voice_m2)
</abjad>

<abjad>
main_voice_m3 = Voice(construct.notes([-3, -5, -6, -5, -3], [(1, 8), (1, 8), (1, 8), (1, 16), (1, 16)]))
main_voice_m3.name = 'main_voice'   
lower_measures[2].append(main_voice_m3)
</abjad>

Notice that every :class:`~abjad.Voice`  we create is equally named `main_voice` to guarantee the existence of a continuous thread. Many transformations and score traversal operations are possible across threads, so this is another reason why threads are important.  

It is in the last two measures where we suddenly have two simultaneous voices in the lower staff. The new, second :class:`~abjad.Voice` that seems to appear out of nowhere we will label `appendix_voice`.

<abjad>
appendix_voice_m4 = Voice([Note(-1, (1, 2))])
appendix_voice_m4.name = 'appendix_voice'
appendix_voice_m4.voice.number = 1
main_voice_m4 = Voice([Note(-1, (1, 4)), Note(-3, (1, 4))])
main_voice_m4.name = 'main_voice'
main_voice_m4.voice.number = 2
p = Container([appendix_voice_m4, main_voice_m4])
p.parallel = True
lower_measures[3].append(p)
</abjad>

A couple important things to notice: 

1. The `number` property of the `appendix_voice` is set to ``1``, and the `number` property of the `main_voice` is set to ``2``. These determine the direction of the stem for each voice.
2. Because both voices occur simultaneously in the score, we must put them in a parallel :class:`~abjad.Container` to tell Abjad that they indeed run in parallel. Notice the setting of the boolean `parallel` property of the :class:`~abjad.Container` object. It is this :class:`~abjad.Container` that is passed to the measure.

We now do a similar thing for the last measure:

<abjad>
appendix_voice_m5 = Voice([Note(-1, (1, 2))])
appendix_voice_m5.name = 'appendix_voice'
appendix_voice_m5.voice.number = 1
main_voice_m5 =  Voice([Note(-5, (1, 2))])
main_voice_m5.name = 'main_voice'
main_voice_m5.voice.number = 2
p = Container([appendix_voice_m5, main_voice_m5])
p.parallel = True
lower_measures[4].append(p)
</abjad>

Let's see what we have up till now:

<abjad>
write_ly(piano, 'bartok_framework') <hide
show(piano)
</abjad>

Ok, let's add some detail. First, notice that the bottom staff has a treble clef, just like the top staff. Let's change that:

<abjad>
lower_staff.clef.forced = Clef('bass')
</abjad>

Now let's sprinkle some dynamic markings. For the top staff, we will add them to the first note of the first measure and the second note of the second measure. For the bottom staff, we will add dynamic markings to the second note of the first measure and the fourth note of the second measure. Note that because we created Voices inside the measures of the lower staff, we need to index those too:

<abjad>
upper_measures[0][0].dynamics.mark = 'pp'
upper_measures[1][1].dynamics.mark = 'mp'
lower_measures[0][0][1].dynamics.mark = 'pp'
lower_measures[1][0][3].dynamics.mark = 'mp'
</abjad>

Let's also add a double bar line to the end of the piece:

<abjad>
lower_staff.barline.kind = '||'
</abjad>

Let's see how this is coming out:

<abjad>
write_ly(piano, 'bartok_notes') <hide
show(piano)
</abjad>

Notice that the beams of the eighth and sixteenth notes appear as you would usually expect: grouped by beat. We get this for free thanks to LilyPond's default rendering algorithm. This is not, however, the way Bartok notated his score. Let's set the beams as Bartok did, running some across the bar lines: 

<abjad>
Beam(upper_measures[0])
#Beam(upper_measures[1][1:]) <hide 
#Beam(upper_measures[2][0:3]) <hide 
#Beam(upper_measures[2][3:]) <hide 
Beam(lower_staff.leaves[1:5])
Beam(lower_staff.leaves[6:10])
#Beam(lower_staff.leaves[10:13]) <hide 
</abjad>

<abjad>
write_ly(piano, 'bartok_beams') <hide
show(piano)
</abjad>

Now some slurs: 

<abjad>
Slur(upper_staff.leaves[0:5])
Slur(upper_staff.leaves[5:])
Slur(lower_staff.leaves[1:6])
slr = Slur(lower_staff.leaves[6:13] + (main_voice_m4, main_voice_m5))
slr.position = 'down'
</abjad>

Notice that we store the last slur in the `slr` variable to change its ``position`` attribute to ``'down'``. This does what you would expect!

Now dynamic wedges:

<abjad>
Crescendo(upper_staff.leaves[-7:-2])
Decrescendo(upper_staff.leaves[-2:])
</abjad>

...and a `ritardando` marking above the last seven notes of the upper staff:

<abjad>
tx = Text(upper_staff.leaves[-7:])
tx.bound_details__left__text = Markup('ritard.')
</abjad>

And, we almost forgot! Two ties connecting the last notes in the upper and lower staves:

<abjad>
Tie(upper_staff[-2:])
Tie([appendix_voice_m4[0], appendix_voice_m5[0]])
</abjad>

The final result:

<abjad>
write_ly(piano, 'bartok_final') <hide
show(piano)
</abjad>

