rh|SrSSKJr SSKJr SSKJr SSKJr "SS\R5r "SS \R5r \ S :XaSS Kr\R"5 g g ) z These are the lowest level tools for working with self-balancing AVL trees. There's an overhead to creating an AVL tree, but for a large score it is absolutely balanced by having O(log n) search times. ) annotations)prebase) TreeException)commonc\rSrSr%SrSrSSSSSS S .rS \S 'SSjrSr Sr Sr Sr Sr SrSrSrSrSrSrg )AVLNodea An AVL Tree Node, not specialized in any way, just contains positions. >>> position = 1.0 >>> node = tree.core.AVLNode(position) >>> node >>> n2 = tree.core.AVLNode(2.0) >>> node.rightChild = n2 >>> node.update() >>> node Nodes can rebalance themselves, but they work best in a Tree. Please consult the Wikipedia entry on AVL trees (https://en.wikipedia.org/wiki/AVL_tree) for a very detailed description of how this data structure works. ) __weakref__balanceheightpositionpayload leftChild rightChilda# Returns the current state of the difference in heights of the two subtrees rooted on this node. This attribute is used to help balance the AVL tree. >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> print(scoreTree.debug()) L: L: R: R: L: R: R: This tree has one more depth on the right than on the left >>> scoreTree.rootNode.balance 1 The leftChild of the rootNote is perfectly balanced, while the rightChild is off by one (acceptable). >>> scoreTree.rootNode.leftChild.balance 0 >>> scoreTree.rootNode.rightChild.balance 1 The rightChild's children are also (acceptably) unbalanced: >>> scoreTree.rootNode.rightChild.leftChild.balance 0 >>> scoreTree.rootNode.rightChild.rightChild.balance 1 You should never see a balance other than 1, -1, or 0. If you do then something has gone wrong. a The height of the subtree rooted on this node. This property is used to help balance the AVL tree. >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> print(scoreTree.debug()) L: L: R: R: L: R: R: >>> scoreTree.rootNode.height 3 >>> scoreTree.rootNode.rightChild.height 2 >>> scoreTree.rootNode.rightChild.rightChild.height 1 >>> scoreTree.rootNode.rightChild.rightChild.rightChild.height 0 Once you hit a height of zero, then the next child on either size should be None >>> print(scoreTree.rootNode.rightChild.rightChild.rightChild.rightChild) None zR The content of the node at this point. Usually a Music21Object. a& The position of this node -- this is often the same as the offset of the node in a containing score, but does not need to be. It could be the .sortTuple >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> print(scoreTree.rootNode.debug()) L: L: R: R: L: R: R: >>> scoreTree.rootNode.position 3.0 >>> scoreTree.rootNode.leftChild.position 1.0 >>> scoreTree.rootNode.rightChild.position 5.0 a! The left child of this node. After setting the left child you need to do a node update. with node.update() >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> print(scoreTree.rootNode.debug()) L: L: R: R: L: R: R: >>> print(scoreTree.rootNode.leftChild.debug()) L: R: a The right child of this node. After setting the right child you need to do a node update. with node.update() >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> print(scoreTree.rootNode.debug()) L: L: R: R: L: R: R: >>> print(scoreTree.rootNode.rightChild.debug()) L: R: R: >>> print(scoreTree.rootNode.rightChild.rightChild.debug()) R: >>> print(scoreTree.rootNode.rightChild.rightChild.rightChild.debug()) )r r rr rrzdict[str, str] _DOC_ATTRNcTXlX lSUlSUlSUlSUlg)Nr)r rr r rr)selfr rs K/home/james-whalen/.local/lib/python3.13/site-packages/music21/tree/core.py__init__AVLNode.__init__s(    c SnUR(aURRnSnUR(aURRnSRURR UR URUU5$)Nz"<{}: Start:{} Height:{} L:{} R:{}>)rr rformat __class____name__r )rlcHeightrcHeights r__repr__AVLNode.__repr__sl >>~~,,H ??--H3:: NN # # MM KK     rcHURUlURUlg)a move attributes from this node to another in case "removal" actually means substituting one node for another in the tree. Subclass this in derived classes Do not copy anything about height, balance, left or right children, etc. By default just moves position and payload. N)r r)rothers rmoveAttributesAVLNode.moveAttributess  rc@SRUR55$)a Get a debug of the Node: >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> rn = scoreTree.rootNode >>> print(rn.debug()) L: L: R: R: L: R: R:  )join_getDebugPiecesrs rdebug AVLNode.debugs$yy--/00rc/nUR[U55 UR(aLURR5nURSUS35 UR SUSS55 UR (aLUR R5nURSUS35 UR SUSS55 U$)a Return a list of the debugging information of the tree (used for debug): Called recursively >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> rn = scoreTree.rootNode >>> rn._getDebugPieces() ['', '\tL: ', '\t\tL: ', '\t\tR: ', '\tR: ', '\t\tL: ', '\t\tR: ', '\t\t\tR: '] z L: rc3,# UH nSU-v M g7f N.0xs r *AVLNode._getDebugPieces..?:Mq$(MNz R: c3,# UH nSU-v M g7fr-r/r0s rr3r4Cr5r6)appendreprrr'extendr)rresult subResults rr'AVLNode._getDebugPieces&s( d4j! >>668I MME)A,0 1 MM:IabM: : ??779I MME)A,0 1 MM:IabM: : rcUR(aURROSnUR(aURROSn[X5S-UlX!- Ulg)aE Updates the height and balance attributes of the nodes. Must be called whenever .leftChild or .rightChild are changed. Used for the next balancing operation -- does not rebalance itself. Note that it only looks at its children's height and balance attributes not their children's. So if they are wrong, this will be too. Returns None We create a score with everything correct. >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> n = scoreTree.rootNode >>> n >>> n.height, n.balance (3, 1) Now let's screw up the height and balance >>> n.height = 100 >>> n.balance = -2 >>> n.height, n.balance (100, -2) But we can fix it with `.update()` >>> n.update() >>> n.height, n.balance (3, 1) Note that if we were to screw up the balance/height of one of the child notes of `n` then this would not fix that node's balance/height. This method assumes that children have the correct information and only updates the information for this node. r7N)rr rmaxr )r leftHeight rightHeights rupdateAVLNode.updateFsNV/3nnT^^**" 04doo,,R *2Q6 "/ rcURnURUlUR5 XlUR5 U$)z Rotates a node left twice. Makes this node the rightChild of the former leftChild and makes the former leftChild's rightChild be the leftChild of this node. Used during tree rebalancing. Returns the prior leftChild node as the new central node. )rrrDrnextNodes rrotateLeftLeftAVLNode.rotateLeftLeftvs8>>!,, "rcURR5UlUR5 UR5nU$)z Rotates a node left, then right. Makes this note the rightChild of the former rightChild of the former leftChild node Used during tree rebalancing. Returns the former rightChild of the former leftChild node as the new central node. )rrotateRightRightrDrIrGs rrotateLeftRightAVLNode.rotateLeftRights488: &&(rcURR5UlUR5 UR5nU$)z Rotates a node right, then left. Makes this note the leftChild of the former leftChild of the former rightChild node Used during tree rebalancing. Returns the former leftChild of the former rightChild node as the new central node. )rrIrDrLrGs rrotateRightLeftAVLNode.rotateRightLefts4//88: ((*rcURnURUlUR5 XlUR5 U$)z Rotates a node right twice. Makes this node the leftChild of the former rightChild and makes the former rightChild's leftChild be the rightChild of this node. Used during tree rebalancing. Returns the prior rightChild node as the new central node. )rrrDrGs rrLAVLNode.rotateRightRights8??",, !rcUnURS:a<URRS:aUR5nO\UR5nOKURS:a;URRS::aUR 5nOUR 5nURS:dURS:a [S5eU$)zL Rebalances the subtree rooted on this node. Returns the new central node. r7rr@zNSomehow Nodes are still not balanced. node.balance %r must be between -1 and 1)r rrLrPrrIrMr)rnodes r rebalanceAVLNode.rebalances  <>> nodePositions = [0, 2, 4, 6, 8, 10, 12] >>> avl = tree.core.AVLTree() >>> for np in nodePositions: ... avl.createNodeAtPosition(np) >>> for x in avl: ... x Note: for this example to be stable, we can't shuffle the nodes, since there are numerous possible configurations that meet the AVLTree constraints, some of height 2 and some of height 3 c3># UbTURbT"UR5ShvN Uv URbT"UR5ShvN gggN2N 7frX)rr)rUrecurses rrh!AVLTree.__iter__..recurses[>>-&t~~666 ??.&t777/  68s!&A A*A AA A rd)rrhs @r__iter__AVLTree.__iter__s2 8t}}%%rcL^^SUU4SjjmURmT"U5Ulg)a Populate this tree from a sorted list of two-tuples of (position, payload). This is about an order of magnitude faster (3ms vs 21ms for 1000 items; 31 vs. 300ms for 10,000 items) than running createNodeAtPosition() for each element in a list if it is already sorted. Thus, it should be used when converting a Stream where .isSorted is True into a tree. This method assumes that the current tree is empty (or will be wiped) and that listOfTuples is a non-empty list where the first element is a unique position to insert, and the second is the complete payload for that node, and that the positions are strictly increasing in order. If any of the conditions is not true, expect to get a dangerously badly sorted tree that will be useless. >>> listOfTuples = [(i, str(i)) for i in range(1000)] >>> listOfTuples[10] (10, '10') >>> avlTree = tree.core.AVLTree() >>> avlTree.rootNode is None True >>> avlTree.populateFromSortedList(listOfTuples) >>> avlTree.rootNode >>> n = avlTree.rootNode >>> while n is not None: ... print(n, repr(n.payload)) ... n = n.leftChild '500' '250' '125' '62' '31' '15' '7' '3' '1' '0' c>U(dg[U5S-nXnT"USUS5nT"USU5UlT"XS-S5UlUR5 U$)z Divide and conquer. Nrr7)lenrrrD)subListOfTuplesmidpointmidtuplen NodeClassrhs rrh/AVLTree.populateFromSortedList..recurse5sl#?+q0H&0H(1+x{3A!/)8"<=AK"?a<=#ABAL HHJHrN)returnzAVLNode | None) nodeClassrb)r listOfTuplesrtrhs @@rpopulateFromSortedListAVLTree.populateFromSortedLists%Z  NN  - rcF^^UU4SjmT"TRU5Tlg)a creates a new node at position and sets the rootNode appropriately >>> avl = tree.core.AVLTree() >>> avl.createNodeAtPosition(20) >>> avl.rootNode >>> avl.createNodeAtPosition(10) >>> avl.rootNode >>> avl.createNodeAtPosition(5) >>> avl.rootNode >>> avl.createNodeAtPosition(30) >>> avl.rootNode >>> avl.rootNode.leftChild >>> avl.rootNode.rightChild >>> avl.rootNode.rightChild.rightChild c4>UcTRU5$XR:a)T"URU5UlUR5 O8URU:a(T"URU5UlUR5 UbUR 5$g)z this recursively finds the right place for the new node and either creates a new node (if it is in the right place) or rebalances the nodes above it and tells those nodes how to set their new roots. N)rwr rrDrrV)rU innerPositionrhrs rrh-AVLTree.createNodeAtPosition..recursecs|~~m44}},!(!G .")$//="I ~~'' rNrdrr rhs` @rcreateNodeAtPositionAVLTree.createNodeAtPositionFs: (*  x8 rcRURbURR5$g)a  Gets string representation of the node tree. Useful only for debugging its internal node structure. >>> tsList = [(0, 2), (0, 9), (1, 1), (2, 3), (3, 4), ... (4, 9), (5, 6), (5, 8), (6, 8), (7, 7)] >>> tss = [tree.spans.Timespan(x, y) for x, y in tsList] >>> tsTree = tree.timespanTree.TimespanTree() >>> tsTree.insert(tss) >>> print(tsTree.debug()) L: L: R: R: L: R: R: )rbr)r(s rr) AVLTree.debugzs$, == $==&&( (rc4^U4SjmT"XR5$)zr Searches for a node whose position is `position` in the subtree rooted on `node`. Returns a Node object or None c>UbwURU:XaU$UR(a!XR:aT"XR5$UR(a"URU:aT"XR5$grX)r rr)r}rUrhs rrh*AVLTree.getNodeByPosition..recurses]==M1K^^ (E"=..AA__)F"=//BBrrdrs @rgetNodeByPositionAVLTree.getNodeByPositions x//rcB^U4SjmT"URU5nUcgU$)a Gets the first node after `position`. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTree(flatten=True) >>> node1 = scoreTree.getNodeAfter(0.5) >>> node1 Indices:(l:27 *29* r:33) Payload:> >>> node2 = scoreTree.getNodeAfter(0.6) >>> node2 is node1 True >>> endNode = scoreTree.getNodeAfter(9999) >>> endNode Indices:(l:191 *195* r:199) Payload:> >>> while endNode is not None: ... print(endNode) ... endNodePosition = endNode.position ... endNode = scoreTree.getNodeAfter(endNodePosition) Indices:(l:191 *195* r:199) Payload:> Indices:(l:196 *196* r:197) Payload:> Indices:(l:196 *197* r:199) Payload:> Indices:(l:198 *198* r:199) Payload:> >>> note1 = score.flatten().notes[30] Works with sortTuple positions as well: >>> st = note1.sortTuple() >>> st SortTuple(atEnd=0, offset=6.0, priority=0, classSortOrder=20, isNotGrace=1, insertIndex=...) >>> scoreTree.getNodeAfter(st) Indices:(l:55 *56* r:57) Payload:> c>UcgSnURU::a&UR(aT"URU5nU$XR:aT"URU5=(d UnU$rXr rr)rUr} inner_resultrhs rrh%AVLTree.getNodeAfter..recursesa|L}} -$//&t F  .&t~~}EM  rNrdrr r<rhs @r getNodeAfterAVLTree.getNodeAfters(V 1 > rcLURU5nU(a UR$g)a Gets start position after `position`. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTree(flatten=True) >>> scoreTree.getPositionAfter(0.5).offset 1.0 Returns None if no succeeding position exists. >>> endPosition = scoreTree.getPositionAfter(9999) >>> while endPosition is not None: ... print(endPosition) ... endPosition = scoreTree.getPositionAfter(endPosition) SortTuple(atEnd=1, offset=36.0, priority=0, classSortOrder=-5, ...) SortTuple(atEnd=1, offset=36.0, priority=0, classSortOrder=-5, ...) SortTuple(atEnd=1, offset=36.0, priority=0, classSortOrder=-5, ...) SortTuple(atEnd=1, offset=36.0, priority=0, classSortOrder=-5, ...) Generally speaking, negative positions will usually return 0.0 >>> scoreTree.getPositionAfter(-999).offset 0.0 Unless the Tree is empty in which case, None is returned: >>> at = tree.core.AVLTree() >>> at.getPositionAfter(-999) is None True N)rr rr rUs rgetPositionAfterAVLTree.getPositionAfters$>  * == rcB^U4SjmT"URU5nUcgU$)a7 Finds the node immediately before position. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() 100 is beyond the end, so it will get the last node in piece. >>> scoreTree.getNodeBefore(100) >>> scoreTree.getNodeBefore(0) is None True c>UcgSnURU:aT"URU5=(d UnU$XR::a$UR(aT"URU5nU$rXr)rUr} innerResultrhs rrh&AVLTree.getNodeBefore..recursesa|K}}},%doo}EM  --/DNN%dnnmD  rNrdrs @r getNodeBeforeAVLTree.getNodeBefores' 1 > rcDURU5nUcgUR$)a# Gets the start position immediately preceding `position` in this position-tree. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> scoreTree.getPositionBefore(100) 36.0 Return None if no preceding position exists. >>> scoreTree.getPositionBefore(0) is None True N)rr rs rgetPositionBeforeAVLTree.getPositionBefore$s&!!(+ <}}rcB^U4SjmT"URU5Ulg)a Removes a node at `position` and rebalances the tree Used internally by TimespanTree. >>> avl = tree.core.AVLTree() >>> avl.createNodeAtPosition(20) >>> avl.createNodeAtPosition(10) >>> avl.createNodeAtPosition(5) >>> avl.createNodeAtPosition(30) >>> avl.rootNode Remove node at 30 >>> avl.removeNode(30) >>> avl.rootNode Removing a node eliminates its payload: >>> ten = avl.getNodeByPosition(10) >>> ten.payload = 'ten' >>> twenty = avl.getNodeByPosition(20) >>> twenty.payload = 'twenty' >>> avl.removeNode(10) >>> avl.rootNode >>> avl.rootNode.payload 'twenty' Removing a non-existent node does nothing. >>> avl.removeNode(9.5) >>> avl.rootNode >>> for n in avl: ... print(n, n.payload) None twenty c>UGbCURU:XaUR(aUR(aURnUR(aURnUR(aMURU5 T"URUR5UlUR 5 OUR=(d URnOqURU:a)T"URU5UlUR 5 O8URU:a(T"URU5UlUR 5 UbUR 5$grX)r rrr"rDrV)rUr}rH recurseRemoves rr)AVLTree.removeNode..recurseRemoveds==M1~~$//#'??&00'/'9'9H'000 //5*7IZIZ*[ #~~@]]]2%24>>=%QDNKKM]]]2&3DOO]&SDOKKM~~'' rNrd)rr rs @r removeNodeAVLTree.removeNode8sX (,&dmmX> rrdN)rrYrZr[r\r]rrwrrjryrr)rrrrrrr_r/rrrarasR II &D<.|29h40&8t#J<(B?rra__main__N)r\ __future__rmusic21rmusic21.exceptions21rrSlottedObjectMixinrProtoM21ObjectrarmainTestr/rrrs` #. wf''wx c?g$$c?N  z r