GBNP: Full docstrings for internal functions.

src/sage/algebras/gbnp.py

@@ -190,8 +190,36 @@
 
 def _sage2gap(elem, gap_alg, s2g):
     """
-    Given an element in the free algebra, translates it into a GAP element.
-    Return value: the GAP element.
+    Convert an element of a free algebra into a GAP element by generators.
+
+    This is an internal function.
+
+    INPUT:
+
+    - ``elem`` -- an element of a Sage free algebra over some field
+
+    - ``gap_alg`` -- an algebra which is a GAP element
+
+    - ``s2g`` -- a mapping of the *monoid generators* of the free algebra to the
+      generators of ``gap_alg``
+
+    OUTPUT:
+
+    A ``GapElement`` which is a non-commutative polynomial representing
+    ``elem``.
+
+    EXAMPLES::
+
+        sage: from sage.algebras.gbnp import _sage2gap, _gap2sage
+        sage: A.<sa, sb> = FreeAlgebra(QQ)
+        sage: msa, msb = A.monoid().gens()
+        sage: elem = 3*sa^2 + 2/5*sb*sa*sb
+        sage: GapA = libgap.FreeAssociativeAlgebraWithOne(libgap(QQ), ["a", "b"])
+        sage: ga, gb = GapA.GeneratorsOfAlgebraWithOne()
+        sage: gap_elem = _sage2gap(elem, GapA, {msa: ga, msb: gb}); gap_elem
+        (3)*a^2+(2/5)*b*a*b
+        sage: _gap2sage(libgap.GP2NP(gap_elem), A) == elem    # optional - gbnp
+        True
     """
     gap_elem = gap_alg.ZeroImmutable()
     if not elem.is_zero():
@@ -207,8 +235,41 @@ def _sage2gap(elem, gap_alg, s2g):
 
 def _gap2sage(gap_l, sage_alg):
     """
-    Given a GAP element, translates it into an element in the free algebra.
-    Return value: the sage element.
+    Convert a GBNP non-commutative polynomial to an element of a Sage algebra.
+
+    This is an internal function.
+
+    INPUT:
+
+    - ``gap_l`` -- a ``GapElement`` which is in GBNP's non-commutative
+      polynomial (NP) format. It is a list of two lists of the same length. The
+      first of the two lists encodes the monomials, and the second list holds
+      the coefficients of the base field. See the `GBNP
+      documentation<https://gap-packages.github.io/gbnp/doc/chap2.html#X7FDF3E5E7F33D3A2>`_
+      for the full description of the NP format.
+
+    - ``sage_alg`` -- a Sage algebra, such as the free algebra. It needs to be
+      generated by at least the number of generators of the algebra of
+      ``elem``
+
+    EXAMPLES::
+
+        sage: from sage.algebras.gbnp import _sage2gap, _gap2sage
+        sage: F = GF(5)
+        sage: gap_elem = [[[2, 1, 2], [1, 1]], [libgap(F(3)), libgap(F(2))]]
+        sage: A.<a, b> = FreeAlgebra(GF(5))
+        sage: elem = _gap2sage(gap_elem, A); elem
+        2*a^2 + 3*b*a*b
+
+    TESTS::
+
+        sage: GapA = libgap.FreeAssociativeAlgebraWithOne(libgap(F), ["a", "b"])
+        sage: ga, gb = GapA.GeneratorsOfAlgebraWithOne()
+        sage: ma, mb = A.monoid().gens()
+        sage: f1 = _sage2gap(elem, GapA, {ma: ga, mb: gb})
+        sage: f2 = libgap.NP2GP(gap_elem, GapA)   # optional - gbnp
+        sage: _gap2sage(libgap.GP2NP(f1 - f2), A)   # optional - gbnp
+        0
     """
     sage_gens = sage_alg.gens()
     sage_elem = sage_alg.zero()
@@ -260,7 +321,7 @@ def __init__(self, *args, **kwds):
         self._gap_algebra = libgap.FreeAssociativeAlgebraWithOne(libgap(sage_alg.base_ring()),
                                         *[str(t) for t in sage_alg_gens])
 
-        gap_gens = list(libgap.GeneratorsOfAlgebra(self._gap_algebra))[1:]
+        gap_gens = libgap.GeneratorsOfAlgebraWithOne(self._gap_algebra)
         self._s2g = dict(zip(sage_alg_gens, gap_gens))
         self._gap_rels = libgap.GP2NPList([_sage2gap(x, self._gap_algebra, self._s2g) for x in self.gens()])
 
@@ -438,7 +499,7 @@ def __init__(self, R, I, names=None, category=None):
         self._gap_algebra = libgap.FreeAssociativeAlgebraWithOne(libgap(self.base_ring()),
                                 *[str(t) for t in sage_alg_gens])
 
-        gap_gens = list(libgap.GeneratorsOfAlgebra(self._gap_algebra))[1:]
+        gap_gens = libgap.GeneratorsOfAlgebraWithOne(self._gap_algebra)
         self._s2g = dict(zip(sage_alg_gens, gap_gens))
 
         sage_ideal = self.defining_ideal()