j+n dZddlmZddlZddlZddlmZddlmZddlm Z ddlm Z e j dZ Gd d ej Zd Zd!d Zd!dZd!dZdZd"dZdZ d#dZd$dZdZd%dZd&dZdZdZGddejZeeeeeeeeeeeeeg Ze d krddlZej!edSdS)'z This module defines the L, P, and R objects and their related transformations as called on a :class:`~music21.chord.Chord`, according to Neo-Riemannian theory. ) annotationsN) exceptions21)chord) enharmonics) environmentzanalysis.neoRiemannianceZdZdS) LRPExceptionN)__name__ __module__ __qualname__/Users/tedpeters/Documents/Projects/Claude Projects/Misc Tools/notename-sheets/.venv/lib/python3.11/site-packages/music21/analysis/neoRiemannian.pyr r sDrr cd|jD}tj|}|}t j|}||_|S)a Returns a copy of chord `c` with pitches simplified. Uses `:meth:music21.analysis.enharmonics.EnharmonicSimplifier.bestPitches` >>> c = chord.Chord('B# F- G') >>> c2 = analysis.neoRiemannian._simplerEnharmonics(c) >>> c2 >>> c3 = analysis.neoRiemannian._simplerEnharmonics(c2) Returns a copy even if nothing has changed. >>> c2 is c3 False cg|] }|j Sr nameWithOctave).0ps r z'_simplerEnharmonics..5s555a!555r)pitchesrEnharmonicSimplifier bestPitchescopydeepcopy)c pitchListes newPitchesnewChords r_simplerEnharmonicsr!#sT$6519555I  )) 4 4B!!J}QH!H OrTc|rd}|}n3|r d}|j}n|durt d|St |||}|j|_|S)aB L transforms a major or minor triad through the 'Leading-Tone exchange'. A C major chord, under L, will return an E minor chord, by transforming the root to its leading tone, B. >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = analysis.neoRiemannian.L(c1) >>> c2.pitches (, , ) Chords must be major or minor triads: >>> c3 = chord.Chord('C4 D4 E4') >>> analysis.neoRiemannian.L(c3) Traceback (most recent call last): music21.analysis.neoRiemannian.LRPException: Cannot perform L on this chord: not a major or minor triad If `raiseException` is `False` then the original chord is returned. >>> c4 = analysis.neoRiemannian.L(c3, raiseException=False) >>> c4 is c3 True Accepts any music21 chord, with or without octave specified: >>> noOctaveChord = chord.Chord([0, 3, 7]) >>> chordL = analysis.neoRiemannian.L(noOctaveChord) >>> chordL.pitches (, , ) z-m2m2Tz:Cannot perform L on this chord: not a major or minor triad) isMajorTriadroot isMinorTriadfifthr _singlePitchTransform quarterLengthrraiseExceptiontransposeInterval changingPitchoutChords rLr/<sB ~~ !     T ! ![\\ \$Q(9=IIH_H Orc|r d}|j}n3|r d}|j}n|durtd|St |||}|j|_|S)a P transforms a major or minor triad chord to its 'parallel': i.e. to the chord of the same diatonic name but opposite model. Example: A C major chord, under P, will return an C minor chord >>> c2 = chord.Chord('C4 E4 G4') >>> c3 = analysis.neoRiemannian.P(c2) >>> c3.pitches (, , ) See :func:`~music21.analysis.neoRiemannian.L` for further details about error handling. OMIT_FROM_DOCS >>> c3 = chord.Chord('C4 D4 E4') >>> analysis.neoRiemannian.P(c3) Traceback (most recent call last): music21.analysis.neoRiemannian.LRPException... z-A1A1Tz:Cannot perform P on this chord: not a Major or Minor triad)r$thirdr&r r(r)r*s rPr3ms* ~~ !     T ! ![\\ \$Q(9=IIH_H Orc|r d}|j}n@|rd}|}n|durt d|St |||}|j|_|S)a R transforms a major or minor triad to its relative, i.e. if major, to its relative minor and if minor, to its relative major. Example 1: A C major chord, under R, will return an A minor chord >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = analysis.neoRiemannian.R(c1) >>> c2.pitches (, , ) See :func:`~music21.analysis.neoRiemannian.L` for further details about error handling. OMIT_FROM_DOCS >>> c3 = chord.Chord('C4 D4 E4') >>> analysis.neoRiemannian.R(c3) Traceback (most recent call last): music21.analysis.neoRiemannian.LRPException... M2z-M2Tz:Cannot perform R on this chord: not a Major or Minor triad)r$r'r&r%r r(r)r*s rRr6s* ~~     ! T ! ![\\ \$Q(9=IIH_H Orcjtj|}tj|}tt|jD]Q}d|j|_|j|j|jkr"|j||dRtj |jS)z| Performs a neoRiemannian transformation on c that involves transposing `changingPitch` by `transposeInterval`. FT)inPlace) rrrangelenrspellingIsInferredname transposerChord)rr,r-changingPitchCopyr is rr(r(s  m44}QH 3x'(( ) )KK16.  !X%5a%8%= = =  Q  ) )*;T ) J J J ;x' ( ((rLRPc|j}|D]}|dkrt|}|j|krdS&|dkrt|}|j|krdSJ|dkrt|}|j|krdSnt |ddS)a Tests if two chords are related by a single L, P, R transformation, and returns that transform if so (otherwise, False). >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = chord.Chord('B3 E4 G4') >>> analysis.neoRiemannian.isNeoR(c1, c2) 'L' >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = chord.Chord('C4 E-4 G4') >>> analysis.neoRiemannian.isNeoR(c1, c2) 'P' >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = chord.Chord('C4 E4 A4') >>> analysis.neoRiemannian.isNeoR(c1, c2) 'R' >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = chord.Chord('C-4 E-4 A-4') >>> analysis.neoRiemannian.isNeoR(c1, c2) False Option to limit to the search to only 1-2 transforms ('L', 'R', 'P', 'LR', 'LP', 'RP'). So: >>> c3 = chord.Chord('C4 E-4 G4') >>> analysis.neoRiemannian.isNeoR(c1, c3) 'P' ... but not if P is excluded ... >>> analysis.neoRiemannian.isNeoR(c1, c3, transforms='LR') False r/r6r33 is not a NeoRiemannian transformation (L, R, or P)F) normalOrderr/r6r3r )c1c2 transformsc2NOr@rs risNeoRrIsL >D ZZ 88"A}$$ss% #XX"A}$$ss% #XX"A}$$ss%!XXXYY Y 5rcfgd}|j}|D]"}t||}|j|kr|cS#dS)a Tests if there is a chromatic mediant relation between two chords and returns the type if so (otherwise, False). >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = chord.Chord('A-3 C4 E-4') >>> analysis.neoRiemannian.isChromaticMediant(c1, c2) 'LFM' >>> c3 = chord.Chord('C4 E4 G4') >>> c4 = chord.Chord('C-4 E-4 A-4') >>> analysis.neoRiemannian.isChromaticMediant(c3, c4) False UFMUSMLFMLSMtransformationF)rDchromaticMediants)rErF transformListrH transform thisChords risChromaticMediantrVs]"100M >D" %bCCC  D ( (    ) 5rFc|s-|s|durtd|d|S|r |ddd}g}|D]}|dkr9t|}|r'|t j|A|dkr9t|}|r'|t j||dkr9t|}|r'|t j|t|d |r|s|Sd |DS|s|St|S) a LRP_combinations takes a major or minor triad, transforms it according to the list of L, R, and P transformations in the given transformationString, and returns the result in triad. Certain combinations, such as LPLPLP, are cyclical, and therefore will return a copy of the original chord if `simplifyEnharmonics` = `True` (see :func:`~music21.analysis.neoRiemannian.completeHexatonic`, below). `leftOrdered` allows a user to work with their preferred function notation (left or right orthography). By default, `leftOrdered` is False, so transformations progress towards the right. Thus, 'LPR' will start by transforming the chord by L, then P, then R. If `leftOrdered` is True, the operations work in the opposite direction (right to left), so 'LPR' indicates the result of the chord transformed by R, then P, then L. `simplifyEnharmonics` replaces multiple sharps and flats where they arise from combined transformations with the simpler enharmonic equivalent (e.g. C for D--). If simplifyEnharmonics is True, the resulting chord will be simplified to a collection of notes with at most 1 flat or 1 sharp, in their most common form. >>> c1 = chord.Chord('C4 E4 G4') >>> c2 = analysis.neoRiemannian.LRP_combinations(c1, 'LP') >>> c2 >>> c2b = analysis.neoRiemannian.LRP_combinations(c1, 'LP', leftOrdered=True) >>> c2b >>> c3 = chord.Chord('C4 E4 G4 C5 E5') >>> c4 = analysis.neoRiemannian.LRP_combinations(c3, 'RLP') >>> c4 >>> c5 = chord.Chord('B4 D#5 F#5') >>> c6 = analysis.neoRiemannian.LRP_combinations(c5, ... 'LPLPLP', leftOrdered=True, simplifyEnharmonics=True) >>> c6 >>> c5 = chord.Chord('C4 E4 G4') >>> c6 = analysis.neoRiemannian.LRP_combinations(c5, 'LPLPLP', leftOrdered=True) >>> c6 >>> c5 = chord.Chord('A-4 C4 E-5') >>> c6 = analysis.neoRiemannian.LRP_combinations(c5, 'LPLPLP') >>> c6 Optionally: return all chords creating by the given string in order. >>> c7 = chord.Chord('C4 E4 G4') >>> c8 = analysis.neoRiemannian.LRP_combinations( ... c7, 'LPLPLP', simplifyEnharmonics=True, eachOne=True) >>> c8 [, , , , , ] On that particular case of LPLPLP, see more in :func:`~music21.analysis.neoRiemannian.completeHexatonic`. Tz(Cannot perform transformations on chord z: not a major or minor triadNr/r6r3rCc,g|]}t|Sr )r!rxs rrz$LRP_combinations..s!>>>q'**>>>r) r$r&r r/appendrrr6r3r!)rtransformationStringr+ leftOrderedsimplifyEnharmonicseachOne chordListr@s rLRP_combinationsrbsT >>  ANN$4$4 T ! !Z1ZZZ\\ \:3DDbD9I !ZZ 88!A 3  q!1!1222 #XX!A 3  q!1!1222 #XX!A 3  q!1!1222!XXXYY Y *" ? >>I>>> >" *H&q)) )rc|jdkrbg}|}ttttttg}|D]3}||}|rt|}||4|S|durt ddS)at completeHexatonic returns the list of six triads generated by the operation PLPLPL. This six-part operation cycles between major and minor triads, ultimately returning to the input triad (or its enharmonic equivalent). This functions returns those six triads, ending with the original triad. `simplifyEnharmonics` is False, by default, giving double flats at the end. >>> c1 = chord.Chord('C4 E4 G4') >>> analysis.neoRiemannian.completeHexatonic(c1) [, , , , , ] `simplifyEnharmonics` can be set to True in order to avoid this. >>> c2 = chord.Chord('C4 E4 G4') >>> analysis.neoRiemannian.completeHexatonic(c2, simplifyEnharmonics=True) [, , , , , ] z3-11TzHCannot perform transformations on this chord: not a major or minor triadN) forteClassTnIr3r/r!r\r )rr_r+ hexatonicList lastChord operations operations rcompleteHexatonicris: &    Aq!Q' # , ,I! ),,I" ;/ ::   + + + + T ! !Z\\ \ " !rc|}|j}hddfhddfhddfhddfg}|D] \}}||vr|cStd ) a@ Returns a lowercase string representing the "hexatonic system" that the chord `c` belongs to as classified by Richard Cohn, "Maximally Smooth Cycles, Hexatonic Systems, and the Analysis of Late-Romantic Triadic Progressions," *Music Analysis*, 15.1 (1996), 9-40, at p. 17. Possible values are 'northern', 'western', 'eastern', or 'southern' >>> cMaj = chord.Chord('C E G') >>> analysis.neoRiemannian.hexatonicSystem(cMaj) 'northern' >>> gMin = chord.Chord('G B- D') >>> analysis.neoRiemannian.hexatonicSystem(gMin) 'western' Each chord in the :func:`~music21.analysis.neoRiemannian.completeHexatonic` of that chord is in the same hexatonic system, by definition or tautology. >>> for ch in analysis.neoRiemannian.completeHexatonic(cMaj): ... print(analysis.neoRiemannian.hexatonicSystem(ch)) northern northern northern northern northern northern Note that the classification looks only at the pitch class of the root of the chord. Seventh chords, diminished triads, etc. will also be classified. >>> dDom65 = chord.Chord('F#4 D5 A5 C6') >>> analysis.neoRiemannian.hexatonicSystem(dDom65) 'southern' >rnorthern> eastern> southern> westernz'Odd pitch class that is not in 0 to 11!)r% pitchClassr )rr%rootPCmappingspcSetpoleNames rhexatonicSystemrsL 6688D _FJ'I&Z(Y'H $x U??OOO  @ A AArrLc*gd}||vrtd|d}|dkrd}n|dkrd}n|dkrd }|rd }n&|rd }ntd t||| }t |S)a3 Transforms a chord into the given chromatic mediant. Options: UFM = Upper Flat Mediant; USM = Upper Sharp Mediant; LFM = Lower Flat Mediant ; LSM = Lower Sharp Mediant; Each of these transformations is mode-preserving; involves root motion by a third; entails exactly one common-tone. >>> cMaj = chord.Chord('C5 E5 G5') >>> UFMcMaj = analysis.neoRiemannian.chromaticMediants(cMaj, transformation='UFM') >>> UFMcMaj.normalOrder [3, 7, 10] >>> USMcMaj = analysis.neoRiemannian.chromaticMediants(cMaj, transformation='USM') >>> USMcMaj.normalOrder [4, 8, 11] >>> LFMcMaj = analysis.neoRiemannian.chromaticMediants(cMaj, transformation='LFM') >>> [x.nameWithOctave for x in LFMcMaj.pitches] ['C5', 'E-5', 'A-5'] >>> LSMcMaj = analysis.neoRiemannian.chromaticMediants(cMaj, transformation='LSM') >>> [x.nameWithOctave for x in LSMcMaj.pitches] ['C#5', 'E5', 'A5'] Fine to call on a chord with multiple enharmonics, but will always simplify the output chromatic mediant. >>> cMajEnh = chord.Chord('D--5 F-5 A--5') >>> USM = analysis.neoRiemannian.chromaticMediants(cMaj, transformation='USM') >>> [x.nameWithOctave for x in USM.pitches] ['B4', 'E5', 'G#5'] >>> USM.normalOrder == USMcMaj.normalOrder True rKzTransformation must be one of PRrMLPrNPLrORPTFChord must be major or minorr^) ValueErrorr&r$rbr!)rrQoptionsr]LOs rrRrRsR+**GW$$C'CCDDD# 5 # 5 #~~9    9 78880bAAAA q ! !!rupperc ddg}||vrtd|d}|r |dkrd}n,|r |dkrd}ntdt||}t |S)a Transforms a chord into the upper or lower disjunct mediant. These transformations involve: root motion by a non-diatonic third; mode-change; no common-tones. >>> cMaj = chord.Chord('C5 E5 G5') >>> upr = analysis.neoRiemannian.disjunctMediants(cMaj, upperOrLower='upper') >>> [x.name for x in upr.pitches] ['B-', 'E-', 'G-'] >>> lwr = analysis.neoRiemannian.disjunctMediants(cMaj, upperOrLower='lower') >>> [x.name for x in lwr.pitches] ['B', 'D#', 'G#'] rlowerzupperOrLower must be one of PRPPLPr)rr$r&rbr!)r upperOrLowerrr]s rdisjunctMediantsr3s" G7""AAABBB ~~9 7 " "#(   9 7 " "#( 7888011A q ! !!rc&t|ddS)aI Slide transform connecting major and minor triads with the third as the single common tone (i.e. with the major triad root a semi-tone below the minor). So: root motion by a semi-tone; mode-change; one common-tones. Slide is equivalent to 'LPR'. >>> cMaj = chord.Chord('C5 E5 G5') >>> slideUp = analysis.neoRiemannian.S(cMaj) >>> [x.name for x in slideUp.pitches] ['C#', 'E', 'G#'] >>> aMin = chord.Chord('A4 C5 E5') >>> slideDown = analysis.neoRiemannian.S(aMin) >>> [x.name for x in slideDown.pitches] ['A-', 'C', 'E-'] LPRFr_rbrs rSrWs( Au% @ @ @@rc&t|ddS)a  The 'Neberverwandt' ('fifth-change') transform connects a minor triad with its major dominant, and so also a major triad with its minor sub-dominant, with one common tone in each case. This is equivalent to 'RLP'. >>> cMaj = chord.Chord('C5 E5 G5') >>> n1 = analysis.neoRiemannian.N(cMaj) >>> [x.name for x in n1.pitches] ['C', 'F', 'A-'] >>> aMin = chord.Chord('A4 C5 E5') >>> n2 = analysis.neoRiemannian.N(aMin) >>> [x.name for x in n2.pitches] ['G#', 'B', 'E'] RLPFrrrs rNrms& Au% @ @ @@rc2eZdZdZdZdZdZdZdZdS)Testctjd}t|}t|}|t |d||tj|t |dtjd}tj|}tdD]}t|}||j |j tjd}tj|}tdD]}t|}||j |j tjd}tj|}tdD]}t|}||j |j dS)N C4 E-4 G4z zzC4 E4 G4 C5 C5 G5rkzC4 E4 G4 C5 E5 G5) rr>r/r3 assertEqualstrassertIsInstancerrr9rr6)selfrFc2_Lc2_Pc5copyC5r@s r testNeoRiemannianTransformationsz%Test.testNeoRiemannianTransformationss [ % %uuuu T$FGGG dEK000 T$DEEE [, - -r""q  A2BB 444 [, - -r""q  A2BB 444 [, - -r""q  A2BB 44444rctjd}t|d}|t |dtjd}t|d}|t |dtjd}t|dd}|t |d tjd }t|d}|t |d tjd } t| dd } || | |t5t| dddddn #1swxYwYtjd} |t5t| dddddn #1swxYwYtjd} t| dd} |tjdj| jdS)NC4 E4 G4rzzC4 E4 G4 C5 E5rz%Trz' C-4 E-4 G-4z zB- D# F#F)r+zB# F G#B# E# G#zC# E G#) rr>rbrrassertIs assertRaisesr r)rrc5_Tc6c6_Tc7c7_Tc8c8_Td_sharp_min_misspelledd_sharp_min_transformedf_min_misspelled e_sharp_mine_sharp_min_transformeds rtestNeoRiemannianCombinationsz"Test.testNeoRiemannianCombinationss [ $ $D)) T$EFFF [) * *E** T$KLLL [) * *Dd;;; T$MNNN [ ' 'D)) T$FGGG!&Z!8!8"23I4BG#I#I#I ,.EFFF   | , , P P 3T$ O O O O P P P P P P P P P P P P P P P!;y11   | , , J J -tD I I I I J J J J J J J J J J J J J J Jk*-- "2;UY"Z"Z"Z Y//79P9XYYYYYs$5FFF G,,G03G0ctjd}tjd}t||}||dtjd}t||}||dt||d}||tjd}t||}||d tjd }t ||} || d tjd } t|| } t || } || || tjd } tjd}t| |}t | |}||||d dS)NrzB3 E4 G4r/rr3LR)rGzC4 E4 A4r6z C4 E-4 A-4rNz C-4 E-4 A-4rz C-4 E--4 A--4)rr>rIr assertFalserV)rrErFans1c3ans2c4ans3rans4rans5ans6rrans7ans8s r testIsNeoRzTest.testIsNeoRs [ $ $ [ $ $b"~~ s### [ % %b"~~ s###b"...  [ $ $b"~~ s### [ & &!"b)) u%%% [ ' 'b"~~!"b))   [ ' ' [ ) )b"~~!"b))  u%%%%%rctjd}tjd}t|d}||jgdt|d}||jgdt|d}|d |jDgd t|d }|d |jDgd t |d}|d|jDgdt |d}|d|jDgddS)NC5 E5 G5z C#5 E#5 G#5rLrP)rvrwrtrM)rkrlrxrNcg|] }|j Sr rrZs rrz%Test.testMediants..DDDq!*DDDr)C5zE-5zA-5rOcg|] }|j Sr rrZs rrz%Test.testMediants..rr)zC#5E5A5r)rcg|] }|j Sr r<rZs rrz%Test.testMediants..s>>>Q!&>>>r)BEGrcg|] }|j Sr rrZs rrz%Test.testMediants..sJJJq!*JJJr)rrr)rr>rRrrDrr) rc9c9aUFMcMajUSMcMajLFMcMajLSMcMaj upChromatic downChromatics r testMediantszTest.testMediantss [ $ $k-((#Bu=== ,jjj999#Bu=== ,jjj999#Bu=== DDGODDDFZFZFZ[[[#Bu=== DDGODDDFYFYFYZZZ&sAAA  >>+*=>>>PPP(7CCC  JJM4IJJJ+++ - - - - -rctjd}tjd}t|}|d|jDgdt|}|d|jDgdt |}|d|jDgdt |}|d |jDgd dS) NrzA4 C5 E5cg|] }|j Sr rrZs rrz Test.testSnN..s:::Q!&:::r)zC#rG#cg|] }|j Sr rrZs rrz Test.testSnN..s<<.555Q!&555r)rFrcg|] }|j Sr rrZs rrz Test.testSnN.. rr)rrr)rr>rrrr)rc10c11slideUp slideDownN1N2s rtestSnNz Test.testSnNs k*%%k*%%C&& ::'/:::O>O>OPPP sVV 55"*5557G7G7GHHH sVV 55"*5557G7G7GHHHHHrcttjd}ttjgd}||j|j||jtjdjtjd}t |dd}tjgd}t |dd}||jd j|jD]}||j||j|j||jtjd jdS) NzC# E# G#)rnrorlrzB D# F#rFr)rxrvrsrz A# D# F##) r/rr>rrrb assertTruer;r)rc_sharp_maj_named_transformed%c_sharp_maj_pitch_classes_transformed b_maj_namedb_maj_named_transformedb_maj_pitch_classesb_maj_pitch_classes_transformedrs rtestInstantiatingChordPCNumbersz$Test.testInstantiatingChordPCNumbers s()%+j*A*A(B(B%01%+iii2H2H0I0I- 6>>F H H H >FZ008 : : :k),, "2;GL#N#N#N#k***55*:;NPTOT+V+V+V' +3A6IJJJ08 3 3A   Q1 2 2 2 2 088@ B B B 8@[119 ; ; ; ; ;rN) r r r rrrrrrr rrrrsv5554ZZZ@"&"&"&H---0III";;;;;rr__main__)T)rA)TFFF)FT)rL)r)"__doc__ __future__rrunittestmusic21rrmusic21.analysisrr Environment environLocalMusic21Exceptionr r!r/r3r6r(rIrVrbrirrRrrrTestCaser _DOC_ORDERr mainTestr rrrsv #"""""  ((((((&{&'?@@      <0   2////b####J####J ) ) )8888t@%)!&)." n*n*n*n*`*\*\*\*\X2B2B2Br>">">">"@""""""""HAAA,AAA._;_;_;_;_;8 _;_;_;Hq!Q6',)   zNNNGTr