
    3j                       d Z ddlmZ ddlZddlZddlmZ ddlmZ ddlm	Z	 ddlm
Z
 ddlmZ dd	lmZ  ej                  d
      Z G d de	j                        Z G d dej"                        Zi ddddg dfddddg dfddddg dfddddg dfd ddd!g d"fd#dd$d%g d&fd'dd(d)g d*fd+d,d-d.g d/fd0dd1d2g d3fd4d,d5d6g d7fd8dd9d:g d;fd<dd=d>g d?fd@dddAg dBfdCddDdEg dFfdGddHdIg dJfdKddLdMg dNfdOdddPg dQfi dRddSd)g dTfdUddVdWg dXfdYddZd[g d\fd]dd^d_g d`fdaddbdcg ddfdedddfg dgfdhddidjg dkfdlddidmg dnfdoddidpg dqfdrddsdtg dufdvddidwg dxfdydddzg d{fd|d,dd}g d~fddddg dfddddg dfddddg dfddddg dfi ddddg dfddddg dfddddg dfddddg dfddddg dfdd,ddg dfddddg dfdd,ddg dfddddg dfddddg dfddddg dfddddg dfdddsdg dfddddg dfddddg dĢfddddg dȢfddddg d̢fi ddddg dϢfddddg dҢfdd,ddg dբfdd,ddg dآfddddg dܢfddddg dfddddg dfddddg dfdddsdg dfddddg dfddddg dfddddg dfdd,ddg dfddddg dfdddd g dfddddg dfdd,ddg dfddd	g d
fdddg dfdddg dfdZ G d dej"                        Z G d de      Z G d de      Zd Zd ZddZ G d dej4                        ZeeeeeeegZedk(  rddlZ ej<                  e       yy(  a  
This module defines objects for defining and manipulating structures
common to serial and/or twelve-tone music,
including :class:`~music21.serial.ToneRow` subclasses.

Serial searching methods that were previously here have been moved to
:mod:`~music21.search.serial`.
    )annotationsN)chord)environment)exceptions21)notepitch)streamserialc                      e Zd Zy)SerialExceptionN)__name__
__module____qualname__     ;/DATA/.local/lib/python3.12/site-packages/music21/serial.pyr   r   #   s    r   r   c                  (     e Zd ZdZd Z fdZ xZS )TwelveToneMatrixai  
    An object representation of a 2-dimensional array of 12 pitches.
    Internal representation is as a :class:`~music21.stream.Stream`,
    which stores 12 Streams, each Stream a horizontal row of pitches
    in the matrix.

    This object is commonly used by calling the
    :meth:`~music21.stream.TwelveToneRow.matrix` method of
    :class:`~music21.stream.TwelveToneRow` (or a subclass).

    >>> ttr = serial.TwelveToneRow([0, 2, 11, 7, 8, 3, 9, 1, 4, 10, 6, 5])
    >>> aMatrix = ttr.matrix()
    >>> print(aMatrix)
      0  2  B  7  8  3  9  1  4  A  6  5
      A  0  9  5  6  1  7  B  2  8  4  3
      1  3  0  8  9  4  A  2  5  B  7  6
      5  7  4  0  1  8  2  6  9  3  B  A
      4  6  3  B  0  7  1  5  8  2  A  9
      9  B  8  4  5  0  6  A  1  7  3  2
      3  5  2  A  B  6  0  4  7  1  9  8
      B  1  A  6  7  2  8  0  3  9  5  4
      8  A  7  3  4  B  5  9  0  6  2  1
      2  4  1  9  A  5  B  3  6  0  8  7
      6  8  5  1  2  9  3  7  A  4  0  B
      7  9  6  2  3  A  4  8  B  5  1  0

    >>> repr(aMatrix)
    '<music21.serial.TwelveToneMatrix for [<music21.serial.TwelveToneRow row-1>]>'

    >>> fourthQuartetMatrix = serial.getHistoricalRowByName('SchoenbergOp37').matrix()
    >>> repr(fourthQuartetMatrix)
    '<music21.serial.TwelveToneMatrix for
         [<music21.serial.HistoricalTwelveToneRow Schoenberg Op. 37 Fourth String Quartet>]>'
    c                   g }| D ]h  }g }|D ]?  }|j                  t        |j                  j                        j	                  d             A |j                  dj                  |             j dj                  |      S )z?
        Return a string representation of the matrix.
            
)appendstrr	   pitchClassStringrjustjoin)selfretrowFormmsgns        r   __str__zTwelveToneMatrix.__str__L   sl     GC

3qww778>>qAB JJrwws|$	 
 yy~r   c                x    | r*t        | d   t              r	d| d    dS t        |          S t        |          S )Nr   zfor [])
isinstanceToneRowsuper_reprInternal)r   	__class__s    r   r*   zTwelveToneMatrix._reprInternalX   sC    $q'7+tAwiq))w,..7(**r   )r   r   r   __doc__r$   r*   __classcell__r+   s   @r   r   r   (   s    !F
+ +r   r   
WebernOp29WebernzOp. 29z	Cantata I)r                        
   	   r      
