numanlib 0.1.0__tar.gz

numanlib-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: numanlib
+Version: 0.1.0
+Summary: Add your description here
+Author: Fabio Nicotra
+Author-email: Fabio Nicotra <nicotra.fabio@icloud.com>
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=1.5
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+

numanlib-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "numanlib"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Fabio Nicotra", email = "nicotra.fabio@icloud.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "matplotlib>=3.5",
+    "numpy>=1.26",
+    "pandas>=1.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.2,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/numanlib"]

numanlib-0.1.0/src/numanlib/__init__.py

@@ -0,0 +1,8 @@
+from . import root_finding
+from . import interpolation
+from . import linear_systems
+from . import differentiation
+
+import matplotlib.pyplot as plt
+
+plt.ion()

numanlib-0.1.0/src/numanlib/core/__init__.py

@@ -0,0 +1,2 @@
+from .polynomial import Polynomial
+from .newton_polynomial import NewtonPolynomial

numanlib-0.1.0/src/numanlib/core/formatting.py

@@ -0,0 +1,18 @@
+"""Text helpers shared by the stencil-style result objects
+(FiniteDifferenceResult, NewtonCotesResult, CompositeNewtonCotesResult)
+for rendering formula() and error_term() strings."""
+from fractions import Fraction
+
+
+def derivative_notation(derivative_order: int) -> str:
+    if derivative_order <= 3:
+        return "'" * derivative_order
+    return f"^({derivative_order})"
+
+
+def signed_term(coeff: Fraction, expr: str) -> str:
+    if coeff == 1:
+        return expr
+    if coeff == -1:
+        return f"-{expr}"
+    return f"{coeff}*{expr}"

numanlib-0.1.0/src/numanlib/core/newton_polynomial.py

@@ -0,0 +1,56 @@
+import numpy as np
+from dataclasses import dataclass
+from typing import SupportsFloat
+from numpy.typing import NDArray
+from .polynomial import Polynomial
+
+
+@dataclass(frozen=True)
+class NewtonPolynomial:
+    nodes: NDArray[np.float64]   # x_0, ..., x_{n-1}  (n nodes, one per non-constant term)
+    coeffs: NDArray[np.float64]  # a_0, ..., a_n       (n+1 divided-difference coefficients)
+
+    def __post_init__(self):
+        object.__setattr__(self, 'nodes', np.asarray(self.nodes, dtype=float))
+        object.__setattr__(self, 'coeffs', np.asarray(self.coeffs, dtype=float))
+        if self.nodes.ndim != 1 or self.coeffs.ndim != 1:
+            raise ValueError("nodes and coeffs must be 1-D arrays.")
+        if len(self.coeffs) != len(self.nodes) + 1:
+            raise ValueError(
+                f"len(coeffs) must equal len(nodes) + 1, "
+                f"got {len(self.coeffs)} and {len(self.nodes)}."
+            )
+
+    @property
+    def degree(self) -> int:
+        return len(self.coeffs) - 1
+
+    def _evaluate(self, x: float) -> float:
+        result = self.coeffs[self.degree]
+        for i in range(self.degree - 1, -1, -1):
+            result = self.coeffs[i] + (x - self.nodes[i]) * result
+        return result
+
+    def __call__(self, x):
+        if isinstance(x, (list, tuple, np.ndarray)):
+            return np.array([self._evaluate(float(v)) for v in x], dtype=float)
+        return self._evaluate(float(x))
+
+    def to_polynomial(self) -> 'Polynomial':
+        result = Polynomial([self.coeffs[0]])
+        node_poly = Polynomial([1.0])
+        for k in range(1, self.degree + 1):
+            node_poly = node_poly * Polynomial([1.0, -self.nodes[k - 1]])
+            result = result + self.coeffs[k] * node_poly
+        return result
+
+    def __str__(self) -> str:
+        if self.degree == 0:
+            return f"{self.coeffs[0]:.6g}"
+        parts = [f"{self.coeffs[0]:.6g}"]
+        for k in range(1, self.degree + 1):
+            node_str = "·".join(f"(x - {self.nodes[j]:.6g})" for j in range(k))
+            coeff = self.coeffs[k]
+            sign = "+" if coeff >= 0 else "-"
+            parts.append(f"{sign} {abs(coeff):.6g}·{node_str}")
+        return " ".join(parts)

