{"id":17336838,"url":"https://github.com/wesselb/fdm","last_synced_at":"2025-04-14T17:31:15.803Z","repository":{"id":57428910,"uuid":"136389144","full_name":"wesselb/fdm","owner":"wesselb","description":"Estimate derivatives with finite differences","archived":false,"fork":false,"pushed_at":"2021-02-02T08:42:54.000Z","size":6484,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-24T09:12:24.816Z","etag":null,"topics":["finite-difference","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wesselb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-06T21:41:38.000Z","updated_at":"2024-04-09T04:18:02.000Z","dependencies_parsed_at":"2022-09-08T23:50:21.605Z","dependency_job_id":null,"html_url":"https://github.com/wesselb/fdm","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesselb%2Ffdm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesselb%2Ffdm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesselb%2Ffdm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesselb%2Ffdm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wesselb","download_url":"https://codeload.github.com/wesselb/fdm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223639403,"owners_count":17177816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["finite-difference","python"],"created_at":"2024-10-15T15:32:40.641Z","updated_at":"2025-04-14T17:31:15.793Z","avatar_url":"https://github.com/wesselb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [FDM: Finite Difference Methods](http://github.com/wesselb/fdm)\n\n[![CI](https://github.com/wesselb/fdm/workflows/CI/badge.svg?branch=master)](https://github.com/wesselb/fdm/actions?query=workflow%3ACI)\n[![Coverage Status](https://coveralls.io/repos/github/wesselb/fdm/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/wesselb/fdm?branch=master)\n[![Latest Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://wesselb.github.io/fdm)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nFDM estimates derivatives with finite differences.\nSee also [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl).\n\n* [Installation](#installation)\n* [Multivariate Derivatives](#multivariate-derivatives)\n    - [Gradients](#gradients)\n    - [Jacobians](#jacobians)\n    - [Jacobian-Vector Products (Directional Derivatives)](#jacobian-vector-products-directional-derivatives)\n    - [Hessian-Vector Products](#hessian-vector-products)\n* [Scalar Derivatives](#scalar-derivatives)\n* [Testing Sensitivities in a Reverse-Mode Automatic Differentation Framework](#testing-sensitivities-in-a-reverse-mode-automatic-differentation-framework)\n\n## Installation\n\nFDM requires Python 3.6 or higher.\n\n```bash\npip install fdm\n```\n\n## Multivariate Derivatives\n\n```python\nfrom fdm import gradient, jacobian, jvp, hvp\n```\n\nFor the purpose of illustration, let us consider a quadratic function:\n\n```python\n\u003e\u003e\u003e a = np.random.randn(3, 3); a = a @ a.T\n\u003e\u003e\u003e a\narray([[ 3.57224794,  0.22646662, -1.80432262],\n       [ 0.22646662,  4.72596213,  3.46435663],\n       [-1.80432262,  3.46435663,  3.70938152]])\n\n\u003e\u003e\u003e def f(x):\n...     return 0.5 * x @ a @ x\n```\n\nConsider the following input value:\n\n```python\n\u003e\u003e\u003e x = np.array([1.0, 2.0, 3.0])\n```\n\n### Gradients\n\n```python\n\u003e\u003e\u003e grad = gradient(f)\n\u003e\u003e\u003e grad(x)\narray([-1.38778668, 20.07146076, 16.25253519])\n\n\u003e\u003e\u003e a @ x\narray([-1.38778668, 20.07146076, 16.25253519])\n```\n\n### Jacobians\n\n```python\n\u003e\u003e\u003e jac = jacobian(f)\n\u003e\u003e\u003e jac(x)\narray([[-1.38778668, 20.07146076, 16.25253519]])\n\n\u003e\u003e\u003e a @ x\narray([-1.38778668, 20.07146076, 16.25253519])\n```\n\nBut `jacobian` also works for multi-valued functions.\n\n```python\n\u003e\u003e\u003e def f2(x):\n...     return a @ x\n\n\u003e\u003e\u003e jac2 = jacobian(f2)\n\u003e\u003e\u003e jac2(x)\narray([[ 3.57224794,  0.22646662, -1.80432262],\n       [ 0.22646662,  4.72596213,  3.46435663],\n       [-1.80432262,  3.46435663,  3.70938152]])\n\n\u003e\u003e\u003e a\narray([[ 3.57224794,  0.22646662, -1.80432262],\n       [ 0.22646662,  4.72596213,  3.46435663],\n       [-1.80432262,  3.46435663,  3.70938152]])\n```\n\n### Jacobian-Vector Products (Directional Derivatives)\n\nIn the scalar case, `jvp` computes directional derivatives:\n\n```python\n\u003e\u003e\u003e v = np.array([0.5, 0.6, 0.7])  # A direction\n\n\u003e\u003e\u003e dir_deriv = jvp(f, v)\n\u003e\u003e\u003e dir_deriv(x)\n22.725757753354657\n\n\u003e\u003e\u003e np.sum(grad(x) * v)\n22.72575775335481\n```\n\nIn the multivariate case, `jvp` generalises to Jacobian-vector products:\n\n```python\n\u003e\u003e\u003e prod = jvp(f2, v)\n\u003e\u003e\u003e prod(x)\narray([0.65897811, 5.37386023, 3.77301973])\n\n\u003e\u003e\u003e a @ v\narray([0.65897811, 5.37386023, 3.77301973])\n```\n\n### Hessian-Vector Products\n\n```python\n\u003e\u003e\u003e prod = hvp(f, v)\n\u003e\u003e\u003e prod(x)\narray([[0.6589781 , 5.37386023, 3.77301973]])\n\n\u003e\u003e\u003e 0.5 * (a + a.T) @ v\narray([0.65897811, 5.37386023, 3.77301973])\n```\n\n## Scalar Derivatives\n```python\n\u003e\u003e\u003e from fdm import central_fdm\n```\n\nLet's try to estimate the first derivative of `np.sin` at `1` with a\nsecond-order method.\n\n```python\n\u003e\u003e\u003e central_fdm(order=2, deriv=1)(np.sin, 1) - np.cos(1)\n-1.2914319613699377e-09\n```\n\nAnd let's try to estimate the second derivative of `np.sin` at `1` with a\nthird-order method.\n\n```python\n\u003e\u003e\u003e central_fdm(order=3, deriv=2)(np.sin, 1) + np.sin(1)\n1.6342919018086377e-08\n```\n\nHm.\nLet's check the accuracy of this third-order method.\nThe step size and accuracy of the method are computed upon calling\n`FDM.estimate`.\n\n```python\n\u003e\u003e\u003e central_fdm(order=3, deriv=2).estimate(np.sin, 1).acc\n5.476137293912896e-06\n```\n\nWe might want a little more accuracy. Let's check the accuracy of a\nfifth-order method.\n\n```python\n\u003e\u003e\u003e central_fdm(order=5, deriv=2).estimate(np.sin, 1).acc\n7.343652562575157e-10\n```\n\nAnd let's estimate the second derivative of `np.sin` at `1` with a\nfifth-order method.\n\n```python\n\u003e\u003e\u003e central_fdm(order=5, deriv=2)(np.sin, 1) + np.sin(1)\n-1.7121615236703747e-10\n```\n\nHooray!\n\nFinally, let us verify that increasing the order generally increases the accuracy.\n\n```python\n\u003e\u003e\u003e for i in range(3, 10):\n...      print(central_fdm(order=i, deriv=2)(np.sin, 1) + np.sin(1))\n1.6342919018086377e-08\n8.604865264771888e-09\n-1.7121615236703747e-10\n8.558931341440257e-12\n-2.147615418834903e-12\n6.80566714095221e-13\n-1.2434497875801753e-14\n```\n\n## Testing Sensitivities in a Reverse-Mode Automatic Differentation Framework\n\nConsider the function\n\n```python\ndef mul(a, b):\n    return a * b\n```\n\nand its sensitivity\n\n```python\ndef s_mul(s_y, y, a, b):\n    return s_y * b, a * s_y\n```\n\nThe sensitivity `s_mul` takes in the sensitivity `s_y` of the output `y`,\nthe output `y`, and  the arguments of the function `mul`; and returns a tuple\ncontaining the sensitivities with respect to `a` and `b`.\nThen function `check_sensitivity` can be used to assert that the\nimplementation of `s_mul` is correct:\n\n```python\n\u003e\u003e\u003e from fdm import check_sensitivity\n\n\u003e\u003e\u003e check_sensitivity(mul, s_mul, (2, 3))  # Test at arguments `2` and `3`.\n```\n\nSuppose that the implementation were wrong, for example\n\n```python\ndef s_mul_wrong(s_y, y, a, b):\n    return s_y * b, b * s_y  # Used `b` instead of `a` for the second sensitivity!\n```\n\nThen `check_sensitivity` should throw an `AssertionError`:\n\n```python\n\u003e\u003e\u003e check_sensitivity(mul, s_mul, (2, 3))\nAssertionError: Sensitivity of argument 2 of function \"mul\" did not match numerical estimate.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesselb%2Ffdm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwesselb%2Ffdm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesselb%2Ffdm/lists"}