functorial composition

src/doc/en/reference/combinat/module_list.rst

@@ -28,6 +28,7 @@ Comprehensive Module List
     sage/combinat/blob_algebra
     sage/combinat/cartesian_product
     sage/combinat/catalog_partitions
+    sage/rings/cfinite_sequence
     sage/combinat/chas/all
     sage/combinat/chas/fsym
     sage/combinat/chas/wqsym
@@ -154,6 +155,7 @@ Comprehensive Module List
     sage/combinat/key_polynomial
     sage/combinat/knutson_tao_puzzles
     sage/combinat/k_tableau
+    sage/rings/lazy_species
     sage/combinat/lr_tableau
     sage/combinat/matrices/all
     sage/combinat/matrices/dancing_links
@@ -408,4 +410,3 @@ Comprehensive Module List
     sage/combinat/words/word_options
     sage/combinat/words/words
     sage/combinat/yang_baxter_graph
-    sage/rings/cfinite_sequence

src/doc/en/reference/references/index.rst

@@ -3162,6 +3162,10 @@ REFERENCES:
             descent algebra.* Adv. Math. **77** (1989).
             https://web.archive.org/web/20210829143502/http://lacim-membre.uqam.ca/~christo/Publi%C3%A9s/1989/Decomposition%20Solomon.pdf
 
+.. [GL2011] Ira M. Gessel, Ji Li.
+            *Enumeration of point-determining graphs*. Journal of
+            Combinatorial Theory, Series A, 118 (2011), pp. 591--612.
+
 .. [GR1993] Ira M. Gessel, Christophe Reutenauer.
             *Counting Permutations with Given Cycle Structure and Descent Set*. Journal of
             Combinatorial Theory, Series A, 64 (1993), pp. 189--215.

src/sage/combinat/species/all.py

@@ -1,9 +1,66 @@
 r"""
 Combinatorial species
 
-.. TODO:: Short blurb about species
+A combinatorial species, as introduced by Joyal, is a functor from
+the category of finite sets with bijections to the category of finite
+sets with bijections.  Alternatively, we can regard a combinatorial
+species as a formal sum of group actions of the symmetric groups
+`\mathfrak S_n`, for `n\in\NN`.  For example, the trivial action of
+`\mathfrak S_n` corresponds to the species `\mathcal E_n` of sets of
+cardinality `n`.
 
-.. TODO:: Proofread / point to the main classes rather than the modules?
+More generally, a weighted multisort species in `k` sorts is a
+functor from the category of `k`-tuples of finite sets with
+bijections to the category of weighted finite sets with
+weight-preserving bijections.  We may think of the sorts as
+variables, traditionally denoted by `X, Y, Z`.
+
+Such a species is equivalent to a formal sum of group actions of
+groups `\mathfrak S_{n_1} \times \cdots \times \mathfrak S_{n_k}` with
+`(n_1,\ldots,n_k)\in\NN^k`, together with a weight on the orbits of
+each group action.  Yet more generally, a virtual weighted multisort
+species is a formal difference of weighted multisort species.
+
+We regard a combinatorial species as a sequence of group actions of
+the symmetric groups `\mathfrak S_n`, for `n\in\NN`.
+
+Coefficients of lazy species are computed on demand.  They have
+infinite precision, although equality can only be decided in special
+cases.
+
+There are currently two implementations of combinatorial species, one
+of which is deprecated and will be removed once all of the
+functionality has been ported to the new framework.
+
+The recommended implementation is :ref:`sage.rings.lazy_species` and
+used as the following examples illustrate.
+
+EXAMPLES:
+
+We define rooted ordered trees with leaves having weight `q`::
+
+    sage: R.<q> = QQ[]
+    sage: L.<X> = LazyCombinatorialSpecies(R)
+    sage: leaf = X
+    sage: node = q * X
+    sage: linorder = X/(1 - X)
+    sage: T = L.undefined(valuation=1)
+    sage: T.define(leaf + node * linorder(T))
+    sage: T.isotype_generating_series()
+    X + q*X^2 + ((q^2+q)*X^3) + ((q^3+3*q^2+q)*X^4) + ((q^4+6*q^3+6*q^2+q)*X^5)
+    + ((q^5+10*q^4+20*q^3+10*q^2+q)*X^6) + O(X^7)
+
+We define rooted unordered trees with leaves of sort `Y`.  The
+standard representation of a species is its molecular decomposition::
+
+    sage: L = LazyCombinatorialSpecies(R, "X")
+    sage: E = L.Sets()
+    sage: Ep = E.restrict(1)
+    sage: M.<X, Y> = LazyCombinatorialSpecies(R)
+    sage: A = M.undefined(valuation=1)
+    sage: A.define(Y + X * Ep(A))
+    sage: A.truncate(5)
+    Y + X*Y + (X^2*Y+X*E_2(Y)) + (X^3*Y+X^2*E_2(Y)+X^2*Y^2+X*E_3(Y))
 
 Introductory material
 ---------------------
@@ -39,13 +96,17 @@
 
 - :ref:`sage.combinat.species.structure`
 - :ref:`sage.combinat.species.misc`
+
 """
 # install the docstring of this module to the containing package
 from sage.misc.namespace_package import install_doc
 install_doc(__package__, __doc__)
 
 from sage.misc.lazy_import import lazy_import
