chemql-python 0.1.0__tar.gz → 0.2.1__tar.gz

{chemql_python-0.1.0/src/chemql_python.egg-info → chemql_python-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemql-python
-Version: 0.1.0
+Version: 0.2.1
 Summary: A chemistry-focused query language and REPL
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -12,6 +12,8 @@ Dynamic: license-file
 
 # ChemQL
 
+![ChemQL logo](logo.png)
+
 ChemQL is a chemistry-focused query language and REPL for exploring element, molecule, and reaction datasets. It lets you search the built-in chemistry data, filter results with expressions, set reaction conditions, and combine queries with small Python snippets when needed.
 
 ## What ChemQL does
@@ -80,9 +82,11 @@ The Python package is `chemql`. Its query engine, chemistry types, and bundled
 datasets can be imported directly:
 
 ```python
-from chemql import execute_query_text
+from chemql import balance_stoichiometry, execute_query_text
 
 result = execute_query_text('search elements name = "Hydrogen"')
+reaction = balance_stoichiometry(["O2", "H2"], ["H2O"], reversible=True)
+print(reaction)
 ```
 
 ## Core query syntax
@@ -159,10 +163,18 @@ add catalyst "Vanadium oxide"
 remove catalyst "Vanadium oxide"
 conditions
 react N2 3H2
+balance O2 + H2 -> H2O
+balance O2 + H2 <-> H2O
 ```
 
 Temperature accepts `C`, `F`, or `K`; pressure accepts `Pa`, `N/m^2`, `Nm^-2`, `bar`, or `atm`. The keywords `standard` and `room` are also accepted.
 
+`balance` accepts chemical formulas on each side, separated by `+`. It returns
+a `Reaction` with the smallest positive integer stoichiometric coefficients.
+The arrow determines reaction direction: `->` is irreversible and `<->` is
+reversible. `//` begins a comment, as it does elsewhere in ChemQL. The function
+API is `balance_stoichiometry(reactants, products, reversible=None)`.
+
 ## Operators
 
 ChemQL supports these comparison operators:

{chemql_python-0.1.0 → chemql_python-0.2.1}/README.md

@@ -1,5 +1,7 @@
 # ChemQL
 
+![ChemQL logo](logo.png)
+
 ChemQL is a chemistry-focused query language and REPL for exploring element, molecule, and reaction datasets. It lets you search the built-in chemistry data, filter results with expressions, set reaction conditions, and combine queries with small Python snippets when needed.
 
 ## What ChemQL does
@@ -68,9 +70,11 @@ The Python package is `chemql`. Its query engine, chemistry types, and bundled
 datasets can be imported directly:
 
 ```python
-from chemql import execute_query_text
+from chemql import balance_stoichiometry, execute_query_text
 
 result = execute_query_text('search elements name = "Hydrogen"')
+reaction = balance_stoichiometry(["O2", "H2"], ["H2O"], reversible=True)
+print(reaction)
 ```
 
 ## Core query syntax
@@ -147,10 +151,18 @@ add catalyst "Vanadium oxide"
 remove catalyst "Vanadium oxide"
 conditions
 react N2 3H2
+balance O2 + H2 -> H2O
+balance O2 + H2 <-> H2O
 ```
 
 Temperature accepts `C`, `F`, or `K`; pressure accepts `Pa`, `N/m^2`, `Nm^-2`, `bar`, or `atm`. The keywords `standard` and `room` are also accepted.
 
+`balance` accepts chemical formulas on each side, separated by `+`. It returns
+a `Reaction` with the smallest positive integer stoichiometric coefficients.
+The arrow determines reaction direction: `->` is irreversible and `<->` is
+reversible. `//` begins a comment, as it does elsewhere in ChemQL. The function
+API is `balance_stoichiometry(reactants, products, reversible=None)`.
+
 ## Operators
 
 ChemQL supports these comparison operators:

{chemql_python-0.1.0 → chemql_python-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chemql-python"
-version = "0.1.0"
+version = "0.2.1"
 description = "A chemistry-focused query language and REPL"
 readme = "README.md"
 requires-python = ">=3.10"

{chemql_python-0.1.0 → chemql_python-0.2.1}/src/chemql/__init__.py

@@ -13,6 +13,9 @@ from prompt_toolkit.completion import Completer, Completion
 import urllib.parse
 import urllib.request
 import urllib.error
+from fractions import Fraction
+from functools import reduce
+from math import gcd
 
 
 __all__ = [
@@ -22,6 +25,7 @@ __all__ = [
     "Reaction",
     "ReturnTable",
     "Unknown",
+    "balance_stoichiometry",
     "execute_query",
     "execute_query_text",
 ]
@@ -918,7 +922,170 @@ reactionKeys = ("id", "name", "equation", "reaction_type", "reversible", "reacta
 del elements
 del reactions
 del molecules
-del MOLECULES_BY_FORMULA
+
+
+def _formula_counts(formula):
+    if not isinstance(formula, str) or not formula:
+        raise ValueError("Chemical formulas must be non-empty strings")
+    symbols = {element.symbol for element in ELEMENTS}
+
+    def parse_group(index, nested=False):
+        counts = {}
+        while index < len(formula):
+            char = formula[index]
+            if char == ")":
+                if not nested:
+                    raise ValueError(f"Unmatched closing parenthesis in formula `{formula}`")
+                return counts, index
+            if char == "(":
+                group, index = parse_group(index + 1, True)
+                if index >= len(formula) or formula[index] != ")":
+                    raise ValueError(f"Unclosed parenthesis in formula `{formula}`")
+                index += 1
+                match = re.match(r"\d+", formula[index:])
+                multiplier = int(match.group()) if match else 1
+                if multiplier <= 0:
+                    raise ValueError(f"Invalid atom count in formula `{formula}`")
+                if match:
+                    index += len(match.group())
+                for symbol, amount in group.items():
+                    counts[symbol] = counts.get(symbol, 0) + amount * multiplier
+                continue
+            if not char.isupper():
+                raise ValueError(f"Invalid chemical formula `{formula}`")
+            end = index + 1
+            if end < len(formula) and formula[end].islower():
+                end += 1
+            symbol = formula[index:end]
+            if symbol not in symbols:
+                raise ValueError(f"Unknown element `{symbol}` in formula `{formula}`")
+            index = end
+            match = re.match(r"\d+", formula[index:])
+            amount = int(match.group()) if match else 1
+            if amount <= 0:
+                raise ValueError(f"Invalid atom count in formula `{formula}`")
+            if match:
+                index += len(match.group())
+            counts[symbol] = counts.get(symbol, 0) + amount
+        if nested:
+            raise ValueError(f"Unclosed parenthesis in formula `{formula}`")
+        return counts, index
+
+    counts, end = parse_group(0)
+    if end != len(formula) or not counts:
+        raise ValueError(f"Invalid chemical formula `{formula}`")
+    return counts
+
+
+def _stoichiometric_species(side):
+    if isinstance(side, str):
+        species = [item.strip() for item in side.split("+")]
+    else:
+        species = [str(item).strip() for item in side]
+    if not species or any(not item for item in species):
+        raise ValueError("Both sides of a reaction must contain molecules")
+    return species
+
+
+def balance_stoichiometry(reactants, products, reversible=None):
+    """Balance a reaction and return it as a :class:`Reaction`."""
+    reactant_formulas = _stoichiometric_species(reactants)
+    product_formulas = _stoichiometric_species(products)
+    formulas = reactant_formulas + product_formulas
+    formulas_by_element = [_formula_counts(formula) for formula in formulas]
+    elements = list(dict.fromkeys(
+        element for counts in formulas_by_element for element in counts
+    ))
+    matrix = [
+        [
+            Fraction(counts.get(element, 0) * (1 if index < len(reactant_formulas) else -1))
+            for index, counts in enumerate(formulas_by_element)
+        ]
+        for element in elements
+    ]
+
+    pivot_columns = []
+    pivot_row = 0
+    for column in range(len(formulas)):
+        selected = next(
+            (row for row in range(pivot_row, len(matrix)) if matrix[row][column]),
+            None,
+        )
+        if selected is None:
+            continue
+        matrix[pivot_row], matrix[selected] = matrix[selected], matrix[pivot_row]
+        divisor = matrix[pivot_row][column]
+        matrix[pivot_row] = [value / divisor for value in matrix[pivot_row]]
+        for row in range(len(matrix)):
+            if row == pivot_row or not matrix[row][column]:
+                continue
+            factor = matrix[row][column]
+            matrix[row] = [
+                value - factor * pivot
+                for value, pivot in zip(matrix[row], matrix[pivot_row])
+            ]
+        pivot_columns.append(column)
+        pivot_row += 1
+        if pivot_row == len(matrix):
+            break
+
+    free_columns = [
+        column for column in range(len(formulas)) if column not in pivot_columns
+    ]
+    if len(free_columns) != 1:
+        raise ValueError("Reaction does not have a unique stoichiometric balance")
+    coefficients = [Fraction(0) for _ in formulas]
+    free_column = free_columns[0]
+    coefficients[free_column] = Fraction(1)
+    for row, column in enumerate(pivot_columns):
+        coefficients[column] = -matrix[row][free_column]
+    if all(value < 0 for value in coefficients):
+        coefficients = [-value for value in coefficients]
+    if any(value <= 0 for value in coefficients):
+        raise ValueError("Reaction cannot be balanced with positive coefficients")
+
+    denominator = 1
+    for coefficient in coefficients:
+        denominator = denominator * coefficient.denominator // gcd(
+            denominator, coefficient.denominator
+        )
+    integer_coefficients = [
+        int(coefficient * denominator) for coefficient in coefficients
+    ]
+    common_divisor = reduce(gcd, integer_coefficients)
+    integer_coefficients = [value // common_divisor for value in integer_coefficients]
+    participants = [
+        {
+            "molecule": formula,
+            "stoichiometric_coefficient": coefficient,
+        }
+        for formula, coefficient in zip(formulas, integer_coefficients)
+    ]
+    split_at = len(reactant_formulas)
+    return Reaction(
+        "BALANCED",
+        "Balanced reaction",
+        "balanced",
+        reversible,
+        participants[:split_at],
+        participants[split_at:],
+        {},
+        "",
+    )
+
+
+def _execute_balance_command(text):
+    text = text.split("//", 1)[0].rstrip()
+    match = re.fullmatch(
+        r"\s*balance\s+(.+?)\s*(<->|->)\s*(.+?)\s*",
+        text,
+        re.IGNORECASE,
+    )
+    if not match:
+        raise ValueError("Usage: balance <reactants> ->|<-> <products>")
+    reactants, arrow, products = match.groups()
+    reversible = arrow == "<->"
+    return balance_stoichiometry(reactants, products, reversible)
 
 
 
@@ -2134,6 +2301,14 @@ def execute(arguments, query_text=None, positions=None):
     if not arguments:
         return
 
+    if arguments[0].lower() == "balance":
+        try:
+            return _execute_balance_command(
+                query_text if query_text is not None else shlex.join(arguments)
+            )
+        except ValueError as exc:
+            return format_error(str(exc), query_text)
+
     if arguments[0].lower() in {"help", "?"}:
         return HELP
 
@@ -2562,11 +2737,15 @@ HELP = """\033[1;36mChemql - Python Chemistry Query Language\033[0m
             set catalysts
               conditions
             react N2 3H2
+            balance O2 + H2 -> H2O
+            balance O2 + H2 <-> H2O
 
     Temperature accepts C, F, or K. Pressure accepts Pa, N/m^2, Nm^-2, or bar.
     `standard` means 0 C and 100000 Pa; `room` means 25 C and 101325 Pa.
           Unset values appear as `Not Set` in `conditions`.
     Reaction matching allows 5 K temperature and 5% pressure tolerance.
+    `balance` returns a Reaction with the smallest positive integer coefficients.
+    The `->` arrow is irreversible; `<->` is reversible. `//` starts a comment.
 
 \033[1;33mRESULTS\033[0m
   \033[1mfirst\033[0m
@@ -2718,7 +2897,7 @@ class ChemqlLexer(Lexer):
             first_word = words[0] if words else ""
 
             # search / source / list / return / clear / exit
-            if first_word in {"search", "source", "list", "clear", "exit", "findel", "findmol", "findre", "set", "add", "remove", "react", "conditions", "view", "help", "dump"}:
+            if first_word in {"search", "source", "list", "clear", "exit", "findel", "findmol", "findre", "set", "add", "remove", "react", "balance", "conditions", "view", "help", "dump"}:
                 command_start = line.find(first_word)
                 command_end = command_start + len(first_word)
 
@@ -2857,6 +3036,7 @@ class ChemqlLexer(Lexer):
                         "add",
                         "remove",
                         "react",
+                        "balance",
                         "conditions",
                         "view",
                         "help",
@@ -2936,7 +3116,7 @@ class ChemqlCompleter(Completer):
         commands = (
             "search", "source", "list", "clear", "return", "exit",
             "findel", "findmol", "findre", "set", "add", "remove",
-            "react", "conditions",
+            "react", "balance", "conditions",
         )
 
         if not command_words:
@@ -3019,7 +3199,7 @@ def main():
         "-v",
         "--version",
         action="version",
-        version="0.1.0",
+        version="0.2.1",
     )
 
     args = parser.parse_args()

{chemql_python-0.1.0 → chemql_python-0.2.1/src/chemql_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemql-python
-Version: 0.1.0
+Version: 0.2.1
 Summary: A chemistry-focused query language and REPL
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -12,6 +12,8 @@ Dynamic: license-file
 
 # ChemQL
 
+![ChemQL logo](logo.png)
+
 ChemQL is a chemistry-focused query language and REPL for exploring element, molecule, and reaction datasets. It lets you search the built-in chemistry data, filter results with expressions, set reaction conditions, and combine queries with small Python snippets when needed.
 
 ## What ChemQL does
@@ -80,9 +82,11 @@ The Python package is `chemql`. Its query engine, chemistry types, and bundled
 datasets can be imported directly:
 
 ```python
-from chemql import execute_query_text
+from chemql import balance_stoichiometry, execute_query_text
 
 result = execute_query_text('search elements name = "Hydrogen"')
+reaction = balance_stoichiometry(["O2", "H2"], ["H2O"], reversible=True)
+print(reaction)
 ```
 
 ## Core query syntax
@@ -159,10 +163,18 @@ add catalyst "Vanadium oxide"
 remove catalyst "Vanadium oxide"
 conditions
 react N2 3H2
+balance O2 + H2 -> H2O
+balance O2 + H2 <-> H2O
 ```
 
 Temperature accepts `C`, `F`, or `K`; pressure accepts `Pa`, `N/m^2`, `Nm^-2`, `bar`, or `atm`. The keywords `standard` and `room` are also accepted.
 
+`balance` accepts chemical formulas on each side, separated by `+`. It returns
+a `Reaction` with the smallest positive integer stoichiometric coefficients.
+The arrow determines reaction direction: `->` is irreversible and `<->` is
+reversible. `//` begins a comment, as it does elsewhere in ChemQL. The function
+API is `balance_stoichiometry(reactants, products, reversible=None)`.
+
 ## Operators
 
 ChemQL supports these comparison operators:

{chemql_python-0.1.0 → chemql_python-0.2.1}/tests/test_public_api.py

@@ -10,6 +10,7 @@ def test_all_exports_only_public_query_api_and_result_types():
         "Reaction",
         "ReturnTable",
         "Unknown",
+        "balance_stoichiometry",
         "execute_query",
         "execute_query_text",
     }
@@ -24,4 +25,4 @@ def test_cli_version_option_prints_version(monkeypatch, capsys, option):
         chemql.main()
 
     assert exception.value.code == 0
-    assert capsys.readouterr().out == "0.1.0\n"
+    assert capsys.readouterr().out == "0.2.1\n"

{chemql_python-0.1.0 → chemql_python-0.2.1}/tests/test_reactions.py

@@ -2,6 +2,45 @@ import chemql
 from prompt_toolkit.document import Document
 
 
+def test_balance_stoichiometry_returns_minimal_reaction_coefficients():
+    reaction = chemql.balance_stoichiometry(["O2", "H2"], ["H2O"], True)
+
+    assert isinstance(reaction, chemql.Reaction)
+    assert [part["stoichiometric_coefficient"] for part in reaction.reactants] == [1, 2]
+    assert [part["stoichiometric_coefficient"] for part in reaction.products] == [2]
+    assert reaction.reversible is True
+
+    grouped = chemql.balance_stoichiometry(
+        ["Ca(OH)2", "H3PO4"],
+        ["Ca3(PO4)2", "H2O"],
+    )
+    assert [
+        part["stoichiometric_coefficient"]
+        for part in grouped.reactants + grouped.products
+    ] == [3, 2, 1, 6]
+
+
+def test_balance_syntax_infers_direction_from_arrow_and_honors_comments(capsys):
+    chemql.process_lines(["balance O2 + H2 -> H2O //reversible"])
+    assert "1 O₂ + 2 H₂ → 2 H₂O" in capsys.readouterr().out
+
+    reaction = chemql.execute_query_text(
+        "balance O2 + H2 <-> H2O //irreversible"
+    )
+    assert isinstance(reaction, chemql.Reaction)
+    assert reaction.reversible is True
+    assert "1 O₂ + 2 H₂ ⇌ 2 H₂O" in str(reaction)
+
+
+def test_balance_stoichiometry_rejects_invalid_formula():
+    try:
+        chemql.balance_stoichiometry(["Xx2"], ["H2"])
+    except ValueError as exc:
+        assert "Unknown element" in str(exc)
+    else:
+        raise AssertionError("Unknown elements must be rejected")
+
+
 def test_findre_searches_reactions_by_id_and_projects_attributes():
     result = chemql.execute([
         "findre", "RHEA:10000", "return", "id", "name", "source"