README: rewrite it, it was rather out-of-date

[sage.d.git] / mjo / symbol_sequence.py

diff --git a/mjo/symbol_sequence.py b/mjo/symbol_sequence.py
index 757c60d853ab1b36fae3e7b3df6e8bcd7a7512ba..2a104aed958d877103e1962f1ad212e2ab07c981 100644 (file)
--- a/mjo/symbol_sequence.py
+++ b/mjo/symbol_sequence.py
@@ -1,14 +1,14 @@
 from sage.all import *
 
 class SymbolSequence:
 from sage.all import *
 
 class SymbolSequence:

-    """
+    r"""

     An iterable object which acts like a sequence of symbolic
     expressions (variables).
 
     INPUT:
 
       - ``name`` -- The sequence name. For example, if you name the
     An iterable object which acts like a sequence of symbolic
     expressions (variables).
 
     INPUT:
 
       - ``name`` -- The sequence name. For example, if you name the

-        sequence `x`, the variables will be called `x0`, `x1`,...
+        sequence `x`, the variables will be called `x_0`, `x_1`,...

 
       - ``latex_name`` -- An optional latex expression (string) to
         use instead of `name` when converting the symbols to latex.
 
       - ``latex_name`` -- An optional latex expression (string) to
         use instead of `name` when converting the symbols to latex.


@@ -20,29 +20,33 @@ class SymbolSequence:
 
     An iterable object containing symbolic expressions.
 
 
     An iterable object containing symbolic expressions.
 

+    SETUP::
+
+        sage: from mjo.symbol_sequence import SymbolSequence
+

     EXAMPLES:
 
     The simplest use case::
 
         sage: a = SymbolSequence('a')
         sage: a[0]
     EXAMPLES:
 
     The simplest use case::
 
         sage: a = SymbolSequence('a')
         sage: a[0]

-        a0
+        a_0

         sage: a[1]
         sage: a[1]

-        a1
+        a_1

 
     Create polynomials with symbolic coefficients of arbitrary
     degree::
 
         sage: a = SymbolSequence('a')
 
     Create polynomials with symbolic coefficients of arbitrary
     degree::
 
         sage: a = SymbolSequence('a')

-        sage: p = sum([ a[i]*x^i for i in range(0,5)])
+        sage: p = sum( a[i]*x^i for i in range(5) )

         sage: p
         sage: p

-        a4*x^4 + a3*x^3 + a2*x^2 + a1*x + a0
+        a_4*x^4 + a_3*x^3 + a_2*x^2 + a_1*x + a_0

 
     Using a different latex name since 'lambda' is reserved::
 
 
     Using a different latex name since 'lambda' is reserved::
 

-        sage: l = SymbolSequence('l', '\lambda')
+        sage: l = SymbolSequence('l', r'\lambda')

         sage: l[0]
         sage: l[0]

-        l0
+        l_0

         sage: latex(l[0])
         \lambda_{0}
 
         sage: latex(l[0])
         \lambda_{0}
 


@@ -50,34 +54,34 @@ class SymbolSequence:
 
         sage: a = SymbolSequence('a')
         sage: a[0,1,2]
 
         sage: a = SymbolSequence('a')
         sage: a[0,1,2]

-        a012
+        a_0_1_2

         sage: latex(a[0,1,2])
         a_{0}_{1}_{2}
         sage: latex(a[0,1,2])
         a_{0}_{1}_{2}

-        sage: [ a[i,j] for i in range(0,2) for j in range(0,2) ]
-        [a00, a01, a10, a11]
+        sage: [ a[i,j] for i in range(2) for j in range(2) ]
+        [a_0_0, a_0_1, a_1_0, a_1_1]

 
     You can pass slices instead of integers to obtain a list of
     symbols::
 
         sage: a = SymbolSequence('a')
         sage: a[5:7]
 
     You can pass slices instead of integers to obtain a list of
     symbols::
 
         sage: a = SymbolSequence('a')
         sage: a[5:7]

