sagemathgh-38887: libbraiding version bump
    
Fixes sagemath#38886 by updating libbraiding package and adding new methods to
braids.


### 📝 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

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - sagemath#12345: short description why this is a dependency -->
<!-- - sagemath#34567: ... -->
    
URL: sagemath#38887
Reported by: miguelmarco
Reviewer(s): Enrique Manuel Artal Bartolo, Travis Scrimshaw

build/pkgs/libbraiding/checksums.ini

@@ -1,4 +1,4 @@
 tarball=libbraiding-VERSION-actually-VERSION.tar.gz
-sha1=b7e13778784fe1e36e7c0cbd7a4c234a090cd1b2
-sha256=73087d1145ace719eafeda1db1c28b5fe1c981b7e784dc59f2b1d6fc4ff75f80
+sha1=8c22d5d396e2c4d2dd032172589042933b651108
+sha256=d1738c3ad64a90ca0ad968d2e3c9069b0de08abcf37fb44a151a229d88203950
 upstream_url=https://github.com/miguelmarco/libbraiding/releases/download/VERSION/libbraiding-VERSION.tar.gz

build/pkgs/libbraiding/package-version.txt

@@ -1 +1 @@
-1.2
+1.3.1

build/pkgs/libbraiding/spkg-configure.m4

