
    rh                       S r SSKJr  SSKrSSKrSSKJr  SSKJr  SSKJ	r	  SSKJ
r
  SSKJr  SS	KJr  \R                  " S
5      r " S S\	R                  5      r " S S\R"                  5      r0 SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_S SSS!/ S"Q4_S#SS$S%/ S&Q4_S'SS(S)/ S*Q4_S+S,S-S./ S/Q4_S0SS1S2/ S3Q4_S4S,S5S6/ S7Q4_S8SS9S:/ S;Q4_S<SS=S>/ S?Q4_S@SSSA/ SBQ4_SCSSDSE/ SFQ4_SGSSHSI/ SJQ4_SKSSLSM/ SNQ4_SOSSSP/ SQQ4_0 SRSSSS)/ STQ4_SUSSVSW/ SXQ4_SYSSZS[/ S\Q4_S]SS^S_/ S`Q4_SaSSbSc/ SdQ4_SeSSSf/ SgQ4_ShSSiSj/ SkQ4_SlSSiSm/ SnQ4_SoSSiSp/ SqQ4_SrSSsSt/ SuQ4_SvSSiSw/ SxQ4_SySSSz/ S{Q4_S|S,SS}/ S~Q4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_E0 SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SS,SS/ SQ4_SSSS/ SQ4_SS,SS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSsS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_E0 SSSS/ SQ4_SSSS/ SQ4_SS,SS/ SQ4_SS,SS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSsS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SSSS/ SQ4_SS,SS/ SQ4_SSSS/ SQ4_SSSGS / GSQ4_GSSSGS/ GSQ4_GSS,SGS/ GSQ4_ESGSGS	/ GS
Q4SGSGS/ GSQ4SGSGS/ GSQ4GS.Er " GS GS\R"                  5      r " GS GS\5      r " GS GS\5      rGS rGS rGSGS jr " GS GS\R4                  5      r\\\\\\\/r\GS:X  a  SSKr\R<                  " \5        gg(  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                      \ rS rSrSrg)SerialException$    N)__name__
__module____qualname____firstlineno____static_attributes__r       H/home/james-whalen/.local/lib/python3.13/site-packages/music21/serial.pyr   r   $   s    r   r   c                  2   ^  \ rS rSrSrS rU 4S jrSrU =r$ )TwelveToneMatrix)   a  
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                
   / nU  Hk  n/ nU H@  nUR                  [        UR                  R                  5      R	                  S5      5        MB     UR                  SR                  U5      5        Mm     SR                  U5      $ )z/
Return a string representation of the matrix.
    
)appendstrr	   pitchClassStringrjustjoin)selfretrowFormmsgns        r   __str__TwelveToneMatrix.__str__M   sl     GC

3qww778>>qAB JJrwws|$	 
 yy~r   c                   > U (       a/  [        U S   [        5      (       a	  SU S    S3$ [        TU ]  5       $ [        TU ]  5       $ )Nr   zfor [])
isinstanceToneRowsuper_reprInternal)r#   	__class__s    r   r/   TwelveToneMatrix._reprInternalY   sF    $q'7++tAwiq))w,..7(**r   r   )	r   r   r   r   __doc__r(   r/   r   __classcell__r0   s   @r   r   r   )   s    !F
+ +r   r   
WebernOp29WebernzOp. 29z	Cantata I)r                        
   	   r      