-        [a5, a6]
+        [a_5, a_6]

 
     This even works for the second, third, etc. indices::
 
         sage: a = SymbolSequence('a')
         sage: a[0:2, 0:2]
 
     This even works for the second, third, etc. indices::
 
         sage: a = SymbolSequence('a')
         sage: a[0:2, 0:2]

-        [a00, a01, a10, a11]
+        [a_0_0, a_0_1, a_1_0, a_1_1]

 
     TESTS:
 
     We shouldn't overwrite variables in the global namespace::
 
         sage: a = SymbolSequence('a')
 
     TESTS:
 
     We shouldn't overwrite variables in the global namespace::
 
         sage: a = SymbolSequence('a')

-        sage: a0 = 4
+        sage: a_0 = 4

         sage: a[0]
         sage: a[0]

-        a0
-        sage: a0
+        a_0
+        sage: a_0

         4
 
     The symbol at a given index should always be the same, even when
         4
 
     The symbol at a given index should always be the same, even when


@@ -93,9 +97,9 @@ class SymbolSequence:
 
         sage: a = SymbolSequence('a')
         sage: a[3, 0:2]
 
         sage: a = SymbolSequence('a')
         sage: a[3, 0:2]

-        [a30, a31]
+        [a_3_0, a_3_1]

         sage: a[0:2, 3]
         sage: a[0:2, 3]

-        [a03, a13]
+        [a_0_3, a_1_3]

 
     """
 
 
     """
 


@@ -116,12 +120,26 @@ class SymbolSequence:
         Return a symbol with the given subscript. Creates the
         appropriate name and latex_name before delegating to
         SR.symbol().
         Return a symbol with the given subscript. Creates the
         appropriate name and latex_name before delegating to
         SR.symbol().

+
+        SETUP::
+
+            sage: from mjo.symbol_sequence import SymbolSequence
+
+        EXAMPLES::
+
+            sage: a = SymbolSequence('a', 'alpha', 'real')
+            sage: a_1 = a._create_symbol_(1)
+            sage: a_1
+            a_1
+            sage: latex(a_1)
+            alpha_{1}
+

         """
         # Allow creating unnamed symbols, for consistency with
         # SR.symbol().
         name = None
         if self._name is not None:
         """
         # Allow creating unnamed symbols, for consistency with
         # SR.symbol().
         name = None
         if self._name is not None:

-            name = '%s%d' % (self._name, subscript)
+            name = '%s_%d' % (self._name, subscript)

 
         latex_name = None
         if self._latex_name is not None:
 
         latex_name = None
         if self._latex_name is not None:


@@ -136,13 +154,31 @@ class SymbolSequence:
         to be non-iterable. This is slow, but also works, which is
         more than can be said about some of the snappier solutions of
         lore.
         to be non-iterable. This is slow, but also works, which is
         more than can be said about some of the snappier solutions of
         lore.

+
+        SETUP::
+
+            sage: from mjo.symbol_sequence import SymbolSequence
+
+        EXAMPLES::
+
+            sage: a = SymbolSequence('a')
+            sage: a._flatten_list_([1,2,3])
+            [1, 2, 3]
+            sage: a._flatten_list_([1,[2,3]])
+            [1, 2, 3]
+            sage: a._flatten_list_([1,[2,[3]]])
+            [1, 2, 3]
+            sage: a._flatten_list_([[[[[1,[2,[3]]]]]]])
+            [1, 2, 3]
+

         """
         result = []
 
         for item in l:
         """
         result = []
 
         for item in l:

-            if isinstance(item, list):
+            try:
+                item = iter(item)

                 result += self._flatten_list_(item)
                 result += self._flatten_list_(item)

-            else:
+            except TypeError:

                 result += [item]
 
         return result
                 result += [item]
 
         return result


