nummeth 0.1.0__py3-none-any.whl

nummeth/__init__.py

@@ -0,0 +1,132 @@
+"""
+NumMeth: A Practical, Educational Numerical Methods Library for Laboratories & Engineering.
+"""
+
+__version__ = "0.1.0"
+
+# Core structures
+from nummeth.core.results import IterationResult, TableFormatter
+
+# 1. Algebraic & Transcendental Roots
+from nummeth.roots import (
+    bisection,
+    false_position,
+    newton_raphson,
+    secant,
+    fixed_point,
+)
+
+# 2. Linear Systems & Eigenvalues
+from nummeth.linear_systems import (
+    gauss_elimination,
+    gauss_jacobi,
+    gauss_seidel,
+    matrix_inverse,
+    power_method,
+)
+
+# 3. Interpolation & Splines
+from nummeth.interpolation import (
+    lagrange_interpolate,
+    divided_difference_table,
+    divided_difference_interp,
+    newton_forward_table,
+    newton_forward_interp,
+    newton_backward_table,
+    newton_backward_interp,
+    natural_cubic_spline,
+)
+
+# 4. Curve Fitting & Regression
+from nummeth.fitting import (
+    polynomial_fit,
+)
+
+# 5. Numerical Calculus
+from nummeth.calculus import (
+    derivative_forward,
+    derivative_backward,
+    derivative_central,
+    derivative_second,
+    trapezoidal,
+    simpson_13,
+    simpson_38,
+    boole,
+    weddle,
+)
+
+# 6. Ordinary Differential Equations (IVP)
+from nummeth.ode import (
+    euler,
+    modified_euler,
+    rk2,
+    rk4,
+    milne_predictor_corrector,
+)
+
+# 7. Partial Differential Equations (Finite Differences)
+from nummeth.pde import (
+    solve_laplace_2d,
+    solve_poisson_2d,
+    heat_1d_bender_schmidt,
+    heat_1d_crank_nicolson,
+    wave_1d_explicit,
+)
+
+# 8. Applications
+from nummeth.applications import (
+    solve_circuit_nodal,
+)
+
+__all__ = [
+    "__version__",
+    "IterationResult",
+    "TableFormatter",
+    # Roots
+    "bisection",
+    "false_position",
+    "newton_raphson",
+    "secant",
+    "fixed_point",
+    # Linear
+    "gauss_elimination",
+    "gauss_jacobi",
+    "gauss_seidel",
+    "matrix_inverse",
+    "power_method",
+    # Interpolation
+    "lagrange_interpolate",
+    "divided_difference_table",
+    "divided_difference_interp",
+    "newton_forward_table",
+    "newton_forward_interp",
+    "newton_backward_table",
+    "newton_backward_interp",
+    "natural_cubic_spline",
+    # Fitting
+    "polynomial_fit",
+    # Calculus
+    "derivative_forward",
+    "derivative_backward",
+    "derivative_central",
+    "derivative_second",
+    "trapezoidal",
+    "simpson_13",
+    "simpson_38",
+    "boole",
+    "weddle",
+    # ODE
+    "euler",
+    "modified_euler",
+    "rk2",
+    "rk4",
+    "milne_predictor_corrector",
+    # PDE
+    "solve_laplace_2d",
+    "solve_poisson_2d",
+    "heat_1d_bender_schmidt",
+    "heat_1d_crank_nicolson",
+    "wave_1d_explicit",
+    # Applications
+    "solve_circuit_nodal",
+]

nummeth/applications/__init__.py

@@ -0,0 +1,4 @@
+"""Real-world numerical applications."""
+from .circuit import solve_circuit_nodal
+
+__all__ = ["solve_circuit_nodal"]

nummeth/applications/circuit.py

