Ticket #9280: trac_9280-graded-algebras-example.patch

doc/en/reference/categories.rst

@@ -133 +133 @@
    sage/categories/examples/commutative_additive_monoids
    sage/categories/examples/commutative_additive_semigroups
    sage/categories/examples/coxeter_groups
+   sage/categories/examples/graded_algebras_with_basis
    sage/categories/examples/finite_coxeter_groups
    sage/categories/examples/finite_enumerated_sets
    sage/categories/examples/finite_monoids

sage/categories/algebras_with_basis.py

@@ -104 +104 @@
 
     def example(self, alphabet = ('a','b','c')):
         """
-        Returns an example of algebra with basis::
+        Returns an example of algebra with basis as per
+        :meth:`Category.example <sage.categories.category.Category.example>`.
+
+        ::
 
             sage: AlgebrasWithBasis(QQ).example()
             An example of an algebra with basis: the free algebra on the generators ('a', 'b', 'c') over Rational Field

new file sage/categories/examples/graded_algebras_with_basis.py

@@ +1 @@
+r"""
+Examples of graded algebras with basis
+"""
+#*****************************************************************************
+#  Copyright (C) 2010 John H. Palmieri <palmieri@math.washington.edu>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  http://www.gnu.org/licenses/
+#*****************************************************************************
+
+from sage.misc.cachefunc import cached_method
+from sage.categories.all import GradedAlgebrasWithBasis
+from sage.combinat.free_module import CombinatorialFreeModule, CombinatorialFreeModuleElement
+
+def basis_function(d, degrees):
+    """
+    INPUT:
+
+    - ``d`` - non-negative integer, the degree in which you want the basis
+    - ``degrees`` - list or tuple of positive integers, the degrees of
+      the polynomial generators
+
+    OUTPUT: list of lists representing the basis in degree `d`.  Each
+    list represents a monomial in a graded polynomial algebra with
+    generators graded by ``degrees``: if the generators are `(x_1,
+    ..., x_n)`, then a tuple `(e_1, ..., e_n)` in the output
+    represents the monomial `x_1^{e_1} ... x_n^{e_n}`.
+
+    EXAMPLES::
+
+        sage: from sage.categories.examples.graded_algebras_with_basis import basis_function
+        sage: basis_function(3, [1,2])
+        [[1, 1], [3, 0]]
+        sage: basis_function(3, [2,1])
+        [[1, 1], [0, 3]]
+        sage: basis_function(3, [1,1])
+        [[0, 3], [1, 2], [2, 1], [3, 0]]
+        sage: basis_function(3, [2,2])
+        []
+        sage: basis_function(-8, [1,2,3]) # always zero in negative degrees
+        []
+    """
+    from sage.combinat.integer_vector_weighted import WeightedIntegerVectors
+    # The following doesn't work: it leads to failures of the
+    # TestSuite.  A bug somewhere, presumably...
+    # return WeightedIntegerVectors(d, degrees)
+    return WeightedIntegerVectors(d, degrees).list()
+
+class GradedPolynomialAlgebra(CombinatorialFreeModule):
+    r"""
+    This class illustrates an implementation of a graded algebra
+    with basis: a polynomial algebra on several generators of varying
+    degrees.
+
+    INPUT:
+
+    - ``R`` - base ring
+
+    - ``generators`` - list of strings defining the polynomial
+      generators (optional, default ``("a", "b", "c")``)
+
+    - ``degrees`` - a positive integer or a list of positive integers
+      (optional, default ``1``).  If it is a list of positive
+      integers, then it must be of the same length as ``generators``,
+      and its `i`-th entry specifies the degree of the `i`-th
+      generator.  If it is an integer `d`, then every generator is
+      given degree `d`.
+
+    .. note:: 
+
+        This is not a very full-featured implementation of a
+        polynomial algebra; you can add and multiply elements and
+        compute their degrees, but not much else.  For real
+        calculations, use Sage's ``PolynomialRing`` construction.
+
+    The implementation involves the following:
+
+    - A choice of how to represent elements.  In this case, the basis
+      elements are monomials in the generators, and each monomial is
+      represented as a tuple corresponding to the exponents of the
+      generators.  The algebra is constructed as a
+      :class:`CombinatorialFreeModule
+      <sage.combinat.free_module.CombinatorialFreeModule>` on the
+      basis of monomials, so it inherits all of the methods for such
+      objects, and has operations like addition already defined.
+
+    - A basis function - this algebra is graded by the non-negative
+      integers, so there is a function defined in this module,
+      creatively called :func:`basis_function`, which takes an integer
+      `d` as input and returns a list of tuples representing a basis
+      for the algebra in degree `d`.
+
+    - If the algebra is called ``A``, then its basis function is
+      stored as ``A._basis_fcn``.  Thus the function can be used to
+      find a basis for the degree `d` piece: essentially, just call
+      ``A._basis_fcn(d)``.  More precisely, call ``A.monomial(x)`` for
+      each ``x`` in ``A._basis_fcn(d)``.  See also the method
+      :meth:`basis`.
+
+    - A :meth:`homogeneous_component` method, returning the degree `d`
+      piece of `A`.
+
+    - For dealing with basis elements: :meth:`product_on_basis`,
+      :meth:`degree_on_basis`, and :meth:`_repr_term`. The first of
+      these defines the product by defining it on the tuples which
+      define basis elements; the product on arbitrary elements is
+      determined by linearity.  Similarly, the second of these defines
+      the degree of any monomial, and then the :meth:`degree
+      <GradedPolynomialAlgebra.Element.degree>` method for elements --
+      see the next item -- uses it to compute the degree for a linear
+      combination of monomials.  The last of these determines the
+      print representation for monomials, which automatically produces
+      the print representation for general elements.
+
+    - There is a class for elements, which inherits from
+      :class:`CombinatorialFreeModuleElement
+      <sage.combinat.free_module.CombinatorialFreeModuleElement>`.  An
+      element is determined by a dictionary whose keys are tuples
+      (representing monomials, as described above) and whose
+      corresponding values are the coefficients.  The class implements
+      two things: an :meth:`is_homogeneous
+      <GradedPolynomialAlgebra.Element.is_homogeneous>` method and a
+      :meth:`degree <GradedPolynomialAlgebra.Element.degree>` method.
+    """
+    def __init__(self, R, generators=("a", "b", "c"), degrees=1):
+        """
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example(); A
+            An example of a graded algebra with basis: the polynomial algebra on generators ('a', 'b', 'c') of degrees (1, 1, 1) over Rational Field
+            sage: A = GradedAlgebrasWithBasis(QQ).example(generators=("x", "y"), degrees=(2, 3)); A
+            An example of a graded algebra with basis: the polynomial algebra on generators ('x', 'y') of degrees (2, 3) over Rational Field
+            sage: TestSuite(A).run()
+        """
+        from sage.sets.all import Family, NonNegativeIntegers
+        from sage.rings.all import Integer
+        from functools import partial
+        self._generators = generators
+        try:
+            Integer(degrees)
+            if degrees <= 0:
+                raise ValueError, "Degrees must be positive integers"
+            degrees = [degrees] * len(generators)
+        except TypeError:
+            # assume degrees is a list or tuple already.
+            if len(degrees) != len(generators):
+                raise ValueError, "List of generators and degrees must have the same length"
+            try:
+                for d in degrees:
+                    assert Integer(d) > 0
+            except (TypeError, AssertionError):
+                raise ValueError, "Degrees must be positive integers"
+        self._degrees = tuple(degrees)
+        NN = NonNegativeIntegers()
+        # Use "partial" to make the basis function (with the degrees
+        # argument specified) pickleable.  Otherwise, it seems to
+        # cause problems...
+        self._basis_fcn = partial(basis_function, degrees=degrees)
+        CombinatorialFreeModule.__init__(self, R,
+                                         Family(NN, self._basis_fcn),
+                                         category=GradedAlgebrasWithBasis(R))
+
+    @cached_method
+    def one_basis(self):
+        """
+        Returns a tuple of all zeroes, which indexes the one of this
+        algebra, as per
+        :meth:`AlgebrasWithBasis.ParentMethods.one_basis
+        <sage.categories.algebras_with_basis.AlgebrasWithBasis.ParentMethods.one_basis`.
+
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example()
+            sage: A.one_basis()
+            (0, 0, 0)
+            sage: A.one()
+            1
+        """
+        return (0,) * len(self._generators)
+
+    def product_on_basis(self, t1, t2):
+        r"""
+        Product of basis elements, as per
+        :meth:`AlgebrasWithBasis.ParentMethods.product_on_basis
+        <sage.categories.algebras_with_basis.AlgebrasWithBasis.ParentMethods.product_on_basis`.
+
+        INPUT:
+
+        - ``t1``, ``t2`` - tuples determining monomials (as the
+          exponents of the generators) in this algebra
+
+        OUTPUT: the product of the two corresponding monomials, as an
+        element of self.
+
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example()
+            sage: A.product_on_basis((1,0,1), (0,0,2))
+            ac^{3}
+            sage: (a,b,c) = A.algebra_generators()
+            sage: a * (1-b)^2 * c
+            ac - 2*abc + ab^{2}c
+        """
+        return self.monomial(tuple([a+b for a,b in zip(t1, t2)]))
+
+    def degree_on_basis(self, t):
+        """
+        The degree of the element determined by the tuple ``t`` in
+        this graded polynomial algebra.
+
+        INPUT:
+
+        - ``t`` - a tuple determining a monomial (as the exponents of
+          the generators) in this algebra
+
+        OUTPUT: int, the degree of the corresponding monomial
+
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example(generators=("x", "y"), degrees=(2, 3))
+            sage: A.degree_on_basis((1,1)) # x^1 y^1
+            5
+            sage: A.degree_on_basis((0,3))
+            9
+        """
+        return sum([exp*deg for exp,deg in zip(t, self._degrees)])
+
+    @cached_method
+    def algebra_generators(self):
+        r"""
+        Returns the generators of this algebra, as per :meth:`Algebras.ParentMethods.algebra_generators`.
+
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example(); A
+            An example of a graded algebra with basis: the polynomial algebra on generators ('a', 'b', 'c') of degrees (1, 1, 1) over Rational Field
+            sage: A.algebra_generators()
+            Family (a, b, c)
+        """
+        from sage.sets.family import Family
+        L = len(self._generators)
+        return Family([self.monomial((0,) * i + (1,) + (0,) * (L-i-1)) for i in range(L)])
+
+    def homogeneous_component(self, n):
+        """
+        Returns the degree `n` piece of this graded algebra.
+
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example(generators=("x", "y"), degrees=(2, 3))
+            sage: A.homogeneous_component(1)  # zero
+            Free module generated by () over Rational Field
+            sage: A.homogeneous_component(6)
+            Free module generated by (y^{2}, x^{3}) over Rational Field
+
+        For this algebra, you can also access the homogeneous
+        components using square brackets::
+
+            sage: A[9]
+            Free module generated by (y^{3}, x^{3}y) over Rational Field
+        """
+        basis = tuple([tuple(a) for a in self._basis_fcn(n)])
+        M = CombinatorialFreeModule(self.base_ring(),
+                                    basis,
+                                    element_class=self.Element)
+        M._name = "Free module generated by %s"%(tuple(self.monomial(a) for a in basis),)
+        return M
+
+    # The following makes A[n] the same as
+    # A.homogeneous_components(n).  While a homogeneous_components
+    # method should be implemented for any graded object, whether
+    # __getitem__ should be defined and whether it should be the same
+    # as homogeneous_components (or return something else, e.g., an
+    # element of the algebra as in the case of
+    # SymmetricFunctions(QQ).schur()), should be decided on a
+    # case-by-case basis.
+    __getitem__ = homogeneous_component
+
+    def basis(self, d=None):
+        """
+        Returns the basis for this graded algebra, either the whole
+        basis or the basis in degree `d`.
+
+        INPUT:
+
+        - `d` - integer or None, optional (default None)
+
+        If `d` is None, then return a basis of the algebra.
+        Otherwise, return the basis in degree `d`.
+
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example(generators=("x", "y"), degrees=(2, 3))
+            sage: A.basis(4)
+            Family (x^{2},)
+            sage: A.basis(6)
+            Family (y^{2}, x^{3})
+            sage: A.basis(-10)
+            Family ()
+            sage: A.basis() # no argument: return the whole basis
+            Lazy family (Term map from Lazy family (<functools.partial object at ...>(i))_{i in Non negative integers} to An example of a graded algebra with basis: the polynomial algebra on generators ('x', 'y') of degrees (2, 3) over Rational Field(i))_{i in Lazy family (<functools.partial object at ...>(i))_{i in Non negative integers}}
+        """
+        from sage.sets.family import Family 
+        if d is None: 
+            return Family(self._basis_keys, self.monomial) 
+        else: 
+            return Family([self.monomial(tuple(a)) for a in self._basis_fcn(d)]) 
+
+    def _repr_(self):
+        """
+        Print representation
+
+        EXAMPLES::
+
+            sage: GradedAlgebrasWithBasis(QQ).example() # indirect doctest
+            An example of a graded algebra with basis: the polynomial algebra on generators ('a', 'b', 'c') of degrees (1, 1, 1) over Rational Field
+        """
+        return "An example of a graded algebra with basis: the polynomial algebra on generators %s of degrees %s over %s"%(self._generators, self._degrees, self.base_ring())
+
+
+    def _repr_term(self, t):
+        """
+        Print representation for the basis element represented by the
+        tuple ``t``.  This governs the behavior of the print
+        representation of all elements of the algebra.
+
+        EXAMPLES::
+
+            sage: A = GradedAlgebrasWithBasis(QQ).example(generators=("B", "H", "d"))
+            sage: A._repr_term((0,1,2))
+            'Hd^{2}'
+            sage: A._repr_term((2,3,1))
+            'B^{2}H^{3}d'
+        """
+        if len(t) == 0:
+            return "0"
+        if max(t) == 0:
+            return "1"
+        s = ""
+        for e,g in zip(t, self._generators):
+            if e != 0:
+                if e != 1:
+                    s += "%s^{%s}" % (g,e)
+                else:
+                    s += "%s" % g
+                s = s.strip()
+        return s
+
+    class Element(CombinatorialFreeModuleElement):
+        def is_homogeneous(self):
+            """
+            Return True iff this element is homogeneous.
+
+            EXAMPLES::
+
+                sage: A = GradedAlgebrasWithBasis(QQ).example(generators=("x", "y"), degrees=(2, 3))
+                sage: (x, y) = A.algebra_generators()
+                sage: (3*x).is_homogeneous()
+                True
+                sage: (x^3 - y^2).is_homogeneous()
+                True
+                sage: ((x + y)^2).is_homogeneous()
+                False
+            """
+            monos = self.support()
+            if len(monos) <= 1:
+                return True
+            degree = None 
+            deg = self.parent().degree_on_basis
+            for mono in monos:
+                if degree is None: 
+                    degree = deg(mono) 
+                elif deg(mono) != degree: 
+                    return False 
+            return True 
+
+        def degree(self):
+            """
+            The degree of this element in the graded polynomial algebra.
+
+            .. note::
+
+               This raises an error if the element is not homogeneous.
+               Another implementation option would be to return the
+               maximum of the degrees of the homogeneous summands.
+
+            EXAMPLES::
+
+                sage: A = GradedAlgebrasWithBasis(QQ).example(generators=("x", "y"), degrees=(2, 3))
+                sage: (x, y) = A.algebra_generators()
+                sage: x.degree()
+                2
+                sage: (x^3 + 4*y^2).degree()
+                6
+                sage: ((1 + x)^3).degree()
+                Traceback (most recent call last):
+                ...
+                ValueError: Element is not homogeneous.
+            """
+            if len(self.support()) == 0:
+                raise ValueError, "The zero element does not have a well-defined degree."
+            try:
+                assert self.is_homogeneous()
+                return self.parent().degree_on_basis(self.leading_support())
+            except AssertionError:
+                raise ValueError, "Element is not homogeneous."
+
+Example = GradedPolynomialAlgebra

sage/categories/examples/hopf_algebras_with_basis.py

@@ -1 +1 @@
 r"""