@@ -1,50 +1,9 @@
 SAGE_SPKG_CONFIGURE([libbraiding], [
-  # Since libbraiding is a C++ library with no pkg-config file,
-  # the best we can do here is compile and run a test program
-  # linked against it.
-  AC_LANG_PUSH(C++)
-  SAVED_LIBS=$LIBS
-  LIBS="$LIBS -lbraiding"
-  AC_MSG_CHECKING([if we can link against libbraiding])
-  AC_RUN_IFELSE([
-    AC_LANG_PROGRAM([
-      #include <braiding.h>
-      #include <list>
-      using namespace Braiding;
-    ],[
-      // Mimic BraidGroup(2)([1,1]).thurston_type() in SageMath.
-      // thurstontype == 1 corresponds to "periodic"
-      if (thurstontype(2, {1,1}) == 1) { return 0; } else { return 1; }
-    ])
-  ],
-  [
-    AC_MSG_RESULT([yes])
+  PKG_CHECK_MODULES([libbraiding], [libbraiding >= 1.3.1], [
+    AC_MSG_RESULT([found libbraiding >= 1.3.1, will use installed version])
     sage_spkg_install_libbraiding=no
-  ],
-  [
-    AC_MSG_RESULT([no])
-    sage_spkg_install_libbraiding=yes
   ],[
-    AC_LINK_IFELSE([
-      AC_LANG_PROGRAM([
-        #include <braiding.h>
-        #include <list>
-        using namespace Braiding;
-      ],[
-        // Mimic BraidGroup(2)([1,1]).thurston_type() in SageMath.
-        // thurstontype == 1 corresponds to "periodic"
-        if (thurstontype(2, {1,1}) == 1) { return 0; } else { return 1; }
-      ])
-    ],
-    [
-      AC_MSG_RESULT([yes])
-      sage_spkg_install_libbraiding=no
-    ],
-    [
-      AC_MSG_RESULT([no])
-      sage_spkg_install_libbraiding=yes
-    ])
+    AC_MSG_RESULT([couldn't find libbraiding >= 1.3.1. It will be installed])
+    sage_spkg_install_libbraiding=yes
   ])
-  LIBS=$SAVED_LIBS
-  AC_LANG_POP
 ])

src/sage/groups/braid.py

@@ -96,7 +96,8 @@
 lazy_import('sage.libs.braiding',
             ['leftnormalform', 'rightnormalform', 'centralizer', 'supersummitset', 'greatestcommondivisor',
              'leastcommonmultiple', 'conjugatingbraid', 'ultrasummitset',
-             'thurston_type', 'rigidity', 'sliding_circuits'],
+             'thurston_type', 'rigidity', 'sliding_circuits', 'send_to_sss',
+             'send_to_uss', 'send_to_sc', 'trajectory', 'cyclic_slidings' ],
             feature=sage__libs__braiding())
 lazy_import('sage.knots.knot', 'Knot')
 
@@ -2239,6 +2240,90 @@ def colored_jones_polynomial(self, N, variab=None, try_inverse=True):
         self._cj_with_q[N] = cj.subs({q: 1/q}) if use_inverse else cj
         return self.colored_jones_polynomial(N, variab, try_inverse)
 
+    def super_summit_set_element(self):
+        r"""
+        Return an element of the braid's super summit set and the conjugating
+        braid.
+
+        EXAMPLES::
+
+            sage: B = BraidGroup(4)
+            sage: b = B([1, 2, 1, 2, 3, -1, 2, 1, 3])
+            sage: b.super_summit_set_element()
+            (s0*s2*s0*s1*s2*s1*s0, s0^-1*s1^-1*s0^-1*s2^-1*s1^-1*s0^-1*s1*s0*s2*s1*s0)
+        """
+        to_sss = send_to_sss(self)
+        B = self.parent()
+        return tuple([B._element_from_libbraiding(b) for b in to_sss])
+
+    def ultra_summit_set_element(self):
+        r"""
+        Return an element of the braid's ultra summit set and the conjugating
+        braid.
+
+        EXAMPLES::
+
+            sage: B = BraidGroup(4)
+            sage: b = B([1, 2, 1, 2, 3, -1, 2, -1, 3])
+            sage: b.ultra_summit_set_element()
+            (s0*s1*s0*s2*s1, s0^-1*s1^-1*s0^-1*s2^-1*s1^-1*s0^-1*s1*s2*s1^2*s0)
+        """
+        to_uss = send_to_uss(self)
+        B = self.parent()
+        return tuple([B._element_from_libbraiding(b) for b in to_uss])
+
+    def sliding_circuits_element(self):
+        r"""
+        Return an element of the braid's sliding circuits, and the conjugating
+        braid.
+
+        EXAMPLES::
+
+            sage: B = BraidGroup(4)
+            sage: b = B([1, 2, 1, 2, 3, -1, 2, -1, 3])
+            sage: b.sliding_circuits_element()
+            (s0*s1*s0*s2*s1, s0^2*s1*s2)
+        """
+        to_sc = send_to_sc(self)
+        B = self.parent()
+        return tuple([B._element_from_libbraiding(b) for b in to_sc])
+
+    def trajectory(self):
+        r"""
+        Return the braid's trajectory.
+
+        EXAMPLES::
+
+            sage: B = BraidGroup(4)
+            sage: b = B([1, 2, 1, 2, 3, -1, 2, -1, 3])
+            sage: b.trajectory()
+            [s0^-1*s1^-1*s0^-1*s2^-1*s1^-1*s2*s0*s1*s2*s1*s0^2*s1*s2^2,
+             s0*s1*s2^3,
+             s0*s1*s2*s1^2,
+             s0*s1*s0*s2*s1]
+        """
+        traj = trajectory(self)
+        B = self.parent()
+        return [B._element_from_libbraiding(b) for b in traj]
+
+    def cyclic_slidings(self):
+        r"""
+        Return the braid's cyclic slidings.
+
+        OUTPUT: The braid's cyclic slidings. Each cyclic sliding is a list of braids.
+
+        EXAMPLES::
+
+            sage: B = BraidGroup(4)
+            sage: b = B([1, 2, 1, 2, 3, -1, 2, 1])
+            sage: b.cyclic_slidings()
+            [[s0*s2*s1*s0*s1*s2, s0*s1*s2*s1*s0^2, s1*s0*s2^2*s1*s0],
+             [s0*s1*s2*s1^2*s0, s0*s1*s2*s1*s0*s2, s1*s0*s2*s0*s1*s2]]
+        """
+        cs = cyclic_slidings(self)
+        B = self.parent()
+        return [[B._element_from_libbraiding(b) for b in t] for t in cs]
+
 
 class RightQuantumWord:
     """

src/sage/libs/braiding.pyx

@@ -41,6 +41,11 @@ cdef extern from "braiding.h" namespace "Braiding":
     int thurstontype(int n, list[int] word)
     int Rigidity_ext(int n, list[int] word)
     list[list[list[list[int]]]] SlidingCircuits(int n, list[int] word)
+    list[list[list[int]]] SendToSSS(int n, list[int] word)
+    list[list[list[int]]] SendToUSS(int n, list[int] word)
+    list[list[list[int]]] SendToSC(int n, list[int] word)
+    list[list[list[int]]] Trajectory(int n, list[int] word)
+    list[list[list[list[int]]]] CyclicSlidings(int n, list[int] word)
 
 
 def conjugatingbraid(braid1, braid2):
@@ -383,3 +388,161 @@ def sliding_circuits(braid):
     cdef list[list[list[list[int]]]] rop = SlidingCircuits(nstrands, l)
     sig_off()
     return rop
+
+
+def send_to_sss(braid):
+    r"""
+    Return an element of the braid's super summit set and the conjugating braid.
+
+    INPUT:
+
+    - ``braid`` -- a braid
+
+    OUTPUT:
+
+    A list with two braids, the first one is an element of ``braid`` super summit
+    set, the second one is the corresponding conjugating braid.
+
+    EXAMPLES::
+
+        sage: from sage.libs.braiding import send_to_sss
+        sage: B = BraidGroup(4)
+        sage: d = B([1, 2, 1, 2, 3, -1, 2,- 3])
+        sage: send_to_sss(d)
+        [[[0], [1, 2, 1, 3]], [[-1], [1, 2, 3, 2]]]
+
+    """
+    nstrands = braid.parent().strands()
+    l = braid.Tietze()
+    sig_on()
+    cdef list[list[list[int]]] rop = SendToSSS(nstrands, l)
+    sig_off()
+    return rop
+
+
+def send_to_uss(braid):
+    r"""
+    Return an element of the braid's ultra summit set and the conjugating braid.
+
+    INPUT:
+
+    - ``braid`` -- a braid
+
+    OUTPUT:
+
+    A list with two braids, the first one is an element of ``braid`` ultra summit
+    set, the second one is the corresponding conjugating braid.
+
+    EXAMPLES::
+
+        sage: from sage.libs.braiding import send_to_uss
+        sage: B = BraidGroup(4)
+        sage: d = B([1, 2, 1, 2, 3, -1, 2,- 1])
+        sage: send_to_uss(d)
+        [[[0], [1, 2, 3, 2]], [[0], [1]]]
+
+    """
+    nstrands = braid.parent().strands()
+    l = braid.Tietze()
+    sig_on()
+    cdef list[list[list[int]]] rop = SendToUSS(nstrands, l)
+    sig_off()
+    return rop
+
+
+def send_to_sc(braid):
+    r"""
+    Return an element of the braid's sliding circuits and the conjugating braid.
+
+    INPUT:
+
+    - ``braid`` -- a braid
+
+    OUTPUT:
+
+    A list with two braids, the first one is an element of ``braid`` sliding
+    circuits, the second one is the corresponding conjugating braid.
+
+    EXAMPLES::
+
+        sage: from sage.libs.braiding import send_to_sc
+        sage: B = BraidGroup(4)
+        sage: d = B([1, 2, 1, 2, 3, -1, 2, 2])
+        sage: send_to_sc(d)
+        [[[0], [1, 2, 3, 2], [2, 1]], [[0], [1]]]
+
+
+    """
+    nstrands = braid.parent().strands()
+    l = braid.Tietze()
+    sig_on()
+    cdef list[list[list[int]]] rop = SendToSC(nstrands, l)
+    sig_off()
+    return rop
+
+
+def trajectory(braid):
+    r"""
+    Return the braid's trajectory.
+
+    INPUT:
+
+    - ``braid`` -- a braid
+
+    OUTPUT:
+
+    A list of braids, formed by the ``braid```trajectory.
+
+    EXAMPLES::
+
+        sage: from sage.libs.braiding import trajectory
+        sage: B = BraidGroup(4)
+        sage: d = B([1, 2, 1, 2, 3, -1, 2, 2])
+        sage: trajectory(d)
+        [[[0], [1, 3], [1, 2, 3, 2]],
+         [[0], [1, 2, 3, 2, 1], [3]],
+         [[0], [1, 2, 3, 2], [2, 1]],
+         [[0], [2, 1, 3], [1, 2, 3]]]
+
+
+    """
+    nstrands = braid.parent().strands()
+    l = braid.Tietze()
+    sig_on()
+    cdef list[list[list[int]]] rop = Trajectory(nstrands, l)
+    sig_off()
+    return rop
+
+
+def cyclic_slidings(braid):
+    r"""
+    Return the cyclic slidings of the braid.
+
+    INPUT:
+
+    - ``braid`` -- a braid
+
+    OUTPUT:
+
+    A list of lists of braids, given by the input's cyclic slidings.
+
+    EXAMPLES::
+
+        sage: from sage.libs.braiding import cyclic_slidings
+        sage: B = BraidGroup(4)
+        sage: d = B([1, 2, 1, 2, 3, -1, 2, 2])
+        sage: cyclic_slidings(d)
+        [[[[0], [1, 2, 3, 2], [2, 1]],
+          [[0], [1, 2, 3, 2, 1], [3]],
+          [[0], [2, 1, 3], [1, 2, 3]]],
+         [[[0], [1, 3, 2, 1], [2, 3]],
+          [[0], [1, 2, 3, 2, 1], [1]],
+          [[0], [2, 1, 3], [3, 2, 1]]]]
+
+    """
+    nstrands = braid.parent().strands()
+    l = braid.Tietze()
+    sig_on()
+    cdef list[list[list[list[int]]]] rop = CyclicSlidings(nstrands, l)
+    sig_off()
+    return rop