
    rhh                      % S r SSKJr  / SQrSSKrSSKrSSKJr  SSK	J
r
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  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  \R2                  " S5      r\\\\\\
\4   r 0 r!S\"S'    " S S\RF                  5      r$ " S S\RJ                  5      r& " S S\&5      r' " S S\'5      r( " S S\'5      r) " S S \'5      r* " S! S"\'5      r+ " S# S$\'5      r, " S% S&\'5      r- " S' S(\'5      r. " S) S*\'5      r/ " S+ S,\'5      r0 " S- S.\&5      r1 " S/ S0\15      r2 " S1 S2\25      r3 " S3 S4\25      r4 " S5 S6\25      r5 " S7 S8\25      r6 " S9 S:\25      r7 " S; S<\25      r8 " S= S>\25      r9 " S? S@\25      r: " SA SB\25      r; " SC SD\25      r< " SE SF\25      r= " SG SH\25      r> " SI SJ\25      r? " SK SL\25      r@ " SM SN\25      rA " SO SP\15      rB " SQ SR\15      rC " SS ST\15      rD " SU SV\15      rE " SW SX\15      rF " SY SZ\15      rG " S[ S\\15      rH " S] S^\15      rI " S_ S`\15      rJ " Sa Sb\15      rK\1\'/rL\MSc:X  a  SSKr\R                  " 5         gg)da  
The various Scale objects provide a bidirectional object representation
of octave repeating and non-octave repeating scales built by network
of :class:`~music21.interval.Interval` objects as modeled
in :class:`~music21.intervalNetwork.IntervalNetwork`.

The main public interface to these resources are subclasses
of :class:`~music21.scale.ConcreteScale`, such
as :class:`~music21.scale.MajorScale`, :class:`~music21.scale.MinorScale`,
and :class:`~music21.scale.MelodicMinorScale`.

More unusual scales are also available, such
as :class:`~music21.scale.OctatonicScale`, :class:`~music21.scale.SieveScale`,
and :class:`~music21.scale.RagMarwa`.

All :class:`~music21.scale.ConcreteScale` subclasses provide the ability
to get a pitches across any range, get a pitch for scale step, get a
scale step for pitch, and, for any given pitch ascend or descend to the
next pitch. In all cases :class:`~music21.pitch.Pitch` objects are returned.

>>> sc1 = scale.MajorScale('a')
>>> [str(p) for p in sc1.getPitches('g2', 'g4')]
['G#2', 'A2', 'B2', 'C#3', 'D3', 'E3', 'F#3', 'G#3', 'A3', 'B3', 'C#4', 'D4', 'E4', 'F#4']

>>> sc2 = scale.MelodicMinorScale('a')
>>> [str(p) for p in sc2.getPitches('g2', 'g4', direction=scale.Direction.DESCENDING)]
['G4', 'F4', 'E4', 'D4', 'C4', 'B3', 'A3', 'G3', 'F3', 'E3', 'D3', 'C3', 'B2', 'A2', 'G2']

>>> [str(p) for p in sc2.getPitches('g2', 'g4', direction=scale.Direction.ASCENDING)]
['G#2', 'A2', 'B2', 'C3', 'D3', 'E3', 'F#3', 'G#3', 'A3', 'B3', 'C4', 'D4', 'E4', 'F#4']
    )annotations)+intervalNetworkscala	DirectionTerminusScaleExceptionScaleAbstractScaleAbstractDiatonicScaleAbstractOctatonicScaleAbstractHarmonicMinorScaleAbstractMelodicMinorScaleAbstractCyclicalScaleAbstractOctaveRepeatingScaleAbstractRagAsawariAbstractRagMarwaAbstractWeightedHexatonicBluesConcreteScaleDiatonicScale