@@ -153,6 +189,31 @@ class SymbolSequence:
         This handles individual integer arguments, slices, and
         tuples. It just hands off the real work to
         self._subscript_foo_().
         This handles individual integer arguments, slices, and
         tuples. It just hands off the real work to
         self._subscript_foo_().

+
+        SETUP::
+
+            sage: from mjo.symbol_sequence import SymbolSequence
+
+        EXAMPLES:
+
+        An integer argument::
+
+            sage: a = SymbolSequence('a')
+            sage: a.__getitem__(1)
+            a_1
+
+        A tuple argument::
+
+            sage: a = SymbolSequence('a')
+            sage: a.__getitem__((1,2))
+            a_1_2
+
+        A slice argument::
+
+            sage: a = SymbolSequence('a')
+            sage: a.__getitem__(slice(1,4))
+            [a_1, a_2, a_3]
+

         """
         if isinstance(key, tuple):
             return self._subscript_tuple_(key)
         """
         if isinstance(key, tuple):
             return self._subscript_tuple_(key)


@@ -170,6 +231,17 @@ class SymbolSequence:
         """
         The subscript is a single integer, or something that acts like
         one.
         """
         The subscript is a single integer, or something that acts like
         one.

+
+        SETUP::
+
+            sage: from mjo.symbol_sequence import SymbolSequence
+
+        EXAMPLES::
+
+            sage: a = SymbolSequence('a')
+            sage: a._subscript_integer_(123)
+            a_123
+

         """
         if n < 0:
             # Cowardly refuse to create a variable named "a-1".
         """
         if n < 0:
             # Cowardly refuse to create a variable named "a-1".


@@ -187,6 +259,17 @@ class SymbolSequence:
         We were given a slice. Clean up some of its properties
         first. The start/step are default for lists. We make
         copies of these because they're read-only.
         We were given a slice. Clean up some of its properties
         first. The start/step are default for lists. We make
         copies of these because they're read-only.

+
+        SETUP::
+
+            sage: from mjo.symbol_sequence import SymbolSequence
+
+        EXAMPLES::
+
+            sage: a = SymbolSequence('a')
+            sage: a._subscript_slice_(slice(1,3))
+            [a_1, a_2]
+

         """
         (start, step) = (s.start, s.step)
         if start is None:
         """
         (start, step) = (s.start, s.step)
         if start is None:


@@ -209,6 +292,24 @@ class SymbolSequence:
         """
         When we have more than one level of subscripts, we pick off
         the first one and generate the rest recursively.
         """
         When we have more than one level of subscripts, we pick off
         the first one and generate the rest recursively.

+
+        SETUP::
+
+            sage: from mjo.symbol_sequence import SymbolSequence
+
+        EXAMPLES:
+
+        A simple two-tuple::
+
+            sage: a = SymbolSequence('a')
+            sage: a._subscript_tuple_((1,8))
+            a_1_8
+
+        Nested tuples::
+
+            sage: a._subscript_tuple_(( (1,2), (3,(4,5,6)) ))
+            a_1_2_3_4_5_6
+

         """
 
         # We never call this method without an argument.
         """
 
         # We never call this method without an argument.


@@ -228,11 +329,11 @@ class SymbolSequence:
         # corresponding to the second coordinate, with the first
         # coordinate(s) fixed.
         if isinstance(key, slice):
         # corresponding to the second coordinate, with the first
         # coordinate(s) fixed.
         if isinstance(key, slice):

-            ss = [ SymbolSequence(w._repr_(), w._latex_(), self._domain)
-                   for w in v ]
+            ss = ( SymbolSequence(w._repr_(), w._latex_(), self._domain)
+                   for w in v )

 
             # This might be nested...
 
             # This might be nested...

-            maybe_nested_list = [ s._subscript_tuple_(args) for s in ss ]
+            maybe_nested_list = ( s._subscript_tuple_(args) for s in ss )

             return self._flatten_list_(maybe_nested_list)
 
         else:
             return self._flatten_list_(maybe_nested_list)
 
         else: