Addressing Darij's comments.

Author: Travis Scrimshaw

src/sage/algebras/associated_graded.py

@@ -15,6 +15,7 @@
 
 from sage.misc.cachefunc import cached_method
 from sage.misc.misc_c import prod
+from copy import copy
 
 from sage.categories.algebras_with_basis import AlgebrasWithBasis
 from sage.categories.graded_algebras_with_basis import GradedAlgebrasWithBasis
@@ -37,6 +38,35 @@ class AssociatedGradedAlgebra(CombinatorialFreeModule):
     INPUT:
 
     - ``A`` -- a filtered algebra
+
+    EXAMPLES:
+
+        sage: A = Algebras(QQ).WithBasis().Filtered().example()
+        sage: grA = A.graded_algebra()
+        sage: x,y,z = map(lambda s: grA.algebra_generators()[s], ['x','y','z'])
+        sage: x
+        bar(U['x'])
+        sage: y * x + z
+        bar(U['x']*U['y']) + bar(U['z'])
+        sage: A(y) * A(x) + A(z)
+        U['x']*U['y']
+
+    We note that the conversion between ``A`` and ``grA`` is the canonical
+    ``QQ``-module isomorphism::
+
+        sage: grA(A.an_element())
+        bar(U['x']^2*U['y']^2*U['z']^3)
+        sage: elt = A.an_element() + A.algebra_generators()['x'] + 2
+        sage: grelt = grA(elt); grelt
+        bar(U['x']^2*U['y']^2*U['z']^3) + bar(U['x']) + 2*bar(1)
+        sage: A(grelt) == elt
+        True
+
+    .. TODO::
+
+        The algebra ``A`` must currently be an instance of (a subclass of)
+        :class:`CombinatorialFreeModule`. This should work with any algebra
+        with a basis.
     """
     def __init__(self, A, category=None):
         """
@@ -51,16 +81,21 @@ def __init__(self, A, category=None):
         if A not in AlgebrasWithBasis(A.base_ring()).Filtered():
             raise ValueError("the base algebra must be filtered")
         self._A = A
+
         if category is None:
             category = A.category().Graded()
-        from copy import copy
         opts = copy(A.print_options())
         if not opts['prefix'] and not opts['bracket']:
             opts['bracket'] = '('
         opts['prefix'] = opts['prefix'] + 'bar'
+
         CombinatorialFreeModule.__init__(self, A.base_ring(), A.indices(),
                                          category=category, **opts)
 
+        # Setup the conversion back
+        phi = self.module_morphism(lambda x: A.monomial(x), codomain=A)
+        self._A.register_conversion(phi)
+
     def _repr_(self):
         """
         Return a string representation of ``self``.
@@ -92,6 +127,11 @@ def _element_constructor_(self, x):
         """
         Construct an element of ``self`` from ``x``.
 
+        .. NOTE::
+
+            This constructs an element from the filtered algebra ``A``
+            by the canonical module isomorphism.
+
         EXAMPLES::
 
             sage: A = Algebras(QQ).WithBasis().Filtered().example()

src/sage/categories/examples/filtered_algebras_with_basis.py

@@ -14,7 +14,7 @@
 from sage.sets.family import Family
 from sage.misc.misc import powerset
 
-class IntersectionFilteredAlgebra(CombinatorialFreeModule):
+class PBWBasisCrossProduct(CombinatorialFreeModule):
     r"""
     This class illustrates an implementation of a filtered algebra
     with basis: the universal enveloping algebra of the Lie algebra
@@ -32,6 +32,9 @@ class IntersectionFilteredAlgebra(CombinatorialFreeModule):
 
     - A set of algebra generators -- the set of generators `x,y,z`.
 
+    - The index of the unit element -- the unit element in the monoid
+      of monomials.
+
     - A product -- this is given on basis elements by using
       :meth:`product_on_basis`.
 
@@ -115,6 +118,9 @@ def degree_on_basis(self, m):
         """
         return len(m)
 
