Some reviewer changes and tweaks.

Author: tscrim

src/sage/algebras/lie_algebras/lie_algebra.py

@@ -319,11 +319,11 @@ class LieAlgebra(Parent, UniqueRepresentation): # IndexedGenerators):
         sage: L.<X,Y,Z> = LieAlgebra(QQ, {('X','Y'): {'Z': 1}}, category=C); L
         Nilpotent Lie algebra on 3 generators (X, Y, Z) over Rational Field
 
-    Free nilpotent Lie algebras are the truncated versions of the free Lie
-    algebras. That is, the only relations other than anticommutativity and the
-    Jacobi identity among the Lie brackets are that brackets of length higher
-    than the nilpotency step vanish. They can be created by using the
-    ``step`` keyword::
+    **7.** Free nilpotent Lie algebras are the truncated versions of the free
+    Lie algebras. That is, the only relations other than anticommutativity
+    and the Jacobi identity among the Lie brackets are that brackets of
+    length higher than the nilpotency step vanish. They can be created by
+    using the ``step`` keyword::
 
         sage: L = LieAlgebra(ZZ, 2, step=3); L
         Free Nilpotent Lie algebra on 5 generators (X_1, X_2, X_12, X_112, X_122) over Integer Ring
@@ -430,7 +430,7 @@ def __classcall_private__(cls, R=None, arg0=None, arg1=None, names=None,
             return LieAlgebraWithStructureCoefficients(R, arg1, names, index_set,
                                                        category=category, **kwds)
 
-        # Otherwise it must be either a free or abelian Lie algebra
+        # Otherwise it must be either a free (nilpotent) or abelian Lie algebra
 
         if arg1 in ZZ:
             step = kwds.get("step", None)
@@ -439,6 +439,9 @@ def __classcall_private__(cls, R=None, arg0=None, arg1=None, names=None,
                 from sage.algebras.lie_algebras.nilpotent_lie_algebra import FreeNilpotentLieAlgebra
                 del kwds["step"]
                 return FreeNilpotentLieAlgebra(R, arg1, step, names=names, **kwds)
+            elif nilpotent:
+                raise ValueError("free nilpotent Lie algebras must have a"
+                                 " 'step' parameter given")
 
             if isinstance(arg0, str):
                 names = arg0
@@ -454,6 +457,11 @@ def __classcall_private__(cls, R=None, arg0=None, arg1=None, names=None,
                     raise ValueError("the number of names must equal the"
                                      " number of generators")
 
+        if "step" in kwds or nilpotent:
+            raise ValueError("free nilpotent Lie algebras must have both"
+                             " a number of generators and step parameters"
+                             " specified")
+
         if abelian:
             from sage.algebras.lie_algebras.abelian import AbelianLieAlgebra
             return AbelianLieAlgebra(R, names, index_set)

src/sage/algebras/lie_algebras/nilpotent_lie_algebra.py

@@ -18,7 +18,9 @@
 
 from sage.algebras.lie_algebras.structure_coefficients import LieAlgebraWithStructureCoefficients
 from sage.categories.lie_algebras import LieAlgebras
-
+from sage.structure.indexed_generators import standardize_names_index_set
+from sage.rings.integer_ring import ZZ
+from collections import OrderedDict
 
 class NilpotentLieAlgebra_dense(LieAlgebraWithStructureCoefficients):
     r"""
@@ -156,37 +158,40 @@ def _repr_(self):
 
 class FreeNilpotentLieAlgebra(NilpotentLieAlgebra_dense):
     r"""
-    Returns the free nilpotent Lie algebra of step ``s`` with ``r`` generators.
+    Return the free nilpotent Lie algebra of step ``s`` with ``r`` generators.
 
-    The free nilpotent Lie algebra `L` of step `s` with `r` generators is the
-    quotient of the free Lie algebra on `r` generators by the `s+1`th term of
-    the lower central series. That is, the only relations in the Lie algebra `L`
-    are anticommutativity, the Jacobi identity, and the vanishing of all
-    brackets of length more than `s`.
+    The free nilpotent Lie algebra `L` of step `s` with `r` generators is
+    the quotient of the free Lie algebra on `r` generators by the `(s+1)`-th
+    term of the lower central series. That is, the only relations in the
+    Lie algebra `L` are anticommutativity, the Jacobi identity, and the
+    vanishing of all brackets of length more than `s`.
 
     INPUT:
 
     - ``R`` -- the base ring
     - ``r`` -- an integer; the number of generators
     - ``s`` -- an integer; the nilpotency step of the algebra
     - ``names`` -- (optional) a string or a list of strings used to name the
-      basis elements; If ``names`` is a string, then names for the basis will be
-      autogenerated as determined by the ``naming`` parameter.
-    - ``naming`` -- (optional) a string; the naming scheme to use for the basis.
-      Valid values are:
-          'index' : The basis elements are ``names_w``, where `w` are Lyndon
-                    words indexing the basis.
-                    This naming scheme is not supported if `r > 10`, since it
-                    leads to ambiguous names. When `r \leq 10`, this is the
-                    default naming scheme.
-          'linear' : the basis is indexed ``names_1``,...,``names_n`` in the
-                     ordering of the Lyndon basis. When `r > 10`, this is the
-                     default naming scheme.
+      basis elements; if ``names`` is a string, then names for the basis
+      will be autogenerated as determined by the ``naming`` parameter
+    - ``naming`` -- (optional) a string; the naming scheme to use for
+      the basis; valid values are:
+
+      * ``'index'`` - (default for `r \leq 10`) the basis elements are
+        ``names_w``, where ``w`` are Lyndon words indexing the basis
+      * ``'linear'`` - (default for `r > 10`) the basis is indexed
+        ``names_1``, ..., ``names_n`` in the ordering of the Lyndon basis
+
+    .. NOTE::
+
+        The ``'index'`` naming scheme is not supported if `r > 10` since
+        it leads to ambiguous names.
 
     EXAMPLES:
 
-    We compute the free step 4 Lie algebra on 2 generators and verify the only
-    non-trivial relation [[1,[1,2]],2] = [1,[[1,2],2]]::
+    We compute the free step 4 Lie algebra on 2 generators and
+    verify the only non-trivial relation
+    `[[X_1,[X_1,X_2]],X_2] = [X_1,[[X_1,X_2],X_2]]`::
 
         sage: L = LieAlgebra(QQ, 2, step=4)
         sage: L.basis().list()
@@ -288,33 +293,51 @@ class FreeNilpotentLieAlgebra(NilpotentLieAlgebra_dense):
         sage: [X_12222.bracket(Xk) for Xk in L.basis()]
         [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 
-    The dimensions of the smallest free nilpotent Lie algebras on 2 or 3
-    generators::
+    The dimensions of the smallest free nilpotent Lie algebras on
+    2 and 3 generators::
 
         sage: l = [LieAlgebra(QQ, 2, step=k) for k in range(1, 7)]
         sage: [L.dimension() for L in l]
         [2, 3, 5, 8, 14, 23]
         sage: l = [LieAlgebra(QQ, 3, step=k) for k in range(1, 4)]
         sage: [L.dimension() for L in l]
         [3, 6, 14]
+    """
+    @staticmethod
+    def __classcall_private__(cls, R, r, s, names=None, naming=None, category=None, **kwds):
+        """
+        Normalize input to ensure a unique representation.
 
-    Test suite for a free nilpotent Lie algebra::
+        TESTS::
 
-        sage: L = LieAlgebra(QQ, 4, step=3)
-        sage: TestSuite(L).run()
-    """
+            sage: L1.<X> = LieAlgebra(ZZ, 2, step=2)
+            sage: L2 = LieAlgebra(ZZ, 2, step=2, names=['X'])
+            sage: L3 = LieAlgebra(ZZ, 2, step=2)
+            sage: L1 is L2 and L2 is L3
+            True
+        """
+        if names is None:
+            names = 'X'
 
-    def __init__(self, R, r, s, names=None, naming=None, category=None, **kwds):
+        cat = LieAlgebras(R).FiniteDimensional().WithBasis()
+        category = cat.Graded().Stratified().or_subcategory(category)
+
+        return super(FreeNilpotentLieAlgebra, cls).__classcall__(
+            cls, R,r, s, names=tuple(names), naming=naming,
+            category=category, **kwds)
+
+    def __init__(self, R, r, s, names, naming, category, **kwds):
         r"""
         Initialize ``self``
 
         EXAMPLES::
 
-            sage: LieAlgebra(ZZ, 2, step=2)
-            Free Nilpotent Lie algebra on 3 generators (X_1, X_2, X_12) over Integer Ring
-        """
-        from sage.rings.integer_ring import ZZ
+            sage: L = LieAlgebra(ZZ, 2, step=2)
+            sage: TestSuite(L).run()
 
+            sage: L = LieAlgebra(QQ, 4, step=3)
+            sage: TestSuite(L).run()  # long time
+        """
         if r not in ZZ or r <= 0:
             raise ValueError("number of generators %s is not "
                              "a positive integer" % r)
@@ -327,7 +350,7 @@ def __init__(self, R, r, s, names=None, naming=None, category=None, **kwds):
 
         free_gen_names = ['F%d' % k for k in range(r)]
         L = LieAlgebra(R, free_gen_names).Lyndon()
-        from collections import OrderedDict
+
         basis_dict = OrderedDict()
         for d in range(1, s + 1):
             for X in L.graded_basis(d):
@@ -336,12 +359,7 @@ def __init__(self, R, r, s, names=None, naming=None, category=None, **kwds):
                           for s in X.leading_support().to_word())
                 basis_dict[w] = X
 
-        # define names for basis elements
-        if not names:
-            names = 'X'
-        if isinstance(names, str):
-            names = tuple(names)
-        if len(names) == 1 and len(basis_dict)>1:
+        if len(names) == 1 and len(basis_dict) > 1:
             if not naming:
                 if r > 10:
                     naming = 'linear'
@@ -361,7 +379,7 @@ def __init__(self, R, r, s, names=None, naming=None, category=None, **kwds):
 
         # extract structural coefficients from the free Lie algebra
         s_coeff = {}
-        for k,X_ind in enumerate(basis_dict):
+        for k, X_ind in enumerate(basis_dict):
             X = basis_dict[X_ind]
             degX = len(X_ind)
             for Y_ind in basis_dict.keys()[k+1:]:
@@ -376,20 +394,17 @@ def __init__(self, R, r, s, names=None, naming=None, category=None, **kwds):
                     s_coeff[(X_ind, Y_ind)] = {W: Z[basis_dict[W].leading_support()]
                                                for W in basis_dict}
 
-        from sage.structure.indexed_generators import standardize_names_index_set
         names, index_set = standardize_names_index_set(names, basis_dict.keys())
         s_coeff = LieAlgebraWithStructureCoefficients._standardize_s_coeff(
             s_coeff, index_set)
 
-        category = LieAlgebras(R).FiniteDimensional().WithBasis() \
-                                 .Graded().Stratified().or_subcategory(category)
         NilpotentLieAlgebra_dense.__init__(self, R, s_coeff, names,
                                            index_set, s,
                                            category=category, **kwds)
 
     def _repr_generator(self, w):
         r"""
-        Returns the string representation of the basis element
+        Return the string representation of the basis element
         indexed by the word ``w`` in ``self``.
 
         EXAMPLES::
@@ -408,7 +423,7 @@ def _repr_generator(self, w):
         return self.variable_names()[i]
 
     def _repr_(self):
-        """
+        r"""
         Return a string representation of ``self``.
 
         EXAMPLES::
@@ -418,3 +433,4 @@ def _repr_(self):
             Free Nilpotent Lie algebra on 5 generators (X_1, X_2, X_12, X_112, X_122) over Rational Field
         """
         return "Free %s" % (super(FreeNilpotentLieAlgebra, self)._repr_())
+