homlab-polynomial 0.1.0__tar.gz

homlab_polynomial-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Homology Lab
+
+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.

homlab_polynomial-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: homlab-polynomial
+Version: 0.1.0
+Summary: Collect indexed C terms in polynomials with SymPy.
+Author: GGN_2015
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy>=1.10
+Dynamic: license-file
+
+# homlab_polynomial
+
+`homlab_polynomial` 提供一个 Python 编程入口，用 SymPy 将包含普通变量 `A` 和三下标变量
+`C[x, y, z]` 的字符串表达式整理成按不同 `C[x, y, z]` 分组的形式。
+
+## 安装
+
+```bash
+pip install .
+```
+
+## 使用
+
+```python
+from homlab_polynomial import organize_polynomial
+
+expr = "A*C[1, 2, 3] + 2*C[1,2,3] + A^2*C[0,0,0]"
+print(organize_polynomial(expr))
+```
+
+输出：
+
+```text
+C[0, 0, 0]*(A^2) + C[1, 2, 3]*(A + 2)
+```
+
+负指数也支持：
+
+```python
+organize_polynomial("A^-10*C[0,0,0] + 2*C[0,0,0]/A")
+```
+
+输出：
+
+```text
+C[0, 0, 0]*(2*A^(-1) + A^(-10))
+```
+
+说明：
+
+- `C[x, y, z]` 的三个下标必须是整数，可以为负数。
+- 输入支持用 `^` 表示指数运算，也支持 Python/SymPy 风格的 `**`。
+- 默认输出也使用 `^`。如果需要 `**`，可以传入 `output_power_operator="**"`。
+- 系数支持有限 Laurent 多项式，因此 `A^-1`、`1/A`、`A^-10` 都可以使用。
+- `C[x, y, z]` 项不会带外部负号；负号会保留在括号中的系数多项式里。
+- 不含 `C` 的纯 `A` 项会作为最后的余项保留。
+
+如果需要继续做 SymPy 计算，可以使用：
+
+```python
+from homlab_polynomial import organize_polynomial_expr
+
+sympy_expr = organize_polynomial_expr("A*C[1,2,3] + C[1,2,3]")
+```
+
+## 验算
+
+`organize_polynomial()` 默认会在每次整理后进行随机代入验算。它会给 `A` 和所有出现过的
+`C[x, y, z]` 赋非零有理数，检查整理前后的表达式是否一致。
+
+也可以直接调用验算函数：
+
+```python
+from homlab_polynomial import verify_simplification
+
+verify_simplification(
+    "A*C[1,2,3] + C[1,2,3]",
+    "C[1, 2, 3]*(A + 1)",
+)
+```

homlab_polynomial-0.1.0/README.md

@@ -0,0 +1,70 @@
+# homlab_polynomial
+
+`homlab_polynomial` 提供一个 Python 编程入口，用 SymPy 将包含普通变量 `A` 和三下标变量
+`C[x, y, z]` 的字符串表达式整理成按不同 `C[x, y, z]` 分组的形式。
+
+## 安装
+
+```bash
+pip install .
+```
+
+## 使用
+
+```python
+from homlab_polynomial import organize_polynomial
+
+expr = "A*C[1, 2, 3] + 2*C[1,2,3] + A^2*C[0,0,0]"
+print(organize_polynomial(expr))
+```
+
+输出：
+
+```text
+C[0, 0, 0]*(A^2) + C[1, 2, 3]*(A + 2)
+```
+
+负指数也支持：
+
+```python
+organize_polynomial("A^-10*C[0,0,0] + 2*C[0,0,0]/A")
+```
+
+输出：
+
+```text
+C[0, 0, 0]*(2*A^(-1) + A^(-10))
+```
+
+说明：
+
+- `C[x, y, z]` 的三个下标必须是整数，可以为负数。
+- 输入支持用 `^` 表示指数运算，也支持 Python/SymPy 风格的 `**`。
+- 默认输出也使用 `^`。如果需要 `**`，可以传入 `output_power_operator="**"`。
+- 系数支持有限 Laurent 多项式，因此 `A^-1`、`1/A`、`A^-10` 都可以使用。
+- `C[x, y, z]` 项不会带外部负号；负号会保留在括号中的系数多项式里。
+- 不含 `C` 的纯 `A` 项会作为最后的余项保留。
+
+如果需要继续做 SymPy 计算，可以使用：
+
+```python
+from homlab_polynomial import organize_polynomial_expr
+
+sympy_expr = organize_polynomial_expr("A*C[1,2,3] + C[1,2,3]")
+```
+
+## 验算
+
+`organize_polynomial()` 默认会在每次整理后进行随机代入验算。它会给 `A` 和所有出现过的
+`C[x, y, z]` 赋非零有理数，检查整理前后的表达式是否一致。
+
+也可以直接调用验算函数：
+
+```python
+from homlab_polynomial import verify_simplification
+
+verify_simplification(
+    "A*C[1,2,3] + C[1,2,3]",
+    "C[1, 2, 3]*(A + 1)",
+)
+```

