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:

.. code-block:: python

   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:

.. code-block:: python

   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``:

.. code-block:: python

   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

.. code-block:: python

   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}")

2. **GEN Phase**: Generate forbidden patterns

.. code-block:: python

   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
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   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
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   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
~~~~~~~~~~~~~~~

.. code-block:: bash

   bisc-examples

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

Interactive Demo
~~~~~~~~~~~~~~~~

.. code-block:: bash

   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 :doc:`examples` for more detailed use cases
* Explore the :doc:`api` for complete API documentation
* Read about the theoretical background in the research paper