Ticket #7797: trac7797-full_letterplace_wrapper_combined.patch

doc/en/reference/algebras.rst

@@ -9 +9 @@
    sage/algebras/free_algebra
    sage/algebras/free_algebra_element
 
+   sage/algebras/letterplace/free_algebra_letterplace
+   sage/algebras/letterplace/free_algebra_element_letterplace
+   sage/algebras/letterplace/letterplace_ideal
+
    sage/algebras/free_algebra_quotient
    sage/algebras/free_algebra_quotient_element
 

module_list.py

@@ -114 +114 @@
                include_dirs = [SAGE_INC + 'FLINT/'],
                depends = flint_depends),
 
+    Extension('sage.algebras.letterplace.free_algebra_letterplace',
+              sources = ['sage/algebras/letterplace/free_algebra_letterplace.pyx'],
+              language="c++",
+              include_dirs = [SAGE_INC +'singular/'],
+              depends = singular_depends),
+
+    Extension('sage.algebras.letterplace.free_algebra_element_letterplace',
+              sources = ['sage/algebras/letterplace/free_algebra_element_letterplace.pyx'],
+              language="c++",
+              include_dirs = [SAGE_INC +'singular/'],
+              depends = singular_depends),
+
+    Extension('sage.algebras.letterplace.letterplace_ideal',
+              sources = ['sage/algebras/letterplace/letterplace_ideal.pyx'],
+              language="c++",
+              include_dirs = [SAGE_INC +'singular/'],
+              depends = singular_depends),
+
     Extension('sage.algebras.quatalg.quaternion_algebra_cython',
                sources = ['sage/algebras/quatalg/quaternion_algebra_cython.pyx'],
                language='c++',

sage/algebras/free_algebra.py

@@ -9 +9 @@
   things.
 
 - Simon King (2011-04): Put free algebras into the category framework.
+  Reimplement free algebra constructor, using a
+  :class:`~sage.structure.factory.UniqueFactory` for handling
+  different implementations of free algebras. Allow degree weights
+  for free algebras in letterplace implementation.
 
 EXAMPLES::
 
@@ -20 +24 @@
     sage: G.base_ring()
     Free Algebra on 3 generators (x, y, z) over Integer Ring
 
+The above free algebra is based on a generic implementation. By
+:trac:`7797`, there is a different implementation
+:class:`~sage.algebras.letterplace.free_algebra_letterplace.FreeAlgebra_letterplace`
+based on Singular's letterplace rings. It is currently restricted to
+weighted homogeneous elements and is therefore not the default. But the
+arithmetic is much faster than in the generic implementation.
+Moreover, we can compute Groebner bases with degree bound for its
+two-sided ideals, and thus provide ideal containment tests::
+
+    sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+    sage: F
+    Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+    sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+    sage: I.groebner_basis(degbound=4)
+    Twosided Ideal (y*z*y*y - y*z*y*z + y*z*z*y - y*z*z*z, y*z*y*x + y*z*y*z + y*z*z*x + y*z*z*z, y*y*z*y - y*y*z*z + y*z*z*y - y*z*z*z, y*y*z*x + y*y*z*z + y*z*z*x + y*z*z*z, y*y*y - y*y*z + y*z*y - y*z*z, y*y*x + y*y*z + y*z*x + y*z*z, x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+    sage: y*z*y*y*z*z + 2*y*z*y*z*z*x + y*z*y*z*z*z - y*z*z*y*z*x + y*z*z*z*z*x in I
+    True
+
+Positive integral degree weights for the letterplace implementation
+was introduced in trac ticket #...::
+
+    sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+    sage: x.degree()
+    2
+    sage: y.degree()
+    1
+    sage: z.degree()
+    3
+    sage: I = F*[x*y-y*x, x^2+2*y*z, (x*y)^2-z^2]*F
+    sage: Q.<a,b,c> = F.quo(I)
+    sage: TestSuite(Q).run()
+    sage: a^2*b^2
+    c*c
+
 TESTS::
 
     sage: F = FreeAlgebra(GF(5),3,'x')
     sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
+    sage: F = FreeAlgebra(GF(5),3,'x', implementation='letterplace')
+    sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
 
 ::
 
     sage: F.<x,y,z> = FreeAlgebra(GF(5),3)
     sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
+    sage: F.<x,y,z> = FreeAlgebra(GF(5),3, implementation='letterplace')
+    sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
 
 ::
 
     sage: F = FreeAlgebra(GF(5),3, ['xx', 'zba', 'Y'])
     sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
+    sage: F = FreeAlgebra(GF(5),3, ['xx', 'zba', 'Y'], implementation='letterplace')
+    sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
 
 ::
 
     sage: F = FreeAlgebra(GF(5),3, 'abc')
     sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
+    sage: F = FreeAlgebra(GF(5),3, 'abc', implementation='letterplace')
+    sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
 
 ::
 
-    sage: F = FreeAlgebra(FreeAlgebra(ZZ,1,'a'), 2, 'x')
+    sage: F = FreeAlgebra(FreeAlgebra(ZZ,2,'ab'), 2, 'x')
     sage: TestSuite(F).run()
+    sage: F is loads(dumps(F))
+    True
+
+Note that the letterplace implementation can only be used if the corresponding
+(multivariate) polynomial ring has an implementation in Singular::
+
+    sage: FreeAlgebra(FreeAlgebra(ZZ,2,'ab'), 2, 'x', implementation='letterplace')
+    Traceback (most recent call last):
+    ...
+    NotImplementedError: The letterplace implementation is not available for the free algebra you requested
 
 """
 
@@ -66 +138 @@
 
 import sage.structure.parent_gens
 
-def FreeAlgebra(R, n, names):
+from sage.structure.factory import UniqueFactory
+from sage.all import PolynomialRing
+from sage.rings.polynomial.multi_polynomial_libsingular import MPolynomialRing_libsingular
+
+class FreeAlgebraFactory(UniqueFactory):
     """
-    Return the free algebra over the ring `R` on `n`
-    generators with given names.
-    
-    INPUT:
-    
-    -  ``R`` - ring
-    -  ``n`` - integer
-    -  ``names`` - string or list/tuple of n strings
-    
-    OUTPUT:
-    
-    A free algebra.
-    
+    A constructor of free algebras.
+
+    See :mod:`~sage.algebras.free_algebra` for examples and corner cases.
+
     EXAMPLES::
-    
+
         sage: FreeAlgebra(GF(5),3,'x')
         Free Algebra on 3 generators (x0, x1, x2) over Finite Field of size 5
         sage: F.<x,y,z> = FreeAlgebra(GF(5),3)
@@ -105 +172 @@
         sage: G = FreeAlgebra(ZZ,3,'x,y,z')
         sage: F is G
         True
+        sage: F.<x,y,z> = FreeAlgebra(GF(5),3)  # indirect doctest
+        sage: F is loads(dumps(F))
+        True
+        sage: F is FreeAlgebra(GF(5),['x','y','z'])
+        True
+        sage: copy(F) is F is loads(dumps(F))
+        True
+        sage: TestSuite(F).run()
+
+    By :trac:`7797`, we provide a different implementation of free
+    algebras, based on Singular's "letterplace rings". Our letterplace
+    wrapper allows for chosing positive integral degree weights for the
+    generators of the free algebra. However, only (weighted) homogenous
+    elements are supported. Of course, isomorphic algebras in different
+    implementations are not identical::
+
+        sage: G = FreeAlgebra(GF(5),['x','y','z'], implementation='letterplace')
+        sage: F == G
+        False
+        sage: G is FreeAlgebra(GF(5),['x','y','z'], implementation='letterplace')
+        True
+        sage: copy(G) is G is loads(dumps(G))
+        True
+        sage: TestSuite(G).run()
+
+    ::
+
+        sage: H = FreeAlgebra(GF(5),['x','y','z'], implementation='letterplace', degrees=[1,2,3])
+        sage: F != H != G
+        True
+        sage: H is FreeAlgebra(GF(5),['x','y','z'], implementation='letterplace', degrees=[1,2,3])
+        True
+        sage: copy(H) is H is loads(dumps(H))
+        True
+        sage: TestSuite(H).run()
     
     Free algebras commute with their base ring.
     ::
@@ -122 +224 @@
         sage: c^3 * a * b^2
         a*b^2*c^3
     """
-    names = sage.structure.parent_gens.normalize_names(n, names)
-    return cache(R, n, names)
+    def create_key(self,base_ring, arg1=None, arg2=None,
+                                      sparse=False, order='degrevlex',
+                                      names=None, name=None,
+                                      implementation=None, degrees=None):
+        """
+        Create the key under which a free algebra is stored.
+
+        TESTS::
+
+            sage: FreeAlgebra.create_key(GF(5),['x','y','z'])
+            (Finite Field of size 5, ('x', 'y', 'z'))
+            sage: FreeAlgebra.create_key(GF(5),['x','y','z'],3)
+            (Finite Field of size 5, ('x', 'y', 'z'))
+            sage: FreeAlgebra.create_key(GF(5),3,'xyz')
+            (Finite Field of size 5, ('x', 'y', 'z'))
+            sage: FreeAlgebra.create_key(GF(5),['x','y','z'], implementation='letterplace')
+            (Multivariate Polynomial Ring in x, y, z over Finite Field of size 5,)
+            sage: FreeAlgebra.create_key(GF(5),['x','y','z'],3, implementation='letterplace')
+            (Multivariate Polynomial Ring in x, y, z over Finite Field of size 5,)
+            sage: FreeAlgebra.create_key(GF(5),3,'xyz', implementation='letterplace')
+            (Multivariate Polynomial Ring in x, y, z over Finite Field of size 5,)
+            sage: FreeAlgebra.create_key(GF(5),3,'xyz', implementation='letterplace', degrees=[1,2,3])
+            ((1, 2, 3), Multivariate Polynomial Ring in x, y, z, x_ over Finite Field of size 5)
+
+        """
+        if arg1 is None and arg2 is None and names is None:
+            # this is used for pickling
+            if degrees is None:
+                return (base_ring,)
+            return tuple(degrees),base_ring
+        PolRing = None
+        # test if we can use libSingular/letterplace
+        if implementation is not None and implementation != 'generic':
+            try:
+                PolRing = PolynomialRing(base_ring, arg1, arg2,
+                                   sparse=sparse, order=order,
+                                   names=names, name=name,
+                                   implementation=implementation if implementation!='letterplace' else None)
+                if not isinstance(PolRing,MPolynomialRing_libsingular):
+                    if PolRing.ngens() == 1:
+                        PolRing = PolynomialRing(base_ring,1,PolRing.variable_names())
+                        if not isinstance(PolRing,MPolynomialRing_libsingular):
+                            raise TypeError
+                    else:
+                        raise TypeError
+            except (TypeError, NotImplementedError),msg:
+                raise NotImplementedError, "The letterplace implementation is not available for the free algebra you requested"
+        if PolRing is not None:
+            if degrees is None:
+                return (PolRing,)
+            from sage.all import TermOrder
+            T = PolRing.term_order()+TermOrder('lex',1)
+            varnames = list(PolRing.variable_names())
+            newname = 'x'
+            while newname in varnames:
+                newname += '_'
+            varnames.append(newname)
+            return tuple(degrees),PolynomialRing(PolRing.base(), varnames,
+                    sparse=sparse, order=T,
+                    implementation=implementation if implementation!='letterplace'  else None)
+        # normalise the generator names
+        from sage.all import Integer
+        if isinstance(arg1, (int, long, Integer)):
+            arg1, arg2 = arg2, arg1
+        if not names is None:
+            arg1 = names
+        elif not name is None:
+            arg1 = name
+        if arg2 is None:
+            arg2 = len(arg1)
+        names = sage.structure.parent_gens.normalize_names(arg2,arg1)
+        return base_ring, names
+
+    def create_object(self, version, key):
+        """
+        Construct the free algebra that belongs to a unique key.
+
+        NOTE:
+
+        Of course, that method should not be called directly,
+        since it does not use the cache of free algebras.
+
+        TESTS::
+
+            sage: FreeAlgebra.create_object('4.7.1', (QQ['x','y'],))
+            Free Associative Unital Algebra on 2 generators (x, y) over Rational Field
+            sage: FreeAlgebra.create_object('4.7.1', (QQ['x','y'],)) is FreeAlgebra(QQ,['x','y'])
+            False
+
+        """
+        if len(key)==1:
+            from sage.algebras.letterplace.free_algebra_letterplace import FreeAlgebra_letterplace
+            return FreeAlgebra_letterplace(key[0])
+        if isinstance(key[0],tuple):
+            from sage.algebras.letterplace.free_algebra_letterplace import FreeAlgebra_letterplace
+            return FreeAlgebra_letterplace(key[1],degrees=key[0])
+        return FreeAlgebra_generic(key[0],len(key[1]),key[1])
+
+FreeAlgebra = FreeAlgebraFactory('FreeAlgebra')
+
 
 def is_FreeAlgebra(x):
     """
@@ -138 +338 @@
         False
         sage: is_FreeAlgebra(FreeAlgebra(ZZ,100,'x'))
         True
+        sage: is_FreeAlgebra(FreeAlgebra(ZZ,10,'x',implementation='letterplace'))
+        True
+        sage: is_FreeAlgebra(FreeAlgebra(ZZ,10,'x',implementation='letterplace', degrees=range(1,11)))
+        True
+
     """
-    return isinstance(x, FreeAlgebra_generic)
+    from sage.algebras.letterplace.free_algebra_letterplace import FreeAlgebra_letterplace
+    return isinstance(x, (FreeAlgebra_generic,FreeAlgebra_letterplace))
 
 
 class FreeAlgebra_generic(Algebra):
@@ -158 +364 @@
         x*y*x*y*x*y*x*y*x*y*x*y + x*y*z*x*y*z*x*y*z*x*y*z
         sage: (2 + x*z + x^2)^2 + (x - y)^2
         4 + 5*x^2 - x*y + 4*x*z - y*x + y^2 + x^4 + x^3*z + x*z*x^2 + x*z*x*z
+
+    TESTS:
+
+    Free algebras commute with their base ring.
+    ::
+
+        sage: K.<a,b> = FreeAlgebra(QQ)
+        sage: K.is_commutative()
+        False
+        sage: L.<c,d> = FreeAlgebra(K)
+        sage: L.is_commutative()
+        False
+        sage: s = a*b^2 * c^3; s
+        a*b^2*c^3
+        sage: parent(s)
+        Free Algebra on 2 generators (c, d) over Free Algebra on 2 generators (a, b) over Rational Field
+        sage: c^3 * a * b^2
+        a*b^2*c^3
+
     """
     Element = FreeAlgebraElement
     def __init__(self, R, n, names):
@@ -174 +399 @@
     
             sage: F.<x,y,z> = FreeAlgebra(QQ, 3); F # indirect doctet
             Free Algebra on 3 generators (x, y, z) over Rational Field
+
+        TEST:
+
+        Note that the following is *not* the recommended way to create
+        a free algebra.
+        ::
+
+            sage: from sage.algebras.free_algebra import FreeAlgebra_generic
+            sage: FreeAlgebra_generic(ZZ,3,'abc')
+            Free Algebra on 3 generators (a, b, c) over Integer Ring
+
         """
         if not isinstance(R, Ring):
             raise TypeError("Argument R must be a ring.")
@@ -218 +454 @@
     def __cmp__(self, other):
         """
         Two free algebras are considered the same if they have the same
-        base ring, number of generators and variable names.
+        base ring, number of generators and variable names, and the same
+        implementation.
         
         EXAMPLES::
         
@@ -233 +470 @@
             False
             sage: F == FreeAlgebra(QQ,3,'y')
             False
+
+        Note that since :trac:`7797` there is a different
+        implementation of free algebras. Two corresponding free
+        algebras in different implementations are not equal, but there
+        is a coercion::
+
+
         """
         if not isinstance(other, FreeAlgebra_generic):
             return -1
         c = cmp(self.base_ring(), other.base_ring())
         if c: return c
-        c = cmp(self.__ngens, other.__ngens)
+        c = cmp(self.__ngens, other.ngens())
         if c: return c
         c = cmp(self.variable_names(), other.variable_names())
         if c: return c
@@ -251 +495 @@
         EXAMPLES::
         
             sage: F = FreeAlgebra(QQ,3,'x')
-            sage: print F  # indirect doctest
+            sage: F  # indirect doctest
             Free Algebra on 3 generators (x0, x1, x2) over Rational Field
             sage: F.rename('QQ<<x0,x1,x2>>')
-            sage: print F #indirect doctest
+            sage: F #indirect doctest
             QQ<<x0,x1,x2>>
             sage: FreeAlgebra(ZZ,1,['a'])
             Free Algebra on 1 generators (a,) over Integer Ring
@@ -264 +508 @@
 
     def _element_constructor_(self, x):
         """
-       Coerce x into self.
+       Convert x into self.
        
        EXAMPLES::
        
            sage: R.<x,y> = FreeAlgebra(QQ,2)
            sage: R(3) # indirect doctest
            3
+
+       TESTS::
+
+           sage: F.<x,y,z> = FreeAlgebra(GF(5),3)
+           sage: L.<x,y,z> = FreeAlgebra(ZZ,3,implementation='letterplace')
+           sage: F(x)     # indirect doctest
+           x
+           sage: F.1*L.2
+           y*z
+           sage: (F.1*L.2).parent() is F
+           True
+
+       ::
+
+           sage: K.<z> = GF(25)
+           sage: F.<a,b,c> = FreeAlgebra(K,3)
+           sage: L.<a,b,c> = FreeAlgebra(K,3, implementation='letterplace')
+           sage: F.1+(z+1)*L.2
+           b + (z+1)*c
+
        """
         if isinstance(x, FreeAlgebraElement):
             P = x.parent()
@@ -278 +542 @@
                 return x
             if not (P is self.base_ring()):
                 return self.element_class(self, x)
+        elif hasattr(x,'letterplace_polynomial'):
+            P = x.parent()
+            if self.has_coerce_map_from(P): # letterplace versus generic
+                ngens = P.ngens()
+                M = self.__monoid
+                def exp_to_monomial(T):
+                    out = []
+                    for i in xrange(len(T)):
+                        if T[i]:
+                            out.append((i%ngens,T[i]))
+                    return M(out)
+                return self.element_class(self, dict([(exp_to_monomial(T),c) for T,c in x.letterplace_polynomial().dict().iteritems()]))
         # ok, not a free algebra element (or should not be viewed as one).
+        if isinstance(x, basestring):
+            from sage.all import sage_eval
+            return sage_eval(x,locals=self.gens_dict())
         F = self.__monoid
         R = self.base_ring()
         # coercion from free monoid
@@ -299 +578 @@
 
         - this free algebra
 
+        - a free algebra in letterplace implementation that has
+          the same generator names and whose base ring coerces
+          into self's base ring
+
         - the underlying monoid
 
         - anything that coerces to the base ring of this free algebra
@@ -366 +649 @@
             TypeError: no canonical coercion from Free Algebra on 3 generators
             (x, y, z) over Finite Field of size 7 to Free Algebra on 3
             generators (x, y, z) over Integer Ring
+
+        TESTS::
+
+           sage: F.<x,y,z> = FreeAlgebra(GF(5),3)
+           sage: L.<x,y,z> = FreeAlgebra(GF(5),3,implementation='letterplace')
+           sage: F(x)
+           x
+           sage: F.1*L.2     # indirect doctest
+           y*z
+
         """
         try:
             R = x.parent()
@@ -419 +712 @@
             True
             sage: F.has_coerce_map_from(PolynomialRing(ZZ, 3, 'x,y,z'))
             False
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K,3)
+            sage: L.<a,b,c> = FreeAlgebra(K,3, implementation='letterplace')
+            sage: F.1+(z+1)*L.2      # indirect doctest
+            b + (z+1)*c
+
         """
         if self.__monoid.has_coerce_map_from(R):
             return True

sage/algebras/free_algebra_element.py

@@ -78 +78 @@
         EXAMPLES::
         
             sage: A.<x,y,z>=FreeAlgebra(ZZ,3)
-            sage: repr(-x+3*y*z)
+            sage: repr(-x+3*y*z)    # indirect doctest
             '-x + 3*y*z'
 
         Trac ticket #11068 enables the use of local variable names::
@@ -105 +105 @@
         EXAMPLES::
         
             sage: A.<x,y,z>=FreeAlgebra(ZZ,3)
-            sage: latex(-x+3*y^20*z)
+            sage: latex(-x+3*y^20*z)   # indirect doctest
             \left(-1\right)x + 3y^{20}z
             sage: alpha,beta,gamma=FreeAlgebra(ZZ,3,'alpha,beta,gamma').gens()
             sage: latex(alpha-beta)
@@ -197 +197 @@
         EXAMPLES::
         
             sage: R.<x,y> = FreeAlgebra(QQ,2)
-            sage: x + y
+            sage: x + y    # indirect doctest
             x + y
         """
         A = self.parent()
@@ -234 +234 @@
         EXAMPLES::
         
             sage: R.<x,y> = FreeAlgebra(QQ,2)
-            sage: -(x+y)
+            sage: -(x+y)    # indirect doctest
             -x - y
         """
         y = self.parent()(0)
@@ -252 +252 @@
         EXAMPLES::
         
             sage: R.<x,y> = FreeAlgebra(QQ,2)
-            sage: x - y
+            sage: x - y    # indirect doctest
             x - y
         """
         A = self.parent()
@@ -290 +290 @@
         EXAMPLES::
         
             sage: A.<x,y,z>=FreeAlgebra(ZZ,3)
-            sage: (x+y+x*y)*(x+y+1)
+            sage: (x+y+x*y)*(x+y+1)    # indirect doctest
             x + y + x^2 + 2*x*y + y*x + y^2 + x*y*x + x*y^2
         """
         A = self.parent()

sage/algebras/free_algebra_quotient.py

@@ -1 +1 @@
 """
-Free algebra quotients
+Finite dimensional free algebra quotients
+
+REMARK:
+
+This implementation only works for finite dimensional quotients, since
+a list of basis monomials and the multiplication matrices need to be
+explicitly provided.
+
+The homogeneous part of a quotient of a free algebra over a field by a
+finitely generated homogeneous twosided ideal is available in a
+different implementation. See
+:mod:`~sage.algebras.letterplace.free_algebra_letterplace` and
+:mod:`~sage.rings.quotient_ring`.
 
 TESTS::
 

new file sage/algebras/letterplace/__init__.py

@@ +1 @@
+# tell Python that letterplace exists

new file sage/algebras/letterplace/free_algebra_element_letterplace.pxd

@@ +1 @@
+###############################################################################
+#
+#       Copyright (C) 2011 Simon King <simon.king@uni-jena.de>
+#  Distributed under the terms of the GNU General Public License (GPL),
+#  version 2 or any later version.  The full text of the GPL is available at:
+#                  http://www.gnu.org/licenses/
+#
+###############################################################################
+
+cdef class FreeAlgebraElement_letterplace
+
+from sage.structure.element cimport AlgebraElement, ModuleElement, RingElement, Element
+from sage.rings.polynomial.multi_polynomial_libsingular cimport MPolynomialRing_libsingular, MPolynomial_libsingular
+from sage.algebras.letterplace.free_algebra_letterplace cimport FreeAlgebra_letterplace
+include "../../ext/stdsage.pxi"
+
+cdef class FreeAlgebraElement_letterplace(AlgebraElement):
+    cdef MPolynomial_libsingular _poly
+

new file sage/algebras/letterplace/free_algebra_element_letterplace.pyx

@@ +1 @@
+###############################################################################
+#
+#       Copyright (C) 2011 Simon King <simon.king@uni-jena.de>
+#  Distributed under the terms of the GNU General Public License (GPL),
+#  version 2 or any later version.  The full text of the GPL is available at:
+#                  http://www.gnu.org/licenses/
+#
+###############################################################################
+
+"""
+Weighted homogeneous elements of free algebras, in letterplace implementation.
+
+AUTHOR:
+
+- Simon King (2011-03-23): Trac ticket :trac:`7797`
+
+"""
+
+from sage.libs.singular.function import lib, singular_function
+from sage.misc.misc import repr_lincomb
+from sage.rings.polynomial.multi_polynomial_ideal import MPolynomialIdeal
+
+# Define some singular functions
+lib("freegb.lib")
+poly_reduce = singular_function("NF")
+singular_system=singular_function("system")
+
+#####################
+# Free algebra elements
+cdef class FreeAlgebraElement_letterplace(AlgebraElement):
+    """
+    Weighted homogeneous elements of a free associative unital algebra (letterplace implementation)
+
+    EXAMPLES::
+
+        sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+        sage: x+y
+        x + y
+        sage: x*y !=y*x
+        True
+        sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+        sage: (y^3).reduce(I)
+        y*y*y
+        sage: (y^3).normal_form(I)
+        y*y*z - y*z*y + y*z*z
+
+    Here is an example with nontrivial degree weights::
+
+        sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+        sage: I = F*[x*y-y*x, x^2+2*y*z, (x*y)^2-z^2]*F
+        sage: x.degree()
+        2
+        sage: y.degree()
+        1
+        sage: z.degree()
+        3
+        sage: (x*y)^3
+        x*y*x*y*x*y
+        sage: ((x*y)^3).normal_form(I)
+        z*z*y*x
+        sage: ((x*y)^3).degree()
+        9
+
+    """
+    def __init__(self, A, x, check=True):
+        """
+        INPUT:
+
+        - A free associative unital algebra in letterplace implementation, `A`.
+        - A homogeneous polynomial that can be coerced into the currently
+          used polynomial ring of `A`.
+        - ``check`` (optional bool, default ``True``): Do not attempt the
+          above coercion (for internal use only).
+
+        TEST::
+
+            sage: from sage.algebras.letterplace.free_algebra_element_letterplace import FreeAlgebraElement_letterplace
+            sage: F.<x,y,z> = FreeAlgebra(GF(3), implementation='letterplace')
+            sage: F.set_degbound(2)
+            sage: P = F.current_ring()
+            sage: F.set_degbound(4)
+            sage: P == F.current_ring()
+            False
+            sage: p = FreeAlgebraElement_letterplace(F,P.1*P.3+2*P.0*P.4); p
+            -x*y + y*x
+            sage: loads(dumps(p)) == p
+            True
+
+        """
+        cdef FreeAlgebra_letterplace P = A
+        if check:
+            if not x.is_homogeneous():
+                raise ValueError, "Free algebras based on Letterplace can currently only work with weighted homogeneous elements"
+            P.set_degbound(x.degree())
+            x = P._current_ring(x)
+        AlgebraElement.__init__(self,P)
+        self._poly = x
+    def __reduce__(self):
+        """
+        Pickling.
+
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: loads(dumps(x*y*x)) == x*y*x   # indirect doctest
+            True
+
+        """
+        return self.__class__, (self._parent,self._poly)
+    def __copy__(self):
+        """
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: copy(x*y*z+z*y*x) == x*y*z+z*y*x   # indirect doctest
+            True
+
+        """
+        self._poly = (<FreeAlgebra_letterplace>self._parent)._current_ring(self._poly)
+        return self.__class__(self._parent,self._poly,check=False)
+    def __hash__(self):
+        """
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: set([x*y*z, z*y+x*z,x*y*z])  # indirect doctest
+            set([x*z + z*y, x*y*z])
+
+        """
+        return hash(self._poly)
+    def __iter__(self):
+        """
+        Iterates over the pairs "tuple of exponents, coefficient".
+
+        EXAMPLE::
+
+            sage: F.<w,x,y,z> = FreeAlgebra(GF(3), implementation='letterplace')
+            sage: p = x*y-z^2
+            sage: list(p)   # indirect doctest
+            [((0, 0, 0, 1, 0, 0, 0, 1), 2), ((0, 1, 0, 0, 0, 0, 1, 0), 1)]
+
+        """
+        return self._poly.dict().iteritems()
+    def _repr_(self):
+        """
+        TEST::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: -(a+b*(z+1)-c)^2     # indirect doctest
+            -a*a + (4*z + 4)*a*b + a*c + (4*z + 4)*b*a + (2*z + 1)*b*b + (z + 1)*b*c + c*a + (z + 1)*c*b - c*c
+
+        It is possible to change the names temporarily::
+
+            sage: from sage.structure.parent_gens import localvars
+            sage: with localvars(F, ['w', 'x','y']):
+            ...     print a+b*(z+1)-c
+            w + (z + 1)*x - y
+            sage: print a+b*(z+1)-c
+            a + (z + 1)*b - c
+
+        """
+        cdef list L = []
+        cdef FreeAlgebra_letterplace P = self._parent
+        cdef int ngens = P.__ngens
+        if P._base.is_atomic_repr():
+            for E,c in zip(self._poly.exponents(),self._poly.coefficients()):
+                monstr = P.exponents_to_string(E)
+                if monstr:
+                    if c==1:
+                        if L:
+                            L.extend(['+',monstr])
+                        else:
+                            L.append(monstr)
+                    elif c==-1:
+                        if L:
+                            L.extend(['-',monstr])
+                        else:
+                            L.append('-'+monstr)
+                    else:
+                        if L:
+                            if c>=0:
+                                L.extend(['+',repr(c)+'*'+monstr])
+                            else:
+                                L.extend(['-',repr(-c)+'*'+monstr])
+                        else:
+                            L.append(repr(c)+'*'+monstr)
+                else:
+                    if c>=0:
+                        if L:
+                            L.extend(['+',repr(c)])
+                        else:
+                            L.append(repr(c))
+                    else:
+                        if L:
+                            L.extend(['-',repr(-c)])
+                        else:
+                            L.append(repr(c))
+        else:
+            for E,c in zip(self._poly.exponents(),self._poly.coefficients()):
+                monstr = P.exponents_to_string(E)
+                if monstr:
+                    if c==1:
+                        if L:
+                            L.extend(['+',monstr])
+                        else:
+                            L.append(monstr)
+                    elif c==-1:
+                        if L:
+                            L.extend(['-',monstr])
+                        else:
+                            L.append('-'+monstr)
+                    else:
+                        if L:
+                            L.extend(['+','('+repr(c)+')*'+monstr])
+                        else:
+                            L.append('('+repr(c)+')*'+monstr)
+                else:
+                    if L:
+                        L.extend(['+',repr(c)])
+                    else:
+                        L.append(repr(c))
+        if L:
+            return ' '.join(L)
+        return '0'
+
+    def _latex_(self):
+        """
+        TEST::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace', degrees=[1,2,3])
+            sage: -(a*b*(z+1)-c)^2
+            (2*z + 1)*a*b*a*b + (z + 1)*a*b*c + (z + 1)*c*a*b - c*c
+            sage: latex(-(a*b*(z+1)-c)^2)     # indirect doctest
+            \left(2 z + 1\right) a b a b + \left(z + 1\right) a b c + \left(z + 1\right) c a b - c c
+
+        """
+        cdef list L = []
+        cdef FreeAlgebra_letterplace P = self._parent
+        cdef int ngens = P.__ngens
+        from sage.all import latex
+        if P._base.is_atomic_repr():
+            for E,c in zip(self._poly.exponents(),self._poly.coefficients()):
+                monstr = P.exponents_to_latex(E)
+                if monstr:
+                    if c==1:
+                        if L:
+                            L.extend(['+',monstr])
+                        else:
+                            L.append(monstr)
+                    elif c==-1:
+                        if L:
+                            L.extend(['-',monstr])
+                        else:
+                            L.append('-'+monstr)
+                    else:
+                        if L:
+                            if c>=0:
+                                L.extend(['+',repr(latex(c))+' '+monstr])
+                            else:
+                                L.extend(['-',repr(latex(-c))+' '+monstr])
+                        else:
+                            L.append(repr(latex(c))+' '+monstr)
+                else:
+                    if c>=0:
+                        if L:
+                            L.extend(['+',repr(latex(c))])
+                        else:
+                            L.append(repr(latex(c)))
+                    else:
+                        if L:
+                            L.extend(['-',repr(latex(-c))])
+                        else:
+                            L.append(repr(c))
+        else:
+            for E,c in zip(self._poly.exponents(),self._poly.coefficients()):
+                monstr = P.exponents_to_latex(E)
+                if monstr:
+                    if c==1:
+                        if L:
+                            L.extend(['+',monstr])
+                        else:
+                            L.append(monstr)
+                    elif c==-1:
+                        if L:
+                            L.extend(['-',monstr])
+                        else:
+                            L.append('-'+monstr)
+                    else:
+                        if L:
+                            L.extend(['+','\\left('+repr(latex(c))+'\\right) '+monstr])
+                        else:
+                            L.append('\\left('+repr(latex(c))+'\\right) '+monstr)
+                else:
+                    if L:
+                        L.extend(['+',repr(latex(c))])
+                    else:
+                        L.append(repr(latex(c)))
+        if L:
+            return ' '.join(L)
+        return '0'
+
+    def degree(self):
+        """
+        Return the degree of this element.
+
+        NOTE:
+
+        Generators may have a positive integral degree weight. All
+        elements must be weighted homogeneous.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: ((x+y+z)^3).degree()
+            3
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: ((x*y+z)^3).degree()
+            9
+
+        """
+        return self._poly.degree()
+
+    def letterplace_polynomial(self):
+        """
+        Return the commutative polynomial that is used internally to represent this free algebra element.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: ((x+y-z)^2).letterplace_polynomial()
+            x*x_1 + x*y_1 - x*z_1 + y*x_1 + y*y_1 - y*z_1 - z*x_1 - z*y_1 + z*z_1
+
+        If degree weights are used, the letterplace polynomial is
+        homogenized by slack variables::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: ((x*y+z)^2).letterplace_polynomial()
+            x*x__1*y_2*x_3*x__4*y_5 + x*x__1*y_2*z_3*x__4*x__5 + z*x__1*x__2*x_3*x__4*y_5 + z*x__1*x__2*z_3*x__4*x__5
+
+        """
+        return self._poly
+
+    def lm(self):
+        """
+        The leading monomial of this free algebra element.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: ((2*x+3*y-4*z)^2*(5*y+6*z)).lm()
+            x*x*y
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: ((2*x*y+z)^2).lm()
+            x*y*x*y
+
+        """
+        return FreeAlgebraElement_letterplace(self._parent, self._poly.lm())
+
+    def lt(self):
+        """
+        The leading term (monomial times coefficient) of this free algebra
+        element.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: ((2*x+3*y-4*z)^2*(5*y+6*z)).lt()
+            20*x*x*y
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: ((2*x*y+z)^2).lt()
+            4*x*y*x*y
+
+        """
+        return FreeAlgebraElement_letterplace(self._parent, self._poly.lt())
+
+    def lc(self):
+        """
+        The leading coefficient of this free algebra element, as element
+        of the base ring.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: ((2*x+3*y-4*z)^2*(5*y+6*z)).lc()
+            20
+            sage: ((2*x+3*y-4*z)^2*(5*y+6*z)).lc().parent() is F.base()
+            True
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: ((2*x*y+z)^2).lc()
+            4
+
+        """
+        return self._poly.lc()
+
+    def __nonzero__(self):
+        """
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: bool(x)      # indirect doctest
+            True
+            sage: bool(F.zero())
+            False
+
+        """
+        return bool(self._poly)
+
+    def lm_divides(self, FreeAlgebraElement_letterplace p):
+        """
+        Tell whether or not the leading monomial of self devides the
+        leading monomial of another element.
+
+        NOTE:
+
+        A free algebra element `p` divides another one `q` if there are
+        free algebra elements `s` and `t` such that `spt = q`.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: ((2*x*y+z)^2*z).lm()
+            x*y*x*y*z
+            sage: (y*x*y-y^4).lm()
+            y*x*y
+            sage: (y*x*y-y^4).lm_divides((2*x*y+z)^2*z)
+            True
+
+        """
+        if self._parent is not p._parent:
+            raise TypeError, "The two arguments must be elements in the same free algebra."
+        cdef FreeAlgebra_letterplace A = self._parent
+        P = A._current_ring
+        p_poly = p._poly = P(p._poly)
+        s_poly = self._poly = P(self._poly)
+        cdef int p_d = p_poly.degree()
+        cdef int s_d = s_poly.degree()
+        if s_d>p_d:
+            return False
+        cdef int i
+        if P.monomial_divides(s_poly,p_poly):
+            return True
+        for i from 0 <= i < p_d-s_d:
+            s_poly = singular_system("stest",s_poly,1,
+                                     A._degbound,A.__ngens,ring=P)
+            if P.monomial_divides(s_poly,p_poly):
+                return True
+        return False
+
+    def __richcmp__(left, right, int op):
+        """
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: p = ((2*x+3*y-4*z)^2*(5*y+6*z))
+            sage: p-p.lt()<p    # indirect doctest
+            True
+
+        """
+        return (<Element>left)._richcmp(right, op)
+    def __cmp__(left, right):
+        """
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: p = ((2*x+3*y-4*z)^2*(5*y+6*z))
+            sage: cmp(p,p-p.lt())    # indirect doctest
+            1
+
+        """
+        return (<Element>left)._cmp(right)
+
+    cdef int _cmp_c_impl(self, Element other) except -2:
+        """
+        Auxiliary method for comparison.
+
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: p = ((2*x+3*y-4*z)^2*(5*y+6*z))
+            sage: p-p.lt()<p    # indirect doctest
+            True
+
+        """
+        cdef int c = cmp(type(self),type(other))
+        if c: return c
+        return cmp((<FreeAlgebraElement_letterplace>self)._poly,(<FreeAlgebraElement_letterplace>other)._poly)
+
+    ################################
+    ## Arithmetic
+    cpdef ModuleElement _neg_(self):
+        """
+        TEST::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: -((z+2)*a^2*b+3*c^3)  # indirect doctest
+            (4*z + 3)*a*a*b + (2)*c*c*c
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: -(3*x*y+2*z^2)
+            -3*x*y - 2*z*z
+
+        """
+        return FreeAlgebraElement_letterplace(self._parent,-self._poly,check=False)
+    cpdef ModuleElement _add_(self, ModuleElement other):
+        """
+        Addition, under the side condition that either one summand
+        is zero, or both summands have the same degree.
+
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: x+y    # indirect doctest
+            x + y
+            sage: x+1
+            Traceback (most recent call last):
+            ...
+            ArithmeticError: Can only add elements of the same weighted degree
+            sage: x+0
+            x
+            sage: 0+x
+            x
+
+        """
+        if not other:
+            return self
+        if not self:
+            return other
+        cdef FreeAlgebraElement_letterplace right = other
+        if right._poly.degree()!=self._poly.degree():
+            raise ArithmeticError, "Can only add elements of the same weighted degree"
+        # update the polynomials
+        cdef FreeAlgebra_letterplace A = self._parent
+        self._poly = A._current_ring(self._poly)
+        right._poly = A._current_ring(right._poly)
+        return FreeAlgebraElement_letterplace(self._parent,self._poly+right._poly,check=False)
+
+    cpdef ModuleElement _sub_(self, ModuleElement other):
+        """
+        Difference, under the side condition that either one summand
+        is zero or both have the same weighted degree.
+
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: x*y-y*x     # indirect doctest
+            x*y - y*x
+            sage: x-1
+            Traceback (most recent call last):
+            ...
+            ArithmeticError: Can only subtract elements of the same degree
+            sage: x-0
+            x
+            sage: 0-x
+            -x
+
+        Here is an example with non-trivial degree weights::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: x*y+z
+            x*y + z
+
+        """
+        if not other:
+            return self
+        if not self:
+            return -other
+        cdef FreeAlgebraElement_letterplace right = other
+        if right._poly.degree()!=self._poly.degree():
+            raise ArithmeticError, "Can only subtract elements of the same degree"
+        # update the polynomials
+        cdef FreeAlgebra_letterplace A = self._parent
+        self._poly = A._current_ring(self._poly)
+        right._poly = A._current_ring(right._poly)
+        return FreeAlgebraElement_letterplace(self._parent,self._poly-right._poly,check=False)
+
+    cpdef ModuleElement _lmul_(self, RingElement right):
+        """
+        Multiplication from the right with an element of the base ring.
+
+        TEST::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: (a+b)*(z+1)    # indirect doctest
+            (z + 1)*a + (z + 1)*b
+
+        """
+        return FreeAlgebraElement_letterplace(self._parent,self._poly._lmul_(right),check=False)
+
+    cpdef ModuleElement _rmul_(self, RingElement left):
+        """
+        Multiplication from the left with an element of the base ring.
+
+        TEST::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: (z+1)*(a+b)   # indirect doctest
+            (z + 1)*a + (z + 1)*b
+
+        """
+        return FreeAlgebraElement_letterplace(self._parent,self._poly._rmul_(left),check=False)
+
+    cpdef RingElement _mul_(self, RingElement other):
+        """
+        Product of two free algebra elements in letterplace implementation.
+
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: (x*y+z)*z   # indirect doctest
+            x*y*z + z*z
+
+        """
+        cdef FreeAlgebraElement_letterplace left = self
+        cdef FreeAlgebraElement_letterplace right = other
+        cdef FreeAlgebra_letterplace A = left._parent
+        A.set_degbound(left._poly.degree()+right._poly.degree())
+        # we must put the polynomials into the same ring
+        left._poly = A._current_ring(left._poly)
+        right._poly = A._current_ring(right._poly)
+        rshift = singular_system("stest",right._poly,left._poly.degree(),A._degbound,A.__ngens, ring=A._current_ring)
+        return FreeAlgebraElement_letterplace(A,left._poly*rshift, check=False)
+
+    def __pow__(FreeAlgebraElement_letterplace self, int n, k):
+        """
+        TEST::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: (a+z*b)^3    # indirect doctest
+            a*a*a + (z)*a*a*b + (z)*a*b*a + (z + 3)*a*b*b + (z)*b*a*a + (z + 3)*b*a*b + (z + 3)*b*b*a + (4*z + 3)*b*b*b
+
+        """
+        cdef FreeAlgebra_letterplace A = self._parent
+        if n<0:
+            raise ValueError, "Negative exponents are not allowed"
+        if n==0:
+            return FreeAlgebraElement_letterplace(A, A._current_ring(1),
+                                                  check=False)
+        if n==1:
+            return self
+        A.set_degbound(self._poly.degree()*n)
+        cdef MPolynomial_libsingular p,q
+        self._poly = A._current_ring(self._poly)
+        cdef int d = self._poly.degree()
+        q = p = self._poly
+        cdef int i
+        for i from 0<i<n:
+            q = singular_system("stest",q,d,A._degbound,A.__ngens,
+                                     ring=A._current_ring)
+            p *= q
+        return FreeAlgebraElement_letterplace(A, p, check=False)
+
+    ## Groebner related stuff
+    def reduce(self, G):
+        """
+        Reduce this element by a list of elements or by a
+        twosided weighted homogeneous ideal.
+
+        INPUT:
+
+        Either a list or tuple of weighted homogeneous elements of the
+        free algebra, or an ideal of the free algebra, or an ideal in
+        the commutative polynomial ring that is currently used to
+        implement the multiplication in the free algebra.
+
+        OUTPUT:
+
+        The twosided reduction of this element by the argument.
+
+        NOTE:
+
+        This may not be the normal form of this element, unless
+        the argument is a twosided Groebner basis up to the degree
+        of this element.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: p = y^2*z*y^2+y*z*y*z*y
+
+        We compute the letterplace version of the Groebneer basis
+        of `I` with degree bound 4::
+
+            sage: G = F._reductor_(I.groebner_basis(4).gens(),4)
+            sage: G.ring() is F.current_ring()
+            True
+
+        Since the element `p` is of degree 5, it is no surrprise
+        that its reductions with respect to the original generators
+        of `I` (of degree 2), or with respect to `G` (Groebner basis
+        with degree bound 4), or with respect to the Groebner basis
+        with degree bound 5 (which yields its normal form) are
+        pairwise different::
+
+            sage: p.reduce(I)
+            y*y*z*y*y + y*z*y*z*y
+            sage: p.reduce(G)
+            y*y*z*z*y + y*z*y*z*y - y*z*z*y*y + y*z*z*z*y
+            sage: p.normal_form(I)
+            y*y*z*z*z + y*z*y*z*z - y*z*z*y*z + y*z*z*z*z
+            sage: p.reduce(I) != p.reduce(G) != p.normal_form(I) != p.reduce(I)
+            True
+
+        """
+        cdef FreeAlgebra_letterplace P = self._parent
+        if not isinstance(G,(list,tuple)):
+            if G==P:
+                return P.zero_element()
+            if not (isinstance(G,MPolynomialIdeal) and G.ring()==P._current_ring):
+                G = G.gens()
+        C = P.current_ring()
+        cdef int selfdeg = self._poly.degree()
+        if isinstance(G,MPolynomialIdeal):
+            gI = G
+        else:
+            gI = P._reductor_(G,selfdeg) #C.ideal(g,coerce=False)
+        from sage.libs.singular.option import LibSingularOptions
+        libsingular_options = LibSingularOptions()
+        bck = (libsingular_options['redTail'],libsingular_options['redSB'])
+        libsingular_options['redTail'] = True
+        libsingular_options['redSB'] = True
+        poly = poly_reduce(C(self._poly),gI, ring=C,
+                           attributes={gI:{"isSB":1}})
+        libsingular_options['redTail'] = bck[0]
+        libsingular_options['redSB'] = bck[1]
+        return FreeAlgebraElement_letterplace(P,poly,check=False)
+
+    def normal_form(self,I):
+        """
+        Return the normal form of this element with respect to
+        a twosided weighted homogeneous ideal.
+
+        INPUT:
+
+        A twosided homogeneous ideal `I` of the parent `F` of
+        this element, `x`.
+
+        OUTPUT:
+
+        The normal form of `x` wrt. `I`.
+
+        NOTE:
+
+        The normal form is computed by reduction with respect
+        to a Groebnerbasis of `I` with degree bound `deg(x)`.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: (x^5).normal_form(I)
+            -y*z*z*z*x - y*z*z*z*y - y*z*z*z*z
+
+        We verify two basic properties of normal forms: The
+        difference of an element and its normal form is contained
+        in the ideal, and if two elements of the free algebra
+        differ by an element of the ideal then they have the same
+        normal form::
+
+            sage: x^5 - (x^5).normal_form(I) in I
+            True
+            sage: (x^5+x*I.0*y*z-3*z^2*I.1*y).normal_form(I) == (x^5).normal_form(I)
+            True
+
+        Here is an example with non-trivial degree weights::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[1,2,3])
+            sage: I = F*[x*y-y*x+z, y^2+2*x*z, (x*y)^2-z^2]*F
+            sage: ((x*y)^3).normal_form(I)
+            z*z*y*x - z*z*z
+            sage: (x*y)^3-((x*y)^3).normal_form(I) in I
+            True
+            sage: ((x*y)^3+2*z*I.0*z+y*I.1*z-x*I.2*y).normal_form(I) == ((x*y)^3).normal_form(I)
+            True
+
+        """
+        if self._parent != I.ring():
+            raise ValueError, "Can not compute normal form wrt an ideal that does not belong to %s"%self._parent
+        sdeg = self._poly.degree()
+        return self.reduce(self._parent._reductor_(I.groebner_basis(degbound=sdeg).gens(), sdeg))

new file sage/algebras/letterplace/free_algebra_letterplace.pxd

@@ +1 @@
+###############################################################################
+#
+#       Copyright (C) 2011 Simon King <simon.king@uni-jena.de>
+#  Distributed under the terms of the GNU General Public License (GPL),
+#  version 2 or any later version.  The full text of the GPL is available at:
+#                  http://www.gnu.org/licenses/
+#
+###############################################################################
+
+cdef class FreeAlgebra_letterplace
+
+from sage.rings.ring cimport Algebra
+from sage.structure.element cimport AlgebraElement, ModuleElement, RingElement, Element
+from sage.rings.polynomial.multi_polynomial_libsingular cimport MPolynomialRing_libsingular, MPolynomial_libsingular
+from sage.algebras.letterplace.free_algebra_element_letterplace cimport FreeAlgebraElement_letterplace
+
+include "../../ext/stdsage.pxi"
+
+cdef class FreeAlgebra_letterplace(Algebra):
+    cdef MPolynomialRing_libsingular _commutative_ring
+    cdef MPolynomialRing_libsingular _current_ring
+    cdef int _degbound
+    cdef int __ngens
+    cdef int _nb_slackvars
+    cdef object __monoid
+    cdef public object __custom_name
+    cdef str exponents_to_string(self, E)
+    cdef str exponents_to_latex(self, E)
+    cdef tuple _degrees

new file sage/algebras/letterplace/free_algebra_letterplace.pyx

@@ +1 @@
+###############################################################################
+#
+#       Copyright (C) 2011 Simon King <simon.king@uni-jena.de>
+#  Distributed under the terms of the GNU General Public License (GPL),
+#  version 2 or any later version.  The full text of the GPL is available at:
+#                  http://www.gnu.org/licenses/
+#
+###############################################################################
+
+"""
+Free associative unital algebras, implemented via Singular's letterplace rings
+
+AUTHOR:
+
+- Simon King (2011-03-21): :trac:`7797`
+
+With this implementation, Groebner bases out to a degree bound and
+normal forms can be computed for twosided weighted homogeneous ideals
+of free algebras. For now, all computations are restricted to weighted
+homogeneous elements, i.e., other elements can not be created by
+arithmetic operations.
+
+EXAMPLES::
+
+    sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+    sage: F
+    Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+    sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+    sage: I
+    Twosided Ideal (x*y + y*z, x*x + x*y - y*x - y*y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+    sage: x*(x*I.0-I.1*y+I.0*y)-I.1*y*z
+    x*y*x*y + x*y*y*y - x*y*y*z + x*y*z*y + y*x*y*z + y*y*y*z
+    sage: x^2*I.0-x*I.1*y+x*I.0*y-I.1*y*z in I
+    True
+
+The preceding containment test is based on the computation of Groebner
+bases with degree bound::
+
+    sage: I.groebner_basis(degbound=4)
+    Twosided Ideal (y*z*y*y - y*z*y*z + y*z*z*y - y*z*z*z, y*z*y*x + y*z*y*z + y*z*z*x + y*z*z*z, y*y*z*y - y*y*z*z + y*z*z*y - y*z*z*z, y*y*z*x + y*y*z*z + y*z*z*x + y*z*z*z, y*y*y - y*y*z + y*z*y - y*z*z, y*y*x + y*y*z + y*z*x + y*z*z, x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+When reducing an element by `I`, the original generators are chosen::
+
+    sage: (y*z*y*y).reduce(I)
+    y*z*y*y
+
+However, there is a method for computing the normal form of an
+element, which is the same as reduction by the Groebner basis out to
+the degree of that element::
+
+    sage: (y*z*y*y).normal_form(I)
+    y*z*y*z - y*z*z*y + y*z*z*z
+    sage: (y*z*y*y).reduce(I.groebner_basis(4))
+    y*z*y*z - y*z*z*y + y*z*z*z
+
+The default term order derives from the degree reverse lexicographic
+order on the commutative version of the free algebra::
+
+    sage: F.commutative_ring().term_order()
+    Degree reverse lexicographic term order
+
+A different term order can be chosen, and of course may yield a
+different normal form::
+
+    sage: L.<a,b,c> = FreeAlgebra(QQ, implementation='letterplace', order='lex')
+    sage: L.commutative_ring().term_order()
+    Lexicographic term order
+    sage: J = L*[a*b+b*c,a^2+a*b-b*c-c^2]*L
+    sage: J.groebner_basis(4)
+    Twosided Ideal (2*b*c*b - b*c*c + c*c*b, a*c*c - 2*b*c*a - 2*b*c*c - c*c*a, a*b + b*c, a*a - 2*b*c - c*c) of Free Associative Unital Algebra on 3 generators (a, b, c) over Rational Field
+    sage: (b*c*b*b).normal_form(J)
+    1/2*b*c*c*b - 1/2*c*c*b*b
+
+Here is an example with degree weights::
+
+    sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[1,2,3])
+    sage: (x*y+z).degree()
+    3
+
+TEST::
+
+    sage: TestSuite(F).run()
+    sage: TestSuite(L).run()
+    sage: loads(dumps(F)) is F
+    True
+
+TODO:
+
+The computation of Groebner bases only works for global term
+orderings, and all elements must be weighted homogeneous with respect
+to positive integral degree weights. It is ongoing work in Singular to
+lift these restrictions.
+
+We support coercion from the letterplace wrapper to the corresponding
+generic implementation of a free algebra
+(:class:`~sage.algebras.free_algebra.FreeAlgebra_generic`), but there
+is no coercion in the opposite direction, since the generic
+implementation also comprises non-homogeneous elements.
+
+We also do not support coercion from a subalgebra, or between free
+algebras with different term orderings, yet.
+
+"""
+
+from sage.all import PolynomialRing, prod
+from sage.libs.singular.function import lib, singular_function 
+from sage.rings.polynomial.term_order import TermOrder
+from sage.rings.polynomial.multi_polynomial_ring_generic import MPolynomialRing_generic
+from sage.categories.algebras import Algebras
+from sage.rings.noncommutative_ideals import IdealMonoid_nc
+
+#####################
+# Define some singular functions
+lib("freegb.lib")
+poly_reduce = singular_function("NF")
+singular_system=singular_function("system") 
+
+# unfortunately we can not set Singular attributes for MPolynomialRing_libsingular
+# Hence, we must constantly work around Letterplace's sanity checks,
+# and can not use the following library functions:
+#set_letterplace_attributes = singular_function("setLetterplaceAttributes")
+#lpMult = singular_function("lpMult")
+
+#####################
+# Auxiliar functions
+
+cdef MPolynomialRing_libsingular make_letterplace_ring(base_ring,blocks):
+    """
+    Create a polynomial ring in block order.
+
+    INPUT:
+
+    - ``base_ring``: A multivariate polynomial ring.
+    - ``blocks``: The number of blocks to be formed.
+
+    OUTPUT:
+
+    A multivariate polynomial ring in block order, all blocks
+    isomorphic (as ordered rings) with the given ring, and the
+    variable names of the `n`-th block (`n>0`) ending with
+    ``"_%d"%n``.
+
+    TEST:
+
+    Note that, since the algebras are cached, we need to choose
+    a different base ring, since other doctests could have a
+    side effect on the atteined degree bound::
+
+        sage: F.<x,y,z> = FreeAlgebra(GF(17), implementation='letterplace')
+        sage: L.<a,b,c> = FreeAlgebra(GF(17), implementation='letterplace', order='lex')
+        sage: F.set_degbound(4)
+        sage: F.current_ring()  # indirect doctest
+        Multivariate Polynomial Ring in x, y, z, x_1, y_1, z_1, x_2, y_2, z_2, x_3, y_3, z_3 over Finite Field of size 17
+        sage: F.current_ring().term_order()
+        Block term order with blocks:
+        (Degree reverse lexicographic term order of length 3,
+         Degree reverse lexicographic term order of length 3,
+         Degree reverse lexicographic term order of length 3,
+         Degree reverse lexicographic term order of length 3)
+        sage: L.set_degbound(2)
+        sage: L.current_ring().term_order()
+        Block term order with blocks:
+        (Lexicographic term order of length 3,
+         Lexicographic term order of length 3)
+
+    """
+    n = base_ring.ngens()
+    T0 = base_ring.term_order()
+    T = T0
+    cdef i
+    cdef tuple names0 = base_ring.variable_names()
+    cdef list names = list(names0)
+    for i from 1<=i<blocks:
+        T += T0
+        names.extend([x+'_'+str(i) for x in names0])
+    return PolynomialRing(base_ring.base_ring(),len(names),names,order=T)
+
+#####################
+# The free algebra
+
+cdef class FreeAlgebra_letterplace(Algebra):
+    """
+    Finitely generated free algebra, with arithmetic restricted to weighted homogeneous elements.
+
+    NOTE:
+
+    The restriction to weighted homogeneous elements should be lifted
+    as soon as the restriction to homogeneous elements is lifted in
+    Singular's "Letterplace algebras".
+
+    EXAMPLE::
+
+        sage: K.<z> = GF(25)
+        sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+        sage: F
+        Free Associative Unital Algebra on 3 generators (a, b, c) over Finite Field in z of size 5^2
+        sage: P = F.commutative_ring()
+        sage: P
+        Multivariate Polynomial Ring in a, b, c over Finite Field in z of size 5^2
+
+    We can do arithmetic as usual, as long as we stay (weighted) homogeneous::
+
+        sage: (z*a+(z+1)*b+2*c)^2
+        (z + 3)*a*a + (2*z + 3)*a*b + (2*z)*a*c + (2*z + 3)*b*a + (3*z + 4)*b*b + (2*z + 2)*b*c + (2*z)*c*a + (2*z + 2)*c*b - c*c
+        sage: a+1
+        Traceback (most recent call last):
+        ...
+        ArithmeticError: Can only add elements of the same weighted degree
+
+    """
+    # It is not really a free algebra over the given generators. Rather,
+    # it is a free algebra over the commutative monoid generated by the given generators.
+    def __init__(self, R, degrees=None):
+        """
+        INPUT:
+
+        A multivariate polynomial ring of type :class:`~sage.rings.polynomial.multipolynomial_libsingular.MPolynomialRing_libsingular`.
+
+        OUTPUT:
+
+        The free associative version of the given commutative ring.
+
+        NOTE:
+
+        One is supposed to use the `FreeAlgebra` constructor, in order to use the cache.
+
+        TEST::
+
+            sage: from sage.algebras.letterplace.free_algebra_letterplace import FreeAlgebra_letterplace
+            sage: FreeAlgebra_letterplace(QQ['x','y'])
+            Free Associative Unital Algebra on 2 generators (x, y) over Rational Field
+            sage: FreeAlgebra_letterplace(QQ['x'])
+            Traceback (most recent call last):
+            ...
+            TypeError: A letterplace algebra must be provided by a polynomial ring of type <type 'sage.rings.polynomial.multi_polynomial_libsingular.MPolynomialRing_libsingular'>
+
+        ::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: TestSuite(F).run(verbose=True)
+            running ._test_additive_associativity() . . . pass
+            running ._test_an_element() . . . pass
+            running ._test_associativity() . . . pass
+            running ._test_category() . . . pass
+            running ._test_characteristic() . . . pass
+            running ._test_distributivity() . . . pass
+            running ._test_elements() . . .
+              Running the test suite of self.an_element()
+              running ._test_category() . . . pass
+              running ._test_eq() . . . pass
+              running ._test_not_implemented_methods() . . . pass
+              running ._test_pickling() . . . pass
+              pass
+            running ._test_elements_eq() . . . pass
+            running ._test_eq() . . . pass
+            running ._test_not_implemented_methods() . . . pass
+            running ._test_one() . . . pass
+            running ._test_pickling() . . . pass
+            running ._test_prod() . . . pass
+            running ._test_some_elements() . . . pass
+            running ._test_zero() . . . pass
+
+        """
+        if not isinstance(R,MPolynomialRing_libsingular):
+            raise TypeError, "A letterplace algebra must be provided by a polynomial ring of type %s"%MPolynomialRing_libsingular
+        self.__ngens = R.ngens()
+        if degrees is None:
+            varnames = R.variable_names()
+            self._nb_slackvars = 0
+        else:
+            varnames = R.variable_names()[:-1]
+            self._nb_slackvars = 1
+        base_ring = R.base_ring()
+        Algebra.__init__(self, base_ring, varnames,
+                         normalize=False, category=Algebras(base_ring))
+        self._commutative_ring = R
+        self._current_ring = make_letterplace_ring(R,1)
+        self._degbound = 1
+        if degrees is None:
+            self._degrees = tuple([int(1)]*self.__ngens)
+        else:
+            if (not isinstance(degrees,(tuple,list))) or len(degrees)!=self.__ngens-1 or any([i<=0 for i in degrees]):
+                raise TypeError, "The generator degrees must be given by a list or tuple of %d positive integers"%(self.__ngens-1)
+            self._degrees = tuple([int(i) for i in degrees])
+            self.set_degbound(max(self._degrees))
+        self._populate_coercion_lists_(coerce_list=[base_ring])
+    def __reduce__(self):
+        """
+        TEST::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: loads(dumps(F)) is F    # indirect doctest
+            True
+
+        """
+        from sage.algebras.free_algebra import FreeAlgebra
+        if self._nb_slackvars==0:
+            return FreeAlgebra,(self._commutative_ring,)
+        return FreeAlgebra,(self._commutative_ring,None,None,None,None,None,None,None,self._degrees)
+    # Small methods
+    def ngens(self):
+        """
+        Return the number of generators.
+
+        EXAMPLE::
+
+            sage: F.<a,b,c> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F.ngens()
+            3
+
+        """
+        return self.__ngens-self._nb_slackvars
+    def gen(self,i):
+        """
+        Return the `i`-th generator.
+
+        INPUT:
+
+        `i` -- an integer.
+
+        OUTPUT:
+
+        Generator number `i`.
+
+        EXAMPLE::
+
+            sage: F.<a,b,c> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F.1 is F.1  # indirect doctest
+            True
+            sage: F.gen(2)
+            c
+
+        """
+        if i>=self.__ngens-self._nb_slackvars:
+            raise ValueError, "This free algebra only has %d generators"%(self.__ngens-self._nb_slackvars)
+        if self._gens is not None:
+            return self._gens[i]
+        deg = self._degrees[i]
+        #self.set_degbound(deg)
+        p = self._current_ring.gen(i)
+        cdef int n
+        cdef int j = self.__ngens-1
+        for n from 1<=n<deg:
+            j += self.__ngens
+            p *= self._current_ring.gen(j)
+        return FreeAlgebraElement_letterplace(self, p)
+    def current_ring(self):
+        """
+        Return the commutative ring that is used to emulate
+        the non-commutative multiplication out to the current degree.
+
+        EXAMPLE::
+
+            sage: F.<a,b,c> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F.current_ring()
+            Multivariate Polynomial Ring in a, b, c over Rational Field
+            sage: a*b
+            a*b
+            sage: F.current_ring()
+            Multivariate Polynomial Ring in a, b, c, a_1, b_1, c_1 over Rational Field
+            sage: F.set_degbound(3)
+            sage: F.current_ring()
+            Multivariate Polynomial Ring in a, b, c, a_1, b_1, c_1, a_2, b_2, c_2 over Rational Field
+
+        """
+        return self._current_ring
+    def commutative_ring(self):
+        """
+        Return the commutative version of this free algebra.
+
+        NOTE:
+
+        This commutative ring is used as a unique key of the free algebra.
+
+        EXAMPLE::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace')
+            sage: F
+            Free Associative Unital Algebra on 3 generators (a, b, c) over Finite Field in z of size 5^2
+            sage: F.commutative_ring()
+            Multivariate Polynomial Ring in a, b, c over Finite Field in z of size 5^2
+            sage: FreeAlgebra(F.commutative_ring()) is F
+            True
+
+        """
+        return self._commutative_ring
+    def term_order_of_block(self):
+        """
+        Return the term order that is used for the commutative version of this free algebra.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F.term_order_of_block()
+            Degree reverse lexicographic term order
+            sage: L.<a,b,c> = FreeAlgebra(QQ, implementation='letterplace',order='lex')
+            sage: L.term_order_of_block()
+            Lexicographic term order
+
+        """
+        return self._commutative_ring.term_order()
+
+    def generator_degrees(self):
+        return self._degrees
+
+    # Some basic properties of this ring
+    def is_commutative(self):
+        """
+        Tell whether this algebra is commutative, i.e., whether the generator number is one.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F.is_commutative()
+            False
+            sage: FreeAlgebra(QQ, implementation='letterplace', names=['x']).is_commutative()
+            True
+
+        """
+        return self.__ngens-self._nb_slackvars <= 1
+
+    def is_field(self):
+        """
+        Tell whether this free algebra is a field.
+
+        NOTE:
+
+        This would only be the case in the degenerate case of no generators.
+        But such an example can not be constructed in this implementation.
+
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F.is_field()
+            False
+
+        """
+        return (not (self.__ngens-self._nb_slackvars)) and self._base.is_field()
+
+    def _repr_(self):
+        """
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F     # indirect doctest
+            Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+        The degree weights are not part of the string representation::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3])
+            sage: F
+            Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+
+        """
+        return "Free Associative Unital Algebra on %d generators %s over %s"%(self.__ngens-self._nb_slackvars,self.gens(),self._base)
+
+    def _latex_(self):
+        """
+        Representation of this free algebra in LaTeX.
+
+        EXAMPLE::
+
+            sage: F.<bla,alpha,z> = FreeAlgebra(QQ, implementation='letterplace', degrees=[1,2,3])
+            sage: latex(F)
+            \Bold{Q}\langle \mbox{bla}, \alpha, z\rangle
+
+        """
+        from sage.all import latex
+        return "%s\\langle %s\\rangle"%(latex(self.base_ring()),', '.join(self.latex_variable_names()))
+
+    def degbound(self):
+        """
+        Return the degree bound that is currently used.
+
+        NOTE:
+
+        When multiplying two elements of this free algebra, the degree
+        bound will be dynamically adapted. It can also be set by
+        :meth:`set_degbound`.
+
+        EXAMPLE:
+
+        In order to avoid we get a free algebras from the cache that
+        was created in another doctest and has a different degree
+        bound, we choose a base ring that does not appear in other tests::
+
+            sage: F.<x,y,z> = FreeAlgebra(ZZ, implementation='letterplace')
+            sage: F.degbound()
+            1
+            sage: x*y
+            x*y
+            sage: F.degbound()
+            2
+            sage: F.set_degbound(4)
+            sage: F.degbound()
+            4
+
+        """
+        return self._degbound
+    def set_degbound(self,d):
+        """
+        Increase the degree bound that is currently in place.
+
+        NOTE:
+
+        The degree bound can not be decreased.
+
+        EXAMPLE:
+
+        In order to avoid we get a free algebras from the cache that
+        was created in another doctest and has a different degree
+        bound, we choose a base ring that does not appear in other tests::
+
+            sage: F.<x,y,z> = FreeAlgebra(GF(251), implementation='letterplace')
+            sage: F.degbound()
+            1
+            sage: x*y
+            x*y
+            sage: F.degbound()
+            2
+            sage: F.set_degbound(4)
+            sage: F.degbound()
+            4
+            sage: F.set_degbound(2)
+            sage: F.degbound()
+            4
+
+        """
+        if d<=self._degbound:
+            return
+        self._degbound = d
+        self._current_ring = make_letterplace_ring(self._commutative_ring,d)
+
+#    def base_extend(self, R):
+#        if self._base.has_coerce_map_from(R):
+#            return self
+
+    ################################################
+    ## Ideals
+
+    def _ideal_class_(self, n=0):
+        """
+        Return the class :class:`~sage.algebras.letterplace.letterplace_ideal.LetterplaceIdeal`.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = [x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: I
+            Right Ideal (x*y + y*z, x*x + x*y - y*x - y*y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+            sage: type(I) is F._ideal_class_()
+            True
+
+        """
+        from sage.algebras.letterplace.letterplace_ideal import LetterplaceIdeal
+        return LetterplaceIdeal
+
+    def ideal_monoid(self):
+        """
+        Return the monoid of ideals of this free algebra.
+
+        EXAMPLE::
+
+            sage: F.<x,y> = FreeAlgebra(GF(2), implementation='letterplace')
+            sage: F.ideal_monoid()
+            Monoid of ideals of Free Associative Unital Algebra on 2 generators (x, y) over Finite Field of size 2
+            sage: F.ideal_monoid() is F.ideal_monoid()
+            True
+
+        """
+        if self.__monoid is None:
+            self.__monoid = IdealMonoid_nc(self)
+        return self.__monoid
+
+    # Auxiliar methods
+    cdef str exponents_to_string(self, E):
+        """
+        This auxiliary method is used for the string representation of elements of this free algebra.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(GF(2), implementation='letterplace')
+            sage: x*y*x*z   # indirect doctest
+            x*y*x*z
+
+        It should be possible to use the letterplace algebra to implement the
+        free algebra generated by the elements of a finitely generated free abelian
+        monoid. However, we can not use it, yet. So, for now, we raise an error::
+
+            sage: from sage.algebras.letterplace.free_algebra_element_letterplace import FreeAlgebraElement_letterplace
+            sage: P = F.commutative_ring()
+            sage: FreeAlgebraElement_letterplace(F, P.0*P.1^2+P.1^3) # indirect doctest
+            Traceback (most recent call last):
+            ...
+            NotImplementedError:
+              Apparently you tried to view the letterplace algebra with
+              shift-multiplication as the free algebra over a finitely
+              generated free abelian monoid.
+              In principle, this is correct, but it is not implemented, yet.
+
+        """
+        cdef int ngens = self.__ngens
+        cdef int nblocks = len(E)/ngens
+        cdef int i,j,base, exp, var_ind
+        cdef list out = []
+        cdef list tmp
+        for i from 0<=i<nblocks:
+            base = i*ngens
+            tmp = [(j,E[base+j]) for j in xrange(ngens) if E[base+j]]
+            if not tmp:
+                continue
+            var_ind, exp = tmp[0]
+            if len(tmp)>1 or exp>1:
+                raise NotImplementedError, "\n  Apparently you tried to view the letterplace algebra with\n  shift-multiplication as the free algebra over a finitely\n  generated free abelian monoid.\n  In principle, this is correct, but it is not implemented, yet."
+
+            out.append(self._names[var_ind])
+            i += (self._degrees[var_ind]-1)
+            ### This was the original implementation, with "monoid hack" but without generator degrees
+            #s = '.'.join([('%s^%d'%(x,e) if e>1 else x) for x,e in zip(self._names,E[i*ngens:(i+1)*ngens]) if e])
+            #if s:
+            #    out.append(s)
+        return '*'.join(out)
+
+    # Auxiliar methods
+    cdef str exponents_to_latex(self, E):
+        """
+        This auxiliary method is used for the representation of elements of this free algebra as a latex string.
+
+        EXAMPLE::
+
+            sage: K.<z> = GF(25)
+            sage: F.<a,b,c> = FreeAlgebra(K, implementation='letterplace', degrees=[1,2,3])
+            sage: -(a*b*(z+1)-c)^2
+            (2*z + 1)*a*b*a*b + (z + 1)*a*b*c + (z + 1)*c*a*b - c*c
+            sage: latex(-(a*b*(z+1)-c)^2)     # indirect doctest
+            \left(2 z + 1\right) a b a b + \left(z + 1\right) a b c + \left(z + 1\right) c a b - c c
+
+        """
+        cdef int ngens = self.__ngens
+        cdef int nblocks = len(E)/ngens
+        cdef int i,j,base, exp, var_ind
+        cdef list out = []
+        cdef list tmp
+        cdef list names = self.latex_variable_names()
+        for i from 0<=i<nblocks:
+            base = i*ngens
+            tmp = [(j,E[base+j]) for j in xrange(ngens) if E[base+j]]
+            if not tmp:
+                continue
+            var_ind, exp = tmp[0]
+            if len(tmp)>1 or exp>1:
+                raise NotImplementedError, "\n  Apparently you tried to view the letterplace algebra with\n  shift-multiplication as the free algebra over a finitely\n  generated free abelian monoid.\n  In principle, this is correct, but it is not implemented, yet."
+
+            out.append(names[var_ind])
+            i += (self._degrees[var_ind]-1)
+        return ' '.join(out)
+
+    def _reductor_(self, g, d):
+        """
+        Return a commutative ideal that can be used to compute the normal
+        form of a free algebra element of a given degree.
+
+        INPUT:
+
+        ``g`` - a list of elements of this free algebra.
+        ``d`` - an integer.
+
+        OUTPUT:
+
+        An ideal such that reduction of a letterplace polynomial by that ideal corresponds
+        to reduction of an element of degree at most ``d`` by ``g``.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: p = y*x*y + y*y*y + y*z*y - y*z*z
+            sage: p.reduce(I)
+            y*y*y - y*y*z + y*z*y - y*z*z
+            sage: G = F._reductor_(I.gens(),3); G
+            Ideal (x*y_1 + y*z_1, x_1*y_2 + y_1*z_2, x*x_1 + x*y_1 - y*x_1 - y*y_1, x_1*x_2 + x_1*y_2 - y_1*x_2 - y_1*y_2) of Multivariate Polynomial Ring in x, y, z, x_1, y_1, z_1, x_2, y_2, z_2... over Rational Field
+
+        We do not use the usual reduction method for polynomials in
+        Sage, since it does the reductions in a different order
+        compared to Singular. Therefore, we call the original Singular
+        reduction method, and prevent a warning message by asserting
+        that `G` is a Groebner basis.
+
+            sage: from sage.libs.singular.function import singular_function
+            sage: poly_reduce = singular_function("NF")
+            sage: q = poly_reduce(p.letterplace_polynomial(), G, ring=F.current_ring(), attributes={G:{"isSB":1}}); q
+            y*y_1*y_2 - y*y_1*z_2 + y*z_1*y_2 - y*z_1*z_2
+            sage: p.reduce(I).letterplace_polynomial() == q
+            True
+
+        """
+        cdef list out = []
+        C = self.current_ring()
+        cdef FreeAlgebraElement_letterplace x
+        ngens = self.__ngens
+        degbound = self._degbound
+        cdef list G = [C(x._poly) for x in g]
+        for y in G:
+            out.extend([y]+[singular_system("stest",y,n+1,degbound,ngens,ring=C) for n in xrange(d-y.degree())])
+        return C.ideal(out)
+
+    ###########################
+    ## Coercion
+    cpdef _coerce_map_from_(self,S):
+        """
+        A ring ``R`` coerces into self, if
+
+        - it coerces into the current polynomial ring, or
+        - it is a free graded algebra in letterplace implementation,
+          the generator names of ``R`` are a proper subset of the
+          generator names of self, the degrees of equally named
+          generators are equal, and the base ring of ``R`` coerces
+          into the base ring of self.
+
+        TEST:
+
+        Coercion from the base ring::
+
+            sage: F.<x,y,z> = FreeAlgebra(GF(5), implementation='letterplace')
+            sage: 5 == F.zero()    # indirect doctest
+            True
+
+        Coercion from another free graded algebra::
+
+            sage: F.<t,y,z> = FreeAlgebra(ZZ, implementation='letterplace', degrees=[4,2,3])
+            sage: G = FreeAlgebra(GF(5), implementation='letterplace', names=['x','y','z','t'], degrees=[1,2,3,4])
+            sage: t*G.0       # indirect doctest
+            t*x
+
+        """
+        if self==S or self._current_ring.has_coerce_map_from(S):
+            return True
+        cdef int i
+        # Do we have another letterplace algebra?
+        if not isinstance(S, FreeAlgebra_letterplace):
+            return False
+        # Do the base rings coerce?
+        if not self.base_ring().has_coerce_map_from(S.base_ring()):
+            return False
+        # Do the names match?
+        cdef tuple degs, Sdegs, names, Snames
+        names = self.variable_names()
+        Snames = S.variable_names()
+        if not set(names).issuperset(Snames):
+            return False
+        # Do the degrees match
+        degs = self._degrees
+        Sdegs = (<FreeAlgebra_letterplace>S)._degrees
+        for i from 0<=i<S.ngens():
+            if degs[names.index(Snames[i])] != Sdegs[i]:
+                return False
+        return True
+
+    def _an_element_(self):
+        """
+        Return an element.
+
+        EXAMPLE::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: F.an_element()   # indirect doctest
+            x
+
+        """
+        return FreeAlgebraElement_letterplace(self, self._current_ring.an_element(), check=False)
+
+#    def random_element(self, degree=2, terms=5):
+#        """
+#        Return a random element of a given degree and with a given number of terms.
+#
+#        INPUT:
+#
+#        - ``degree`` -- the maximal degree of the output (default 2).
+#        - ``terms`` -- the maximal number of terms of the output (default 5).
+#
+#        NOTE:
+#
+#        This method is currently not useful at all.
+#
+#        Not tested.
+#        """
+#        self.set_degbound(degree)
+#        while(1):
+#            p = self._current_ring.random_element(degree=degree,terms=terms)
+#            if p.is_homogeneous():
+#                break
+#        return FreeAlgebraElement_letterplace(self, p, check=False)
+
+    def _from_dict_(self, D, check=True):
+        """
+        Create an element from a dictionary.
+
+        INPUT:
+
+        - A dictionary. Keys: tuples of exponents. Values:
+          The coefficients of the corresponding monomial
+          in the to-be-created element.
+        - ``check`` (optional bool, default ``True``):
+          This is forwarded to the initialisation of
+          :class:`~sage.algebas.letterplace.free_algebra_element_letterplace.FreeAlgebraElement_letterplace`.
+
+        TEST:
+
+        This method applied to the dictionary of any element must
+        return the same element. This must hold true even if the
+        underlying letterplace ring has been extended in the meantime.
+        ::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: p = 3*x*y+2*z^2
+            sage: F.set_degbound(10)
+            sage: p == F._from_dict_(dict(p))
+            True
+
+        For the empty dictionary, zero is returned::
+
+            sage: F._from_dict_({})
+            0
+
+        """
+        if not D:
+            return self.zero_element()
+        cdef int l
+        for e in D.iterkeys():
+            l = len(e)
+            break
+        cdef dict out = {}
+        self.set_degbound(l/self.__ngens)
+        cdef int n = self._current_ring.ngens()
+        for e,c in D.iteritems():
+            out[tuple(e)+(0,)*(n-l)] = c
+        return FreeAlgebraElement_letterplace(self,self._current_ring(out),
+                                              check=check)
+
+    def _element_constructor_(self, x):
+        """
+        Return an element of this free algebra.
+
+        INPUT:
+
+        An element of a free algebra with a proper subset of generator
+        names, or anything that can be interpreted in the polynomial
+        ring that is used to implement the letterplace algebra out to
+        the current degree bound, or a string that can be interpreted
+        as an expression in the algebra (provided that the
+        coefficients are numerical).
+
+        EXAMPLE::
+
+            sage: F.<t,y,z> = FreeAlgebra(ZZ, implementation='letterplace', degrees=[4,2,3])
+
+        Conversion of a number::
+
+            sage: F(3)
+            3
+
+        Interpretation of a string as an algebra element::
+
+            sage: F('t*y+3*z^2')
+            t*y + 3*z*z
+
+        Conversion from the currently underlying polynomial ring::
+
+            sage: F.set_degbound(3)
+            sage: P = F.current_ring()
+            sage: F(P.0*P.7*P.11*P.15*P.17*P.23 - 2*P.2*P.7*P.11*P.14*P.19*P.23)
+            t*y - 2*z*z
+
+        Conversion from a graded sub-algebra::
+
+            sage: G = FreeAlgebra(GF(5), implementation='letterplace', names=['x','y','z','t'], degrees=[1,2,3,4])
+            sage: G(t*y + 2*y^3 - 4*z^2)   # indirect doctest
+            (2)*y*y*y + z*z + t*y
+
+        """
+        if isinstance(x, basestring):
+            from sage.all import sage_eval
+            return sage_eval(x,locals=self.gens_dict())
+        try:
+            P = x.parent()
+        except AttributeError:
+            P = None
+        if P is self:
+            (<FreeAlgebraElement_letterplace>x)._poly = self._current_ring((<FreeAlgebraElement_letterplace>x)._poly)
+            return x
+        if isinstance(P, FreeAlgebra_letterplace):
+            self.set_degbound(P.degbound())
+            Ppoly = (<FreeAlgebra_letterplace>P)._current_ring
+            Gens = self._current_ring.gens()
+            Names = self._current_ring.variable_names()
+            PNames = list(Ppoly.variable_names())
+            # translate the slack variables
+            PNames[P.ngens(): len(PNames): P.ngens()+1] = list(Names[self.ngens(): len(Names): self.ngens()+1])[:P.degbound()]
+            x = Ppoly.hom([Gens[Names.index(asdf)] for asdf in PNames])(x.letterplace_polynomial())
+        return FreeAlgebraElement_letterplace(self,self._current_ring(x))

new file sage/algebras/letterplace/letterplace_ideal.pyx

@@ +1 @@
+###############################################################################
+#
+#       Copyright (C) 2011 Simon King <simon.king@uni-jena.de>
+#  Distributed under the terms of the GNU General Public License (GPL),
+#  version 2 or any later version.  The full text of the GPL is available at:
+#                  http://www.gnu.org/licenses/
+#
+###############################################################################
+
+"""
+Homogeneous ideals of free algebras.
+
+For twosided ideals and when the base ring is a field, this
+implementation also provides Groebner bases and ideal containment
+tests.
+
+EXAMPLES::
+
+    sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+    sage: F
+    Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+    sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+    sage: I
+    Twosided Ideal (x*y + y*z, x*x + x*y - y*x - y*y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+One can compute Groebner bases out to a finite degree, can compute normal
+forms and can test containment in the ideal::
+
+    sage: I.groebner_basis(degbound=3)
+    Twosided Ideal (y*y*y - y*y*z + y*z*y - y*z*z, y*y*x + y*y*z + y*z*x + y*z*z, x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+    sage: (x*y*z*y*x).normal_form(I)
+    y*z*z*y*z + y*z*z*z*x + y*z*z*z*z
+    sage: x*y*z*y*x - (x*y*z*y*x).normal_form(I) in I
+    True
+
+AUTHOR:
+
+- Simon King (2011-03-22):  See :trac:`7797`.
+
+"""
+
+from sage.rings.noncommutative_ideals import Ideal_nc
+from sage.libs.singular.function import lib, singular_function
+from sage.algebras.letterplace.free_algebra_letterplace cimport FreeAlgebra_letterplace
+from sage.algebras.letterplace.free_algebra_element_letterplace cimport FreeAlgebraElement_letterplace
+from sage.all import Infinity
+
+#####################
+# Define some singular functions
+lib("freegb.lib")
+singular_system=singular_function("system")
+poly_reduce=singular_function("NF")
+
+class LetterplaceIdeal(Ideal_nc):
+    """
+    Graded homogeneous ideals in free algebras.
+
+    In the two-sided case over a field, one can compute Groebner bases
+    up to a degree bound, normal forms of graded homogeneous elements
+    of the free algebra, and ideal containment.
+
+    EXAMPLES::
+
+        sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+        sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+        sage: I
+        Twosided Ideal (x*y + y*z, x*x + x*y - y*x - y*y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+        sage: I.groebner_basis(2)
+        Twosided Ideal (x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+        sage: I.groebner_basis(4)
+        Twosided Ideal (y*z*y*y - y*z*y*z + y*z*z*y - y*z*z*z, y*z*y*x + y*z*y*z + y*z*z*x + y*z*z*z, y*y*z*y - y*y*z*z + y*z*z*y - y*z*z*z, y*y*z*x + y*y*z*z + y*z*z*x + y*z*z*z, y*y*y - y*y*z + y*z*y - y*z*z, y*y*x + y*y*z + y*z*x + y*z*z, x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+    Groebner bases are cached. If one has computed a Groebner basis
+    out to a high degree then it will also be returned if a Groebner
+    basis with a lower degree bound is requested::
+
+        sage: I.groebner_basis(2)
+        Twosided Ideal (y*z*y*y - y*z*y*z + y*z*z*y - y*z*z*z, y*z*y*x + y*z*y*z + y*z*z*x + y*z*z*z, y*y*z*y - y*y*z*z + y*z*z*y - y*z*z*z, y*y*z*x + y*y*z*z + y*z*z*x + y*z*z*z, y*y*y - y*y*z + y*z*y - y*z*z, y*y*x + y*y*z + y*z*x + y*z*z, x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+    Of course, the normal form of any element has to satisfy the following::
+
+        sage: x*y*z*y*x - (x*y*z*y*x).normal_form(I) in I
+        True
+
+    Left and right ideals can be constructed, but only twosided ideals provide
+    Groebner bases::
+
+        sage: JL = F*[x*y+y*z,x^2+x*y-y*x-y^2]; JL
+        Left Ideal (x*y + y*z, x*x + x*y - y*x - y*y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+        sage: JR = [x*y+y*z,x^2+x*y-y*x-y^2]*F; JR
+        Right Ideal (x*y + y*z, x*x + x*y - y*x - y*y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+        sage: JR.groebner_basis(2)
+        Traceback (most recent call last):
+        ...
+        TypeError: This ideal is not two-sided. We can only compute two-sided Groebner bases
+        sage: JL.groebner_basis(2)
+        Traceback (most recent call last):
+        ...
+        TypeError: This ideal is not two-sided. We can only compute two-sided Groebner bases
+
+    Also, it is currently not possible to compute a Groebner basis when the base
+    ring is not a field::
+
+        sage: FZ.<a,b,c> = FreeAlgebra(ZZ, implementation='letterplace')
+        sage: J = FZ*[a^3-b^3]*FZ
+        sage: J.groebner_basis(2)
+        Traceback (most recent call last):
+        ...
+        TypeError: Currently, we can only compute Groebner bases if the ring of coefficients is a field
+
+    The letterplace implementation of free algebras also provides integral degree weights
+    for the generators, and we can compute Groebner bases for twosided graded homogeneous
+    ideals::
+
+        sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace',degrees=[1,2,3])
+        sage: I = F*[x*y+z-y*x,x*y*z-x^6+y^3]*F
+        sage: I.groebner_basis(Infinity)
+        Twosided Ideal (x*z*z - y*x*x*z - y*x*y*y + y*x*z*x + y*y*y*x + z*x*z + z*y*y - z*z*x,
+        x*y - y*x + z,
+        x*x*x*x*z*y*y + x*x*x*z*y*y*x - x*x*x*z*y*z - x*x*z*y*x*z + x*x*z*y*y*x*x +
+        x*x*z*y*y*y - x*x*z*y*z*x - x*z*y*x*x*z - x*z*y*x*z*x +
+        x*z*y*y*x*x*x + 2*x*z*y*y*y*x - 2*x*z*y*y*z - x*z*y*z*x*x -
+        x*z*y*z*y + y*x*z*x*x*x*x*x - 4*y*x*z*x*x*z - 4*y*x*z*x*z*x +
+        4*y*x*z*y*x*x*x + 3*y*x*z*y*y*x - 4*y*x*z*y*z + y*y*x*x*x*x*z +
+        y*y*x*x*x*z*x - 3*y*y*x*x*z*x*x - y*y*x*x*z*y +
+        5*y*y*x*z*x*x*x + 4*y*y*x*z*y*x - 4*y*y*y*x*x*z +
+        4*y*y*y*x*z*x + 3*y*y*y*y*z + 4*y*y*y*z*x*x + 6*y*y*y*z*y +
+        y*y*z*x*x*x*x + y*y*z*x*z + 7*y*y*z*y*x*x + 7*y*y*z*y*y -
+        7*y*y*z*z*x - y*z*x*x*x*z - y*z*x*x*z*x + 3*y*z*x*z*x*x +
+        y*z*x*z*y + y*z*y*x*x*x*x - 3*y*z*y*x*z + 7*y*z*y*y*x*x +
+        3*y*z*y*y*y - 3*y*z*y*z*x - 5*y*z*z*x*x*x - 4*y*z*z*y*x +
+        4*y*z*z*z - z*y*x*x*x*z - z*y*x*x*z*x - z*y*x*z*x*x -
+        z*y*x*z*y + z*y*y*x*x*x*x - 3*z*y*y*x*z + 3*z*y*y*y*x*x +
+        z*y*y*y*y - 3*z*y*y*z*x - z*y*z*x*x*x - 2*z*y*z*y*x +
+        2*z*y*z*z - z*z*x*x*x*x*x + 4*z*z*x*x*z + 4*z*z*x*z*x -
+        4*z*z*y*x*x*x - 3*z*z*y*y*x + 4*z*z*y*z + 4*z*z*z*x*x +
+        2*z*z*z*y,
+        x*x*x*x*x*z + x*x*x*x*z*x + x*x*x*z*x*x + x*x*z*x*x*x + x*z*x*x*x*x +
+        y*x*z*y - y*y*x*z + y*z*z + z*x*x*x*x*x - z*z*y,
+        x*x*x*x*x*x - y*x*z - y*y*y + z*z)
+        of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+    Again, we can compute normal forms::
+
+        sage: (z*I.0-I.1).normal_form(I)
+        0
+        sage: (z*I.0-x*y*z).normal_form(I)
+        -y*x*z + z*z
+
+    """
+    def __init__(self, ring, gens, coerce=True, side = "twosided"):
+        """
+        INPUT:
+
+        - ``ring``: A free algebra in letterplace implementation.
+        - ``gens``: List, tuple or sequence of generators.
+        - ``coerce`` (optional bool, default ``True``):
+          Shall ``gens`` be coerced first?
+        - ``side``: optional string, one of ``"twosided"`` (default),
+          ``"left"`` or ``"right"``. Determines whether the ideal
+          is a left, right or twosided ideal. Groebner bases or
+          only supported in the twosided case.
+
+        TEST::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: from sage.algebras.letterplace.letterplace_ideal import LetterplaceIdeal
+            sage: LetterplaceIdeal(F,x)
+            Twosided Ideal (x) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+            sage: LetterplaceIdeal(F,[x,y],side='left')
+            Left Ideal (x, y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+        It is not correctly detected that this class inherits from an
+        extension class. Therefore, we have to skip one item of the
+        test suite::
+
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: TestSuite(I).run(skip=['_test_category'],verbose=True)
+            running ._test_eq() . . . pass
+            running ._test_not_implemented_methods() . . . pass
+            running ._test_pickling() . . . pass
+
+        """
+        Ideal_nc.__init__(self, ring, gens, coerce=coerce, side=side)
+        self.__GB = self
+        self.__uptodeg = 0
+    def groebner_basis(self, degbound=None):
+        """
+        Twosided Groebner basis with degree bound.
+
+        INPUT:
+
+        - ``degbound`` (optional integer, or Infinity): If it is provided,
+          a Groebner basis at least out to that degree is returned. By
+          default, the current degree bound of the underlying ring is used.
+
+        ASSUMPTIONS:
+
+        Currently, we can only compute Groebner bases for twosided
+        ideals, and the ring of coefficients must be a field. A
+        `TypeError` is raised if one of these conditions is violated.
+
+        NOTES:
+
+        - The result is cached. The same Groebner basis is returned
+          if a smaller degree bound than the known one is requested.
+        - If the degree bound Infinity is requested, it is attempted to
+          compute a complete Groebner basis. But we can not guarantee
+          that the computation will terminate, since not all twosided
+          homogeneous ideals of a free algebra have a finite Groebner
+          basis.
+
+        EXAMPLES::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+
+        Since `F` was cached and since its degree bound can not be
+        decreased, it may happen that, as a side effect of other tests,
+        it already has a degree bound bigger than 3. So, we can not
+        test against the output of ``I.groebner_basis()``::
+
+            sage: F.set_degbound(3)
+            sage: I.groebner_basis()   # not tested
+            Twosided Ideal (y*y*y - y*y*z + y*z*y - y*z*z, y*y*x + y*y*z + y*z*x + y*z*z, x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+            sage: I.groebner_basis(4)
+            Twosided Ideal (y*z*y*y - y*z*y*z + y*z*z*y - y*z*z*z, y*z*y*x + y*z*y*z + y*z*z*x + y*z*z*z, y*y*z*y - y*y*z*z + y*z*z*y - y*z*z*z, y*y*z*x + y*y*z*z + y*z*z*x + y*z*z*z, y*y*y - y*y*z + y*z*y - y*z*z, y*y*x + y*y*z + y*z*x + y*z*z, x*y + y*z, x*x - y*x - y*y - y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+            sage: I.groebner_basis(2) is I.groebner_basis(4)
+            True
+            sage: G = I.groebner_basis(4)
+            sage: G.groebner_basis(3) is G
+            True
+
+        If a finite complete Groebner basis exists, we can compute
+        it as follows::
+
+            sage: I = F*[x*y-y*x,x*z-z*x,y*z-z*y,x^2*y-z^3,x*y^2+z*x^2]*F
+            sage: I.groebner_basis(Infinity)
+            Twosided Ideal (z*z*z*y*y + z*z*z*z*x, z*x*x*x + z*z*z*y, y*z - z*y, y*y*x + z*x*x, y*x*x - z*z*z, x*z - z*x, x*y - y*x) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+        Since the commutators of the generators are contained in the ideal,
+        we can verify the above result by a computation in a polynomial ring
+        in negative lexicographic order::
+
+            sage: P.<c,b,a> = PolynomialRing(QQ,order='neglex')
+            sage: J = P*[a^2*b-c^3,a*b^2+c*a^2]
+            sage: J.groebner_basis()
+            [b*a^2 - c^3, b^2*a + c*a^2, c*a^3 + c^3*b, c^3*b^2 + c^4*a]
+
+        Aparently, the results are compatible, by sending `a` to `x`, `b`
+        to `y` and `c` to `z`.
+
+        """
+        cdef FreeAlgebra_letterplace A = self.ring()
+        cdef FreeAlgebraElement_letterplace x
+        if degbound is None:
+            degbound = A.degbound()
+        if self.__uptodeg >= degbound:
+            return self.__GB
+        if not A.base().is_field():
+            raise TypeError, "Currently, we can only compute Groebner bases if the ring of coefficients is a field"
+        if self.side()!='twosided':
+            raise TypeError, "This ideal is not two-sided. We can only compute two-sided Groebner bases"
+        if degbound == Infinity:
+            while self.__uptodeg<Infinity:
+                test_bound = 2*max([x._poly.degree() for x in self.__GB.gens()])
+                self.groebner_basis(test_bound)
+            return self.__GB
+        # Set the options required by letterplace
+        from sage.libs.singular.option import LibSingularOptions
+        libsingular_options = LibSingularOptions()
+        bck = (libsingular_options['redTail'],libsingular_options['redSB'])
+        libsingular_options['redTail'] = True
+        libsingular_options['redSB'] = True
+        A.set_degbound(degbound)
+        P = A._current_ring
+        out = [FreeAlgebraElement_letterplace(A,X,check=False) for X in
+               singular_system("freegb",P.ideal([x._poly for x in self.__GB.gens()]),
+                               degbound,A.__ngens, ring = P)]
+        libsingular_options['redTail'] = bck[0]
+        libsingular_options['redSB'] = bck[1]
+        self.__GB = A.ideal(out,side='twosided',coerce=False)
+        if degbound >= 2*max([x._poly.degree() for x in out]):
+            degbound = Infinity
+        self.__uptodeg = degbound
+        self.__GB.__uptodeg = degbound
+        return self.__GB
+
+    def __contains__(self,x):
+        """
+        The containment test is based on a normal form computation.
+
+        EXAMPLES::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: x*I.0-I.1*y+I.0*y in I    # indirect doctest
+            True
+            sage: 1 in I
+            False
+
+        """
+        R = self.ring()
+        return (x in R) and R(x).normal_form(self).is_zero()
+
+    def reduce(self, G):
+        """
+        Reduction of this ideal by another ideal,
+        or normal form of an algebra element with respect to this ideal.
+
+        INPUT:
+
+        - ``G``: A list or tuple of elements, an ideal,
+          the ambient algebra, or a single element.
+
+        OUTPUT:
+
+        - The normal form of ``G`` with respect to this ideal, if
+          ``G`` is an element of the algebra.
+        - The reduction of this ideal by the elements resp. generators
+          of ``G``, if ``G`` is a list, tuple or ideal.
+        - The zero ideal, if ``G`` is the algebra containing this ideal.
+
+        EXAMPLES::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: I.reduce(F)
+            Twosided Ideal (0) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+            sage: I.reduce(x^3)
+            -y*z*x - y*z*y - y*z*z
+            sage: I.reduce([x*y])
+            Twosided Ideal (y*z, x*x - y*x - y*y) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+            sage: I.reduce(F*[x^2+x*y,y^2+y*z]*F)
+            Twosided Ideal (x*y + y*z, -y*x + y*z) of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field
+
+        """
+        P = self.ring()
+        if not isinstance(G,(list,tuple)):
+            if G==P:
+                return P.ideal([P.zero_element()])
+            if G in P:
+                return G.normal_form(self)
+            G = G.gens()
+        C = P.current_ring()
+        sI = C.ideal([C(X.letterplace_polynomial()) for X in self.gens()], coerce=False)
+        selfdeg = max([x.degree() for x in sI.gens()])
+        gI = P._reductor_(G, selfdeg)
+        from sage.libs.singular.option import LibSingularOptions
+        libsingular_options = LibSingularOptions()
+        bck = (libsingular_options['redTail'],libsingular_options['redSB'])
+        libsingular_options['redTail'] = True
+        libsingular_options['redSB'] = True
+        sI = poly_reduce(sI,gI, ring=C, attributes={gI:{"isSB":1}})
+        libsingular_options['redTail'] = bck[0]
+        libsingular_options['redSB'] = bck[1]
+        return P.ideal([FreeAlgebraElement_letterplace(P,x,check=False) for x in sI], coerce=False)

sage/categories/rings.py

@@ -108 +108 @@
             rings also inherits from the base class of
             rings. Therefore, we implemented a ``__mul__``
             method for parents, that calls a ``_mul_``
-            method implemented here. See trac ticket #11068.
+            method implemented here. See :trac:`7797`.
 
             INPUT:
 
@@ -190 +190 @@
             The code is copied from the base class of rings.
             This is since there are rings that do not inherit
             from that class, such as matrix algebras.  See
-            trac ticket #11068.
+            :trac:`7797`.
 
             EXAMPLE::
 
@@ -267 +267 @@
             :class:`~sage.rings.ring.Ring`. This is
             because there are rings that do not inherit
             from that class, such as matrix algebras.
-            See trac ticket #11068.
+            See :trac:`7797`.
 
             INPUT:
 
@@ -439 +439 @@
             - ``names``: a list of strings to be used as names
               for the variables in the quotient ring.
 
-            EXAMPLES::
+            EXAMPLES:
 
-                sage: F.<x,y,z> = FreeAlgebra(QQ, 3)
-                sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            Usually, a ring inherits a method :meth:`sage.rings.ring.Ring.quotient`.
+            So, we need a bit of effort to make the following example work with the
+            category framework::
+
+                sage: F.<x,y,z> = FreeAlgebra(QQ)
+                sage: from sage.rings.noncommutative_ideals import Ideal_nc
+                sage: class PowerIdeal(Ideal_nc):
+                ...    def __init__(self, R, n):
+                ...        self._power = n
+                ...        self._power = n
+                ...        Ideal_nc.__init__(self,R,[R.prod(m) for m in CartesianProduct(*[R.gens()]*n)])
+                ...    def reduce(self,x):
+                ...        R = self.ring()
+                ...        return add([c*R(m) for c,m in x if len(m)<self._power],R(0))
+                ...
+                sage: I = PowerIdeal(F,3)
                 sage: Q = Rings().parent_class.quotient(F,I); Q
-                Quotient of Free Algebra on 3 generators (x, y, z) over Rational Field by the ideal (x*y + y*z, x^2 + x*y - y*x - y^2)
+                Quotient of Free Algebra on 3 generators (x, y, z) over Rational Field by the ideal (x^3, x^2*y, x^2*z, x*y*x, x*y^2, x*y*z, x*z*x, x*z*y, x*z^2, y*x^2, y*x*y, y*x*z, y^2*x, y^3, y^2*z, y*z*x, y*z*y, y*z^2, z*x^2, z*x*y, z*x*z, z*y*x, z*y^2, z*y*z, z^2*x, z^2*y, z^3)
                 sage: Q.0
                 xbar
                 sage: Q.1
                 ybar
                 sage: Q.2
                 zbar
+                sage: Q.0*Q.1
+                xbar*ybar
+                sage: Q.0*Q.1*Q.0
+                0
 
             """
             from sage.rings.quotient_ring import QuotientRing

sage/rings/noncommutative_ideals.pyx

@@ -12 +12 @@
 
 AUTHOR:
 
-- Simon King (2011-03-28), <simon.king@uni-jena.de>: Trac ticket #11068.
+- Simon King (2011-03-21), <simon.king@uni-jena.de>, :trac:`7797`.
 
 EXAMPLES::
 
@@ -39 +39 @@
     )
      of Full MatrixSpace of 2 by 2 dense matrices over Integer Ring
 
+See :mod:`~sage.algebras.letterplace.letterplace_ideal` for a more
+elaborate implementation in the special case of ideals in free
+algebras.
+
 TEST::
 
     sage: A = SteenrodAlgebra(2)
@@ -137 +141 @@
     Generic non-commutative ideal.
 
     All fancy stuff such as the computation of Groebner bases must be
-    implemented in sub-classes.
+    implemented in sub-classes. See :class:`~sage.algebras.letterplace.letterplace_ideal.LetterplaceIdeal`
+    for an example.
 
     EXAMPLE::
 

sage/rings/quotient_ring.py

@@ -21 +21 @@
 provides a ``reduce`` method so that ``I.reduce(x)`` is the normal
 form of an element `x` with respect to `I` (i.e., we have
 ``I.reduce(x)==I.reduce(y)`` if `x-y\\in I`, and
-``x-I.reduce(x) in I``). It is planned (trac ticket #7797) to
-provide this for the case of homogeneous twosided ideals in free
-algebras. By now, we only have the following toy example::
+``x-I.reduce(x) in I``). Here is a toy example::
 
     sage: from sage.rings.noncommutative_ideals import Ideal_nc
     sage: class PowerIdeal(Ideal_nc):
@@ -75 +73 @@
     sage: (a+b+2)^4
     16 + 32*a + 32*b
 
+Since trac ticket #7797, there is an implementation of free algebras
+based on Singular's implementation of the Letterplace Algebra. Our
+letterplace wrapper allows to provide the above toy example more
+easily::
+
+    sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+    sage: Q3 = F.quo(F*[F.prod(m) for m in CartesianProduct(*[F.gens()]*3)]*F)
+    sage: Q3
+    Quotient of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field by the ideal (x*x*x, x*x*y, x*x*z, x*y*x, x*y*y, x*y*z, x*z*x, x*z*y, x*z*z, y*x*x, y*x*y, y*x*z, y*y*x, y*y*y, y*y*z, y*z*x, y*z*y, y*z*z, z*x*x, z*x*y, z*x*z, z*y*x, z*y*y, z*y*z, z*z*x, z*z*y, z*z*z)
+    sage: Q3.0*Q3.1-Q3.1*Q3.0
+    xbar*ybar - ybar*xbar
+    sage: Q3.0*(Q3.1*Q3.2)-(Q3.1*Q3.2)*Q3.0
+    0
+    sage: Q2 = F.quo(F*[F.prod(m) for m in CartesianProduct(*[F.gens()]*2)]*F)
+    sage: Q2.is_commutative()
+    True
+
 """
 
 ###########################################################################
@@ -209 +224 @@
         sage: R.quotient(I)
         Ring of integers modulo 2
 
+    Here is an example of the quotient of a free algebra by a
+    twosided homogeneous ideal (see :trac:`7797`)::
+
+        sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+        sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+        sage: Q.<a,b,c> = F.quo(I); Q
+        Quotient of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field by the ideal (x*y + y*z, x*x + x*y - y*x - y*y)
+        sage: a*b
+        -b*c
+        sage: a^3
+        -b*c*a - b*c*b - b*c*c
+        sage: J = Q*[a^3-b^3]*Q
+        sage: R.<i,j,k> = Q.quo(J); R
+        Quotient of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field by the ideal (-y*y*z - y*z*x - 2*y*z*z, x*y + y*z, x*x + x*y - y*x - y*y)
+        sage: i^3
+        -j*k*i - j*k*j - j*k*k
+        sage: j^3
+        -j*k*i - j*k*j - j*k*k
+
     """
     # 1. Not all rings inherit from the base class of rings.
     # 2. We want to support quotients of free algebras by homogeneous two-sided ideals.
@@ -269 +303 @@
         sage: is_QuotientRing(R)
         False
 
+    ::
+
+        sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+        sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+        sage: Q = F.quo(I)
+        sage: is_QuotientRing(Q)
+        True
+        sage: is_QuotientRing(F)
+        False
+
     """
     return isinstance(x, QuotientRing_nc)
 
@@ -283 +327 @@
     """
     The quotient ring of `R` by a twosided ideal `I`.
     
-    This base class is for rings that do not inherit from :class:`~sage.rings.ring.CommutativeRing`.
-    Real life examples will be available with trac ticket #7797.
+    EXAMPLES:
+
+    This class is for rings that do not inherit from :class:`~sage.rings.ring.CommutativeRing`.
+    Here is a quotient of a free algebra by a twosided homogeneous ideal::
+
+        sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+        sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+        sage: Q.<a,b,c> = F.quo(I); Q
+        Quotient of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field by the ideal (x*y + y*z, x*x + x*y - y*x - y*y)
+        sage: a*b
+        -b*c
+        sage: a^3
+        -b*c*a - b*c*b - b*c*c
+
+    A quotient of a quotient is just the quotient of the original top
+    ring by the sum of two ideals::
+
+        sage: J = Q*[a^3-b^3]*Q
+        sage: R.<i,j,k> = Q.quo(J); R
+        Quotient of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field by the ideal (-y*y*z - y*z*x - 2*y*z*z, x*y + y*z, x*x + x*y - y*x - y*y)
+        sage: i^3
+        -j*k*i - j*k*j - j*k*k
+        sage: j^3
+        -j*k*i - j*k*j - j*k*k
 
     For rings that *do* inherit from :class:`~sage.rings.ring.CommutativeRing`, we provide
     a subclass :class:`QuotientRing_generic`, for backwards compatibility.
@@ -305 +371 @@
         sage: S(0) == a^2 + b^2
         True
     
-    A quotient of a quotient is just the quotient of the original top
+    Again, a quotient of a quotient is just the quotient of the original top
     ring by the sum of two ideals.
     
     ::
@@ -328 +394 @@
         -  ``R`` - a ring.
         -  ``I`` - a twosided ideal of `R`.
         - ``names`` - a list of generator names.
-        
+
+        EXAMPLES::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: Q.<a,b,c> = F.quo(I); Q
+            Quotient of Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field by the ideal (x*y + y*z, x*x + x*y - y*x - y*y)
+            sage: a*b
+            -b*c
+            sage: a^3
+            -b*c*a - b*c*b - b*c*c
+
         """
         if R not in _Rings:
             raise TypeError, "The first argument must be a ring, but %s is not"%R
@@ -365 +442 @@
             sage: I = R.ideal([4 + 3*x + x^2, 1 + x^2])
             sage: R.quotient_ring(I).construction()
             (QuotientFunctor, Univariate Polynomial Ring in x over Integer Ring)
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: Q = F.quo(I)
+            sage: Q.construction()
+            (QuotientFunctor, Free Associative Unital Algebra on 3 generators (x, y, z) over Rational Field)
 
         TESTS::
         
@@ -422 +504 @@
 
         AUTHOR:
 
-        - Simon King (2011-03-23): See trac ticket #11068.
+        - Simon King (2011-03-23): See :trac:`7797`.
 
         EXAMPLES:
 
@@ -432 +514 @@
             sage: P.quo(P.random_element()).is_commutative()
             True
 
-        The non-commutative case is more interesting, but it
-        will only be available once trac ticket #7797 is merged.
+        The non-commutative case is more interesting::
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: Q = F.quo(I)
+            sage: Q.is_commutative()
+            False
+            sage: Q.1*Q.2==Q.2*Q.1
+            False
+
+        In the next example, the generators apparently commute::
+
+            sage: J = F*[x*y-y*x,x*z-z*x,y*z-z*y,x^3-y^3]*F
+            sage: R = F.quo(J)
+            sage: R.is_commutative()
+            True
 
         """
         try:

sage/rings/quotient_ring_element.py

@@ -533 +533 @@
             0
             sage: a.__cmp__(b)
             1
+
+        See :trac:`7797`:
+
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: Q = F.quo(I)
+            sage: Q.0^4    # indirect doctest
+            ybar*zbar*zbar*xbar + ybar*zbar*zbar*ybar + ybar*zbar*zbar*zbar
+
         """
         #if self.__rep == other.__rep or ((self.__rep - other.__rep) in self.parent().defining_ideal()):
         #    return 0

sage/rings/ring.pyx

@@ -409 +409 @@
             sage: Q = sage.rings.ring.Ring.quotient(F,I)
             sage: Q.ideal_monoid()
             Monoid of ideals of Quotient of Free Algebra on 3 generators (x, y, z) over Integer Ring by the ideal (x*y + y*z, x^2 + x*y - y*x - y^2)
+            sage: F.<x,y,z> = FreeAlgebra(ZZ, implementation='letterplace')
+            sage: I = F*[x*y+y*z,x^2+x*y-y*x-y^2]*F
+            sage: Q = F.quo(I)
+            sage: Q.ideal_monoid()
+            Monoid of ideals of Quotient of Free Associative Unital Algebra on 3 generators (x, y, z) over Integer Ring by the ideal (x*y + y*z, x*x + x*y - y*x - y*y)
 
         """
         if self.__ideal_monoid is not None:
@@ -536 +541 @@
             sage: (x+y,z+y^3)*R
             Ideal (x + y, y^3 + z) of Multivariate Polynomial Ring in x, y, z over Finite Field of size 7
 
-        The following was implemented in trac ticket #11068::
+        The following was implemented in :trac:`7797`::
 
             sage: A = SteenrodAlgebra(2)
             sage: A*[A.1+A.2,A.1^2]
@@ -609 +614 @@
             sage: RR._ideal_class_()
             <class 'sage.rings.ideal.Ideal_pid'>
 
-        Since #11068, non-commutative rings have ideals as well::
+        Since :trac:`7797`, non-commutative rings have ideals as well::
 
             sage: A = SteenrodAlgebra(2)
             sage: A._ideal_class_()

sage/structure/parent.pyx

@@ -814 +814 @@
         is because ``__mul__`` can not be implemented via inheritance
         from the parent methods of the category, but ``_mul_`` can
         be inherited. This is, e.g., used when creating twosided
-        ideals of matrix algebras. See trac ticket #11068.
+        ideals of matrix algebras. See :trac:`7797`.
 
         EXAMPLE::
 
+            sage: F.<x,y,z> = FreeAlgebra(QQ, implementation='letterplace')
             sage: MS = MatrixSpace(QQ,2,2)
 
         This matrix space is in fact an algebra, and in particular

setup.py

@@ -855 +855 @@
       packages    = ['sage',
                      
                      'sage.algebras',
+                     'sage.algebras.letterplace',
                      'sage.algebras.quatalg',
                      'sage.algebras.steenrod',