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: ball = species.SingletonSpecies()
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)]

>>> from sage.all import *
>>> ball = species.SingletonSpecies()
>>> 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)]

ball = species.SingletonSpecies()
bar = species.EmptySetSpecies()
BB = CombinatorialSpecies()
BB.define(ball + ball*BB + ball*bar*BB)
o = var('o')                                                                  # needs sage.symbolic
BB.isotypes([o]*3).list()                                                     # needs sage.symbolic

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)[source]

Bases: CombinatorialObject

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

EXAMPLES:

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

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

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

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: 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}]

>>> 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}]

P = species.SubsetSpecies()
S = P.structures(["a", "b", "c"])
[s.change_labels([1,2,3]) for s in S]
is_isomorphic(x)[source]

EXAMPLES:

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

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

S = species.SetSpecies()
a = S.structures([1,2,3]).random_element(); a
b = S.structures(['a','b','c']).random_element(); b
a.is_isomorphic(b)
labels()[source]

Return the labels used for this structure.

Note

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

EXAMPLES:

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

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

P = species.SubsetSpecies()
s = P.structures(["a", "b", "c"]).random_element()
s.labels()
parent()[source]

Return the species that this structure is associated with.

EXAMPLES:

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

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

L = species.LinearOrderSpecies()
a,b = L.structures([1,2])
a.parent()
class sage.combinat.species.structure.IsotypesWrapper(species, labels, structure_class)[source]

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: F = species.SetSpecies()
sage: S = F.isotypes([1,2,3])
sage: S == loads(dumps(S))
True

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

F = species.SetSpecies()
S = F.isotypes([1,2,3])
S == loads(dumps(S))
class sage.combinat.species.structure.SimpleIsotypesWrapper(species, labels, structure_class)[source]

Bases: SpeciesWrapper

Warning

This is deprecated and currently not used for anything.

EXAMPLES:

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

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

F = species.SetSpecies()
S = F.structures([1,2,3])
S == loads(dumps(S))
class sage.combinat.species.structure.SimpleStructuresWrapper(species, labels, structure_class)[source]

Bases: SpeciesWrapper

Warning

This is deprecated and currently not used for anything.

EXAMPLES:

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

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

F = species.SetSpecies()
S = F.structures([1,2,3])
S == loads(dumps(S))
sage.combinat.species.structure.SpeciesStructure[source]

alias of GenericSpeciesStructure

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

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: 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

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

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

EXAMPLES:

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

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

E = species.SetSpecies(); B = E+E
s = B.structures([1,2,3]).random_element()
s.parent()
s == loads(dumps(s))
canonical_label()[source]

EXAMPLES:

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}}

>>> 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}}

P = species.PartitionSpecies()
s = (P+P).structures([1,2,3])[1]; s                                   # needs sage.libs.flint
s.canonical_label()                                                   # needs sage.libs.flint
change_labels(labels)[source]

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: X = species.SingletonSpecies()
sage: X2 = X+X
sage: s = X2.structures([1]).random_element(); s
1
sage: s.change_labels(['a'])
'a'

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

X = species.SingletonSpecies()
X2 = X+X
s = X2.structures([1]).random_element(); s
s.change_labels(['a'])
transport(perm)[source]

EXAMPLES:

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}}

>>> 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}}

P = species.PartitionSpecies()
s = (P+P).structures([1,2,3])[1]; s                                   # needs sage.libs.flint
s.transport(PermutationGroupElement((2,3)))                           # needs sage.groups sage.libs.flint
class sage.combinat.species.structure.SpeciesWrapper(species, labels, iterator, generating_series, name, structure_class)[source]

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: 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

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

from sage.combinat.species.structure import SpeciesWrapper
F = species.SetSpecies()
S = SpeciesWrapper(F, [1,2,3], "_structures", "generating_series", 'Structures', None)
S
S.list()
S.cardinality()
cardinality()[source]

Return the number of structures in this set.

EXAMPLES:

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

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

F = species.SetSpecies()
F.structures([1,2,3]).cardinality()
labels()[source]

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: F = species.SetSpecies()
sage: F.structures([1,2,3]).labels()
[1, 2, 3]

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

F = species.SetSpecies()
F.structures([1,2,3]).labels()
class sage.combinat.species.structure.StructuresWrapper(species, labels, structure_class)[source]

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: F = species.SetSpecies()
sage: S = F.structures([1,2,3])
sage: S == loads(dumps(S))
True

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

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