BiSC Algorithm Documentation
============================

.. image:: https://badge.fury.io/py/bisc-algorithm.svg
   :target: https://badge.fury.io/py/bisc-algorithm
   :alt: PyPI version

.. image:: https://img.shields.io/badge/python-3.7+-blue.svg
   :target: https://www.python.org/downloads/
   :alt: Python 3.7+

.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT
   :alt: License: MIT

Welcome to the BiSC Algorithm documentation! This package implements the BiSC (Bidirectional Systematic Counting) algorithm for discovering generalized permutation patterns.

The BiSC algorithm, introduced by Henning Ulfarsson, is a powerful tool for automated conjecture generation in combinatorics, specifically for finding forbidden patterns that characterize classes of permutations.

Quick Start
-----------

Installation
~~~~~~~~~~~~

Install the package from PyPI:

.. code-block:: bash

   pip install bisc-algorithm

Basic Usage
~~~~~~~~~~~

.. code-block:: python

   from bisc_package import Permutation, bisc_algorithm

   # Create a set of permutations
   permutations = [
       Permutation([1, 2, 3]),
       Permutation([1, 3, 2]),
       Permutation([2, 1, 3])
   ]

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

Command Line Tools
~~~~~~~~~~~~~~~~~~

The package includes command-line tools for exploration:

.. code-block:: bash

   # Run examples
   bisc-examples

   # Interactive demo
   bisc-demo

Algorithm Overview
------------------

The BiSC algorithm consists of two main phases:

1. **MINE Phase**: Records all mesh patterns that appear in the input permutations
2. **GEN Phase**: Infers forbidden patterns from the allowed patterns using systematic generation

This approach enables automated discovery of characterizing forbidden patterns for various permutation classes.

Contents
--------

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   installation
   quickstart
   examples
   api

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   bisc_package

.. toctree::
   :maxdepth: 1
   :caption: Development

   contributing
   changelog

Research Paper
--------------

This implementation is based on the research paper:

**"BiSC: An algorithm for discovering generalized permutation patterns"**
by Henning Ulfarsson

Available at: https://arxiv.org/abs/2411.17778

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`