| Name | balg JSON |
| Version |
0.0.6
JSON |
| download |
| home_page | None |
| Summary | A boolean algebra toolkit to evaluate expressions, truth tables, and produce logic diagrams |
| upload_time | 2024-09-08 18:19:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT License Copyright (c) 2024 MustafaAamir Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
algebra
boolean
logic
logic diagram
truth table
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Boolean Algebra Toolkit
- Truth Table to Boolean Expression and Logic Diagram Generator
- Boolean Expression Evaluator and Truth Table Generator
# Installation
```bash
pip install balg
```
# Usage
| **Token** | **Equivalent** |
|:---------:|:--------------:|
| & | AND |
| ^ | XOR |
| + | OR |
| ~ | NOT |
| [A-z] | Variable |
```python
from balg.boolean import Boolean
booleanObject = Boolean()
```
1. To generate an expression's truth table:
```python
input_expression: str = "~(A & B & C)+(A & B)+(B & C)"
tt: str = booleanObject.expr_to_tt(input_expression)
```
2. To generate an expression given the minterms and variables:
```python
variables: List[str] = ['A', 'B', 'C']
minterms: List[int] = [0, 1, 3, 7]
expression: str = booleanObject.tt_to_expr(variables, minterms)
```
3. To generate a logic diagram given an expression:
```python
input_expression: str = "~(A & B & C)+(A & B)+(B & C)"
file_name: str = "logic_diagram12"
format: str = "png"
directory: str = "examples" # stores in the current directory by default
booleanObject.expr_to_dg(input_expression, file_name, directory, format)
```
4. To generate a logic diagram given variables and minterms
```python
variables: List[str] = ['A', 'B', 'C']
minterms: List[int] = [0, 1, 3, 7]
file_name: str = "logic_diagram12"
directory: str = "examples"
format: str = "png"
booleanObject.tt_to_dg(variables, minterms, file_name, directory, format)
```
5. To assert equality for expressions
```python
expressions_list = ["(A & ~B) + (~A & B)", "(A ^ B)", "(A + B) & ~(A & B)"]
ret = booleanObject.expr_cmp(expression_list) # returns True
```
6. To simplify expressions (ambiguous):
```python
simplified_expr: str = booleanObject.expr_simplify("~(A) + ~(B)")
```
7. To generate random expressions:
```python
#generating a single expression
expression: str = boolean.generate_expression(max_depth=4, max_identifiers=5)
#generating multiple expressions
expression: List[str] = boolean.generate_expressions(max_depth=4, max_identifiers=5, count=100)
#max_depth refers to nesting depth:
expression = "A" #nesting_depth = 0
expression = "(((4)))" #nesting_depth = 3
#max_identifiers refers to the number of identifiers allowed in an expression
expression = "A + B + C" # has 3 identifiers
```
# Example Diagrams
## ((A & B) & C) + (~C)
## (A & B) + (~(A & B) & ~C) + (C & B)
Other diagrams can be found in the `diagrams/` directory
# Explanation of the Quine-McCluskey Algorithm
This section deals with converting a given truth table to a minimized boolean expression using the [Quine-McCluskey algorithm](https://en.wikipedia.org/wiki/Quine%E2%80%93McCluskey_algorithm) and producing a logic diagram.
## Overview
1. Initialize variables & [Minterms](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterm)
2. Identify essential [Prime implicants](https://en.wikipedia.org/wiki/Implicant)
3. Minimize & Synthesize the boolean function
### Initialization
- The synthesizer is initialized with a list of character variables and [minterms](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterm):
- [Minterms](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterm) refer to values for which the output is 1.
- [Prime implicants](https://en.wikipedia.org/wiki/Implicant) are found by repeatedly combining minterms that differ by only one variable:
### The Quine-McCluskey Algorithm
```
The Quine-McCluskey Algorithm
+-----------------------------------+
| initialize variables and minterms |
| variables := [A, B, C] |
| minterms := [0, 3, 6, 7] |
| minters := [000, 011, 110, 111] |
+-----------------------------------+
|
/
/
|
V
+-----------------------+
| find prime_implicants |
| | A | B | C | out | |
| |---|---|---|------| |
| | 0 | 0 | 0 | 1 | |
| | 0 | 0 | 1 | 0 | |
| | 0 | 1 | 0 | 0 | |
| | 0 | 1 | 1 | 1 | |
| | 1 | 0 | 0 | 0 | |
| | 1 | 0 | 1 | 0 | |
| | 1 | 1 | 0 | 1 | |
| | 1 | 1 | 1 | 1 | |
+-----------------------+
|
|
\
|
V
+----------------------------------+
| | group | minterm | A | B | C | |
| |-------|---------|---|---|---| |
| | 0 | m[0] | 0 | 0 | 0 | |
| | 2 | m[1] | 0 | 1 | 1 | |
| | | m[2] | 1 | 1 | 0 | |
| | 3 | m[3] | 1 | 1 | 1 | |
| |-------|---------|---|---|---| |
+----------------------------------+
\
\
|
V
+-------------------------------------------+
| find pair where only one variable differs |
| | group | minterm | A | B | C | expr |
| |-------|------------|---|---|---|--------|
| | 0 | m[0] | 0 | 0 | 0 | ~(ABC) |
| | 2 | m[1]-m[3] | _ | 1 | 1 | BC |
| | | m[2]-m[3] | 1 | 1 | _ | AB |
+-------------------------------------------+
|
/
|
V
+-------------------------------------------+
| since the bit-diff between pairs in each |
| class is > 1, we move onto the next step |
| |
| | expr | m0 | m1 | m2 | m3 | |
| |--------|-----|-----|-----|------| |
| | ~(ABC) | X | | | | |
| | BC | | X | | | |
| | AB | | | X | | |
| |--------|-----|-----|-----|------| |
+-------------------------------------------+
|
|
/
|
V
+-----------------------------------------+
| If each column contains one element |
| the expression can't be eliminated. |
| Therefore, the resulting expression is: |
| ~(ABC) + BC + AB |
+-----------------------------------------+
```
# Tips
1. Use parentheses when the order of operations is ambiguous.
2. The precedence is as follows, starting from the highest: NOT -> OR -> (AND, XOR)
# Documentation (for developers)
``` python
class TruthTableSynthesizer(variables: List[str], minterms: List[int])
class BooleanExpression(expression: str)
class Boolean()
class BooleanExpressionGenerator(max_identifiers: int = 5, max_depth: int = 5)
```
```python
TruthTableSynthesizer.decimal_to_binary(num: int) -> str
TruthTableSynthesizer.combine_implicants(implicants: List[Set[str]]) -> Set[str]
TruthTableSynthesizer.get_prime_implicants() -> Set[str]
TruthTableSynthesizer.covers_minterm(implicant: str, minterm: str) -> bool
TruthTableSynthesizer.get_essential_prime_implicants(prime_implicants: Set[str]) -> Set[str]
TruthTableSynthesizer.minimize_function(prime_implicants: Set[str], essential_implicants: Set[str]) -> List[str]
TruthTableSynthesizer.implicant_to_expression(implicant: str) -> str
TruthTableSynthesizer.synthesize() -> str
BooleanExpression.to_postfix(inifx: str) -> List[str]
BooleanExpression.evaluate(values: Dict[str, bool]) -> bool
BooleanExpression.tt() -> List[Tuple[Dict[str, bool], bool]]
BooleanExpression.fmt_tt() -> str
BooleanExpression.generate_logic_diagram() -> graphviz.Digraph
BooleanExpressionGenerator.generate_expression() -> str
BooleanExpressionGenerator.generate_expressions(number: int = 1) -> List[str]
Boolean.expr_to_tt(input_expression: str) -> str
Boolean.tt_to_expr(variables: List[str], minterms: List[int]) -> str
Boolean.tt_to_dg(variables: List[str], minterms: List[int], file: str | None = None, directory: str | None = None, format: str = "png") -> str
Boolean.expr_to_dg(input_expression: str, file: str | None = None, directory: str | None = None, format: str = "png") -> str
Boolean.expr_simplify(input_expression: str) -> str
Boolean.expr_cmp(expressions: List[str]) -> bool
Boolean.generate_expression(max_identifiers: int=5, max_depth: int=4) -> str
Boolean.generate_expressions(max_identifiers: int=5, max_depth: int=4, number: int) -> List[str]
```
#### TODO
0. Optimize functions
0.5. LaTeX interface
1. NAND, NOR, XNOR
2. Implication (X -> Y) and bi-implication (X <-> Y)
4. Add support for constants (1, 0)
5. Implement functional completeness testing
6. ~Expression comparison by comparing minterms (grammar agnostic)~
7. (improbable) implement [Quantum Gates](https://en.wikipedia.org/wiki/Quantum_logic_gate#:~:text=Quantum%20logic%20gates%20are%20the,are%20for%20conventional%20digital%20circuits.&text=Unlike%20many%20classical%20logic%20gates,computing%20using%20only%20reversible%20gates.)
8. (improbable) potential integration with Verilog systems
Raw data
{
"_id": null,
"home_page": null,
"name": "balg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "algebra, boolean, logic, logic diagram, truth table",
"author": null,
"author_email": "Mustafa Aamir <mustafa.290101@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/61/d2/450b5ba0631e6496d85e27e6a1bc0680820a189d8dea0e969db1ef4cf3c6/balg-0.0.6.tar.gz",
"platform": null,
"description": "# Boolean Algebra Toolkit\n\n- Truth Table to Boolean Expression and Logic Diagram Generator\n- Boolean Expression Evaluator and Truth Table Generator\n\n# Installation\n\n```bash\npip install balg\n```\n# Usage\n\n| **Token** | **Equivalent** |\n|:---------:|:--------------:|\n| & | AND |\n| ^ | XOR |\n| + | OR |\n| ~ | NOT |\n| [A-z] | Variable |\n\n```python\nfrom balg.boolean import Boolean\nbooleanObject = Boolean()\n```\n1. To generate an expression's truth table:\n\n```python\ninput_expression: str = \"~(A & B & C)+(A & B)+(B & C)\"\ntt: str = booleanObject.expr_to_tt(input_expression)\n```\n\n2. To generate an expression given the minterms and variables:\n\n```python\nvariables: List[str] = ['A', 'B', 'C']\nminterms: List[int] = [0, 1, 3, 7]\nexpression: str = booleanObject.tt_to_expr(variables, minterms)\n```\n\n3. To generate a logic diagram given an expression:\n\n```python\ninput_expression: str = \"~(A & B & C)+(A & B)+(B & C)\"\nfile_name: str = \"logic_diagram12\"\nformat: str = \"png\"\ndirectory: str = \"examples\" # stores in the current directory by default\nbooleanObject.expr_to_dg(input_expression, file_name, directory, format)\n```\n\n4. To generate a logic diagram given variables and minterms\n\n```python\nvariables: List[str] = ['A', 'B', 'C']\nminterms: List[int] = [0, 1, 3, 7]\nfile_name: str = \"logic_diagram12\"\ndirectory: str = \"examples\"\nformat: str = \"png\"\nbooleanObject.tt_to_dg(variables, minterms, file_name, directory, format)\n```\n\n5. To assert equality for expressions\n```python\nexpressions_list = [\"(A & ~B) + (~A & B)\", \"(A ^ B)\", \"(A + B) & ~(A & B)\"]\nret = booleanObject.expr_cmp(expression_list) # returns True\n```\n\n6. To simplify expressions (ambiguous):\n```python\nsimplified_expr: str = booleanObject.expr_simplify(\"~(A) + ~(B)\")\n```\n\n7. To generate random expressions:\n```python\n#generating a single expression\nexpression: str = boolean.generate_expression(max_depth=4, max_identifiers=5)\n\n#generating multiple expressions\nexpression: List[str] = boolean.generate_expressions(max_depth=4, max_identifiers=5, count=100)\n\n#max_depth refers to nesting depth:\nexpression = \"A\" #nesting_depth = 0\nexpression = \"(((4)))\" #nesting_depth = 3\n\n#max_identifiers refers to the number of identifiers allowed in an expression\nexpression = \"A + B + C\" # has 3 identifiers\n```\n\n# Example Diagrams\n\n## ((A & B) & C) + (~C)\n\n\n\n## (A & B) + (~(A & B) & ~C) + (C & B)\n\n\n\nOther diagrams can be found in the `diagrams/` directory\n\n# Explanation of the Quine-McCluskey Algorithm\nThis section deals with converting a given truth table to a minimized boolean expression using the [Quine-McCluskey algorithm](https://en.wikipedia.org/wiki/Quine%E2%80%93McCluskey_algorithm) and producing a logic diagram.\n\n## Overview\n1. Initialize variables & [Minterms](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterm)\n2. Identify essential [Prime implicants](https://en.wikipedia.org/wiki/Implicant)\n3. Minimize & Synthesize the boolean function\n\n### Initialization\n\n- The synthesizer is initialized with a list of character variables and [minterms](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterm):\n- [Minterms](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterm) refer to values for which the output is 1.\n- [Prime implicants](https://en.wikipedia.org/wiki/Implicant) are found by repeatedly combining minterms that differ by only one variable:\n\n### The Quine-McCluskey Algorithm\n\n```\n\n The Quine-McCluskey Algorithm\n\n+-----------------------------------+\n| initialize variables and minterms |\n| variables := [A, B, C] |\n| minterms := [0, 3, 6, 7] |\n| minters := [000, 011, 110, 111] |\n+-----------------------------------+\n |\n /\n /\n |\n V\n +-----------------------+\n | find prime_implicants |\n | | A | B | C | out | |\n | |---|---|---|------| |\n | | 0 | 0 | 0 | 1 | |\n | | 0 | 0 | 1 | 0 | |\n | | 0 | 1 | 0 | 0 | |\n | | 0 | 1 | 1 | 1 | |\n | | 1 | 0 | 0 | 0 | |\n | | 1 | 0 | 1 | 0 | |\n | | 1 | 1 | 0 | 1 | |\n | | 1 | 1 | 1 | 1 | |\n +-----------------------+\n |\n |\n \\\n |\n V\n+----------------------------------+\n| | group | minterm | A | B | C | |\n| |-------|---------|---|---|---| |\n| | 0 | m[0] | 0 | 0 | 0 | |\n| | 2 | m[1] | 0 | 1 | 1 | |\n| | | m[2] | 1 | 1 | 0 | |\n| | 3 | m[3] | 1 | 1 | 1 | |\n| |-------|---------|---|---|---| |\n+----------------------------------+\n \\\n \\\n |\n V\n +-------------------------------------------+\n | find pair where only one variable differs |\n | | group | minterm | A | B | C | expr |\n | |-------|------------|---|---|---|--------|\n | | 0 | m[0] | 0 | 0 | 0 | ~(ABC) |\n | | 2 | m[1]-m[3] | _ | 1 | 1 | BC |\n | | | m[2]-m[3] | 1 | 1 | _ | AB |\n +-------------------------------------------+\n |\n /\n |\n V\n +-------------------------------------------+\n | since the bit-diff between pairs in each |\n | class is > 1, we move onto the next step |\n | |\n | | expr | m0 | m1 | m2 | m3 | |\n | |--------|-----|-----|-----|------| |\n | | ~(ABC) | X | | | | |\n | | BC | | X | | | |\n | | AB | | | X | | |\n | |--------|-----|-----|-----|------| |\n +-------------------------------------------+\n |\n |\n /\n |\n V\n +-----------------------------------------+\n | If each column contains one element |\n | the expression can't be eliminated. |\n | Therefore, the resulting expression is: |\n | ~(ABC) + BC + AB |\n +-----------------------------------------+\n\n```\n\n# Tips\n1. Use parentheses when the order of operations is ambiguous.\n2. The precedence is as follows, starting from the highest: NOT -> OR -> (AND, XOR)\n\n# Documentation (for developers)\n\n``` python\nclass TruthTableSynthesizer(variables: List[str], minterms: List[int])\nclass BooleanExpression(expression: str)\nclass Boolean()\nclass BooleanExpressionGenerator(max_identifiers: int = 5, max_depth: int = 5)\n```\n```python\nTruthTableSynthesizer.decimal_to_binary(num: int) -> str\nTruthTableSynthesizer.combine_implicants(implicants: List[Set[str]]) -> Set[str]\nTruthTableSynthesizer.get_prime_implicants() -> Set[str]\nTruthTableSynthesizer.covers_minterm(implicant: str, minterm: str) -> bool\nTruthTableSynthesizer.get_essential_prime_implicants(prime_implicants: Set[str]) -> Set[str]\nTruthTableSynthesizer.minimize_function(prime_implicants: Set[str], essential_implicants: Set[str]) -> List[str]\nTruthTableSynthesizer.implicant_to_expression(implicant: str) -> str\nTruthTableSynthesizer.synthesize() -> str\n\nBooleanExpression.to_postfix(inifx: str) -> List[str]\nBooleanExpression.evaluate(values: Dict[str, bool]) -> bool\nBooleanExpression.tt() -> List[Tuple[Dict[str, bool], bool]]\nBooleanExpression.fmt_tt() -> str\nBooleanExpression.generate_logic_diagram() -> graphviz.Digraph\n\nBooleanExpressionGenerator.generate_expression() -> str\nBooleanExpressionGenerator.generate_expressions(number: int = 1) -> List[str]\n\nBoolean.expr_to_tt(input_expression: str) -> str\nBoolean.tt_to_expr(variables: List[str], minterms: List[int]) -> str\nBoolean.tt_to_dg(variables: List[str], minterms: List[int], file: str | None = None, directory: str | None = None, format: str = \"png\") -> str\nBoolean.expr_to_dg(input_expression: str, file: str | None = None, directory: str | None = None, format: str = \"png\") -> str\nBoolean.expr_simplify(input_expression: str) -> str\nBoolean.expr_cmp(expressions: List[str]) -> bool\nBoolean.generate_expression(max_identifiers: int=5, max_depth: int=4) -> str\nBoolean.generate_expressions(max_identifiers: int=5, max_depth: int=4, number: int) -> List[str]\n```\n\n#### TODO\n0. Optimize functions\n0.5. LaTeX interface\n1. NAND, NOR, XNOR\n2. Implication (X -> Y) and bi-implication (X <-> Y)\n4. Add support for constants (1, 0)\n5. Implement functional completeness testing\n6. ~Expression comparison by comparing minterms (grammar agnostic)~\n7. (improbable) implement [Quantum Gates](https://en.wikipedia.org/wiki/Quantum_logic_gate#:~:text=Quantum%20logic%20gates%20are%20the,are%20for%20conventional%20digital%20circuits.&text=Unlike%20many%20classical%20logic%20gates,computing%20using%20only%20reversible%20gates.)\n8. (improbable) potential integration with Verilog systems\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 MustafaAamir Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A boolean algebra toolkit to evaluate expressions, truth tables, and produce logic diagrams",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://github.com/MustafaAamir/balg"
},
"split_keywords": [
"algebra",
" boolean",
" logic",
" logic diagram",
" truth table"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4296b869070690dbc073e50f18cf5aa0c599efefa6c0e66aee5fa6fd43d50146",
"md5": "57c01fb93ab7e1a148f300f9b3e42b97",
"sha256": "d266cc55b19852f05a6c1231723df0d5b8c547888c3494ce2e98d9369bbb8355"
},
"downloads": -1,
"filename": "balg-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "57c01fb93ab7e1a148f300f9b3e42b97",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10523,
"upload_time": "2024-09-08T18:19:10",
"upload_time_iso_8601": "2024-09-08T18:19:10.212990Z",
"url": "https://files.pythonhosted.org/packages/42/96/b869070690dbc073e50f18cf5aa0c599efefa6c0e66aee5fa6fd43d50146/balg-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61d2450b5ba0631e6496d85e27e6a1bc0680820a189d8dea0e969db1ef4cf3c6",
"md5": "01322dccb98e9a07de91ebbbfc323e07",
"sha256": "b1a53c862497d8a4e952a5aa6bb99f2f336353b781138059a0f84e4d71250bed"
},
"downloads": -1,
"filename": "balg-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "01322dccb98e9a07de91ebbbfc323e07",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 193412,
"upload_time": "2024-09-08T18:19:13",
"upload_time_iso_8601": "2024-09-08T18:19:13.969403Z",
"url": "https://files.pythonhosted.org/packages/61/d2/450b5ba0631e6496d85e27e6a1bc0680820a189d8dea0e969db1ef4cf3c6/balg-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-08 18:19:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MustafaAamir",
"github_project": "balg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "balg"
}