WebernOp28zOp. 28zString Quartet)r9   r   r   r8   r=   r<   r;   r:   r?   r@   r7   r>   SchoenbergOp24Mvmt5
SchoenbergzOp. 24zSerenade, Mvt. 5, "Tanzscene")r?   r>   r   r   r;   r=   r:   r<   r@   r7   r9   r8   SchoenbergOp24Mvmt4zSerenade, Mvt. 4, "Sonett")r;   r8   r   r7   r   r9   r@   r=   r?   r:   r<   r>   SchoenbergJakobsleiterzDie Jakobsleiter)r9   r8   r:   r;   r@   r<   r   r   r7   r>   r=   r?   SchoenbergOp27No4zOp. 27 No. 4z#Four Pieces for Mixed Chorus, No. 4)r9   r   r>   r=   r@   r;   r7   r   r8   r?   r:   r<   
WebernOp23zOp. 23zThree Songs)r@   r   r<   r;   r>   r=   r8   r:   r9   r   r?   r7   BergLuluActIIScene1BergzLulu, Act II, Scene 1z0Perm. (Every 5th Note Of Transposed Primary Row))r>   r<   r9   r   r?   r8   r;   r7   r:   r@   r   r=   SchoenbergOp27No1zOp. 27 No. 1z#Four Pieces for Mixed Chorus, No. 1)r=   r:   r8   r@   r<   r9   r   r;   r>   r?   r7   r   BergLuluActIScene20zLulu, Act I , Scene XXz0Perm. (Every 7th Note Of Transposed Primary Row))r>   r=   r   r@   r:   r7   r;   r8   r?   r   r9   r<   SchoenbergOp27No3zOp. 27 No. 3z#Four Pieces for Mixed Chorus, No. 3)r<   r=   r8   r;   r:   r   r7   r   r@   r>   r?   r9   SchoenbergOp27No2zOp. 27 No. 2z#Four Pieces for Mixed Chorus, No. 2)r   r7   r;   r>   r8   r@   r   r<   r=   r:   r?   r9   SchoenbergFragPianozFragment For Piano)r=   r?   r   r<   r9   r8   r@   r7   r:   r>   r;   r   SchoenbergOp50BzOp. 50BzDe Profundis)r   r?   r@   r;   r8   r>   r<   r7   r   r=   r:   r9   SchoenbergOp50CzOp. 50CzModern Psalms, The First Psalm)r;   r   r   r@   r7   r<   r:   r?   r=   r>   r9   r8   SchoenbergOp50AzOp. 50AzThree Times A Thousand Years)r<   r?   r=   r;   r:   r7   r>   r8   r   r9   r   r@   SchoenbergMosesAronzMoses And Aron)r?   r>   r;   r8   r   r9   r<   r:   r=   r@   r7   r   
WebernOp25zOp. 25)r<   r;   r   r=   r9   r:   r8   r7   r>   r   r?   r@   SchoenbergOp23No5zOp. 23, No. 5zFive Piano Pieces)r9   r?   r7   r<   r@   r=   r>   r8   r;   r   r   r:   SchoenbergOp28No1zOp. 28 No. 1z%Three Satires for Mixed Chorus, No. 1)r   r;   r<   r9   r?   r7   r:   r   r8   r=   r@   r>   SchoenbergOp28No3zOp. 28 No. 3z%Three Satires for Mixed Chorus, No. 3)r:   r=   r;   r@   r8   r>   r<   r?   r   r7   r9   r   
WebernOp21zOp. 21zChamber Symphony)r:   r@   r<   r=   r>   r?   r   r;   r   r9   r8   r7   SchoenbergIsraelExistszIsrael Exists Again)r   r   r;   r?   r7   r:   r8   r9   r>   r@   r=   r<   SchoenbergOp35No2zOp. 35z!Six Pieces for Male Chorus, No. 2)r=   r?   r<   r9   r   r8   r:   r7   r>   r   r;   r@   SchoenbergOp35No3z!Six Pieces for Male Chorus, No. 3)r   r=   r<   r@   r:   r   r?   r>   r;   r7   r8   r9   SchoenbergOp35No1z!Six Pieces for Male Chorus, No. 1)r8   r7   r   r:   r;   r9   r@   r>   r?   r=   r   r<   SchoenbergOp48No1zOp. 48zThree Songs, No. 1, "Sommermud")r9   r8   r   r=   r   r:   r;   r>   r7   r<   r?   r@   SchoenbergOp35No5z!Six Pieces for Male Chorus, No. 5)r9   r<   r>   r8   r   r7   r@   r;   r   r=   r:   r?   SchoenbergOp29Suite)r   r<   r=   r>   r8   r7   r   r?   r@   r;   r:   r9   BergLyricSuitePermz"Lyric Suite, Last Mvt. Permutation)r:   r=   r>   r;   r9   r?   r8   r@   r<   r   r   r7   
WebernOp20zOp. 20zString Trio)r@   r<   r8   r9   r=   r:   r?   r>   r   r;   r   r7   SchoenbergOp46zOp. 46zA Survivor From Warsaw)r=   r<   r   r@   r;   r   r7   r>   r:   r?   r9   r8   SchoenbergFragOrganSonatazFragment of Sonata For Organ)r9   r<   r7   r   r?   r8   r@   r=   r>   r:   r   r;   SchoenbergOp44zOp. 44z!Prelude To A Suite From "Genesis")r>   r=   r8   r:   r;   r   r7   r@   r9   r   r?   r<   SchoenbergOp45zOp. 45)r8   r>   r   r?   r;   r9   r7   r@   r=   r<   r:   r   SchoenbergOp33AzOp. 33AzTwo Piano Pieces, No. 1)r>   r:   r   r7   r?   r=   r9   r   r<   r@   r8   r;   SchoenbergOp25zOp.25zSuite for Piano)r;   r:   r<   r9   r=   r   r@   r8   r7   r   r?   r>   SchoenbergOp26zOp. 26zWind Quintet)r   r<   r?   r7   r9   r   r>   r8   r;   r=   r@   r:   SchoenbergOp33BzOp. 33BzTwo Piano Pieces, No. 2)r7   r9   r:   r   r?   r@   r=   r>   r<   r;   r   r8   BergViolinConcertoz!Concerto For Violin And Orchestra)r<   r>   r8   r=   r?   r   r;   r@   r7   r9   r   r:   
WebernOp22zOp. 22z2Quartet For Violin, Clarinet, Tenor Sax, And Piano)r=   r   r8   r:   r;   r@   r?   r>   r7   r9   r<   r   BergLuluzLulu: Primary Row)r   r;   r:   r8   r<   r?   r=   r@   r7   r>   r   r9   
WebernOp30zOp. 30zVariations For Orchestra)r?   r>   r9   r   r7   r8   r   r=   r:   r;   r<   r@   
WebernOp31zOp. 31z
Cantata II)r=   r?   r:   r;   r@   r   r<   r7   r>   r8   r9   r   WebernOpNo17No1zOp. 17, No. 1z"Armer Sunder, Du")r7   r>   r:   r=   r   r;   r<   r@   r?   r   r9   r8   
WebernOp24zConcerto For Nine Instruments)r7   r>   r8   r   r<   r=   r@   r;   r:   r   r9   r?   SchoenbergOp48No2zThree Songs, No. 2, "Tot")r8   r   r?   r9   r>   r;   r@   r<   r   r7   r:   r=   
WebernOp27zOp. 27zVariations For Piano)r   r7   r>   r8   r9   r   r=   r;   r<   r:   r?   r@   SchoenbergOp47zOp. 47zFantasy For Violin And Piano)r>   r?   r9   r7   r:   r<   r   r;   r   r8   r@   r=   WebernOp19No2zOp. 19, No. 2z"Ziehn Die Schafe")r@   r;   r?   r=   r<   r   r7   r:   r   r8   r>   r9   WebernOp19No1zOp. 19, No. 1z"Weiss Wie Lilien")r<   r>   r=   r:   r   r?   r@   r9   r8   r7   r;   r   
WebernOp26zDas Augenlicht)r@   r>   r?   r   r7   r   r;   r9   r:   r8   r=   r<   SchoenbergFragPianoPhantasiazFragment of Phantasia For Piano)r9   r:   r   r=   r;   r@   r   r7   r8   r?   r>   r<   BergDerWeinzDer Wein)r8   r;   r:   r<   r?   r>   r9   r=   r@   r   r7   r   BergWozzeckPassacagliaz%Wozzeck, Act I, Scene 4 "Passacaglia")r   r7   r<   r9   r   r=   r;   r>   r?   r:   r@   r8   WebernOp18No1zOp. 18, No. 1z"Schatzerl Klein")r   r7   r:   r@   r>   r?   r   r;   r9   r<   r8   r=   WebernOp18No2zOp. 18, No. 2z
"Erlosung")r=   r?   r:   r@   r;   r<   r   r7   r8   r>   r9   r   WebernOp18No3zOp. 18, No. 3z"Ave, Regina Coelorum")r;   r   r<   r=   r:   r7   r>   r8   r9   r   r?   r@   SchoenbergOp42zOp. 42z Concerto For Piano And Orchestra)r   r>   r8   r:   r;   r   r=   r@   r9   r?   r7   r<   SchoenbergOp48No3z!Three Songs, No, 3, "Madchenlied")r9   r<   r?   r7   r   r:   r>   r=   r;   r   r@   r8   SchoenbergOp37zOp. 37zFourth String Quartet)r8   r9   r?   r>   r:   r   r;   r   r@   r<   r=   r7   SchoenbergOp36zOp. 36z!Concerto for Violin and Orchestra)r?   r>   r   r7   r;   r=   r   r9   r<   r@   r8   r:   SchoenbergOp34zOp. 34zAccompaniment to a Film Scene)r   r=   r8   r;   r9   r   r?   r7   r>   r@   r:   r<   BergChamberConcertozChamber Concerto)r7   r<   r:   r?   r8   r   r=   r@   r   r9   r;   r>   SchoenbergOp32zOp. 32zVon Heute Auf Morgen)r8   r   r?   r9   r7   r:   r@   r<   r;   r   r>   r=   SchoenbergOp31zVariations for Orchestra)r>   r;   r=   r   r:   r?   r8   r9   r<   r@   r7   r   SchoenbergOp30zThird String Quartet)r<   r;   r   r?   r   r:   r=   r7   r>   r9   r@   r8   BergLyricSuitezLyric Suite Primary Row)r:   r;   r   r?   r<   r8   r@   r9   r   r=   r>   r7   zOp. 41zOde To Napoleon)r9   r   r;   r:   r?   r@   r   r8   r=   r<   r7   r>   zOp. 17, No. 3z"Heiland, Unsere Missetaten...")r@   r:   r;   r   r<   r=   r   r9   r8   r7   r>   r?   zOp. 17, No. 2z"Liebste Jungfrau")r9   r   r7   r<   r@   r8   r   r=   r:   r;   r?   r>   )SchoenbergOp41WebernOp17No3WebernOp17No2c                     ^  \ rS rSr% SrSS0rS\S'   / SQrSU 4S jjrU 4S	 jr	S
 r
