passagemath-combinat 10.6.42__cp314-cp314-musllinux_1_2_x86_64.whl

sage/combinat/species/all.py

@@ -0,0 +1,48 @@
+# sage_setup: distribution = sagemath-combinat
+r"""
+Combinatorial species
+
+Introductory material
+---------------------
+
+- :ref:`section-examples-catalan`
+- :ref:`section-generic-species`
+
+Basic Species
+-------------
+
+- :ref:`sage.combinat.species.species`
+- :ref:`sage.combinat.species.empty_species`
+- :ref:`sage.combinat.species.recursive_species`
+- :ref:`sage.combinat.species.characteristic_species`
+- :ref:`sage.combinat.species.cycle_species`
+- :ref:`sage.combinat.species.partition_species`
+- :ref:`sage.combinat.species.permutation_species`
+- :ref:`sage.combinat.species.linear_order_species`
+- :ref:`sage.combinat.species.set_species`
+- :ref:`sage.combinat.species.subset_species`
+- :ref:`sage.combinat.species.library`
+
+Operations on Species
+---------------------
+
+- :ref:`sage.combinat.species.sum_species`
+- :ref:`sage.combinat.species.product_species`
+- :ref:`sage.combinat.species.composition_species`
+- :ref:`sage.combinat.species.functorial_composition_species`
+
+Miscellaneous
+-------------
+
+- :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')
+del lazy_import
+del install_doc

sage/combinat/species/characteristic_species.py

@@ -0,0 +1,321 @@
+# sage_setup: distribution = sagemath-combinat
+"""
+Characteristic species
+"""
+# ****************************************************************************
+#       Copyright (C) 2008 Mike Hansen <mhansen@gmail.com>,
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#
+#    This code is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#    General Public License for more details.
+#
+#  The full text of the GPL is available at:
+#
+#                  http://www.gnu.org/licenses/
+# ****************************************************************************
+
+from .species import GenericCombinatorialSpecies
+from sage.arith.misc import factorial
+from .structure import GenericSpeciesStructure
+from .set_species import SetSpecies
+from sage.structure.unique_representation import UniqueRepresentation
+
+
+class CharacteristicSpeciesStructure(GenericSpeciesStructure):
+    def __repr__(self):
+        """
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(3)
+            sage: a = F.structures([1, 2, 3]).random_element(); a
+            {1, 2, 3}
+            sage: F = species.SingletonSpecies()
+            sage: F.structures([1]).list()
+            [1]
+            sage: F = species.EmptySetSpecies()
+            sage: F.structures([]).list()
+            [{}]
+        """
+        s = GenericSpeciesStructure.__repr__(self)
+        if self.parent()._n == 1:
+            return s[1:-1]
+        else:
+            return "{" + s[1:-1] + "}"
+
+    def canonical_label(self):
+        """
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(3)
+            sage: a = F.structures(["a", "b", "c"]).random_element(); a
+            {'a', 'b', 'c'}
+            sage: a.canonical_label()
+            {'a', 'b', 'c'}
+        """
+        P = self.parent()
+        rng = list(range(1, P._n + 1))
+        return CharacteristicSpeciesStructure(P, self._labels, rng)
+
+    def transport(self, perm):
+        """
+        Return the transport of this structure along the permutation ``perm``.
+
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(3)
+            sage: a = F.structures(["a", "b", "c"]).random_element(); a
+            {'a', 'b', 'c'}
+            sage: p = PermutationGroupElement((1,2))                                    # needs sage.groups
+            sage: a.transport(p)                                                        # needs sage.groups
+            {'a', 'b', 'c'}
+        """
+        return self
+
+    def automorphism_group(self):
+        """
+        Return the group of permutations whose action on this structure
+        leave it fixed. For the characteristic species, there is only one
+        structure, so every permutation is in its automorphism group.
+
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(3)
+            sage: a = F.structures(["a", "b", "c"]).random_element(); a
+            {'a', 'b', 'c'}
+            sage: a.automorphism_group()                                                # needs sage.groups
+            Symmetric group of order 3! as a permutation group
+        """
+        from sage.groups.perm_gps.permgroup_named import SymmetricGroup
+        return SymmetricGroup(len(self._labels))
+
+
+class CharacteristicSpecies(GenericCombinatorialSpecies, UniqueRepresentation):
+    def __init__(self, n, min=None, max=None, weight=None):
+        """
+        Return the characteristic species of order `n`.
+
+        This species has exactly one structure on a set of size `n`
+        and no structures on sets of any other size.
+
+        EXAMPLES::
+
+            sage: X = species.CharacteristicSpecies(1)
+            sage: X.structures([1]).list()
+            [1]
+            sage: X.structures([1,2]).list()
+            []
+            sage: X.generating_series()[0:4]
+            [0, 1, 0, 0]
+            sage: X.isotype_generating_series()[0:4]
+            [0, 1, 0, 0]
+            sage: X.cycle_index_series()[0:4]                                           # needs sage.modules
+            [0, p[1], 0, 0]
+
+            sage: F = species.CharacteristicSpecies(3)
+            sage: c = F.generating_series()[0:4]
+            sage: F._check()
+            True
+            sage: F == loads(dumps(F))
+            True
+
+        TESTS::
+
+            sage: S1 = species.CharacteristicSpecies(1)
+            sage: S2 = species.CharacteristicSpecies(1)
+            sage: S3 = species.CharacteristicSpecies(2)
+            sage: S4 = species.CharacteristicSpecies(2, weight=2)
+            sage: S1 is S2
+            True
+            sage: S1 == S3
+            False
+        """
+        self._n = n
+        self._name = "Characteristic species of order %s" % n
+        self._state_info = [n]
+        GenericCombinatorialSpecies.__init__(self, min=min, max=max, weight=weight)
+
+    _default_structure_class = CharacteristicSpeciesStructure
+
+    def _structures(self, structure_class, labels):
+        """
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(2)
+            sage: l = [1, 2, 3]
+            sage: F.structures(l).list()
+            []
+            sage: F = species.CharacteristicSpecies(3)
+            sage: F.structures(l).list()
+            [{1, 2, 3}]
+        """
+        if len(labels) == self._n:
+            yield structure_class(self, labels, range(1,self._n+1))
+
+    _isotypes = _structures
+
+    def _gs_term(self, base_ring):
+        """
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(2)
+            sage: F.generating_series()[0:5]
+            [0, 0, 1/2, 0, 0]
+            sage: F.generating_series().count(2)
+            1
+        """
+        return base_ring(self._weight) / base_ring(factorial(self._n))
+
+    def _order(self):
+        """
+        Return the order of the generating series.
+
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(2)
+            sage: F._order()
+            2
+        """
+        return self._n
+
+    def _itgs_term(self, base_ring):
+        """
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(2)
+            sage: F.isotype_generating_series()[0:5]
+            [0, 0, 1, 0, 0]
+
+        Here we test out weighting each structure by q.
+
+        ::
+
+            sage: R.<q> = ZZ[]
+            sage: Fq = species.CharacteristicSpecies(2, weight=q)
+            sage: Fq.isotype_generating_series()[0:5]
+            [0, 0, q, 0, 0]
+        """
+        return base_ring(self._weight)
+
+    def _cis_term(self, base_ring):
+        """
+        EXAMPLES::
+
+            sage: F = species.CharacteristicSpecies(2)
+            sage: g = F.cycle_index_series()                                            # needs sage.modules
+            sage: g[0:5]                                                                # needs sage.modules
+            [0, 0, 1/2*p[1, 1] + 1/2*p[2], 0, 0]
+        """
+        cis = SetSpecies(weight=self._weight).cycle_index_series(base_ring)
+        return cis.coefficient(self._n)
+
+    def _equation(self, var_mapping):
+        """
+        Return the right hand side of an algebraic equation satisfied by
+        this species. This is a utility function called by the
+        algebraic_equation_system method.
+
+        EXAMPLES::
+
+            sage: C = species.CharacteristicSpecies(2)
+            sage: Qz = QQ['z']
+            sage: R.<node0> = Qz[]
+            sage: var_mapping = {'z':Qz.gen(), 'node0':R.gen()}
+            sage: C._equation(var_mapping)
+            z^2
+        """
+        return var_mapping['z']**(self._n)
+
+
+#Backward compatibility
+CharacteristicSpecies_class = CharacteristicSpecies
+
+
+class EmptySetSpecies(CharacteristicSpecies):
+    def __init__(self, min=None, max=None, weight=None):
+        """
+        Return the empty set species.
+
+        This species has exactly one structure on the empty set. It is
+        the same (and is implemented) as ``CharacteristicSpecies(0)``.
+
+        EXAMPLES::
+
+            sage: X = species.EmptySetSpecies()
+            sage: X.structures([]).list()
+            [{}]
+            sage: X.structures([1,2]).list()
+            []
+            sage: X.generating_series()[0:4]
+            [1, 0, 0, 0]
+            sage: X.isotype_generating_series()[0:4]
+            [1, 0, 0, 0]
+            sage: X.cycle_index_series()[0:4]                                           # needs sage.modules
+            [p[], 0, 0, 0]
+
+        TESTS::
+
+            sage: E1 = species.EmptySetSpecies()
+            sage: E2 = species.EmptySetSpecies()
+            sage: E1 is E2
+            True
+
+            sage: E = species.EmptySetSpecies()
+            sage: E._check()
+            True
+            sage: E == loads(dumps(E))
+            True
+        """
+        CharacteristicSpecies_class.__init__(self, 0, min=min, max=max, weight=weight)
+        self._name = "Empty set species"
+        self._state_info = []
+
+
+#Backward compatibility
+EmptySetSpecies_class = EmptySetSpecies._cached_constructor = EmptySetSpecies
+
+
+class SingletonSpecies(CharacteristicSpecies):
+    def __init__(self, min=None, max=None, weight=None):
+        """
+        Return the species of singletons.
+
+        This species has exactly one structure on a set of size `1`. It
+        is the same (and is implemented) as ``CharacteristicSpecies(1)``.
+
+        EXAMPLES::
+
+            sage: X = species.SingletonSpecies()
+            sage: X.structures([1]).list()
+            [1]
+            sage: X.structures([1,2]).list()
+            []
+            sage: X.generating_series()[0:4]
+            [0, 1, 0, 0]
+            sage: X.isotype_generating_series()[0:4]
+            [0, 1, 0, 0]
+            sage: X.cycle_index_series()[0:4]                                           # needs sage.modules
+            [0, p[1], 0, 0]
+
+        TESTS::
+
+            sage: S1 = species.SingletonSpecies()
+            sage: S2 = species.SingletonSpecies()
+            sage: S1 is S2
+            True
+
+            sage: S = species.SingletonSpecies()
+            sage: S._check()
+            True
+            sage: S == loads(dumps(S))
+            True
+        """
+        CharacteristicSpecies_class.__init__(self, 1, min=min, max=max, weight=weight)
+        self._name = "Singleton species"
+        self._state_info = []
+
+
+#Backward compatibility
+SingletonSpecies_class = SingletonSpecies

sage/combinat/species/composition_species.py

@@ -0,0 +1,273 @@
+# sage_setup: distribution = sagemath-combinat
+"""
+Composition species
+"""
+#*****************************************************************************
+#       Copyright (C) 2008 Mike Hansen <mhansen@gmail.com>,
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#
+#    This code is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#    General Public License for more details.
+#
+#  The full text of the GPL is available at:
+#
+#                  http://www.gnu.org/licenses/
+#*****************************************************************************
+from .species import GenericCombinatorialSpecies
+from .structure import GenericSpeciesStructure
+from .partition_species import PartitionSpecies
+from sage.structure.unique_representation import UniqueRepresentation
+
+
+class CompositionSpeciesStructure(GenericSpeciesStructure):
+    def __init__(self, parent, labels, pi, f, gs):
+        """
+        TESTS::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            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
+            True
+        """
+        self._partition = pi
+        GenericSpeciesStructure.__init__(self, parent, labels, [f, gs])
+
+    def __repr__(self):
+        """
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: L.structures(['a','b','c'])[0]                                        # needs sage.libs.flint
+            F-structure: {{'a', 'b', 'c'}}; G-structures: (('a', 'b', 'c'),)
+        """
+        f, gs = self._list
+        return "F-structure: %s; G-structures: %s" % (repr(f), repr(gs))
+
+    def transport(self, perm):
+        """
+        EXAMPLES::
+
+            sage: p = PermutationGroupElement((2,3))                                    # needs sage.groups
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: S = L.structures(['a','b','c']).list()                                # needs sage.libs.flint
+            sage: a = S[2]; a                                                           # needs sage.libs.flint
+            F-structure: {{'a', 'c'}, {'b'}}; G-structures: (('a', 'c'), ('b'))
+            sage: a.transport(p)                                                        # needs sage.groups sage.libs.flint
+            F-structure: {{'a', 'b'}, {'c'}}; G-structures: (('a', 'c'), ('b'))
+        """
+        f, gs = self._list
+        pi = self._partition.transport(perm)
+        f = f.change_labels(pi._list)
+        _ = [g.change_labels(part) for g, part in zip(gs, pi)]  # TODO: BUG HERE ?
+        return self.__class__(self, self._labels, pi, f, gs)
+
+    def change_labels(self, labels):
+        """
+        Return a relabelled structure.
+
+        INPUT:
+
+        - ``labels`` -- list of labels
+
+        OUTPUT:
+
+        A structure with the `i`-th label of ``self`` replaced with the `i`-th
+        label of the list.
+
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: S = L.structures(['a','b','c']).list()                                # needs sage.libs.flint
+            sage: a = S[2]; a                                                           # needs sage.libs.flint
+            F-structure: {{'a', 'c'}, {'b'}}; G-structures: (('a', 'c'), ('b'))
+            sage: a.change_labels([1,2,3])                                              # needs sage.libs.flint
+            F-structure: {{1, 3}, {2}}; G-structures: [(1, 3), (2)]
+        """
+        f, gs = self._list
+        pi = self._partition.change_labels(labels)
+        f = f.change_labels(list(pi))
+        g = [g.change_labels(part) for g, part in zip(gs, pi)]
+        return self.__class__(self, labels, pi, f, g)
+
+
+class CompositionSpecies(GenericCombinatorialSpecies, UniqueRepresentation):
+    def __init__(self, F, G, min=None, max=None, weight=None):
+        """
+        Return the composition of two species.
+
+        EXAMPLES::
+
+            sage: E = species.SetSpecies()
+            sage: C = species.CycleSpecies()
+            sage: S = E(C)
+            sage: S.generating_series()[:5]
+            [1, 1, 1, 1, 1]
+            sage: E(C) is S
+            True
+
+        TESTS::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: c = L.generating_series()[:3]
+            sage: L._check()  #False due to isomorphism types not being implemented     # needs sage.libs.flint
+            False
+            sage: L == loads(dumps(L))
+            True
+        """
+        self._F = F
+        self._G = G
+        self._name = "Composition of (%s) and (%s)" % (F, G)
+        self._state_info = [F, G]
+        GenericCombinatorialSpecies.__init__(self, min=None, max=None, weight=None)
+
+    _default_structure_class = CompositionSpeciesStructure
+
+    def _structures(self, structure_class, labels):
+        """
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: L.structures(['a','b','c']).list()                                    # needs sage.libs.flint
+            [F-structure: {{'a', 'b', 'c'}}; G-structures: (('a', 'b', 'c'),),
+             F-structure: {{'a', 'b', 'c'}}; G-structures: (('a', 'c', 'b'),),
+             F-structure: {{'a', 'c'}, {'b'}}; G-structures: (('a', 'c'), ('b')),
+             F-structure: {{'a', 'b'}, {'c'}}; G-structures: (('a', 'b'), ('c')),
+             F-structure: {{'b', 'c'}, {'a'}}; G-structures: (('b', 'c'), ('a')),
+             F-structure: {{'a'}, {'b'}, {'c'}}; G-structures: (('a'), ('b'), ('c'))]
+
+        TESTS::
+
+            sage: # needs sage.libs.flint
+            sage: a = _[2]
+            sage: f, gs = a._list
+            sage: f
+            {{'a', 'c'}, {'b'}}
+            sage: f.parent()
+            Set species
+            sage: f._list
+            [1, 2]
+            sage: f._labels
+            [{'a', 'c'}, {'b'}]
+            sage: [g.parent() for g in gs]
+            [Cyclic permutation species, Cyclic permutation species]
+            sage: [g._labels for g in gs]
+            [['a', 'c'], ['b']]
+            sage: [g._list for g in gs]
+            [[1, 2], [1]]
+        """
+        from itertools import product
+        P = PartitionSpecies()
+        for pi in P.structures(labels):
+            # The labels of the G-structures will be just be the things
+            # in labels
+            gs = product(*[self._G.structures(part.label_subset()) for part in pi])
+
+            # The labels of the F-structure will be set objects
+            fs = self._F.structures(list(pi))
+            for f, gg in product(fs, gs):
+                yield structure_class(self, labels, pi, f, gg)
+
+    def _isotypes(self, structure_class, labels):
+        """
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: L.isotypes(['a','b','c']).list()                                      # needs sage.modules
+            Traceback (most recent call last):
+            ...
+            NotImplementedError
+        """
+        raise NotImplementedError
+
+    def _gs(self, series_ring, base_ring):
+        """
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: L.generating_series()[:5]
+            [1, 1, 1, 1, 1]
+        """
+        return self._F.generating_series(base_ring)(self._G.generating_series(base_ring))
+
+    def _itgs(self, series_ring, base_ring):
+        """
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: L.isotype_generating_series()[:10]                                    # needs sage.modules
+            [1, 1, 2, 3, 5, 7, 11, 15, 22, 30]
+        """
+        cis = self.cycle_index_series(base_ring)
+        return cis.isotype_generating_series()
+
+    def _cis(self, series_ring, base_ring):
+        """
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: L.cycle_index_series()[:5]                                            # needs sage.modules
+            [p[],
+             p[1],
+             p[1, 1] + p[2],
+             p[1, 1, 1] + p[2, 1] + p[3],
+             p[1, 1, 1, 1] + p[2, 1, 1] + p[2, 2] + p[3, 1] + p[4]]
+
+        Here we (indirectly) check that the cycle index series for
+        permutations weighted by the number of cycles is correctly
+        computed.
+
+        ::
+
+            sage: t = QQ['t'].gen()
+            sage: E = species.SetSpecies()
+            sage: C = species.CycleSpecies(weight=t)
+            sage: S = E(C)
+            sage: S.isotype_generating_series()[:5]  #indirect                          # needs sage.modules
+            [1, t, t^2 + t, t^3 + t^2 + t, t^4 + t^3 + 2*t^2 + t]
+
+        We do the same thing with set partitions weighted by the number of
+        blocks.
+
+        ::
+
+            sage: t = QQ['t'].gen()
+            sage: E = species.SetSpecies()
+            sage: E_t = species.SetSpecies(min=1,weight=t)
+            sage: Par = E(E_t)
+            sage: Par.isotype_generating_series()[:5]                                   # needs sage.modules
+            [1, t, t^2 + t, t^3 + t^2 + t, t^4 + t^3 + 2*t^2 + t]
+        """
+        f_cis = self._F.cycle_index_series(base_ring)
+        g_cis = self._G.cycle_index_series(base_ring)
+        return f_cis(g_cis)
+
+    def weight_ring(self):
+        """
+        Return the weight ring for this species. This is determined by
+        asking Sage's coercion model what the result is when you multiply
+        (and add) elements of the weight rings for each of the operands.
+
+        EXAMPLES::
+
+            sage: E = species.SetSpecies(); C = species.CycleSpecies()
+            sage: L = E(C)
+            sage: L.weight_ring()
+            Rational Field
+        """
+        return self._common_parent([self._F.weight_ring(), self._G.weight_ring()])
+
+
+CompositionSpecies_class = CompositionSpecies