WebernOp28zOp. 28zString Quartet)r3   r   r   r2   r7   r6   r5   r4   r9   r:   r1   r8   SchoenbergOp24Mvmt5
SchoenbergzOp. 24zSerenade, Mvt. 5, "Tanzscene")r9   r8   r   r   r5   r7   r4   r6   r:   r1   r3   r2   SchoenbergOp24Mvmt4zSerenade, Mvt. 4, "Sonett")r5   r2   r   r1   r   r3   r:   r7   r9   r4   r6   r8   SchoenbergJakobsleiterzDie Jakobsleiter)r3   r2   r4   r5   r:   r6   r   r   r1   r8   r7   r9   SchoenbergOp27No4zOp. 27 No. 4z#Four Pieces for Mixed Chorus, No. 4)r3   r   r8   r7   r:   r5   r1   r   r2   r9   r4   r6   
WebernOp23zOp. 23zThree Songs)r:   r   r6   r5   r8   r7   r2   r4   r3   r   r9   r1   BergLuluActIIScene1BergzLulu, Act II, Scene 1z0Perm. (Every 5th Note Of Transposed Primary Row))r8   r6   r3   r   r9   r2   r5   r1   r4   r:   r   r7   SchoenbergOp27No1zOp. 27 No. 1z#Four Pieces for Mixed Chorus, No. 1)r7   r4   r2   r:   r6   r3   r   r5   r8   r9   r1   r   BergLuluActIScene20zLulu, Act I , Scene XXz0Perm. (Every 7th Note Of Transposed Primary Row))r8   r7   r   r:   r4   r1   r5   r2   r9   r   r3   r6   SchoenbergOp27No3zOp. 27 No. 3z#Four Pieces for Mixed Chorus, No. 3)r6   r7   r2   r5   r4   r   r1   r   r:   r8   r9   r3   SchoenbergOp27No2zOp. 27 No. 2z#Four Pieces for Mixed Chorus, No. 2)r   r1   r5   r8   r2   r:   r   r6   r7   r4   r9   r3   SchoenbergFragPianozFragment For Piano)r7   r9   r   r6   r3   r2   r:   r1   r4   r8   r5   r   SchoenbergOp50BzOp. 50BzDe Profundis)r   r9   r:   r5   r2   r8   r6   r1   r   r7   r4   r3   SchoenbergOp50CzOp. 50CzModern Psalms, The First Psalm)r5   r   r   r:   r1   r6   r4   r9   r7   r8   r3   r2   SchoenbergOp50AzOp. 50AzThree Times A Thousand Years)r6   r9   r7   r5   r4   r1   r8   r2   r   r3   r   r:   SchoenbergMosesAronzMoses And Aron)r9   r8   r5   r2   r   r3   r6   r4   r7   r:   r1   r   
WebernOp25zOp. 25)r6   r5   r   r7   r3   r4   r2   r1   r8   r   r9   r:   SchoenbergOp23No5zOp. 23, No. 5zFive Piano Pieces)r3   r9   r1   r6   r:   r7   r8   r2   r5   r   r   r4   SchoenbergOp28No1zOp. 28 No. 1z%Three Satires for Mixed Chorus, No. 1)r   r5   r6   r3   r9   r1   r4   r   r2   r7   r:   r8   SchoenbergOp28No3zOp. 28 No. 3z%Three Satires for Mixed Chorus, No. 3)r4   r7   r5   r:   r2   r8   r6   r9   r   r1   r3   r   
WebernOp21zOp. 21zChamber Symphony)r4   r:   r6   r7   r8   r9   r   r5   r   r3   r2   r1   SchoenbergIsraelExistszIsrael Exists Again)r   r   r5   r9   r1   r4   r2   r3   r8   r:   r7   r6   SchoenbergOp35No2zOp. 35z!Six Pieces for Male Chorus, No. 2)r7   r9   r6   r3   r   r2   r4   r1   r8   r   r5   r:   SchoenbergOp35No3z!Six Pieces for Male Chorus, No. 3)r   r7   r6   r:   r4   r   r9   r8   r5   r1   r2   r3   SchoenbergOp35No1z!Six Pieces for Male Chorus, No. 1)r2   r1   r   r4   r5   r3   r:   r8   r9   r7   r   r6   SchoenbergOp48No1zOp. 48zThree Songs, No. 1, "Sommermud")r3   r2   r   r7   r   r4   r5   r8   r1   r6   r9   r:   SchoenbergOp35No5z!Six Pieces for Male Chorus, No. 5)r3   r6   r8   r2   r   r1   r:   r5   r   r7   r4   r9   SchoenbergOp29Suite)r   r6   r7   r8   r2   r1   r   r9   r:   r5   r4   r3   BergLyricSuitePermz"Lyric Suite, Last Mvt. Permutation)r4   r7   r8   r5   r3   r9   r2   r:   r6   r   r   r1   
WebernOp20zOp. 20zString Trio)r:   r6   r2   r3   r7   r4   r9   r8   r   r5   r   r1   SchoenbergOp46zOp. 46zA Survivor From Warsaw)r7   r6   r   r:   r5   r   r1   r8   r4   r9   r3   r2   SchoenbergFragOrganSonatazFragment of Sonata For Organ)r3   r6   r1   r   r9   r2   r:   r7   r8   r4   r   r5   SchoenbergOp44zOp. 44z!Prelude To A Suite From "Genesis")r8   r7   r2   r4   r5   r   r1   r:   r3   r   r9   r6   SchoenbergOp45zOp. 45)r2   r8   r   r9   r5   r3   r1   r:   r7   r6   r4   r   SchoenbergOp33AzOp. 33AzTwo Piano Pieces, No. 1)r8   r4   r   r1   r9   r7   r3   r   r6   r:   r2   r5   SchoenbergOp25zOp.25zSuite for Piano)r5   r4   r6   r3   r7   r   r:   r2   r1   r   r9   r8   SchoenbergOp26zOp. 26zWind Quintet)r   r6   r9   r1   r3   r   r8   r2   r5   r7   r:   r4   SchoenbergOp33BzOp. 33BzTwo Piano Pieces, No. 2)r1   r3   r4   r   r9   r:   r7   r8   r6   r5   r   r2   BergViolinConcertoz!Concerto For Violin And Orchestra)r6   r8   r2   r7   r9   r   r5   r:   r1   r3   r   r4   
WebernOp22zOp. 22z2Quartet For Violin, Clarinet, Tenor Sax, And Piano)r7   r   r2   r4   r5   r:   r9   r8   r1   r3   r6   r   BergLuluzLulu: Primary Row)r   r5   r4   r2   r6   r9   r7   r:   r1   r8   r   r3   
WebernOp30zOp. 30zVariations For Orchestra)r9   r8   r3   r   r1   r2   r   r7   r4   r5   r6   r:   
WebernOp31zOp. 31z
Cantata II)r7   r9   r4   r5   r:   r   r6   r1   r8   r2   r3   r   WebernOpNo17No1zOp. 17, No. 1z"Armer Sunder, Du")r1   r8   r4   r7   r   r5   r6   r:   r9   r   r3   r2   
WebernOp24zConcerto For Nine Instruments)r1   r8   r2   r   r6   r7   r:   r5   r4   r   r3   r9   SchoenbergOp48No2zThree Songs, No. 2, "Tot")r2   r   r9   r3   r8   r5   r:   r6   r   r1   r4   r7   
WebernOp27zOp. 27zVariations For Piano)r   r1   r8   r2   r3   r   r7   r5   r6   r4   r9   r:   SchoenbergOp47zOp. 47zFantasy For Violin And Piano)r8   r9   r3   r1   r4   r6   r   r5   r   r2   r:   r7   WebernOp19No2zOp. 19, No. 2z"Ziehn Die Schafe")r:   r5   r9   r7   r6   r   r1   r4   r   r2   r8   r3   WebernOp19No1zOp. 19, No. 1z"Weiss Wie Lilien")r6   r8   r7   r4   r   r9   r:   r3   r2   r1   r5   r   
WebernOp26zDas Augenlicht)r:   r8   r9   r   r1   r   r5   r3   r4   r2   r7   r6   SchoenbergFragPianoPhantasiazFragment of Phantasia For Piano)r3   r4   r   r7   r5   r:   r   r1   r2   r9   r8   r6   BergDerWeinzDer Wein)r2   r5   r4   r6   r9   r8   r3   r7   r:   r   r1   r   BergWozzeckPassacagliaz%Wozzeck, Act I, Scene 4 "Passacaglia")r   r1   r6   r3   r   r7   r5   r8   r9   r4   r:   r2   WebernOp18No1zOp. 18, No. 1z"Schatzerl Klein")r   r1   r4   r:   r8   r9   r   r5   r3   r6   r2   r7   WebernOp18No2zOp. 18, No. 2z
"Erlosung")r7   r9   r4   r:   r5   r6   r   r1   r2   r8   r3   r   WebernOp18No3zOp. 18, No. 3z"Ave, Regina Coelorum")r5   r   r6   r7   r4   r1   r8   r2   r3   r   r9   r:   SchoenbergOp42zOp. 42z Concerto For Piano And Orchestra)r   r8   r2   r4   r5   r   r7   r:   r3   r9   r1   r6   SchoenbergOp48No3z!Three Songs, No, 3, "Madchenlied")r3   r6   r9   r1   r   r4   r8   r7   r5   r   r:   r2   SchoenbergOp37zOp. 37zFourth String Quartet)r2   r3   r9   r8   r4   r   r5   r   r:   r6   r7   r1   SchoenbergOp36zOp. 36z!Concerto for Violin and Orchestra)r9   r8   r   r1   r5   r7   r   r3   r6   r:   r2   r4   SchoenbergOp34zOp. 34zAccompaniment to a Film Scene)r   r7   r2   r5   r3   r   r9   r1   r8   r:   r4   r6   BergChamberConcertozChamber Concerto)r1   r6   r4   r9   r2   r   r7   r:   r   r3   r5   r8   SchoenbergOp32zOp. 32zVon Heute Auf Morgen)r2   r   r9   r3   r1   r4   r:   r6   r5   r   r8   r7   SchoenbergOp31zVariations for Orchestra)r8   r5   r7   r   r4   r9   r2   r3   r6   r:   r1   r   SchoenbergOp30zThird String Quartet)r6   r5   r   r9   r   r4   r7   r1   r8   r3   r:   r2   BergLyricSuitezLyric Suite Primary Row)r4   r5   r   r9   r6   r2   r:   r3   r   r7   r8   r1   zOp. 41zOde To Napoleon)r3   r   r5   r4   r9   r:   r   r2   r7   r6   r1   r8   zOp. 17, No. 3z"Heiland, Unsere Missetaten...")r:   r4   r5   r   r6   r7   r   r3   r2   r1   r8   r9   zOp. 17, No. 2z"Liebste Jungfrau")r3   r   r1   r6   r:   r2   r   r7   r4   r5   r9   r8   )SchoenbergOp41WebernOp17No3WebernOp17No2c                       e Zd ZU dZddiZded<   g dZd fd	Z fdZd	 Z	d
 Z
