Species structures - Combinatorics

Skip to content
Back to top
View this page
Edit this page

# Species structures

We will illustrate the use of the structure classes using the “balls and bars” model for integer compositions. An integer composition of 6 such as [2, 1, 3] can be represented in this model as ‘oooooo’ where the 6 o’s correspond to the balls and the 2 ‘s correspond to the bars. If BB is our species for this model, the it satisfies the following recursive definition:

BB = o + o*BB + o*|*BB

Here we define this species using the default structures:

Sage

    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)
    sage: o = var('o')                                                                  # needs sage.symbolic
    sage: BB.isotypes([o]*3).list()                                                     # needs sage.symbolic
    [o*(o*o), o*((o*{})*o), (o*{})*(o*o), (o*{})*((o*{})*o)]

Python

    >>> from sage.all import *
    >>> ball = species.SingletonSpecies()
    doctest:warning...
    DeprecationWarning: combinat.species is superseded by LazyCombinatorialSpecies
    See https://github.com/sagemath/sage/issues/38544 for details.
    >>> bar = species.EmptySetSpecies()
    >>> BB = CombinatorialSpecies()
    >>> BB.define(ball + ball*BB + ball*bar*BB)
    >>> o = var('o')                                                                  # needs sage.symbolic
    >>> BB.isotypes([o]*Integer(3)).list()                                                     # needs sage.symbolic
    [o*(o*o), o*((o*{})*o), (o*{})*(o*o), (o*{})*((o*{})*o)]

If we ignore the parentheses, we can read off that the integer compositions are [3], [2, 1], [1, 2], and [1, 1, 1].

