{"id":25217791,"url":"https://github.com/mustafaaamir/balg","last_synced_at":"2026-01-30T22:37:48.173Z","repository":{"id":255746233,"uuid":"853297079","full_name":"MustafaAamir/balg","owner":"MustafaAamir","description":"A boolean algebra toolkit written in python","archived":false,"fork":false,"pushed_at":"2024-11-05T10:13:39.000Z","size":449,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-29T01:24:11.154Z","etag":null,"topics":["boolean-algebra","boolean-expression","python3","quine-mccluskey"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MustafaAamir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-06T11:31:37.000Z","updated_at":"2024-11-26T09:23:23.000Z","dependencies_parsed_at":"2024-11-05T10:52:39.475Z","dependency_job_id":null,"html_url":"https://github.com/MustafaAamir/balg","commit_stats":null,"previous_names":["mustafaaamir/booleanalgebratoolkit","mustafaaamir/balg"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MustafaAamir/balg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MustafaAamir%2Fbalg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MustafaAamir%2Fbalg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MustafaAamir%2Fbalg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MustafaAamir%2Fbalg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MustafaAamir","download_url":"https://codeload.github.com/MustafaAamir/balg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MustafaAamir%2Fbalg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28921417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T22:32:35.345Z","status":"ssl_error","status_checked_at":"2026-01-30T22:32:31.927Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boolean-algebra","boolean-expression","python3","quine-mccluskey"],"created_at":"2025-02-10T20:52:29.482Z","updated_at":"2026-01-30T22:37:48.159Z","avatar_url":"https://github.com/MustafaAamir.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n![BalgPoster_ManimCE_v0 18 1](https://github.com/user-attachments/assets/8fcd383c-b52f-4884-b375-32560b495249)\n\n\n# Installation\n\n```bash\npip install balg==0.0.6\n```\n# Usage\n\n| **Token** | **Equivalent** |\n|:---------:|:--------------:|\n|     \u0026     |       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 \u0026 B \u0026 C)+(A \u0026 B)+(B \u0026 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 \u0026 B \u0026 C)+(A \u0026 B)+(B \u0026 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 \u0026 ~B) + (~A \u0026 B)\", \"(A ^ B)\", \"(A + B) \u0026 ~(A \u0026 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 \u0026 B) \u0026 C) + (~C)\n\n![logic_diagram](https://github.com/user-attachments/assets/5142ee73-0c51-4bcd-9730-0a33129cf72f)\n\n## (A \u0026 B) + (~(A \u0026 B) \u0026 ~C) + (C \u0026 B)\n\n![logic_diagram](https://github.com/user-attachments/assets/ae681531-7076-445b-be9f-41bf98dff005)\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 \u0026 [Minterms](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterm)\n2. Identify essential [Prime implicants](https://en.wikipedia.org/wiki/Implicant)\n3. Minimize \u0026 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 \u003e 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 -\u003e OR -\u003e (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) -\u003e str\nTruthTableSynthesizer.combine_implicants(implicants: List[Set[str]]) -\u003e Set[str]\nTruthTableSynthesizer.get_prime_implicants() -\u003e Set[str]\nTruthTableSynthesizer.covers_minterm(implicant: str, minterm: str) -\u003e bool\nTruthTableSynthesizer.get_essential_prime_implicants(prime_implicants: Set[str]) -\u003e Set[str]\nTruthTableSynthesizer.minimize_function(prime_implicants: Set[str], essential_implicants: Set[str]) -\u003e List[str]\nTruthTableSynthesizer.implicant_to_expression(implicant: str) -\u003e str\nTruthTableSynthesizer.synthesize() -\u003e str\n\nBooleanExpression.to_postfix(inifx: str) -\u003e List[str]\nBooleanExpression.evaluate(values: Dict[str, bool]) -\u003e bool\nBooleanExpression.tt() -\u003e List[Tuple[Dict[str, bool], bool]]\nBooleanExpression.fmt_tt() -\u003e str\nBooleanExpression.generate_logic_diagram() -\u003e graphviz.Digraph\n\nBooleanExpressionGenerator.generate_expression() -\u003e str\nBooleanExpressionGenerator.generate_expressions(number: int = 1) -\u003e List[str]\n\nBoolean.expr_to_tt(input_expression: str) -\u003e str\nBoolean.tt_to_expr(variables: List[str], minterms: List[int]) -\u003e str\nBoolean.tt_to_dg(variables: List[str], minterms: List[int], file: str | None = None, directory: str | None = None, format: str = \"png\") -\u003e str\nBoolean.expr_to_dg(input_expression: str, file: str | None = None, directory: str | None = None, format: str = \"png\") -\u003e str\nBoolean.expr_simplify(input_expression: str) -\u003e str\nBoolean.expr_cmp(expressions: List[str]) -\u003e bool\nBoolean.generate_expression(max_identifiers: int=5, max_depth: int=4) -\u003e str\nBoolean.generate_expressions(max_identifiers: int=5, max_depth: int=4, number: int) -\u003e List[str]\n```\n\n#### TODO\n0. Optimize functions\n0.5. LaTeX interface\n1. NAND, NOR, XNOR\n2. Implication (X -\u003e Y) and bi-implication (X \u003c-\u003e 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.\u0026text=Unlike%20many%20classical%20logic%20gates,computing%20using%20only%20reversible%20gates.)\n8. (improbable) potential integration with Verilog systems\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafaaamir%2Fbalg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmustafaaamir%2Fbalg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafaaamir%2Fbalg/lists"}