MajorScale
MinorScaleDorianScalePhrygianScaleLydianScaleMixolydianScaleHypodorianScaleHypophrygianScaleHypolydianScaleHypomixolydianScaleLocrianScaleHypolocrianScaleHypoaeolianScaleHarmonicMinorScaleMelodicMinorScaleOctatonicScaleOctaveRepeatingScaleCyclicalScaleChromaticScaleWholeToneScale
SieveScale
ScalaScale
RagAsawariRagMarwaWeightedHexatonicBluesN)r   )r   r   )r   )base)common)
deprecated)defaults)environment)exceptions21)note)pitch)interval)sievescalezdict[_PitchDegreeCacheKey, str]_pitchDegreeCachec                      \ rS rSrSrg)r   b    N)__name__
__module____qualname____firstlineno____static_attributes__r=       P/home/james-whalen/.local/lib/python3.13/site-packages/music21/scale/__init__.pyr   r   b   s    rC   r   c                  `   ^  \ rS rSrSrU 4S jr\S 5       r\S 5       r\	SS j5       r
SrU =r$ )	r	   f   z
Generic base class for all scales, both abstract and concrete.

>>> s = scale.Scale()
>>> s.type
'Scale'
>>> s.name  # default same as type.
'Scale'
>>> s.isConcrete
False

Not a useful class on its own.  See its subclasses.
c                4   > [         TU ]  " S0 UD6  SU l        g )Nr	   r=   )super__init__typeselfkeywords	__class__s     rD   rI   Scale.__init__t   s    $8$	rC   c                    U R                   $ )z,
Return or construct the name of this scale
rJ   rL   s    rD   name
Scale.namex   s    
 yyrC   c                    g)z
To be concrete, a Scale must have a defined tonic.
An abstract Scale is not Concrete, nor is a Concrete scale
without a defined tonic.  Thus, is always false.
Fr=   rR   s    rD   
isConcreteScale.isConcrete   s     rC   c                   / n[        U S5      (       a  [        U R                  5      nO[        R                  " U 5      (       a  / nU  H  n[        US5      (       a  UR                  UR                  5        M1  [        U[        R                  5      (       a  UR                  U5        Mc  UR                  [        R                  " U5      5        M     O[        U S5      (       a  U R                  /nUSL a  U$ 0 n/ nU H*  n[        XA5      nXu;  d  M  SXW'   UR                  U5        M,     U H'  nUR                  b  M  [        R                  Ul
        M)     U$ )a  
Utility function and staticmethod

Given a data format as "other" (a ConcreteScale, Chord, Stream, List of Pitches,
or single Pitch),
extract all unique Pitches using comparisonAttribute to test for them.

>>> pStrList = ['A4', 'D4', 'E4', 'F-4', 'D4', 'D5', 'A', 'D#4']
>>> pList = [pitch.Pitch(p) for p in pStrList]
>>> nList = [note.Note(p) for p in pStrList]
>>> s = stream.Stream()
>>> for n in nList:
...     s.append(n)

Here we only remove the second 'D4' because the default comparison is `nameWithOctave`

>>> [str(p) for p in scale.Scale.extractPitchList(pList)]
['A4', 'D4', 'E4', 'F-4', 'D5', 'A4', 'D#4']

Note that octaveless notes like the 'A' get a default octave.  In general,
it is better to work with octave-possessing pitches.

Now we remove the F-4, D5, and A also because we are working with
`comparisonAttribute=pitchClass`.
Note that we're using a Stream as `other` now:

>>> [str(p) for p in scale.Scale.extractPitchList(s, comparisonAttribute='pitchClass')]
['A4', 'D4', 'E4', 'D#4']

Now let's get rid of all but one diatonic `D`
by using :meth:`~music21.pitch.Pitch.step` as our
`comparisonAttribute`.  Note that we can just give a list of
strings as well, and they become :class:`~music21.pitch.Pitch` objects. Oh, we will also
show that `extractPitchList` works on any scale:

>>> sc = scale.Scale()
>>> [str(p) for p in sc.extractPitchList(pStrList, comparisonAttribute='step')]
['A4', 'D4', 'E4', 'F-4']
pitchesr6   FT)hasattrlistrY   r0   
isIterableappendr6   
isinstancePitchgetattroctaver2   pitchOctave)othercomparisonAttributeremoveDuplicatesprepuniquePitchespost	hashValues           rD   extractPitchListScale.extractPitchList   s   T 5)$$u}}%Cu%%C1g&&JJqww'5;;//JJqMJJu{{1~.  UG$$;;-Cu$JA7I-+/(A	 
 Axx#//  rC   rQ   )nameWithOctaveT)r>   r?   r@   rA   __doc__rI   propertyrS   rV   staticmethodrk   rB   __classcell__rN   s   @rD   r	   r	   f   sK         K KrC   r	   c                    ^  \ rS rSrSrSrU 4S jrS rS r\	S 5       r
S rS	S	\R                  S
4S jrS	S	S	\R                  S
4S jr\R                  S	S	S4S jr\R                  S	S	4S jrS\R                  4S jr\R                  SS4   SS jjr\R                  S	S	4S jr\R                  4S jrS	S	\R                  4S jrS	S	\R                  4S jrSrU =r$ )r
      a7  
An abstract scale is specific scale formation, but does not have a
defined pitch collection or pitch reference. For example, all Major
scales can be represented by an AbstractScale; a ConcreteScale,
however, is a specific Major Scale, such as G Major.

These classes provide an interface to, and create and manipulate,
the stored :class:`~music21.intervalNetwork.IntervalNetwork`
object. Thus, they are rarely created or manipulated directly by
most users.

The AbstractScale additionally stores an `_alteredDegrees` dictionary.
Subclasses can define altered nodes in AbstractScale that are passed
to the :class:`~music21.intervalNetwork.IntervalNetwork`.

Equality
--------
Two abstract scales are the same if they have the same class and the
same tonicDegree and octaveDuplicating attributes and the same intervalNetwork,
and it satisfies all other music21 superclass attributes.

>>> as1 = scale.AbstractOctatonicScale()
>>> as2 = scale.AbstractOctatonicScale()
>>> as1 == as2
True
>>> as2.tonicDegree = 5
>>> as1 == as2
False

>>> as1 == scale.AbstractDiatonicScale()
False
)tonicDegree_netoctaveDuplicatingc                l   > [         TU ]  " S0 UD6  S U l        SU l        SU l        SU l        0 U l        g )N   Tr=   )rH   rI   rv   ru   rw   deterministic_alteredDegreesrK   s     rD   rI   AbstractScale.__init__   s@    $8$	 "& "  "rC   c                    [         e)z
Calling the buildNetwork, with or without parameters,
is main job of the AbstractScale class.  This needs to be subclassed by a derived class
)NotImplementedErrorrR   s    rD   buildNetworkAbstractScale.buildNetwork  s
    
 "!rC   c                   / nU H  n[        U[        5      (       a'  UR                  [        R                  " U5      5        M?  [        U[
        R                  5      (       a  UR                  UR                  5        M{  UR                  U5        M     UnU R                  U5        [        R                  " U5      (       a  U(       d  [        SU 35      e/ n[        XSS 5       H*  u  pVUR                  [        R                  " XV5      5        M,     US   R                  US   R                  :X  a?  [        R                  " US   US   5      nUR                  S:X  a	  SU l        GOQSU l        GOH[         R"                  " US   5      nUR$                  c  UR&                  Ul        US   US   :  aR  UR(                  US   R(                  :  a4  U=R$                  S-  sl        UR(                  US   R(                  :  a  M4  OQUR(                  US   R(                  :  a4  U=R$                  S-  sl        UR(                  US   R(                  :  a  M4  UR                  [        R                  " US   U5      5        [        R                  " US   U5      nUR                  S:X  a  SU l        OSU l        [*        R,                  " UU R                  S	9U l        g)
a.  
Builds the network (list of motions) for an abstract scale
from a list of pitch.Pitch objects.  If
the concluding note (usually the "octave") is not given,
then it'll be created automatically.

Here we treat the augmented triad as a scale:

>>> p1 = pitch.Pitch('C4')
>>> p2 = pitch.Pitch('E4')
>>> p3 = pitch.Pitch('G#4')
>>> abstractScale = scale.AbstractScale()
>>> abstractScale.buildNetworkFromPitches([p1, p2, p3])
>>> abstractScale.octaveDuplicating
True
>>> abstractScale._net
<music21.scale.intervalNetwork.IntervalNetwork object at 0x...>

Now see it return a new "scale" of the augmentedTriad on D5

>>> abstractScale._net.realizePitch('D5')
[<music21.pitch.Pitch D5>, <music21.pitch.Pitch F#5>,
 <music21.pitch.Pitch A#5>, <music21.pitch.Pitch D6>]

It is also possible to use implicit octaves:

>>> abstract_scale = scale.AbstractScale()
>>> abstract_scale.buildNetworkFromPitches(['C', 'F'])
>>> abstract_scale.octaveDuplicating
True
>>> abstract_scale._net.realizePitch('G')
[<music21.pitch.Pitch G4>, <music21.pitch.Pitch C5>, <music21.pitch.Pitch G5>]
z-Cannot build a network from this pitch list: ry   Nr   P8TFrw   )r^   strr]   r6   r_   r5   NotefixDefaultOctaveForPitchListr0   
isListLiker   zipr7   IntervalrS   rw   copydeepcopyra   implicitOctavepsr   IntervalNetworkrv   )rL   	pitchListpitchListRealrg   intervalListcurrentPitch	nextPitchspans           rD   buildNetworkFromPitches%AbstractScale.buildNetworkFromPitches  sU   D A!S!!$$U[[^4Atyy))$$QWW-$$Q'  "	)))4  ++9 #PQZP[!\]]'*9m'D#L 1 1, JK (ER=1!2!22 $$Yq\9R=ADyyD )-&).&il+Axx++}y|+ddYr]---HHMH ddYr]--- ddYr]---HHNH ddYr]---  1 1)B- CD$$Yq\15DyyD )-&).& $33LFJF\F\^	rC   c                   SnU S   R                   nU  Hh  nUR                  c@  XR                  :  a  X#l        XR                  :  a  US-  nX#l        XR                  :  a  M  UR                  nUR                   nMj     U $ )aY  
Suppose you have a set of octaveless Pitches that you use to make a scale.

Something like:

>>> pitchListStrs = 'a b c d e f g a'.split()
>>> pitchList = [pitch.Pitch(p) for p in pitchListStrs]

Here's the problem, between `pitchList[1]` and `pitchList[2]` the `.implicitOctave`
stays the same, so the `.ps` drops:

>>> (pitchList[1].implicitOctave, pitchList[2].implicitOctave)
(4, 4)
>>> (pitchList[1].ps, pitchList[2].ps)
(71.0, 60.0)

Hence this helper staticmethod that makes it so that for octaveless pitches ONLY, each
one has a .ps above the previous:

>>> pl2 = scale.AbstractScale.fixDefaultOctaveForPitchList(pitchList)
>>> (pl2[1].implicitOctave, pl2[2].implicitOctave, pl2[3].implicitOctave)
(4, 5, 5)
>>> (pl2[1].ps, pl2[2].ps)
(71.0, 72.0)

Note that the list is modified inPlace:

>>> pitchList is pl2
True
>>> pitchList[2] is pl2[2]
True
r   ry   )r   ra   r   )r   lastPs
lastOctaverg   s       rD   r   *AbstractScale.fixDefaultOctaveForPitchListr  s{    H q\00
AxxDD=)Httm!OJ)H ttm TTF))J  rC   c                .    U R                   R                  $ )zN
Return the maximum number of scale steps, or the number to use as a
modulus.
)rv   degreeMaxUniquerR   s    rD   getDegreeMaxUnique AbstractScale.getDegreeMaxUnique  s     yy(((rC   NFc           
         U R                   c  [        S5      eU R                   R                  UUUUU R                  UUS9n[        R
                  " U5      $ )z
Realize the abstract scale as a list of pitch objects,
given a pitch object, the step of that pitch object,
and a min and max pitch.
z.no IntervalNetwork is defined by this "scale".minPitchmaxPitchalteredDegrees	directionreverse)rv   r   realizePitchr{   r   r   )rL   pitchObjstepOfPitchr   r   r   r   ri   s           rD   getRealizationAbstractScale.getRealization  s^     99 !QRRyy%%h&1/7/7595I5I09.5 & 7 }}T""rC   c           	         U R                   c  [        S5      eU R                   R                  UUUU R                  UUS9nU$ )z
Realize the abstract scale as a list of pitch
objects, given a pitch object, the step of
that pitch object, and a min and max pitch.
zno network is defined.r   )rv   r   realizeIntervalsr{   )rL   r   r   r   r   r   ri   s          rD   getIntervalsAbstractScale.getIntervals  sQ     99 !9::yy))+3;3;9=9M9M4=29 * ; rC   Tc                    U R                   R                  UUUUUUU R                  US9n[        R                  " U5      $ )z'
Get a pitch for desired scale degree.
)pitchReferencenodeNamenodeDegreeTargetr   r   r   r   equateTerminirv   getPitchFromNodeDegreer{   r   r   )	rL   r   r   r   r   r   r   r   ri   s	            rD   r   $AbstractScale.getPitchFromNodeDegree  sL     yy//)-//' 0 	
 }}T""rC   c           
         U R                   R                  UUUUUUU R                  S9n[        R                  " U5      $ )a  
Given one or more scale degrees, return a list of
all matches over the entire range.

See :meth:`~music21.intervalNetwork.IntervalNetwork.realizePitchByDegree`.
in `intervalNetwork.IntervalNetwork`.

Create an abstract pentatonic scale:

>>> pitchList = ['C#4', 'D#4', 'F#4', 'G#4', 'A#4']
>>> abstractScale = scale.AbstractScale()
>>> abstractScale.buildNetworkFromPitches([pitch.Pitch(p) for p in pitchList])
)r   nodeIdnodeDegreeTargetsr   r   r   r   )rv   realizePitchByDegreer{   r   r   )rL   r   r   r   r   r   r   ri   s           rD   r   "AbstractScale.realizePitchByDegree  sI    * yy--)/// . 1 }}T""rC   
pitchClassc           	     ~    U R                   R                  UUUUUU R                  S9n[        R                  " U5      $ )z
Expose functionality from
:class:`~music21.intervalNetwork.IntervalNetwork`, passing on the
stored alteredDegrees dictionary.
)r   r   pitchTargetrd   r   r   )rv   getRelativeNodeDegreer{   r   r   )rL   r   r   r   rd   r   ri   s          rD   r   #AbstractScale.getRelativeNodeDegree  sF     yy..)# 3// / 
 }}T""rC   ry   c           
         U R                   R                  UUUUUU R                  US9n[        R                  " U5      $ )z
Expose functionality from :class:`~music21.intervalNetwork.IntervalNetwork`,
passing on the stored alteredDegrees dictionary.
)r   r   pitchOriginr   stepSizer   getNeighbor)rv   r   r{   r   r   )rL   r   r   r   r   r   r   ri   s           rD   r   AbstractScale.nextPitch3  sH     yy"".,4/:-6,4262F2F/: # % }}T""rC   c           
         U R                   R                  UUSUUUU R                  S9n[        R                  " U5      $ )z#
Define a pitch target and a node.
ry   )r   r   r   r   r   r   r   r   )rL   r   r   r   r   r   ri   s          rD   getNewTonicPitchAbstractScale.getNewTonicPitchH  sI     yy//)// 0 
 }}T""rC   c                    U R                  US9n[        R                  " 5       nUR                  U5        [	        U 5      Ul        U$ )z_
Get the interval sequence as a :class:~music21.scala.ScalaData object
for a particular scale:
r   )r   r   	ScalaDatasetIntervalSequencereprdescription)rL   r   	intervalssss       rD   getScalaDataAbstractScale.getScalaData^  sA     %%	%:	__
y)d	rC   c                ^   Ub  [         R                  " U5      u  pVUc  [        R                  U5      nOUnUS:X  aY  U R	                  US9n[
        R                  " U5      n	U	R                  US5        U	R                  5         U	R                  5         U$ [        R                  " U 4XS.UD6$ )zG
Write the scale in a format. Here, prepare scala format if requested.
r   r   wfmtfp)r0   
findFormatenvironLocalgetTempFiler   r   	ScalaFileopenwritecloser	   )
rL   r   r   r   rM   
fileFormatextfpLocalr   sfs
             rD   r   AbstractScale.writej  s     ?$//4OJz&2237W$&&&;__R(%

{{4<S<8<<rC   c                    SSK Jn  UbC  [        R                  " U5      u  pgUS:X  a%  U R	                  XcS9nU" 5       R                  XUS9  g[        R                  " U 4XS.UD6  g)zF
Show the scale in a format. Here, prepare scala format if requested.
r   )SubConverterNr   r   r   app)music21.converter.subConvertersr   r0   r   r   launchr	   show)	rL   r   r   r   rM   r   r   
unused_extreturnedFilePaths	            rD   r   AbstractScale.show~  sh     	A?%+%6%6s%;"JW$#'::j:#N %%&6C%P

46S6X6rC   )r{   rv   rz   rw   ru   r   r   r   Direction | bool)r>   r?   r@   rA   rn   equalityAttributesrI   r   r   rp   r   r   r   	ASCENDINGr   r   r   r   r   r   r   r   r   r   rB   rq   rr   s   @rD   r
   r
      s3   B F"$"Z^x 0 0d)( !% $!*!4!4$#6 "&""(22"8 *3)<)<(,(,-1#6 (1':':&*&*#F 3?(1(;(;#2 *3)<)<04# '	#  .#0 $-#6#6"&"&#, &/%8%8 
 1D1D =( 1D1D 7 7rC   r
   c                  >   ^  \ rS rSrSrSSU 4S jjjrSS jrSrU =r$ )r   i  a  
An abstract representation of a Diatonic scale w/ or without mode.

>>> as1 = scale.AbstractDiatonicScale('major')
>>> as1.type
'Abstract diatonic'
>>> as1.mode
'major'
>>> as1.octaveDuplicating
True

Equality
--------
AbstractDiatonicScales must satisfy all the characteristics of a
general AbstractScale but also need to have equal dominantDegrees.

>>> as1 = scale.AbstractDiatonicScale('major')
>>> as2 = scale.AbstractDiatonicScale('lydian')
>>> as1 == as2
False

Note that their modes do not need to be the same.
For instance for the case of major and Ionian which have
the same networks:

>>> as3 = scale.AbstractDiatonicScale('ionian')
>>> (as1.mode, as3.mode)
('major', 'ionian')
>>> as1 == as3
True
c                   > [         TU ]  " S0 UD6  Xl        SU l        S U l        S U l        SU l        SU l        SU l        U R                  US9  g )NzAbstract diatonicTr   moder=   )
rH   rI   r   rJ   ru   dominantDegreerw   relativeMinorDegreerelativeMajorDegreer   rL   r   rM   rN   s      rD   rI   AbstractDiatonicScale.__init__  sX    $8$	'	"!%(* (* t$rC   c                   SnSU l         SU l        [        U[        5      (       a  UR	                  5       nUS;   a  UnSU l        SU l        GOUS:X  a  USS USS -   nSU l        SU l        GOUS	:X  a  US
S USS
 -   nSU l        SU l        GOUS:X  a  USS USS -   nSU l        SU l        GO}US:X  a  USS USS -   nSU l        S
U l        GO\US;   a  USS USS -   nSU l        SU l        GO;US:X  a  USS USS -   nS
U l        SU l        GOUS:X  a(  USS USS -   nSU l         SU l        SU l        SU l        OUS:X  a(  USS USS -   nSU l         SU l        S
U l        SU l        OUS:X  a  UnSU l         SU l        SU l        SU l        OUS:X  a(  USS USS -   nSU l         SU l        SU l        SU l        OkUS:X  a(  US
S USS
 -   nSU l         SU l        SU l        SU l        O=US:X  a(  USS USS -   nSU l         SU l        SU l        SU l        O[        SU< 35      e[        R                  " UU R                  SS9U l        g)a  
Given subclass dependent parameters, build and assign the IntervalNetwork.

>>> sc = scale.AbstractDiatonicScale()
>>> sc.buildNetwork('Lydian')  # N.B. case-insensitive name
>>> [str(p) for p in sc.getRealization('f4', 1, 'f2', 'f6')]
['F2', 'G2', 'A2', 'B2', 'C3', 'D3', 'E3',
 'F3', 'G3', 'A3', 'B3', 'C4', 'D4', 'E4',
 'F4', 'G4', 'A4', 'B4', 'C5', 'D5', 'E5',
 'F5', 'G5', 'A5', 'B5', 'C6', 'D6', 'E6', 'F6']

Unknown modes raise an exception:

>>> sc.buildNetwork('blues-like')
Traceback (most recent call last):
music21.scale.ScaleException: Cannot create a
    scale of the following mode: 'blues-like'

* Changed in v6: case-insensitive modes
)M2r   m2r   r   r   r   ry      )Nmajorionian   dorianN   phrygian      lydian   
mixolydian)aeolianminorlocrian
hypodorianhypophrygian
hypolydianhypomixolydianhypoaeolianhypolocrianz-Cannot create a scale of the following mode: rw   pitchSimplification)ru   r   r^   r   lowerr   r   r   r   r   rw   rv   rL   r   srcListr   s       rD   r   "AbstractDiatonicScale.buildNetwork  s   . =dC  ::<D,,"L'(D$'(D$X"12;!4L'(D$'(D$Z"12;!4L'(D$'(D$X"12;!4L'(D$'(D$\!"12;!4L'(D$'(D$))"12;!4L'(D$'(D$Y"12;!4L'(D$'(D$\!"12;!4L D"#D'(D$'(D$^#"12;!4L D"#D'(D$'(D$\!"L D"#D'(D$'(D$%%"12;!4L D"#D'(D$'(D$]""12;!4L D"#D'(D$'(D$]""12;!4L D"#D'(D$'(D$ #PQUPX!YZZ#33"44 $&	rC   )rv   r   r   rw   r   r   ru   rJ   N)r   
str | None	r>   r?   r@   rA   rn   rI   r   rB   rq   rr   s   @rD   r   r     s    >
% 
%d& d&rC   r   c                  :   ^  \ rS rSrSrSU 4S jjrSS jrSrU =r$ )r   i"  z7
Abstract scale representing the two octatonic scales.
c                `   > [         TU ]  " S0 UD6  SU l        SU l        U R	                  US9  g )NzAbstract OctatonicTr   r=   rH   rI   rJ   rw   r   r   s      rD   rI   AbstractOctatonicScale.__init__'  s3    $8$(	!%t$rC   c                    SnUS;   a
  UnSU l         O'US;   a  USS USS -   nSU l         O[        SU 35      e[        R                  " UU R                  SS9U l        g)	a  