-lazy_import("sage.combinat.species.recursive_species", "CombinatorialSpecies")
-lazy_import("sage.combinat.species", "library", as_='species')
+lazy_import("sage.combinat.species.recursive_species", "CombinatorialSpecies",
+            deprecation=(38544, "combinat.species is superseded by LazyCombinatorialSpecies"))
+
+lazy_import("sage.combinat.species", "library", as_='species',
+            deprecation=(38544, "combinat.species is superseded by LazyCombinatorialSpecies"))
 del lazy_import
 del install_doc

src/sage/combinat/species/characteristic_species.py

@@ -29,6 +29,9 @@ def __repr__(self):
         EXAMPLES::
 
             sage: F = species.CharacteristicSpecies(3)
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: a = F.structures([1, 2, 3]).random_element(); a
             {1, 2, 3}
             sage: F = species.SingletonSpecies()

src/sage/combinat/species/composition_species.py

@@ -27,6 +27,9 @@ def __init__(self, parent, labels, pi, f, gs):
         TESTS::
 
             sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: L = E(C)
             sage: a = L.structures(['a','b','c']).random_element()                      # needs sage.libs.flint
             sage: a == loads(dumps(a))                                                  # needs sage.libs.flint

src/sage/combinat/species/cycle_species.py

@@ -25,6 +25,10 @@ def __repr__(self):
         EXAMPLES::
 
             sage: S = species.CycleSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