d Zd Zd Zd Zd ZddZddZd Z xZS )r(   aU  
    A Stream representation of a tone row, or an ordered sequence of pitches;
    can most importantly be used to deal with
    serial transformations.

    Unlike a normal Stream, the first argument is assumed to be a ToneRow:

    >>> toneRow = serial.ToneRow([10, 9, 4, 5, 6, 3, 2, 8, 7, 11, 0, 1])

    The representation of a ToneRow will be the contents:

    >>> toneRow
    <music21.serial.ToneRow A94563287B01>

    Unless (like a Stream), the id is set:

    >>> toneRow.id = 'retrograde_jungfrau'
    >>> toneRow
    <music21.serial.ToneRow retrograde_jungfrau>

    A ToneRow does not need to have twelve pitches, like this ten-tone row
    from Ruth Crawford Seeger's String Quartet 1931

    >>> rcsRow = serial.ToneRow([2, 4, 5, 3, 6, 9, 8, 7, 1, 0])
    >>> rcsRow
    <music21.serial.ToneRow 2453698710>
    >>> len(rcsRow)
    10
    rowz6A list representing the pitch class values of the row.dict[str, str]	_DOC_ATTR)	pitchClasses	noteNamesisTwelveToneRow	isSameRowgetIntervalsAsStringzeroCenteredTransformationoriginalCenteredTransformationfindZeroCenteredTransformations#findOriginalCenteredTransformationsc                   t        |   di | ||| _        ng | _        | j                  D ]  }t        |t        j
                  t        j                  f      st	        j
                  |      }t        |t        j                        st        j                  |      }n|}d |j                  _        | j                  |        y )Nr   r   )
r)   __init__r   r'   r	   Pitchr   Noteoctaver   )r   r   keywordspcr#   r+   s        r   r   zToneRow.__init__#  s    $8$?DHDH((Bb5;;		":;[[_b$)),IIB'!AGGNKKN r   c                v    t         |          }|j                  d      s|S dj                  d | D              S )N0xr   c              3  H   K   | ]  }|j                   j                    y wN)r	   r   ).0r#   s     r   	<genexpr>z(ToneRow._reprInternal.<locals>.<genexpr>;  s     >Aqww//s    ")r)   r*   
startswithr   )r   superInternalr+   s     r   r*   zToneRow._reprInternal6  s9    -/''-  ww>>>>r   c                V    | D cg c]  }|j                   j                   }}|S c c}w )a;  
        Convenience function showing the pitch classes of a
        :class:`~music21.serial.ToneRow` as a list.

        >>> fiveFold = [5 * i for i in range(12)]
        >>> fiveFold
        [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]

        >>> quintupleRow = serial.pcToToneRow(fiveFold)
        >>> quintupleRow
        <music21.serial.TwelveToneRow 05A3816B4927>
        >>> quintupleRow.pitchClasses()
        [0, 5, 10, 3, 8, 1, 6, 11, 4, 9, 2, 7]

        >>> halfStep = serial.pcToToneRow([0, 1])
        >>> halfStep.pitchClasses()
        [0, 1]
        )r	   
pitchClass)r   r#   	pitchLists      r   r   zToneRow.pitchClasses=  s-    & 266AQWW''	6 7s   &c                B    | D cg c]  }|j                    }}|S c c}w )a  
        Convenience function showing the note names of a
        :class:`~music21.serial.ToneRow` as a list.

        >>> chromatic = serial.TwelveToneRow(range(12))
        >>> chromatic.noteNames()
        ['C', 'C#', 'D', 'E-', 'E', 'F', 'F#', 'G', 'G#', 'A', 'B-', 'B']

        >>> halfStep = serial.ToneRow([0, 1])
        >>> halfStep.noteNames()
        ['C', 'C#']
        )name)r   pnoteLists      r   r   zToneRow.noteNamesS  s&     %))DqAFFD) *s   c                v    | j                         }t        |      dk7  ryd}t        d      D ]	  }||vsd} |S )a  
        Describes whether a :class:`~music21.serial.ToneRow` constitutes
        a twelve-tone row. Note that a
        :class:`~music21.serial.TwelveToneRow` object might not be a twelve-tone row.

        >>> serial.ToneRow([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]).isTwelveToneRow()
        True
        >>> serial.ToneRow([0, 4, 8]).isTwelveToneRow()
        False
        >>> serial.ToneRow([3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3]).isTwelveToneRow()
        False
           FT)r   lenrange)r   r   tempis       r   r   zToneRow.isTwelveToneRowc  sH     %%'	y>RD2YI% D  Kr   c                    | j                         }t               }|D ]Z  }t        j                         }d|j                  _        ||j                  _        d|j                  _        |j                  |       \ |S )a  
        Convenience function returning a :class:`~music21.serial.TwelveToneRow` with the
        same pitches.
        Note that a :class:`~music21.serial.ToneRow` may be created without being a
        true twelve tone row.

        >>> r1 = serial.pcToToneRow(range(11))
        >>> type(r1)
        <class 'music21.serial.ToneRow'>
        >>> n = note.Note()
        >>> n.pitch.pitchClass = 11
        >>> r1.append(n)
        >>> r2 = r1.makeTwelveToneRow()
        >>> type(r2)
        <class 'music21.serial.TwelveToneRow'>
                N)
r   TwelveToneRowr   r   durationquarterLengthr	   r   r   r   )r   pcSetathisPcr#   s        r   makeTwelveToneRowzToneRow.makeTwelveToneRowz  sc    $ !!#OF		A'*AJJ$!'AGG!AGGNHHQK  r   c                    t        |       t        |      k7  ryt        | |      D ]4  \  }}|j                  j                  |j                  j                  k7  s4 y y)ao  
        Convenience function describing if two rows are the same.

        >>> row1 = serial.pcToToneRow([6, 7, 8])
        >>> row2 = serial.pcToToneRow([-6, 19, 128])
        >>> row3 = serial.pcToToneRow([6, 7, -8])
        >>> row1.isSameRow(row2)
        True
        >>> row2.isSameRow(row1)
        True
        >>> row1.isSameRow(row3)
        False
        FT)r   zipr	   r   )r   otherselfTone	otherTones       r   r   zToneRow.isSameRow  sQ     t9E
"#&tU#3Hi~~((IOO,F,FF $4 r   c                    t        |       }| j                         }d}t        |dz
        D ]C  }||dz      ||   z
  dz  }|t        d      v r|t        |      z   }|dk(  r|dz   }|dk(  s?|dz   }E |S )a  

        Returns the string of intervals between consecutive pitch classes of
        a :class:`~music21.serial.ToneRow`.
        'T' = 10, 'E' = 11.

        >>> cRow = serial.pcToToneRow([0])
        >>> cRow.getIntervalsAsString()
        ''
        >>> reverseChromatic = serial.pcToToneRow([11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0])
        >>> reverseChromatic.getIntervalsAsString()
        'EEEEEEEEEEE'
        r   r3   r   r8   Tr1   E)r   r   r   r   )r   
numPitchesr   intervalStringr   intervals         r   r   zToneRow.getIntervalsAsString  s     Y
%%'	zA~&A!!a%(9Q<72=H59$!/#h-!?2~!/#!52~!/#!5 ' r   c                   t        |       }| j                         }t        |      |k7  rt        d      |d   }g }|dv r:t	        |      D ]!  }||   |z
  |z   dz  }|j                  |       # t        |      S |dk(  r:t	        |      D ]!  }||z   ||   z
  dz  }|j                  |       # t        |      S |dk(  r@t	        |      D ]'  }|||dz
  |z
     z   |z
  dz  }|j                  |       ) t        |      S |dk(  r@t	        |      D ]'  }|||dz
  |z
     z
  |z   dz  }|j                  |       ) t        |      S t        d	|       )