+    # TODO: This is a general procedure of expanding multiplication defined
+    #  on generators to arbitrary monomials and could likely be factored out
+    #  and be useful elsewhere.
     def product_on_basis(self, s, t):
         """
         Return the product of two basis elements indexed by ``s`` and ``t``.
@@ -142,6 +148,7 @@ def product_on_basis(self, s, t):
 
         if len(t) == 1:
             if len(s) == 1:
+                # Do the product of the generators
                 a = s.leading_support()
                 b = t.leading_support()
                 cur = self.monomial(s*t)
@@ -165,5 +172,5 @@ def product_on_basis(self, s, t):
             cur = cur * self.monomial(self._indices.gen(a))
         return cur
 
-Example = IntersectionFilteredAlgebra
+Example = PBWBasisCrossProduct
 

src/sage/categories/filtered_algebras.py

@@ -12,9 +12,13 @@
 from sage.categories.filtered_modules import FilteredModulesCategory
 
 class FilteredAlgebras(FilteredModulesCategory):
-    """
+    r"""
     The category of filtered algebras.
 
+    An algebra `A` over `R` is *filtered* if `A` is a filtered `R`-module
+    such that `F_i \cdot F_j \subseteq F_{i+j}` for all `i, j` in the
+    filteration group.
+
     EXAMPLES::
 
         sage: Algebras(ZZ).Filtered()

src/sage/categories/filtered_algebras_with_basis.py

@@ -46,7 +46,10 @@ def graded_algebra(self):
     class ElementMethods:
         def is_homogeneous(self):
             """
-            Return whether this element is homogeneous.
+            Return whether ``self`` is homogeneous.
+
+            An element `x` is homogeneous if `x \in F_i \setminus F_{i-1}`
+            for some `i`.
 
             EXAMPLES::
 
@@ -71,7 +74,7 @@ def is_homogeneous(self):
 
         def homogeneous_degree(self):
             """
-            The degree of this element.
+            The degree of ``self``.
 
             .. NOTE::
 

src/sage/categories/filtered_modules.py

@@ -1,5 +1,7 @@
 r"""
 Filtered modules
+
+We require all `F_i \setminus F_{i-1}` to be modules for all `i`.
 """
 #*****************************************************************************
 #  Copyright (C) 2014 Travis Scrimshaw <tscrim at ucdavis.edu>
@@ -123,9 +125,14 @@ def _repr_object_names(self):
         return "filtered {}".format(self.base_category()._repr_object_names())
 
 class FilteredModules(FilteredModulesCategory):
-    """
+    r"""
     The category of filtered modules.
 
+    A `R`-module `M` is *filtered* if there exists a `R`-module
+    isomorphism `A = \bigoplus_{i \in I} F_i`, where `I` is a
+    totally ordered additive abelian group, such that
+    `F_{i-1} \subseteq F_i` for all `i \in I`.
+
     EXAMPLES::
 
         sage: Modules(ZZ).Filtered()

src/sage/categories/filtered_modules_with_basis.py

@@ -44,10 +44,12 @@ def basis(self, d=None):
 
             INPUT:
 
-            - `d` -- non negative integer or ``None``, optional (default: ``None``)
+            - ``d`` -- (optional, default ``None``) non negative integer
+              or ``None``
 
-            If `d` is None, returns a basis of the module.
-            Otherwise, returns the basis of the homogeneous component of degree `d`.
+            If ``d`` is ``None``, returns a basis of the module.
+            Otherwise, returns the basis of the homogeneous component
+            of degree ``d`` (i.e., of ``F_d \setminus F_{d-1}``).
 
             EXAMPLES::
 
@@ -74,6 +76,9 @@ def is_homogeneous(self):
             """
             Return whether ``self`` is homogeneous.
 
+            An element `x` is homogeneous if `x \in F_i \setminus F_{i-1}`
+            for some `i`.
+
             EXAMPLES::
 
                 sage: A = ModulesWithBasis(ZZ).Filtered().example()
@@ -99,7 +104,10 @@ def is_homogeneous(self):
 
         def degree(self):
             """
-            The degree of this element in the filtered module.
+            The degree of ``self`` in the filtered module.
+
+            The degree of an element `x` is the value `i` such that
+            `x \in F_i \setminus F_{i-1}`.
 
             .. NOTE::
 
@@ -164,7 +172,7 @@ def homogeneous_component(self, n):
         def truncate(self, n):
             """
             Return the sum of the homogeneous components of degree
-            strictly less than ``n`` of this element.
+            strictly less than ``n`` of ``self``.
 
             EXAMPLES::