S rS rS rS rS rS rSS jrSS jrS rSrU =r$ )r-      a  
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U ]  " S0 UD6  Ub  Xl        O/ U l        U R                   H  n[        U[        R
                  [        R                  45      (       d  [        R
                  " U5      n[        U[        R                  5      (       d  [        R                  " US9nOUnS UR                  l        U R                  U5        M     g )Nr   r   )
r.   __init__r   r,   r	   Pitchr   Noteoctaver   )r#   r   keywordspcr'   r0   s        r   r   ToneRow.__init__$  s    $8$?HDH((Bb5;;		":;;[[_b$)),,IIB'!AGGNKKN r   c                   > [         TU ]  5       nUR                  S5      (       d  U$ SR                  S U  5       5      $ )N0xr   c              3  L   #    U  H  oR                   R                  v   M     g 7fN)r	   r    ).0r'   s     r   	<genexpr>(ToneRow._reprInternal.<locals>.<genexpr><  s     >Aww//s   "$)r.   r/   
startswithr"   )r#   superInternalr0   s     r   r/   ToneRow._reprInternal7  s<    -/''--  ww>>>>r   c                Z    U  Vs/ s H  oR                   R                  PM     nnU$ s  snf )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   ToneRow.pitchClasses>  s+    & 266AWW''	6 7s   (c                F    U  Vs/ s H  oR                   PM     nnU$ s  snf )a7  
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   ToneRow.noteNamesT  s$     %))DqFFD) *s   c                    U R                  5       n[        U5      S:w  a  gSn[        S5       H  nX1;  d  M
  SnM     U$ )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   ToneRow.isTwelveToneRowd  sF     %%'	y>RD2Y% D  Kr   c                    U R                  5       n[        5       nU H[  n[        R                  " 5       nSUR                  l        X4R                  l        SUR                  l        UR                  U5        M]     U$ )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   makeTwelveToneRowToneRow.makeTwelveToneRow{  sa    $ !!#OF		A'*AJJ$!'GG!AGGNHHQK  r   c                    [        U 5      [        U5      :w  a  g[        X5       H5  u  p#UR                  R                  UR                  R                  :w  d  M5    g   g)a  
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   ToneRow.isSameRow  sM     t9E
"#&t#3H~~((IOO,F,FF $4 r   c                    [        U 5      nU R                  5       nSn[        US-
  5       HG  nX$S-      X$   -
  S-  nU[        S5      ;   a  U[        U5      -   nUS:X  a  US-   nUS:X  d  MB  US-   nMI     U$ )aR  

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   r9   r   r>   Tr7   E)r   r   r   r   )r#   
numPitchesr   intervalStringr   intervals         r   r   ToneRow.getIntervalsAsString  s     Y
%%'	zA~&A!a%(9<72=H59$!/#h-!?2~!/#!52~!/#!5 ' r   c                z   [        U 5      nU R                  5       n[        U5      U:w  a  [        S5      eUS   n/ nUS;   a1  [	        U5       H!  nXG   U-
  U-   S-  nUR                  U5        M#     OUS:X  a0  [	        U5       H   nX%-   XG   -
  S-  nUR                  U5        M"     OUS:X  a7  [	        U5       H'  nX$US-
  U-
     -   U-
  S-  nUR                  U5        M)     OKUS:X  a7  [	        U5       H'  nX$US-
  U-
     -
  U-   S-  nUR                  U5        M)     O[        S	U 35      e[        U5      $ )
a  
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Rr9   RIzInvalid transformation type: )r   r   intr   r   r   pcToToneRow)	r#   transformationTypeindexr   r   
firstPitchtransformedPitchListr   newPitchs	            r   r   "ToneRow.zeroCenteredTransformation  sk   : Y
%%'	u:!"IJJq\
!+:&%L:5=C$++H5 '  3&:&!.=C$++H5 '  3&:&!j1nq.@$AAJNRTT$++H5 '  4':&!j1nq.@$AAJNRTT$++H5 ' "$ABTAU"VWW/00r   c                    U R                  5       nUS   nXB-   S-  nUS;   a  U R                  SU5      $ U R                  X5      $ )a  
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   &ToneRow.originalCenteredTransformation  sV    B %%'	q\
&",+223AA../ALLr   c                0   [        U 5      [        U5      :w  a  gUR                  5       n/ nUS   nUS   nX R                  SU5      R                  5       :X  a  SU4nUR                  U5        X R                  SU5      R                  5       :X  a  SU4nUR                  U5        X R                  SU5      R                  5       :X  a  SU4nUR                  U5        X R                  SU5      R                  5       :X  a  SU4nUR                  U5        U$ )a  
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   'ToneRow.findZeroCenteredTransformations*  s   0 t9H%"//1$Q'
#B'	==c:N[[]] *_N%%n5==c:N[[]] *_N%%n5==c9MZZ\\ )^N%%n5==dIN[[]]!9_N%%n5!!r   c                0   U R                  5       nUR                  5       n/ nUS   nUS   nUS   nXu-
  S-  nXv-
  S-  n	USU-  -
  U-   S-  n
U R                  nX;" SU5      R                  5       :X  a  SU4nUR                  U5        X;" SU5      R                  5       :X  a  SU4nUR                  U5        X;" SU	5      R                  5       :X  a  SU	4nUR                  U5        X;" SU
5      R                  5       :X  a  SU
4nUR                  U5        U$ )	a  
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   r8   r   r   r   r   )r   r   r   )r#   r   originalRowPitchesr   r   oldFirstPitcholdLastPitchnewFirstPitchtiPitchrPitchriPitchocTransr   s                r   r   +ToneRow.findOriginalCenteredTransformationsY  sM   . "..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   r   )returnzt.Union[bool, list[t.Any]])r   r   r   r   r2   r   __annotations__
_DOC_ORDERr   r/   r   r   r   r   r   r   r   r   r   r   r   r3   r4   s   @r   r-   r-      sk    < 	G!I~ \J
&?, .8,671r'MR-"^7" 7"r   r-   c                  j    \ rS rSrSr/ SQrS rS rS rSS jr	S r
SS	 jr          SS
 jrSrg)r   i  zV
