gh-39945: Fixing high complexity canonical_labelling for OrderedTree and BinaryTree
    
Added canonical_labelling overwrite to OrderedTree, modified the same
method in BinaryTree, so that the complexity is linear, instead of
quadratic in the original implementation.

This solves the issue #35930, which arises when using Sagemath to do
linear-time random generation of large tree-like structures based on
OrderedTree or BinaryTree when a canonical labelling is needed, in which
case the quadratic nature of the original algorithm slows down a linear
random generator.

This is done by using a "boxed" value to keep track of already-assigned
labels, instead of computing the number of nodes at each time for the
shifting. The precise implementation takes care so that the canonical
labellings given in the examples are not changed.

Comments are also updated.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

#35930: This PR solves the given issue.
    
URL: #39945
Reported by: fwjmath
Reviewer(s): fwjmath, Travis Scrimshaw

Author: Release Manager

src/sage/combinat/abstract_tree.py

@@ -1198,14 +1198,28 @@ def node_number(self):
             sage: T.node_number()
             10000
         """
-        count = 0
+        # An attribute _node_number for storing the number of nodes
+        # This is OK as AbstractTree is immutable
+        # If the attribute is not present, we compute it
+        try:
+            return self._node_number
+        except AttributeError:
+            pass
+
+        if self.is_empty():
+            self._node_number = Integer(0)
+            return self._node_number
 
-        def incr(node):
-            nonlocal count
-            count += 1
+        def count(node):
+            if not node.is_empty():
+                # Using post-order
+                # Thus _node_number is computed for all non-empty subtrees
+                node._node_number = Integer(1)
+                node._node_number += sum(e._node_number for e in node
+                                         if not e.is_empty())
 
-        self.iterative_pre_order_traversal(incr)
-        return Integer(count)
+        self.iterative_post_order_traversal(count)
+        return self._node_number
 
     def depth(self):
         """
@@ -1518,13 +1532,14 @@ def canonical_labelling(self, shift=1):
             sage: BinaryTree().canonical_labelling()
             .
         """
-        LTR = self.parent().labelled_trees()
-        liste = []
-        deca = 1
-        for subtree in self:
-            liste += [subtree.canonical_labelling(shift + deca)]
-            deca += subtree.node_number()
-        return LTR._element_constructor_(liste, label=shift)
+        def aux(tree, LTR, curlabel):
+            mylabel = curlabel[0]
+            curlabel[0] += 1
+            newtree = LTR([aux(st, LTR, curlabel) for st in tree],
+                          label=mylabel)
+            return newtree
+
+        return aux(self, self.parent().labelled_trees(), [shift])
 
     def to_hexacode(self):
         r"""
@@ -2181,6 +2196,41 @@ def __getitem__(self, idx):
         else:
             return ClonableArray._getitem(self, i)
 
+    def _require_mutable(self):
+        """
+        Check that ``self`` is mutable and clear the ``_node_number`` parameter.
+
+        The mutation could affect a precomputed ``_node_number``,
+        and so we clear this when this is called, which is done in
+        preparation for mutating the tree.
+
+        Values cleared:
+
+        - ``_node_number`` : number of nodes in the tree
+
+        EXAMPLES::
+
+            sage: T = OrderedTree()
+            sage: T._require_mutable()
+            Traceback (most recent call last):
+            ...
+            ValueError: object is immutable; please change a copy instead.
+
+        ::
+
+            sage: T = LabelledRootedTree([]).clone()
+            sage: T.node_number()
+            1
+            sage: T._require_mutable()
+            sage: hasattr(T, '_node_number')
+            False
+        """
+        super()._require_mutable()
+        try:
+            delattr(self, '_node_number')
+        except AttributeError:
+            pass
+
 
 class AbstractLabelledTree(AbstractTree):
     """

src/sage/combinat/binary_tree.py

@@ -822,12 +822,23 @@ def canonical_labelling(self, shift=1):
         r"""
         Return a labelled version of ``self``.
 
-        The canonical labelling of a binary tree is a certain labelling of the
-        nodes (not the leaves) of the tree.
-        The actual canonical labelling is currently unspecified. However, it
-        is guaranteed to have labels in `1...n` where `n` is the number of
-        nodes of the tree. Moreover, two (unlabelled) trees compare as equal if
-        and only if their canonical labelled trees compare as equal.
+        The actual canonical labelling is currently unspecified. However,
+        currently we use the labelling of the internal nodes (not the leaves)
+        of the tree given by the in-order, i.e., the order defined recursively
+        using the rule that, for each node `u`, its descendants in the left
+        (resp. right) subtree comes before (resp. after) `u`.
+
+        Under any future changes, we guarantee that the labels by default is
+        from `1` to `n`, with `n` the number of nodes of the tree. The smallest
+        labeling is adjustable using the parameter ``shift``. Moreover, we
+        guarantee that two (unlabelled) trees compare as equal if and only if
+        their canonical labelled trees compare as equal.
+
+        The runtime of this method is linear in the number of nodes.
+
+        INPUT:
+
+        - ``shift`` -- integer (optional); the smallest label in the tree labelling
 
         EXAMPLES::
 
@@ -838,14 +849,17 @@ def canonical_labelling(self, shift=1):
             sage: BinaryTree([[[], [[], None]], [[], []]]).canonical_labelling()
             5[2[1[., .], 4[3[., .], .]], 7[6[., .], 8[., .]]]
         """
-        LTR = self.parent().labelled_trees()
-        if self:
-            sz0 = self[0].node_number()
-            return LTR([self[0].canonical_labelling(shift),
-                        self[1].canonical_labelling(shift + 1 + sz0)],
-                       label=shift + sz0)
-        else:
-            return LTR(None)
+        def aux(tree, LTR, curlabel):
+            if not tree:
+                return LTR(None)
+            ltree = aux(tree[0], LTR, curlabel)
+            mylabel = curlabel[0]
+            curlabel[0] += 1
+            rtree = aux(tree[1], LTR, curlabel)
+            newtree = LTR([ltree, rtree], label=mylabel)
+            return newtree
+
+        return aux(self, self.parent().labelled_trees(), [shift])
 
     def show(self, with_leaves=False):
         """