numanlib-0.1.0/src/numanlib/core/polynomial.py

@@ -0,0 +1,248 @@
+import warnings
+import numpy as np
+from typing import SupportsFloat
+from dataclasses import dataclass
+    
+@dataclass(frozen=True)
+class Polynomial:
+    coeffs: np.ndarray # [a_n, a_{n-1}, ..., a_0]
+    degree: int = 0  # Default value
+
+    def __post_init__(self):
+        object.__setattr__(self, 'coeffs', np.array(self.coeffs, dtype=float))
+        # Calculate degree based on the length of the coefficients
+        object.__setattr__(self, 'degree', len(self.coeffs) - 1)
+        
+    def __str__(self):
+        monomials = []
+        for degree, coeff in enumerate(reversed(self.coeffs)):
+            if coeff == 0:
+                continue
+            if degree == 0:
+                monomials.append(f"{coeff:.2g}")
+            elif degree == 1 and coeff == 1:
+                monomials.append("x")
+            elif degree == 1 and coeff == -1:
+                monomials.append("-x")
+            elif degree == 1:
+                monomials.append(f"{coeff:.2g}·x")
+            elif coeff == 1:
+                monomials.append(f"x^{degree}")
+            elif coeff == -1:
+                monomials.append(f"-x^{degree}")
+            else:
+                monomials.append(f"{coeff:.2g}·x^{degree}")
+        
+        return " + ".join(reversed(monomials)).replace("+ -", "- ")
+    
+    def __add__(self, other):
+        if isinstance(other, (int, float, complex)):
+            other = Polynomial([other])
+        if not isinstance(other, Polynomial):
+            return NotImplemented
+        max_degree = max(self.degree, other.degree)
+        new_coeffs = np.zeros(max_degree + 1)
+        new_coeffs[-len(self.coeffs):] += self.coeffs
+        new_coeffs[-len(other.coeffs):] += other.coeffs
+        return Polynomial(new_coeffs)
+
+    def __radd__(self, other):
+        return self.__add__(other)
+
+    def __mul__(self, other):
+        if isinstance(other, Polynomial):
+            return Polynomial(np.convolve(self.coeffs, other.coeffs))
+        if isinstance(other, (int, float, complex)):
+            return Polynomial(self.coeffs * other)
+        return NotImplemented
+
+    def __rmul__(self, other):
+        return self.__mul__(other)
+
+    def __pow__(self, n: int) -> 'Polynomial':
+        if not isinstance(n, int) or n < 0:
+            return NotImplemented
+        result = Polynomial([1.0])
+        base = self
+        while n > 0:
+            if n % 2 == 1:
+                result = result * base
+            base = base * base
+            n //= 2
+        return result
+    
+    def __sub__(self, other):
+        if not isinstance(other, Polynomial):
+            return NotImplemented
+        return self + (-other)
+    
+    def __neg__(self):
+        return Polynomial(-self.coeffs)
+    
+    def __truediv__(self, other):
+        if isinstance(other, (int, float, complex)):
+            if other == 0:
+                raise ZeroDivisionError("Cannot divide by zero.")
+            return 1/other * self
+        if isinstance(other, Polynomial):
+            return NotImplemented
+        return NotImplemented
+    
+    def __eq__(self, other):
+        if not isinstance(other, Polynomial):
+            return NotImplemented
+        return np.array_equal(self.coeffs, other.coeffs)
+    
+    def __hash__(self):
+        return hash(tuple(self.coeffs))
+    
+    def from_roots(roots, multiplicities: np.ndarray = None) -> 'Polynomial':
+        roots = np.asarray(list(roots) if not hasattr(roots, '__len__') else roots)
+        if multiplicities is None:
+            multiplicities = np.ones(len(roots), dtype=int)
+        elif len(roots) != len(multiplicities):
+            raise ValueError("Length of multiplicities must match length of roots.")
+        res = Polynomial([1])
+        for r, m in zip(roots, multiplicities):
+            res *= Polynomial([1, -r])**m
+        return res
+        
+    def horner(self, x0: float) -> 'HornerResult':
+        n = self.degree
+        q_coeffs = np.zeros(n) # Coefficients of Q(x)
+        
+        q_coeffs[0] = self.coeffs[0]
+        p_deriv = q_coeffs[0]
+        for k in range(1, n):
+            q_coeffs[k] = self.coeffs[k] + x0 * q_coeffs[k-1]
+            p_deriv = q_coeffs[k] + x0 * p_deriv
+        
+        p_val = self.coeffs[n] + x0 * q_coeffs[n-1]
+        
+        return HornerResult(
+            value=p_val,
+            derivative=p_deriv,
+            quotient=Polynomial(q_coeffs)
+        )    
+        
+    def _evaluate(self, x: SupportsFloat):
+        p_val = self.coeffs[0]
+        for i in range(1, self.degree + 1):
+            p_val = self.coeffs[i] + x * p_val
+        return p_val
+
+    def __call__(self, x):
+        if isinstance(x, (list, tuple, np.ndarray)):
+            # Create a numpy array from the evaluated points
+            return np.array([self._evaluate(val) for val in x], dtype=float)
+        # Otherwise, treat as scalar
+        return self._evaluate(x)
+    
+    def deflate(self, root: SupportsFloat):
+        return self.horner(root).quotient
+
+    def deflate_quadratic(self, r: complex) -> 'Polynomial':
+        """Deflate by (x - r)(x - r̄) = x² - 2·Re(r)·x + |r|², keeping real coefficients."""
+        p = -2 * r.real
+        q = r.real**2 + r.imag**2
+        a = self.coeffs
+        n = self.degree
+        b = np.zeros(n - 1)
+        b[0] = a[0]
+        b[1] = a[1] - p * b[0]
+        for k in range(2, n - 1):
+            b[k] = a[k] - p * b[k-1] - q * b[k-2]
+        return Polynomial(b)
+
+    def solve(self, x_hat: SupportsFloat, polish: bool = True, use_muller: bool = False) -> np.ndarray:
+        from ..root_finding import Newton, Muller
+        newton_solver = Newton()
+        muller_solver = Muller() if use_muller else None
+        roots = []
+        current_poly = self
+
+        while current_poly.degree > 2:
+            if use_muller:
+                x = float(x_hat)
+                h = max(0.5, abs(x) * 0.1)
+                result = muller_solver.solve(current_poly, p0=x - h, p1=x, p2=x + h)
+                if not result.converged:
+                    warnings.warn(
+                        f"Müller's method failed during deflation; returning {len(roots)} of {self.degree} roots.",
+                        RuntimeWarning
+                    )
+                    return np.array(roots)
+                if result.complex_root is not None:
+                    r = result.complex_root
+                    roots.extend([r, r.conjugate()])
+                    current_poly = current_poly.deflate_quadratic(r)
+                    x_hat = r.real
+                else:
+                    roots.append(result.root)
+                    current_poly = current_poly.deflate(result.root)
+                    x_hat = result.root
+            else:
+                root = newton_solver.solve(current_poly, x_hat).root
+                if root is None:
+                    warnings.warn(
+                        f"Newton's method failed during deflation; returning {len(roots)} of {self.degree} roots.",
+                        RuntimeWarning
+                    )
+                    return np.array(roots, dtype=float)
+                roots.append(root)
+                current_poly = current_poly.deflate(root)
+                x_hat = root
+
+        if current_poly.degree == 2:
+            roots.extend(current_poly.solve_quadratic())
+        elif current_poly.degree == 1:
+            roots.append(-current_poly.coeffs[1] / current_poly.coeffs[0])
+
+        if polish:
+            polished = []
+            for r in roots:
+                if np.iscomplex(r):
+                    polished.append(r)
+                    continue
+                result = newton_solver.solve(self, r)
+                if result.root is None:
+                    warnings.warn(
+                        f"Newton's method failed while polishing root {r}; keeping unpolished value.",
+                        RuntimeWarning
+                    )
+                    polished.append(r)
+                else:
+                    polished.append(result.root)
+            roots = polished
+
+        return np.array(sorted(roots, key=lambda r: (complex(r).real, complex(r).imag)))
+
+    def solve_quadratic(self) -> np.ndarray:
+        if self.degree != 2:
+            raise ValueError("The polynomial must be of degree 2 to use the quadratic formula.")
+        a, b, c = self.coeffs
+        discriminant = b**2 - 4*a*c
+        sqrt_d = np.sqrt(complex(discriminant)) if discriminant < 0 else np.sqrt(discriminant)
+        return np.array([(-b + sqrt_d) / (2*a), (-b - sqrt_d) / (2*a)])
+    
+    def derivative(self) -> 'Polynomial':
+        n = self.degree
+        coeffs = [self.coeffs[i] * (n - i) for i in range(n)]
+        return Polynomial(coeffs)
+    
+    def integral(self, constant: float = 0.0) -> 'Polynomial':
+        n = self.degree
+        coeffs = [self.coeffs[i] / (n - i + 1) for i in range(n + 1)]
+        coeffs.append(constant)
+        return Polynomial(coeffs)
+
+    def integrate(self, a: SupportsFloat, b: SupportsFloat) -> float:
+        antiderivative = self.integral()
+        return antiderivative(b) - antiderivative(a)
+
+        
+@dataclass(frozen=True)
+class HornerResult:
+    value: float
+    derivative: float
+    quotient: Polynomial

