Tools for enumeration modulo the action of a permutation group - Combinatorics

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

# Tools for enumeration modulo the action of a permutation group

sage.combinat.enumeration_mod_permgroup.all_children(v, max_part)

  Return all the children of an integer vector (`ClonableIntArray`) `v` in the tree of enumeration by lexicographic order. The children of an integer vector `v` whose entries have the sum \(n\) are all integer vectors of sum \(n+1\) which follow `v` in the lexicographic order.

  That means this function adds \(1\) on the last nonzero entries and the following ones. For an integer vector \(v\) such that

  \[v = [ \dots, a , 0, 0 ] \text{ with } a \neq 0,\]

  then, the list of children is

  \[[ [ \dots, a+1 , 0, 0 ] , [ \dots, a , 1, 0 ], [ \dots, a , 0, 1 ] ].\]

  EXAMPLES:

  Sage

      sage: from sage.combinat.enumeration_mod_permgroup import all_children
      sage: from sage.structure.list_clone_demo import IncreasingIntArrays
      sage: v = IncreasingIntArrays()([1,2,3,4])
      sage: all_children(v, -1)
      [[1, 2, 3, 5]]

  Python

      >>> from sage.all import *
      >>> from sage.combinat.enumeration_mod_permgroup import all_children
      >>> from sage.structure.list_clone_demo import IncreasingIntArrays
      >>> v = IncreasingIntArrays()([Integer(1),Integer(2),Integer(3),Integer(4)])
      >>> all_children(v, -Integer(1))
      [[1, 2, 3, 5]]

sage.combinat.enumeration_mod_permgroup.canonical_children(sgs, v, max_part)

  Return the canonical children of the integer vector `v`. This function computes all children of the integer vector `v` via the function `all_children()` and returns from this list only these which are canonicals identified via the function `is_canonical()`.

  EXAMPLES:

  Sage

      sage: from sage.combinat.enumeration_mod_permgroup import canonical_children
      sage: G = PermutationGroup([[(1,2,3,4)]])
      sage: sgs = G.strong_generating_system()
      sage: from sage.structure.list_clone_demo import IncreasingIntArrays
      sage: IA = IncreasingIntArrays()
      sage: canonical_children(sgs, IA([1,2,3,5]), -1)
      []

  Python

      >>> from sage.all import *
      >>> from sage.combinat.enumeration_mod_permgroup import canonical_children
      >>> G = PermutationGroup([[(Integer(1),Integer(2),Integer(3),Integer(4))]])
      >>> sgs = G.strong_generating_system()
      >>> from sage.structure.list_clone_demo import IncreasingIntArrays
      >>> IA = IncreasingIntArrays()
      >>> canonical_children(sgs, IA([Integer(1),Integer(2),Integer(3),Integer(5)]), -Integer(1))
      []

sage.combinat.enumeration_mod_permgroup.canonical_representative_of_orbit_of(sgs, v)

  Return the maximal vector for the lexicographic order living in the orbit of \(v\) under the action of the permutation group whose strong generating system is `sgs`. The maximal vector is also called “canonical”. Hence, this method returns the canonical vector inside the orbit of \(v\). If \(v\) is already canonical, the method returns \(v\).

  Let \(G\) to be the permutation group which admits `sgs` as a strong generating system. An integer vector \(v\) is said to be canonical under the action of \(G\) if and only if:

  \[v = \max_{\text{lex order}} \{g \cdot v | g \in G \}\]

  EXAMPLES:

  Sage

      sage: from sage.combinat.enumeration_mod_permgroup import canonical_representative_of_orbit_of
      sage: G = PermutationGroup([[(1,2,3,4)]])
      sage: sgs = G.strong_generating_system()
      sage: from sage.structure.list_clone_demo import IncreasingIntArrays
      sage: IA = IncreasingIntArrays()
      sage: canonical_representative_of_orbit_of(sgs, IA([1,2,3,5]))
      [5, 1, 2, 3]

  Python

      >>> from sage.all import *
      >>> from sage.combinat.enumeration_mod_permgroup import canonical_representative_of_orbit_of
      >>> G = PermutationGroup([[(Integer(1),Integer(2),Integer(3),Integer(4))]])
      >>> sgs = G.strong_generating_system()
      >>> from sage.structure.list_clone_demo import IncreasingIntArrays
      >>> IA = IncreasingIntArrays()
      >>> canonical_representative_of_orbit_of(sgs, IA([Integer(1),Integer(2),Integer(3),Integer(5)]))
      [5, 1, 2, 3]

sage.combinat.enumeration_mod_permgroup.is_canonical(sgs, v)

  Return `True` if the integer vector \(v\) is maximal with respect to the lexicographic order in its orbit under the action of the permutation group whose strong generating system is `sgs`. Such vectors are said to be canonical.

  Let \(G\) to be the permutation group which admit `sgs` as a strong generating system. An integer vector \(v\) is said to be canonical under the action of \(G\) if and only if:

  \[v = \max_{\text{lex order}} \{g \cdot v | g \in G \}\]

  EXAMPLES:

  Sage

      sage: from sage.combinat.enumeration_mod_permgroup import is_canonical
      sage: G = PermutationGroup([[(1,2,3,4)]])
      sage: sgs = G.strong_generating_system()
      sage: from sage.structure.list_clone_demo import IncreasingIntArrays
      sage: IA = IncreasingIntArrays()
      sage: is_canonical(sgs, IA([1,2,3,6]))
      False

  Python

      >>> from sage.all import *
      >>> from sage.combinat.enumeration_mod_permgroup import is_canonical
      >>> G = PermutationGroup([[(Integer(1),Integer(2),Integer(3),Integer(4))]])
      >>> sgs = G.strong_generating_system()
      >>> from sage.structure.list_clone_demo import IncreasingIntArrays
      >>> IA = IncreasingIntArrays()
      >>> is_canonical(sgs, IA([Integer(1),Integer(2),Integer(3),Integer(6)]))
      False

