pycodemath 0.2.0__py3-none-any.whl

pycodemath/core/errors.py

@@ -0,0 +1,15 @@
+"""Pycodemath exceptions — one lightweight, shared domain error type.
+
+Goal: the user/agent and the REPL get a readable Pycodemath message instead of
+a raw SymPy exception (``SympifyError``, ``TypeError`` from ``float``, etc.).
+"""
+
+from __future__ import annotations
+
+
+class PycodemathError(Exception):
+    """Pycodemath domain error (parsing, evaluation, generation).
+
+    Always carries a concise, readable message; the original exception is
+    attached via ``raise ... from exc`` for inspection while debugging.
+    """

pycodemath/core/ir.py

@@ -0,0 +1,307 @@
+"""Pycodemath IR — the shared expression tree (contract between the engine and the generator).
+
+The cornerstone of the project. Both module 1 (the math engine) and module 2
+(the code generator) operate on the same ``Expr`` object. It is a thin but
+proprietary layer over SymPy expressions: it gives us a concise API, a stable
+interface, and a place where we will later hook in the masking stage.
+
+The "token-cutting" goal: writing math should be short (``E("sin(x)*x")``),
+and expansion into code happens only in the generator.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Callable, Iterable
+
+import sympy as sp
+
+from .errors import PycodemathError
+
+
+@lru_cache(maxsize=512)
+def _lambdify_cached(sy: sp.Expr, syms: tuple) -> Callable:
+    """Compile (and memoize) a SymPy expression into a numeric function.
+
+    ``lambdify`` is code generation + exec — a single call costs ~ms, so
+    without a cache, methods called repeatedly on the same expression (loops,
+    tests, REPL) would pay for compilation every time. The key (expression,
+    symbols) is hashable, because SymPy expressions are immutable.
+    """
+    return sp.lambdify(syms, sy, modules=["math", "numpy"])
+
+
+class Expr:
+    """Wrapper around a SymPy expression with its own concise API.
+
+    We keep a ``sympy.Expr`` inside (``self.sy``). All mathematical operations
+    are delegated to SymPy, but the user/agent sees only the stable Pycodemath
+    interface.
+    """
+
+    __slots__ = ("sy",)
+
+    sy: "sp.Expr"
+
+    def __init__(self, expr: "sp.Expr | Expr | str | int | float"):
+        if isinstance(expr, Expr):
+            self.sy = expr.sy
+        else:
+            # str, int, float, sympy.Expr — a single entry point via sympify.
+            # Note: for ``str`` this is SymPy evaluation (the same surface as
+            # in the parser) — do not feed it untrusted text without being
+            # aware that sympify is NOT a sandbox.
+            self.sy = sp.sympify(expr)
+
+    # --- introspection --------------------------------------------------
+    @property
+    def free_symbols(self) -> tuple[sp.Symbol, ...]:
+        """Symbols (variables) occurring in the expression, in a stable order."""
+        return tuple(sorted(self.sy.free_symbols, key=lambda s: s.name))
+
+    def symbol_names(self) -> list[str]:
+        return [s.name for s in self.free_symbols]
+
+    # --- symbolic operations (delegated, but return Expr) ---------------
+    def simplify(self) -> "Expr":
+        return Expr(sp.simplify(self.sy))
+
+    def expand(self) -> "Expr":
+        return Expr(sp.expand(self.sy))
+
+    def diff(self, var: str) -> "Expr":
+        return Expr(sp.diff(self.sy, sp.Symbol(var)))
+
+    def integrate(self, var: str) -> "Expr":
+        res = sp.integrate(self.sy, sp.Symbol(var))
+        # An unevaluated Integral in the result is junk that breaks the contract
+        # (analogous to the res.has(sp.Sum) guard in summation) — we refuse
+        # clearly.
+        if res.has(sp.Integral):
+            raise PycodemathError(
+                "integrate: no closed form — compute numerically "
+                "or simplify the expression"
+            )
+        return Expr(res)
+
+    def subs(self, mapping: dict[str, "float | int | str"]) -> "Expr":
+        # String values go through the guarded parser (whitelist of tokens
+        # and names), NOT through bare sympify — otherwise subs would be a
+        # second sympify surface with the full namespace, bypassing the parser.
+        # Local import: frontend.parser imports core.ir (cycle).
+        from ..frontend.parser import parse
+
+        m = {
+            sp.Symbol(k): parse(v).sy if isinstance(v, str) else sp.sympify(v)
+            for k, v in mapping.items()
+        }
+        return Expr(self.sy.subs(m))
+
+    def evalf(self, **values: float) -> float:
+        """Numeric evaluation after substituting values for symbols."""
+        m = {sp.Symbol(k): v for k, v in values.items()}
+        result = self.sy.evalf(subs=m)
+        try:
+            return float(result)
+        except TypeError as exc:
+            # Complex or still-symbolic result — a readable error instead of a
+            # raw TypeError from ``float()``.
+            raise PycodemathError(
+                f"cannot return a real number from {result} "
+                f"(complex result or unsubstituted symbols)"
+            ) from exc
+
+    def compiled(self, vars: "Iterable[str]") -> Callable:
+        """Compile the expression into a fast numeric function (``lambdify``).
+
+        Numeric engine contract: compile ONCE before the loop, iterate without
+        SymPy overhead (``evalf`` remains the contract for a SINGLE evaluation).
+        ``math`` first — domain errors are a plain ``ValueError``, scalars are
+        fast; ``numpy`` as a fallback for functions that math lacks. The
+        returned function takes values positionally, in the order of ``vars``.
+        Compilations are cached (LRU) by the (expression, symbols) pair.
+        """
+        return _lambdify_cached(self.sy, tuple(sp.Symbol(v) for v in vars))
+
+    # --- serialization (concise, token-friendly) ------------------------
+    def to_source(self) -> str:
+        """Short, unambiguous text form — round-trips with the parser."""
+        return str(self.sy)
+
+    def equivalent(self, other: "Expr | str | int | float") -> bool:
+        """Mathematical equality: does ``self - other`` simplify to zero.
+
+        Slower than ``==`` (runs ``simplify``), but catches the equivalence of
+        expressions with different structure, e.g. ``(x+1)**2`` and
+        ``x**2 + 2*x + 1``. ``==`` remains a structural comparison, consistent
+        with ``__hash__``.
+        """
+        other = other if isinstance(other, Expr) else Expr(other)
+        return bool(sp.simplify(self.sy - other.sy) == 0)
+
+    def __eq__(self, other: object) -> bool:
+        # STRUCTURAL comparison (consistent with ``__hash__``) — fast and
+        # safe for set/dict. For mathematical equality: ``equivalent``.
+        if isinstance(other, Expr):
+            return bool(self.sy == other.sy)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self.sy)
+
+    def __repr__(self) -> str:
+        return f"Expr({self.sy!s})"
+
+    def __str__(self) -> str:
+        return str(self.sy)
+
+
+class Matrix:
+    """Wrapper around a SymPy matrix/vector — IR extension for linear algebra.
+
+    We keep a ``sympy.MatrixBase`` inside (``self.sy``). A vector is simply an
+    ``n × 1`` column matrix. The notation stays concise: ``M("[[1,2],[3,4]]")``,
+    ``V("[1,2,3]")`` — while the heavy operations are done by the engine
+    (``engine.linalg``).
+    """
+
+    __slots__ = ("sy",)
+
+    sy: "sp.MatrixBase"
+
+    def __init__(self, data: "sp.MatrixBase | Matrix | str | list | tuple"):
+        if isinstance(data, Matrix):
+            self.sy = data.sy
+        elif isinstance(data, sp.MatrixBase):
+            self.sy = data
+        elif isinstance(data, str):
+            self.sy = _parse_matrix(data)
+        else:
+            try:
+                self.sy = sp.Matrix(data)
+            except (ValueError, TypeError) as exc:
+                # e.g. rows of different lengths — a readable error instead of a
+                # raw ValueError from deep inside SymPy (contract: always PycodemathError)
+                raise PycodemathError(f"invalid matrix: {exc}") from exc
+
+    # --- introspection --------------------------------------------------
+    @property
+    def shape(self) -> tuple[int, int]:
+        return self.sy.shape
+
+    @property
+    def rows(self) -> int:
+        return self.sy.rows
+
+    @property
+    def cols(self) -> int:
+        return self.sy.cols
+
+    @property
+    def free_symbols(self) -> tuple[sp.Symbol, ...]:
+        return tuple(sorted(self.sy.free_symbols, key=lambda s: s.name))
+
+    def symbol_names(self) -> list[str]:
+        return [s.name for s in self.free_symbols]
+
+    def tolist(self) -> list[list]:
+        return self.sy.tolist()
+
+    # --- operations (delegated, but return IR) --------------------------
+    @property
+    def T(self) -> "Matrix":
+        """Transpose."""
+        return Matrix(self.sy.T)
+
+    def __matmul__(self, other: "Matrix") -> "Matrix":
+        return Matrix(self.sy * Matrix(other).sy)
+
+    def __mul__(self, other: "Matrix | int | float | Expr") -> "Matrix":
+        if isinstance(other, Matrix):
+            return Matrix(self.sy * other.sy)
+        if isinstance(other, Expr):
+            return Matrix(self.sy * other.sy)
+        return Matrix(self.sy * sp.sympify(other))
+
+    __rmul__ = __mul__
+
+    def __add__(self, other: "Matrix") -> "Matrix":
+        return Matrix(self.sy + Matrix(other).sy)
+
+    def __sub__(self, other: "Matrix") -> "Matrix":
+        return Matrix(self.sy - Matrix(other).sy)
+
+    def __getitem__(self, key):
+        return self.sy[key]
+
+    def __iter__(self):
+        return iter(self.sy)
+
+    # --- serialization / comparison -------------------------------------
+    def to_source(self) -> str:
+        """Concise literal form: ``[[1, 2], [3, 4]]`` (round-trips with ``M``)."""
+        return str(self.sy.tolist())
+
+    def equivalent(self, other: "Matrix | sp.MatrixBase | str | list") -> bool:
+        """MATHEMATICAL equality: does ``self - other`` simplify to zero.
+
+        Slower than ``==`` (runs ``simplify`` on the entries), but catches the
+        equivalence of matrices with differently structured entries. ``==``
+        remains a structural comparison, consistent with ``__hash__``
+        (analogous to ``Expr``).
+        """
+        other = other if isinstance(other, Matrix) else Matrix(other)
+        if self.sy.shape != other.sy.shape:
+            return False
+        diff = (self.sy - other.sy).applyfunc(sp.simplify)
+        return bool(diff.is_zero_matrix)
+
+    def __eq__(self, other: object) -> bool:
+        # STRUCTURAL comparison (consistent with ``__hash__``) — fast and safe
+        # for set/dict. For mathematical equality: ``equivalent``.
+        if isinstance(other, Matrix):
+            return bool(self.sy == other.sy)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        # A matrix is mutable, but we hash its immutable counterpart —
+        # "structurally equal → equal hash", as for ``Expr``.
+        return hash(sp.ImmutableMatrix(self.sy))
+
+    def __repr__(self) -> str:
+        return f"Matrix({self.sy.tolist()!r})"
+
+    def __str__(self) -> str:
+        return str(self.sy)
+
+
+def _parse_matrix(source: str) -> sp.MatrixBase:
+    """Parse a matrix/vector literal: ``[[1,2],[3,4]]`` or ``[1,2,3]``."""
+    try:
+        obj = sp.sympify(source)
+        return sp.Matrix(obj)
+    except (sp.SympifyError, ValueError, TypeError) as exc:
+        raise PycodemathError(f"cannot parse matrix {source!r}: {exc}") from exc
+
+
+def E(source: "str | sp.Expr | Expr | int | float") -> Expr:
+    """IR constructor shortcut: ``E("sin(x)*x")``."""
+    return Expr(source)
+
+
+def M(data: "sp.MatrixBase | Matrix | str | list | tuple") -> Matrix:
+    """IR matrix constructor shortcut: ``M("[[1,2],[3,4]]")``."""
+    return Matrix(data)
+
+
+def V(data: "sp.MatrixBase | Matrix | str | list | tuple") -> Matrix:
+    """IR vector constructor shortcut (column matrix): ``V("[1,2,3]")``."""
+    return Matrix(data)
+
+
+def symbols(names: "str | Iterable[str]") -> tuple[Expr, ...]:
+    """Create symbols as IR expressions: ``x, y = symbols("x y")``."""
+    syms = sp.symbols(names)
+    if not isinstance(syms, (tuple, list)):
+        syms = (syms,)
+    return tuple(Expr(s) for s in syms)

pycodemath/engine/linalg.py

@@ -0,0 +1,197 @@
+"""Linear algebra engine (module 3) — matrices and vectors on IR.
+
+Operates on ``Matrix`` from the IR core. By default it computes symbolically
+(SymPy — exact, rational results, with parameters), and when that is not
+possible (or when you explicitly ask for ``numeric=True``) — it falls back to
+a numeric NumPy path.
+
+Operations: multiplication, transpose, determinant, inverse, solving systems
+``A x = b``, and eigenvalues and eigenvectors.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import sympy as sp
+
+try:  # SymPy >= 1.13
+    from sympy.matrices.exceptions import MatrixError
+except ImportError:  # SymPy 1.12
+    from sympy.matrices.common import MatrixError
+
+from ..core.errors import PycodemathError
+from ..core.ir import Expr, Matrix
+
+# Exceptions after which we may drop to the numeric fallback: these are
+# signals that "SymPy cannot compute this symbolically" (singularity, wrong
+# shape, missing algorithm). Everything else (e.g. a programmer error) should
+# blow up loudly, not vanish into the fallback.
+_FALLBACK_ERRORS = (MatrixError, ValueError, TypeError, NotImplementedError)
+
+
+def _mat(x: "Matrix | sp.MatrixBase | str | list") -> Matrix:
+    return x if isinstance(x, Matrix) else Matrix(x)
+
+
+def _to_float(m: Matrix) -> np.ndarray:
+    """Cast an IR matrix to a ``float`` array (for the numeric path).
+
+    The numeric path requires concrete numbers — a matrix with parameters would
+    raise a raw ``TypeError`` from deep inside NumPy, so instead we raise a
+    readable error.
+    """
+    if m.sy.free_symbols:
+        names = ", ".join(sorted(s.name for s in m.sy.free_symbols))
+        raise PycodemathError(
+            f"the numeric path requires a matrix without symbols; parameters given: {names}"
+        )
+    return np.array(m.sy.tolist(), dtype=float)
+
+
+def _num_to_expr(v) -> Expr:
+    """Wrap a number (float/complex from NumPy) back into a scalar IR."""
+    v = complex(v)
+    if abs(v.imag) < 1e-12:
+        return Expr(sp.Float(v.real))
+    return Expr(sp.Float(v.real) + sp.Float(v.imag) * sp.I)
+
+
+def _numeric(fn, *args, **kwargs):
+    """Run an ``np.linalg`` operation, translating ``LinAlgError`` to the contract.
+
+    The numeric path on a singular/ill-conditioned matrix (or one whose
+    spectrum does not converge) raises a raw ``numpy.linalg.LinAlgError`` — in
+    English and outside the contract. We catch it and return a consistent
+    ``PycodemathError``, like the rest of the engine (cf. ``numerics`` with a
+    singular Jacobian).
+    """
+    try:
+        return fn(*args, **kwargs)
+    except np.linalg.LinAlgError as exc:
+        raise PycodemathError(
+            f"numeric linear algebra failed "
+            f"(singular or ill-conditioned matrix): {exc}"
+        ) from exc
+
+
+# --- basic operations --------------------------------------------------
+def multiply(a, b) -> Matrix:
+    """Matrix product ``A · B`` (also works for matrix × vector)."""
+    A, B = _mat(a), _mat(b)
+    # a mismatched shape used to raise a raw sympy.ShapeError outside the contract
+    if A.sy.cols != B.sy.rows:
+        raise PycodemathError(
+            f"multiply: incompatible dimensions {A.sy.rows}×{A.sy.cols} · "
+            f"{B.sy.rows}×{B.sy.cols} — the number of columns of A must equal "
+            f"the number of rows of B"
+        )
+    return Matrix(A.sy * B.sy)
+
+
+def transpose(a) -> Matrix:
+    """Transpose ``Aᵀ``."""
+    return Matrix(_mat(a).sy.T)
+
+
+def det(a, numeric: bool = False) -> Expr:
+    """Determinant ``det(A)`` (IR scalar). Symbolic, with a numeric fallback."""
+    A = _mat(a)
+    # a non-square matrix used to raise a raw NonSquareMatrixError, and after
+    # the numeric fallback — a misleading message about singularity
+    if A.sy.rows != A.sy.cols:
+        raise PycodemathError(
+            f"det: the matrix must be square, but its dimensions are "
+            f"{A.sy.rows}×{A.sy.cols}"
+        )
+    if not numeric:
+        try:
+            return Expr(A.sy.det())
+        except _FALLBACK_ERRORS:
+            pass
+    return _num_to_expr(_numeric(np.linalg.det, _to_float(A)))
+
+
+def inv(a, numeric: bool = False) -> Matrix:
+    """Inverse matrix ``A⁻¹``. Symbolic, with a numeric fallback."""
+    A = _mat(a)
+    if not numeric:
+        try:
+            return Matrix(A.sy.inv())
+        except _FALLBACK_ERRORS:
+            pass
+    return Matrix(sp.Matrix(_numeric(np.linalg.inv, _to_float(A))))
+
+
+# --- systems of equations ----------------------------------------------
+def solve_system(A, b, numeric: bool = False) -> Matrix:
+    """Solve the system ``A x = b`` and return the solution vector ``x``.
+
+    ``b`` may be a vector (column) or a list. For a square matrix — the exact
+    solution (``LUsolve`` / ``numpy.linalg.solve``). For an overdetermined
+    system (more equations than unknowns) — the least-squares solution
+    (``solve_least_squares`` / ``numpy.linalg.lstsq``). Symbolic, with a
+    numeric NumPy fallback.
+    """
+    A = _mat(A)
+    b = _mat(b)
+    # a mismatched number of rows used to produce, after the fallback, a
+    # misleading message about parameters/singularity instead of pointing to
+    # the wrong dimensions
+    if A.sy.rows != b.sy.rows:
+        raise PycodemathError(
+            f"solve_system: incompatible dimensions — A has {A.sy.rows} rows, "
+            f"but b has {b.sy.rows} elements"
+        )
+    square = A.sy.rows == A.sy.cols
+    if not numeric:
+        try:
+            if square:
+                return Matrix(A.sy.LUsolve(b.sy))
+            return Matrix(A.sy.solve_least_squares(b.sy))
+        except _FALLBACK_ERRORS:
+            pass
+    An = _to_float(A)
+    bn = _to_float(b).reshape(-1)
+    if square:
+        x = _numeric(np.linalg.solve, An, bn)
+    else:
+        x = _numeric(np.linalg.lstsq, An, bn, rcond=None)[0]
+    return Matrix(sp.Matrix(np.asarray(x).reshape(-1, 1)))
+
+
+# --- spectrum ----------------------------------------------------------
+def eigenvalues(a, numeric: bool = False) -> list[Expr]:
+    """Eigenvalues — a list of IR scalars (with multiplicities)."""
+    A = _mat(a)
+    if not numeric:
+        try:
+            out: list[Expr] = []
+            for val, mult in A.sy.eigenvals().items():
+                out.extend([Expr(val)] * int(mult))
+            return out
+        except _FALLBACK_ERRORS:
+            pass
+    return [_num_to_expr(v) for v in _numeric(np.linalg.eigvals, _to_float(A))]
+
+
+def eigenvectors(a, numeric: bool = False) -> list[tuple[Expr, Matrix]]:
+    """Eigenvectors — a list of pairs ``(eigenvalue, vector)``.
+
+    The symbolic path returns exact vectors (one per eigen-direction); the
+    numeric fallback — one normalized vector per value.
+    """
+    A = _mat(a)
+    if not numeric:
+        try:
+            out: list[tuple[Expr, Matrix]] = []
+            for val, _mult, vecs in A.sy.eigenvects():
+                for vec in vecs:
+                    out.append((Expr(val), Matrix(vec)))
+            return out
+        except _FALLBACK_ERRORS:
+            pass
+    w, vecs = _numeric(np.linalg.eig, _to_float(A))
+    return [
+        (_num_to_expr(w[i]), Matrix(sp.Matrix(vecs[:, i].reshape(-1, 1))))
+        for i in range(len(w))
+    ]