From 4b7efa309d011373d52fe5b6c7930213be9cb1c7 Mon Sep 17 00:00:00 2001 From: Travis Scrimshaw Date: Wed, 28 Jul 2021 09:31:29 +1000 Subject: [PATCH] Fixing up some documentation and doctests. --- .../data_structures/coefficient_stream.py | 303 ++++++++---------- src/sage/rings/lazy_laurent_series.py | 72 +++-- src/sage/rings/lazy_laurent_series_ring.py | 46 ++- 3 files changed, 209 insertions(+), 212 deletions(-) diff --git a/src/sage/data_structures/coefficient_stream.py b/src/sage/data_structures/coefficient_stream.py index 2387ba297e6..f5da2a09023 100644 --- a/src/sage/data_structures/coefficient_stream.py +++ b/src/sage/data_structures/coefficient_stream.py @@ -6,9 +6,9 @@ can be used to build up more complex streams for different kinds of series (Laurent, Dirichlet, etc). -EXAMPLES:: +EXAMPLES: - The coefficient stream can be used to build up a Lazy laurent series:: +The coefficient stream can be used to build up a Lazy laurent series:: sage: L. = LazyLaurentSeriesRing(ZZ) sage: f = L(lambda n: n, True) @@ -32,28 +32,28 @@ sage: [h[i] for i in range(10)] [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - Coefficient streams can be subtracted:: +Coefficient streams can be subtracted:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_sub sage: h = CoefficientStream_sub(f, g) sage: [h[i] for i in range(10)] [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8] - Coefficient streams can be multiplied:: +Coefficient streams can be multiplied:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_mul sage: h = CoefficientStream_mul(f, g) sage: [h[i] for i in range(10)] [0, 1, 3, 6, 10, 15, 21, 28, 36, 45] - Coefficient streams can be divided:: +Coefficient streams can be divided:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_div sage: h = CoefficientStream_div(f, g) sage: [h[i] for i in range(10)] [0, 1, 1, 1, 1, 1, 1, 1, 1, 1] - Two coefficient streams can be composed (depending on whether it exists):: +Two coefficient streams can be composed (depending on whether it exists):: sage: from sage.data_structures.coefficient_stream import CoefficientStream_composition sage: g = CoefficientStream_coefficient_function(lambda n: n, QQ, True, 1) @@ -61,28 +61,28 @@ sage: [h[i] for i in range(10)] [0, 1, 4, 14, 46, 145, 444, 1331, 3926, 11434] - We can also use the unary negation operator on a coefficient stream:: +We can also use the unary negation operator on a coefficient stream:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_neg sage: h = CoefficientStream_neg(f) sage: [h[i] for i in range(10)] [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] - Coefficient streams can be multiplied by a scalar:: +Coefficient streams can be multiplied by a scalar:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_scalar sage: h = CoefficientStream_scalar(f, 2) sage: [h[i] for i in range(10)] [0, 2, 4, 6, 8, 10, 12, 14, 16, 18] - The multiplicative inverse of a series can also be obtained:: +The multiplicative inverse of a series can also be obtained:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_inv sage: h = CoefficientStream_inv(g) sage: [h[i] for i in range(10)] [-2, 1, 0, 0, 0, 0, 0, 0, 0, 0] - Functions can also be applied to a coefficient stream:: +Functions can also be applied to a coefficient stream:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_apply_coeff sage: h = CoefficientStream_apply_coeff(f, lambda n: n^2, QQ) @@ -104,24 +104,20 @@ # (at your option) any later version. # https://www.gnu.org/licenses/ # **************************************************************************** + from sage.rings.integer_ring import ZZ from sage.rings.infinity import infinity class CoefficientStream(): """ - Abstract base class for all streams. + Abstract base class for all coefficient streams. INPUT: - ``sparse`` -- boolean; whether the implementation of the series is sparse - - ``approximate_valuation`` -- the approximate valuation of the series - - EXAMPLES:: - """ - def __init__(self, sparse, approximate_valuation): """ Initialize the auxillary class for any series. @@ -138,24 +134,14 @@ def __init__(self, sparse, approximate_valuation): class CoefficientStream_inexact(CoefficientStream): """ - An abstract base class for the stream when it is not or we do not know if it is + An abstract base class for the stream when we do not know it is eventually geometric. INPUT: - ``sparse`` -- boolean; whether the implementation of the series is sparse - - ``approximate_valuation`` -- integer; the approximate valuation of the series - - EXAMPLES:: - - sage: from sage.data_structures.coefficient_stream import CoefficientStream_coefficient_function, CoefficientStream_uninitialized - sage: CoefficientStream_coefficient_function.__base__ - - sage: CoefficientStream_uninitialized.__base__ - """ - def __init__(self, is_sparse, approximate_valuation): """ Initialize the stream class for a CoefficientStream when it is not @@ -243,14 +229,28 @@ def __getitem__(self, n): - ``n`` -- integer; the index of the coefficient to return - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_coefficient_function - sage: f = CoefficientStream_coefficient_function(lambda n: n, QQ, True, 0) + sage: f = CoefficientStream_coefficient_function(lambda n: n^2, QQ, True, 0) sage: f[3] - 3 + 9 + sage: f._cache + {3: 9} sage: [f[i] for i in range(10)] - [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] + sage: f._cache + {0: 0, 1: 1, 2: 4, 3: 9, 4: 16, 5: 25, 6: 36, 7: 49, 8: 64, 9: 81} + + sage: f = CoefficientStream_coefficient_function(lambda n: n^2, QQ, False, 0) + sage: f[3] + 9 + sage: f._cache + [0, 1, 4, 9] + sage: [f[i] for i in range(10)] + [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] + sage: f._cache + [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] """ if n < self._approximate_valuation: return ZZ.zero() @@ -277,7 +277,7 @@ def valuation(self): """ Return the valuation of the series. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_coefficient_function sage: f = CoefficientStream_coefficient_function(lambda n: n, QQ, True, 0) @@ -316,17 +316,15 @@ def valuation(self): class CoefficientStream_eventually_geometric(CoefficientStream): r""" - Coefficient Stream for a series which is known to be eventually geometric + Coefficient stream for a series which is known to be eventually geometric. INPUT: - - ``laurent_polynomial`` -- a Laurent polynomial - - - ``is_sparse`` -- a boolean, which specifies whether the series is sparse - - - ``constant`` -- either ``None`` (default: ``None``) or pair of an element of the base ring and an integer - - - ``degree`` -- either ``None`` (default: ``None``) or an integer, the degree of the polynomial + - ``laurent_polynomial`` -- a Laurent polynomial + - ``is_sparse`` -- boolean; specifies whether the series is sparse + - ``constant`` -- (default: 0) the eventual constant value + - ``degree`` -- (default: the degree of ``laurent_polynomial`` plus 1) + the degree where the coefficient stream becomes ``constant`` EXAMPLES:: @@ -352,14 +350,21 @@ class CoefficientStream_eventually_geometric(CoefficientStream): def __init__(self, laurent_polynomial, is_sparse, constant=None, degree=None): """ - Initialize the stream for a series that is known to be eventually geometric. + Initialize ``self``. TESTS:: - sage: L. = LazyLaurentSeriesRing(QQ) - sage: M = z^2 + z - sage: type(M._coeff_stream) - + sage: R. = LaurentPolynomialRing(QQ) + sage: from sage.data_structures.coefficient_stream import CoefficientStream_eventually_geometric + sage: X = CoefficientStream_eventually_geometric(z^2 + z^-1, False) + sage: [X[i] for i in range(-1,8)] + [1, 0, 0, 1, 0, 0, 0, 0, 0] + sage: X = CoefficientStream_eventually_geometric(z^2 + z^-1, True, 5) + sage: [X[i] for i in range(-1,8)] + [1, 0, 0, 1, 5, 5, 5, 5, 5] + sage: X = CoefficientStream_eventually_geometric(z^2 + z^-1, False, 5, 4) + sage: [X[i] for i in range(-1,8)] + [1, 0, 0, 1, 0, 5, 5, 5, 5] """ if constant is None: constant = ZZ.zero() @@ -386,16 +391,19 @@ def __getitem__(self, n): INPUT: - - ``n`` -- integer, the degree for which the coefficient is required + - ``n`` -- integer; the degree for which the coefficient is required EXAMPLES:: - sage: L. = LazyLaurentSeriesRing(QQ) - sage: f = 1 + z + z^2 + z^3 - sage: f[3] + sage: R. = LaurentPolynomialRing(QQ) + sage: from sage.data_structures.coefficient_stream import CoefficientStream_eventually_geometric + sage: f = CoefficientStream_eventually_geometric(z^2 + z^-1, False, 3, 10) + sage: f[2] 1 sage: f[8] 0 + sage: f[15] + 3 """ if n >= self._degree: return self._constant @@ -455,12 +463,10 @@ class CoefficientStream_coefficient_function(CoefficientStream_inexact): INPUT: - - ``coefficient_function`` -- a python function that generates the coefficients of the series - + - ``coefficient_function`` -- a python function that generates the + coefficients of the series - ``ring`` -- the base ring of the series - - - ``is_sparse`` -- a boolean, which specifies whether the series is sparse - + - ``is_sparse`` -- boolean; specifies whether the series is sparse - ``approximate_valuation`` -- the approximate valuation of the series EXAMPLES:: @@ -488,11 +494,11 @@ def __init__(self, coefficient_function, ring, is_sparse, approximate_valuation) def get_coefficient(self, n): """ - Return the coefficient of the term with exponent ``n`` of the stream. + Return the ``n``-th coefficient of ``self``. INPUT: - - ``n`` -- integer, the degree for which the coefficient is required + - ``n`` -- integer; the degree for the coefficient EXAMPLES:: @@ -505,7 +511,7 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return a generator for the coefficients of the stream. + A generator for the coefficients of ``self``. EXAMPLES:: @@ -524,12 +530,11 @@ def iterate_coefficients(self): class CoefficientStream_uninitialized(CoefficientStream_inexact): r""" - Coefficient Stream for an uninitialized series. + Coefficient stream for an uninitialized series. INPUT: - - ``is_sparse`` -- a boolean, which specifies whether the series is sparse - + - ``is_sparse`` -- boolean; which specifies whether the series is sparse - ``approximate_valuation`` -- the approximate valuation of the series EXAMPLES:: @@ -539,7 +544,6 @@ class CoefficientStream_uninitialized(CoefficientStream_inexact): sage: N Uninitialized Lazy Laurent Series """ - def __init__(self, is_sparse, approximate_valuation): """ Initialize an uninitialized lazy laurent series. @@ -556,11 +560,11 @@ def __init__(self, is_sparse, approximate_valuation): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the series. + Return the ``n``-th coefficient of ``self``. INPUT: - - ``n`` -- integer, the degree for which the coefficient is required + - ``n`` -- integer; the degree for the coefficient EXAMPLES:: @@ -575,7 +579,7 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return a generator for the coefficients of the series. + A generator for the coefficients of ``self``. EXAMPLES:: @@ -594,16 +598,12 @@ def iterate_coefficients(self): class CoefficientStream_unary(CoefficientStream_inexact): - """ + r""" Class for unary operators for the coefficient stream. INPUT: - - ``series`` -- stream upon which the operator operates - - - ``*args`` -- optional arguments (non-keyword) - - - ``**kwargs`` -- optional arguments (keyword) + - ``series`` -- :class:`CoefficientStream` the operator acts on EXAMPLES:: @@ -619,7 +619,7 @@ class CoefficientStream_unary(CoefficientStream_inexact): def __init__(self, series, *args, **kwargs): """ - Initialize. + Initialize ``self``. TESTS:: @@ -674,13 +674,8 @@ class CoefficientStream_binary(CoefficientStream_inexact): INPUT: - - ``left`` -- stream to the left side of the operator - - - ``right`` -- stream to the right side of the operator - - - ``*args`` -- optional arguments (non-keyword) - - - ``**kwargs`` -- optional arguments (keyword) + - ``left`` -- :class:`CoefficientStream` for the left side of the operator + - ``right`` -- :class:`CoefficientStream` for the right side of the operator EXAMPLES:: @@ -752,12 +747,13 @@ def __eq__(self, other): class CoefficientStream_binary_commutative(CoefficientStream_binary): - """ - Abstract base class for commutative binary operators for the coefficient stream. + r""" + Abstract base class for commutative binary operators for the + coefficient stream. INPUT: - - ``other`` -- a stream of coefficients + - ``other`` -- a :class:`CoefficientStream` EXAMPLES:: @@ -773,7 +769,6 @@ class CoefficientStream_binary_commutative(CoefficientStream_binary): sage: h == u True """ - def __hash__(self): """ Return the hash of ``self``. @@ -852,7 +847,7 @@ def __getitem__(self, n): INPUT:: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the index of the coefficient to be returned TESTS:: @@ -869,7 +864,7 @@ def valuation(self): """ Return the valuation of the series. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import CoefficientStream_zero sage: s = CoefficientStream_zero(True) @@ -896,10 +891,10 @@ def __hash__(self): """ return 0 + ##################################################################### # Binary operations - class CoefficientStream_add(CoefficientStream_binary_commutative): """ Operator for addition of two coefficient streams. @@ -907,7 +902,6 @@ class CoefficientStream_add(CoefficientStream_binary_commutative): INPUT: - ``left`` -- stream of coefficients on the left side of the operator - - ``right`` -- stream of coefficients on the right side of the operator EXAMPLES:: @@ -922,7 +916,6 @@ class CoefficientStream_add(CoefficientStream_binary_commutative): sage: [u[i] for i in range(10)] [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] """ - def __init__(self, left, right): """ Initalize. @@ -942,13 +935,13 @@ def __init__(self, left, right): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the stream when ``left`` is added to ``right``. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_add) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 0) @@ -963,9 +956,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return a generator for the coefficients of the stream when ``left`` is added to ``right``. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_add) sage: f = CoefficientStream_coefficient_function(lambda n: 1, ZZ, False, 0) @@ -988,7 +981,6 @@ class CoefficientStream_sub(CoefficientStream_binary): INPUT: - ``left`` -- stream of coefficients on the left side of the operator - - ``right`` -- stream of coefficients on the right side of the operator EXAMPLES:: @@ -1006,7 +998,7 @@ class CoefficientStream_sub(CoefficientStream_binary): def __init__(self, left, right): """ - Initalize. + Initalize ``self``. TESTS:: @@ -1023,13 +1015,13 @@ def __init__(self, left, right): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the stream when ``right`` is subtracted from ``left``. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_sub) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 0) @@ -1044,9 +1036,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return a generator for the coefficients of the stream when ``right`` is subtracted from ``left``. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_sub) sage: f = CoefficientStream_coefficient_function(lambda n: 1, ZZ, False, 0) @@ -1071,7 +1063,6 @@ class CoefficientStream_mul(CoefficientStream_binary_commutative): INPUT: - ``left`` -- stream of coefficients on the left side of the operator - - ``right`` -- stream of coefficients on the right side of the operator EXAMPLES:: @@ -1086,10 +1077,9 @@ class CoefficientStream_mul(CoefficientStream_binary_commutative): sage: [u[i] for i in range(10)] [0, 1, 3, 6, 10, 15, 21, 28, 36, 45] """ - def __init__(self, left, right): """ - Initalize. + Initalize ``self``. TESTS:: @@ -1106,13 +1096,13 @@ def __init__(self, left, right): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the stream when ``right`` is multiplied with ``left``. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_mul) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 0) @@ -1133,9 +1123,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return a generator for the coefficients of the stream when ``right`` is multiplied with ``left``. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_mul) sage: f = CoefficientStream_coefficient_function(lambda n: 1, ZZ, False, 0) @@ -1164,7 +1154,6 @@ class CoefficientStream_div(CoefficientStream_binary): INPUT: - ``left`` -- stream of coefficients on the left side of the operator - - ``right`` -- stream of coefficients on the right side of the operator EXAMPLES:: @@ -1182,7 +1171,7 @@ class CoefficientStream_div(CoefficientStream_binary): def __init__(self, left, right): """ - Initalize. + Initalize ``self``. TESTS:: @@ -1200,13 +1189,13 @@ def __init__(self, left, right): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the stream when ``left`` is divided by ``right``. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_div) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 1) @@ -1228,9 +1217,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return a generator for the coefficients of the stream when ``left`` is divided by ``right``. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_div) sage: f = CoefficientStream_coefficient_function(lambda n: 1, ZZ, False, 1) @@ -1256,7 +1245,7 @@ def iterate_coefficients(self): class CoefficientStream_composition(CoefficientStream_binary): - """ + r""" Return ``f`` composed by ``g``. This is the composition `(f \circ g)(z) = f(g(z))`. @@ -1278,10 +1267,9 @@ class CoefficientStream_composition(CoefficientStream_binary): sage: [u[i] for i in range(10)] [0, 1, 3, 8, 21, 55, 144, 377, 987, 2584] """ - def __init__(self, f, g): """ - Initalize. + Initalize ``self``. TESTS:: @@ -1307,13 +1295,13 @@ def __init__(self, f, g): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the stream when ``f`` is composed by ``g``. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_composition) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 1) @@ -1336,9 +1324,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return a generator for the coefficients of the stream when ``f`` is composed by ``g``. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_coefficient_function, CoefficientStream_composition) sage: f = CoefficientStream_coefficient_function(lambda n: 1, ZZ, False, 1) @@ -1353,10 +1341,10 @@ def iterate_coefficients(self): yield self.get_coefficient(n) n += 1 + ##################################################################### # Unary operations - class CoefficientStream_scalar(CoefficientStream_unary): """ Operator for multiplying a coefficient stream with a scalar. @@ -1364,7 +1352,6 @@ class CoefficientStream_scalar(CoefficientStream_unary): INPUT: - ``series`` -- a :class:`CoefficientStream` - - ``scalar`` -- a scalar EXAMPLES:: @@ -1375,7 +1362,6 @@ class CoefficientStream_scalar(CoefficientStream_unary): sage: [g[i] for i in range(10)] [0, 2, 2, 2, 2, 2, 2, 2, 2, 2] """ - def __init__(self, series, scalar): """ Initialize. @@ -1389,18 +1375,17 @@ def __init__(self, series, scalar): [-3, -3, -3, -3, -3, -3, -3, -3, -3, -3] """ self._scalar = scalar - super().__init__(series, series._is_sparse, series._approximate_valuation) def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the ``series`` when multiplied by the ``scalar``. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_scalar, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 1) @@ -1414,9 +1399,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return the generator for the coefficients of the ``series`` when multiplied by the ``scalar``. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_scalar, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n^2, ZZ, False, 1) @@ -1430,7 +1415,6 @@ def iterate_coefficients(self): yield self._series[n] * self._scalar n += 1 - class CoefficientStream_neg(CoefficientStream_unary): """ Operator for negative of the stream. @@ -1464,13 +1448,13 @@ def __init__(self, series): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the ``series`` when negated. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_neg, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 1) @@ -1484,9 +1468,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return the generator for the coefficients of the ``series`` when negated. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_neg, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n^2, ZZ, False, 1) @@ -1517,7 +1501,6 @@ class CoefficientStream_inv(CoefficientStream_unary): sage: [g[i] for i in range(10)] [-1, 0, 0, 0, 0, 0, 0, 0, 0, 0] """ - def __init__(self, series): """ Initialize. @@ -1538,13 +1521,13 @@ def __init__(self, series): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the multiplicative inverse of the ``series``. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_inv, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 1) @@ -1564,9 +1547,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return the generator for the coefficients of the multiplicative inverse of the ``series``. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_inv, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n^2, ZZ, False, 1) @@ -1597,9 +1580,7 @@ class CoefficientStream_apply_coeff(CoefficientStream_unary): INPUT: - ``series`` -- a :class:`CoefficientStream` - - - ``function`` -- a python function that modifies the elements of the stream - + - ``function`` -- a function that modifies the elements of the stream - ``ring`` -- the base ring of the stream EXAMPLES:: @@ -1610,7 +1591,6 @@ class CoefficientStream_apply_coeff(CoefficientStream_unary): sage: [g[i] for i in range(10)] [0, -1, -1, -1, -1, -1, -1, -1, -1, -1] """ - def __init__(self, series, function, ring): """ Initialize. @@ -1629,13 +1609,13 @@ def __init__(self, series, function, ring): def get_coefficient(self, n): """ - Return the ``n``-th coefficient of the series with ``function`` applied to each coefficient. + Return the ``n``-th coefficient of ``self``. - INPUT:: + INPUT: - - ``n`` -- integer, the index of the coefficient to be returned + - ``n`` -- integer; the degree for the coefficient - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_apply_coeff, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n, ZZ, True, 1) @@ -1650,9 +1630,9 @@ def get_coefficient(self, n): def iterate_coefficients(self): """ - Return the generator for the coefficients of the series with ``function`` applied to each coefficient. + A generator for the coefficients of ``self``. - TESTS:: + EXAMPLES:: sage: from sage.data_structures.coefficient_stream import (CoefficientStream_apply_coeff, CoefficientStream_coefficient_function) sage: f = CoefficientStream_coefficient_function(lambda n: n^2, ZZ, False, 1) @@ -1666,3 +1646,4 @@ def iterate_coefficients(self): c = self._ring(self._function(self._series[n])) yield c n += 1 + diff --git a/src/sage/rings/lazy_laurent_series.py b/src/sage/rings/lazy_laurent_series.py index 3e5e0bba5b9..8e0c2801b22 100644 --- a/src/sage/rings/lazy_laurent_series.py +++ b/src/sage/rings/lazy_laurent_series.py @@ -102,12 +102,6 @@ class LazyLaurentSeries(ModuleElement): r""" A Laurent series where the coefficients are computed lazily. - INPUT: - - - ``parent`` -- The base ring for the series - - - ``coeff_stream`` -- The auxiliary class that handles the coefficient stream - EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ) @@ -134,7 +128,12 @@ class LazyLaurentSeries(ModuleElement): def __init__(self, parent, coeff_stream): """ - Initialize the series. + Initialize ``self``. + + INPUT: + + - ``parent`` -- the base ring for the series + - ``coeff_stream`` -- the coefficient stream defining the series TESTS:: @@ -153,7 +152,7 @@ def __getitem__(self, n): - ``n`` -- integer - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ) sage: f = z/(1 - 2*z^3) @@ -181,19 +180,20 @@ def __getitem__(self, n): def __call__(self, g): r""" - Return the composition of the series with ``g``. + Return the composition of ``self`` with ``g``. - Given two Laurent Series `f` and `g` over the same base ring, the composition of `f` with `g`, - `(f \circ g)(z) = f(g(z))`, is defined if and only if: - - `g = 0` and `val(f) >= 0` - - `g` is non-zero and `f` has only finitely many non-zero coefficients - - `g` is non-zero and `val(g) > 0` + Given two Laurent Series `f` and `g` over the same base ring, the + composition `(f \circ g)(z) = f(g(z))` is defined if and only if: + + - `g = 0` and `val(f) >= 0`, + - `g` is non-zero and `f` has only finitely many non-zero coefficients, + - `g` is non-zero and `val(g) > 0`. INPUT: - ``g`` -- other series - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(QQ) sage: f = z^2 + 1 + z @@ -804,14 +804,14 @@ def coefficient(self, n): def map_coefficients(self, func, ring=None): """ - Return the series with ``func`` applied to each coefficient of this series. + Return the series with ``func`` applied to each coefficient of ``self``. INPUT: - - ``func`` -- Python function that takes in a coefficient and returns + - ``func`` -- function that takes in a coefficient and returns a new coefficient - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ) sage: s = z/(1 - 2*z) @@ -849,7 +849,7 @@ def change_ring(self, ring): - ``ring`` -- a ring - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ, sparse=False) sage: s = 2 + z @@ -887,7 +887,7 @@ def truncate(self, d): - ``d`` -- integer - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ, sparse=False) sage: alpha = 1/(1-z) @@ -921,9 +921,9 @@ def __pow__(self, n): INPUT: - - ``n`` -- integer, the power to which to raise the series + - ``n`` -- integer; the power to which to raise the series - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ) sage: (1 - z)^-1 @@ -959,12 +959,12 @@ def approximate_series(self, prec, name=None): - ``prec`` -- an integer - - ``name`` -- name of the variable; if it is ``None``, the name of the variable - of the series is used + - ``name`` -- name of the variable; if it is ``None``, the name of + the variable of the series is used OUTPUT: a Laurent series with absolute precision ``prec`` - TESTS:: + EXAMPLES:: sage: L = LazyLaurentSeriesRing(ZZ, 'z') sage: z = L.gen() @@ -1001,7 +1001,7 @@ def prec(self): """ Return the precision of the series, which is infinity. - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ) sage: f = 1/(1 - z) @@ -1011,7 +1011,7 @@ def prec(self): return infinity def polynomial(self, degree=None, name=None): - """ + r""" Return the polynomial or Laurent polynomial if the series is actually so. INPUT: @@ -1021,7 +1021,9 @@ def polynomial(self, degree=None, name=None): - ``name`` -- name of the variable; if it is ``None``, the name of the variable of the series is used - OUTPUT: a Laurent polynomial if the valuation of the series is negative or + OUTPUT: + + A Laurent polynomial if the valuation of the series is negative or a polynomial otherwise. If ``degree`` is not ``None``, the terms of the series of degree @@ -1093,14 +1095,14 @@ def polynomial(self, degree=None, name=None): return R([self[i] for i in range(m)]) def valuation(self): - """ - Return the valuation of the series. + r""" + Return the valuation of ``self``. This method determines the valuation of the series by looking for a nonzero coefficient. Hence if the series happens to be zero, then it may run forever. - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(ZZ) sage: s = 1/(1 - z) - 1/(1 - 2*z) @@ -1152,8 +1154,9 @@ def _repr_(self): return ret + ' + ...' def _richcmp_(self, other, op): - """ - Compare ``self` with ``other`` with respect to the comparison operator ``op``. + r""" + Compare ``self` with ``other`` with respect to the comparison + operator ``op``. Equality is verified if the corresponding coefficients of both series can be checked for equality without computing coefficients @@ -1168,7 +1171,7 @@ def _richcmp_(self, other, op): - ``op`` -- comparison operator - TESTS:: + EXAMPLES:: sage: L. = LazyLaurentSeriesRing(QQ) sage: z + z^2 == z^2 + z @@ -1359,3 +1362,4 @@ def define(self, s): if not isinstance(self._coeff_stream, CoefficientStream_uninitialized) or self._coeff_stream._target is not None: raise ValueError("series already defined") self._coeff_stream._target = s._coeff_stream + diff --git a/src/sage/rings/lazy_laurent_series_ring.py b/src/sage/rings/lazy_laurent_series_ring.py index d4fb001bae1..54a381026c7 100644 --- a/src/sage/rings/lazy_laurent_series_ring.py +++ b/src/sage/rings/lazy_laurent_series_ring.py @@ -65,7 +65,6 @@ # (at your option) any later version. # https://www.gnu.org/licenses/ # **************************************************************************** -import random from sage.structure.unique_representation import UniqueRepresentation from sage.structure.parent import Parent @@ -98,8 +97,8 @@ class LazyLaurentSeriesRing(UniqueRepresentation, Parent): INPUT: - ``base_ring`` -- base ring of this Laurent series ring - - ``names`` -- name of the generator of this Laurent series ring + - ``sparse`` -- (default: ``False``) whether this series is sparse or not EXAMPLES:: @@ -110,7 +109,7 @@ class LazyLaurentSeriesRing(UniqueRepresentation, Parent): def __init__(self, base_ring, names, sparse=False, category=None): """ - Initialize the ring. + Initialize ``self``. TESTS:: @@ -133,10 +132,23 @@ def _repr_(self): """ return "Lazy Laurent Series Ring in {} over {}".format(self.variable_name(), self.base_ring()) + def _latex_(self): + r""" + Return a latex representation of ``self``. + + EXAMPLES:: + + sage: L = LazyLaurentSeriesRing(GF(2), 'z') + sage: latex(L) + \Bold{F}_{2} [\![z]\!] + """ + from sage.misc.latex import latex + return latex(self.base_ring()) + r"[\![{}]\!]".format(self.variable_name()) + @cached_method def gen(self, n=0): """ - Return the generator of this Laurent series ring. + Return the ``n``-th generator of ``self``. EXAMPLES:: @@ -155,8 +167,8 @@ def gen(self, n=0): return self.element_class(self, coeff_stream) def ngens(self): - """ - Return the number of generators of this Laurent series ring. + r""" + Return the number of generators of ``self``. This is always 1. @@ -171,7 +183,7 @@ def ngens(self): @cached_method def gens(self): """ - Return the tuple of the generator. + Return the generators of ``self``. EXAMPLES:: @@ -212,11 +224,10 @@ def _element_constructor_(self, x=None, valuation=None, constant=None, degree=No INPUT: - - ``x`` -- a Laurent series, a Laurent polynomial, a Python function, or a list of elements in the base ring - - - ``valuation`` -- an integer or ``None`` (default: ``None``), the approximate valuation of the series - - - ``constant`` -- either ``None`` (default: ``None``) or pair of an element of the base ring and an integer + - ``x`` -- data used to the define a Laurent series + - ``valuation`` -- integer (optional); the valuation of the series + - ``constant`` -- (optional) the eventual constant of the series + - ``degree`` -- (optional) the degree when the series is ``constant`` EXAMPLES:: @@ -274,9 +285,9 @@ def _element_constructor_(self, x=None, valuation=None, constant=None, degree=No sage: g z^5 + 3*z^6 + 5*z^7 + 7*z^8 + 9*z^9 - z^10 - z^11 - z^12 + ... - TODO:: + .. TODO:: - Add a method to make a copy of self._sparse. + Add a method to change the sparse/dense implementation. """ if x is None: if valuation is None: @@ -323,7 +334,7 @@ def _element_constructor_(self, x=None, valuation=None, constant=None, degree=No def _an_element_(self): """ - Return a Laurent series in this ring. + Return a Laurent series in ``self``. EXAMPLES:: @@ -337,7 +348,7 @@ def _an_element_(self): @cached_method def one(self): - """ + r""" Return the constant series `1`. EXAMPLES:: @@ -351,7 +362,7 @@ def one(self): @cached_method def zero(self): - """ + r""" Return the zero series. EXAMPLES:: @@ -361,3 +372,4 @@ def zero(self): 0 """ return self.element_class(self, CoefficientStream_zero(self._sparse)) +