Metadata-Version: 2.1
Name: group_action
Version: 0.2.17
Summary: A Python package for group action.
Home-page: https://github.com/ant1sir/group_action
Author: ant1sir
Author-email: antoine@sirianni.ai
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE

## QUESTION
When you have to design a standard cell libray, you need to choose a number of combinatorial cells.
You can simply ask a friend and start from an existing list or build your own from scratch.
But how? More specifically, how many n-input Boolean functions are there?

This latter question connects to the mathematical concept of group action that is a pivotal part of Algebra.
If you like Rubyk's cube, you should not feel too uncomfortable.

It can be reformulated in this context as follows.
What are the orbits in the action of the symmetric group $S_n$ on the set of n-input Boolean functions $X_n=B^{B^n}$?

## DESCRIPTION
The name of this package is **group_action**.

The version of this package is **0.2.17**.

It contains a library module named **library** and three applications named **orbits**, **conjugacy_classes**, and **burnside**.

**orbits** computes the orbits in the action of the symmetric group $S_n$ on the set of n-input Boolean functions $X_n=B^{B^n}$.

The result is basically a list of signatures that is presented in 2 formats and 2 levels of details.

Here, a **signature** is a non negative integer representing a Boolean function.

When the problem becomes too big you might consider using the following commands to get the number of orbits.

**conjugacy_classes** computes the conjugacy classes of the symmetric group $S_n$.

**burnside** computes the Burnside's formula for a given number of inputs $n$ and the number of orbits generated by the action of $S_n$ on $X_n$.

For instance, what 2-input Boolean function does 12 represent?
I use Big Endian format for binary words.
12 = 0101
This gives the following truth table
```
x0 x1 f(x0, x1)
0  0  0
1  0  1
0  1  0
1  1  1
```
and the following expression
f(x0, x1) = x0 & ~x1 | x0 & x1 = x0

Note: x1 does not figure in this expression.

So 12 represents a 1-input Boolean function.
It gives a standard cell called **buffer**.

To move forward, is 12 the only signature representing a buffer cell?
Actually this answer is no!
If you permut x0 and x1, you get the following truth table.
```
x0 x1 f(x0, x1)
0  0  0
1  0  0
0  1  1
1  1  1
```
It corresponds to f(x0, x1) = ~x0 & x1 | x0 & x1 = x1, another instance of the buffer cell.

This is what the group action concept is all about, and behyond :-)

## HOW DOES IT WORK?

### orbits
Each permutation of $S_n$ is applied to each n-input Boolean function f of $X_n$, computing a new n-input Boolean function g.
These computations are gathered into chunks and run in parallel on a number of cores.

Each pair $\lbrace f, g \rbrace$ forms an edge of a graph that is latter analyzed.
The orbits we are looking for are the connected parts of the obtained graph.

From this analysis, one can get the number of orbits, a list of representatives, and the detailed contents of each orbit.
Boolean functions are represented by their signatures as non negative integers.

The results are printed out to the screen or stored into a json file named **data.json**.
Binary data is considered as Big Endian throughout the code.

### conjugacy_classes
Same as **orbits** but the symmetric group $S_n$ acts on itself and action looks like this : $g.x = gxg^{-1}$.

### burnside
Here the orbits are not populated like for both the previous commands, as the level of complexity grows and becomes untractable.
**burnside** command builds the formula as a string upon two facts.
1. Conjugated permutations give the same number of fixed points.
2. The action of $S_n$ on $B^n$ allows to derive the number of fixed functions for a given permutation.
Then the formula is evaluated.
Special attention to very long integers has to be payed.

## INSTALL
Run ```pip install group_action```.

### On Ubuntu
The commands named **orbits**, **conjugacy_classes**, and **burnside** are automatically installed under $HOME/.local/bin under Ubuntu 22.04 when you install the package.

Make sure your path is updated with $HOME/.local/bin.
Check the following [link](https://askubuntu.com/questions/1144231/home-local-bin-not-in-path-for-ubuntu-19-04) for more information. 

You are ready to go :-)

## USAGE
```
orbits [-h] [--version] [--n N] [--c C] [--r] [--v] [--j]

Brut force computation of orbits of n-input 1-output Boolean functions under the action of the symmetric group Sn.

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit
  --n N       Number of inputs
  --c C       Number of cores
  --v         Output every element of each orbit
  --j         Output data.json file
```

```
usage: conjugacy_classes [-h] [--n N] [--c C] [--v] [--j]

Brut force computation of conjugacy classes of the symmetric group Sn.

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit
  --n N       Number of elements in S
  --c C       Number of cores
  --v         Output every element of each orbit
  --j         Output data.json file
```

```
usage: burnside [-h] [--n N] [--c C]

Build Burnside's formula and compute the number of orbits generated by the action of the symmetric group Sn on the set of n-input Boolean
functions B^{B^n}

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit
  --n N       Number of inputs
  --c C       Number of cores
```

## EXAMPLES
After the installation, run ```orbits --n 3 --c 12``` in order to run on 12 cores and to get the number of orbits and a representative of each orbit as an integer signature for 3-input, 1-output Boolean functions.
Activate the verbose mode running ```orbits --n 3 --c 12 --v``` in order to get the orbits populated.

## TEST
```
n=0      2 orbits
n=1      4 orbits
n=2     12 orbits
n=3     80 orbits
n=4  3 984 orbits
```

## KNOWN BUGS AND LIMITATIONS
1. The group action is concrete and set up to $G=S_n$ and $X=B^{B^n}$ in this version.
2. The packaging is managed through PyPI, not yet synchronized to GitHub.

## FEEDBACK
Any comment and/or improvement whether on optimization, packaging, documentation, or on any other appropriate topic is welcome :-)

## CONTACT
You can reach me by email: antoine AT sirianni DOT ai.
I'll do my best to provide you with support.

Check [ORConf 2024 presentation video](https://www.youtube.com/watch?v=cpYvwZsMajM) on Open Source Standard Cell Library Design to get to know me.

## DOCUMENTATION
Check [ORConf 2024 presentation slides](https://drive.google.com/file/d/1MqquCYTonRa8ladpjQhkc7wXzL7EGqIk/view) on Open Source Standard Cell Library Design.
Type ```pydoc -w group_action.library``` to generate the HTML documentation of the library module.


