eqsys 0.1.0__tar.gz

eqsys-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.benchmarks/

eqsys-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# eqsys
+
+Nonlinear equation system solver with automatic dependency tracking.
+
+Write only residual functions in plain Python — the system handles variable tracking, sparse Jacobian computation, and Newton-Raphson iteration automatically.
+
+## Installation
+
+```bash
+pip install eqsys
+```
+
+## Quick Example
+
+```python
+import math
+from eqsys import EquationSystem
+
+sys = EquationSystem("pipe_flow")
+
+# Variables — name and initial guess are required
+P1   = sys.var("P1",   guess=101325.0)
+P2   = sys.var("P2",   guess=100000.0)
+flow = sys.var("flow", guess=1.0, min_value=0.0)
+
+# Constants
+D, L, rho, mu = 0.1, 5.0, 998.0, 1e-3
+
+# Equations — plain Python functions returning residuals
+def inlet_pressure():
+    return P1() - 101325.0
+
+def pipe_pressure_drop():
+    area = math.pi * D ** 2 / 4
+    v = flow() / (rho * area)
+    Re = rho * v * D / mu
+    f = 64 / Re if Re < 2300 else 0.02
+    dp = f * L / D * rho * v ** 2 / 2
+    return P2() - (P1() - dp)
+
+def outlet_pressure():
+    return P2() - 100000.0
+
+sys.add_equation("inlet_pressure", inlet_pressure)
+sys.add_equation("pipe_pressure_drop", pipe_pressure_drop)
+sys.add_equation("outlet_pressure", outlet_pressure)
+
+# Validate and solve
+sys.validate()
+status = sys.solve()
+
+print(f"P1 = {P1()}")    # 101325.0
+print(f"P2 = {P2()}")    # 100000.0
+print(f"flow = {flow()}")  # ~12.77
+```
+
+## Key Features
+
+- **Minimal API** — write residual functions, the system does the rest
+- **Automatic dependency tracking** — no need to declare which variables each equation uses
+- **Sparse Jacobian** — only computes non-zero partial derivatives
+- **Per-variable solver parameters** — bounds, max step, derivative step
+- **Strict validation** — catches dimension mismatches, unused variables, equation errors
+- **Convergence diagnostics** — residual history, worst equations, variable trajectories
+- **Real-time monitoring** — `on_iteration` callback with stop control
+- **Multiple systems** — variables from one system can be used as constants in another
+
+## API
+
+### Variables
+
+```python
+x = sys.var("x",
+    guess=1.0,           # required — initial value
+    min_value=-1e15,     # lower bound (default)
+    max_value=1e15,      # upper bound (default)
+    max_step=1e10,       # max change per iteration (default)
+    deriv_step=1e-8,     # finite difference step (default)
+)
+
+x()  # returns current float value (guess before solve, solution after)
+```
+
+### Equations
+
+```python
+sys.add_equation("name", func)  # func() -> float (residual)
+```
+
+Any Python code is allowed inside equations: `if/else`, `math.*`, loops, function calls.
+
+### Validation
+
+```python
+status = sys.validate()  # ValidationStatus.VALID / INVALID / WARNING
+details = sys.validation_details()  # list of ValidationIssue
+```
+
+Checks: dimension match, duplicate names, equation errors, unused variables, guess bounds.
+
+### Solving
+
+```python
+status = sys.solve(tol=1e-8, max_iter=100)  # SolveStatus.CONVERGED / NOT_CONVERGED / ERROR
+```
+
+No exceptions — check the returned status.
+
+### Diagnostics
+
+```python
+diag = sys.diagnostics()
+diag.iterations           # number of iterations
+diag.converged            # bool
+diag.residual_history     # [norm_0, norm_1, ...]
+diag.worst_equations()    # [("eq_name", residual), ...] sorted by |residual|
+diag.variable_history("x")  # [x_0, x_1, ...]
+```
+
+### Real-Time Monitoring
+
+```python
+def monitor(info, control):
+    print(f"Iter {info.iteration}: norm={info.norm:.2e}")
+    if info.iteration > 50:
+        control.stop = True  # abort solve
+
+sys.solve(on_iteration=monitor)
+```
+
+## Requirements
+
+- Python 3.11+
+- numpy
+- scipy
+
+## License
+
+MIT

eqsys-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "eqsys"
+version = "0.1.0"
+description = "Nonlinear equation system solver with automatic dependency tracking"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy",
+    "scipy",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-benchmark",
+]

eqsys-0.1.0/tests/test_benchmarks.py

@@ -0,0 +1,60 @@
+import pytest
+from eqsys import EquationSystem, SolveStatus
+
+
+def _build_linear_system(n: int) -> tuple[EquationSystem, list]:
+    """Build a system of n equations: x_i = i+1 for i in 0..n-1."""
+    sys = EquationSystem(f"bench_{n}")
+    variables = []
+    for i in range(n):
+        v = sys.var(f"x{i}", guess=0.0)
+        variables.append(v)
+
+    for i in range(n):
+        target = float(i + 1)
+        var = variables[i]
+
+        def make_eq(v=var, t=target):
+            def eq():
+                return v() - t
+            return eq
+
+        sys.add_equation(f"eq{i}", make_eq())
+
+    return sys, variables
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("n", [10, 100, 500, 1000])
+def test_benchmark_solve(benchmark, n):
+    """Benchmark solve time for N-equation linear system."""
+    sys, variables = _build_linear_system(n)
+
+    def run():
+        for v in variables:
+            v.value = 0.0
+        return sys.solve()
+
+    result = benchmark(run)
+    assert result == SolveStatus.CONVERGED
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("n", [10, 100, 500, 1000])
+def test_benchmark_tracker_overhead(benchmark, n):
+    """Benchmark tracker overhead: eval with tracking for N variables."""
+    sys = EquationSystem(f"tracker_bench_{n}")
+    variables = []
+    for i in range(n):
+        v = sys.var(f"x{i}", guess=float(i))
+        variables.append(v)
+
+    def read_all_vars():
+        sys._tracker.start()
+        total = 0.0
+        for v in variables:
+            total += v()
+        sys._tracker.stop()
+        return total
+
+    benchmark(read_all_vars)