Quick Start Guide

This guide will get you started with the BiSC algorithm package quickly.

Basic Concepts

Permutations

The core data structure is the Permutation class:

from bisc_package import Permutation

# Create permutations
perm1 = Permutation([1, 2, 3])
perm2 = Permutation([3, 1, 2])

print(f"Permutation 1: {perm1}")
print(f"Permutation 2: {perm2}")

Mesh Patterns

Mesh patterns are permutations with additional shading constraints:

from bisc_package import MeshPattern

# Create a mesh pattern
pattern = MeshPattern([1, 2], {(0, 0), (1, 1)})
print(f"Mesh pattern: {pattern}")

The BiSC Algorithm

Basic Usage

The main function is bisc_algorithm:

from bisc_package import bisc_algorithm, Permutation

# Define a set of permutations (stack-sortable permutations up to length 4)
permutations = [
    Permutation([1]),
    Permutation([1, 2]),
    Permutation([2, 1]),
    Permutation([1, 2, 3]),
    Permutation([1, 3, 2]),
    Permutation([2, 1, 3]),
    Permutation([2, 3, 1]),
    Permutation([3, 2, 1]),
    # Note: [3, 1, 2] is NOT stack-sortable
]

# Find forbidden patterns of length 3
forbidden = bisc_algorithm(permutations, max_pattern_length=3)
print(f"Forbidden patterns: {forbidden}")

Expected output: The algorithm should find that [2, 3, 1] (which corresponds to the pattern 231) is forbidden for stack-sortable permutations.

Step-by-Step Breakdown

The BiSC algorithm has two main phases:

  1. MINE Phase: Extract all occurring patterns

from bisc_package.core.bisc_algorithm import mine_patterns

# Extract patterns of length 3
allowed_patterns = mine_patterns(permutations, 3)
print(f"Allowed patterns: {allowed_patterns}")

  1. GEN Phase: Generate forbidden patterns

from bisc_package.core.bisc_algorithm import generate_forbidden

# Generate forbidden patterns from allowed ones
forbidden_patterns = generate_forbidden(allowed_patterns, 3)
print(f"Forbidden patterns: {forbidden_patterns}")

Working with Known Classes

Stack-Sortable Permutations

from bisc_package.examples.known_classes.stack_sortable import generate_stack_sortable
from bisc_package import bisc_algorithm

# Generate all stack-sortable permutations up to length 4
stack_sortable = generate_stack_sortable(4)

# Find the forbidden pattern
forbidden = bisc_algorithm(stack_sortable, max_pattern_length=3)
print(f"Stack-sortable forbidden pattern: {forbidden}")
# Should output: [Permutation([2, 3, 1])]

Smooth Permutations

from bisc_package.examples.known_classes.smooth_permutations import generate_smooth
from bisc_package import bisc_algorithm

# Generate smooth permutations up to length 4
smooth = generate_smooth(4)

# Find forbidden patterns of length 4
forbidden = bisc_algorithm(smooth, max_pattern_length=4)
print(f"Smooth permutations forbidden patterns: {forbidden}")

Command Line Interface

The package provides convenient command-line tools:

Examples Runner

bisc-examples

This runs several built-in examples demonstrating the algorithm on known permutation classes.

Interactive Demo

bisc-demo

This provides an interactive demonstration where you can input your own permutations and see the algorithm in action.

Next Steps

  • Check out the Examples for more detailed use cases

  • Explore the API Reference for complete API documentation

  • Read about the theoretical background in the research paper