eqsys 0.1.0__py3-none-any.whl

eqsys/__init__.py

@@ -0,0 +1,7 @@
+"""eqsys — Nonlinear equation system solver."""
+
+from eqsys.status import SolveStatus, ValidationStatus
+from eqsys.system import EquationSystem
+from eqsys.var import Var
+
+__all__ = ["EquationSystem", "Var", "SolveStatus", "ValidationStatus"]

eqsys/diagnostics.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+@dataclass
+class IterationInfo:
+    iteration: int
+    norm: float
+    values: dict[str, float]
+    residuals: dict[str, float]
+
+
+@dataclass
+class SolverControl:
+    stop: bool = False
+
+
+class DiagnosticsData:
+    def __init__(self):
+        self.reset()
+
+    def reset(self):
+        self.converged = False
+        self.residual_history: list[float] = []
+        self._residuals_per_eq: list[dict[str, float]] = []
+        self._values_per_iter: list[dict[str, float]] = []
+
+    @property
+    def iterations(self) -> int:
+        return len(self.residual_history)
+
+    @property
+    def final_norm(self) -> float:
+        if not self.residual_history:
+            return 0.0
+        return self.residual_history[-1]
+
+    def record_iteration(
+        self,
+        norm: float,
+        residuals: dict[str, float],
+        values: dict[str, float],
+    ):
+        self.residual_history.append(norm)
+        self._residuals_per_eq.append(dict(residuals))
+        self._values_per_iter.append(dict(values))
+
+    def worst_equations(self) -> list[tuple[str, float]]:
+        if not self._residuals_per_eq:
+            return []
+        last = self._residuals_per_eq[-1]
+        return sorted(last.items(), key=lambda x: abs(x[1]), reverse=True)
+
+    def variable_history(self, var_name: str) -> list[float]:
+        if self._values_per_iter and var_name not in self._values_per_iter[0]:
+            raise KeyError(f'Variable "{var_name}" not found in diagnostics history')
+        return [v[var_name] for v in self._values_per_iter]

eqsys/jacobian.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy.sparse import coo_matrix
+from eqsys.var import Var
+
+
+def compute_jacobian(
+    equations: list[tuple[str, callable]],
+    variables: list[Var],
+    deps: dict[str, set[str]],
+    residuals: np.ndarray,
+) -> coo_matrix:
+    var_index = {v.name: j for j, v in enumerate(variables)}
+    rows = []
+    cols = []
+    data = []
+
+    for i, (eq_name, eq_func) in enumerate(equations):
+        eq_deps = deps.get(eq_name, set())
+        for var_name in eq_deps:
+            j = var_index[var_name]
+            var = variables[j]
+
+            original = var.value
+            var.value = original + var.deriv_step
+            f_perturbed = eq_func()
+            var.value = original
+
+            dfdx = (f_perturbed - residuals[i]) / var.deriv_step
+            rows.append(i)
+            cols.append(j)
+            data.append(dfdx)
+
+    n_eq = len(equations)
+    n_var = len(variables)
+    return coo_matrix((data, (rows, cols)), shape=(n_eq, n_var)).tocsc()

eqsys/solver.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+from scipy.sparse.linalg import spsolve
+
+from eqsys.diagnostics import DiagnosticsData, IterationInfo, SolverControl
+from eqsys.jacobian import compute_jacobian
+from eqsys.status import SolveStatus
+from eqsys.var import Var
+
+
+def newton_raphson(
+    eval_fn: Callable,
+    equations: list[tuple[str, Callable]],
+    variables: list[Var],
+    diagnostics: DiagnosticsData,
+    tol: float = 1e-8,
+    max_iter: int = 100,
+    on_iteration: Callable[[IterationInfo, SolverControl], None] | None = None,
+) -> SolveStatus:
+    diagnostics.reset()
+
+    for iteration in range(max_iter):
+        try:
+            F, deps = eval_fn()
+        except Exception:
+            return SolveStatus.ERROR
+
+        norm = float(np.linalg.norm(F))
+        converged = norm < tol
+
+        residuals_dict = {
+            eq_name: float(F[i]) for i, (eq_name, _) in enumerate(equations)
+        }
+        values_dict = {v.name: v.value for v in variables}
+        diagnostics.record_iteration(
+            norm=norm, residuals=residuals_dict, values=values_dict
+        )
+
+        if on_iteration is not None:
+            info = IterationInfo(
+                iteration=iteration,
+                norm=norm,
+                values=dict(values_dict),
+                residuals=dict(residuals_dict),
+            )
+            control = SolverControl()
+            on_iteration(info, control)
+            if control.stop:
+                return SolveStatus.NOT_CONVERGED
+
+        if converged:
+            diagnostics.converged = True
+            return SolveStatus.CONVERGED
+
+        try:
+            J = compute_jacobian(equations, variables, deps, F)
+            dx = spsolve(J, -F)
+        except Exception:
+            return SolveStatus.ERROR
+
+        for k, var in enumerate(variables):
+            step = float(dx[k])
+            step = max(-var.max_step, min(var.max_step, step))
+            new_val = var.value + step
+            new_val = max(var.min_value, min(var.max_value, new_val))
+            var.value = new_val
+
+    return SolveStatus.NOT_CONVERGED

