passagemath-categories 10.6.32__cp314-cp314t-musllinux_1_2_aarch64.whl

sage/groups/perm_gps/partn_ref/automorphism_group_canonical_label.pyx

@@ -0,0 +1,906 @@
+# sage_setup: distribution = sagemath-categories
+# sage.doctest: needs sage.groups
+r"""
+Automorphism groups and canonical labels
+
+This module implements a general algorithm for computing automorphism groups and
+canonical labels of objects. The class of objects in question must be some kind
+of structure for which an automorphism is a permutation in $S_n$ for some $n$,
+which we call here the order of the object. It should be noted that the word
+"canonical" in the term canonical label is used loosely. Given an object $X$,
+the canonical label $C(X)$ is just an object for which $C(X) = C(Y)$ for any
+$Y$ such that $X \cong Y$.
+
+To understand the algorithm better, a few definitions will help. First one
+should note that throughout this module, $S_n$ is defined as the set of
+permutations of the set $[n] := \{0, 1, ..., n-1\}$. One speaks of
+ordered partitions $\Pi = (C_1, ..., C_k)$ of $[n]$. The $C_i$ are disjoint
+subsets of $[n]$ whose union is equal to $[n]$, and we call them cells. A
+partition $\Pi_1$ is said to be finer than another partition $\Pi_2$ if every
+cell of $\Pi_1$ is a subset of some cell of $\Pi_2$ (in this situation we also
+say that $\Pi_2$ is coarser than $\Pi_1$). A partition stack
+$\nu = (\Pi_0, ..., \Pi_k)$ is a sequence of partitions such that $\Pi_i$ is
+finer than $\Pi_{i-1}$ for each $i$ such that $1 \leq i \leq k$. Sometimes these
+are called nested partitions. The depth of $\nu$ is defined to be $k$ and the
+degree of $\nu$ is defined to be $n$. Partition stacks are implemented as
+\code{PartitionStack} (see automorphism_group_canonical_label.pxd for more
+information). Finally, we say that a permutation respects the partition $\Pi$ if
+its orbits form a partition which is finer than $\Pi$.
+
+In order to take advantage of the algorithms in this module for a specific kind
+of object, one must implement (in Cython) three functions which will be specific
+to the kind of objects in question. Pointers to these functions are passed to
+the main function of the module, which is \code{get_aut_gp_and_can_lab}. For
+specific examples of implementations of these functions, see any of the files in
+\code{sage.groups.perm_gps.partn_ref} beginning with "refinement." They are:
+
+A. \code{refine_and_return_invariant}:
+
+    Signature:
+
+    \code{int refine_and_return_invariant(PartitionStack *PS, void *S, int *cells_to_refine_by, int ctrb_len)}
+
+    This function should split up cells in the partition at the top of the
+    partition stack in such a way that any automorphism that respects the
+    partition also respects the resulting partition. The array
+    cells_to_refine_by is a list of the beginning positions of some cells which
+    have been changed since the last refinement, of length ctrb_len. It is not
+    necessary to use this in an implementation of this function, but it will
+    affect performance. One should consult \code{refinement_graphs} for more
+    details and ideas for particular implementations.
+
+    Output:
+
+    An integer $I$ invariant under the orbits of $S_n$.  That is, if
+    $\gamma \in S_n$, then
+    $$ I(G, PS, cells_to_refine_by) = I( \gamma(G), \gamma(PS), \gamma(cells_to_refine_by) ) .$$
+
+
+B. \code{compare_structures}:
+
+    Signature:
+
+    \code{int compare_structures(int *gamma_1, int *gamma_2, void *S1, void *S2, int degree)}
+
+    This function must implement a total ordering on the set of objects of fixed
+    order. Return:
+        -1 if \code{gamma_1^{-1}(S1) < gamma_2^{-1}(S2)},
+        0 if \code{gamma_1^{-1}(S1) == gamma_2^{-1}(S2)},
+        1 if \code{gamma_1^{-1}(S1) > gamma_2^{-1}(S2)}.
+
+    The value ``degree`` indicates the degree of the permutations ``gamma1`` and
+    ``gamma_2``.
+
+    Important note:
+
+    The permutations are thought of as being input in inverse form, and this can
+    lead to subtle bugs. One is encouraged to consult existing implementations
+    to make sure the right thing is being done: this is so that you can avoid
+    *actually* needing to compute the inverse.
+
+C. \code{all_children_are_equivalent}:
+
+    Signature:
+
+    \code{bint all_children_are_equivalent(PartitionStack *PS, void *S)}
+
+    This function must return False unless it is the case that each discrete
+    partition finer than the top of the partition stack is equivalent to the
+    others under some automorphism of S. The converse need not hold: if this is
+    indeed the case, it still may return False. This function is originally used
+    as a consequence of Lemma 2.25 in [1].
+
+EXAMPLES::
+
+    sage: import sage.groups.perm_gps.partn_ref.automorphism_group_canonical_label
+
+REFERENCE:
+
+- [1] McKay, Brendan D. Practical Graph Isomorphism. Congressus Numerantium,
+  Vol. 30 (1981), pp. 45-87.
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2006 - 2011 Robert L. Miller <rlmillster@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from libc.string cimport memcmp, memcpy
+from cysignals.memory cimport sig_malloc, sig_realloc, sig_free
+
+from sage.groups.perm_gps.partn_ref.data_structures cimport *
+from sage.data_structures.bitset_base cimport *
+
+cdef inline int agcl_cmp(int a, int b) noexcept:
+    if a < b:
+        return -1
+    elif a == b:
+        return 0
+    else:
+        return 1
+
+# Functions
+
+cdef bint all_children_are_equivalent_trivial(PartitionStack *PS, void *S) noexcept:
+    return 0
+
+cdef int refine_and_return_invariant_trivial(PartitionStack *PS, void *S, int *cells_to_refine_by, int ctrb_len) noexcept:
+    return 0
+
+cdef int compare_structures_trivial(int *gamma_1, int *gamma_2, void *S1, void *S2, int degree) noexcept:
+    return 0
+
+
+def test_get_aut_gp_and_can_lab_trivially(int n=6,
+    list partition=[[0,1,2],[3,4],[5]], canonical_label=True, base=False):
+    """
+    TESTS::
+
+        sage: tttt = sage.groups.perm_gps.partn_ref.automorphism_group_canonical_label.test_get_aut_gp_and_can_lab_trivially
+        sage: tttt()
+        12
+        sage: tttt(canonical_label=False, base=False)
+        12
+        sage: tttt(canonical_label=False, base=True)
+        12
+        sage: tttt(canonical_label=True, base=True)
+        12
+        sage: tttt(n=0, partition=[])
+        1
+        sage: tttt(n=0, partition=[], canonical_label=False, base=False)
+        1
+        sage: tttt(n=0, partition=[], canonical_label=False, base=True)
+        1
+        sage: tttt(n=0, partition=[], canonical_label=True, base=True)
+        1
+    """
+    cdef aut_gp_and_can_lab *output
+    cdef Integer I = Integer(0)
+    cdef PartitionStack *part
+    part = PS_from_list(partition)
+    if part is NULL:
+        raise MemoryError
+    cdef object empty_list = []
+    output = get_aut_gp_and_can_lab(<void *> empty_list, part, n, &all_children_are_equivalent_trivial, &refine_and_return_invariant_trivial, &compare_structures_trivial, canonical_label, NULL, NULL, NULL)
+    SC_order(output.group, 0, I.value)
+    print(I)
+    PS_dealloc(part)
+    deallocate_agcl_output(output)
+
+
+def test_intersect_parabolic_with_alternating(int n=9, list partition=[[0,1,2],[3,4],[5,6,7,8]]):
+    """
+    A test for nontrivial input group in computing automorphism groups.
+
+    TESTS::
+
+        sage: from sage.groups.perm_gps.partn_ref.automorphism_group_canonical_label import test_intersect_parabolic_with_alternating as tipwa
+        sage: tipwa()
+        144
+        sage: tipwa(5, [[0],[1],[2],[3,4]])
+        1
+        sage: tipwa(5, [[0],[1],[2,3,4]])
+        3
+        sage: tipwa(5, [[0,1],[2,3,4]])
+        6
+        sage: tipwa(7, [[0,1,2,3,4,5,6]])
+        2520
+        sage: factorial(7)/2
+        2520
+        sage: tipwa(9, [[0,1,2,3],[4,5,6,7,8]])
+        1440
+    """
+    cdef aut_gp_and_can_lab *output
+    cdef Integer I = Integer(0)
+    cdef PartitionStack *part
+    part = PS_from_list(partition)
+    if part is NULL:
+        raise MemoryError
+    cdef StabilizerChain *group = SC_alternating_group(part.degree)
+    if group is NULL:
+        PS_dealloc(part)
+        raise MemoryError
+    cdef object empty_list = []
+    output = get_aut_gp_and_can_lab(<void *> empty_list, part, n, &all_children_are_equivalent_trivial, &refine_and_return_invariant_trivial, &compare_structures_trivial, 0, group, NULL, NULL)
+    SC_order(output.group, 0, I.value)
+    print(I)
+    PS_dealloc(part)
+    SC_dealloc(group)
+    deallocate_agcl_output(output)
+
+
+cdef int compare_perms(int *gamma_1, int *gamma_2, void *S1, void *S2, int degree) noexcept:
+    cdef list MS1 = <list> S1
+    cdef list MS2 = <list> S2
+    cdef int i, j
+    for i in range(degree):
+        j = agcl_cmp(MS1[gamma_1[i]], MS2[gamma_2[i]])
+        if j != 0:
+            return j
+    return 0
+
+
+def coset_rep(list perm=[0,1,2,3,4,5], list gens=[[1,2,3,4,5,0]]):
+    """
+    Given a group G generated by the given generators, defines a map from the
+    Symmetric group to G so that any two elements from the same right coset go
+    to the same element. Tests nontrivial input group when computing canonical
+    labels.
+
+    TESTS::
+
+        sage: from sage.groups.perm_gps.partn_ref.automorphism_group_canonical_label import coset_rep
+        sage: coset_rep()
+        [5, 0, 1, 2, 3, 4]
+        sage: gens = [[1,2,3,0]]
+        sage: reps = []
+        sage: for p in SymmetricGroup(4):
+        ....:   p = [p(i)-1 for i in range(1,5)]
+        ....:   r = coset_rep(p, gens)
+        ....:   if r not in reps:
+        ....:       reps.append(r)
+        sage: len(reps)
+        6
+        sage: gens = [[1,0,2,3],[0,1,3,2]]
+        sage: reps = []
+        sage: for p in SymmetricGroup(4):
+        ....:   p = [p(i)-1 for i in range(1,5)]
+        ....:   r = coset_rep(p, gens)
+        ....:   if r not in reps:
+        ....:       reps.append(r)
+        sage: len(reps)
+        6
+        sage: gens = [[1,2,0,3]]
+        sage: reps = []
+        sage: for p in SymmetricGroup(4):
+        ....:   p = [p(i)-1 for i in range(1,5)]
+        ....:   r = coset_rep(p, gens)
+        ....:   if r not in reps:
+        ....:       reps.append(r)
+        sage: len(reps)
+        8
+    """
+    cdef int i, n = len(perm)
+    assert all(len(g) == n for g in gens)
+    cdef aut_gp_and_can_lab *output
+    cdef Integer I = Integer(0)
+    cdef PartitionStack *part
+    part = PS_new(n, 1)
+    cdef int *c_perm = <int *> sig_malloc(n * sizeof(int))
+    cdef StabilizerChain *group = SC_new(n, 1)
+    if part is NULL or c_perm is NULL or group is NULL:
+        sig_free(c_perm)
+        PS_dealloc(part)
+        SC_dealloc(group)
+        raise MemoryError
+    for g in gens:
+        for i from 0 <= i < n:
+            c_perm[i] = g[i]
+        SC_insert(group, 0, c_perm, 1)
+    output = get_aut_gp_and_can_lab(<void *> perm, part, n, &all_children_are_equivalent_trivial, &refine_and_return_invariant_trivial, &compare_perms, 1, group, NULL, NULL)
+    SC_order(output.group, 0, I.value)
+    assert I == 1
+    r_inv = list(range(n))
+    for i in range(n):
+        r_inv[output.relabeling[i]] = i
+    label = [perm[r_inv[i]] for i in range(n)]
+    PS_dealloc(part)
+    SC_dealloc(group)
+    deallocate_agcl_output(output)
+    sig_free(c_perm)
+    return label
+
+
+cdef aut_gp_and_can_lab *allocate_agcl_output(int n) noexcept:
+    r"""
+    Allocate an instance of the aut_gp_and_can_lab struct of degree n. This can
+    be input to the get_aut_gp_and_can_lab function, and the output will be
+    stored to it.
+    """
+    cdef aut_gp_and_can_lab *output = <aut_gp_and_can_lab *> sig_malloc(sizeof(aut_gp_and_can_lab))
+    if output is NULL:
+        return NULL
+    output.group = SC_new(n)
+    output.relabeling = <int *> sig_malloc(n*sizeof(int))
+    output.generators = <int *> sig_malloc(2*n*n*sizeof(int))
+    output.size_of_generator_array = 2*n*n
+    if output.group is NULL or \
+       output.relabeling is NULL or \
+       output.generators is NULL:
+        deallocate_agcl_output(output)
+        return NULL
+    return output
+
+cdef void deallocate_agcl_output(aut_gp_and_can_lab *output) noexcept:
+    r"""
+    Deallocate an aut_gp_and_can_lab struct.
+    """
+    if output is not NULL:
+        SC_dealloc(output.group)
+        sig_free(output.relabeling)
+        sig_free(output.generators)
+    sig_free(output)
+
+cdef agcl_work_space *allocate_agcl_work_space(int n) noexcept:
+    r"""
+    Allocate work space for the get_aut_gp_and_can_lab function. It can be
+    input to the function in which case it must be deallocated after the
+    function is called.
+    """
+    cdef int *int_array
+
+    cdef agcl_work_space *work_space
+    work_space = <agcl_work_space *> sig_malloc(sizeof(agcl_work_space))
+    if work_space is NULL:
+        return NULL
+
+    work_space.degree = n
+    int_array = <int *> sig_malloc((n*n + # for perm_stack
+                                     n   + # for label_indicators
+                                     7*n   # for int_array
+                                    )*sizeof(int))
+    work_space.group1 = SC_new(n)
+    work_space.group2 = SC_new(n)
+    work_space.label_ps = PS_new(n,0)
+    work_space.bitset_array = <bitset_t *> sig_malloc((n + 2*len_of_fp_and_mcr + 1)*sizeof(bitset_t))
+    work_space.orbits_of_subgroup = OP_new(n)
+    work_space.orbits_of_permutation = OP_new(n)
+    work_space.first_ps = PS_new(n,0)
+
+    if int_array                        is NULL or \
+       work_space.group1                is NULL or \
+       work_space.group2                is NULL or \
+       work_space.label_ps              is NULL or \
+       work_space.bitset_array          is NULL or \
+       work_space.orbits_of_subgroup    is NULL or \
+       work_space.orbits_of_permutation is NULL or \
+       work_space.first_ps              is NULL:
+        sig_free(work_space)
+        return NULL
+
+    work_space.perm_stack       = int_array
+    work_space.label_indicators = int_array + n*n
+    work_space.int_array        = int_array + n*n + n
+
+    cdef int i
+    for i from 0 <= i < n + 2*len_of_fp_and_mcr + 1:
+        work_space.bitset_array[i].bits = NULL
+    try:
+        for i from 0 <= i < n + 2*len_of_fp_and_mcr + 1:
+            bitset_init(work_space.bitset_array[i], n)
+    except MemoryError:
+        deallocate_agcl_work_space(work_space)
+        return NULL
+    return work_space
+
+cdef void deallocate_agcl_work_space(agcl_work_space *work_space) noexcept:
+    r"""
+    Deallocate work space for the get_aut_gp_and_can_lab function.
+    """
+    if work_space is NULL:
+        return
+    cdef int i, n = work_space.degree
+    if work_space.bitset_array is not NULL:
+        for i from 0 <= i < n + 2*len_of_fp_and_mcr + 1:
+            bitset_free(work_space.bitset_array[i])
+    sig_free(work_space.perm_stack)
+    SC_dealloc(work_space.group1)
+    SC_dealloc(work_space.group2)
+    PS_dealloc(work_space.label_ps)
+    sig_free(work_space.bitset_array)
+    OP_dealloc(work_space.orbits_of_subgroup)
+    OP_dealloc(work_space.orbits_of_permutation)
+    PS_dealloc(work_space.first_ps)
+    sig_free(work_space)
+
+cdef aut_gp_and_can_lab *get_aut_gp_and_can_lab(void *S,
+    PartitionStack *partition, int n,
+    bint (*all_children_are_equivalent)(PartitionStack *PS, void *S) noexcept,
+    int (*refine_and_return_invariant)(PartitionStack *PS, void *S,
+                                       int *cells_to_refine_by, int ctrb_len) noexcept,
+    int (*compare_structures)(int *gamma_1, int *gamma_2, void *S1, void *S2,
+                              int degree) noexcept,
+    bint canonical_label, StabilizerChain *input_group,
+    agcl_work_space *work_space_prealloc, aut_gp_and_can_lab *output_prealloc) except NULL:
+    """
+    Traverse the search space for subgroup/canonical label calculation.
+
+    INPUT:
+
+    - ``S`` -- pointer to the structure
+    - ``partition`` -- PartitionStack representing a partition of the points
+    - ``len_partition`` -- length of the partition
+    - ``n`` -- the number of points (points are assumed to be 0,1,...,n-1)
+    - ``canonical_label`` -- whether to search for canonical label; if True, return
+        the permutation taking S to its canonical label
+    - ``all_children_are_equivalent`` -- pointer to a function
+        INPUT:
+        - ``PS`` -- pointer to a partition stack
+        - ``S`` -- pointer to the structure
+        OUTPUT:
+        bint; returns ``True`` if it can be determined that all refinements below
+        the current one will result in an equivalent discrete partition
+    - ``refine_and_return_invariant`` -- pointer to a function
+        INPUT:
+        - ``PS`` -- pointer to a partition stack
+        - ``S`` -- pointer to the structure
+        - ``alpha`` -- an array consisting of numbers, which indicate the starting
+          positions of the cells to refine against (will likely be modified)
+        OUTPUT:
+        integer; returns an invariant under application of arbitrary permutations
+    - ``compare_structures`` -- pointer to a function
+        INPUT:
+        - ``gamma_1``, ``gamma_2`` -- (list) permutations of the points of S1 and S2
+        - ``S1``, ``S2`` -- pointers to the structures
+        - ``degree`` -- degree of gamma_1 and 2
+        OUTPUT:
+        integer; 0 if gamma_1(S1) = gamma_2(S2), otherwise -1 or 1 (see docs for cmp),
+        such that the set of all structures is well-ordered
+
+    .. NOTE::
+
+        The partition ``partition1`` *must* satisfy the property that in each
+        cell, the smallest element occurs first!
+
+    OUTPUT: a pointer to a ``aut_gp_and_can_lab`` struct
+    """
+    cdef PartitionStack *current_ps
+    cdef PartitionStack *first_ps
+    cdef PartitionStack *label_ps
+    cdef int first_meets_current = -1
+    cdef int label_meets_current
+    cdef int current_kids_are_same = 1
+    cdef int first_kids_are_same
+
+    cdef int *current_indicators
+    cdef int *first_indicators
+    cdef int *label_indicators
+    cdef int first_and_current_indicator_same
+    cdef int label_and_current_indicator_same = -1
+    cdef int compared_current_and_label_indicators
+
+    cdef OrbitPartition *orbits_of_subgroup
+    cdef OrbitPartition *orbits_of_permutation
+    cdef OrbitPartition *orbits_of_supergroup
+    cdef int subgroup_primary_orbit_size = 0
+    cdef int minimal_in_primary_orbit
+
+    cdef bitset_t *fixed_points_of_generators # i.e. fp
+    cdef bitset_t *minimal_cell_reps_of_generators # i.e. mcr
+    cdef int index_in_fp_and_mcr = -1
+
+    cdef bitset_t *vertices_to_split
+    cdef bitset_t *vertices_have_been_reduced
+    cdef int *permutation
+    cdef int *label_perm
+    cdef int *id_perm
+    cdef int *cells_to_refine_by
+    cdef int *vertices_determining_current_stack
+    cdef int *perm_stack
+    cdef StabilizerChain *group = NULL
+    cdef StabilizerChain *old_group
+    cdef StabilizerChain *tmp_gp
+
+    cdef int i, j, k, ell, b
+    cdef bint discrete, automorphism, update_label
+    cdef bint backtrack, new_vertex, mem_err = 0
+
+    cdef aut_gp_and_can_lab *output
+    cdef agcl_work_space *work_space
+
+    if output_prealloc is not NULL:
+        output = output_prealloc
+        output.group.base_size = 0
+    else:
+        output = allocate_agcl_output(n)
+        if output is NULL:
+            raise MemoryError
+
+    output.num_gens = 0
+    if n == 0:
+        return output
+
+    if work_space_prealloc is not NULL:
+        work_space = work_space_prealloc
+    else:
+        work_space = allocate_agcl_work_space(n)
+        if work_space is NULL:
+            if output_prealloc is NULL:
+                deallocate_agcl_output(output)
+            raise MemoryError
+
+    # Allocate:
+    if input_group is not NULL:
+        perm_stack                     = work_space.perm_stack
+        group                          = work_space.group1
+        old_group                      = work_space.group2
+        orbits_of_supergroup           = input_group.OP_scratch
+        SC_copy_nomalloc(group, input_group, n)
+        SC_identify(perm_stack, n)
+    if canonical_label:
+        label_indicators               = work_space.label_indicators
+        label_ps                       = work_space.label_ps
+    first_ps                           = work_space.first_ps
+    orbits_of_subgroup                 = work_space.orbits_of_subgroup
+    orbits_of_permutation              = work_space.orbits_of_permutation
+
+    current_indicators                 = work_space.int_array
+    first_indicators                   = work_space.int_array + n
+    permutation                        = work_space.int_array + 2 * n
+    id_perm                            = work_space.int_array + 3 * n
+    cells_to_refine_by                 = work_space.int_array + 4 * n
+    vertices_determining_current_stack = work_space.int_array + 5 * n
+    label_perm                         = work_space.int_array + 6 * n
+
+    fixed_points_of_generators         = work_space.bitset_array
+    minimal_cell_reps_of_generators    = work_space.bitset_array + len_of_fp_and_mcr
+    vertices_to_split                  = work_space.bitset_array + 2*len_of_fp_and_mcr
+    vertices_have_been_reduced         = work_space.bitset_array + 2*len_of_fp_and_mcr + n
+
+    if work_space_prealloc is not NULL:
+        OP_clear(orbits_of_subgroup)
+
+    bitset_zero(vertices_have_been_reduced[0])
+    current_ps = partition
+    current_ps.depth = 0
+
+    # default values of "infinity"
+    for i from 0 <= i < n:
+        first_indicators[i] = -1
+    if canonical_label:
+        for i from 0 <= i < n:
+            label_indicators[i] = -1
+
+    # set up the identity permutation
+    for i from 0 <= i < n:
+        id_perm[i] = i
+
+    # Our first refinement needs to check every cell of the partition,
+    # so cells_to_refine_by needs to be a list of pointers to each cell.
+    j = 1
+    cells_to_refine_by[0] = 0
+    for i from 0 < i < n:
+        if current_ps.levels[i-1] == 0:
+            cells_to_refine_by[j] = i
+            j += 1
+    # Ignore the invariant this time, since we are
+    # creating the root of the search tree.
+    if input_group is NULL:
+        refine_and_return_invariant(current_ps, S, cells_to_refine_by, j)
+    else:
+        refine_also_by_orbits(current_ps, S, refine_and_return_invariant,
+            cells_to_refine_by, j, group, perm_stack)
+    PS_move_all_mins_to_front(current_ps)
+
+    # Refine down to a discrete partition
+    while not PS_is_discrete(current_ps):
+        i = current_ps.depth
+        if not all_children_are_equivalent(current_ps, S):
+            current_kids_are_same = i + 1
+        vertices_determining_current_stack[i] = PS_first_smallest(current_ps, vertices_to_split[i])
+        bitset_unset(vertices_have_been_reduced[0], i)
+        if input_group is not NULL:
+            OP_clear(orbits_of_supergroup)
+            for j from i <= j < group.base_size:
+                for ell from 0 <= ell < group.num_gens[j]:
+                    OP_merge_list_perm(orbits_of_supergroup, group.generators[j] + n*ell)
+            b = orbits_of_supergroup.mcr[OP_find(orbits_of_supergroup, perm_stack[i*n + vertices_determining_current_stack[i]])]
+            tmp_gp = group
+            group = old_group
+            old_group = tmp_gp
+            if SC_insert_base_point_nomalloc(group, old_group, i, b):
+                mem_err = 1
+                break
+            current_indicators[i] = split_point_and_refine_by_orbits(current_ps,
+                vertices_determining_current_stack[i], S, refine_and_return_invariant,
+                cells_to_refine_by, group, perm_stack)
+        else:
+            current_indicators[i] = split_point_and_refine(current_ps, vertices_determining_current_stack[i], S, refine_and_return_invariant, cells_to_refine_by)
+        PS_move_all_mins_to_front(current_ps)
+        first_indicators[i] = current_indicators[i]
+        if canonical_label:
+            label_indicators[i] = current_indicators[i]
+        SC_add_base_point(output.group, vertices_determining_current_stack[i])
+
+    if not mem_err:
+        first_meets_current = current_ps.depth
+        first_kids_are_same = current_ps.depth
+        first_and_current_indicator_same = current_ps.depth
+        PS_copy_from_to(current_ps, first_ps)
+        if canonical_label:
+            label_meets_current = current_ps.depth
+            label_and_current_indicator_same = current_ps.depth
+            compared_current_and_label_indicators = 0
+            PS_copy_from_to(current_ps, label_ps)
+            if input_group is not NULL:
+                if compute_relabeling(group, old_group, label_ps.entries, label_perm):
+                    mem_err = 1
+        current_ps.depth -= 1
+
+    # Main loop:
+    while current_ps.depth != -1:
+
+        if mem_err:
+            if output_prealloc is NULL:
+                deallocate_agcl_output(output)
+            if work_space_prealloc is NULL:
+                deallocate_agcl_work_space(work_space_prealloc)
+            raise MemoryError
+
+        # If necessary, update label_meets_current
+        if canonical_label and label_meets_current > current_ps.depth:
+            label_meets_current = current_ps.depth
+
+        # I. Search for a new vertex to split, and update subgroup information
+        new_vertex = 0
+        if current_ps.depth > first_meets_current:
+            # If we are not at a node of the first stack, reduce size of
+            # vertices_to_split by using the symmetries we already know.
+            if not bitset_check(vertices_have_been_reduced[0], current_ps.depth):
+                for i from 0 <= i <= index_in_fp_and_mcr:
+                    j = 0
+                    while j < current_ps.depth and bitset_check(fixed_points_of_generators[i], vertices_determining_current_stack[j]):
+                        j += 1
+                    # If each vertex split so far is fixed by generator i,
+                    # then remove elements of vertices_to_split which are
+                    # not minimal in their orbits under generator i.
+                    if j == current_ps.depth:
+                        for k from 0 <= k < n:
+                            if bitset_check(vertices_to_split[current_ps.depth], k) and not bitset_check(minimal_cell_reps_of_generators[i], k):
+                                bitset_flip(vertices_to_split[current_ps.depth], k)
+                bitset_flip(vertices_have_been_reduced[0], current_ps.depth)
+            # Look for a new point to split.
+            i = vertices_determining_current_stack[current_ps.depth] + 1
+            i = bitset_next(vertices_to_split[current_ps.depth], i)
+            if i != -1:
+                # There is a new point.
+                vertices_determining_current_stack[current_ps.depth] = i
+                new_vertex = 1
+            else:
+                # No new point: backtrack.
+                current_ps.depth -= 1
+        else:
+            # If we are at a node of the first stack, the above reduction
+            # will not help. Also, we must update information about
+            # primary orbits here.
+            if current_ps.depth < first_meets_current:
+                # If we are done searching under this part of the first
+                # stack, then first_meets_current is one higher, and we
+                # are looking at a new primary orbit (corresponding to a
+                # larger subgroup in the stabilizer chain).
+                first_meets_current = current_ps.depth
+                minimal_in_primary_orbit = output.group.base_orbits[current_ps.depth][0]
+            while True:
+                i = vertices_determining_current_stack[current_ps.depth]
+                # This was the last point to be split here.
+                # If it has been added to the primary orbit, update size info.
+                if output.group.parents[current_ps.depth][i] != -1:
+                    subgroup_primary_orbit_size += 1
+                # Look for a new point to split.
+                i += 1
+                i = bitset_next(vertices_to_split[current_ps.depth], i)
+                if i != -1:
+                    # There is a new point.
+                    vertices_determining_current_stack[current_ps.depth] = i
+                    if orbits_of_subgroup.mcr[OP_find(orbits_of_subgroup, i)] == i:
+                        new_vertex = 1
+                        break
+                else:
+                    # No new point: backtrack.
+                    # Note that now, we are backtracking up the first stack.
+                    vertices_determining_current_stack[current_ps.depth] = -1
+                    # If every choice of point to split gave something in the
+                    # (same!) primary orbit, then all children of the first
+                    # stack at this point are equivalent.
+                    j = 0
+                    for i from 0 <= i < n:
+                        if bitset_check(vertices_to_split[current_ps.depth], i):
+                            j += 1
+                    if j == subgroup_primary_orbit_size and first_kids_are_same == current_ps.depth+1:
+                        first_kids_are_same = current_ps.depth
+                    subgroup_primary_orbit_size = 0
+                    current_ps.depth -= 1
+                    break
+        if not new_vertex:
+            continue
+
+        if current_kids_are_same > current_ps.depth + 1:
+            current_kids_are_same = current_ps.depth + 1
+        if first_and_current_indicator_same > current_ps.depth:
+            first_and_current_indicator_same = current_ps.depth
+        if canonical_label and label_and_current_indicator_same >= current_ps.depth:
+            label_and_current_indicator_same = current_ps.depth
+            compared_current_and_label_indicators = 0
+
+        # II. Refine down to a discrete partition, or until
+        # we leave the part of the tree we are interested in
+        discrete = 0
+        backtrack = 0
+        while True:
+            i = current_ps.depth
+            if input_group is not NULL:
+                current_indicators[i] = split_point_and_refine_by_orbits(current_ps,
+                    vertices_determining_current_stack[i], S,
+                    refine_and_return_invariant, cells_to_refine_by,
+                    group, perm_stack)
+            else:
+                current_indicators[i] = split_point_and_refine(current_ps,
+                    vertices_determining_current_stack[i], S,
+                    refine_and_return_invariant, cells_to_refine_by)
+            PS_move_all_mins_to_front(current_ps)
+            if first_and_current_indicator_same == i and \
+              current_indicators[i] == first_indicators[i] and \
+              stacks_are_equivalent(first_ps, current_ps):
+                first_and_current_indicator_same += 1
+            if canonical_label:
+                if compared_current_and_label_indicators == 0:
+                    if label_indicators[i] == -1:
+                        compared_current_and_label_indicators = -1
+                    else:
+                        compared_current_and_label_indicators = agcl_cmp(current_indicators[i], label_indicators[i])
+                if label_and_current_indicator_same == i and compared_current_and_label_indicators == 0:
+                    label_and_current_indicator_same += 1
+                if compared_current_and_label_indicators > 0:
+                    label_indicators[i] = current_indicators[i]
+            if first_and_current_indicator_same < current_ps.depth and (not canonical_label or compared_current_and_label_indicators < 0):
+                backtrack = 1
+                break
+            if PS_is_discrete(current_ps):
+                discrete = 1
+                break
+            vertices_determining_current_stack[current_ps.depth] = PS_first_smallest(current_ps, vertices_to_split[current_ps.depth])
+            if input_group is not NULL:
+                i = current_ps.depth
+                k = vertices_determining_current_stack[i]
+                if group.parents[i][perm_stack[n*i + k]] == -1:
+                    # if we get here then canonical_label must be true
+                    # and we have to make a change of base
+                    OP_clear(orbits_of_supergroup)
+                    for j from i <= j < group.base_size:
+                        for ell from 0 <= ell < group.num_gens[j]:
+                            OP_merge_list_perm(orbits_of_supergroup, group.generators[j] + n*ell)
+                    b = orbits_of_supergroup.mcr[OP_find(orbits_of_supergroup, perm_stack[i*n + k])]
+                    tmp_gp = group
+                    group = old_group
+                    old_group = tmp_gp
+                    if SC_insert_base_point_nomalloc(group, old_group, i, b):
+                        mem_err = 1
+                        break
+            bitset_unset(vertices_have_been_reduced[0], current_ps.depth)
+            if not all_children_are_equivalent(current_ps, S):
+                current_kids_are_same = current_ps.depth + 1
+
+        # III. Check for automorphisms and labels
+        automorphism = 0
+        if discrete:
+            if current_ps.depth == first_and_current_indicator_same:
+                PS_get_perm_from(current_ps, first_ps, permutation)
+                if compare_structures(permutation, id_perm, S, S, n) == 0:
+                    if input_group is NULL or SC_contains(group, 0, permutation, 0):
+                        # TODO: might be slight optimization for containment using perm_stack
+                        automorphism = 1
+        if not automorphism:
+            if (not canonical_label) or (compared_current_and_label_indicators < 0):
+                backtrack = 1
+            else:
+                # if we get here, discrete must be true
+                update_label = 0
+                if (compared_current_and_label_indicators > 0) or (current_ps.depth < label_ps.depth):
+                    if input_group is not NULL:
+                        if compute_relabeling(group, old_group, current_ps.entries, permutation):
+                            mem_err = 1
+                            break
+                    update_label = 1
+                else:
+                    if input_group is NULL:
+                        i = compare_structures(current_ps.entries, label_ps.entries, S, S, n)
+                    else:
+                        if compute_relabeling(group, old_group, current_ps.entries, permutation):
+                            mem_err = 1
+                            break
+                        i = compare_structures(permutation, label_perm, S, S, n)
+                    if i > 0:
+                        update_label = 1
+                    elif i < 0:
+                        backtrack = 1
+                    else:
+                        if input_group is NULL:
+                            PS_get_perm_from(current_ps, label_ps, permutation)
+                            automorphism = 1
+                        elif memcmp(permutation, label_perm, n*sizeof(int)):
+                            SC_invert_perm(group.perm_scratch, permutation, n)
+                            SC_mult_perms(permutation, group.perm_scratch, label_perm, n)
+                            automorphism = 1
+                        else:
+                            backtrack = 1
+                if update_label:
+                    PS_copy_from_to(current_ps, label_ps)
+                    if input_group is not NULL:
+                        memcpy(label_perm, permutation, n*sizeof(int))
+                    compared_current_and_label_indicators = 0
+                    label_meets_current = current_ps.depth
+                    label_and_current_indicator_same = current_ps.depth
+                    label_indicators[current_ps.depth] = -1
+                    backtrack = 1
+        if automorphism:
+            if index_in_fp_and_mcr < len_of_fp_and_mcr - 1:
+                index_in_fp_and_mcr += 1
+            bitset_zero(fixed_points_of_generators[index_in_fp_and_mcr])
+            bitset_zero(minimal_cell_reps_of_generators[index_in_fp_and_mcr])
+            OP_clear(orbits_of_permutation)
+            for i from 0 <= i < n:
+                OP_join(orbits_of_permutation, i, permutation[i])
+            bitset_zero(minimal_cell_reps_of_generators[index_in_fp_and_mcr])
+            for i from 0 <= i < n:
+                if permutation[i] == i:
+                    bitset_set(fixed_points_of_generators[index_in_fp_and_mcr], i)
+                    bitset_set(minimal_cell_reps_of_generators[index_in_fp_and_mcr], i)
+                else:
+                    bitset_unset(fixed_points_of_generators[index_in_fp_and_mcr], i)
+                    if orbits_of_permutation.parent[i] == i:
+                        bitset_set(minimal_cell_reps_of_generators[index_in_fp_and_mcr], orbits_of_permutation.mcr[i])
+            if OP_merge_list_perm(orbits_of_subgroup, permutation): # if permutation made orbits coarser
+                # add permutation as a generator of the automorphism group
+                if n*output.num_gens == output.size_of_generator_array:
+                    # must double its size
+                    output.size_of_generator_array *= 2
+                    output.generators = <int *> sig_realloc( output.generators, output.size_of_generator_array * sizeof(int) )
+                    if output.generators is NULL:
+                        mem_err = True
+                        continue # main loop
+                j = n*output.num_gens
+                for i from 0 <= i < n:
+                    output.generators[j + i] = permutation[i]
+                output.num_gens += 1
+                if SC_update_tree(output.group, first_meets_current, permutation, 1):
+                    mem_err = 1
+                    continue # main loop
+                if orbits_of_subgroup.mcr[OP_find(orbits_of_subgroup, minimal_in_primary_orbit)] != minimal_in_primary_orbit:
+                    current_ps.depth = first_meets_current
+                    continue # main loop
+            if canonical_label:
+                current_ps.depth = label_meets_current
+            else:
+                current_ps.depth = first_meets_current
+            if bitset_check(vertices_have_been_reduced[0], current_ps.depth):
+                bitset_and(vertices_to_split[current_ps.depth], vertices_to_split[current_ps.depth], minimal_cell_reps_of_generators[index_in_fp_and_mcr])
+            continue # main loop
+        if backtrack:
+            i = current_ps.depth
+            current_ps.depth = min(max(first_kids_are_same - 1, label_and_current_indicator_same), current_kids_are_same - 1)
+            if i == current_kids_are_same:
+                continue # main loop
+            if index_in_fp_and_mcr < len_of_fp_and_mcr - 1:
+                index_in_fp_and_mcr += 1
+            bitset_zero(fixed_points_of_generators[index_in_fp_and_mcr])
+            bitset_zero(minimal_cell_reps_of_generators[index_in_fp_and_mcr])
+            j = current_ps.depth
+            current_ps.depth = i # just for mcr and fixed functions...
+            for i from 0 <= i < n:
+                if PS_is_mcr(current_ps, i):
+                    bitset_set(minimal_cell_reps_of_generators[index_in_fp_and_mcr], i)
+                    if PS_is_fixed(current_ps, i):
+                        bitset_set(fixed_points_of_generators[index_in_fp_and_mcr], i)
+            current_ps.depth = j
+            if bitset_check(vertices_have_been_reduced[0], current_ps.depth):
+                bitset_and(vertices_to_split[current_ps.depth], vertices_to_split[current_ps.depth], minimal_cell_reps_of_generators[index_in_fp_and_mcr])
+
+    # End of main loop.
+
+    if canonical_label:
+        if input_group is NULL:
+            for i from 0 <= i < n:
+                output.relabeling[label_ps.entries[i]] = i
+        else:
+            for i from 0 <= i < n:
+                output.relabeling[label_perm[i]] = i
+
+    if work_space_prealloc is NULL:
+        deallocate_agcl_work_space(work_space)
+
+    return output