Given subclass dependent parameters, build and assign the IntervalNetwork.

>>> sc = scale.AbstractDiatonicScale()
>>> sc.buildNetwork('lydian')
>>> [str(p) for p in sc.getRealization('f4', 1, 'f2', 'f6')]
['F2', 'G2', 'A2', 'B2', 'C3', 'D3', 'E3',
 'F3', 'G3', 'A3', 'B3', 'C4', 'D4', 'E4',
 'F4', 'G4', 'A4', 'B4', 'C5', 'D5', 'E5',
 'F5', 'G5', 'A5', 'B5', 'C6', 'D6', 'E6', 'F6']
)r   r   r   r   r   r   r   r   )Nr  r   ry   )ry   r   Nz-cannot create a scale of the following mode: maxAccidentalr  )ru   r   r   r   rw   rv   r  s       rD   r   #AbstractOctatonicScale.buildNetwork/  s{     C?""L DY"12;!4L D #PQUPV!WXX#33LFJF\F\HWY	rC   rv   rw   ru   rJ   r  r  rr   s   @rD   r   r   "  s    %Y YrC   r   c                  :   ^  \ rS rSrSrSSU 4S jjjrS rSrU =r$ )r   iJ  z
A true bidirectional scale that with the augmented
second to a leading tone.

This is the only scale to use the "_alteredDegrees" property.

mode is not used
c                p   > [         TU ]  " S0 UD6  SU l        SU l        SU l        U R                  5         g )NzAbstract Harmonic MinorTr   r=   rH   rI   rJ   rw   r   r   r   s      rD   rI   #AbstractHarmonicMinorScale.__init__S  s6    $8$-	!%#%rC   c                    / SQnSU l         SU l        [        R                  " UU R                  S S9U l        [        R                  R                  [        R                  " S5      S.U R                  S'   g )N)r   r   r   r   r   r   r   ry   r   r  a1)r   r7   r  )ru   r   r   r   rw   rv   r   BIr7   r   r{   )rL   r   s     rD   r   'AbstractHarmonicMinorScale.buildNetworkZ  si    A#33LFJF\F\HLN	 )2255 ))$/#
QrC   rv   r   rw   ru   rJ   r  r   r  returnNoner  rr   s   @rD   r   r   J  s     
 
rC   r   c                  :   ^  \ rS rSrSrSSU 4S jjjrS rSrU =r$ )r   ij  z)
A directional scale.

mode is not used.
c                p   > [         TU ]  " S0 UD6  SU l        SU l        SU l        U R                  5         g )NzAbstract Melodic MinorTr   r=   r'  r   s      rD   rI   "AbstractMelodicMinorScale.__init__p  s6    $8$,	!%#%rC   c                    SU l         SU l        [        R                  " U R                  S S9U l        U R
                  R                  5         g )Nry   r   r  )ru   r   r   r   rw   rv   fillMelodicMinorrR   s    rD   r   &AbstractMelodicMinorScale.buildNetworkw  sB    #33"44 $&	 			""$rC   r-  r  r.  r  rr   s   @rD   r   r   j  s    
 % %rC   r   c                  6   ^  \ rS rSrSrSU 4S jjrS rSrU =r$ )r   i  zo
A scale of any size built with an interval list of any form.
The resulting scale may be non octave repeating.
c                `   > [         TU ]  " S0 UD6  SU l        SU l        U R	                  US9  g )NzAbstract CyclicalFr   r=   r  r   s      rD   rI   AbstractCyclicalScale.__init__  s3    $8$'	!&t$rC   c                    [        U[        [        45      (       d  U/nOUnSU l        [        R
                  " UU R                  S9U l        g)&
Here, mode is the list of intervals.
ry   r   N)r^   r[   tupleru   r   r   rw   rv   )rL   r   modeLists      rD   r   "AbstractCyclicalScale.buildNetwork  sG     $u..vHH#33HFJF\F\^	rC   r$  r  r  rr   s   @rD   r   r     s    
%
^ 
^rC   r   c                  6   ^  \ rS rSrSrSU 4S jjrS rSrU =r$ )r   i  a/  
A scale of any size built with an interval list
that assumes octave completion. An additional
interval to complete the octave will be added
to the provided intervals. This does not guarantee
that the octave will be repeated in one octave,
only the next octave above the last interval will
be provided.
c                l   > [         TU ]  " S0 UD6  SU l        Uc  S/nU R                  US9  SU l        g )NzAbstract Octave Repeatingr   r   Tr=   )rH   rI   rJ   r   rw   r   s      rD   rI   %AbstractOctaveRepeatingScale.__init__  sA    $8$/	<6Dt$ "&rC   c                   [         R                  " U5      (       d  U/n[        R                  " U5      nUR                  nUb  UR                  U5        SU l        [        R                  " UU R                  S9U l
        g)r;  Nry   r   )r0   r   r7   add
complementr]   ru   r   r   rw   rv   )rL   r   intervalSumiComplements       rD   r   )AbstractOctaveRepeatingScale.buildNetwork  so       &&6D ll4(!,,"KK$#33DFJF\F\^	rC   r$  r  r  rr   s   @rD   r   r     s    &^ ^rC   r   c                  6   ^  \ rS rSrSrSU 4S jjrS rSrU =r$ )r   i  
A pseudo raga-scale.
c                p   > [         TU ]  " S0 UD6  SU l        SU l        SU l        U R                  5         g )NzAbstract Rag AsawariTr   r=   r'  rK   s     rD   rI   AbstractRagAsawari.__init__  s6    $8$*	!%#%rC   c                   SU l         SU l        [        R                  SS.SSS.SSS.SSS.SSS.[        R                  S	S.SS
S.SSS.SSS.S
SS.S	SS.SSS.4nS[        R                  S[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SS[        R                  [
        R                  /4S.S[        R                  S[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SSS
[
        R                  /4S.SS
S	[
        R                  /4S.SS	S[
        R                  /4S.SS[        R                  [
        R                  /4S.4n[        R                  " U R                  SS9U l        U R                  R                  X5        g )Nry   r   iddegreer   r  r  r	  r     r  	   r   r7   connectionsm3r   M3
mostCommonr  ru   r   r   LOWHIGHr   r   
DESCENDINGr   r   rw   rv   fillArbitraryrL   nodesedgess      rD   r   AbstractRagAsawari.buildNetwork  sB    2Q'Q'Q'Q' 3Q'Q'Q'Q'Q'Q'  llAy':':;! I//0! I//0! I//0! 	(;(;<!
 mmQ	(<(<=! I001! I001! I001! I001! I001! y';';<!_3
j $33"44 ,.	 			-rC   r-  r/  r0  r  rr   s   @rD   r   r     s    J. J.rC   r   c                  6   ^  \ rS rSrSrSU 4S jjrS rSrU =r$ )r   i  rI  c                p   > [         TU ]  " S0 UD6  SU l        SU l        SU l        U R                  5         g )NzAbstract Rag MarwaTr   r=   r'  rK   s     rD   rI   AbstractRagMarwa.__init__!  s6    $8$(	!%#%rC   c                $   SU l         SU l        [        R                  SS.SSS.SSS.SSS.SSS.SSS.SS	S.[        R                  S
S.SS	S.S	SS.S
SS.SSS.SSS.SSS.4nS[        R                  S[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SS[        R                  [
        R                  /4S.S[        R                  S[
        R                  /4S.SSS	[
        R                  /4S.SS	S
[
        R                  /4S.SS
S[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SS[        R                  [
        R                  /4S.4n[        R                  " U R                  S9U l        U R                  R                  X5        g )Nry   r   rM  r   r  r	  r  r  r  rP  rQ  
      r   rR  A2r   rT  z-M2z-m2d3r   rW  r\  s      rD   r   AbstractRagMarwa.buildNetwork(  sq    2Q'Q'Q'Q'Q'Q' 3Q'Q'Q'Q'a(a($ &llAy/B/BCE I$7$78: I$7$78: I$7$78: I$7$78: I$7$78: 	0C0CDF
 &mmQ	0D0DEG I$8$89; I$8$89; I$8$89; Y%9%9:<  "i&:&:;=  (,,	0D0DEGW.
` $33"44
	 			-rC   r-  r`  r  rr   s   @rD   r   r     s    G. G.rC   r   c                  2   ^  \ rS rSrSrU 4S jrS rSrU =r$ )r   ir  zR
A dynamic, probabilistic mixture of minor pentatonic and a hexatonic blues scale
c                ~   > [         TU ]  " S0 UD6  SU l        SU l        SU l        SU l        U R                  5         g )Nz!Abstract Weighted Hexatonic BluesTFr   r=   )rH   rI   rJ   rw   rz   r   r   rK   s     rD   rI   'AbstractWeightedHexatonicBlues.__init__w  s>    $8$7	!%"rC   c           
        SU l         SU l        [        R                  SS.SSS.SSS.SSS.SSS.SSS.[        R                  S	S.4nS
[        R                  S[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.SSS[
        R                  /4S.S
SS[
        R                  /4S.SS[        R                  [
        R                  /4S.4n[        R                  " U R                  U R                  S9U l        U R                  R                  X5        g )Nry   r   rM  r   r  r	  r  r  r  rT  rR  r   r*  r   )rw   rz   )ru   r   r   rX  rY  r   r+  r   r   rw   rz   rv   r[  r\  s      rD   r   +AbstractWeightedHexatonicBlues.buildNetwork  sn    2Q'Q'Q'Q'Q' 3 llAy||4! ILL)! ILL)! ILL)! ILL)! ILL)! 	5!5
@ $33"44,,/	 			-rC   )rv   rz   r   rw   ru   rJ   r  rr   s   @rD   r   r   r  s    /. /.rC   r   c                  v  ^  \ rS rSrSrSr  S[   S\U 4S jjjr\S 5       rU 4S jr	S r
\S	 5       rS
 rS r\S 5       r\R                  S]S j5       rS rSS.S jr   S^ S_S jjrS r   S^       S`S jjr\" \SS9rSS\R.                  4 SaS jjr\" \SS9rSS\R.                  S4     SbS jjrSS\R.                  4S jr\R.                  S4S jr\R.                  S4S jr\R.                  S4S jrSS S!S"S#S$.S%S&S'S(S)S$.S*S+S,S-S.S$.S/S0S1S2S3S$.S4S5S6S7S8S$.S9S:S;S<S=S$.S>S?S@SASBS$.SC.rSS S!S"S#S$.S%S&S'S(S)S$.S*S+S,SDS.S$.S/S0S1S2S3S$.S4S5SES7S8S$.S9S:S;S<S=S$.S>S?S@SFSBS$.SC.r S\R.                  SGS4SH jr!\"RF                  \$" SISJSK5      S\R.                  SLS4   ScSM jj5       5       r%S\R.                  SLS4   SdSN jjr&\R.                  SLSS4   SeSO jjr'SfSP jr(SQSS\R.                  S4SR jr)   SgSS jr*ShST jr+ShSU jr,SV r-SW r.SS\R.                  4SX jr/SS\R.                  4SY jr0SZr1U =r2$ )ir   i  aj  
A concrete scale is specific scale formation with
a defined pitch collection (a `tonic` Pitch) that
may or may not be bound by specific range. For
example, a specific Major Scale, such as G
Major, from G2 to G4.

This class is can either be used directly or more
commonly as a base class for all concrete scales.

Here we treat a diminished triad as a scale:

>>> myScale = scale.ConcreteScale(pitches=['C4', 'E-4', 'G-4', 'A4'])
>>> myScale.getTonic()
<music21.pitch.Pitch C4>
>>> myScale.nextPitch('G-2')
<music21.pitch.Pitch A2>
>>> [str(p) for p in myScale.getPitches('E-5', 'G-7')]
['E-5', 'G-5', 'A5', 'C6', 'E-6', 'G-6', 'A6', 'C7', 'E-7', 'G-7']


A scale that lasts two octaves and uses quarter tones (D~)

>>> complexScale = scale.ConcreteScale(
...     pitches=['C#3', 'E-3', 'F3', 'G3', 'B3', 'D~4', 'F#4', 'A4', 'C#5']
... )
>>> complexScale.getTonic()
<music21.pitch.Pitch C#3>
>>> complexScale.nextPitch('G3', direction=scale.Direction.DESCENDING)
<music21.pitch.Pitch F3>

>>> [str(p) for p in complexScale.getPitches('C3', 'C7')]
['C#3', 'E-3', 'F3', 'G3', 'B3', 'D~4', 'F#4',
 'A4', 'C#5', 'E-5', 'F5', 'G5', 'B5', 'D~6', 'F#6', 'A6']

Descending form:

>>> [str(p) for p in complexScale.getPitches('C7', 'C5')]
['A6', 'F#6', 'D~6', 'B5', 'G5', 'F5', 'E-5', 'C#5']

Equality
--------
Two ConcreteScales are the same if they satisfy all general Music21Object
equality methods and their Abstract scales, their tonics, and their
boundRanges are the same:



OMIT_FROM_DOCS

>>> scale.ConcreteScale(tonic=4)
Traceback (most recent call last):
ValueError: Tonic must be a Pitch, Note, or str, not <class 'int'>

