{"id":4133,"library":"numdifftools","title":"Numdifftools","description":"The numdifftools library is a suite of tools written in Python to solve automatic numerical differentiation problems in one or more variables. It employs finite differences in an adaptive manner, coupled with a Richardson extrapolation methodology, to provide maximally accurate results. The library is currently at version 0.9.42 and sees active, though not rapid, development, with the documentation for 0.9.41 updated in late 2025 and PyPI showing an update for 0.9.42 in early 2022.","status":"active","version":"0.9.42","language":"en","source_language":"en","source_url":"https://github.com/pbrod/numdifftools","tags":["numerical differentiation","calculus","gradient","jacobian","hessian","derivative","finite differences","richardson extrapolation"],"install":[{"cmd":"pip install numdifftools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Required for various scientific computing functionalities.","package":"scipy","optional":false},{"reason":"Optional: Provides an easy-to-use interface to derivatives calculated with Algorithmic Differentiation (AD).","package":"algopy","optional":true},{"reason":"Optional: Extends functionality with some tools found in statsmodels.tools.numdiff.","package":"statsmodels","optional":true}],"imports":[{"symbol":"numdifftools","correct":"import numdifftools as nd"},{"note":"Classes like Derivative, Gradient, etc., are typically accessed via the top-level 'nd' alias or imported directly, not as submodules.","wrong":"import numdifftools.Derivative","symbol":"Derivative","correct":"from numdifftools import Derivative"}],"quickstart":{"code":"import numpy as np\nimport numdifftools as nd\n\ndef f(x):\n    return x**3 + x**2\n\n# Compute the 1st derivative of f(x) at x=1\ndf = nd.Derivative(f)\nresult_df = df(1)\nprint(f\"First derivative of f(x) at x=1: {result_df}\")\n\n# Compute the 2nd derivative of f(x) at x=1\nddf = nd.Derivative(f, n=2)\nresult_ddf = ddf(1)\nprint(f\"Second derivative of f(x) at x=1: {result_ddf}\")\n\n# Compute the gradient of a multivariate function\ndef rosen(x):\n    return (1 - x[0])**2 + 100 * (x[1] - x[0]**2)**2\n\ngrad = nd.Gradient(rosen)\nresult_grad = grad([1, 1]) # At the minimum of Rosenbrock function\nprint(f\"Gradient of Rosenbrock at (1,1): {result_grad}\")","lang":"python","description":"This quickstart demonstrates how to compute the first and second derivatives of a scalar function, and the gradient of a multivariate function using `numdifftools.Derivative` and `numdifftools.Gradient`."},"warnings":[{"fix":"For non-analytic functions or those that do not support complex inputs, use 'central' or other finite difference methods by setting the `method` parameter (e.g., `nd.Derivative(func, method='central')`).","message":"The complex-step differentiation method, while highly accurate and robust to round-off errors, requires the target function to be analytic and support complex number inputs. It will fail for non-analytic functions (e.g., `abs`, `max`, `min`) or functions that do not handle complex inputs gracefully.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rely on the library's adaptive step size selection when possible. If manually setting `step`, ensure it's within a reasonable range to balance approximation and round-off errors. Monitor error estimates provided by the tools.","message":"Selecting an inappropriate step size can lead to inaccurate results. Too small a step size may introduce round-off errors, while too large a step size can increase approximation errors. Numdifftools attempts to adaptively select an optimal step size, but manual override with `step` parameter should be done cautiously.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update any custom code that directly accesses `self.f` to use `self.fun` instead. Always prefer using the public API where possible.","message":"In versions around 0.9.15 to 0.9.18, a major API change occurred where the internal class member variable `self.f` was renamed to `self.fun`. If you were subclassing `numdifftools` classes or accessing these internal variables directly, your code would break.","severity":"breaking","affected_versions":"0.9.15 to 0.9.18 onwards"},{"fix":"If encountering `ImportError` related to `scipy.ndimage.filters`, update import statements to use `scipy.ndimage` directly, or import the specific function from `scipy.ndimage` if it was moved.","message":"In version 0.9.41, there was an update where an import path from `scipy.ndimage.filters` was replaced by `scipy.ndimage`. Code relying on direct imports from the `filters` submodule of `scipy.ndimage` might encounter `ImportError`.","severity":"breaking","affected_versions":">=0.9.41"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}