@@ -0,0 +1,78 @@
+"""
+Electrical circuit nodal analysis application using systems of linear equations.
+Ported from laboratory circuit solver exercise.
+"""
+
+from typing import Dict, List, Tuple
+from nummeth.core.results import IterationResult
+from nummeth.linear_systems.elimination import gauss_elimination
+
+def solve_circuit_nodal(
+    known_voltages: Dict[int, float],
+    unknown_nodes: List[int],
+    resistors: List[Tuple[int, int, float]],
+    method: str = "elimination"
+) -> IterationResult:
+    """
+    Solves for unknown node voltages and branch currents in a resistor network
+    using Kirchhoff's Current Law (Nodal Analysis).
+
+    Parameters:
+        known_voltages: Dict mapping node number -> known voltage (e.g. {1: 10.0, 6: 0.0}).
+        unknown_nodes: List of unknown node indices (e.g. [2, 3, 4, 5]).
+        resistors: List of tuples (node1, node2, resistance_in_ohms).
+        method: "elimination" or "seidel".
+
+    Returns:
+        IterationResult where value is dict of all node voltages, and extra['branch_currents']
+        contains branch currents.
+    """
+    n = len(unknown_nodes)
+    index = {node: i for i, node in enumerate(unknown_nodes)}
+
+    A = [[0.0 for _ in range(n)] for _ in range(n)]
+    b = [0.0 for _ in range(n)]
+
+    for node in unknown_nodes:
+        row = index[node]
+        for u, v, r in resistors:
+            if r <= 0:
+                raise ValueError("Resistance must be positive.")
+            if node == u:
+                other = v
+            elif node == v:
+                other = u
+            else:
+                continue
+
+            g = 1.0 / r
+            A[row][row] += g
+
+            if other in index:
+                A[row][index[other]] -= g
+            elif other in known_voltages:
+                b[row] += g * known_voltages[other]
+
+    # Solve linear system
+    sol_res = gauss_elimination(A, b, pivoting=True)
+    voltages = dict(known_voltages)
+    for i, node in enumerate(unknown_nodes):
+        voltages[node] = sol_res.value[i]
+
+    # Calculate branch currents
+    branch_currents = []
+    for u, v, r in resistors:
+        cur = (voltages[u] - voltages[v]) / r
+        branch_currents.append({"from": u, "to": v, "resistance": r, "current": cur})
+
+    return IterationResult(
+        value=voltages,
+        converged=True,
+        message="Circuit nodal voltages and currents resolved successfully.",
+        extra={
+            "voltages": voltages,
+            "branch_currents": branch_currents,
+            "conductance_matrix": A,
+            "rhs_vector": b
+        }
+    )

nummeth/calculus/__init__.py

@@ -0,0 +1,26 @@
+"""Numerical calculus: differentiation and integration."""
+from .differentiation import (
+    derivative_forward,
+    derivative_backward,
+    derivative_central,
+    derivative_second,
+)
+from .integration import (
+    trapezoidal,
+    simpson_13,
+    simpson_38,
+    boole,
+    weddle,
+)
+
+__all__ = [
+    "derivative_forward",
+    "derivative_backward",
+    "derivative_central",
+    "derivative_second",
+    "trapezoidal",
+    "simpson_13",
+    "simpson_38",
+    "boole",
+    "weddle",
+]

nummeth/calculus/differentiation.py

@@ -0,0 +1,21 @@
+"""
+Numerical Differentiation using finite difference formulas.
+"""
+
+from typing import Callable, Union, List
+
+def derivative_forward(f: Callable[[float], float], x: float, h: float = 1e-5) -> float:
+    """First derivative via 2-point forward difference: f'(x) ≈ (f(x + h) - f(x)) / h"""
+    return (f(x + h) - f(x)) / h
+
+def derivative_backward(f: Callable[[float], float], x: float, h: float = 1e-5) -> float:
+    """First derivative via 2-point backward difference: f'(x) ≈ (f(x) - f(x - h)) / h"""
+    return (f(x) - f(x - h)) / h
+
+def derivative_central(f: Callable[[float], float], x: float, h: float = 1e-5) -> float:
+    """First derivative via 2-point central difference (O(h^2)): f'(x) ≈ (f(x + h) - f(x - h)) / (2h)"""
+    return (f(x + h) - f(x - h)) / (2.0 * h)
+
+def derivative_second(f: Callable[[float], float], x: float, h: float = 1e-4) -> float:
+    """Second derivative via central difference: f''(x) ≈ (f(x + h) - 2f(x) + f(x - h)) / h^2"""
+    return (f(x + h) - 2.0 * f(x) + f(x - h)) / (h ** 2)