aT  
        Returns a :class:`~music21.serial.ToneRow` giving a transformation of a tone row.
        Admissible transformationTypes are 'P' (prime), 'I' (inversion),
        'R' (retrograde), and 'RI' (retrograde inversion).

        In the "zero-centered" convention,
        the transformations Pn and In start on the pitch class n, and the transformations
        Rn and RIn end on the pitch class n.

        >>> chromatic = serial.pcToToneRow(range(12))
        >>> chromatic.pitchClasses()
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
        >>> chromaticP3 = chromatic.zeroCenteredTransformation('P',3)
        >>> chromaticP3.pitchClasses()
        [3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 1, 2]
        >>> chromaticI6 = chromatic.zeroCenteredTransformation('I',6)
        >>> chromaticI6.pitchClasses()
        [6, 5, 4, 3, 2, 1, 0, 11, 10, 9, 8, 7]
        >>> schoenberg = serial.getHistoricalRowByName('SchoenbergOp26')
        >>> schoenberg.pitchClasses()
        [3, 7, 9, 11, 1, 0, 10, 2, 4, 6, 8, 5]
        >>> schoenbergR8 = schoenberg.zeroCenteredTransformation('R',8)
        >>> schoenbergR8.pitchClasses()
        [10, 1, 11, 9, 7, 3, 5, 6, 4, 2, 0, 8]
        >>> schoenbergRI9 = schoenberg.zeroCenteredTransformation('RI',9)
        >>> schoenbergRI9.noteNames()
        ['G', 'E', 'F#', 'G#', 'B-', 'D', 'C', 'B', 'C#', 'E-', 'F', 'A']
        z%Transformation must be by an integer.r   Pr   r   IRr3   RIzInvalid transformation type: )r   r   intr   r   r   pcToToneRow)	r   transformationTypeindexr   r   
firstPitchtransformedPitchListr   newPitchs	            r   r   z"ToneRow.zeroCenteredTransformation  s   : Y
%%'	u:!"IJJq\
!+:&%aL:5=C$++H5 '$ /00  3&:&!J.1=C$++H5 ' /00  3&:&!Ij1nq.@$AAJNRTT$++H5 ' /00  4':&!Ij1nq.@$AAJNRTT$++H5 ' /00 "$ABTAU"VWWr   c                    | j                         }|d   }||z   dz  }|dv r| j                  d|      S | j                  ||      S )av  
        Returns a :class:`~music21.serial.ToneRow` giving a transformation of a tone row.
        Admissible transformations are 'T' (transposition), 'I' (inversion),
        'R' (retrograde), and 'RI' (retrograde inversion).

        In the "original-centered" convention,
        which is less common than the "zero-centered" convention, the original row is not initially
        transposed to start on the pitch class 0. Thus, the transformation Tn transposes
        the original row up by n semitones, and the transformations In, Rn, and RIn first
        transform the row appropriately (without transposition), then transpose the resulting
        row by n semitones.

        >>> chromatic = serial.pcToToneRow(range(12))
        >>> chromatic.pitchClasses()
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
        >>> chromaticP3 = chromatic.originalCenteredTransformation('T',3)
        >>> chromaticP3.pitchClasses()
        [3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 1, 2]
        >>> chromaticI6 = chromatic.originalCenteredTransformation('I',6)
        >>> chromaticI6.pitchClasses()
        [6, 5, 4, 3, 2, 1, 0, 11, 10, 9, 8, 7]
        >>> schoenberg = serial.getHistoricalRowByName('SchoenbergOp26')
        >>> schoenberg.pitchClasses()
        [3, 7, 9, 11, 1, 0, 10, 2, 4, 6, 8, 5]
        >>> schoenbergR8 = schoenberg.originalCenteredTransformation('R',8)
        >>> schoenbergR8.pitchClasses()
        [1, 4, 2, 0, 10, 6, 8, 9, 7, 5, 3, 11]
        >>> schoenbergRI9 = schoenberg.originalCenteredTransformation('RI',9)
        >>> schoenbergRI9.noteNames()
        ['B-', 'G', 'A', 'B', 'C#', 'F', 'E-', 'D', 'E', 'F#', 'G#', 'C']
        r   r   r   r   )r   r   )r   r   r   r   r   newIndexs         r   r   z&ToneRow.originalCenteredTransformation   sZ    @ %%'	q\
&",+223AA../A8LLr   c                .   t        |       t        |      k7  ry|j                         }g }|d   }|d   }|| j                  d|      j                         k(  rd|f}|j                  |       || j                  d|      j                         k(  rd|f}|j                  |       || j                  d|      j                         k(  rd|f}|j                  |       || j                  d|      j                         k(  rd|f}|j                  |       |S )aZ  
        Gives the list of zero-centered serial transformations
        taking one :class:`~music21.serial.ToneRow`
        to another, the second specified in the argument. Each transformation is given as a
        tuple of the transformation type and index.

        See :meth:`~music21.serial.ToneRow.zeroCenteredTransformation` for
        an explanation of this convention.

        >>> chromatic = serial.pcToToneRow([2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 1])
        >>> reverseChromatic = serial.pcToToneRow([8, 7, 6, 5, 4, 3, 2, 1, 0, 11, 10, 9])
        >>> chromatic.findZeroCenteredTransformations(reverseChromatic)
        [('I', 8), ('R', 9)]
        >>> schoenberg25 = serial.getHistoricalRowByName('SchoenbergOp25')
        >>> schoenberg26 = serial.pcToToneRow(serial.getHistoricalRowByName(
        ...                                        'SchoenbergOp26').row)
        >>> schoenberg25.findZeroCenteredTransformations(schoenberg26)
        []
        >>> schoenberg26.findZeroCenteredTransformations(
        ...     schoenberg26.zeroCenteredTransformation('RI', 8))
        [('RI', 8)]
        Fr   r   r   r   r   )r   r   r   r   )r   otherRowotherRowPitchestransformationListr   	lastPitchtransformations          r   r   z'ToneRow.findZeroCenteredTransformations(  s   . t9H%"//1$Q'
#B'	d==c:N[[]] *_N%%n5d==c:N[[]] *_N%%n5d==c9MZZ\\ )^N%%n5d==dIN[[]]!9_N%%n5!!r   c                4   | j                         }|j                         }g }|d   }|d   }|d   }||z
  dz  }||z
  dz  }	|d|z  z
  |z   dz  }
| j                  }| |d|      j                         k(  rd|f}|j                  |       | |d|      j                         k(  rd|f}|j                  |       | |d|	      j                         k(  rd|	f}|j                  |       | |d|
      j                         k(  rd|
f}|j                  |       |S )	a4  
        Gives the list of original-centered serial transformations taking one
        :class:`~music21.serial.ToneRow`
        to another, the second specified in the argument. Each transformation is given as a tuple
        of the transformation type and index.

        See :meth:`~music21.serial.ToneRow.originalCenteredTransformation` for an
        explanation of this convention.

        >>> chromatic = serial.pcToToneRow(       [2, 3, 4, 5, 6, 7, 8, 9, 'A', 'B',   0, 1])
        >>> reverseChromatic = serial.pcToToneRow([8, 7, 6, 5, 4, 3, 2, 1, 0,   'B', 'A', 9])
        >>> chromatic.findOriginalCenteredTransformations(reverseChromatic)
        [('I', 6), ('R', 7)]
        >>> schoenberg25 = serial.getHistoricalRowByName('SchoenbergOp25')
        >>> schoenberg26 = serial.getHistoricalRowByName('SchoenbergOp26')
        >>> schoenberg25.findOriginalCenteredTransformations(schoenberg26)
        []
        >>> schoenberg26.findOriginalCenteredTransformations(
        ...     schoenberg26.originalCenteredTransformation('RI',8))
        [('RI', 8)]
        r   r   r   r2   r   r   r   r   )r   r   r   )r   r   originalRowPitchesr   r   oldFirstPitcholdLastPitchnewFirstPitchtiPitchrPitchriPitchocTransr   s                r   r   z+ToneRow.findOriginalCenteredTransformationsV  sQ   . "..0"//1*1-)"-'* !=0B6  ,."4 !A$56EK 55gc73@@BB!7^N%%n5gc73@@BB!7^N%%n5gc62??AA!6]N%%n5gdG4AACC"G_N%%n5!!r   r   )r   r   r   r   )returnzt.Union[bool, list[t.Any]])r   r   r   r,   r   __annotations__