This is in OMIT
FNc                "  > [         TU ]  " S0 UD6  SU l        S U l        SU l        Uc*  Ub'  [
        R                  " U5      (       a  U(       a  US   nU   Uc  S U l        O[        U[        5      (       a  [        R                  " U5      U l        On[        U[        R                  5      (       a  UR                  U l        O=[        U[        R                  5      (       a  Xl        O[        S[        U5       35      eUb  [
        R                  " U5      (       aq  U(       ai  [        5       U l        U R                  R!                  U5        U R                  U;   a.  UR#                  U R                  5      S-   U R                  l        g g g g g )NConcreteFr   z)Tonic must be a Pitch, Note, or str, not ry   r=   )rH   rI   rJ   	_abstract
boundRanger0   r   tonicr^   r   r6   r_   r5   r   
ValueErrorr
   r   indexru   )rL   rt  rY   rM   rN   s       rD   rI   ConcreteScale.__init__  s@    	$8$	 .2  M'%%g..AJE 	=DJs##U+DJtyy))DJu{{++JHeVWW%%g..*_DNNN227;zzW$-4]]4::-F-J* %  /  rC   c                     U R                   c  gg)a  
Return True if the scale is Concrete, that is, it has a defined Tonic.

>>> sc1 = scale.MajorScale('c')
>>> sc1.isConcrete
True
>>> sc2 = scale.MajorScale()
>>> sc2.isConcrete
False

To be concrete, a Scale must have a
defined tonic. An abstract Scale is not Concrete
FTrt  rR   s    rD   rV   ConcreteScale.isConcrete  s     ::rC   c                  > [         TU ]  U5      (       d  gU R                  (       a  UR                  (       d  U R                  UR                  :H  $ [	        XR
                  5      (       ai  [	        XR
                  5      (       aO  U R                  UR                  :X  a5  U R                  UR                  :X  a  U R                  UR                  :X  a  gg)aQ  
For concrete equality, the stored abstract objects must evaluate as equal,
as well as local attributes.

>>> sc1 = scale.MajorScale('c')
>>> sc2 = scale.MajorScale('c')
>>> sc3 = scale.MinorScale('c')
>>> sc4 = scale.MajorScale('g')
>>> sc5 = scale.MajorScale()  # an abstract scale, as no tonic defined

>>> sc1 == sc2
True
>>> sc1 == sc3
False
>>> sc1 == sc4
False
>>> sc1.abstract == sc4.abstract  # can compare abstract forms
True
>>> sc4 == sc5  # implicit abstract comparison
True
>>> sc5 == sc2  # implicit abstract comparison
True
>>> sc5 == sc3  # implicit abstract comparison
False
FT)rH   __eq__rV   rr  r^   rN   rs  rt  )rL   rc   rN   s     rD   r|  ConcreteScale.__eq__/  s    4 w~e$$e&6&6>>U__445..11"499%//95+;+;;

ekk1rC   c                    [        U 5      S-	  $ )Nr  )rN  rR   s    rD   __hash__ConcreteScale.__hash__Y  s    $x1}rC   c                    U R                   c  SR                  SU R                  /5      $ SR                  U R                   R                  U R                  /5      $ )z
Return or construct the name of this scale

>>> sc = scale.DiatonicScale()  # abstract, as no defined tonic
>>> sc.name
'Abstract diatonic'
 Abstract)rt  joinrJ   rS   rR   s    rD   rS   ConcreteScale.name\  sF     ::88Z34488TZZ__dii899rC   c                    U R                   $ r  rS   rR   s    rD   _reprInternalConcreteScale._reprInternalj  s    yyrC   c                    U R                   $ )zj
Return the tonic.

>>> sc = scale.ConcreteScale(tonic='e-4')
>>> sc.getTonic()
<music21.pitch.Pitch E-4>
ry  rR   s    rD   getTonicConcreteScale.getTonico  s     zzrC   c                    U R                   $ )a  
Return the AbstractScale instance governing this ConcreteScale.

>>> sc1 = scale.MajorScale('d')
>>> sc2 = scale.MajorScale('b-')
>>> sc1 == sc2
False
>>> sc1.abstract == sc2.abstract
True

Abstract scales can also be set afterwards:

>>> scVague = scale.ConcreteScale()
>>> scVague.abstract = scale.AbstractDiatonicScale('major')
>>> scVague.tonic = pitch.Pitch('D')
>>> [p.name for p in scVague.getPitches()]
['D', 'E', 'F#', 'G', 'A', 'B', 'C#', 'D']

>>> scVague.abstract = scale.AbstractOctatonicScale()
>>> [p.name for p in scVague.getPitches()]
['D', 'E', 'F', 'G', 'A-', 'B-', 'C-', 'D-', 'D']

* Changed in v6: changing `.abstract` is now allowed.
)rr  rR   s    rD   abstractConcreteScale.abstracty  s    6 ~~rC   c                h    [        U[        5      (       d  [        S[        U5       35      eXl        g )Nz'abstract must be an AbstractScale, not )r^   r
   	TypeErrorrJ   rr  )rL   newAbstracts     rD   r  r    s-    +}55Ed;FWEXYZZ$rC   c                6    U R                   R                  5       $ )z9
Convenience routine to get this from the AbstractScale.
)rr  r   rR   s    rD   r    ConcreteScale.getDegreeMaxUnique  s     ~~0022rC   inPlacec                  U(       a  U nO[         R                  " U 5      nU R                  c6  [        R                  " S5      Ul        UR                  R                  USS9  OUR                  R                  USS9  U(       d  U$ g)a  
Transpose this Scale by the given interval

Note: It does not make sense to transpose an abstract scale, since
it is merely a collection of intervals.  Thus,
only concrete scales can be transposed.

>>> sc1 = scale.MajorScale('C')
>>> sc2 = sc1.transpose('p5')
>>> sc2
<music21.scale.MajorScale G major>
>>> sc3 = sc2.transpose('p5')
>>> sc3
<music21.scale.MajorScale D major>

>>> sc3.transpose('p5', inPlace=True)
>>> sc3
<music21.scale.MajorScale A major>
NC4Tr  )r   r   rt  r6   r_   	transpose)rL   valuer  ri   s       rD   r  ConcreteScale.transpose  so    ( D==&D::T*DJJJ   5JJ   5K rC   c                  ^^ SSK Jn  U R                  UUUS9mT Vs/ s H  ofR                  PM     snmSUU4S jjnUR	                  5       R
                   H  nUR                  (       a  UR                  n	OUR                  /n	/ n
U	 H  nU" Xj5        M     U
(       d  MJ  [        XR                  5      (       a  [        U
5      Ul        Mv  U
S   Ul        M     gs  snf )z
Given a Stream object containing Pitches, match all pitch names
and or pitch space values and replace the target pitch with
copies of pitches stored in this scale.

This is always applied recursively to all sub-Streams.
r   chordr   r   r   c                  > U R                  SS9nUR                  SS9nUR                  U5        U H  nUR                  T;  a  M  T
TR	                  UR                  5         n[
        R                  " U5      nUR                  Ul        UR                  SS9nS nU H!  n	U	R                  UR                  :X  d  M  U	nM#     Uc  UR                  U5        M  UR                  U5        M     g )NFr  r  )
alterLimit)convertQuarterTonesToMicrotonesgetAllCommonEnharmonicsr]   rS   rv  r   r   ra   )rg   dstpAlttestEnharmonicspEnhpDstpDstNew
pDstNewEnhmatchx	pitchCollpitchCollNamess             rD   tuneOnePitch(ConcreteScale.tune.<locals>.tuneOnePitch  s     44U4CD #::a:HO""4('99N2 !!5!5dii!@A---!%$<<<J
*.#Avv* ! $ =JJw'JJu%' (rC   N)r  list[pitch.Pitch])music21r  
getPitchesrS   recursenotesisChordrY   r6   r^   Chordr<  )rL   	streamObjr   r   r   r  rg   r  eelementPitchesouterDestinationr  r  s              @@rD   tuneConcreteScale.tune  s     	" OOX-5.7 $ &	 +44)Q&&)4	& 	&> ""$**Ayy!""#'' 35#Q1 $  a-- %&6 7AI.q1AG# +C 5s   Cc                0    SSK Jn  UR                  X5      $ )a#  
Return a RomanNumeral object built on the specified scale degree.

>>> sc1 = scale.MajorScale('a-4')
>>> h1 = sc1.romanNumeral(1)
>>> h1.root()
<music21.pitch.Pitch A-4>

>>> h5 = sc1.romanNumeral(5)
>>> h5.root()
<music21.pitch.Pitch E-5>
>>> h5
<music21.roman.RomanNumeral V in A- major>
r   )roman)r  r  RomanNumeral)rL   rO  r  s      rD   romanNumeralConcreteScale.romanNumeral  s     	"!!&//rC   c           	        U R                   c  / $ U R                  c  [        R                  " S5      nOU R                  nU R                   R                  n[        U[        5      (       a  [        R                  " U5      nOUn[        U[        5      (       a  [        R                  " U5      nOUnUb  Ub  Xg:  a  Uc  SnXvpvOU[        R                  :X  a  SnOSnUc  [        R                  nU R                   R                  UUUUUUS9$ )zT
Return a list of Pitch objects, using a
deepcopy of a cached version if available.
r  TF)r   r   r   r   )rr  rt  r6   r_   ru   r^   r   r   rZ  r   r   )	rL   r   r   r   r   r   minPitchObjmaxPitchObjr   s	            rD   r  ConcreteScale.getPitches$  s    >>!I :: {{4(HzzHnn00 h$$++h/K"K h$$++h/K"K#+-%G*5+)...GG!++I ~~,,X-86A6A7@5< - > 	>rC   za
                           Get a default pitch list from this scale.
                           )docc                V    SSK Jn  U R                  UUUS9nUR                  " U40 UD6$ )z
Return a realized chord containing all the
pitches in this scale within a particular
inclusive range defined by two pitches.

All keyword arguments are passed on to the
Chord, permitting specification of
`quarterLength` and similar parameters.
r   r  r  )r  r  r  r  )rL   r   r   r   rM   r  	myPitchess          rD   getChordConcreteScale.getChordf  s:      	" OOX-5.7 $ 9	 {{9111rC   z
        Return a Chord object from this harmony over a default range.
        Use the `getChord()` method if you need greater control over the
        parameters of the chord.
        Tc           
        U R                   c  [        S5      eSnU R                  (       a  U R                  (       ay  U(       dr  U(       dk  [	        U SS5      (       aY  U R                  R
                  nU R                  U R                  UUUU4nU[        ;   a  [        R                  " [        U   5      $ U R                   R                  U R                  U R                   R                  UUUUUS9nU(       a  UR
                  [        U'   U$ )a  
Given a scale degree, return a deepcopy of the appropriate pitch.

>>> sc = scale.MajorScale('e-')
>>> sc.pitchFromDegree(2)
<music21.pitch.Pitch F4>
>>> sc.pitchFromDegree(7)
<music21.pitch.Pitch D5>

OMIT_FROM_DOCS

Test deepcopy

>>> d = sc.pitchFromDegree(7)
>>> d.accidental = pitch.Accidental('sharp')
>>> d
<music21.pitch.Pitch D#5>
>>> sc.pitchFromDegree(7)
<music21.pitch.Pitch D5>
N6Abstract scale underpinning this scale is not defined.rJ   )r   r   r   r   r   r   r   )rr  r   usePitchDegreeCachert  r`   rm   rN   rJ   r:   r6   r_   r   ru   )	rL   rO  r   r   r   r   cacheKeytonicCacheKeyri   s	            rD   pitchFromDegreeConcreteScale.pitchFromDegree  s    6 >>! !YZZ.2$$ gdFD6Q6Q JJ55M		H ,,{{#4X#>??~~44::^^//#' 5 ) *.*=*=h'rC   c           	     ~    U R                   R                  U R                  U R                   R                  UUUUS9nU$ )a  
Given one or more scale degrees, return a list
of all matches over the entire range.

>>> sc = scale.MajorScale('e-')
>>> sc.pitchesFromScaleDegrees([3, 7])
[<music21.pitch.Pitch G4>, <music21.pitch.Pitch D5>]
>>> [str(p) for p in sc.pitchesFromScaleDegrees([3, 7], 'c2', 'c6')]
['D2', 'G2', 'D3', 'G3', 'D4', 'G4', 'D5', 'G5']

>>> sc = scale.HarmonicMinorScale('a')
>>> [str(p) for p in sc.pitchesFromScaleDegrees([3, 7], 'c2', 'c6')]
['C2', 'G#2', 'C3', 'G#3', 'C4', 'G#4', 'C5', 'G#5', 'C6']
)r   r   r   r   r   r   )rr  r   rt  ru   )rL   degreeTargetsr   r   r   ri   s         rD   pitchesFromScaleDegrees%ConcreteScale.pitchesFromScaleDegrees  sD    * ~~22::>>--+ 3  rC   c                    U R                  XUS9nU R                  X#US9nUc  [        SU 35      eUc  [        SU 35      e[        R                  " XV5      $ )z
Given two degrees, provide the interval as an interval.Interval object.

>>> sc = scale.MajorScale('e-')
>>> sc.intervalBetweenDegrees(3, 7)
<music21.interval.Interval P5>
)r   r   z%cannot get a pitch for scale degree: )r  r   r7   r   )rL   degreeStart	degreeEndr   r   pStartpEnds          rD   intervalBetweenDegrees$ConcreteScale.intervalBetweenDegrees  s{     %%k4A & C##I2? $ A> #H!QRR< #H!OPP  ..rC   rS   c                |    U R                   R                  U R                  U R                   R                  UUUS9nU$ )aX  
For a given pitch, return the appropriate scale degree.
If no scale degree is available, None is returned.

Note: by default it will use a find algorithm that is based on the note's
`.name` not on `.pitchClass` because this is used so commonly by tonal functions.
So if it's important that D# and E- are the same, set the
comparisonAttribute to `pitchClass`

>>> sc = scale.MajorScale('e-')
>>> sc.getScaleDegreeFromPitch('e-2')
1
>>> sc.getScaleDegreeFromPitch('d')
7
>>> sc.getScaleDegreeFromPitch('d#', comparisonAttribute='name') is None
True
>>> sc.getScaleDegreeFromPitch('d#', comparisonAttribute='pitchClass')
1
>>> sc.getScaleDegreeFromPitch('e') is None
True
>>> sc.getScaleDegreeFromPitch('e', comparisonAttribute='step')
1

>>> sc = scale.HarmonicMinorScale('a')
>>> sc.getScaleDegreeFromPitch('c')
3
>>> sc.getScaleDegreeFromPitch('g#')
7
>>> sc.getScaleDegreeFromPitch('g') is None
True

>>> cMaj = key.Key('C')
>>> cMaj.getScaleDegreeFromPitch(pitch.Pitch('E-'),
...                              direction=scale.Direction.ASCENDING,
...                              comparisonAttribute='step')
3
)r   r   r   rd   r   )rr  r   rt  ru   )rL   r   r   rd   ri   s        rD   getScaleDegreeFromPitch%ConcreteScale.getScaleDegreeFromPitch  sB    R ~~334::=A^^=W=W@KH[>G	 4 I
 rC   c                   U R                  XU5      nUb  US4$ U R                  UUSS9nUc  [        SU SU S3-   5      eU R                  U/5      nU(       d  gUS   nUR                  c  SnOUR                  R                  nUR                  c  Sn	OUR                  R                  n	X-
  n
U
S:X  a  US4$ [
        R                  " U
5      nX[4$ )	a]  
Given a scale (or :class:`~music21.key.Key` object) and a pitch, return a two-element
tuple of the degree of the scale and an accidental (or None) needed to get this
pitch.

>>> cMaj = key.Key('C')
>>> cMaj.getScaleDegreeAndAccidentalFromPitch(pitch.Pitch('E'))
(3, None)
>>> cMaj.getScaleDegreeAndAccidentalFromPitch(pitch.Pitch('E-'))
(3, <music21.pitch.Accidental flat>)


The Direction of a melodic minor scale is significant

>>> aMin = scale.MelodicMinorScale('a')
>>> aMin.getScaleDegreeAndAccidentalFromPitch(pitch.Pitch('G'),
...                                           direction=scale.Direction.DESCENDING)
(7, None)
>>> aMin.getScaleDegreeAndAccidentalFromPitch(pitch.Pitch('G'),
...                                           direction=scale.Direction.ASCENDING)
(7, <music21.pitch.Accidental flat>)
>>> aMin.getScaleDegreeAndAccidentalFromPitch(pitch.Pitch('G-'),
...                                           direction=scale.Direction.ASCENDING)
(7, <music21.pitch.Accidental double-flat>)

Returns (None, None) if for some reason this scale does not have this step
(a whole-tone scale, for instance)
Nsteprd   zICannot get any scale degree from getScaleDegreeFromPitch for pitchTarget z, direction z, comparisonAttribute='step'NNr   )r  r   r  
accidentalalterr6   
Accidental)rL   r   r   rd   	scaleStepscaleStepNormalpitchesFound
foundPitch
foundAlter
pitchAlter	alterDiffalterAccidentals               rD   $getScaleDegreeAndAccidentalFromPitch2ConcreteScale.getScaleDegreeAndAccidentalFromPitch.  s   @ 00I\]	 t$$"::;;DOU ; WO &$_$\)<XYZ[ [  778IJL#)!_
$$,
'2288
%%-
(3399
"/IA~'.."'"2"29"='99rC   defdedodidis)r   r   ry   r  rafrarerirismefmemimismishfeffefafifissefsesolsisisleflelalilisteftetitistish)ry   r  r	  r  r   r  r  mysotyr  c                r   [        U[        5      (       a  [        R                  " U5      nU R	                  X5      u  pVUS:X  a  U R
                  nO!US:X  a  U R                  nO[        SU 35      eUS:  a  [        S5      eUc  [        S5      eUSL a  Uc  Xu   S   $ Xu   UR                     $ Xu   S   $ )	a   
Returns the chromatic solfeg (or diatonic if chromatic is False)
for a given pitch in a given scale.

The `variant` method lets one specify either the default `music21`
or `humdrum` solfeg representation
for altered notes.

>>> eflatMaj = key.Key('E-')
>>> eflatMaj.solfeg(pitch.Pitch('G'))
'mi'
>>> eflatMaj.solfeg('A')
'fi'
>>> eflatMaj.solfeg('A', chromatic=False)
'fa'
>>> eflatMaj.solfeg(pitch.Pitch('G#'), variant='music21')  # default
'mis'
>>> eflatMaj.solfeg(pitch.Pitch('G#'), variant='humdrum')
'my'
r  humdrumzUnknown solfeg variant r  z)Cannot call solfeg on non-7-degree scalesz#Unknown scale degree for this pitchTr   )	r^   r   r6   r_   r  _solfegSyllables_humdrumSolfegSyllablesr   r  )rL   r   r   variant	chromaticscaleDegr  syllableDicts           rD   solfegConcreteScale.solfeg  s    2 k3''++k2K!%!J!J;!bi00L	!77L #:7)!DEEa< !LMM !FGG!#-a00#-j.>.>??)!,,rC   v9v10zuse nextPitch insteadry   c                &    U R                  UUUUS9$ )at  
See :meth:`~music21.scale.ConcreteScale.nextPitch`.  This function
is a deprecated alias for that method.

This routine was named and created before music21 aspired to have
full subclass substitution.  Thus, is shadows the `.next()` function of
Music21Object without performing similar functionality.

The routine is formally deprecated in v9 and will be removed in v10.
)r   r   r   r   )r   )rL   r   r   r   r   s        rD   nextConcreteScale.next  s&    & ~~##	  
 	
rC   c           	     *   Uc  U R                   $ U R                  c  [        S5      e[        U[        5      (       aF  US:w  a5  US:  a  Un[
        R                  nO+[        U5      n[
        R                  nO[        S5      eSnUnUSL aI  U[
        R                  :X  a  [
        R                  nO$U[
        R                  :X  a  [
        R                  nU R                  R                  U R                   U R                  R                  UUX5-  US9nU$ )a  
Get the next pitch above (or below if direction is Direction.DESCENDING)
a `pitchOrigin` or None. If the `pitchOrigin` is None, the tonic pitch is
returned. This is useful when starting a chain of iterative calls.

The `direction` attribute may be either ascending or descending.
Default is `ascending`. Optionally, positive or negative integers
may be provided as directional stepSize scalars.

An optional `stepSize` argument can be used to set the number
of scale steps that are stepped through.  Thus, .nextPitch(stepSize=2)
will give not the next pitch in the scale, but the next after this one.

The `getNeighbor` will return a pitch from the scale
if `pitchOrigin` is not in the scale. This value can be
True, Direction.ASCENDING, or Direction.DESCENDING.

>>> sc = scale.MajorScale('e-')
>>> print(sc.nextPitch('e-5'))
F5
>>> print(sc.nextPitch('e-5', stepSize=2))
G5
>>> print(sc.nextPitch('e-6', stepSize=3))
A-6

This uses the getNeighbor attribute to
find the next note above f#5 in the E-flat
major scale:

>>> sc.nextPitch('f#5')
<music21.pitch.Pitch G5>

>>> sc = scale.HarmonicMinorScale('g')
>>> sc.nextPitch('g4', scale.Direction.DESCENDING)
<music21.pitch.Pitch F#4>
>>> sc.nextPitch('F#4', scale.Direction.DESCENDING)
<music21.pitch.Pitch E-4>
>>> sc.nextPitch('E-4', scale.Direction.DESCENDING)
<music21.pitch.Pitch D4>
>>> sc.nextPitch('E-4', scale.Direction.ASCENDING, 1)
<music21.pitch.Pitch F#4>
>>> sc.nextPitch('E-4', scale.Direction.ASCENDING, 2)
<music21.pitch.Pitch G4>
r  r   zdirection cannot be zerory   T)r   r   r   r   r   r   )rt  rr  r   r^   intr   r   absrZ  r   ru   )rL   r   r   r   r   
stepScalardirectionEnumri   s           rD   r   ConcreteScale.nextPitch  s   f ::>>! !YZZ
 i%%A~q=!*J$-$7$7M!$YJ$-$8$8M$%?@@J%M $	 3 33'22)"6"66'11~~''::^^//##*# ( 
 rC   c                6   [        U[        5      (       a  [        R                  " U5      nO>[	        US5      (       a  UR                  nO [        U[        R                  5      (       d  gU R                  UUUUS9nUc  g[        Xv5      [        X5      :X  a  gg)z
Given another pitch, as well as an origin and a direction,
determine if this other pitch is in the next in the scale.

>>> sc1 = scale.MajorScale('g')
>>> sc1.isNext('d4', 'c4', scale.Direction.ASCENDING)
True
r6   F)r   r   r   NT)r^   r   r6   r_   rZ   r   r`   )rL   rc   r   r   r   r   rd   nPitchs           rD   isNextConcreteScale.isNexty  s     eS!!KK&EUG$$KKEE5;;//*3)1,7   9 >F0567rC   c                    U R                  UUS9nU R                  R                  R                  U R                  U R                  R
                  UUS9u  pEUUS.nU$ )a  
Given another object of the forms that `extractPitchList` can take,
(e.g., a :class:`~music21.stream.Stream`, a :class:`~music21.scale.ConcreteScale`,
a list of :class:`~music21.pitch.Pitch` objects),
return a named dictionary of pitch lists with keys 'matched' and 'notMatched'.

>>> sc1 = scale.MajorScale('g')
>>> sc2 = scale.MajorScale('d')
>>> sc3 = scale.MajorScale('a')
>>> sc4 = scale.MajorScale('e')

>>> from pprint import pprint as pp
>>> pp(sc1.match(sc2))
{'matched': [<music21.pitch.Pitch D4>, <music21.pitch.Pitch E4>,
             <music21.pitch.Pitch F#4>, <music21.pitch.Pitch G4>,
             <music21.pitch.Pitch A4>, <music21.pitch.Pitch B4>],
'notMatched': [<music21.pitch.Pitch C#5>]}

>>> pp(sc2.match(sc3))
{'matched': [<music21.pitch.Pitch A4>, <music21.pitch.Pitch B4>,
             <music21.pitch.Pitch C#5>, <music21.pitch.Pitch D5>,
             <music21.pitch.Pitch E5>, <music21.pitch.Pitch F#5>],
'notMatched': [<music21.pitch.Pitch G#5>]}

>>> pp(sc1.match(sc4))
{'matched': [<music21.pitch.Pitch E4>, <music21.pitch.Pitch F#4>,
             <music21.pitch.Pitch A4>, <music21.pitch.Pitch B4>],
 'notMatched': [<music21.pitch.Pitch G#4>,
                <music21.pitch.Pitch C#5>,
                <music21.pitch.Pitch D#5>]}
r  )r   r   r   rd   )matched
notMatched)rk   rr  rv   r  rt  ru   )rL   rc   rd   otherPitchesr3  r4  ri   s          rD   r  ConcreteScale.match  st    B ,,UAT - V #nn1177::>>--$ 3	 8 5 $
 rC   r   c                    U R                  UUS9nU R                  R                  R                  U R                  U R                  R
                  UUUUUUS9nU$ )a  
Given another object of the forms that `extractPitches` takes
(e.g., a :class:`~music21.stream.Stream`,
a :class:`~music21.scale.ConcreteScale`,
a list of :class:`~music21.pitch.Pitch` objects),
return a list of pitches that are found in this Scale but are not
found in the provided object.

>>> sc1 = scale.MajorScale('g4')
>>> [str(p) for p in sc1.findMissing(['d'])]
['G4', 'A4', 'B4', 'C5', 'E5', 'F#5', 'G5']
r  )r   r   r   rd   r   r   r   r   )rk   rr  rv   findMissingrt  ru   )	rL   rc   rd   r   r   r   r   r5  ri   s	            rD   r8  ConcreteScale.findMissing  sk    ( ,,UAT - V~~""..::>>--$ 3) / 	
 rC   c                \   U R                  UUUS9nU R                  R                  R                  UUUU R                  R                  S9n/ nU HX  u  pU R                  U	S9n
U
R                  c%  [        R                  " U R                  5      U
l        UR                  X45        MZ     U$ )a  
Return a list of closest-matching :class:`~music21.scale.ConcreteScale` objects
based on this :class:`~music21.scale.AbstractScale`,
provided as a :class:`~music21.stream.Stream`, a :class:`~music21.scale.ConcreteScale`,
or a list of :class:`~music21.pitch.Pitch` objects.
Returned integer values represent the number of matches.

If you are working with Diatonic Scales, you will probably
want to change the `comparisonAttribute` to `name`.

>>> sc1 = scale.MajorScale()
>>> sc1.deriveRanked(['C', 'E', 'B'])
[(3, <music21.scale.MajorScale G major>),
 (3, <music21.scale.MajorScale C major>),
 (2, <music21.scale.MajorScale B major>),
 (2, <music21.scale.MajorScale A major>)]

With the default of comparing by pitchClass, D- is fine for B major
because C# is in the B major scale.

>>> sc1.deriveRanked(['D-', 'E', 'B'])
[(3, <music21.scale.MajorScale B major>),
 (3, <music21.scale.MajorScale A major>),
 (3, <music21.scale.MajorScale E major>),
 (3, <music21.scale.MajorScale D major>)]

Comparing based on enharmonic-sensitive spelling, has fewer hits
for all of these scales:

>>> sc1.deriveRanked(['D-', 'E', 'B'], comparisonAttribute='name')
[(2, <music21.scale.MajorScale B major>),
 (2, <music21.scale.MajorScale A major>),
 (2, <music21.scale.MajorScale G major>),
 (2, <music21.scale.MajorScale E major>)]

Notice that we check how many of the pitches are in the scale
and do not de-duplicate pitches.

>>> sc1.deriveRanked(['C', 'E', 'E', 'E', 'B'])
[(5, <music21.scale.MajorScale G major>),
 (5, <music21.scale.MajorScale C major>),
 (4, <music21.scale.MajorScale B major>),
 (4, <music21.scale.MajorScale A major>)]

If removeDuplicates is given, the E's will get less weight:

>>> sc1.deriveRanked(['C', 'E', 'E', 'E', 'B'], removeDuplicates=True)
[(3, <music21.scale.MajorScale G major>),
 (3, <music21.scale.MajorScale C major>),
 (2, <music21.scale.MajorScale B major>),
 (2, <music21.scale.MajorScale A major>)]

>>> sc1.deriveRanked(['C#', 'E', 'G#'])
[(3, <music21.scale.MajorScale B major>),
 (3, <music21.scale.MajorScale A major>),
 (3, <music21.scale.MajorScale E major>),
 (3, <music21.scale.MajorScale C- major>)]

A Concrete Scale created from pitches still has similar
characteristics to the original.

Here we create a scale like a Harmonic minor but with flat 2 and sharp 4.

>>> e = scale.ConcreteScale(pitches=['A4', 'B-4', 'C5', 'D#5', 'E5', 'F5', 'G#5', 'A5'])

Notice the G# is allowed to be chosen even though we are specifically looking for
scales with a G natural in them.  Once no scale matched all three pitches,
which scale that matches two pitches is arbitrary.

>>> bestScales = e.deriveRanked(['C', 'E', 'G'], resultsReturned=6)
>>> bestScales
[(3, <music21.scale.ConcreteScale E Concrete>),
 (3, <music21.scale.ConcreteScale D- Concrete>),
 (3, <music21.scale.ConcreteScale C# Concrete>),
 (2, <music21.scale.ConcreteScale B Concrete>),
 (2, <music21.scale.ConcreteScale A Concrete>),
 (2, <music21.scale.ConcreteScale G# Concrete>)]


>>> eConcrete = bestScales[0][1]
>>> ' '.join([str(p) for p in eConcrete.pitches])
'E4 F4 G4 A#4 B4 C5 D#5 E5'
)rd   re   r   resultsReturnedrd   r   ry  )
rk   rr  rv   findr{   rN   r  r   r   r]   )rL   rc   r<  rd   re   r5  pairsri   weightrg   scs              rD   deriveRankedConcreteScale.deriveRanked  s    x ,,UAT>N - P ##((\9H=P8<8V8V ) X IFa(B{{""mmDNN;KK%  rC   c                    U R                  UUS9nU R                  R                  R                  UUS9nU R	                  US   S   S9nUR
                  c%  [        R                  " U R                  5      Ul        U$ )a>  
Return the closest-matching :class:`~music21.scale.ConcreteScale`
based on the pitch collection provided as a
:class:`~music21.stream.Stream`, a :class:`~music21.scale.ConcreteScale`,
or a list of :class:`~music21.pitch.Pitch` objects.

How the "closest-matching" scale is defined still needs to be
refined and has changed in the past and will probably change in the future.

>>> sc1 = scale.MajorScale()
>>> sc1.derive(['C#', 'E', 'G#'])
<music21.scale.MajorScale B major>

>>> sc1.derive(['E-', 'B-', 'D'], comparisonAttribute='name')
<music21.scale.MajorScale B- major>
r  )r   rd   r   ry   ry  )rk   rr  rv   r=  rN   r  r   r   )rL   rc   rd   r5  r>  newScales         rD   deriveConcreteScale.derive_	  s    " ,,UAT - V ##((\=P ) R >>a>4$ $dnn =HrC   c                |   U R                  UUS9nU R                  R                  R                  USUU R                  R                  S9n/ n[        U5      nU H^  u  pxXv:X  d  M  U R                  US9n	U	R                  c%  [        R                  " U R                  5      U	l        UR                  U	5        M`     U$ )a|  
Return a list of all Scales of the same class as `self`
where all the pitches in `other` are contained.

Similar to "deriveRanked" but only returns those scales
no matter how many which contain all the pitches.

Just returns a list in order.

If you are working with Diatonic Scales, you will
probably want to change the `comparisonAttribute` to `name`.

>>> sc1 = scale.MajorScale()
>>> sc1.deriveAll(['C', 'E', 'B'])
[<music21.scale.MajorScale G major>, <music21.scale.MajorScale C major>]

>>> [sc.name for sc in sc1.deriveAll(['D-', 'E', 'B'])]
['B major', 'A major', 'E major', 'D major', 'C- major']

>>> sc1.deriveAll(['D-', 'E', 'B'], comparisonAttribute='name')
[]

Find all instances of this pentatonic scale in major scales:

>>> scList = sc1.deriveAll(['C#', 'D#', 'F#', 'G#', 'A#'], comparisonAttribute='name')
>>> [sc.name for sc in scList]
['B major', 'F# major', 'C# major']
r  Nr;  ry  )rk   rr  rv   r=  r{   lenrN   r  r   r   r]   )
rL   rc   rd   r5  r>  ri   
numPitchesr?  rg   r@  s
             rD   	deriveAllConcreteScale.deriveAll|	  s    B ,,UAT - V ##((\9==P8<8V8V ) X &
IF#^^!^,;;&"&--"?BKB  rC   c                    U R                   R                  UUS9nUc  [        S5      eU R                  US9nUR                  c%  [
        R                  " U R                   5      Ul        U$ )a4  
Given a scale degree and a pitch, return a
new :class:`~music21.scale.ConcreteScale` that satisfies
that condition.

Find a major scale with C as the 7th degree:

>>> sc1 = scale.MajorScale()
>>> sc1.deriveByDegree(7, 'c')
<music21.scale.MajorScale D- major>

TODO: Does not yet work for directional scales
)r   r   zcannot derive new tonicry  )rr  r   r   rN   r  r   r   )rL   rO  pitchRefrg   rD  s        rD   deriveByDegreeConcreteScale.deriveByDegree	  sl     NN++# , 
 9 !:;;>>>*$ $dnn =HrC   c                Z    U R                   R                  5       n[        U 5      Ul        U$ )z
Return a configured :class:`~music21.scala.ScalaData`
Object for this scale.  It can be used to find interval
distances in cents between degrees.
)r  r   r   r   )rL   r   s     rD   r   ConcreteScale.getScalaData	  s&     ]]'')d	rC   c                    Ub8  [         R                  " U5      u  pEUS:X  a  U R                  R                  XUS9$ [        R                  XUS9$ )zG
Write the scale in a format.
Here, prepare scala format if requested.
r   )r   r   r   r   )r0   r   r  r   r	   )rL   r   r   r   r   r   s         rD   r   ConcreteScale.write	  sQ    
 ?%+%6%6s%;"JW$}}**sY*OO{{4R{00rC   c                    Ub9  [         R                  " U5      u  pEUS:X  a  U R                  R                  XUS9  g[        R                  XUS9  g)zF
Show the scale in a format. Here, prepare scala format
if requested.
Nr   )r   r   r   r   )r0   r   r  r   r	   )rL   r   r   r   r   r   s         rD   r   ConcreteScale.show	  sN    
 ?%+%6%6s%;"JW$""sy"I

4c
*rC   )rr  rs  rt  rJ   r  )rt  $str | pitch.Pitch | note.Note | NonerY   zlist[pitch.Pitch | str] | None)r  r
   )NNNr`  )r   str | pitch.Pitch | Noner   rW  r   zDirection | Noner/  r  )r/  z'music21.chord.Chord')rO  r)  r   r   r   bool)r   z/'music21.scale.intervalNetwork.Direction' | intr   z0'music21.scale.intervalNetwork.Direction' | bool)r   zDirection | intr   r   r   r  )r  r   F)r   )3r>   r?   r@   rA   rn   r  rI   ro   rV   r|  r  rS   r  r  r  setterr   r  r  r  r  rY   r   r   r  r  r  r  r  r  r  r  r  r!  tno_type_checkr1   r&  r   r0  r  r8  rA  rE  rJ  rN  r   r   r   rB   rq   rr   s   @rD   r   r     sg   7p   :>7;+K6+K4+K +KZ  &(T : :
  8 __% %3 +0  J K2 
K2Z0( *.)-$(	9>&9> '9> "	9>
 
9>z z G %%	2 
24 XE #,#6#6"&99
 !9  9H ))D  ))/4 +4*=*=4:.d 8A7J7JAGB:L !& $ $ $ %	 !& $ $ $ %	 !& $ $ % &	 !& $ $ $ %	 !& $ % $ %	 !& $ $ $ %	 !& $ $ % &	I*d 	 	 	 	 	 	 	K+\  ",, 	.-b __e45 CLCVCVFJ
 A

 D
 6 