+
             sage: S.structures(["a","b","c"])[0]
             ('a', 'b', 'c')
         """

src/sage/combinat/species/empty_species.py

@@ -27,6 +27,9 @@ class EmptySpecies(GenericCombinatorialSpecies, UniqueRepresentation):
     EXAMPLES::
 
         sage: X = species.EmptySpecies(); X
+        doctest:warning...
+        DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+        See https://github.com/sagemath/sage/issues/38544 for details.
         Empty species
         sage: X.structures([]).list()
         []

src/sage/combinat/species/functorial_composition_species.py

@@ -31,6 +31,9 @@ def __init__(self, F, G, min=None, max=None, weight=None):
         EXAMPLES::
 
             sage: E = species.SetSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: E2 = species.SetSpecies(size=2)
             sage: WP = species.SubsetSpecies()
             sage: P2 = E2*E

src/sage/combinat/species/generating_series.py

@@ -216,6 +216,9 @@ def functorial_composition(self, y):
         EXAMPLES::
 
             sage: G = species.SimpleGraphSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: g = G.generating_series()
             sage: [g.coefficient(i) for i in range(10)]
             [1, 1, 1, 4/3, 8/3, 128/15, 2048/45, 131072/315, 2097152/315, 536870912/2835]

src/sage/combinat/species/library.py

@@ -41,6 +41,9 @@ def SimpleGraphSpecies():
     EXAMPLES::
 
         sage: S = species.SimpleGraphSpecies()
+        doctest:warning...
+        DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+        See https://github.com/sagemath/sage/issues/38544 for details.
         sage: S.generating_series().counts(10)
         [1, 1, 2, 8, 64, 1024, 32768, 2097152, 268435456, 68719476736]
         sage: S.cycle_index_series()[:5]                                                # needs sage.modules

src/sage/combinat/species/linear_order_species.py

@@ -27,6 +27,9 @@ def canonical_label(self):
         EXAMPLES::
 
             sage: P = species.LinearOrderSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: s = P.structures(["a", "b", "c"]).random_element()
             sage: s.canonical_label()
             ['a', 'b', 'c']

src/sage/combinat/species/partition_species.py

@@ -33,6 +33,9 @@ def __init__(self, parent, labels, list):
 
             sage: from sage.combinat.species.partition_species import PartitionSpeciesStructure
             sage: P = species.PartitionSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: s = PartitionSpeciesStructure(P, ['a','b','c'], [[1,2],[3]]); s
             {{'a', 'b'}, {'c'}}
             sage: s == loads(dumps(s))

src/sage/combinat/species/permutation_species.py

@@ -30,6 +30,10 @@ def canonical_label(self):
         EXAMPLES::
 
             sage: P = species.PermutationSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
+
             sage: S = P.structures(["a", "b", "c"])
             sage: [s.canonical_label() for s in S]
             [['a', 'b', 'c'],

src/sage/combinat/species/product_species.py

@@ -27,6 +27,9 @@ def __init__(self, parent, labels, subset, left, right):
         TESTS::
 
             sage: S = species.SetSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: F = S * S
             sage: a = F.structures(['a','b','c']).random_element()
             sage: a == loads(dumps(a))

src/sage/combinat/species/recursive_species.py

@@ -30,6 +30,9 @@ def __init__(self, min=None):
         EXAMPLES::
 
             sage: F = CombinatorialSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: loads(dumps(F))
             Combinatorial species
 

src/sage/combinat/species/set_species.py

@@ -29,6 +29,9 @@ def __repr__(self):
         EXAMPLES::
 
             sage: S = species.SetSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: a = S.structures(["a","b","c"]).random_element(); a
             {'a', 'b', 'c'}
         """

src/sage/combinat/species/species.py

@@ -20,6 +20,9 @@
 
     sage: q = QQ['q'].gen()
     sage: leaf = species.SingletonSpecies()
+    doctest:warning...
+    DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+    See https://github.com/sagemath/sage/issues/38544 for details.
     sage: internal_node = species.SingletonSpecies(weight=q)
     sage: L = species.LinearOrderSpecies(min=1)
     sage: T = species.CombinatorialSpecies(min=1)
@@ -139,6 +142,9 @@ def __eq__(self, x):
             sage: X = species.SingletonSpecies()
             sage: E = species.EmptySetSpecies()
             sage: L = CombinatorialSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: L.define(E+X*L)
             sage: K = CombinatorialSpecies()
             sage: K.define(E+X*L)

src/sage/combinat/species/structure.py

@@ -13,6 +13,9 @@
 Here we define this species using the default structures::
 
     sage: ball = species.SingletonSpecies()
+    doctest:warning...
+    DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+    See https://github.com/sagemath/sage/issues/38544 for details.
     sage: bar = species.EmptySetSpecies()
     sage: BB = CombinatorialSpecies()
     sage: BB.define(ball + ball*BB + ball*bar*BB)

src/sage/combinat/species/subset_species.py

@@ -32,6 +32,9 @@ def __repr__(self):
 
             sage: set_random_seed(0)
             sage: S = species.SubsetSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: a = S.structures(["a","b","c"])[0]; a
             {}
         """

src/sage/combinat/species/sum_species.py

@@ -32,6 +32,9 @@ def __init__(self, F, G, min=None, max=None, weight=None):
         EXAMPLES::
 
             sage: S = species.PermutationSpecies()
+            doctest:warning...
+            DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
+            See https://github.com/sagemath/sage/issues/38544 for details.
             sage: A = S+S
             sage: A.generating_series()[:5]
             [2, 2, 2, 2, 2]

src/sage/data_structures/stream.py

@@ -4279,7 +4279,7 @@ def __init__(self, series, shift, minimal_valuation):
             3
         """
         super().__init__(series, series._is_sparse, False)
-        assert isinstance(series, Stream_inexact)
+        assert isinstance(series, (Stream_inexact, Stream_uninitialized))
         # We share self._series._cache but not self._series._approximate order
         # self._approximate_order cannot be updated by self._series.__getitem__
         self._cache = series._cache

