Lazy species

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

@@ -407,3 +407,4 @@ Comprehensive Module List
     sage/combinat/words/words
     sage/combinat/yang_baxter_graph
     sage/rings/cfinite_sequence
+    sage/rings/lazy_species

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

@@ -3147,6 +3147,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> = LazySpecies(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 = LazySpecies(R, "X")
+    sage: E = L.Sets()
+    sage: Ep = E.restrict(1)
+    sage: M.<X, Y> = LazySpecies(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 LazySpecies"))
+
+lazy_import("sage.combinat.species", "library", as_='species',
+            deprecation=(38544, "combinat.species is superseded by LazySpecies"))
 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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+        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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+        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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+            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 LazySpecies
+    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 LazySpecies
+            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 LazySpecies
+    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 LazySpecies
+            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 LazySpecies
+            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/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', 'LazySpecies')
+
 # Tate algebras
 from sage.rings.tate_algebra import TateAlgebra
 

src/sage/rings/lazy_series.py

@@ -7126,8 +7126,7 @@ def arithmetic_product(self, *args):
             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 = LazySpecies(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])