nummeth/calculus/integration.py

@@ -0,0 +1,178 @@
+"""
+Numerical Integration (Quadrature) formulas:
+- Trapezoidal Rule
+- Simpson's 1/3 Rule
+- Simpson's 3/8 Rule
+- Boole's Rule
+- Weddle's Rule
+- Romberg Integration
+"""
+
+from typing import Callable, Union, List, Optional
+from nummeth.core.results import IterationResult
+
+def _get_samples(f_or_y: Union[Callable[[float], float], List[float]], a: float, b: float, n: int) -> Tuple_Helper:
+    """Helper to obtain step size h and samples [y_0, ..., y_n]."""
+    h = (b - a) / n
+    if callable(f_or_y):
+        y = [float(f_or_y(a + i * h)) for i in range(n + 1)]
+    else:
+        y = [float(val) for val in f_or_y]
+        if len(y) != n + 1:
+            raise ValueError(f"For n={n} intervals, exactly {n + 1} y-values are required. Got {len(y)}.")
+    return h, y
+
+class Tuple_Helper(tuple):
+    pass
+
+
+def trapezoidal(
+    f_or_y: Union[Callable[[float], float], List[float]],
+    a: float,
+    b: float,
+    n: int = 100,
+    exact: Optional[float] = None
+) -> IterationResult:
+    """
+    Evaluates definite integral using the Composite Trapezoidal Rule.
+    Formula: (h / 2) * [y_0 + 2*(y_1 + ... + y_{n-1}) + y_n]
+    """
+    if n < 1:
+        raise ValueError("Subintervals n must be at least 1.")
+    h, y = _get_samples(f_or_y, a, b, n)
+
+    s = y[0] + y[-1] + 2.0 * sum(y[1:-1])
+    integral = (h / 2.0) * s
+    abs_err = abs(exact - integral) if exact is not None else None
+
+    return IterationResult(
+        value=integral,
+        error=abs_err,
+        message=f"Trapezoidal rule over [{a}, {b}] with n={n}: {integral:.6f}",
+        extra={"h": h, "n": n, "subintervals": n, "method": "Trapezoidal"}
+    )
+
+
+def simpson_13(
+    f_or_y: Union[Callable[[float], float], List[float]],
+    a: float,
+    b: float,
+    n: int = 100,
+    exact: Optional[float] = None
+) -> IterationResult:
+    """
+    Evaluates definite integral using Composite Simpson's 1/3 Rule.
+    Requires n to be an even integer.
+    Formula: (h / 3) * [y_0 + 4*(odd terms) + 2*(even terms) + y_n]
+    """
+    if n % 2 != 0:
+        raise ValueError("Simpson's 1/3 rule requires an even number of subintervals (n % 2 == 0).")
+    h, y = _get_samples(f_or_y, a, b, n)
+
+    s_odd = sum(y[i] for i in range(1, n, 2))
+    s_even = sum(y[i] for i in range(2, n, 2))
+    integral = (h / 3.0) * (y[0] + y[-1] + 4.0 * s_odd + 2.0 * s_even)
+    abs_err = abs(exact - integral) if exact is not None else None
+
+    return IterationResult(
+        value=integral,
+        error=abs_err,
+        message=f"Simpson's 1/3 rule over [{a}, {b}] with n={n}: {integral:.6f}",
+        extra={"h": h, "n": n, "method": "Simpson 1/3"}
+    )
+
+
+def simpson_38(
+    f_or_y: Union[Callable[[float], float], List[float]],
+    a: float,
+    b: float,
+    n: int = 99,
+    exact: Optional[float] = None
+) -> IterationResult:
+    """
+    Evaluates definite integral using Composite Simpson's 3/8 Rule.
+    Requires n to be a multiple of 3.
+    Formula: (3h / 8) * [y_0 + 3*sum_{i%3!=0} y_i + 2*sum_{i%3==0} y_i + y_n]
+    """
+    if n % 3 != 0:
+        raise ValueError("Simpson's 3/8 rule requires n to be a multiple of 3 (n % 3 == 0).")
+    h, y = _get_samples(f_or_y, a, b, n)
+
+    s = y[0] + y[-1]
+    for i in range(1, n):
+        if i % 3 == 0:
+            s += 2.0 * y[i]
+        else:
+            s += 3.0 * y[i]
+
+    integral = (3.0 * h / 8.0) * s
+    abs_err = abs(exact - integral) if exact is not None else None
+
+    return IterationResult(
+        value=integral,
+        error=abs_err,
+        message=f"Simpson's 3/8 rule over [{a}, {b}] with n={n}: {integral:.6f}",
+        extra={"h": h, "n": n, "method": "Simpson 3/8"}
+    )
+
+
+def boole(
+    f_or_y: Union[Callable[[float], float], List[float]],
+    a: float,
+    b: float,
+    n: int = 4,
+    exact: Optional[float] = None
+) -> IterationResult:
+    """
+    Evaluates definite integral using Boole's Rule.
+    Requires n to be a multiple of 4.
+    Formula per 4-step panel: (2h / 45) * [7*y0 + 32*y1 + 12*y2 + 32*y3 + 7*y4]
+    """
+    if n % 4 != 0:
+        raise ValueError("Boole's rule requires n to be a multiple of 4.")
+    h, y = _get_samples(f_or_y, a, b, n)
+
+    total = 0.0
+    for i in range(0, n, 4):
+        total += 7.0 * y[i] + 32.0 * y[i + 1] + 12.0 * y[i + 2] + 32.0 * y[i + 3] + 7.0 * y[i + 4]
+
+    integral = (2.0 * h / 45.0) * total
+    abs_err = abs(exact - integral) if exact is not None else None
+
+    return IterationResult(
+        value=integral,
+        error=abs_err,
+        message=f"Boole's rule over [{a}, {b}] with n={n}: {integral:.6f}",
+        extra={"h": h, "n": n, "method": "Boole"}
+    )
+
+
+def weddle(
+    f_or_y: Union[Callable[[float], float], List[float]],
+    a: float,
+    b: float,
+    n: int = 6,
+    exact: Optional[float] = None
+) -> IterationResult:
+    """
+    Evaluates definite integral using Weddle's Rule.
+    Requires n to be a multiple of 6.
+    Formula per 6-step panel: (3h / 10) * [y0 + 5*y1 + y2 + 6*y3 + y4 + 5*y5 + y6]
+    """
+    if n % 6 != 0:
+        raise ValueError("Weddle's rule requires n to be a multiple of 6.")
+    h, y = _get_samples(f_or_y, a, b, n)
+
+    total = 0.0
+    for i in range(0, n, 6):
+        total += (y[i] + 5.0 * y[i + 1] + y[i + 2] + 6.0 * y[i + 3] + y[i + 4] + 5.0 * y[i + 5] + y[i + 6])
+
+    integral = (3.0 * h / 10.0) * total
+    abs_err = abs(exact - integral) if exact is not None else None
+
+    return IterationResult(
+        value=integral,
+        error=abs_err,
+        message=f"Weddle's rule over [{a}, {b}] with n={n}: {integral:.6f}",
+        extra={"h": h, "n": n, "method": "Weddle"}
+    )