4 #,#6#6&*Z !Z
 $Z~ '0&9&9-1#)! $!
 +!L/f )5!!'11#' H &')5&+	kZ:1fH	 1D1D 	1 1D1D 
+ 
+rC   r   c                  b   ^  \ rS rSrSrSrSSU 4S jjjrS rS rS r	S r
S	 rS
 rS rSrU =r$ )r   i	  zt
A concrete diatonic scale. Each DiatonicScale
has one instance of a :class:`~music21.scale.AbstractDiatonicScale`.
Tc                X   > [         TU ]  " SSU0UD6  [        S0 UD6U l        SU l        g )Nrt  diatonicr=   )rH   rI   r   rr  rJ   rL   rt  rM   rN   s      rD   rI   DiatonicScale.__init__ 
  s.    1u110E0Q0Q	rC   c                L    U R                  U R                  R                  5      $ )a  
Return the tonic of the diatonic scale.

>>> sc = scale.MajorScale('e-')
>>> sc.getTonic()
<music21.pitch.Pitch E-4>
>>> sc = scale.MajorScale('F#')
>>> sc.getTonic()
<music21.pitch.Pitch F#4>

If no tonic has been defined, it will return an Exception.
(same is true for `getDominant`, `getLeadingTone`, etc.)

>>> sc = scale.DiatonicScale()
>>> sc.getTonic()
Traceback (most recent call last):
music21.scale.intervalNetwork.IntervalNetworkException: pitchReference cannot be None
)r  rr  ru   rR   s    rD   r  DiatonicScale.getTonic
  s    ( ##DNN$>$>??rC   c                L    U R                  U R                  R                  5      $ )z
Return the dominant.

>>> sc = scale.MajorScale('e-')
>>> sc.getDominant()
<music21.pitch.Pitch B-4>
>>> sc = scale.MajorScale('F#')
>>> sc.getDominant()
<music21.pitch.Pitch C#5>
)r  rr  r   rR   s    rD   getDominantDiatonicScale.getDominant
  s     ##DNN$A$ABBrC   c                    U R                  S5      nUR                  U R                  R                  -
  nUS:w  a-  SU-
  n[        R                  " UR
                  U-   5      Ul        U$ )z
