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()
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()
>>> 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)]

Sage Live

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)

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

Sage Live

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)

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

Sage Live

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

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

Sage Live

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

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

Sage Live

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

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

Sage Live

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

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

Sage Live

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

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

Sage Live

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

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 Live

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

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

Sage Live

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

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

Sage Live

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

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

Sage Live

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)

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'

Sage Live

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

Sage Live

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)

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

Sage Live

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

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

Sage Live

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

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]

Sage Live

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

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

Sage Live

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

Make live