_DOC_ORDERr   r*   r   r   r   r   r   r   r   r   r   r   r-   r.   s   @r   r(   r(      sf    < 	G!I~ \J
&?, .8,671r&MP,"\7"r   r(   c                  \    e Zd ZdZg dZd Zd Zd ZddZd Z	ddZ
	 	 	 	 	 	 	 	 	 	 dd	Zy
)r   z^
    A Stream representation of a twelve-tone row, capable of producing a 12-tone matrix.
    )matrixisAllIntervalgetLinkClassificationisLinkChordareCombinatorialc           	        | j                  t        j                        }|D cg c]  }d|j                  j                  z
  dz    }}|D cg c],  }|D cg c]  }|j                  j                  |z   dz    c}. }}}t               }d}|D ]  }|dz  }| j                         }|j                  |        dt        |      z   |_	        |D ]Z  }	t        j                         }
d|
j                  _        |	|
j                  _        d|
j                  _        |j                  |
       \ |j                  d|        |S c c}w c c}w c c}}w )a  
        Returns a :class:`~music21.serial.TwelveToneMatrix` object for the row.
        That object can just be printed (or displayed via .show())

        >>> src = serial.getHistoricalRowByName('SchoenbergOp37')
        >>> [p.name for p in src]
        ['D', 'C#', 'A', 'B-', 'F', 'E-', 'E', 'C', 'G#', 'G', 'F#', 'B']
        >>> len(src)
        12
        >>> s37 = serial.getHistoricalRowByName('SchoenbergOp37').matrix()
        >>> print(s37)
          0  B  7  8  3  1  2  A  6  5  4  9
          1  0  8  9  4  2  3  B  7  6  5  A
          5  4  0  1  8  6  7  3  B  A  9  2
          4  3  B  0  7  5  6  2  A  9  8  1
        ...
        >>> [str(e.pitch) for e in s37[0]]
        ['C', 'B', 'G', 'G#', 'E-', 'C#', 'D', 'B-', 'F#', 'F', 'E', 'A']
        r   r   r3   zrow-r   N)getElementsByClassr   r   r	   r   r   r+   mergeAttributesr   idr   r   r   r   insert)r   r   xr   transr   	matrixObjr   	rowObjectr   r#   s              r   r   zTwelveToneRow.matrix  s-   . **49955=>Xb177%%%+X>UVWUVEhGhAGG&&."4hGUVW$&	CFA(I%%d+!CF?ILIIK+.

(%&"!%  #  Q	*   + ?GWs   #E	E#E:EEc                x    g }t         D ].  }| j                  t        |            s|j                  |       0 |S )a  
        Checks if a given :class:`music21.serial.TwelveToneRow` is the same as
        any of the historical
        twelve-tone rows stored by music21: see :func:`music21.serial.getHistoricalRowByName`.
        Returns a list of names of historical rows to which the input row is identical.

        >>> row = serial.pcToToneRow([2, 3, 9, 1, 11, 5, 8, 7, 4, 0, 10, 6])
        >>> row.findHistorical()
        ['SchoenbergOp32']
        >>> chromatic = serial.pcToToneRow(range(12))
        >>> chromatic.findHistorical()
        []
        )historicalDictr   getHistoricalRowByNamer   )r   sameRowshistoricalRows      r   findHistoricalzTwelveToneRow.findHistorical  s8     +M~~4]CD. , r   c                (   g }|dk(  r=t         D ]2  }t        |      j                  |       }|s |j                  ||f       4 |S |dk(  r?t         D ]4  }t        |      }|j	                  |       }|s"|j                  ||f       6 |S t        d      )aT  
        Checks if a given :class:`music21.serial.TwelveToneRow` is a transformation of
        any historical
        twelve-tone row stored by music21 (see :func:`music21.serial.getHistoricalRowByName`).
        Returns a list
        of tuples, the tuple consisting of the name of a historical row, and a
        list of transformations relating
        the input row to the historical row.

        The convention for serial transformations must also be specified as 'zero' or
        'original', as explained
        in :meth:`~music21.serial.ToneRow.findZeroCenteredTransformations` and
        :meth:`~music21.serial.ToneRow.findOriginalCenteredTransformations`.

        >>> row = serial.pcToToneRow([5, 9, 11, 3, 6, 7, 4, 10, 0, 8, 2, 1])
        >>> row.findTransformedHistorical('original')
        [('SchoenbergOp32', [('R', 11)])]
        zerooriginalz1Invalid convention - choose 'zero' or 'original'.)r   r   r   r   r   r   )r   
conventionr   r   r   historicalRowObjects         r   findTransformedHistoricalz'TwelveToneRow.findTransformedHistorical  s    & !/.}=]]^bcOO]E$:; "0 O#!/&<]&K#+OOPTUOO]E$:;	 "0
 O!"UVVr   c                    | j                         du rt        d      d}| j                         }t        dd      D ]  }t	        |      |vsd} d|vrd}d|vrd}|S )a  
        Describes whether a :class:`~music21.serial.TwelveToneRow` is an all-interval row.

        >>> chromatic = serial.pcToToneRow(range(12))
        >>> chromatic.pitchClasses()
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
        >>> chromatic.isAllInterval()
        False
        >>> bergLyric = serial.getHistoricalRowByName('BergLyricSuite')
        >>> bergLyric.pitchClasses()
        [5, 4, 0, 9, 7, 2, 8, 1, 3, 6, 10, 11]
        >>> bergLyric.isAllInterval()
        True
        Fz.An all-interval row must be a twelve-tone row.Tr3   r8   r   r   )r   r   r   r   r   )r   tempAllIntervalr   r   s       r   r   zTwelveToneRow.isAllInterval  sw      !U*!"RSS224q"A1v^+"'  n$#On$#Or   c                   g d}g d}g d}t        |      }| j                         du rt        d      | | j                  dd      | j                  dd      | j                  d	d      g}g }d
}|D ]D  }|j	                         }	t        |      D ]$  }
||
   |	k(  s||
   }|j                  ||
          & F |sd
