bs-python-utils 1.1.1__tar.gz → 1.1.3__tar.gz

{bs_python_utils-1.1.1 → bs_python_utils-1.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.1.1
+Version: 1.1.3
 Summary: Utilities programs for my Python code
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -50,6 +50,10 @@ Dynamic: license-file
 
 ### Release notes
 
+#### 1.1.2 and 1.1.3(September 11, 2026)
+- Improved the `Timer` class.
+- added `bs_derivs` with Richardson derivatives.
+
 #### 1.1.1 (September 04, 2026)
 Added simulation-based bivariate ranks.
 

{bs_python_utils-1.1.1 → bs_python_utils-1.1.3}/README.md

@@ -19,6 +19,10 @@
 
 ### Release notes
 
+#### 1.1.2 and 1.1.3(September 11, 2026)
+- Improved the `Timer` class.
+- added `bs_derivs` with Richardson derivatives.
+
 #### 1.1.1 (September 04, 2026)
 Added simulation-based bivariate ranks.
 

{bs_python_utils-1.1.1 → bs_python_utils-1.1.3}/bs_python_utils/__init__.py

@@ -6,7 +6,8 @@ programming.
 * `bs_logging` has customized logging
 * `bs_mathstr` has Unicode for math strings
 * `bs_mem` reports memory usage
-* `Timer` has a `Timer` class to time code execution.
+* `Timer` has a `Timer` context manager to time code execution.
+* `bs_derivs` has Richardson derivatives
 * `bsnputils` has Numpy functions
 * `bssputils` has Scipy functions
 * `sklearn_utils` has Sklearn functions

bs_python_utils-1.1.3/bs_python_utils/bs_derivs.py

@@ -0,0 +1 @@
+from bs_python_utils.numerical.bs_derivs import *  # noqa: F401, F403

bs_python_utils-1.1.3/bs_python_utils/core/Timer.py

@@ -0,0 +1,176 @@
+"""
+Utilities to time code:
+
+* a `Timer` class that can be used as a context manager
+* a `timeit` decorator for functions.
+"""
+
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any, ClassVar, Self
+
+
+def timeit(func: Callable) -> Callable:
+    """Decorator to measure and print execution time of a function.
+
+    Wraps a function to measure its execution time using perf_counter()
+    for high precision, and prints the elapsed time to stdout.
+
+    Args:
+        func: The function to be timed.
+
+    Returns:
+        A wrapped function that prints the execution time when called.
+
+    Example:
+        >>> @timeit
+        ... def slow_function():
+        ...     time.sleep(0.1)  # doctest: +SKIP
+        >>> slow_function()  # doctest: +SKIP
+        slow_function executed in 0.100 seconds
+    """
+
+    @wraps(func)
+    def wrapper(*args: Iterable, **kwargs: dict) -> Any:
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        end = time.perf_counter()
+        print(f"{func.__name__} executed in {end - start:.3f} seconds")
+        return result
+
+    return wrapper
+
+
+class TimerError(Exception):
+    """A custom exception used to report errors in use of Timer class"""
+
+
+@dataclass
+class Timer:
+    """A flexible timer class for measuring execution time.
+
+    This class can be used in three ways:
+
+    1. **As a context manager**: automatically starts and stops timing
+    2. **With manual calls**: call start() and stop() explicitly
+    3. **As a named timer**: accumulate timing across multiple calls using the `name` attribute
+
+    Attributes:
+        name: Optional name for the timer. If provided, cumulative elapsed time is stored
+            in the class-level `timers` dict. Use None for one-off timings.
+        text: Format string for displaying elapsed time. Defaults to "Elapsed time: {:0.4f} seconds".
+            The string is formatted with a single float representing elapsed seconds.
+        logger: Callable to handle output. Defaults to print(). Set to None to suppress output.
+        timers: Class-level dictionary storing cumulative times for all named timers.
+
+    Raises:
+        TimerError: If stop() is called without start(), or start() is called on a running timer.
+
+    Example:
+        >>> # As a context manager (recommended for simple use cases)
+        >>> with Timer():
+        ...     time.sleep(0.1)  # doctest: +SKIP
+        Elapsed time: 0.1000 seconds
+
+        >>> # With a custom message
+        >>> with Timer(text="My code took {:0.2f}s"):
+        ...     time.sleep(0.05)  # doctest: +SKIP
+        My code took 0.05s
+
+        >>> # Suppress output
+        >>> with Timer(logger=None):
+        ...     time.sleep(0.1)  # doctest: +SKIP
+
+        >>> # Suppress output and capture elapsed time
+        >>> with Timer(logger=None) as t:
+        ...     time.sleep(0.1)  # doctest: +SKIP
+        >>> elapsed = t.stop()
+
+        >>> # Manual start/stop
+        >>> timer = Timer()
+        >>> timer.start()  # doctest: +SKIP
+        >>> time.sleep(0.1)  # doctest: +SKIP
+        >>> elapsed = timer.stop()  # doctest: +SKIP
+        Elapsed time: 0.1000 seconds
+
+        >>> # Named timer for cumulative timing
+        >>> Timer(name="db_queries").start()  # doctest: +SKIP
+        >>> time.sleep(0.05)  # doctest: +SKIP
+        >>> Timer(name="db_queries").stop()  # doctest: +SKIP
+        Elapsed time: 0.0500 seconds
+        >>> Timer.timers  # doctest: +SKIP
+        {'db_queries': 0.05}
+    """
+
+    timers: ClassVar = {}
+    name: Any = None
+    text: Any = "Elapsed time: {:0.4f} seconds"
+    logger: Any = print
+    _start_time: Any = field(default=None, init=False, repr=False)
+
+    def __post_init__(self):
+        """Initialize the timer and register it if named.
+
+        For named timers, creates an entry in the class-level `timers` dict
+        to accumulate elapsed time across multiple start/stop cycles.
+        """
+        if self.name is not None:
+            self.timers.setdefault(self.name, 0)
+
+    def start(self):
+        """Start the timer.
+
+        Records the current time using perf_counter() for high precision.
+
+        Raises:
+            TimerError: If the timer is already running.
+        """
+        if self._start_time is not None:
+            raise TimerError("Timer is running. Use .stop() to stop it")
+
+        self._start_time = time.perf_counter()
+
+    def stop(self) -> float:
+        """Stop the timer and report elapsed time.
+
+        Calculates elapsed time since start() was called, sends output to the logger
+        if configured, and accumulates the time if this is a named timer.
+
+        Returns:
+            Elapsed time in seconds as a float.
+
+        Raises:
+            TimerError: If the timer is not running.
+        """
+        if self._start_time is None:
+            raise TimerError("Timer is not running. Use .start() to start it")
+
+        # Calculate elapsed time
+        elapsed_time: float = time.perf_counter() - self._start_time
+        self._start_time = None
+
+        # Report elapsed time
+        if self.logger:
+            self.logger(self.text.format(elapsed_time))
+        if self.name:
+            self.timers[self.name] += elapsed_time
+
+        return elapsed_time
+
+    def __enter__(self) -> Self:
+        """Enter context manager: start the timer.
+
+        Returns:
+            self: The Timer instance.
+        """
+        self.start()
+        return self
+
+    def __exit__(self, *exc_info):
+        """Exit context manager: stop the timer.
+
+        Stops the timer regardless of whether an exception occurred in the with block.
+        """
+        self.stop()

bs_python_utils-1.1.3/bs_python_utils/numerical/bs_derivs.py

@@ -0,0 +1,49 @@
+from collections.abc import Callable
+
+
+def richardson_derivative(
+    f: Callable[[float, list], float], x: float, args: list, h: float
+) -> float:
+    """Compute the first derivative of $f(x, args)$ at $x$ via Richardson extrapolation.
+
+    Uses a 5-point central-difference stencil (step `h` and `2h`) that is
+    fourth-order accurate.
+
+    Args:
+        f: The function to differentiate, called as `f(x, args)`.
+        x: The point at which to differentiate.
+        args: Other arguments passed through to `f`.
+        h: The step size.
+
+    Returns:
+        An approximation of the first derivative of `f` at `x`.
+    """
+    f1 = f(x + h, args)
+    f2 = f(x - h, args)
+    f3 = f(x + 2.0 * h, args)
+    f4 = f(x - 2.0 * h, args)
+    return (8.0 * (f1 - f2) - (f3 - f4)) / (12.0 * h)
+
+
+def richardson_second_derivative(
+    f: Callable[[float, list], float], x: float, args: list, h: float
+) -> float:
+    """Compute the second derivative of $f(x, args)$ at $x$ via Richardson extrapolation.
+
+    Applies `richardson_derivative` to the (Richardson-extrapolated) first
+    derivative of `f`.
+
+    Args:
+        f: The function to differentiate, called as `f(x, args)`.
+        x: The point at which to differentiate.
+        args: Other arguments passed through to `f`.
+        h: The step size.
+
+    Returns:
+        An approximation of the second derivative of `f` at `x`.
+    """
+
+    def fprime(y, a):
+        return richardson_derivative(f, y, a, h)
+
+    return richardson_derivative(fprime, x, args, h)

{bs_python_utils-1.1.1 → bs_python_utils-1.1.3}/bs_python_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.1.1
+Version: 1.1.3
 Summary: Utilities programs for my Python code
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -50,6 +50,10 @@ Dynamic: license-file
 
 ### Release notes
 
+#### 1.1.2 and 1.1.3(September 11, 2026)
+- Improved the `Timer` class.
+- added `bs_derivs` with Richardson derivatives.
+
 #### 1.1.1 (September 04, 2026)
 Added simulation-based bivariate ranks.
 

{bs_python_utils-1.1.1 → bs_python_utils-1.1.3}/bs_python_utils.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ bs_python_utils/Timer.py
 bs_python_utils/__init__.py
 bs_python_utils/bivariate_quantiles.py
 bs_python_utils/bs_altair.py
+bs_python_utils/bs_derivs.py
 bs_python_utils/bs_logging.py
 bs_python_utils/bs_mathstr.py
 bs_python_utils/bs_mem.py
@@ -60,6 +61,7 @@ bs_python_utils/examples/examples_seaborn.py
 bs_python_utils/examples/examples_sklearn.py
 bs_python_utils/examples/examples_sparse_gaussian.py
 bs_python_utils/numerical/__init__.py
+bs_python_utils/numerical/bs_derivs.py
 bs_python_utils/numerical/bs_sparse_gaussian.py
 bs_python_utils/numerical/bsnputils.py
 bs_python_utils/numerical/bssputils.py
@@ -77,6 +79,7 @@ bs_python_utils/viz/bs_seaborn.py
 bs_python_utils/viz/bsmplutils.py
 bs_python_utils/viz/streamlit_utils.py
 tests/test_bivariate_quantiles.py
+tests/test_bs_derivs.py
 tests/test_bs_opt.py
 tests/test_bs_sparse_gaussian.py
 tests/test_bsnputils.py
@@ -86,4 +89,5 @@ tests/test_bsutils.py
 tests/test_chebyshev.py
 tests/test_nptri.py
 tests/test_random_draws.py
-tests/test_sklearn_utils.py
+tests/test_sklearn_utils.py
+tests/test_timer.py

{bs_python_utils-1.1.1 → bs_python_utils-1.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bs-python-utils"
-version = "1.1.1"
+version = "1.1.3"
 description = "Utilities programs for my Python code"
 readme = "README.md"
 requires-python = ">=3.13"

bs_python_utils-1.1.3/tests/test_bs_derivs.py

@@ -0,0 +1,365 @@
+import math
+from math import cos, exp, pi, sin
+
+from bs_python_utils.numerical.bs_derivs import (
+    richardson_derivative,
+    richardson_second_derivative,
+)
+
+
+class TestRichardsonDerivative:
+    """Tests for richardson_derivative function."""
+
+    def test_linear_function(self):
+        """First derivative of ax + b is a."""
+
+        # f(x) = 2x + 3, f'(x) = 2
+        def f(x, args):
+            return 2 * x + 3
+
+        x = 1.0
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        assert math.isclose(result, 2.0, rel_tol=1e-10)
+
+    def test_quadratic_function(self):
+        """First derivative of x^2 is 2x."""
+
+        # f(x) = x^2, f'(x) = 2x
+        def f(x, args):
+            return x**2
+
+        x = 3.0
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = 2 * x
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_cubic_function(self):
+        """First derivative of x^3 is 3x^2."""
+
+        # f(x) = x^3, f'(x) = 3x^2
+        def f(x, args):
+            return x**3
+
+        x = 2.0
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = 3 * x**2
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_quartic_function(self):
+        """First derivative of x^4 is 4x^3."""
+
+        # f(x) = x^4, f'(x) = 4x^3
+        def f(x, args):
+            return x**4
+
+        x = 1.5
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = 4 * x**3
+        assert math.isclose(result, expected, rel_tol=1e-6)
+
+    def test_exponential_function(self):
+        """First derivative of e^x is e^x."""
+
+        # f(x) = e^x, f'(x) = e^x
+        def f(x, args):
+            return exp(x)
+
+        x = 0.5
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = exp(x)
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_sine_function(self):
+        """First derivative of sin(x) is cos(x)."""
+
+        # f(x) = sin(x), f'(x) = cos(x)
+        def f(x, args):
+            return sin(x)
+
+        x = pi / 4
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = cos(x)
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_cosine_function(self):
+        """First derivative of cos(x) is -sin(x)."""
+
+        # f(x) = cos(x), f'(x) = -sin(x)
+        def f(x, args):
+            return cos(x)
+
+        x = pi / 3
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = -sin(x)
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_with_args_parameter(self):
+        """Test that args are passed through correctly."""
+
+        # f(x, args) = a*x^2 + b*x + c where args = [a, b, c]
+        def f(x, args):
+            a, b, c = args
+            return a * x**2 + b * x + c
+
+        x = 2.0
+        h = 0.01
+        args = [3.0, 2.0, 1.0]
+        result = richardson_derivative(f, x, args, h)
+        expected = 2 * args[0] * x + args[1]  # f'(x) = 2ax + b
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_zero_at_critical_point(self):
+        """Derivative should be near zero at critical points."""
+
+        # f(x) = x^2, critical point at x = 0
+        def f(x, args):
+            return x**2
+
+        x = 0.0
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        assert abs(result) < 1e-10
+
+    def test_different_step_sizes(self):
+        """Results should be accurate with different step sizes."""
+
+        # f(x) = sin(x), f'(x) = cos(x)
+        def f(x, args):
+            return sin(x)
+
+        x = pi / 6
+        expected = cos(x)
+
+        for h in [0.1, 0.01, 0.001]:
+            result = richardson_derivative(f, x, [], h)
+            # Smaller h should generally be more accurate
+            assert math.isclose(result, expected, rel_tol=1e-5)
+
+    def test_negative_x(self):
+        """Should work correctly for negative x values."""
+
+        # f(x) = x^3, f'(x) = 3x^2
+        def f(x, args):
+            return x**3
+
+        x = -2.5
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = 3 * x**2
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_large_x(self):
+        """Should work correctly for large x values."""
+
+        # f(x) = x^2, f'(x) = 2x
+        def f(x, args):
+            return x**2
+
+        x = 100.0
+        h = 0.1
+        result = richardson_derivative(f, x, [], h)
+        expected = 2 * x
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_small_x(self):
+        """Should work correctly for small x values close to zero."""
+
+        # f(x) = x^2, f'(x) = 2x
+        def f(x, args):
+            return x**2
+
+        x = 0.001
+        h = 0.00001
+        result = richardson_derivative(f, x, [], h)
+        expected = 2 * x
+        assert math.isclose(result, expected, rel_tol=1e-6)
+
+    def test_fourth_order_accuracy(self):
+        """Richardson extrapolation should achieve fourth-order accuracy."""
+
+        # For a polynomial of degree 4 or less, the method should be exact
+        # f(x) = x^4 - 2x^3 + x^2, f'(x) = 4x^3 - 6x^2 + 2x
+        def f(x, args):
+            return x**4 - 2 * x**3 + x**2
+
+        x = 1.5
+        h = 0.01
+        result = richardson_derivative(f, x, [], h)
+        expected = 4 * x**3 - 6 * x**2 + 2 * x
+        # Fourth-order method should be very accurate for polynomials
+        assert math.isclose(result, expected, rel_tol=1e-10)
+
+
+class TestRichardsonSecondDerivative:
+    """Tests for richardson_second_derivative function."""
+
+    def test_quadratic_function(self):
+        """Second derivative of x^2 is 2."""
+
+        # f(x) = x^2, f''(x) = 2
+        def f(x, args):
+            return x**2
+
+        x = 3.0
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        assert math.isclose(result, 2.0, rel_tol=1e-6)
+
+    def test_cubic_function(self):
+        """Second derivative of x^3 is 6x."""
+
+        # f(x) = x^3, f''(x) = 6x
+        def f(x, args):
+            return x**3
+
+        x = 2.0
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        expected = 6 * x
+        assert math.isclose(result, expected, rel_tol=1e-6)
+
+    def test_quartic_function(self):
+        """Second derivative of x^4 is 12x^2."""
+
+        # f(x) = x^4, f''(x) = 12x^2
+        def f(x, args):
+            return x**4
+
+        x = 1.5
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        expected = 12 * x**2
+        assert math.isclose(result, expected, rel_tol=1e-5)
+
+    def test_exponential_function(self):
+        """Second derivative of e^x is e^x."""
+
+        # f(x) = e^x, f''(x) = e^x
+        def f(x, args):
+            return exp(x)
+
+        x = 0.5
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        expected = exp(x)
+        assert math.isclose(result, expected, rel_tol=1e-6)
+
+    def test_sine_function(self):
+        """Second derivative of sin(x) is -sin(x)."""
+
+        # f(x) = sin(x), f''(x) = -sin(x)
+        def f(x, args):
+            return sin(x)
+
+        x = pi / 4
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        expected = -sin(x)
+        assert math.isclose(result, expected, rel_tol=1e-5)
+
+    def test_cosine_function(self):
+        """Second derivative of cos(x) is -cos(x)."""
+
+        # f(x) = cos(x), f''(x) = -cos(x)
+        def f(x, args):
+            return cos(x)
+
+        x = pi / 3
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        expected = -cos(x)
+        assert math.isclose(result, expected, rel_tol=1e-5)
+
+    def test_with_args_parameter(self):
+        """Test that args are passed through correctly."""
+
+        # f(x, args) = a*x^2 + b*x + c where args = [a, b, c]
+        def f(x, args):
+            a, b, c = args
+            return a * x**2 + b * x + c
+
+        x = 2.0
+        h = 0.01
+        args = [3.0, 2.0, 1.0]
+        result = richardson_second_derivative(f, x, args, h)
+        expected = 2 * args[0]  # f''(x) = 2a
+        assert math.isclose(result, expected, rel_tol=1e-8)
+
+    def test_inflection_point(self):
+        """Second derivative should change sign at inflection point."""
+
+        # f(x) = x^3, inflection point at x = 0
+        def f(x, args):
+            return x**3
+
+        h = 0.01
+        # Before inflection point
+        result_neg = richardson_second_derivative(f, -1.0, [], h)
+        # After inflection point
+        result_pos = richardson_second_derivative(f, 1.0, [], h)
+
+        assert result_neg < 0
+        assert result_pos > 0
+
+    def test_negative_x(self):
+        """Should work correctly for negative x values."""
+
+        # f(x) = x^4, f''(x) = 12x^2
+        def f(x, args):
+            return x**4
+
+        x = -1.5
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        expected = 12 * x**2
+        assert math.isclose(result, expected, rel_tol=1e-5)
+
+    def test_large_x(self):
+        """Should work correctly for large x values."""
+
+        # f(x) = x^2, f''(x) = 2
+        def f(x, args):
+            return x**2
+
+        x = 100.0
+        h = 0.1
+        result = richardson_second_derivative(f, x, [], h)
+        assert math.isclose(result, 2.0, rel_tol=1e-5)
+
+    def test_composition_with_derivatives(self):
+        """Verify f''(x) by comparing with numerical first derivative of f'(x)."""
+
+        # f(x) = sin(x)
+        # Compute f'' using the second derivative function
+        def f(x, args):
+            return sin(x)
+
+        x = pi / 6
+        h = 0.01
+
+        second_deriv = richardson_second_derivative(f, x, [], h)
+        expected = -sin(x)
+
+        assert math.isclose(second_deriv, expected, rel_tol=1e-5)
+
+    def test_quartic_polynomial_exact(self):
+        """For degree 4 polynomial, second derivative should be very accurate."""
+
+        # f(x) = x^4 - 2x^3 + x^2 + x - 1
+        # f'(x) = 4x^3 - 6x^2 + 2x + 1
+        # f''(x) = 12x^2 - 12x + 2
+        def f(x, args):
+            return x**4 - 2 * x**3 + x**2 + x - 1
+
+        x = 1.5
+        h = 0.01
+        result = richardson_second_derivative(f, x, [], h)
+        expected = 12 * x**2 - 12 * x + 2
+        assert math.isclose(result, expected, rel_tol=1e-8)