src/sage/rings/all.py

@@ -123,6 +123,9 @@
 lazy_import('sage.rings.lazy_series_ring', ['LazyLaurentSeriesRing', 'LazyPowerSeriesRing',
                                             'LazySymmetricFunctions', 'LazyDirichletSeriesRing'])
 
+# Lazy combinatorial species
+lazy_import('sage.rings.lazy_species', 'LazyCombinatorialSpecies')
+
 # Tate algebras
 from sage.rings.tate_algebra import TateAlgebra
 

src/sage/rings/lazy_series.py

@@ -657,6 +657,66 @@
             return P.zero()
         return P.element_class(P, Stream_exact(initial_coefficients, order=v))
 
+    def restrict(self, min_degree=None, max_degree=None):
+        r"""
+        Return the series obtained by keeping only terms of
+        degree between ``min_degree`` and ``max_degree``.
+
+        INPUT:
+
+        - ``min_degree``, ``max_degree`` -- (optional) integers
+          indicating which degrees to keep
+
+        EXAMPLES::
+
+            sage: L.<z> = LazyLaurentSeriesRing(ZZ)
+            sage: alpha = z + 2*z^2 + 3*z^3 + z^4/(1-z)
+            sage: alpha
+            z + 2*z^2 + 3*z^3 + z^4 + z^5 + z^6 + O(z^7)
+            sage: alpha.restrict(2)
+            2*z^2 + 3*z^3 + z^4 + z^5 + z^6 + O(z^7)
+            sage: alpha.restrict(3)
+            3*z^3 + z^4 + z^5 + z^6 + O(z^7)
+            sage: alpha.restrict(3, 6)
+            3*z^3 + z^4 + z^5 + z^6
+            sage: alpha.restrict(max_degree=6)
+            z + 2*z^2 + 3*z^3 + z^4 + z^5 + z^6
+
+            sage: L.<z> = LazyLaurentSeriesRing(QQ)
+            sage: exp(z).restrict(3)
+            1/6*z^3 + 1/24*z^4 + 1/120*z^5 + 1/720*z^6 + 1/5040*z^7 + 1/40320*z^8 + 1/362880*z^9 + O(z^10)
+        """
+        P = self.parent()
+        if max_degree is None and min_degree is None:
+            return self
+        elif max_degree is None:
+            v = max(self._coeff_stream._approximate_order, min_degree)
+            if isinstance(self._coeff_stream, Stream_exact):
+                degree = self._coeff_stream._degree
+                if degree <= min_degree:
+                    coeff_stream = Stream_exact([],
+                                                order=v,
+                                                constant=self._coeff_stream._constant)
+                else:
+                    initial_coefficients = self._coeff_stream._initial_coefficients[min_degree-degree:]
+                    coeff_stream = Stream_exact(initial_coefficients,
+                                                order=v,
+                                                constant=self._coeff_stream._constant)
+            else:
+                coeff_stream = Stream_truncated(self._coeff_stream, 0, v)
+        else:
+            if min_degree is None:
+                v = self._coeff_stream._approximate_order
+            else:
+                v = max(self._coeff_stream._approximate_order, min_degree)
+            initial_coefficients = [self._coeff_stream[i]
+                                    for i in range(v, max_degree + 1)]
+            if not any(initial_coefficients):
+                coeff_stream = Stream_zero()
+            else:
+                coeff_stream = Stream_exact(initial_coefficients, order=v)
+        return P.element_class(P, coeff_stream)
+
     def shift(self, n):
         r"""
         Return ``self`` with the indices shifted by ``n``.
@@ -7219,8 +7279,7 @@
             sage: L = LazySymmetricFunctions(m)                                         # needs sage.modules
 
             sage: # needs sage.modules
-            sage: C = species.CycleSpecies().cycle_index_series()
-            sage: c = L(lambda n: C[n])
+            sage: c = LazyCombinatorialSpecies(QQ, "X").Cycles().cycle_index_series()
             sage: Lplus = L(lambda n: p([1]*n), valuation=1)
             sage: r = c.arithmetic_product(Lplus); r                                    # needs sage.libs.pari
             m[1] + (3*m[1,1]+2*m[2])