g fS ||fS )aJ  
        Gives the classification number of a Link Chord
        (as given in http://www.johnlinkmusic.com/LinkChords.pdf),
        that is, is an all-interval twelve-tone row containing a voicing of the
        all-trichord hexachord: [0, 1, 2, 4, 7, 8].
        In addition, gives a list of sets of five contiguous intervals
        within the row representing a voicing
        of the all-trichord hexachord. Note that the interval sets may be transformed.

        Named for John Link who discovered them.

        >>> bergLyric = serial.getHistoricalRowByName('BergLyricSuite')
        >>> bergLyric.pitchClasses()
        [5, 4, 0, 9, 7, 2, 8, 1, 3, 6, 10, 11]
        >>> bergLyric.isAllInterval()
        True
        >>> bergLyric.getLinkClassification()
        (None, [])
        >>> link = serial.pcToToneRow([0, 3, 8, 2, 10, 11, 9, 4, 1, 5, 7, 6])
        >>> link.getLinkClassification()
        (62, ['8352E'])
        >>> doubleLink = serial.pcToToneRow([0, 1, 8, 5, 7, 10, 4, 3, 11, 9, 2, 6])
        >>> doubleLink.getLinkClassification()
        (33, ['236E8', '36E8T'])
        )125634T97E8134E78526T9134E79T6258r  1367T89E254137E542896T137E982456T142965837ET142973856ET1429738E65T14297TE6853145638E729T1456T729E831456T982E73145927E836T14598E63T7214689T7E2531469E27T853149278356ET1492783E65T1496258T73E1496E358T7214972836E5T14972E6385T1497T853E6214E379T652814E6T783529172E6853T9417356ET82941738T542E69173E65T82941763T4952E8176852E34T9179236E8T54r!  17923E685T4179245T8E6317924T586E3179T65234E8179T8E63254r&  1825E43796Tr'  1825E79T364r(  1852E43769T1852E79463T185629TE74318563479TE218563E7T49218734E5296Tr.  187E259436Tr/  18T352E796418T497E356218T97E52364r2  18E63T79452r3  19476538TE21947T8536E21954763T8E219742538E6T197425T6E831974T8E6352197T8532E641T5E79283641T63E8742591T6E38524791T8352E46791T974253E68214367TE985214376598ETrA  2143E86597T2149586E37T214976538ETrD  216734ET985216743E9T85217634TE98521T8E95634721T96583E47234T1596E87235189E647TrK  23689E7T145236E981547TrM  23T514697E82513647ET9825189TE7463rP  2546E981T7325691T8E4732569E8T1437258T73E6149258T9614E3725T31496E8725T89E614372618T497E3526347ET9185263891T7E45rZ  2653E718T492654T1783E9r\  2654E3871T9r]  2654E7T1983r^  265819TE7432659E8T1347267431T8E952694T817E35269T1783E45rc  269E3871T45rd  26E451T7389re  26E459817T3rf  26E4T718953rg  26E873T514926E95134T8726E95178T43274316E985Trk  2743E86591T274916E385Trm  2749586E31T276134ET985276143E9T8527E34169T852965387E41Trr  296E387T14529TE743618529TE746315829E7835641Trv  2E431T96587rw  2E465387T192E637T854192E783T51469rz  2E796415T382E8T19567432E9658T41373142E8956T73142ET7968531456T972E8314672E9T853152689TE74r  3152E9T87643158629TE74r  316452E98T7317ET562894317ET926854317ET986254319765T42E83198265TE7431T524796E831T567942E831T7E294685325E79T8164r  3265981TE74329E71T4568r  32E981T6547347621T8E953479TE2618534T9E71256835146T927E8r  351T64927E8r  351T7924E6835216E98T743521T8E96743581629ET743594T6127E8359E6128T7435E7216T49835E72946T1835E729T64183625189TE74r  36524ET89173674218T9E536T154927E8r  3764128T9E538297E5T16438E729T61453T17E924568r  3T4952E86173T6194527E83T62E8154973T97E528164r  3E2418596T73E7T4926185416352E7T9841T629E7835r  4328T56E9174328TE6591743T9E865217463152E9T8746529E8T13746731T8E9254692E513T87r  46982315ET7469T315E287r  4769E251T384783T1629E547T198236E547E928361T54T1629E37854TE865923174E2538T16974E29658T317r  4ET85692317r  5896T142E37)25634134E7r  E79T689E257E5427E98229658856ET8E65TE68538E729729E8982E7927E88E63T7E2537T85378356783E658T73358T72836E2E638r  79T6578352r  56ET842E69E65T84952E52E34236E836E8T3E685T8E63586E3r  r  8E63225E435E43725E795E79TE4376E79469TE74479TEE7T49734E534E5287E25E2594352E7T497ET97E597E52r  T794576538r  4763T97425r  r  r  5E79274259524798352Er  4367T4376576598E8659r  49765r  6734E216747634T1T8E9T965834T155189E189E6689E76E981E98153T51447ET925189r  r  91T8E9E8T1r  T96145T31489E61r  r  891T71T7E4E718TT17831783EE38713871T4E7T17T198r  r  r  T817Er  r  r  r  451T71T738598179817TT718971895r  5134T5178T4316E16E98r  4916E16E38r  6134E276144169T653875387E6E387r  r  E7835r  E431Tr	  r1  37T852E783r  415T3E8T199658T3142Er;  56T973146752689r  152E958629r  52E98562899268598625765T498265r  5679431T7Er  r  6598129E719E71T2E981r  r  T9E71146T9r  1T649r  51T79r+  r  1629E94T61E612816T49946T19T641r  r  3652436742T1549r  37641297E5r  T17E917E92r  6194515497r  r  3E241r  r  629E7r4  8T56E8TE659E865r?  r  r  2E513E513T2315ET315E315E29E251rQ  r   8361TrQ  r  E2538r  r:  T856985692142E3)r3   r2   r   r   r5   r4   r7   r6   r:   r9   r8   r1   r                                                                !   r  "   #   $   %   &   r  '   r  (   r  )   *   +   ,   -   .   r  /   r  0   1   2   r  3   r  4   5   6   7   8   9   :   ;   <   =   >   ?   @   A   r  B   C   D   r  E   F   G   H   I   J   K   r  L   M   r  N   O   P   r  Q   R   S   T   U   V   W   X   Y   Z   r  [   \   r  ]   r  ^   r  _   `   a   b   c   r  d   r  e   r  f   r  g   r  h   i   j   k   r  l   m   r  n   o   p   q   r   r  s   t   u   v   r  w   r  x   y   z   r  {   |   }   ~               r        r                                r        r                 r     r                                r           r              r
              r              r                       r        r                          r#     r$     Fz'A Link Chord must be a twelve-tone row.r   r   r   r   N)r   r   r   r   r   r   r   )r   fullLinkIntervalsspecialLinkIntervalslinkClassification	numChordsrowChecklistspecialIntervalsclassificationr   	intervalsr   s              r   r   z#TwelveToneRow.getLinkClassification  s    B;;x" KF*V )*	!U*!"KLL77Q?77Q?77a@B C002I9%$Q'94%7%:N$++,@,CD &    8O!#333r   c                0    | j                         }|d   yy)a_  
        Describes whether a :class:`~music21.serial.TwelveToneRow` is a Link Chord.

        >>> bergLyric = serial.getHistoricalRowByName('BergLyricSuite')
        >>> bergLyric.pitchClasses()
        [5, 4, 0, 9, 7, 2, 8, 1, 3, 6, 10, 11]
        >>> bergLyric.isAllInterval()
        True
        >>> bergLyric.isLinkChord()
        False
        >>> link = serial.pcToToneRow([0, 3, 8, 2, 10, 11, 9, 4, 1, 5, 7, 6])
        >>> link.isLinkChord()
        True
        >>> doubleLink = serial.pcToToneRow([0, 1, 8, 5, 7, 10, 4, 3, 11, 9, 2, 6])
        >>> doubleLink.isLinkChord()
        True
        r   FT)r   )r   	linkTuples     r   r   zTwelveToneRow.isLinkChord  s"    $ ..0	Q<r   c                   | j                         du rt        d      | j                  ||      }| j                  ||      }|j                         }|j                         }|dd |dd z   }	t	        |	      j                         S )a  
        Describes whether two transformations of a twelve-tone row are combinatorial.

        The first and second arguments describe one transformation, while the third and fourth
        describe another.

        First, let's take a row we know to have a combinatoriality pair:

        >>> moses = serial.getHistoricalRowByName('SchoenbergMosesAron')
        >>> moses.pitchClasses()
        [9, 10, 4, 2, 3, 1, 7, 5, 6, 8, 11, 0]

        Combinatoriality holds here between P0 and I3

        >>> moses.areCombinatorial('P', 0, 'I', 3)
        True

        And a combinatorial pair like this between P0 and I3 will also hold
        if you modify both rows in the same way, e.g.
        if you transpose both by the same amount

        >>> moses.areCombinatorial('P', 1, 'I', 4)
        True

        or if you retrograde both

        >>> moses.areCombinatorial('R', 1, 'RI', 4)
        True

        Any modification made to one row form and not the other means all bets are off

        >>> moses.areCombinatorial('R', 6, 'RI', 4)
        False

        * Changed in v7: `convention` is no longer necessary and no longer used.
          Renamed to `unused_convention` and defaults None; to be removed in v8.
        Fz2Combinatoriality applies only to twelve-tone rows.Nr7   )r   r   r   r   r   )
r   
transType1index1
transType2index2trans1trans2pitches1pitches2testRows
             r   r   zTwelveToneRow.areCombinatorial  s    T !U*!"VWW 00VD00VD&&(&&(2A,"1-7#3355r   N)r   bool)
r1  r   r2  r   r3  r   r4  r   r   r:  )r   r   r   r,   r   r   r   r   r   r   r   r   r   r   r   r   r     se    NJ.`("WH<4B056%(56!$56 &)56 "%	56 *.	56r   r   c                       e Zd ZU dZddddZded<   dZd	ed
<   dZd	ed<   dZd	ed<   	 	 	 	 d	 	 	 	 	 d fdZ	 fdZ
d Z xZS )HistoricalTwelveToneRowz
    Subclass of :class:`~music21.serial.TwelveToneRow` storing additional attributes of a
    twelve-tone row used in the historical literature.
    z,The name of the composer, or None.  (String)z(The opus of the work, or None.  (String)z)The title of the work, or None.  (String)composeropustitler   r   N