Return the leading tone.

>>> sc = scale.MinorScale('c')
>>> sc.getLeadingTone()
<music21.pitch.Pitch B4>

Note that the leading tone isn't necessarily
the same as the 7th scale degree in minor:

>>> sc.pitchFromDegree(7)
<music21.pitch.Pitch B-4>
r  rf  )r  midirt  r6   r  r  r  )rL   seventhDegreedistanceInSemitonesalterationInSemitoness       rD   getLeadingToneDiatonicScale.getLeadingTone(
  sk     ,,Q/+004::??B"$$&)<$<!','7'7##&;;(M$ rC   c                ,    [        U R                  5      $ )a  
Return a parallel minor scale based on this
concrete scale.

>>> sc1 = scale.MajorScale(pitch.Pitch('a'))
>>> [str(p) for p in sc1.pitches]
['A4', 'B4', 'C#5', 'D5', 'E5', 'F#5', 'G#5', 'A5']
>>> sc2 = sc1.getParallelMinor()
>>> [str(p) for p in sc2.pitches]
['A4', 'B4', 'C5', 'D5', 'E5', 'F5', 'G5', 'A5']

Running getParallelMinor() again doesn't change anything

>>> sc3 = sc2.getParallelMinor()
>>> [str(p) for p in sc3.pitches]
['A4', 'B4', 'C5', 'D5', 'E5', 'F5', 'G5', 'A5']
)r   rt  rR   s    rD   getParallelMinorDiatonicScale.getParallelMinorA
  s    $ $**%%rC   c                ,    [        U R                  5      $ )a!  
