Utilities

shuffl.utils

This module provides different utility functions that facilitate working with and analyzing shuffle models.

The implemented functions include:

• adjacent_pairs: Returns number of adjacent pairs in a permutation
• sequences: Returns all rising and descending sequences in a permutation

adjacent_pairs(permutation, original)

Returns all adjacent pairs in a given permutation.

Adjacent pairs are pairs of cards that were together in the original deck and which are still together in the permutation.

Example:

from shuffl.utils import adjacent_pairs
from shuffl import Deck

# Deck in original order
deck = Deck(["A", "B", "C", "D", "E"])

# Permutation of deck
permutation = Deck(["B", "C", "A", "D", "E"])

# Print adjacent pairs
# [("B", "C"), ("D", "E")]
print(adjacent(permutation, deck))

PARAMETER	DESCRIPTION
permutation	A permutation of the original set TYPE: Deck
original	Original set TYPE: Deck

RETURNS	DESCRIPTION
list[tuple]	List of all adjacent pairs

Source code in shuffl/utils/_adjacent_pairs.py

def adjacent_pairs(
    permutation: Annotated[Deck, Doc("A permutation of the original set")],
    original: Annotated[Deck, Doc("Original set")],
) -> Annotated[list[tuple], Doc("List of all adjacent pairs")]:
    """Returns all adjacent pairs in a given permutation.

    Adjacent pairs are pairs of cards that were together in the original
    deck and which are still together in the permutation.

    **Example:**

    ```python
    from shuffl.utils import adjacent_pairs
    from shuffl import Deck

    # Deck in original order
    deck = Deck(["A", "B", "C", "D", "E"])

    # Permutation of deck
    permutation = Deck(["B", "C", "A", "D", "E"])

    # Print adjacent pairs
    # [("B", "C"), ("D", "E")]
    print(adjacent(permutation, deck))
    ```
    """
    permutation = _convert(permutation, original)
    return [
        (original[i], original[j]) for (i, j) in pairwise(permutation) if i + 1 == j
    ]