numanlib-0.1.0/src/numanlib/differentiation/__init__.py

@@ -0,0 +1,23 @@
+from .finite_differences import (
+    FiniteDifferenceResult,
+    finite_difference,
+    FORWARD_DIFFERENCE,
+    BACKWARD_DIFFERENCE,
+    THREE_POINT_MIDPOINT,
+    THREE_POINT_ENDPOINT,
+    FIVE_POINT_MIDPOINT,
+    FIVE_POINT_ENDPOINT,
+    SECOND_DERIVATIVE_MIDPOINT,
+)
+
+__all__ = [
+    "FiniteDifferenceResult",
+    "finite_difference",
+    "FORWARD_DIFFERENCE",
+    "BACKWARD_DIFFERENCE",
+    "THREE_POINT_MIDPOINT",
+    "THREE_POINT_ENDPOINT",
+    "FIVE_POINT_MIDPOINT",
+    "FIVE_POINT_ENDPOINT",
+    "SECOND_DERIVATIVE_MIDPOINT",
+]

numanlib-0.1.0/src/numanlib/differentiation/finite_differences.py

@@ -0,0 +1,190 @@
+from dataclasses import dataclass, field
+from fractions import Fraction
+from math import factorial
+from typing import Any, Callable, Dict, List, SupportsFloat, Tuple
+import numpy as np
+import pandas as pd
+from numpy.typing import NDArray
+
+from ..core.formatting import derivative_notation, signed_term
+from ..interpolation import lagrange
+
+
+def _node_label(offset: int) -> str:
+    if offset == 0:
+        return "x0"
+    if abs(offset) == 1:
+        return "x0+h" if offset > 0 else "x0-h"
+    return f"x0{offset:+d}h"
+
+
+def _rational_coefficients(
+    weights: NDArray[np.float64], h: float, derivative_order: int
+) -> List[Fraction]:
+    return [Fraction(w * h**derivative_order).limit_denominator(10_000) for w in weights]
+
+
+def _error_term(
+    coeffs: List[Fraction], offsets: NDArray, derivative_order: int
+) -> Tuple[int, Fraction]:
+    n = len(offsets) - 1
+    j = n + 1
+    while j <= n + 6:
+        leak = sum(c * Fraction(int(o)) ** j for c, o in zip(coeffs, offsets))
+        if leak != 0:
+            return j - derivative_order, leak / factorial(j)
+        j += 1
+    raise RuntimeError("Could not determine the truncation-error term for this stencil.")
+
+
+FORWARD_DIFFERENCE = np.array([0, 1])
+BACKWARD_DIFFERENCE = np.array([-1, 0])
+THREE_POINT_MIDPOINT = np.array([-1, 0, 1])
+THREE_POINT_ENDPOINT = np.array([0, 1, 2])
+FIVE_POINT_MIDPOINT = np.array([-2, -1, 0, 1, 2])
+FIVE_POINT_ENDPOINT = np.array([0, 1, 2, 3, 4])
+SECOND_DERIVATIVE_MIDPOINT = np.array([-1, 0, 1])
+
+
+@dataclass(frozen=True)
+class FiniteDifferenceResult:
+    value: float
+    x0: float
+    h: float
+    derivative_order: int
+    nodes: NDArray[np.float64]
+    f_values: NDArray[np.float64]
+    weights: NDArray[np.float64]
+    error_order: int
+    error_coefficient: Fraction
+    method_name: str = "Finite Difference"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        deriv = derivative_notation(self.derivative_order)
+        order_tag = "O(h)" if self.error_order == 1 else f"O(h^{self.error_order})"
+        return (
+            f"{self.method_name}: f{deriv}({self.x0}) ≈ {self.value} "
+            f"({len(self.nodes)} points, h={self.h}, {order_tag})\n"
+        )
+
+    def to_df(self) -> pd.DataFrame:
+        table = pd.DataFrame({
+            "node": self.nodes,
+            "f(node)": self.f_values,
+            "weight": self.weights,
+        })
+        table.index.name = "i"
+        return table
+
+    def _error_expr(self, coeff: Fraction) -> str:
+        k = self.derivative_order + self.error_order
+        deriv = derivative_notation(k)
+        h_term = "h" if self.error_order == 1 else f"h^{self.error_order}"
+        return signed_term(coeff, f"{h_term}*f{deriv}(ξ)")
+
+    def formula(self) -> str:
+        offsets = np.round((self.nodes - self.x0) / self.h).astype(int)
+        coeffs = _rational_coefficients(self.weights, self.h, self.derivative_order)
+
+        terms = [
+            signed_term(frac, f"f({_node_label(offset)})")
+            for frac, offset in zip(coeffs, offsets)
+            if frac != 0
+        ]
+        rhs = " + ".join(terms).replace("+ -", "- ")
+
+        deriv = derivative_notation(self.derivative_order)
+        denom = "h" if self.derivative_order == 1 else f"h^{self.derivative_order}"
+
+        # exact = formula_value - error_coefficient * h^error_order * f^(k)(ξ)
+        error_part = self._error_expr(-self.error_coefficient)
+        return f"f{deriv}(x0) = (1/{denom}) * ({rhs}) + {error_part}".replace("+ -", "- ")
+
+    def error_term(self) -> str:
+        return f"error ≈ {self._error_expr(self.error_coefficient)}"
+
+    def error_bound(self, M: SupportsFloat) -> float:
+        return abs(float(self.error_coefficient)) * abs(self.h) ** self.error_order * float(M)
+
+    def _abs_coefficient_sum(self) -> Fraction:
+        coeffs = _rational_coefficients(self.weights, self.h, self.derivative_order)
+        return sum(abs(c) for c in coeffs)
+
+    def total_error_bound(self, M: SupportsFloat, epsilon: SupportsFloat) -> float:
+        S = float(self._abs_coefficient_sum())
+        round_off = float(epsilon) * S / abs(self.h) ** self.derivative_order
+        return round_off + self.error_bound(M)
+
+    def optimal_h(self, M: SupportsFloat, epsilon: SupportsFloat) -> float:
+        S = float(self._abs_coefficient_sum())
+        M, epsilon = float(M), float(epsilon)
+        numerator = self.derivative_order * epsilon * S
+        denominator = self.error_order * abs(float(self.error_coefficient)) * M
+        return (numerator / denominator) ** (1 / (self.derivative_order + self.error_order))
+
+
+def finite_difference(
+    f: Callable[[SupportsFloat], SupportsFloat],
+    x0: SupportsFloat,
+    h: SupportsFloat,
+    offsets: NDArray,
+    derivative_order: int = 1,
+) -> 'FiniteDifferenceResult':
+    if not callable(f):
+        raise TypeError("f must be a callable function.")
+    try:
+        x0 = float(x0)
+        h = float(h)
+    except (TypeError, ValueError):
+        raise TypeError("x0 and h must be numeric values.")
+    if h == 0:
+        raise ValueError("h must be nonzero.")
+    if not isinstance(derivative_order, int) or derivative_order <= 0:
+        raise ValueError("derivative_order must be a positive integer.")
+
+    offsets = np.array(offsets, dtype=float)
+    if offsets.ndim != 1:
+        raise ValueError("offsets must be a 1-D array.")
+    if len(np.unique(offsets)) != len(offsets):
+        raise ValueError("offsets must be distinct.")
+    if len(offsets) <= derivative_order:
+        raise ValueError(
+            "offsets must contain more points than derivative_order to "
+            "produce a nonzero derivative."
+        )
+
+    nodes = x0 + h * offsets
+    f_values = np.array([f(node) for node in nodes], dtype=float)
+
+    # Interpolate in the offset variable s = (x - x0) / h rather than in x
+    # directly: the offsets are always small integers near the origin, so
+    # the monomial expansion inside lagrange() stays well-conditioned
+    # regardless of how large x0 or how small h is. Recover the x-derivative
+    # via the chain rule: d^n f/dx^n(x0) = (1/h^n) * d^n g/ds^n(0).
+    lag = lagrange(offsets, f_values)
+    polynomial = lag.polynomial
+    basis_polynomials = lag.metadata["basis_polynomials"]
+    for _ in range(derivative_order):
+        polynomial = polynomial.derivative()
+        basis_polynomials = [basis.derivative() for basis in basis_polynomials]
+
+    scale = 1.0 / h**derivative_order
+    weights = np.array([basis(0.0) for basis in basis_polynomials]) * scale
+
+    coeffs = _rational_coefficients(weights, h, derivative_order)
+    offsets_int = np.round(offsets).astype(int)
+    error_order, error_coefficient = _error_term(coeffs, offsets_int, derivative_order)
+
+    return FiniteDifferenceResult(
+        value=polynomial(0.0) * scale,
+        x0=x0,
+        h=h,
+        derivative_order=derivative_order,
+        nodes=nodes,
+        f_values=f_values,
+        weights=weights,
+        error_order=error_order,
+        error_coefficient=error_coefficient,
+        metadata={"function": f},
+    )

numanlib-0.1.0/src/numanlib/integration/__init__.py

@@ -0,0 +1,33 @@
+from .composite import (
+    CompositeNewtonCotesResult,
+    composite_newton_cotes,
+)
+from .newton_cotes import (
+    NewtonCotesRule,
+    NewtonCotesResult,
+    newton_cotes,
+    TRAPEZOIDAL,
+    SIMPSONS,
+    SIMPSONS_THREE_EIGHTHS,
+    BOOLES,
+    MIDPOINT,
+    OPEN_NEWTON_COTES_1,
+    OPEN_NEWTON_COTES_2,
+    OPEN_NEWTON_COTES_3,
+)
+
+__all__ = [
+    "CompositeNewtonCotesResult",
+    "composite_newton_cotes",
+    "NewtonCotesRule",
+    "NewtonCotesResult",
+    "newton_cotes",
+    "TRAPEZOIDAL",
+    "SIMPSONS",
+    "SIMPSONS_THREE_EIGHTHS",
+    "BOOLES",
+    "MIDPOINT",
+    "OPEN_NEWTON_COTES_1",
+    "OPEN_NEWTON_COTES_2",
+    "OPEN_NEWTON_COTES_3",
+]