A Stream representation of a twelve-tone row, capable of producing a 12-tone matrix.
)matrixisAllIntervalgetLinkClassificationisLinkChordareCombinatorialc           	        U R                  [        R                  5      nU Vs/ s H  nSUR                  R                  -
  S-  PM!     nnU VVs/ s H.  oA Vs/ s H  o"R                  R                  U-   S-  PM      snPM0     nnn[        5       nSnU H  nUS-  nU R                  5       nUR                  U 5        S[        U5      -   Ul	        U H[  n	[        R                  " 5       n
SU
R                  l        XR                  l        SU
R                  l        UR                  U
5        M]     UR                  SU5        M     U$ s  snf s  snf s  snnf )az  
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   r9   zrow-r   N)getElementsByClassr   r   r	   r   r   r0   mergeAttributesr   idr   r   r   r   insert)r#   r   xr   transr   	matrixObjr   	rowObjectr   r'   s              r   r   TwelveToneRow.matrix  s)   . **49955=>Xb177%%%+X>UVWUVEhGhGG&&."4hGUVW$&	CFA(I%%d+!CF?ILIIK+.

(%&"!%  #  Q	*   + ?GWs   &E	E%E?EEc                    / n[          H5  nU R                  [        U5      5      (       d  M$  UR                  U5        M7     U$ )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   findHistoricalTwelveToneRow.findHistorical  s;     +M~~4]CDD. , r   c                H   / nUS:X  aD  [          H8  n[        U5      R                  U 5      nU(       d  M&  UR                  X445        M:     U$ US:X  aF  [          H:  n[        U5      nUR	                  U 5      nU(       d  M(  UR                  X445        M<     U$ [        S5      e)a  
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   findTransformedHistorical'TwelveToneRow.findTransformedHistorical  s    & !/.}=]]^bc5OO]$:; "0 O#!/&<]&K#+OOPTU5OO]$:;	 "0
 O!"UVVr   c                    U R                  5       SL a  [        S5      eSnU R                  5       n[        SS5       H  n[	        U5      U;  d  M  SnM     SU;  a  SnSU;  a  SnU$ )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.Tr9   r>   r   r   )r   r   r   r   r   )r#   tempAllIntervalr   r   s       r   r   TwelveToneRow.isAllInterval  sw      !U*!"RSS224q"A1v^+"'  n$#On$#Or   c                   / SQn/ SQn/ SQn[        U5      nU R                  5       SL a  [        S5      eU U R                  SS5      U R                  SS5      U R                  S	S5      /n/ nS
nU HF  nUR	                  5       n	[        U5       H$  n
X   U	:X  d  M  X:   nUR                  X*   5        M&     MH     U(       d  S
/ 4$ Xv4$ )a  
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179236E8T54r9  17923E685T4179245T8E6317924T586E3179T65234E8179T8E63254r>  1825E43796Tr?  1825E79T364r@  1852E43769T1852E79463T185629TE74318563479TE218563E7T49218734E5296TrF  187E259436TrG  18T352E796418T497E356218T97E52364rJ  18E63T79452rK  19476538TE21947T8536E21954763T8E219742538E6T197425T6E831974T8E6352197T8532E641T5E79283641T63E8742591T6E38524791T8352E46791T974253E68214367TE985214376598ETrY  2143E86597T2149586E37T214976538ETr\  216734ET985216743E9T85217634TE98521T8E95634721T96583E47234T1596E87235189E647Trc  23689E7T145236E981547Tre  23T514697E82513647ET9825189TE7463rh  2546E981T7325691T8E4732569E8T1437258T73E6149258T9614E3725T31496E8725T89E614372618T497E3526347ET9185263891T7E45rr  2653E718T492654T1783E9rt  2654E3871T9ru  2654E7T1983rv  265819TE7432659E8T1347267431T8E952694T817E35269T1783E45r{  269E3871T45r|  26E451T7389r}  26E459817T3r~  26E4T718953r  26E873T514926E95134T8726E95178T43274316E985Tr  2743E86591T274916E385Tr  2749586E31T276134ET985276143E9T8527E34169T852965387E41Tr  296E387T14529TE743618529TE746315829E7835641Tr  2E431T96587r  2E465387T192E637T854192E783T51469r  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   T817Er3  r4  r5  r6  451T71T738598179817TT718971895r(  5134T5178T4316E16E98r  4916E16E38r  6134E276144169T653875387E6E387r  r  E7835r  E431Tr!  rI  37T852E783r(  415T3E8T199658T3142ErS  56T973146752689r  152E958629r  52E98562899268598625765T498265r  5679431T7Er  r  6598129E719E71T2E981r   r  T9E71146T9r  1T649r  51T79rC  r   1629E94T61E612816T49946T19T641r*  r  3652436742T1549r  37641297E5r  T17E917E92r  6194515497r  r  3E241r  r  629E7rL  8T56E8TE659E865rW  r,  r   2E513E513T2315ET315E315E29E251ri  r8  8361Tri  r  E2538r  rR  T856985692142E3)r9   r8   r   r   r;   r:   r=   r<   r@   r?   r>   r7   r                                                                !   r  "   #   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/        r1                          r9     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   #TwelveToneRow.getLinkClassification"  s    D;;x" KF*V )*	!U*!"KLL77Q?77Q?77a@B C002I9%$'94%7%:N$++,@,CD &    8O!33r   c                2    U R                  5       nUS   c  gg)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   TwelveToneRow.isLinkChord  s"    $ ..0	Q<r   c                
   U R                  5       SL a  [        S5      eU R                  X5      nU R                  X45      nUR                  5       nUR                  5       nUSS USS -   n	[	        U	5      R                  5       $ )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.Nr=   )r   r   r   r   r   )
r#   
transType1index1
transType2index2trans1trans2pitches1pitches2testRows
             r   r   TwelveToneRow.areCombinatorial  s    T !U*!"VWW 00D00D&&(&&(2A,"1-7#3355r   r   N)r   bool)
rI  r   rJ  r   rK  r   rL  r   r   rS  )r   r   r   r   r2   r   r   r  r  r   r   r   r   r   r   r   r   r   r     se    NJ.`("WH<@4D056%(56!$56 &)56 "%	56 *.	56r   r   c                     ^  \ rS rSr% SrSSSS.rS\S'   S	rS
\S'   S	rS
\S'   S	r	S
\S'       S     SU 4S jjjr
U 4S jrS rSrU =r$ )HistoricalTwelveToneRowi4  z
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 | strrW  rX  rY  c                L   > [         TU ]  " U40 UD6  Xl        X l        X0l        g r   )r.   r   rW  rX  rY  )r#   rW  rX  rY  r   r   r0   s         r   r    HistoricalTwelveToneRow.__init__C  s&     	)) 	
r   c                   > [         TU ]  U5        [        U[        5      (       d  g UR                  U l        UR
                  U l        UR                  U l        g r   )r.   r   r,   rU  rW  rX  rY  )r#   r   r0   s     r   r   'HistoricalTwelveToneRow.mergeAttributesN  sB    &%!899JJ	[[
r   c                R    U R                    SU R                   SU R                   3$ )N rV  )r#   s    r   r/   %HistoricalTwelveToneRow._reprInternalV  s%    --$))Adjj\::r   )NNNN)rW  rZ  rX  rZ  rY  rZ  )r   r   r   r   r2   r   r   rW  rX  rY  r   r   r/   r   r3   r4   s   @r   rU  rU  4  s    
 C:<!I~  HhD(E8 '+"&#'		#		 !	 	!; ;r   rU  c                    U R                  S5      (       a  U SS n U [        ;   a%  [        U    n[        US   US   US   US   5      nU$ [        S5      e)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   r9   r8   z'No historical row with given name found)r   r  rU  r   )rowNameattrrowObjs      r   r	  r	  Z  sd    N %  !"+. g&(a$q'47DGLGHHr   c                    [        U 5      S:X  a  [        5       nO
[        5       nU  HJ  n[        R                  " 5       nX#R
                  l        SUR
                  l        UR                  U5        ML     U$ )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           	        U  Vs/ s H  nSU-
  S-  PM     nnU VVs/ s H  o0 Vs/ s H
  oU-   S-  PM     snPM     nnn/ nU HW  n/ nU H,  nUR                  [        U5      R                  S5      5        M.     UR                  SR                  U5      5        MY     SR                  U5      $ s  snf s  snf s  snnf )a  
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   rowToMatrixrj    s    V !""1"q&BA"9:;+AE	R+F;
CFJJs6{((+, 

2773< 	  99S> 	#+;s   B2	B<B7B<7B<c                  8    \ rS rSrS rS rS rS rS rS r	Sr
g	)
TestiL  c                "   [        S5      nU R                  U Vs/ s H  o"R                  PM     sn/ SQ5        [        S5      R                  5       nUS   nU R                  U Vs/ s H  oUR                  PM     sn/ SQ5        g s  snf s  snf )Nr   )DC#AB-FE-r   CG#GF#Br   )rt  rx  rv  ru  rs  ro  rn  rq  rw  rr  r   rp  )r	  assertEqualr   r   )r#   srcr   s37r0es         r   
testMatrixTest.testMatrixN  s~    $%56#.#Q&&#.Z	\$%56==?V"-"Q&&"-Z	\	 / .s   B'Bc                   SSK Jn  SSSSSSS	S
SSSSS.nUR                  S5      nUR                  5       R                   HY  nU HP  nUR
                  R                  [
        R                  " U5      R                  :X  d  M=  UR                  X%   5        MR     M[     / nUR                  S   R                  5       R                   H  nUR                  UR                  5        M      U R                  U/ SQ5        g )Nr   )corpusr9   r8   r   r;   r:   r=   r<   r@   r?   r>   r7   r   )r   zg-gza-fze-r}  dczc#zb-bzbwv66.6)%10121r  r  7r  r  r  r  r  r  42r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  5r  )music21r  parseflattennotesr	   r   r   addLyricpartsr   lyricry  )r#   r  seriessr'   keymatchs          r   testLabelingATest.testLabelingAW  s    ""27 LL#""A77%%S)9)D)DDJJv{+  # ##%++ALL! , !5 	6r   c                    / n[          H2  n[        U5      R                  5       SL d  M!  UR                  U5        M4     U R	                  U/ 5        g )NF)r  r	  r   r   ry  )r#   nonRowsr  s      r   testHistoricalTest.testHistoricalj  sE    +M%m4DDF%O}- , 	"%r   c                $    [        S5      nUSS ng)z
Was a problem in slices
rj   r   r   N)r	  )r#   aRowunused_aRow2s      r   testExtractRowPartsTest.testExtractRowPartsq  s     &&:;Aayr   c                4   [        S5      n[        R                  " 5       n[        SSS5       Hg  nXUS-    n[        R
                  " U5      nUR                  UR                  5        UR                  UR                  5        UR                  U5        Mi     g )Nrj   r   r   r   )
r	  r
   Streamr   r   Chordr  primeFormString
forteClassr   )r#   r  bStreamr   aRow2r  s         r   testPostTonalDocsTest.testPostTonalDocsx  ss    %&:;--/q"aA1q5MEE"AJJq(()JJq||$NN1 !r   c                2    SSK Jn  U" U [        5       5        g )Nr   )testCopyAll)music21.test.commonTestr  globals)r#   r  s     r   testCopyAndDeepcopyTest.testCopyAndDeepcopy  s    7D')$r   r   N)r   r   r   r   r~  r  r  r  r  r  r   r   r   r   rl  rl  L  s!    \6&&!	%r   rl  __main__)r   z	list[int]r   r   )r2   
__future__r   typingtunittestr  r   r   r   r   r	   r
   EnvironmentenvironLocalMusic21Exceptionr   r  r   r  r-   r   rU  r	  r   rj  TestCaserl  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S"fmm S"p\6G \6~#;m #;LoIhBJ5r9%8 9%n }&=+[:P
 zT r   