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(); o = var('o')
sage: bar = species.EmptySetSpecies()
sage: BB = CombinatorialSpecies()
sage: BB.define(ball + ball*BB + ball*bar*BB)
sage: BB.isotypes([o]*3).list()
[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: sage.combinat.combinat.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

change_labels(labels)#

Return a relabelled structure.

INPUT:

labels, a 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}]

is_isomorphic(x)#

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

labels()#

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

parent()#

Returns 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

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

Bases: sage.combinat.species.structure.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

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

Bases: sage.combinat.species.structure.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

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

Bases: sage.combinat.species.structure.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

sage.combinat.species.structure.SpeciesStructure#: alias of sage.combinat.species.structure.GenericSpeciesStructure

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

Bases: sage.combinat.species.structure.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

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

canonical_label()#

EXAMPLES:

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

change_labels(labels)#

Return a relabelled structure.

INPUT:

labels, a 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'

transport(perm)#

EXAMPLES:

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

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

Bases: sage.combinat.combinat.CombinatorialClass

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

cardinality()#

Returns the number of structures in this set.

EXAMPLES:

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

labels()#

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

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

Bases: sage.combinat.species.structure.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