passagemath-combinat 10.6.42__cp314-cp314-musllinux_1_2_x86_64.whl

sage/combinat/species/cycle_species.py

@@ -0,0 +1,284 @@
+# sage_setup: distribution = sagemath-combinat
+"""
+Cycle species
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2008 Mike Hansen <mhansen@gmail.com>,
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  http://www.gnu.org/licenses/
+# ***************************************************************************
+
+from sage.arith.misc import divisors, euler_phi
+from sage.combinat.species.misc import accept_size
+from sage.combinat.species.species import GenericCombinatorialSpecies
+from sage.combinat.species.structure import GenericSpeciesStructure
+from sage.structure.unique_representation import UniqueRepresentation
+
+
+class CycleSpeciesStructure(GenericSpeciesStructure):
+    def __repr__(self):
+        """
+        EXAMPLES::
+
+            sage: S = species.CycleSpecies()
+            sage: S.structures(["a","b","c"])[0]
+            ('a', 'b', 'c')
+        """
+        s = GenericSpeciesStructure.__repr__(self)
+        return "("+s[1:-1]+")"
+
+    def canonical_label(self):
+        """
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: P.structures(["a","b","c"]).random_element().canonical_label()
+            ('a', 'b', 'c')
+        """
+        n = len(self._labels)
+        return CycleSpeciesStructure(self.parent(), self._labels, range(1, n+1))
+
+    def permutation_group_element(self):
+        """
+        Return this cycle as a permutation group element.
+
+        EXAMPLES::
+
+            sage: F = species.CycleSpecies()
+            sage: a = F.structures(["a", "b", "c"])[0]; a
+            ('a', 'b', 'c')
+            sage: a.permutation_group_element()                                         # needs sage.groups
+            (1,2,3)
+        """
+        from sage.groups.perm_gps.constructor import PermutationGroupElement
+        return PermutationGroupElement(tuple(self._list))
+
+    def transport(self, perm):
+        """
+        Return the transport of this structure along the permutation
+        perm.
+
+        EXAMPLES::
+
+            sage: F = species.CycleSpecies()
+            sage: a = F.structures(["a", "b", "c"])[0]; a
+            ('a', 'b', 'c')
+            sage: p = PermutationGroupElement((1,2))                                    # needs sage.groups
+            sage: a.transport(p)                                                        # needs sage.groups
+            ('a', 'c', 'b')
+        """
+        p = self.permutation_group_element()
+        p = perm*p*~perm
+        new_list = [1]
+        for i in range(len(self._list)-1):
+            new_list.append( p(new_list[-1]) )
+        return CycleSpeciesStructure(self.parent(), self._labels, new_list)
+
+    def automorphism_group(self):
+        """
+        Return the group of permutations whose action on this structure
+        leave it fixed.
+
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: a = P.structures([1, 2, 3, 4])[0]; a
+            (1, 2, 3, 4)
+            sage: a.automorphism_group()                                                # needs sage.groups
+            Permutation Group with generators [(1,2,3,4)]
+
+        ::
+
+            sage: [a.transport(perm) for perm in a.automorphism_group()]                # needs sage.groups
+            [(1, 2, 3, 4), (1, 2, 3, 4), (1, 2, 3, 4), (1, 2, 3, 4)]
+        """
+        from sage.groups.perm_gps.permgroup_named import SymmetricGroup
+        from sage.groups.perm_gps.permgroup import PermutationGroup
+        S = SymmetricGroup(len(self._labels))
+        p = self.permutation_group_element()
+        return PermutationGroup(S.centralizer(p).gens())
+
+
+class CycleSpecies(GenericCombinatorialSpecies, UniqueRepresentation):
+    @staticmethod
+    @accept_size
+    def __classcall__(cls, *args, **kwds):
+        r"""
+        EXAMPLES::
+
+            sage: C = species.CycleSpecies(); C
+            Cyclic permutation species
+        """
+        return super().__classcall__(cls, *args, **kwds)
+
+    def __init__(self, min=None, max=None, weight=None):
+        """
+        Return the species of cycles.
+
+        EXAMPLES::
+
+            sage: C = species.CycleSpecies(); C
+            Cyclic permutation species
+            sage: C.structures([1,2,3,4]).list()
+            [(1, 2, 3, 4),
+             (1, 2, 4, 3),
+             (1, 3, 2, 4),
+             (1, 3, 4, 2),
+             (1, 4, 2, 3),
+             (1, 4, 3, 2)]
+
+        TESTS:
+
+        We check to verify that the caching of species is actually
+        working.
+
+        ::
+
+            sage: species.CycleSpecies() is species.CycleSpecies()
+            True
+
+            sage: P = species.CycleSpecies()
+            sage: c = P.generating_series()[:3]
+            sage: P._check()
+            True
+            sage: P == loads(dumps(P))
+            True
+        """
+        GenericCombinatorialSpecies.__init__(self, min=min, max=max, weight=weight)
+        self._name = "Cyclic permutation species"
+
+    _default_structure_class = CycleSpeciesStructure
+
+    def _structures(self, structure_class, labels):
+        """
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: P.structures([1,2,3]).list()
+            [(1, 2, 3), (1, 3, 2)]
+        """
+        from sage.combinat.permutation import CyclicPermutations
+        for c in CyclicPermutations(range(1, len(labels)+1)):
+            yield structure_class(self, labels, c)
+
+    def _isotypes(self, structure_class, labels):
+        """
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: P.isotypes([1,2,3]).list()
+            [(1, 2, 3)]
+        """
+        if len(labels) != 0:
+            yield structure_class(self, labels, range(1, len(labels)+1))
+
+    def _gs_callable(self, base_ring, n):
+        r"""
+        The generating series for cyclic permutations is
+        `-\log(1-x) = \sum_{n=1}^\infty x^n/n`.
+
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: g = P.generating_series()
+            sage: g[0:10]
+            [0, 1, 1/2, 1/3, 1/4, 1/5, 1/6, 1/7, 1/8, 1/9]
+
+        TESTS::
+
+            sage: P = species.CycleSpecies()
+            sage: g = P.generating_series(RR)
+            sage: g[0:3]
+            [0.0..., 1.0..., 0.5...]
+        """
+        if n:
+            return self._weight * base_ring.one() / n
+        return base_ring.zero()
+
+    def _order(self):
+        """
+        Return the order of the generating series.
+
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: P._order()
+            1
+        """
+        return 1
+
+    def _itgs_list(self, base_ring, n):
+        """
+        The isomorphism type generating series for cyclic permutations is
+        given by `x/(1-x)`.
+
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: g = P.isotype_generating_series()
+            sage: g[0:5]
+            [0, 1, 1, 1, 1]
+
+        TESTS::
+
+            sage: P = species.CycleSpecies()
+            sage: g = P.isotype_generating_series(RR)
+            sage: g[0:3]
+            [0.0..., 1.0..., 1.0...]
+        """
+        if n:
+            return self._weight * base_ring.one()
+        return base_ring.zero()
+
+    def _cis_callable(self, base_ring, n):
+        r"""
+        The cycle index series of the species of cyclic permutations is
+        given by
+
+        .. MATH::
+
+             -\sum_{k=1}^\infty \phi(k)/k * log(1 - x_k)
+
+
+        which is equal to
+
+        .. MATH::
+
+             \sum_{n=1}^\infty \frac{1}{n} * \sum_{k|n} \phi(k) * x_k^{n/k}
+
+        .
+
+        EXAMPLES::
+
+            sage: P = species.CycleSpecies()
+            sage: cis = P.cycle_index_series()                                          # needs sage.modules
+            sage: cis[0:7]                                                              # needs sage.libs.pari sage.modules
+            [0,
+             p[1],
+             1/2*p[1, 1] + 1/2*p[2],
+             1/3*p[1, 1, 1] + 2/3*p[3],
+             1/4*p[1, 1, 1, 1] + 1/4*p[2, 2] + 1/2*p[4],
+             1/5*p[1, 1, 1, 1, 1] + 4/5*p[5],
+             1/6*p[1, 1, 1, 1, 1, 1] + 1/6*p[2, 2, 2] + 1/3*p[3, 3] + 1/3*p[6]]
+        """
+        from sage.combinat.sf.sf import SymmetricFunctions
+        p = SymmetricFunctions(base_ring).power()
+
+        zero = base_ring.zero()
+
+        if not n:
+            return zero
+        res = zero
+        for k in divisors(n):
+            res += euler_phi(k)*p([k])**(n//k)
+        res /= n
+        return self._weight * res
+
+
+#Backward compatibility
+CycleSpecies_class = CycleSpecies

sage/combinat/species/empty_species.py

@@ -0,0 +1,155 @@
+# sage_setup: distribution = sagemath-combinat
+"""
+Empty species
+"""
+# ****************************************************************************
+#       Copyright (C) 2008 Florent Hivert <Florent.Hivert@univ-rouen,fr>,
+#
+#  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.structure.unique_representation import UniqueRepresentation
+
+
+class EmptySpecies(GenericCombinatorialSpecies, UniqueRepresentation):
+    """
+    Return the empty species. This species has no structure at all.
+    It is the zero of the semi-ring of species.
+
+    EXAMPLES::
+
+        sage: X = species.EmptySpecies(); X
+        Empty species
+        sage: X.structures([]).list()
+        []
+        sage: X.structures([1]).list()
+        []
+        sage: X.structures([1,2]).list()
+        []
+        sage: X.generating_series()[0:4]
+        [0, 0, 0, 0]
+        sage: X.isotype_generating_series()[0:4]
+        [0, 0, 0, 0]
+        sage: X.cycle_index_series()[0:4]                                               # needs sage.modules
+        [0, 0, 0, 0]
+
+    The empty species is the zero of the semi-ring of species.
+    The following tests that it is neutral with respect to addition::
+
+        sage: Empt  = species.EmptySpecies()
+        sage: S = species.CharacteristicSpecies(2)
+        sage: X = S + Empt
+        sage: X == S    # TODO: Not Implemented
+        True
+        sage: (X.generating_series()[0:4] ==
+        ....:  S.generating_series()[0:4])
+        True
+        sage: (X.isotype_generating_series()[0:4] ==
+        ....:  S.isotype_generating_series()[0:4])
+        True
+        sage: (X.cycle_index_series()[0:4] ==                                           # needs sage.modules
+        ....:  S.cycle_index_series()[0:4])
+        True
+
+    The following tests that it is the zero element with respect to
+    multiplication::
+
+        sage: Y = Empt*S
+        sage: Y == Empt   # TODO: Not Implemented
+        True
+        sage: Y.generating_series()[0:4]
+        [0, 0, 0, 0]
+        sage: Y.isotype_generating_series()[0:4]
+        [0, 0, 0, 0]
+        sage: Y.cycle_index_series()[0:4]                                               # needs sage.modules
+        [0, 0, 0, 0]
+
+    TESTS::
+
+        sage: Empt  = species.EmptySpecies()
+        sage: Empt2 = species.EmptySpecies()
+        sage: Empt is Empt2
+        True
+    """
+
+    def __init__(self, min=None, max=None, weight=None):
+        """
+        Initializer for the empty species.
+
+        EXAMPLES::
+
+            sage: F = species.EmptySpecies()
+            sage: F._check()
+            True
+            sage: F == loads(dumps(F))
+            True
+        """
+        # There is no structure at all, so we set min and max accordingly.
+        GenericCombinatorialSpecies.__init__(self, weight=weight)
+        self._name = "Empty species"
+
+    def _gs(self, series_ring, base_ring):
+        """
+        Return the generating series for ``self``.
+
+        EXAMPLES::
+
+            sage: F = species.EmptySpecies()
+            sage: F.generating_series()[0:5] # indirect doctest
+            [0, 0, 0, 0, 0]
+            sage: F.generating_series().count(3)
+            0
+            sage: F.generating_series().count(4)
+            0
+        """
+        return series_ring.zero()
+
+    _itgs = _gs
+    _cis = _gs
+
+    def _structures(self, structure_class, labels):
+        """
+        Thanks to the counting optimisation, this is never called... Otherwise
+        this should return an empty iterator.
+
+        EXAMPLES::
+
+            sage: F = species.EmptySpecies()
+            sage: F.structures([]).list()      # indirect doctest
+            []
+            sage: F.structures([1,2,3]).list() # indirect doctest
+            []
+        """
+        assert False, "This should never be called"
+
+    _default_structure_class = 0
+    _isotypes = _structures
+
+    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.EmptySpecies()
+            sage: Qz = QQ['z']
+            sage: R.<node0> = Qz[]
+            sage: var_mapping = {'z':Qz.gen(), 'node0':R.gen()}
+            sage: C._equation(var_mapping)
+            0
+        """
+        return 0
+
+
+EmptySpecies_class = EmptySpecies