None | strr>  r?  r@  c                P    t        |   |fi | || _        || _        || _        y r   )r)   r   r>  r?  r@  )r   r>  r?  r@  r   r   r+   s         r   r   z HistoricalTwelveToneRow.__init__?  s,     	)) 	
r   c                    t         |   |       t        |t              sy |j                  | _        |j
                  | _        |j                  | _        y r   )r)   r   r'   r<  r>  r?  r@  )r   r   r+   s     r   r   z'HistoricalTwelveToneRow.mergeAttributesJ  s?    &%!89JJ	[[
r   c                R    | j                    d| j                   d| j                   S )N r=  )r   s    r   r*   z%HistoricalTwelveToneRow._reprInternalR  s%    --$))Adjj\::r   )NNNN)r>  rA  r?  rA  r@  rA  )r   r   r   r,   r   r   r>  r?  r@  r   r   r*   r-   r.   s   @r   r<  r<  0  sy    
 C:<!I~  HhD(E8 '+"&#'		#		 !	!;r   r<  c                    | j                  d      r| dd } | t        v r%t        |    }t        |d   |d   |d   |d         }|S t        d      )a	  
    Given the name referring to a twelve-tone row used in the historical literature,
    returns a :class:`~music21.serial.HistoricalTwelveToneRow` object with attributes
    describing the row.

    The names of the rows with stored attributes are below (each must be passed as a string,
    in single quotes).

    >>> for r in sorted(list(serial.historicalDict)):
    ...     print(r)
    BergChamberConcerto
    BergDerWein
    BergLulu
    BergLuluActIIScene1
    BergLuluActIScene20
    BergLyricSuite
    BergLyricSuitePerm
    BergViolinConcerto
    BergWozzeckPassacaglia
    SchoenbergFragOrganSonata
    SchoenbergFragPiano
    SchoenbergFragPianoPhantasia
    SchoenbergIsraelExists
    SchoenbergJakobsleiter
    SchoenbergMosesAron
    SchoenbergOp23No5
    SchoenbergOp24Mvmt4
    SchoenbergOp24Mvmt5
    SchoenbergOp25
    SchoenbergOp26
    SchoenbergOp27No1
    SchoenbergOp27No2
    SchoenbergOp27No3
    SchoenbergOp27No4
    SchoenbergOp28No1
    SchoenbergOp28No3
    SchoenbergOp29
    SchoenbergOp30
    SchoenbergOp31
    SchoenbergOp32
    SchoenbergOp33A
    SchoenbergOp33B
    SchoenbergOp34
    SchoenbergOp35No1
    SchoenbergOp35No2
    SchoenbergOp35No3
    SchoenbergOp35No5
    SchoenbergOp36
    SchoenbergOp37
    SchoenbergOp41
    SchoenbergOp42
    SchoenbergOp44
    SchoenbergOp45
    SchoenbergOp46
    SchoenbergOp47
    SchoenbergOp48No1
    SchoenbergOp48No2
    SchoenbergOp48No3
    SchoenbergOp50A
    SchoenbergOp50B
    SchoenbergOp50C
    WebernOp17No2
    WebernOp17No3
    WebernOp18No1
    WebernOp18No2
    WebernOp18No3
    WebernOp19No1
    WebernOp19No2
    WebernOp20
    WebernOp21
    WebernOp22
    WebernOp23
    WebernOp24
    WebernOp25
    WebernOp26
    WebernOp27
    WebernOp28
    WebernOp29
    WebernOp30
    WebernOp31
    WebernOpNo17No1

    >>> web = serial.getHistoricalRowByName('WebernOp29')
    >>> web.row
    [3, 11, 2, 1, 5, 4, 7, 6, 10, 9, 0, 8]
    >>> web.composer
    'Webern'
    >>> web.opus
    'Op. 29'
    >>> web.title
    'Cantata I'
    >>> web.isLinkChord()
    False

    NOTE: before v6, these rows had 'Row' in front of them,
    like 'RowWebernOp29' instead of 'WebernOp29'.  They can still be accessed
    by the old name.

    >>> rowWeb = serial.getHistoricalRowByName('RowWebernOp29')
    >>> rowWeb.row == web.row
    True
    Rowr   Nr   r3   r2   z'No historical row with given name found)r   r   r<  r   )rowNameattrrowObjs      r   r   r   V  sa    N % !"+. g&(a$q'47DGLGHHr   c                    t        |       dk(  rt               }n
t               }| D ]I  }t        j                         }||j
                  _        d|j
                  _        |j                  |       K |S )a  
    A convenience function that, given a list of pitch classes represented as integers
    and turns it in to a :class:`~music21.serial.ToneRow` object.

    >>> chromaticRow = serial.pcToToneRow([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
    >>> chromaticRow.show('text')
    {0.0} <music21.note.Note C>
    {1.0} <music21.note.Note C#>
    {2.0} <music21.note.Note D>
    {3.0} <music21.note.Note E->
    {4.0} <music21.note.Note E>
    {5.0} <music21.note.Note F>
    {6.0} <music21.note.Note F#>
    {7.0} <music21.note.Note G>
    {8.0} <music21.note.Note G#>
    {9.0} <music21.note.Note A>
    {10.0} <music21.note.Note B->
    {11.0} <music21.note.Note B>
    >>> matrixObj = chromaticRow.matrix()
    >>> print(matrixObj)
      0  1  2  3  4  5  6  7  8  9  A  B
      B  0  1  2  3  4  5  6  7  8  9  A
    ...

    >>> fancyRow = serial.pcToToneRow([4, 5, 0, 6, 7, 2, 'a', 8, 9, 1, 'b', 3])
    >>> matrixObj = fancyRow.matrix()
    >>> print(matrixObj)
      0  1  8  2  3  A  6  4  5  9  7  B
      B  0  7  1  2  9  5  3  4  8  6  A
    ...

    Note that the Row does not have to be a valid row to exist:

    >>> multiSetRow = serial.pcToToneRow([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1])
    >>> multiSetRow.pitchClasses()
    [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]

    Or even have 12 notes:

    >>> shortRow = serial.pcToToneRow([3, 4])
    >>> shortRow.pitchClasses()
    [3, 4]

    If the row does have twelve notes (whether unique or not) the object returned
    is a `TwelveToneRow`:

    >>> multiSetRow
    <music21.serial.TwelveToneRow 111111111111>

    Otherwise, it is simply a `ToneRow`:

    >>> shortRow
    <music21.serial.ToneRow 34>
    r   N)	r   r   r(   r   r   r	   r   r   r   )r   r   r   r#   s       r   r   r     s]    p 5zROIIIK#		 
 Hr   c           	     n   | D cg c]
  }d|z
  dz   }}|D cg c]  }| D cg c]
  }||z   dz   c} }}}g }|D ]T  }g }|D ]+  }|j                  t        |      j                  d             - |j                  dj                  |             V dj                  |      S c c}w c c}w c c}}w )a0  
    Takes a list of numbers of converts it to a string representation of a
    12-tone matrix.

    >>> aMatrix = serial.rowToMatrix([0, 2, 11, 7, 8, 3, 9, 1, 4, 10, 6, 5])
    >>> print(aMatrix)
      0  2 11  7  8  3  9  1  4 10  6  5
     10  0  9  5  6  1  7 11  2  8  4  3
      1  3  0  8  9  4 10  2  5 11  7  6
      5  7  4  0  1  8  2  6  9  3 11 10
      4  6  3 11  0  7  1  5  8  2 10  9
      9 11  8  4  5  0  6 10  1  7  3  2
      3  5  2 10 11  6  0  4  7  1  9  8
     11  1 10  6  7  2  8  0  3  9  5  4
      8 10  7  3  4 11  5  9  0  6  2  1
      2  4  1  9 10  5 11  3  6  0  8  7
      6  8  5  1  2  9  3  7 10  4  0 11
      7  9  6  2  3 10  4  8 11  5  1  0

    This function survives today (2020) because it's been
    an example function for `music21` since the very first demonstrations
    of predecessors from around 2000 onwards.  Nowadays, better to create
    a `TwelveToneRow()` object and then get a matrix from that:

    >>> ttr = serial.TwelveToneRow([0, 2, 11, 7, 8, 3, 9, 1, 4, 10, 6, 5])
    >>> matrix = ttr.matrix()
    >>> print(matrix)
      0  2  B  7  8  3  9  1  4  A  6  5
      A  0  9  5  6  1  7  B  2  8  4  3
      1  3  0  8  9  4  A  2  5  B  7  6
      5  7  4  0  1  8  2  6  9  3  B  A
      4  6  3  B  0  7  1  5  8  2  A  9
      9  B  8  4  5  0  6  A  1  7  3  2
      3  5  2  A  B  6  0  4  7  1  9  8
      B  1  A  6  7  2  8  0  3  9  5  4
      8  A  7  3  4  B  5  9  0  6  2  1
      2  4  1  9  A  5  B  3  6  0  8  7
      6  8  5  1  2  9  3  7  A  4  0  B
      7  9  6  2  3  A  4  8  B  5  1  0
    r   r   r   r   )r   r   r   r   )	r   r   r   r   r   r    r   r"   thisPCs	            r   rowToMatrixrN    s    V !""1"q&BA"9:;+AE	R+F;