eqsys/status.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class SolveStatus(Enum):
+    CONVERGED = "converged"
+    NOT_CONVERGED = "not_converged"
+    ERROR = "error"
+
+
+class ValidationStatus(Enum):
+    VALID = "valid"
+    INVALID = "invalid"
+    WARNING = "warning"

eqsys/system.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import copy
+from typing import Callable
+
+from eqsys.diagnostics import DiagnosticsData, IterationInfo, SolverControl
+from eqsys.solver import newton_raphson
+from eqsys.status import SolveStatus, ValidationStatus
+from eqsys.tracker import DependencyTracker
+from eqsys.validator import ValidationIssue, validate_system
+from eqsys.var import Var
+
+import numpy as np
+
+
+class EquationSystem:
+    def __init__(self, name: str):
+        self.name = name
+        self._variables: list[Var] = []
+        self._equations: list[tuple[str, Callable]] = []
+        self._tracker = DependencyTracker()
+        self._diagnostics = DiagnosticsData()
+        self._validation_issues: list[ValidationIssue] = []
+
+    def __repr__(self) -> str:
+        return (
+            f'EquationSystem("{self.name}", '
+            f"vars={len(self._variables)}, eqs={len(self._equations)})"
+        )
+
+    def var(
+        self,
+        name: str,
+        guess: float,
+        min_value: float = -1e15,
+        max_value: float = 1e15,
+        max_step: float = 1e10,
+        deriv_step: float = 1e-8,
+    ) -> Var:
+        v = Var(
+            name=name,
+            guess=guess,
+            system=self,
+            min_value=min_value,
+            max_value=max_value,
+            max_step=max_step,
+            deriv_step=deriv_step,
+        )
+        self._variables.append(v)
+        return v
+
+    def add_equation(self, name: str, func: Callable) -> None:
+        self._equations.append((name, func))
+
+    def _run_equation(self, eq_func: Callable) -> tuple[object, set[str]]:
+        self._tracker.start()
+        try:
+            result = eq_func()
+        except Exception:
+            self._tracker.stop()
+            raise
+        deps = self._tracker.stop()
+        return result, deps
+
+    def validate(self) -> ValidationStatus:
+        status, self._validation_issues = validate_system(
+            self._variables, self._equations, self._run_equation
+        )
+        return status
+
+    def validation_details(self) -> list[ValidationIssue]:
+        return list(self._validation_issues)
+
+    def solve(
+        self,
+        tol: float = 1e-8,
+        max_iter: int = 100,
+        on_iteration: Callable[[IterationInfo, SolverControl], None] | None = None,
+    ) -> SolveStatus:
+        def eval_fn():
+            residuals = []
+            deps = {}
+            for eq_name, eq_func in self._equations:
+                self._tracker.start()
+                try:
+                    r = eq_func()
+                finally:
+                    eq_deps = self._tracker.stop()
+                residuals.append(r)
+                deps[eq_name] = eq_deps
+            return np.array(residuals, dtype=float), deps
+
+        return newton_raphson(
+            eval_fn=eval_fn,
+            equations=self._equations,
+            variables=self._variables,
+            diagnostics=self._diagnostics,
+            tol=tol,
+            max_iter=max_iter,
+            on_iteration=on_iteration,
+        )
+
+    def diagnostics(self) -> DiagnosticsData:
+        return copy.deepcopy(self._diagnostics)

eqsys/tracker.py

@@ -0,0 +1,16 @@
+class DependencyTracker:
+    def __init__(self):
+        self.active = False
+        self._deps: set[str] = set()
+
+    def start(self):
+        self._deps = set()
+        self.active = True
+
+    def stop(self) -> set[str]:
+        self.active = False
+        return self._deps
+
+    def register(self, var_name: str):
+        if self.active:
+            self._deps.add(var_name)