-Examples of algebras with basis
+Examples of Hopf algebras with basis
 """
 #*****************************************************************************
 #  Copyright (C) 2008-2009 Nicolas M. Thiery <nthiery at users.sf.net>

sage/categories/graded_algebras_with_basis.py

@@ -39 +39 @@
         R = self.base_ring()
         return [GradedModulesWithBasis(R),GradedAlgebras(R), AlgebrasWithBasis(R)]
 
+    def example(self, generators = ('a','b','c'), degrees = 1):
+        """
+        Returns an example of a graded algebra with basis as per
+        :meth:`Category.example <sage.categories.category.Category.example>`.
+
+        EXAMPLES::
+
+            sage: GradedAlgebrasWithBasis(QQ).example()
+            An example of a graded algebra with basis: the polynomial algebra on generators ('a', 'b', 'c') of degrees (1, 1, 1) over Rational Field
+
+        Another set of generators, and their degrees, can be specified
+        as optional arguments::
+
+            sage: GradedAlgebrasWithBasis(QQ).example(generators=("x", "z"), degrees=(3, 10))
+            An example of a graded algebra with basis: the polynomial algebra on generators ('x', 'z') of degrees (3, 10) over Rational Field
+        """
+        from sage.categories.examples.graded_algebras_with_basis import Example
+        return Example(self.base_ring(), generators, degrees)
+
     class ParentMethods:
         pass