homlab_polynomial-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "homlab-polynomial"
+version = "0.1.0"
+description = "Collect indexed C terms in polynomials with SymPy."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "GGN_2015" }
+]
+dependencies = [
+  "sympy>=1.10"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

homlab_polynomial-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

homlab_polynomial-0.1.0/src/homlab_polynomial/__init__.py

@@ -0,0 +1,17 @@
+"""Public API for homlab_polynomial."""
+
+from .core import (
+    PolynomialParseError,
+    PolynomialVerificationError,
+    organize_polynomial,
+    organize_polynomial_expr,
+    verify_simplification,
+)
+
+__all__ = [
+    "PolynomialParseError",
+    "PolynomialVerificationError",
+    "organize_polynomial",
+    "organize_polynomial_expr",
+    "verify_simplification",
+]

homlab_polynomial-0.1.0/src/homlab_polynomial/core.py

@@ -0,0 +1,515 @@
+"""Polynomial collection utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from random import Random
+import re
+from typing import Literal, Optional
+
+import sympy as sp
+from sympy.parsing.sympy_parser import (
+    convert_xor,
+    implicit_multiplication_application,
+    parse_expr,
+    standard_transformations,
+)
+
+
+Index = tuple[int, int, int]
+PowerOperator = Literal["^", "**"]
+
+_C_PATTERN = re.compile(
+    r"(?<![A-Za-z_])C\s*\[\s*([+-]?\d+)\s*,\s*([+-]?\d+)\s*,\s*([+-]?\d+)\s*\]"
+)
+_TOKEN_PREFIX = "_homlab_C_"
+_TRANSFORMATIONS = standard_transformations + (
+    convert_xor,
+    implicit_multiplication_application,
+)
+_SAFE_GLOBALS = {
+    "Add": sp.Add,
+    "Float": sp.Float,
+    "Integer": sp.Integer,
+    "Mul": sp.Mul,
+    "Pow": sp.Pow,
+    "Rational": sp.Rational,
+    "Symbol": sp.Symbol,
+}
+
+
+class PolynomialParseError(ValueError):
+    """Raised when a polynomial string cannot be parsed or collected."""
+
+
+class PolynomialVerificationError(ValueError):
+    """Raised when randomized verification finds a mismatch."""
+
+
+@dataclass(frozen=True)
+class _ParsedPolynomial:
+    expr: sp.Expr
+    a_symbol: sp.Symbol
+    c_symbols: dict[sp.Symbol, Index]
+
+
+@dataclass(frozen=True)
+class _CollectedTerm:
+    c_powers: tuple[tuple[Index, int], ...]
+    coefficient: sp.Expr
+
+
+def organize_polynomial(
+    expression: str,
+    *,
+    output_power_operator: PowerOperator = "^",
+    verify: bool = True,
+    verification_trials: int = 5,
+    random_seed: Optional[int] = None,
+) -> str:
+    """Collect a polynomial by indexed ``C[x, y, z]`` terms.
+
+    Parameters
+    ----------
+    expression:
+        Polynomial string using ``A`` and indexed ``C[x, y, z]`` variables.
+        The indices must be integers. Both ``^`` and ``**`` are accepted for
+        powers.
+    output_power_operator:
+        Power operator used in the returned string. The default is ``^`` to
+        match the input convention.
+    verify:
+        Whether to run randomized substitution checks before returning.
+    verification_trials:
+        Number of randomized substitution checks to run when ``verify`` is
+        true.
+    random_seed:
+        Optional seed for reproducible verification assignments.
+
+    Returns
+    -------
+    str
+        A string in the form ``C[x, y, z]*(polynomial in A) + ...``. If the
+        expression contains terms without any ``C`` factor, they are kept as a
+        final polynomial in ``A``.
+    """
+
+    if output_power_operator not in {"^", "**"}:
+        raise ValueError("output_power_operator must be '^' or '**'.")
+
+    parsed = _parse_polynomial(expression)
+    terms = _collect_terms(parsed)
+    result = _format_terms(terms, output_power_operator)
+    if verify:
+        verify_simplification(
+            expression,
+            result,
+            trials=verification_trials,
+            random_seed=random_seed,
+        )
+    return result
+
+
+def organize_polynomial_expr(
+    expression: str,
+    *,
+    verify: bool = True,
+    verification_trials: int = 5,
+    random_seed: Optional[int] = None,
+) -> sp.Expr:
+    """Return the collected result as a SymPy expression.
+
+    This is useful when callers want to continue symbolic computation after
+    collection. The string API is usually more convenient for display because
+    it preserves the ``C[x, y, z]`` notation.
+    """
+
+    parsed = _parse_polynomial(expression)
+    terms = _collect_terms(parsed)
+    result = _terms_to_expr(terms)
+    if verify:
+        _verify_parsed_against_expr(
+            parsed,
+            result,
+            trials=verification_trials,
+            random_seed=random_seed,
+        )
+    return result
+
+
+def verify_simplification(
+    original_expression: str,
+    simplified_expression: str,
+    *,
+    trials: int = 5,
+    random_seed: Optional[int] = None,
+) -> bool:
+    """Verify two expressions by randomized exact substitutions.
+
+    The function assigns the same random non-zero rational values to ``A`` and
+    every indexed ``C[x, y, z]`` appearing on either side, then checks that the
+    two expressions evaluate to the same value. It returns ``True`` when all
+    trials pass and raises ``PolynomialVerificationError`` on the first
+    mismatch.
+    """
+
+    original = _parse_polynomial(original_expression)
+    simplified = _parse_polynomial(simplified_expression)
+    _verify_parsed_pair(
+        original,
+        simplified,
+        trials=trials,
+        random_seed=random_seed,
+    )
+    return True
+
+
+def _terms_to_expr(terms: list[_CollectedTerm]) -> sp.Expr:
+    c_base = sp.IndexedBase("C")
+    expr_terms: list[sp.Expr] = []
+    for term in terms:
+        if not term.c_powers:
+            expr_terms.append(term.coefficient)
+            continue
+
+        c_factor = _c_factor_expr(term.c_powers, c_base)
+        expr_terms.append(sp.Mul(c_factor, term.coefficient, evaluate=False))
+
+    if not expr_terms:
+        return sp.Integer(0)
+    return sp.Add(*expr_terms, evaluate=False)
+
+
+def _verify_parsed_against_expr(
+    original: _ParsedPolynomial,
+    simplified_expr: sp.Expr,
+    *,
+    trials: int,
+    random_seed: Optional[int],
+) -> None:
+    simplified = _parse_polynomial(_sympy_expr_to_c_string(simplified_expr))
+    _verify_parsed_pair(
+        original,
+        simplified,
+        trials=trials,
+        random_seed=random_seed,
+    )
+
+
+def _verify_parsed_pair(
+    original: _ParsedPolynomial,
+    simplified: _ParsedPolynomial,
+    *,
+    trials: int,
+    random_seed: Optional[int],
+) -> None:
+    if not isinstance(trials, int) or trials < 1:
+        raise ValueError("trials must be a positive integer.")
+
+    rng = Random(random_seed)
+    c_indices = set(original.c_symbols.values()) | set(simplified.c_symbols.values())
+
+    for trial in range(1, trials + 1):
+        a_value = _random_nonzero_rational(rng)
+        c_values = {
+            index: _random_nonzero_rational(rng)
+            for index in c_indices
+        }
+
+        original_value = _evaluate_parsed(original, a_value, c_values)
+        simplified_value = _evaluate_parsed(simplified, a_value, c_values)
+        difference = sp.simplify(original_value - simplified_value)
+        if _is_zero(difference):
+            continue
+
+        assignments = _format_assignments(a_value, c_values)
+        raise PolynomialVerificationError(
+            "verification failed on trial "
+            f"{trial}: original={original_value}, simplified={simplified_value}, "
+            f"assignments={assignments}"
+        )
+
+
+def _evaluate_parsed(
+    parsed: _ParsedPolynomial,
+    a_value: sp.Rational,
+    c_values: dict[Index, sp.Rational],
+) -> sp.Expr:
+    substitutions: dict[sp.Symbol, sp.Rational] = {parsed.a_symbol: a_value}
+    substitutions.update(
+        {
+            symbol: c_values[index]
+            for symbol, index in parsed.c_symbols.items()
+        }
+    )
+    return sp.cancel(parsed.expr.subs(substitutions))
+
+
+def _random_nonzero_rational(rng: Random) -> sp.Rational:
+    numerator = rng.choice([-9, -8, -7, -5, -4, -3, -2, -1, 1, 2, 3, 4, 5, 7, 8, 9])
+    denominator = rng.choice([1, 2, 3, 5, 7])
+    return sp.Rational(numerator, denominator)
+
+
+def _is_zero(value: sp.Expr) -> bool:
+    if value == 0:
+        return True
+    if value.is_number:
+        return abs(complex(sp.N(value))) < 1e-10
+    return False
+
+
+def _format_assignments(
+    a_value: sp.Rational,
+    c_values: dict[Index, sp.Rational],
+) -> str:
+    parts = [f"A={a_value}"]
+    parts.extend(
+        f"C[{index[0]}, {index[1]}, {index[2]}]={value}"
+        for index, value in sorted(c_values.items())
+    )
+    return ", ".join(parts)
+
+
+def _sympy_expr_to_c_string(expr: sp.Expr) -> str:
+    return sp.sstr(expr)
+
+
+def _parse_polynomial(expression: str) -> _ParsedPolynomial:
+    if not isinstance(expression, str) or not expression.strip():
+        raise PolynomialParseError("expression must be a non-empty string.")
+
+    index_to_token: dict[Index, str] = {}
+    token_to_index: dict[str, Index] = {}
+
+    def replace_c(match: re.Match[str]) -> str:
+        index = (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+        token = index_to_token.get(index)
+        if token is None:
+            token = f"{_TOKEN_PREFIX}{len(index_to_token)}"
+            index_to_token[index] = token
+            token_to_index[token] = index
+        return f" {token} "
+
+    rewritten = _C_PATTERN.sub(replace_c, expression)
+    a_symbol = sp.Symbol("A")
+    token_symbols = {token: sp.Symbol(token) for token in token_to_index}
+    local_dict = {"A": a_symbol, **token_symbols}
+
+    try:
+        parsed = parse_expr(
+            rewritten,
+            local_dict=local_dict,
+            global_dict=dict(_SAFE_GLOBALS),
+            transformations=_TRANSFORMATIONS,
+            evaluate=True,
+        )
+    except Exception as exc:
+        raise PolynomialParseError(f"could not parse expression: {expression!r}") from exc
+
+    allowed_symbols = {a_symbol, *token_symbols.values()}
+    unknown_symbols = sorted(
+        str(symbol) for symbol in parsed.free_symbols if symbol not in allowed_symbols
+    )
+    if unknown_symbols:
+        names = ", ".join(unknown_symbols)
+        raise PolynomialParseError(f"unsupported symbol(s): {names}")
+
+    c_symbols = {
+        token_symbols[token]: index
+        for token, index in token_to_index.items()
+    }
+    return _ParsedPolynomial(parsed, a_symbol, c_symbols)
+
+
+def _collect_terms(parsed: _ParsedPolynomial) -> list[_CollectedTerm]:
+    expr = sp.expand(parsed.expr)
+    c_items = sorted(parsed.c_symbols.items(), key=lambda item: item[1])
+
+    collected: dict[tuple[tuple[Index, int], ...], sp.Expr] = {}
+    for term in sp.Add.make_args(expr):
+        c_powers, coefficient = _split_c_factor(term, c_items)
+        collected[c_powers] = collected.get(c_powers, sp.Integer(0)) + coefficient
+
+    terms: list[_CollectedTerm] = []
+    for c_powers, coefficient in collected.items():
+        normalized = _normalize_a_polynomial(coefficient, parsed.a_symbol)
+        if normalized == 0:
+            continue
+        terms.append(_CollectedTerm(c_powers, normalized))
+
+    return sorted(terms, key=_term_sort_key)
+
+
+def _split_c_factor(
+    term: sp.Expr,
+    c_items: list[tuple[sp.Symbol, Index]],
+) -> tuple[tuple[tuple[Index, int], ...], sp.Expr]:
+    powers = term.as_powers_dict()
+    coefficient = term
+    c_powers: list[tuple[Index, int]] = []
+
+    for symbol, index in c_items:
+        power = powers.get(symbol, sp.Integer(0))
+        if power == 0:
+            continue
+
+        int_power = _as_integer_power(
+            power,
+            "expression must be a Laurent polynomial in the indexed C terms.",
+        )
+        coefficient /= symbol ** int_power
+        c_powers.append((index, int_power))
+
+    coefficient = sp.cancel(coefficient)
+    if any(coefficient.has(symbol) for symbol, _index in c_items):
+        raise PolynomialParseError(
+            "expression must be a Laurent polynomial in the indexed C terms."
+        )
+
+    return tuple(c_powers), coefficient
+
+
+def _normalize_a_polynomial(coefficient: sp.Expr, a_symbol: sp.Symbol) -> sp.Expr:
+    expanded = sp.expand(coefficient)
+    for term in sp.Add.make_args(expanded):
+        power = term.as_powers_dict().get(a_symbol, sp.Integer(0))
+        if power == 0:
+            a_free_part = term
+        else:
+            int_power = _as_integer_power(
+                power,
+                "coefficients must be Laurent polynomials in A.",
+            )
+            a_free_part = sp.cancel(term / (a_symbol ** int_power))
+
+        if a_free_part.has(a_symbol):
+            raise PolynomialParseError("coefficients must be Laurent polynomials in A.")
+
+    return sp.collect(expanded, a_symbol)
+
+
+def _as_integer_power(power: sp.Expr, error_message: str) -> int:
+    if power.is_integer is not True:
+        raise PolynomialParseError(error_message)
+    return int(power)
+
+
+def _term_sort_key(term: _CollectedTerm) -> tuple[int, tuple[tuple[Index, int], ...]]:
+    return (1, ()) if not term.c_powers else (0, term.c_powers)
+
+
+def _format_terms(terms: list[_CollectedTerm], power_operator: PowerOperator) -> str:
+    if not terms:
+        return "0"
+
+    chunks: list[str] = []
+    for term in terms:
+        coefficient = term.coefficient
+
+        if term.c_powers:
+            body = (
+                f"{_format_c_factor(term.c_powers, power_operator)}"
+                f"*({_format_expr(coefficient, power_operator)})"
+            )
+            chunks.append(body if not chunks else f" + {body}")
+            continue
+
+        is_negative = coefficient.could_extract_minus_sign()
+        displayed_coefficient = -coefficient if is_negative else coefficient
+        body = _format_expr(displayed_coefficient, power_operator)
+
+        if not chunks:
+            chunks.append(f"-{body}" if is_negative else body)
+        else:
+            chunks.append(f" - {body}" if is_negative else f" + {body}")
+
+    return "".join(chunks)
+
+
+def _format_expr(expr: sp.Expr, power_operator: PowerOperator) -> str:
+    a_symbol = sp.Symbol("A")
+    terms = [
+        _split_a_term(term, a_symbol)
+        for term in sp.Add.make_args(sp.expand(expr))
+    ]
+    terms.sort(key=lambda item: item[0], reverse=True)
+
+    chunks: list[str] = []
+    for power, coefficient in terms:
+        is_negative = coefficient.could_extract_minus_sign()
+        displayed_coefficient = -coefficient if is_negative else coefficient
+        body = _format_a_term(displayed_coefficient, power, power_operator)
+
+        if not chunks:
+            chunks.append(f"-{body}" if is_negative else body)
+        else:
+            chunks.append(f" - {body}" if is_negative else f" + {body}")
+
+    return "".join(chunks)
+
+
+def _split_a_term(term: sp.Expr, a_symbol: sp.Symbol) -> tuple[int, sp.Expr]:
+    power = term.as_powers_dict().get(a_symbol, sp.Integer(0))
+    int_power = _as_integer_power(power, "coefficients must be Laurent polynomials in A.")
+    coefficient = sp.cancel(term / (a_symbol ** int_power))
+    return int_power, coefficient
+
+
+def _format_a_term(
+    coefficient: sp.Expr,
+    power: int,
+    power_operator: PowerOperator,
+) -> str:
+    if power == 0:
+        return _format_number(coefficient, power_operator)
+
+    power_text = _format_a_power(power, power_operator)
+    if coefficient == 1:
+        return power_text
+
+    return f"{_format_number(coefficient, power_operator)}*{power_text}"
+
+
+def _format_a_power(power: int, power_operator: PowerOperator) -> str:
+    if power == 1:
+        return "A"
+    if power < 0:
+        return f"A{power_operator}({power})"
+    return f"A{power_operator}{power}"
+
+
+def _format_number(number: sp.Expr, power_operator: PowerOperator) -> str:
+    text = sp.sstr(number)
+    if power_operator == "^":
+        return text.replace("**", "^")
+    return text
+
+
+def _format_c_factor(
+    c_powers: tuple[tuple[Index, int], ...],
+    power_operator: PowerOperator,
+) -> str:
+    factors: list[str] = []
+    for index, power in c_powers:
+        factor = _format_indexed_c(index)
+        if power != 1:
+            factor = f"{factor}{power_operator}{power}"
+        factors.append(factor)
+    return "*".join(factors)
+
+
+def _format_indexed_c(index: Index) -> str:
+    x, y, z = index
+    return f"C[{x}, {y}, {z}]"
+
+
+def _c_factor_expr(
+    c_powers: tuple[tuple[Index, int], ...],
+    c_base: sp.IndexedBase,
+) -> sp.Expr:
+    factors: list[sp.Expr] = []
+    for (x, y, z), power in c_powers:
+        indexed = c_base[x, y, z]
+        factors.append(indexed if power == 1 else sp.Pow(indexed, power))
+    return sp.Mul(*factors)

homlab_polynomial-0.1.0/src/homlab_polynomial.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: homlab-polynomial
+Version: 0.1.0
+Summary: Collect indexed C terms in polynomials with SymPy.
+Author: GGN_2015
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy>=1.10
+Dynamic: license-file
+
+# homlab_polynomial
+
+`homlab_polynomial` 提供一个 Python 编程入口，用 SymPy 将包含普通变量 `A` 和三下标变量
+`C[x, y, z]` 的字符串表达式整理成按不同 `C[x, y, z]` 分组的形式。
+
+## 安装
+
+```bash
+pip install .
+```
+
+## 使用
+
+```python
+from homlab_polynomial import organize_polynomial
+
+expr = "A*C[1, 2, 3] + 2*C[1,2,3] + A^2*C[0,0,0]"
+print(organize_polynomial(expr))
+```
+
+输出：
+
+```text
+C[0, 0, 0]*(A^2) + C[1, 2, 3]*(A + 2)
+```
+
+负指数也支持：
+
+```python
+organize_polynomial("A^-10*C[0,0,0] + 2*C[0,0,0]/A")
+```
+
+输出：
+
+```text
+C[0, 0, 0]*(2*A^(-1) + A^(-10))
+```
+
+说明：
+
+- `C[x, y, z]` 的三个下标必须是整数，可以为负数。
+- 输入支持用 `^` 表示指数运算，也支持 Python/SymPy 风格的 `**`。
+- 默认输出也使用 `^`。如果需要 `**`，可以传入 `output_power_operator="**"`。
+- 系数支持有限 Laurent 多项式，因此 `A^-1`、`1/A`、`A^-10` 都可以使用。
+- `C[x, y, z]` 项不会带外部负号；负号会保留在括号中的系数多项式里。
+- 不含 `C` 的纯 `A` 项会作为最后的余项保留。
+
+如果需要继续做 SymPy 计算，可以使用：
+
+```python
+from homlab_polynomial import organize_polynomial_expr
+
+sympy_expr = organize_polynomial_expr("A*C[1,2,3] + C[1,2,3]")
+```
+
+## 验算
+
+`organize_polynomial()` 默认会在每次整理后进行随机代入验算。它会给 `A` 和所有出现过的
+`C[x, y, z]` 赋非零有理数，检查整理前后的表达式是否一致。
+
+也可以直接调用验算函数：
+
+```python
+from homlab_polynomial import verify_simplification
+
+verify_simplification(
+    "A*C[1,2,3] + C[1,2,3]",
+    "C[1, 2, 3]*(A + 1)",
+)
+```

homlab_polynomial-0.1.0/src/homlab_polynomial.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/homlab_polynomial/__init__.py
+src/homlab_polynomial/core.py
+src/homlab_polynomial.egg-info/PKG-INFO
+src/homlab_polynomial.egg-info/SOURCES.txt
+src/homlab_polynomial.egg-info/dependency_links.txt
+src/homlab_polynomial.egg-info/requires.txt
+src/homlab_polynomial.egg-info/top_level.txt
+tests/test_core.py

homlab_polynomial-0.1.0/src/homlab_polynomial.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

homlab_polynomial-0.1.0/src/homlab_polynomial.egg-info/requires.txt

@@ -0,0 +1 @@
+sympy>=1.10

homlab_polynomial-0.1.0/src/homlab_polynomial.egg-info/top_level.txt

@@ -0,0 +1 @@
+homlab_polynomial

homlab_polynomial-0.1.0/tests/test_core.py

@@ -0,0 +1,103 @@
+import unittest
+
+import sympy as sp
+
+from homlab_polynomial import (
+    PolynomialParseError,
+    PolynomialVerificationError,
+    organize_polynomial,
+    organize_polynomial_expr,
+    verify_simplification,
+)
+
+
+class OrganizePolynomialTests(unittest.TestCase):
+    def test_collects_same_indexed_c_terms(self):
+        result = organize_polynomial(
+            "A*C[1, 2, 3] + 2*C[1,2,3] + A^2*C[0,0,0]"
+        )
+
+        self.assertEqual(
+            result,
+            "C[0, 0, 0]*(A^2) + C[1, 2, 3]*(A + 2)",
+        )
+
+    def test_supports_negative_indices_and_negative_coefficients(self):
+        result = organize_polynomial(
+            "C[-1,0,+2]*A^2 + 3*A*C[-1,0,2] - C[3,-4,5]"
+        )
+
+        self.assertEqual(
+            result,
+            "C[-1, 0, 2]*(A^2 + 3*A) + C[3, -4, 5]*(-1)",
+        )
+
+    def test_keeps_negative_sign_inside_c_coefficient(self):
+        result = organize_polynomial("-A*C[-2,0,1] - C[-2,0,1]")
+
+        self.assertEqual(result, "C[-2, 0, 1]*(-A - 1)")
+
+    def test_keeps_terms_without_c_as_remainder(self):
+        result = organize_polynomial("A^2 + C[0,0,0]*A + 1")
+
+        self.assertEqual(result, "C[0, 0, 0]*(A) + A^2 + 1")
+
+    def test_accepts_implicit_multiplication(self):
+        result = organize_polynomial("2C[1, 2, 3] A + C[1,2,3]")
+
+        self.assertEqual(result, "C[1, 2, 3]*(2*A + 1)")
+
+    def test_can_return_sympy_expression(self):
+        result = organize_polynomial_expr("A*C[1,2,3] + C[1,2,3]")
+        a = sp.Symbol("A")
+        c = sp.IndexedBase("C")
+
+        self.assertEqual(sp.expand(result - (a + 1) * c[1, 2, 3]), 0)
+
+    def test_verifies_equivalent_simplification(self):
+        self.assertTrue(
+            verify_simplification(
+                "A*C[1,2,3] + C[1,2,3]",
+                "C[1, 2, 3]*(A + 1)",
+                random_seed=123,
+            )
+        )
+
+    def test_verification_rejects_mismatch(self):
+        with self.assertRaises(PolynomialVerificationError):
+            verify_simplification(
+                "A*C[1,2,3] + C[1,2,3]",
+                "C[1, 2, 3]*(A + 2)",
+                random_seed=123,
+            )
+
+    def test_supports_negative_powers_of_a(self):
+        result = organize_polynomial("A^-10*C[0,0,0] + 2*C[0,0,0]/A")
+
+        self.assertEqual(result, "C[0, 0, 0]*(2*A^(-1) + A^(-10))")
+
+    def test_formats_one_over_a_as_negative_power(self):
+        result = organize_polynomial("C[0,0,0]/A")
+
+        self.assertEqual(result, "C[0, 0, 0]*(A^(-1))")
+
+    def test_supports_negative_powers_of_c(self):
+        result = organize_polynomial("A*C[0,0,0]^-1 + 2*C[0,0,0]^-1")
+
+        self.assertEqual(result, "C[0, 0, 0]^-1*(A + 2)")
+
+    def test_rejects_unknown_symbols(self):
+        with self.assertRaises(PolynomialParseError):
+            organize_polynomial("B*C[0,0,0]")
+
+    def test_rejects_non_laurent_coefficients(self):
+        with self.assertRaises(PolynomialParseError):
+            organize_polynomial("C[0,0,0]/(A + 1)")
+
+    def test_rejects_non_laurent_c_terms(self):
+        with self.assertRaises(PolynomialParseError):
+            organize_polynomial("A/(C[0,0,0] + 1)")
+
+
+if __name__ == "__main__":
+    unittest.main()