eqsys/validator.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from collections import Counter
+from typing import Callable
+
+from eqsys.status import ValidationStatus
+from eqsys.var import Var
+
+
+@dataclass
+class ValidationIssue:
+    level: str  # "error" or "warning"
+    message: str
+
+
+def validate_system(
+    variables: list[Var],
+    equations: list[tuple[str, Callable]],
+    run_equation: Callable[[Callable], tuple[object, set[str]]],
+) -> tuple[ValidationStatus, list[ValidationIssue]]:
+    issues: list[ValidationIssue] = []
+
+    # Empty system is valid
+    if not variables and not equations:
+        return ValidationStatus.VALID, issues
+
+    # Duplicate variable names
+    var_names = [v.name for v in variables]
+    var_counts = Counter(var_names)
+    for name, count in var_counts.items():
+        if count > 1:
+            issues.append(ValidationIssue(
+                "error", f'Duplicate variable name "{name}" ({count} times)'))
+
+    # Duplicate equation names
+    eq_names = [name for name, _ in equations]
+    eq_counts = Counter(eq_names)
+    for name, count in eq_counts.items():
+        if count > 1:
+            issues.append(ValidationIssue(
+                "error", f'Duplicate equation name "{name}" ({count} times)'))
+
+    # Dimension check
+    if len(equations) != len(variables):
+        issues.append(ValidationIssue(
+            "error",
+            f"System has {len(equations)} equations but {len(variables)} variables"))
+
+    # Guess bounds check
+    for var in variables:
+        if var.value < var.min_value or var.value > var.max_value:
+            issues.append(ValidationIssue(
+                "error",
+                f'Variable "{var.name}" guess {var.value} is outside '
+                f'bounds [{var.min_value}, {var.max_value}]'))
+
+    # Trial run — call each equation via run_equation, capture deps
+    all_used_vars: set[str] = set()
+    for eq_name, eq_func in equations:
+        try:
+            result, deps = run_equation(eq_func)
+        except Exception as e:
+            issues.append(ValidationIssue(
+                "error",
+                f'Equation "{eq_name}" raised {type(e).__name__}: {e}'))
+            continue
+
+        if not isinstance(result, (int, float)):
+            issues.append(ValidationIssue(
+                "error",
+                f'Equation "{eq_name}" returned {type(result).__name__}, expected numeric'))
+
+        if not deps:
+            issues.append(ValidationIssue(
+                "warning",
+                f'Equation "{eq_name}" does not read any variables'))
+
+        all_used_vars.update(deps)
+
+    # Variables not used by any equation
+    for var in variables:
+        if var.name not in all_used_vars:
+            issues.append(ValidationIssue(
+                "error",
+                f'Variable "{var.name}" is not used by any equation'))
+
+    # Determine status
+    has_errors = any(i.level == "error" for i in issues)
+    has_warnings = any(i.level == "warning" for i in issues)
+
+    if has_errors:
+        return ValidationStatus.INVALID, issues
+    if has_warnings:
+        return ValidationStatus.WARNING, issues
+    return ValidationStatus.VALID, issues

eqsys/var.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from eqsys.system import EquationSystem
+
+
+class Var:
+    def __init__(
+        self,
+        name: str,
+        guess: float,
+        system: EquationSystem | None,
+        min_value: float = -1e15,
+        max_value: float = 1e15,
+        max_step: float = 1e10,
+        deriv_step: float = 1e-8,
+    ):
+        self.name = name
+        self.value = float(guess)
+        self._system = system
+        self.min_value = min_value
+        self.max_value = max_value
+        self.max_step = max_step
+        self.deriv_step = deriv_step
+
+    def __repr__(self) -> str:
+        return f'Var("{self.name}", value={self.value})'
+
+    def __call__(self) -> float:
+        if self._system is not None and self._system._tracker.active:
+            self._system._tracker.register(self.name)
+        return self.value

eqsys-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: eqsys
+Version: 0.1.0
+Summary: Nonlinear equation system solver with automatic dependency tracking
+Requires-Python: >=3.11
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-benchmark; extra == 'dev'

eqsys-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+eqsys/__init__.py,sha256=PZtvsoxfGCafr9Bon6L42R_s4Br1N4sSqR3D3_AjeDw,244
+eqsys/diagnostics.py,sha256=9rnU5ci61SDYY953LtxUe6KeZLhbgKb3mZJNyXGQEis,1609
+eqsys/jacobian.py,sha256=TgI-Ck0eu23zsbjo67J_kWxVn89o_JAVAA6oa9Hcnfk,1017
+eqsys/solver.py,sha256=dyG2J6lBQrsIIOXP42DedmdWOhC7DVcStZqoGw6Uum0,2128
+eqsys/status.py,sha256=gx0wsan9d1coNpJE90S9t-2Q3qL0UDUU7tnUqTQiK3Y,233
+eqsys/system.py,sha256=xthQRwAhVqasZXPE0cg3ddArRhhNYonBfCYL51SxHtM,3110
+eqsys/tracker.py,sha256=eokqyLWLWU21vmSZPxKpvWHh92U_K-8fyke3laCrRTU,378
+eqsys/validator.py,sha256=r4UQjYtpRbjnShyWTG2890HQnoBZHF-7O8agpyisYwY,3164
+eqsys/var.py,sha256=Lh0_7tx-7iY8UC5myhll0c8wyvPf0jOYJQAfgHz41Ic,898
+eqsys-0.1.0.dist-info/METADATA,sha256=uIieW5trglQuvLFgXvAHjuTlcXvfayhRvrmRuU8aVQc,298
+eqsys-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+eqsys-0.1.0.dist-info/RECORD,,

eqsys-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any