docstring_example

docstring_example.py

def _strip(g, base, orbs, stabs):
    """
    Attempt to decompose a group element using a subgroup chain ``stabs``.

    This is done by treating the subgroup chain ``stabs`` as a chain of
    stabilizers with respect to the sequence ``base`` (even though the groups
    in ``stabs`` might only be subgroups of the respective stabilizers),
    and treat ``orbs`` as basic orbits.
    This process is called "sifting". A sift is unsuccessful when a certain
    orbit element is not found or when after the sift the decomposition
    doesn't end with the identity element.

    Examples
    ========

    >>> from sympy.combinatorics.named_groups import SymmetricGroup
    >>> from sympy.combinatorics.permutations import Permutation
    >>> from sympy.combinatorics.util import _strip
    >>> S = SymmetricGroup(5)
    >>> S.schreier_sims()
    >>> g = Permutation([0, 2, 3, 1, 4])
    >>> _strip(g, S.base, S.basic_orbits, S.basic_stabilizers)
    (Permutation([0, 1, 2, 3, 4]), 5)

    See Also
    ========

    schreier_sims, schreier_sims_random

    Notes
    =====

    The algorithm is described in [1],pp.89-90. The reason for returning
    both the current state of the element being decomposed and the level
    at which the sifting ends is that they provide important information for
    the randomized version of the Schreier-Sims algorithm.

    References
    ==========

    [1] Holt, D., Eick, B., O'Brien, E.
    "Handbook of computational group theory"

    """
    h = g
    base_len = len(base)
    for i in range(base_len):
        beta = h(base[i])
        if beta == base[i]:
            continue
        if beta not in orbs[i]:
            return h, i + 1
        u = (stabs[i]).orbit_rep(base[i], beta)
        h = ~u*h
    return h, base_len + 1