Return a concrete relative major scale

>>> sc1 = scale.MinorScale(pitch.Pitch('g'))
>>> [str(p) for p in sc1.pitches]
['G4', 'A4', 'B-4', 'C5', 'D5', 'E-5', 'F5', 'G5']

>>> sc2 = sc1.getParallelMajor()
>>> [str(p) for p in sc2.pitches]
['G4', 'A4', 'B4', 'C5', 'D5', 'E5', 'F#5', 'G5']
)r   rt  rR   s    rD   getParallelMajorDiatonicScale.getParallelMajorU
  s     $**%%rC   c                ^    [        U R                  U R                  R                  5      5      $ )a9  
Return a relative minor scale based on this concrete scale.

>>> sc1 = scale.MajorScale(pitch.Pitch('a'))
>>> [str(p) for p in sc1.pitches]
['A4', 'B4', 'C#5', 'D5', 'E5', 'F#5', 'G#5', 'A5']
>>> sc2 = sc1.getRelativeMinor()
>>> [str(p) for p in sc2.pitches]
['F#5', 'G#5', 'A5', 'B5', 'C#6', 'D6', 'E6', 'F#6']
)r   r  r  r   rR   s    rD   getRelativeMinorDiatonicScale.getRelativeMinorc
  s$     $..t}}/P/PQRRrC   c                ^    [        U R                  U R                  R                  5      5      $ )a{  
Return a concrete relative major scale

>>> sc1 = scale.MinorScale(pitch.Pitch('g'))
>>> [str(p) for p in sc1.pitches]
['G4', 'A4', 'B-4', 'C5', 'D5', 'E-5', 'F5', 'G5']

>>> sc2 = sc1.getRelativeMajor()
>>> [str(p) for p in sc2.pitches]
['B-4', 'C5', 'D5', 'E-5', 'F5', 'G5', 'A5', 'B-5']

Though it's unlikely you would want to do it,
`getRelativeMajor` works on other diatonic scales than
just Major and Minor.

>>> sc2 = scale.DorianScale('d')
>>> [str(p) for p in sc2.pitches]
['D4', 'E4', 'F4', 'G4', 'A4', 'B4', 'C5', 'D5']

>>> [str(p) for p in sc2.getRelativeMajor().pitches]
['C5', 'D5', 'E5', 'F5', 'G5', 'A5', 'B5', 'C6']
)r   r  r  r   rR   s    rD   getRelativeMajorDiatonicScale.getRelativeMajorp
  s$    . $..t}}/P/PQRRrC   rr  rJ   r  )rt  rV  )r>   r?   r@   rA   rn   r  rI   r  rd  rk  rn  rq  rt  rw  rB   rq   rr   s   @rD   r   r   	  sG      