class sage.combinat.species.structure.GenericSpeciesStructure(parent, labels, list)

  Bases: `CombinatorialObject`

  This is a base class from which the classes for the structures inherit.

  EXAMPLES:

  Sage

      sage: from sage.combinat.species.structure import GenericSpeciesStructure
      sage: a = GenericSpeciesStructure(None, [2,3,4], [1,2,3])
      sage: a
      [2, 3, 4]
      sage: a.parent() is None
      True
      sage: a == loads(dumps(a))
      True

  Python

      >>> from sage.all import *
      >>> from sage.combinat.species.structure import GenericSpeciesStructure
      >>> a = GenericSpeciesStructure(None, [Integer(2),Integer(3),Integer(4)], [Integer(1),Integer(2),Integer(3)])
      >>> a
      [2, 3, 4]
      >>> a.parent() is None
      True
      >>> a == loads(dumps(a))
      True

  change_labels(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

        sage: P = species.SubsetSpecies()
        sage: S = P.structures(["a", "b", "c"])
        sage: [s.change_labels([1,2,3]) for s in S]
        [{}, {1}, {2}, {3}, {1, 2}, {1, 3}, {2, 3}, {1, 2, 3}]

    Python

        >>> from sage.all import *
        >>> P = species.SubsetSpecies()
        >>> S = P.structures(["a", "b", "c"])
        >>> [s.change_labels([Integer(1),Integer(2),Integer(3)]) for s in S]
        [{}, {1}, {2}, {3}, {1, 2}, {1, 3}, {2, 3}, {1, 2, 3}]

  is_isomorphic(x)

    EXAMPLES:

    Sage

        sage: S = species.SetSpecies()
        sage: a = S.structures([1,2,3]).random_element(); a
        {1, 2, 3}
        sage: b = S.structures(['a','b','c']).random_element(); b
        {'a', 'b', 'c'}
        sage: a.is_isomorphic(b)
        True

    Python

        >>> from sage.all import *
        >>> S = species.SetSpecies()
        >>> a = S.structures([Integer(1),Integer(2),Integer(3)]).random_element(); a
        {1, 2, 3}
        >>> b = S.structures(['a','b','c']).random_element(); b
        {'a', 'b', 'c'}
        >>> a.is_isomorphic(b)
        True

  labels()

    Return the labels used for this structure.

    Note

    This includes labels which may not “appear” in this particular structure.

    EXAMPLES:

    Sage

        sage: P = species.SubsetSpecies()
        sage: s = P.structures(["a", "b", "c"]).random_element()
        sage: s.labels()
        ['a', 'b', 'c']

    Python

        >>> from sage.all import *
        >>> P = species.SubsetSpecies()
        >>> s = P.structures(["a", "b", "c"]).random_element()
        >>> s.labels()
        ['a', 'b', 'c']

  parent()

    Return the species that this structure is associated with.

    EXAMPLES:

    Sage

        sage: L = species.LinearOrderSpecies()
        sage: a,b = L.structures([1,2])
        sage: a.parent()
        Linear order species

    Python

        >>> from sage.all import *
        >>> L = species.LinearOrderSpecies()
        >>> a,b = L.structures([Integer(1),Integer(2)])
        >>> a.parent()
        Linear order species

class sage.combinat.species.structure.IsotypesWrapper(species, labels, structure_class)

  Bases: `SpeciesWrapper`

  A base class for the set of isotypes of a species with given set of labels. An object of this type is returned when you call the `isotypes()` method of a species.

  EXAMPLES:

  Sage

      sage: F = species.SetSpecies()
      sage: S = F.isotypes([1,2,3])
      sage: S == loads(dumps(S))
      True

  Python

      >>> from sage.all import *
      >>> F = species.SetSpecies()
      >>> S = F.isotypes([Integer(1),Integer(2),Integer(3)])
      >>> S == loads(dumps(S))
      True

class sage.combinat.species.structure.SimpleIsotypesWrapper(species, labels, structure_class)

  Bases: `SpeciesWrapper`

  Warning

  This is deprecated and currently not used for anything.

  EXAMPLES:

  Sage

      sage: F = species.SetSpecies()
      sage: S = F.structures([1,2,3])
      sage: S == loads(dumps(S))
      True

  Python

      >>> from sage.all import *
      >>> F = species.SetSpecies()
      >>> S = F.structures([Integer(1),Integer(2),Integer(3)])
      >>> S == loads(dumps(S))
      True

class sage.combinat.species.structure.SimpleStructuresWrapper(species, labels, structure_class)

  Bases: `SpeciesWrapper`

  Warning

  This is deprecated and currently not used for anything.

  EXAMPLES:

  Sage

      sage: F = species.SetSpecies()
      sage: S = F.structures([1,2,3])
      sage: S == loads(dumps(S))
      True

  Python

      >>> from sage.all import *
      >>> F = species.SetSpecies()
      >>> S = F.structures([Integer(1),Integer(2),Integer(3)])
      >>> S == loads(dumps(S))
      True

sage.combinat.species.structure.SpeciesStructure

  alias of `GenericSpeciesStructure`

class sage.combinat.species.structure.SpeciesStructureWrapper(parent, s, **options)

  Bases: `GenericSpeciesStructure`

  This is a class for the structures of species such as the sum species that do not provide “additional” structure. For example, if you have the sum \(C\) of species \(A\) and \(B\), then a structure of \(C\) will either be either something from \(A\) or \(B\). Instead of just returning one of these directly, a “wrapper” is put around them so that they have their parent is \(C\) rather than \(A\) or \(B\):

  Sage

      sage: X = species.SingletonSpecies()
      sage: X2 = X+X
      sage: s = X2.structures([1]).random_element(); s
      1
      sage: s.parent()
      Sum of (Singleton species) and (Singleton species)
      sage: from sage.combinat.species.structure import SpeciesStructureWrapper
      sage: issubclass(type(s), SpeciesStructureWrapper)
      True

  Python

      >>> from sage.all import *
      >>> X = species.SingletonSpecies()
      >>> X2 = X+X
      >>> s = X2.structures([Integer(1)]).random_element(); s
      1
      >>> s.parent()
      Sum of (Singleton species) and (Singleton species)
      >>> from sage.combinat.species.structure import SpeciesStructureWrapper
      >>> issubclass(type(s), SpeciesStructureWrapper)
      True

  EXAMPLES:

  Sage

      sage: E = species.SetSpecies(); B = E+E
      sage: s = B.structures([1,2,3]).random_element()
      sage: s.parent()
      Sum of (Set species) and (Set species)
      sage: s == loads(dumps(s))
      True

  [Python]

      >>> from sage.all import *
      >>> E = species.SetSpecies(); B = E+E
      >>> s = B.structures([Integer(1),Integer(2),Integer(3)]).random_element()
      >>> s.parent()
      Sum of (Set species) and (Set species)
      >>> s == loads(dumps(s))
      True

  canonical_label()

    EXAMPLES:

    Sage

        sage: P = species.PartitionSpecies()
        sage: s = (P+P).structures([1,2,3])[1]; s                                   # needs sage.libs.flint
        {{1, 3}, {2}}
        sage: s.canonical_label()                                                   # needs sage.libs.flint
        {{1, 2}, {3}}

    Python

        >>> from sage.all import *
        >>> P = species.PartitionSpecies()
        >>> s = (P+P).structures([Integer(1),Integer(2),Integer(3)])[Integer(1)]; s                                   # needs sage.libs.flint
        {{1, 3}, {2}}
        >>> s.canonical_label()                                                   # needs sage.libs.flint
        {{1, 2}, {3}}

  change_labels(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

        sage: X = species.SingletonSpecies()
        sage: X2 = X+X
        sage: s = X2.structures([1]).random_element(); s
        1
        sage: s.change_labels(['a'])
        'a'

    Python

        >>> from sage.all import *
        >>> X = species.SingletonSpecies()
        >>> X2 = X+X
        >>> s = X2.structures([Integer(1)]).random_element(); s
        1
        >>> s.change_labels(['a'])
        'a'

  transport(perm)

    EXAMPLES:

    Sage

        sage: P = species.PartitionSpecies()
        sage: s = (P+P).structures([1,2,3])[1]; s                                   # needs sage.libs.flint
        {{1, 3}, {2}}
        sage: s.transport(PermutationGroupElement((2,3)))                           # needs sage.groups sage.libs.flint
        {{1, 2}, {3}}

    Python

        >>> from sage.all import *
        >>> P = species.PartitionSpecies()
        >>> s = (P+P).structures([Integer(1),Integer(2),Integer(3)])[Integer(1)]; s                                   # needs sage.libs.flint
        {{1, 3}, {2}}
        >>> s.transport(PermutationGroupElement((Integer(2),Integer(3))))                           # needs sage.groups sage.libs.flint
        {{1, 2}, {3}}

class sage.combinat.species.structure.SpeciesWrapper(species, labels, iterator, generating_series, name, structure_class)

  Bases: `Parent`

  This is a abstract base class for the set of structures of a species as well as the set of isotypes of the species.

  Note

  One typically does not use `SpeciesWrapper` directly, but instead instantiates one of its subclasses: `StructuresWrapper` or `IsotypesWrapper`.

  EXAMPLES:

  Sage

      sage: from sage.combinat.species.structure import SpeciesWrapper
      sage: F = species.SetSpecies()
      sage: S = SpeciesWrapper(F, [1,2,3], "_structures", "generating_series", 'Structures', None)
      sage: S
      Structures for Set species with labels [1, 2, 3]
      sage: S.list()
      [{1, 2, 3}]
      sage: S.cardinality()
      1

  Python

      >>> from sage.all import *
      >>> from sage.combinat.species.structure import SpeciesWrapper
      >>> F = species.SetSpecies()
      >>> S = SpeciesWrapper(F, [Integer(1),Integer(2),Integer(3)], "_structures", "generating_series", 'Structures', None)
      >>> S
      Structures for Set species with labels [1, 2, 3]
      >>> S.list()
      [{1, 2, 3}]
      >>> S.cardinality()
      1

  cardinality()

    Return the number of structures in this set.

    EXAMPLES:

    Sage

        sage: F = species.SetSpecies()
        sage: F.structures([1,2,3]).cardinality()
        1

    Python

        >>> from sage.all import *
        >>> F = species.SetSpecies()
        >>> F.structures([Integer(1),Integer(2),Integer(3)]).cardinality()
        1

  labels()

    Return the labels used on these structures. If \(X\) is the species, then `labels()` returns the preimage of these structures under the functor \(X\).

    EXAMPLES:

    Sage

        sage: F = species.SetSpecies()
        sage: F.structures([1,2,3]).labels()
        [1, 2, 3]

    Python

        >>> from sage.all import *
        >>> F = species.SetSpecies()
        >>> F.structures([Integer(1),Integer(2),Integer(3)]).labels()
        [1, 2, 3]

class sage.combinat.species.structure.StructuresWrapper(species, labels, structure_class)

  Bases: `SpeciesWrapper`

  A base class for the set of structures of a species with given set of labels. An object of this type is returned when you call the `structures()` method of a species.

  EXAMPLES:

  Sage

      sage: F = species.SetSpecies()
      sage: S = F.structures([1,2,3])
      sage: S == loads(dumps(S))
      True

  Python

      >>> from sage.all import *
      >>> F = species.SetSpecies()
      >>> S = F.structures([Integer(1),Integer(2),Integer(3)])
      >>> S == loads(dumps(S))
      True