CFJJs6{((+, 

2773< 	  99S> 	#+;s   B'	B1B,B1,B1c                  0    e Zd Zd Zd Zd Zd Zd Zd Zy)Testc                   t        d      }| j                  |D cg c]  }|j                   c}g d       t        d      j                         }|d   }| j                  |D cg c]  }|j                   c}g d       y c c}w c c}w )Nry   )DC#AB-FE-r   CG#GF#Br   )rX  r\  rZ  rY  rW  rS  rR  rU  r[  rV  r   rT  )r   assertEqualr   r   )r   srcr   s37r0es         r   
testMatrixzTest.testMatrixJ  s    $%56#.#Q!&&#.Z	\$%56==?V"-"Q!&&"-Z	\	 / .s   B%Bc                   ddl m} ddddddd	d
ddddd}|j                  d      }|j                         j                  D ]T  }|D ]M  }|j
                  j                  t        j                  |      j                  k(  s:|j                  ||          O V g }|j                  d   j                         j                  D ]  }|j                  |j                          | j                  |g d       y )Nr   )corpusr3   r2   r   r5   r4   r7   r6   r:   r9   r8   r1   r   )r   zg-gza-fze-ra  dczc#zb-bzbwv66.6)%10121rk  rj  7rj  rk  rl  rj  rl  rk  42rl  rk  rk  ro  rm  rl  rk  rj  rj  rl  rk  rj  rl  rn  ro  rn  ro  ro  ro  ro  ro  5ro  )music21rd  parseflattennotesr	   r   r   addLyricpartsr   lyricr]  )r   rd  seriessr#   keymatchs          r   testLabelingAzTest.testLabelingAS  s    ""27 LL#""A77%%S)9)D)DDJJvc{+  # ##%++ALL! , !5 	6r   c                    g }t         D ]/  }t        |      j                         du s|j                  |       1 | j	                  |g        y )NF)r   r   r   r   r]  )r   nonRowsr   s      r   testHistoricalzTest.testHistoricalf  sE    +M%m4DDF%O}- , 	"%r   c                $    t        d      }|dd }y)z)
        Was a problem in slices
        rd   r   r   N)r   )r   aRowunused_aRow2s      r   testExtractRowPartszTest.testExtractRowPartsm  s     &&:;Aayr   c                .   t        d      }t        j                         }t        ddd      D ]f  }|||dz    }t	        j
                  |      }|j                  |j                         |j                  |j                         |j                  |       h y )Nrd   r   r   r   )
r   r
   Streamr   r   Chordru  primeFormString
forteClassr   )r   r  bStreamr   aRow2rh  s         r   testPostTonalDocszTest.testPostTonalDocst  su    %&:;--/q"aA1q5MEE"AJJq(()JJq||$NN1 !r   c                2    ddl m}  || t                      y )Nr   )testCopyAll)music21.test.commonTestr  globals)r   r  s     r   testCopyAndDeepcopyzTest.testCopyAndDeepcopy  s    7D')$r   N)	r   r   r   rb  r|  r  r  r  r  r   r   r   rP  rP  H  s!    \6&&!	%r   rP  __main__)r   z	list[int]r   r   )r,   
__future__r   typingtunittestrq  r   r   r   r   r	   r
   EnvironmentenvironLocalMusic21Exceptionr   r  r   r   r(   r   r<  r   r   rN  TestCaserP  r   r   mainTestr   r   r   <module>r     s   #         &{&&x0	l33 	
7+v}} 7+xS8X{>@S 8X'7>@S
 L(4S!GIS L(4P!GIS |T3E$JLS ,8]EGS 8X}>@S F$;!S!GIS$ ,8]EG%S( F$<!S!GI)S. ,8]EG/S2 ,8]EG3S6 L$0D!GI7S: iCE;S> i1QCE?SB i1OCECSF L$0@!GIGSJ 8X}>@KSN ,9LEGOSR ,FEGSSX ,FEGYS^ 8X'9>@_Sb |T3H$JLcSf ,2UEGgSj ,2UEGkSn ,2UEGoSr ,2SEGsSv ,2UEGwSz |XwBD{S~ 64)M FHSB 8X}>@CSF |X/GBDGSJ  ,6T'M"OKSN |X/RBDOSR |X}BDSSV i1JCEWSZ |W.?BD[S^ |X~BD_Sb i1JCEcSf 64)L FHgSj 8X'[>@kSn 2>@oSr 8X'A>@sSv 8X|>@wSz /3GCE{S~ 8X'F>@SB ,2MEGCSF 8X'=>@GSJ |X/MBDKSN h1EACOSR h1EACSSV 8X'7>@WSZ #\49Z*P%R[S^ FD*?A_Sb vt-T$JLcSf h1DACgSj hACkSn h1IACoSr |X/QBDsSv ,2UEGwSz |X/FBD{S~ |X/RBDSB |X/NBDCSF FD*<!GIGSJ |X/EBDKSN |X/IBDOSR |X/EBDSSV vt%>BDWSZ $X/@BD1RAC1EACcSpQ"fmm Q"l[6G [6|#;m #;LoIhBJ5r9%8 9%n }&=+[:P
 zGT r   