sage/combinat/species/functorial_composition_species.py

@@ -0,0 +1,148 @@
+# sage_setup: distribution = sagemath-combinat
+"""
+Functorial 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:
+#
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+from .species import GenericCombinatorialSpecies
+from .structure import GenericSpeciesStructure
+
+
+class FunctorialCompositionStructure(GenericSpeciesStructure):
+    pass
+
+
+class FunctorialCompositionSpecies(GenericCombinatorialSpecies):
+    def __init__(self, F, G, min=None, max=None, weight=None):
+        """
+        Return the functorial composition of two species.
+
+        EXAMPLES::
+
+            sage: E = species.SetSpecies()
+            sage: E2 = species.SetSpecies(size=2)
+            sage: WP = species.SubsetSpecies()
+            sage: P2 = E2*E
+            sage: G = WP.functorial_composition(P2)
+            sage: G.isotype_generating_series()[0:5]                                    # needs sage.modules
+            [1, 1, 2, 4, 11]
+
+            sage: G = species.SimpleGraphSpecies()
+            sage: c = G.generating_series()[0:2]
+            sage: type(G)
+            <class 'sage.combinat.species.functorial_composition_species.FunctorialCompositionSpecies'>
+            sage: G == loads(dumps(G))
+            True
+            sage: G._check()  # False due to isomorphism types not being implemented    # needs sage.modules
+            False
+        """
+        self._F = F
+        self._G = G
+        self._state_info = [F, G]
+        self._name = f"Functorial composition of ({F}) and ({G})"
+        GenericCombinatorialSpecies.__init__(self, min=None, max=None, weight=None)
+
+    _default_structure_class = FunctorialCompositionStructure
+
+    def _structures(self, structure_class, s):
+        """
+        EXAMPLES::
+
+            sage: G = species.SimpleGraphSpecies()
+            sage: G.structures([1,2,3]).list()
+            [{},
+             {{1, 2}*{3}},
+             {{1, 3}*{2}},
+             {{2, 3}*{1}},
+             {{1, 2}*{3}, {1, 3}*{2}},
+             {{1, 2}*{3}, {2, 3}*{1}},
+             {{1, 3}*{2}, {2, 3}*{1}},
+             {{1, 2}*{3}, {1, 3}*{2}, {2, 3}*{1}}]
+        """
+        gs = self._G.structures(s).list()
+        yield from self._F.structures(gs)
+
+    def _isotypes(self, structure_class, s):
+        """
+        There is no known algorithm for efficiently generating the
+        isomorphism types of the functorial composition of two species.
+
+        EXAMPLES::
+
+            sage: G = species.SimpleGraphSpecies()
+            sage: G.isotypes([1,2,3]).list()                                            # needs sage.modules
+            Traceback (most recent call last):
+            ...
+            NotImplementedError
+        """
+        raise NotImplementedError
+
+    def _gs(self, series_ring, base_ring):
+        """
+        EXAMPLES::
+
+            sage: G = species.SimpleGraphSpecies()
+            sage: G.generating_series()[0:5]
+            [1, 1, 1, 4/3, 8/3]
+        """
+        return self._F.generating_series(base_ring).functorial_composition(self._G.generating_series(base_ring))
+
+    def _itgs(self, series_ring, base_ring):
+        """
+        EXAMPLES::
+
+            sage: G = species.SimpleGraphSpecies()
+            sage: G.isotype_generating_series()[0:5]                                    # needs sage.modules
+            [1, 1, 2, 4, 11]
+        """
+        return self.cycle_index_series(base_ring).isotype_generating_series()
+
+    def _cis(self, series_ring, base_ring):
+        """
+        EXAMPLES::
+
+            sage: G = species.SimpleGraphSpecies()
+            sage: G.cycle_index_series()[0:5]                                           # needs sage.modules
+            [p[],
+             p[1],
+             p[1, 1] + p[2],
+             4/3*p[1, 1, 1] + 2*p[2, 1] + 2/3*p[3],
+             8/3*p[1, 1, 1, 1] + 4*p[2, 1, 1] + 2*p[2, 2] + 4/3*p[3, 1] + p[4]]
+        """
+        return self._F.cycle_index_series(base_ring).functorial_composition(self._G.cycle_index_series(base_ring))
+
+    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: G = species.SimpleGraphSpecies()
+            sage: G.weight_ring()
+            Rational Field
+        """
+        from sage.structure.element import get_coercion_model
+        cm = get_coercion_model()
+
+        f_weights = self._F.weight_ring()
+        g_weights = self._G.weight_ring()
+
+        return cm.explain(f_weights, g_weights, verbosity=0)
+
+
+# Backward compatibility
+FunctorialCompositionSpecies_class = FunctorialCompositionSpecies