@,C2&(&SS SrC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i
  z`
A Major Scale

>>> sc = scale.MajorScale(pitch.Pitch('d'))
>>> sc.pitchFromDegree(7).name
'C#'
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r   r=   rH   rI   rJ   rr  r   r_  s      rD   rI   MajorScale.__init__
  s5    1u11	##DII.rC   rQ   r  r>   r?   r@   rA   rn   rI   rB   rq   rr   s   @rD   r   r   
  s    / /rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i
  z
A natural minor scale, or the Aeolian mode.

>>> sc = scale.MinorScale(pitch.Pitch('g'))
>>> [str(p) for p in sc.pitches]
['G4', 'A4', 'B-4', 'C5', 'D5', 'E-5', 'F5', 'G5']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   MinorScale.__init__
  s5    1u11	##DII.rC   rQ   r  r~  rr   s   @rD   r   r   
      / /rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i
  z
A scale built on the Dorian (D-D white-key) mode.

>>> sc = scale.DorianScale(pitch.Pitch('d'))
>>> [str(p) for p in sc.pitches]
['D4', 'E4', 'F4', 'G4', 'A4', 'B4', 'C5', 'D5']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   DorianScale.__init__
  5    1u11	##DII.rC   rQ   r  r~  rr   s   @rD   r   r   
  r  rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i
  z
A Phrygian scale (E-E white key)

>>> sc = scale.PhrygianScale(pitch.Pitch('e'))
>>> [str(p) for p in sc.pitches]
['E4', 'F4', 'G4', 'A4', 'B4', 'C5', 'D5', 'E5']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   PhrygianScale.__init__
  s5    1u11	##DII.rC   rQ   r  r~  rr   s   @rD   r   r   
  r  rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i
  a  
A Lydian scale (that is, the F-F white-key scale; does not have the
probability of B- emerging as in a historical Lydian collection).

>>> sc = scale.LydianScale(pitch.Pitch('f'))
>>> [str(p) for p in sc.pitches]
['F4', 'G4', 'A4', 'B4', 'C5', 'D5', 'E5', 'F5']

>>> sc = scale.LydianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['C4', 'D4', 'E4', 'F#4', 'G4', 'A4', 'B4', 'C5']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   LydianScale.__init__
  r  rC   rQ   r  r~  rr   s   @rD   r   r   
  s    / /rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i
  a  
A mixolydian scale

>>> sc = scale.MixolydianScale(pitch.Pitch('g'))
>>> [str(p) for p in sc.pitches]
['G4', 'A4', 'B4', 'C5', 'D5', 'E5', 'F5', 'G5']

>>> sc = scale.MixolydianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['C4', 'D4', 'E4', 'F4', 'G4', 'A4', 'B-4', 'C5']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r
  r=   r|  r_  s      rD   rI   MixolydianScale.__init__
  5    1u11 	##DII.rC   rQ   r  r~  rr   s   @rD   r   r   
      
/ /rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i
  aV  
A hypodorian scale: a dorian scale where the given pitch is scale degree 4.

>>> sc = scale.HypodorianScale(pitch.Pitch('d'))
>>> [str(p) for p in sc.pitches]
['A3', 'B3', 'C4', 'D4', 'E4', 'F4', 'G4', 'A4']
>>> sc = scale.HypodorianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['G3', 'A3', 'B-3', 'C4', 'D4', 'E-4', 'F4', 'G4']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   HypodorianScale.__init__
  r  rC   rQ   r  r~  rr   s   @rD   r   r   
  s    	/ /rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i  av  
A hypophrygian scale

>>> sc = scale.HypophrygianScale(pitch.Pitch('e'))
>>> sc.abstract.octaveDuplicating
True
>>> [str(p) for p in sc.pitches]
['B3', 'C4', 'D4', 'E4', 'F4', 'G4', 'A4', 'B4']
>>> sc.getTonic()
<music21.pitch.Pitch E4>
>>> sc.getDominant()
<music21.pitch.Pitch A4>
>>> sc.pitchFromDegree(1)  # scale degree 1 is treated as lowest
<music21.pitch.Pitch B3>
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   HypophrygianScale.__init__  s5    1u11"	##DII.rC   rQ   r  r~  rr   s   @rD   r   r     s    / /rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i  a  
A hypolydian scale

>>> sc = scale.HypolydianScale(pitch.Pitch('f'))
>>> [str(p) for p in sc.pitches]
['C4', 'D4', 'E4', 'F4', 'G4', 'A4', 'B4', 'C5']
>>> sc = scale.HypolydianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['G3', 'A3', 'B3', 'C4', 'D4', 'E4', 'F#4', 'G4']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   HypolydianScale.__init__&  r  rC   rQ   r  r~  rr   s   @rD   r   r         	/ /rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r   i,  a(  
A hypomixolydian scale

>>> sc = scale.HypomixolydianScale(pitch.Pitch('g'))
>>> [str(p) for p in sc.pitches]
['D4', 'E4', 'F4', 'G4', 'A4', 'B4', 'C5', 'D5']
>>> sc = scale.HypomixolydianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['G3', 'A3', 'B-3', 'C4', 'D4', 'E4', 'F4', 'G4']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   HypomixolydianScale.__init__7  s5    1u11$	##DII.rC   rQ   r  r~  rr   s   @rD   r   r   ,  r  rC   r   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r    i=  a$  
A so-called "locrian" scale

>>> sc = scale.LocrianScale(pitch.Pitch('b'))
>>> [str(p) for p in sc.pitches]
['B4', 'C5', 'D5', 'E5', 'F5', 'G5', 'A5', 'B5']

>>> sc = scale.LocrianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['C4', 'D-4', 'E-4', 'F4', 'G-4', 'A-4', 'B-4', 'C5']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   LocrianScale.__init__J  s5    1u11	##DII.rC   rQ   r  r~  rr   s   @rD   r    r    =  r  rC   r    c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r!   iP  a%  
A hypolocrian scale

>>> sc = scale.HypolocrianScale(pitch.Pitch('b'))
>>> [str(p) for p in sc.pitches]
['F4', 'G4', 'A4', 'B4', 'C5', 'D5', 'E5', 'F5']

>>> sc = scale.HypolocrianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['G-3', 'A-3', 'B-3', 'C4', 'D-4', 'E-4', 'F4', 'G-4']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   HypolocrianScale.__init__]  5    1u11!	##DII.rC   rQ   r  r~  rr   s   @rD   r!   r!   P  r  rC   r!   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r"   ic  a"  
A hypoaeolian scale

>>> sc = scale.HypoaeolianScale(pitch.Pitch('a'))
>>> [str(p) for p in sc.pitches]
['E4', 'F4', 'G4', 'A4', 'B4', 'C5', 'D5', 'E5']

>>> sc = scale.HypoaeolianScale(pitch.Pitch('c'))
>>> [str(p) for p in sc.pitches]
['G3', 'A-3', 'B-3', 'C4', 'D4', 'E-4', 'F4', 'G4']
c                   > [         TU ]  " SSU0UD6  SU l        U R                  R	                  U R                  5        g )Nrt  r  r=   r|  r_  s      rD   rI   HypoaeolianScale.__init__o  r  rC   rQ   r  r~  rr   s   @rD   r"   r"   c  s    
/ /rC   r"   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r#   iw  a/  
The harmonic minor collection, realized as a scale.

(The usage of this collection as a scale, is quite ahistorical for
Western European classical music, but it is common in other parts of the
world, but where the term "HarmonicMinor" would not be appropriate).

>>> sc = scale.HarmonicMinorScale('e4')
>>> [str(p) for p in sc.pitches]
['E4', 'F#4', 'G4', 'A4', 'B4', 'C5', 'D#5', 'E5']
>>> sc.getTonic()
<music21.pitch.Pitch E4>
>>> sc.getDominant()
<music21.pitch.Pitch B4>
>>> sc.pitchFromDegree(1)  # scale degree 1 is treated as lowest
<music21.pitch.Pitch E4>

>>> sc = scale.HarmonicMinorScale()
>>> sc
<music21.scale.HarmonicMinorScale Abstract harmonic minor>
>>> sc.deriveRanked(['C', 'E', 'G'], comparisonAttribute='name')
[(3, <music21.scale.HarmonicMinorScale F harmonic minor>),
 (3, <music21.scale.HarmonicMinorScale E harmonic minor>),
 (2, <music21.scale.HarmonicMinorScale B harmonic minor>),
 (2, <music21.scale.HarmonicMinorScale A harmonic minor>)]

Note that G and D are also equally good as B and A, but the system arbitrarily
chooses among ties.
c                V   > [         TU ]  " SSU0UD6  SU l        [        5       U l        g )Nrt  zharmonic minorr=   )rH   rI   rJ   r   rr  r_  s      rD   rI   HarmonicMinorScale.__init__  s+    1u11$	
 45rC   ry  r  r~  rr   s   @rD   r#   r#   w  s    <6 6rC   r#   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r$   i  zn
A melodic minor scale, which is not the same ascending or descending

>>> sc = scale.MelodicMinorScale('e4')
c                V   > [         TU ]  " SSU0UD6  SU l        [        5       U l        g )Nrt  zmelodic minorr=   )rH   rI   rJ   r   rr  r_  s      rD   rI   MelodicMinorScale.__init__  s+    1u11#	 34rC   ry  r  r~  rr   s   @rD   r$   r$     s    5 5rC   r$   c                  4   ^  \ rS rSrSrSrSU 4S jjrSrU =r$ )r%   i  z0
A concrete Octatonic scale in one of two modes
Tc                T   > [         TU ]  " SSU0UD6  [        US9U l        SU l        g )Nrt  r   	Octatonicr=   )rH   rI   r   rr  rJ   )rL   rt  r   rM   rN   s       rD   rI   OctatonicScale.__init__  s+    1u11/T:	rC   ry  r  	r>   r?   r@   rA   rn   r  rI   rB   rq   rr   s   @rD   r%   r%     s        rC   r%   c                  4   ^  \ rS rSrSrSSU 4S jjjrSrU =r$ )r&   i  a~  
A concrete cyclical scale, based on a cycle of intervals.


>>> sc = scale.OctaveRepeatingScale('c4', ['m3', 'M3'])
>>> sc.pitches
[<music21.pitch.Pitch C4>, <music21.pitch.Pitch E-4>,
 <music21.pitch.Pitch G4>, <music21.pitch.Pitch C5>]
>>> [str(p) for p in sc.getPitches('g2', 'g6')]
['G2', 'C3', 'E-3', 'G3', 'C4', 'E-4', 'G4', 'C5', 'E-5', 'G5', 'C6', 'E-6', 'G6']
>>> sc.getScaleDegreeFromPitch('c4')
1
>>> sc.getScaleDegreeFromPitch('e-')
2

No `intervalList` defaults to a single minor second:

>>> sc2 = scale.OctaveRepeatingScale()
>>> sc2.pitches
[<music21.pitch.Pitch C4>, <music21.pitch.Pitch D-4>, <music21.pitch.Pitch C5>]
c                l   > [         TU ]  " SSU0UD6  U(       a  UOS/n[        US9U l        SU l        g )Nrt  r   r   zOctave Repeatingr=   )rH   rI   r   rr  rJ   rL   rt  r   rM   r   rN   s        rD   rI   OctaveRepeatingScale.__init__  s6    1u11+|$54@&	rC   ry  r  )r   list | Noner~  rr   s   @rD   r&   r&     s    ,' 'rC   r&   c                  >   ^  \ rS rSrSr  S   SU 4S jjjrSrU =r$ )r'   i  aM  
A concrete cyclical scale, based on a cycle of intervals.

>>> sc = scale.CyclicalScale('c4', ['P5'])  # can give one list
>>> sc.pitches
[<music21.pitch.Pitch C4>, <music21.pitch.Pitch G4>]
>>> [str(p) for p in sc.getPitches('g2', 'g6')]
['B-2', 'F3', 'C4', 'G4', 'D5', 'A5', 'E6']
>>> sc.getScaleDegreeFromPitch('g4')  # as single interval cycle, all are 1
1
>>> sc.getScaleDegreeFromPitch('b-2', direction=scale.Direction.BI)
1

No `intervalList` defaults to a single minor second:

>>> sc2 = scale.CyclicalScale()
>>> sc2.pitches
[<music21.pitch.Pitch C4>, <music21.pitch.Pitch D-4>]
c                l   > [         TU ]  " SSU0UD6  U(       a  UOS/n[        US9U l        SU l        g )Nrt  r   r   Cyclicalr=   rH   rI   r   rr  rJ   r  s        rD   rI   CyclicalScale.__init__  s8     	1u11+|$.D9	rC   ry  r  )rt  rV  r   r  r~  rr   s   @rD   r'   r'     s*    * :>+/6( rC   r'   c                  4   ^  \ rS rSrSrSrSU 4S jjrSrU =r$ )r(   i  a"  
A concrete cyclical scale, based on a cycle of half steps.


>>> sc = scale.ChromaticScale('g2')
>>> [str(p) for p in sc.pitches]
['G2', 'A-2', 'A2', 'B-2', 'B2', 'C3', 'C#3', 'D3', 'E-3', 'E3', 'F3', 'F#3', 'G3']
>>> [str(p) for p in sc.getPitches('g2', 'g6')]
['G2', 'A-2', ..., 'F#3', 'G3', 'A-3', ..., 'F#4', 'G4', 'A-4', ..., 'G5', ..., 'F#6', 'G6']
>>> sc.abstract.getDegreeMaxUnique()
12
>>> sc.pitchFromDegree(1)
<music21.pitch.Pitch G2>
>>> sc.pitchFromDegree(2)
<music21.pitch.Pitch A-2>
>>> sc.pitchFromDegree(3)
<music21.pitch.Pitch A2>
>>> sc.pitchFromDegree(8)
<music21.pitch.Pitch D3>
>>> sc.pitchFromDegree(12)
<music21.pitch.Pitch F#3>
>>> sc.getScaleDegreeFromPitch('g2', comparisonAttribute='pitchClass')
1
>>> sc.getScaleDegreeFromPitch('F#6', comparisonAttribute='pitchClass')
12
Tc                   > [         TU ]  " SSU0UD6  [        / SQS9U l        SU R                  R                  l        SU l        g )Nrt  )r   r   r   r   r   r   r   r   r   r   r   r   r   rV  	Chromaticr=   )rH   rI   r   rr  rv   r  rJ   r_  s      rD   rI   ChromaticScale.__init__  sF    1u11. 5B C 3?/	rC   ry  r  r  rr   s   @rD   r(   r(     s    4    rC   r(   c                  4   ^  \ rS rSrSrSrSU 4S jjrSrU =r$ )r)   i$  a  
A concrete whole-tone scale.

>>> sc = scale.WholeToneScale('g2')
>>> [str(p) for p in sc.pitches]
['G2', 'A2', 'B2', 'C#3', 'D#3', 'E#3', 'G3']
>>> [str(p) for p in sc.getPitches('g2', 'g5')]
['G2', 'A2', 'B2', 'C#3', 'D#3', 'E#3', 'G3', 'A3', 'B3', 'C#4',
 'D#4', 'E#4', 'G4', 'A4', 'B4', 'C#5', 'D#5', 'E#5', 'G5']
>>> sc.abstract.getDegreeMaxUnique()
6
>>> sc.pitchFromDegree(1)
<music21.pitch.Pitch G2>
>>> sc.pitchFromDegree(2)
<music21.pitch.Pitch A2>
>>> sc.pitchFromDegree(6)
<music21.pitch.Pitch E#3>
>>> sc.getScaleDegreeFromPitch('g2', comparisonAttribute='pitchClass')
1
>>> sc.getScaleDegreeFromPitch('F6', comparisonAttribute='pitchClass')
6
Tc                X   > [         TU ]  " SSU0UD6  [        / SQS9U l        SU l        g )Nrt  )r   r   r   r   r   r   r   z
Whole toner=   r  r_  s      rD   rI   WholeToneScale.__init__=  s,    1u11.4XY 	rC   ry  r  r  rr   s   @rD   r)   r)   $  s    , ! !rC   r)   c                  <   ^  \ rS rSrSr   S SU 4S jjjrSrU =r$ )r*   iC  a  
A scale created from a Xenakis sieve logical string, based on the
:class:`~music21.sieve.Sieve` object definition. The complete period of the
sieve is realized as intervals and used to create a scale.


>>> sc = scale.SieveScale('c4', '3@0')
>>> sc.pitches
[<music21.pitch.Pitch C4>, <music21.pitch.Pitch E-4>]
>>> sc = scale.SieveScale('d4', '3@0')
>>> sc.pitches
[<music21.pitch.Pitch D4>, <music21.pitch.Pitch F4>]
>>> sc = scale.SieveScale('c2', '(-3@2 & 4) | (-3@1 & 4@1) | (3@2 & 4@2) | (-3 & 4@3)')
>>> [str(p) for p in sc.pitches]
['C2', 'D2', 'E2', 'F2', 'G2', 'A2', 'B2', 'C3']


OMIT_FROM_DOCS

Test that an empty SieveScale can be created:

>>> sc = scale.SieveScale()
c           	     b  > [         TU ]  " SSU0UD6  U R                  b  U R                  nO[        R                  " S5      n[
        R                  " U[        U5      [        UR                  S5      5      US9U l	        U R                  R                  5       n[        US9U l        SU l        g )Nrt  r  0   )
pitchLower
pitchUppereldr   Siever=   )rH   rI   rt  r6   r_   r8   
PitchSiever   r  _pitchSievegetIntervalSequencer   rr  rJ   )rL   rt  sieveStringr  rM   intervalSequencerN   s         rD   rI   SieveScale.__init__\  s    
 	1u11 ::!JJEKK%E ++K7:5z7:5??2;N7OUXZ  ++??A.4DE	rC   )rr  r  rJ   )Nz2@0ry   )r  zint | floatr~  rr   s   @rD   r*   r*   C  s'    2 ""#   rC   r*   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r+   iu  a  
A scale created from a Scala scale .scl file. Any file
in the Scala archive can be given by name. Additionally, a file
path to a Scala .scl file, or a raw string representation, can be used.

>>> sc = scale.ScalaScale('g4', 'mbira banda')
>>> [str(p) for p in sc.pitches]
['G4', 'A4(-15c)', 'B4(-11c)', 'C#5(-7c)', 'D~5(+6c)', 'E5(+14c)', 'F~5(+1c)', 'G#5(+2c)']

If only a single string is given, and it's too long to be a tonic,
or it ends in .scl, assume it's the name of a scala scale and
set the tonic to C4

>>> sc = scale.ScalaScale('pelog_9')
>>> [str(p) for p in sc.pitches]
['C4', 'C#~4(-17c)', 'D~4(+17c)', 'F~4(-17c)',
 'F#~4(+17c)', 'G#4(-0c)', 'A~4(-17c)', 'C5(-0c)']

If no scale with that name can be found then it raises an exception:

>>> sc = scale.ScalaScale('badFileName.scl')
Traceback (most recent call last):
music21.scale.ScaleException: Could not find a file named badFileName.scl in the scala database
c                  > UbA  Uc>  [        U[        5      (       a)  [        U5      S:  d  UR                  S5      (       a  UnSn[        TU ]  " SSU0UD6  S U l        S U l        UbK  UR                  S5      S:  a6  [        R                  " U5      U l        U R                  R                  5         OMUb/  [        R                  " U5      nUc  [        SU S35      eX@l        O[        R                  " S	5      U l        U R                  R                  5       n[        US
9U l        SU R                  R                   l        SU R                  R$                   3U l        U R                  R                  U l        g )Nr  sclr  rt  
r	  zCould not find a file named z in the scala databasezfj-12tet.sclr   rV  zScala: r=   )r^   r   rH  endswithrH   rI   
_scalaDatar   countr   r   parser   r  r   rr  rv   r  fileNamerJ   )rL   rt  scalaStringrM   readFiler  rN   s         rD   rI   ScalaScale.__init__  sH   #5#&&UqNN5))KE1u11 "{'8'8'>'B#ook:DOOO!!#$ {{;/H$2;-?UVX X&O#kk.9DO??>>@.4DE2>/doo6678	??66rC   )rr  r  r   rJ   r  r~  rr   s   @rD   r+   r+   u  s    2$7 $7rC   r+   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r,   i  a  
A concrete pseudo-raga scale.

>>> sc = scale.RagAsawari('c2')
>>> [str(p) for p in sc.pitches]
['C2', 'D2', 'F2', 'G2', 'A-2', 'C3']
>>> [str(p) for p in sc.getPitches(direction=scale.Direction.DESCENDING)]
['C3', 'B-2', 'A-2', 'G2', 'F2', 'E-2', 'D2', 'C2']
c                V   > [         TU ]  " SSU0UD6  [        5       U l        SU l        g )Nrt  zRag Asawarir=   )rH   rI   r   rr  rJ   r_  s      rD   rI   RagAsawari.__init__  s)    1u11+-!	rC   ry  r  r~  rr   s   @rD   r,   r,     s    " "rC   r,   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r-   i  z
A concrete pseudo-raga scale.

>>> sc = scale.RagMarwa('c2')

this gets a pitch beyond the terminus b/c of descending form max

>>> [str(p) for p in sc.pitches]
['C2', 'D-2', 'E2', 'F#2', 'A2', 'B2', 'A2', 'C3', 'D-3']
c                V   > [         TU ]  " SSU0UD6  [        5       U l        SU l        g )Nrt  z	Rag Marwar=   )rH   rI   r   rr  rJ   r_  s      rD   rI   RagMarwa.__init__  s)    1u11)+	rC   ry  r  r~  rr   s   @rD   r-   r-     s    	   rC   r-   c                  0   ^  \ rS rSrSrSU 4S jjrSrU =r$ )r.   i  zb
A concrete scale based on a dynamic mixture of a minor pentatonic
and the hexatonic blues scale.
c                V   > [         TU ]  " SSU0UD6  [        5       U l        SU l        g )Nrt  zWeighted Hexatonic Bluesr=   )rH   rI   r   rr  rJ   r_  s      rD   rI   WeightedHexatonicBlues.__init__  s)    1u1179.	rC   ry  r  r~  rr   s   @rD   r.   r.     s    
/ /rC   r.   __main__)Orn   
__future__r   __all__r   typingrZ  music21.scaler   music21.scale.intervalNetworkr   r   r   r  r/   r0   music21.common.decoratorsr1   r2   r3   r4   r5   r6   r7   r8   Environmentr   r<  rJ   r   r)  rX  _PitchDegreeCacheKeyr:   __annotations__Music21Exceptionr   Music21Objectr	   r
   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r    r!   r"   r#   r$   r%   r&   r'   r(   r)   r*   r+   r,   r-   r.   
_DOC_ORDERr>   mainTestr=   rC   rD   <module>r     s  > #"   ) =    0        &&w/	  68 2 7	\22 	nD nfp7E p7lP&M P&f$Y] $YP
 
@% %,^M ^6'^= '^TU. U.pR.} R.j=.] =.B@+E @+L*NSM NSf/ /&/ //- //M //- /(/m /&/m /$/ /,/m /"/- /"/= /&/} /&/} /(&6 &6V5 5&	 ] 	 '= '<M ># ] # L!] !>/ /d>7 >7B" "" }  (	/] 	/" ]+
 z rC   