sage.combinat.enumeration_mod_permgroup.lex_cmp(v1, v2)

  Lexicographic comparison of `ClonableIntArray`.

  INPUT:

  - `v1`, `v2` – two instances of `ClonableIntArray`

  OUTPUT:

  `-1,0,1`, depending on whether \(v_1\) is lexicographically smaller, equal, or greater than \(v_2\).

  EXAMPLES:

  Sage

      sage: I =  IntegerVectorsModPermutationGroup(SymmetricGroup(5),5)
      sage: I =  IntegerVectorsModPermutationGroup(SymmetricGroup(5))
      sage: J =  IntegerVectorsModPermutationGroup(SymmetricGroup(6))
      sage: v1 = I([2,3,1,2,3], check=False)
      sage: v2 = I([2,3,2,3,2], check=False)
      sage: v3 = J([2,3,1,2,3,1], check=False)
      sage: from sage.combinat.enumeration_mod_permgroup import lex_cmp
      sage: lex_cmp(v1, v1)
      0
      sage: lex_cmp(v1, v2)
      -1
      sage: lex_cmp(v2, v1)
      1
      sage: lex_cmp(v1, v3)
      -1
      sage: lex_cmp(v3, v1)
      1

  Python

      >>> from sage.all import *
      >>> I =  IntegerVectorsModPermutationGroup(SymmetricGroup(Integer(5)),Integer(5))
      >>> I =  IntegerVectorsModPermutationGroup(SymmetricGroup(Integer(5)))
      >>> J =  IntegerVectorsModPermutationGroup(SymmetricGroup(Integer(6)))
      >>> v1 = I([Integer(2),Integer(3),Integer(1),Integer(2),Integer(3)], check=False)
      >>> v2 = I([Integer(2),Integer(3),Integer(2),Integer(3),Integer(2)], check=False)
      >>> v3 = J([Integer(2),Integer(3),Integer(1),Integer(2),Integer(3),Integer(1)], check=False)
      >>> from sage.combinat.enumeration_mod_permgroup import lex_cmp
      >>> lex_cmp(v1, v1)
      0
      >>> lex_cmp(v1, v2)
      -1
      >>> lex_cmp(v2, v1)
      1
      >>> lex_cmp(v1, v3)
      -1
      >>> lex_cmp(v3, v1)
      1

sage.combinat.enumeration_mod_permgroup.lex_cmp_partial(v1, v2, step)

  Partial comparison of the two lists according the lexicographic order. It compares the `step`-th first entries.

  EXAMPLES:

  Sage

      sage: from sage.combinat.enumeration_mod_permgroup import lex_cmp_partial
      sage: from sage.structure.list_clone_demo import IncreasingIntArrays
      sage: IA = IncreasingIntArrays()
      sage: lex_cmp_partial(IA([0,1,2,3]),IA([0,1,2,4]),3)
      0
      sage: lex_cmp_partial(IA([0,1,2,3]),IA([0,1,2,4]),4)
      -1

  Python

      >>> from sage.all import *
      >>> from sage.combinat.enumeration_mod_permgroup import lex_cmp_partial
      >>> from sage.structure.list_clone_demo import IncreasingIntArrays
      >>> IA = IncreasingIntArrays()
      >>> lex_cmp_partial(IA([Integer(0),Integer(1),Integer(2),Integer(3)]),IA([Integer(0),Integer(1),Integer(2),Integer(4)]),Integer(3))
      0
      >>> lex_cmp_partial(IA([Integer(0),Integer(1),Integer(2),Integer(3)]),IA([Integer(0),Integer(1),Integer(2),Integer(4)]),Integer(4))
      -1

sage.combinat.enumeration_mod_permgroup.orbit(sgs, v)

  Return the orbit of the integer vector `v` under the action of the permutation group whose strong generating system is `sgs`.

  NOTE:

  The returned orbit is a set. In the doctests, we convert it into a sorted list.

  EXAMPLES:

  Sage

      sage: from sage.combinat.enumeration_mod_permgroup import orbit
      sage: G = PermutationGroup([[(1,2,3,4)]])
      sage: sgs = G.strong_generating_system()
      sage: from sage.structure.list_clone_demo import IncreasingIntArrays
      sage: IA = IncreasingIntArrays()
      sage: sorted(orbit(sgs, IA([1,2,3,4])))
      [[1, 2, 3, 4], [2, 3, 4, 1], [3, 4, 1, 2], [4, 1, 2, 3]]

  Python

      >>> from sage.all import *
      >>> from sage.combinat.enumeration_mod_permgroup import orbit
      >>> G = PermutationGroup([[(Integer(1),Integer(2),Integer(3),Integer(4))]])
      >>> sgs = G.strong_generating_system()
      >>> from sage.structure.list_clone_demo import IncreasingIntArrays
      >>> IA = IncreasingIntArrays()
      >>> sorted(orbit(sgs, IA([Integer(1),Integer(2),Integer(3),Integer(4)])))
      [[1, 2, 3, 4], [2, 3, 4, 1], [3, 4, 1, 2], [4, 1, 2, 3]]