nummeth/core/__init__.py

@@ -0,0 +1,4 @@
+"""Core utilities and result data structures."""
+from .results import IterationResult, TableFormatter
+
+__all__ = ["IterationResult", "TableFormatter"]

nummeth/core/results.py

@@ -0,0 +1,107 @@
+"""
+Core result structures and formatting utilities for numerical methods laboratory calculations.
+"""
+
+from typing import List, Dict, Any, Optional, Sequence
+import math
+
+class TableFormatter:
+    """Helper to format numerical iteration logs as clean ASCII / markdown tables."""
+
+    @staticmethod
+    def format_table(headers: List[str], rows: List[List[Any]], precision: int = 6) -> str:
+        """Formats headers and data rows into a clean, aligned ASCII table."""
+        if not rows:
+            return "(No iterations)"
+
+        formatted_rows = []
+        for row in rows:
+            formatted_row = []
+            for cell in row:
+                if cell is None:
+                    formatted_row.append("N/A")
+                elif isinstance(cell, float):
+                    if math.isnan(cell):
+                        formatted_row.append("NaN")
+                    elif math.isinf(cell):
+                        formatted_row.append("Inf")
+                    else:
+                        formatted_row.append(f"{cell:.{precision}f}")
+                else:
+                    formatted_row.append(str(cell))
+            formatted_rows.append(formatted_row)
+
+        col_widths = [len(h) for h in headers]
+        for row in formatted_rows:
+            for i, cell in enumerate(row):
+                if i < len(col_widths):
+                    col_widths[i] = max(col_widths[i], len(cell))
+                else:
+                    col_widths.append(len(cell))
+
+        # Build borders
+        sep = "+" + "+".join("-" * (w + 2) for w in col_widths) + "+"
+        header_line = "| " + " | ".join(h.center(col_widths[i]) for i, h in enumerate(headers)) + " |"
+
+        lines = [sep, header_line, sep]
+        for r in formatted_rows:
+            row_line = "| " + " | ".join(
+                (r[i] if i < len(r) else "").rjust(col_widths[i]) for i in range(len(col_widths))
+            ) + " |"
+            lines.append(row_line)
+        lines.append(sep)
+
+        return "\n".join(lines)
+
+
+class IterationResult:
+    """
+    Standard return container for iterative numerical methods.
+    Stores final output, iteration count, step history, and error metrics.
+    """
+    def __init__(
+        self,
+        value: Any = None,
+        iterations: int = 0,
+        converged: bool = True,
+        error: Optional[float] = None,
+        headers: Optional[List[str]] = None,
+        history: Optional[List[List[Any]]] = None,
+        message: str = "",
+        extra: Optional[Dict[str, Any]] = None
+    ):
+        self.value = value
+        self.root = value  # Alias for root-finding methods
+        self.solution = value  # Alias for linear solvers / ODEs
+        self.iterations = iterations
+        self.converged = converged
+        self.error = error
+        self.headers = headers or []
+        self.history = history or []
+        self.message = message
+        self.extra = extra or {}
+
+    def table(self, precision: int = 6) -> str:
+        """Returns the iteration history formatted as an ASCII table."""
+        if not self.headers or not self.history:
+            return "(No step history recorded)"
+        return TableFormatter.format_table(self.headers, self.history, precision=precision)
+
+    def print_table(self, precision: int = 6) -> None:
+        """Prints the iteration history table to stdout."""
+        print(self.table(precision=precision))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts result summary to dictionary."""
+        return {
+            "value": self.value,
+            "iterations": self.iterations,
+            "converged": self.converged,
+            "error": self.error,
+            "message": self.message,
+            "extra": self.extra
+        }
+
+    def __repr__(self) -> str:
+        return (f"<IterationResult value={self.value!r}, iterations={self.iterations}, "
+                f"converged={self.converged}, error={self.error}>")

nummeth/fitting/__init__.py

@@ -0,0 +1,4 @@
+"""Curve fitting and regression modules."""
+from .regression import polynomial_fit
+
+__all__ = ["polynomial_fit"]

nummeth/fitting/regression.py

@@ -0,0 +1,123 @@
+"""
+Least Squares Regression and Curve Fitting.
+Supports polynomial fitting (degrees 1, 2, 3, etc.), exponential, and power law fits.
+"""
+
+from typing import List, Optional, Tuple, Dict, Any
+import math
+from nummeth.core.results import IterationResult
+
+def polynomial_fit(
+    x: List[float],
+    y: List[float],
+    degree: int = 1,
+    plot: bool = False,
+    x_label: str = "x",
+    y_label: str = "y",
+    title: Optional[str] = None
+) -> IterationResult:
+    """
+    Fits a polynomial of specified degree y ≈ c_m x^m + ... + c_1 x + c_0
+    using the method of least squares and normal equations (A^T A) c = A^T y.
+
+    Parameters:
+        x: List of x values.
+        y: List of y values.
+        degree: Polynomial degree (1 for linear, 2 for quadratic, 3 for cubic).
+        plot: If True, displays a matplotlib regression plot.
+
+    Returns:
+        IterationResult with coefficients [c_m, c_{m-1}, ..., c_0] in descending powers of x.
+    """
+    n = len(x)
+    if len(y) != n or n <= degree:
+        raise ValueError("Number of data points must exceed the polynomial degree.")
+
+    # Design matrix A: row i = [x[i]^m, x[i]^(m-1), ..., 1]
+    m = degree
+    p = m + 1
+    ATA = [[0.0 for _ in range(p)] for _ in range(p)]
+    ATy = [0.0 for _ in range(p)]
+
+    # Compute normal equations directly
+    for k in range(n):
+        xi = x[k]
+        yi = y[k]
+        # Powers from m down to 0
+        powers = [xi ** (m - j) for j in range(p)]
+        for r in range(p):
+            for c in range(p):
+                ATA[r][c] += powers[r] * powers[c]
+            ATy[r] += powers[r] * yi
+
+    # Solve ATA * c = ATy via Gaussian elimination with partial pivoting
+    # Augmented matrix
+    aug = [ATA[i][:] + [ATy[i]] for i in range(p)]
+
+    for i in range(p):
+        pivot = i
+        for r in range(i + 1, p):
+            if abs(aug[r][i]) > abs(aug[pivot][i]):
+                pivot = r
+        aug[i], aug[pivot] = aug[pivot], aug[i]
+
+        pivot_val = aug[i][i]
+        if abs(pivot_val) < 1e-12:
+            raise ValueError("Collinear or singular system in normal equations.")
+
+        for r in range(i + 1, p):
+            factor = aug[r][i] / pivot_val
+            for c in range(i, p + 1):
+                aug[r][c] -= factor * aug[i][c]
+
+    # Back substitution
+    coeffs = [0.0] * p
+    for i in range(p - 1, -1, -1):
+        total = aug[i][p]
+        for c in range(i + 1, p):
+            total -= aug[i][c] * coeffs[c]
+        coeffs[i] = total / aug[i][i]
+
+    # Calculate R-squared (coefficient of determination)
+    y_mean = sum(y) / n
+    ss_tot = sum((yi - y_mean) ** 2 for yi in y)
+    y_pred = []
+    for xi in x:
+        val = sum(coeffs[j] * (xi ** (m - j)) for j in range(p))
+        y_pred.append(val)
+    ss_res = sum((y[i] - y_pred[i]) ** 2 for i in range(n))
+    r_squared = 1.0 - (ss_res / ss_tot) if ss_tot > 0 else 1.0
+
+    if plot:
+        try:
+            import matplotlib.pyplot as plt
+            import numpy as np
+            min_x, max_x = min(x), max(x)
+            padding = (max_x - min_x) * 0.05
+            xx = np.linspace(min_x - padding, max_x + padding, 200)
+            yy = [sum(coeffs[j] * (val ** (m - j)) for j in range(p)) for val in xx]
+
+            plt.figure(figsize=(7, 5))
+            plt.scatter(x, y, color="red", label="Data Points", zorder=5)
+            plt.plot(xx, yy, color="blue", linewidth=2, label=f"Fit (deg={degree}, R²={r_squared:.4f})")
+            plt.title(title or f"Least Squares Fit (Degree {degree})")
+            plt.xlabel(x_label)
+            plt.ylabel(y_label)
+            plt.grid(True)
+            plt.legend()
+            plt.show()
+        except ImportError:
+            pass
+
+    return IterationResult(
+        value=coeffs,
+        converged=True,
+        error=ss_res,
+        message=f"Polynomial fit (degree {degree}) completed with R² = {r_squared:.4f}.",
+        extra={
+            "coefficients": coeffs,
+            "r_squared": r_squared,
+            "residuals": ss_res,
+            "degree": degree
+        }
+    )