# num-dual
[](https://crates.io/crates/num-dual)
[](https://docs.rs/num-dual)
[](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
[](https://itt-ustutt.github.io/num-dual/)
[](https://badge.fury.io/py/num_dual)
Generalized, recursive, scalar and vector (hyper) dual numbers for the automatic and exact calculation of (partial) derivatives.
Including bindings for python.
## Installation and Usage
### Python
The python package can be installed directly from PyPI:
```
pip install num_dual
```
[//]: # "or from source (you need a rust compiler for that):"
[//]: # "```"
[//]: # "pip install git+https://github.com/itt-ustutt/num-dual"
[//]: # "```"
### Rust
Add this to your `Cargo.toml`:
```toml
[dependencies]
num-dual = "0.7"
```
## Example
### Python
Compute the first and second derivative of a scalar-valued function.
```python
from num_dual import second_derivative
import numpy as np
def f(x):
return np.exp(x) / np.sqrt(np.sin(x)**3 + np.cos(x)**3)
f, df, d2f = second_derivative(f, 1.5)
print(f'f(x) = {f}')
print(f'df/dx = {df}')
print(f'd2f/dx2 = {d2f}')
```
### Rust
This example defines a generic function that can be called using any (hyper) dual number and automatically calculates derivatives.
```rust
use num_dual::*;
fn f<D: DualNum<f64>>(x: D, y: D) -> D {
x.powi(3) * y.powi(2)
}
fn main() {
let (x, y) = (5.0, 4.0);
// Calculate a simple derivative using dual numbers
let x_dual = Dual64::from(x).derivative();
let y_dual = Dual64::from(y);
println!("{}", f(x_dual, y_dual)); // 2000 + [1200]ε
// or use the provided function instead
let (_, df) = first_derivative(|x| f(x, y.into()), x);
println!("{df}"); // 1200
// Calculate a gradient
let (value, grad) = gradient(|v| f(v[0], v[1]), SMatrix::from([x, y]));
println!("{value} {grad}"); // 2000 [1200, 1000]
// Calculate a Hessian
let (_, _, hess) = hessian(|v| f(v[0], v[1]), SMatrix::from([x, y]));
println!("{hess}"); // [[480, 600], [600, 250]]
// for x=cos(t) and y=sin(t) calculate the third derivative w.r.t. t
let (_, _, _, d3f) = third_derivative(|t| f(t.cos(), t.sin()), 1.0);
println!("{d3f}"); // 7.358639755305733
}
```
## Documentation
- You can find the documentation of the rust crate [here](https://docs.rs/num-dual/).
- The documentation of the python package can be found [here](https://itt-ustutt.github.io/num-dual/).
### Python
For the following commands to work you have to have the package installed (see: installing from source).
```
cd docs
make html
```
Open `_build/html/index.html` in your browser.
## Further reading
If you want to learn more about the topic of dual numbers and automatic differentiation, we have listed some useful resources for you here:
- Initial paper about hyper-dual numbers: [Fike, J. and Alonso, J., 2011](https://arc.aiaa.org/doi/abs/10.2514/6.2011-886)
- Website about all topics regarding automatic differentiation: [autodiff.org](http://www.autodiff.org/)
- Our paper about dual numbers in equation of state modeling: [Rehner, P. and Bauer, G., 2021](https://www.frontiersin.org/article/10.3389/fceng.2021.758090)
## Cite us
If you find `num-dual` useful for your own scientific studies, consider [citing our publication](https://www.frontiersin.org/article/10.3389/fceng.2021.758090) accompanying this library.
```
@ARTICLE{rehner2021,
AUTHOR={Rehner, Philipp and Bauer, Gernot},
TITLE={Application of Generalized (Hyper-) Dual Numbers in Equation of State Modeling},
JOURNAL={Frontiers in Chemical Engineering},
VOLUME={3},
YEAR={2021},
URL={https://www.frontiersin.org/article/10.3389/fceng.2021.758090},
DOI={10.3389/fceng.2021.758090},
ISSN={2673-2718}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/itt-ustutt/num-dual",
"name": "num-dual",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "mathematics, numerics, differentiation",
"author": "Gernot Bauer <bauer@itt.uni-stuttgart.de>, Philipp Rehner <prehner@ethz.ch>",
"author_email": "Gernot Bauer <bauer@itt.uni-stuttgart.de>, Philipp Rehner <prehner@ethz.ch>",
"download_url": null,
"platform": null,
"description": "# num-dual\n\n[](https://crates.io/crates/num-dual)\n[](https://docs.rs/num-dual)\n[](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)\n[](https://itt-ustutt.github.io/num-dual/)\n[](https://badge.fury.io/py/num_dual)\n\nGeneralized, recursive, scalar and vector (hyper) dual numbers for the automatic and exact calculation of (partial) derivatives.\nIncluding bindings for python.\n\n\n## Installation and Usage\n\n### Python\n\nThe python package can be installed directly from PyPI:\n```\npip install num_dual\n```\n[//]: # \"or from source (you need a rust compiler for that):\"\n[//]: # \"```\"\n[//]: # \"pip install git+https://github.com/itt-ustutt/num-dual\"\n[//]: # \"```\"\n\n### Rust\n\nAdd this to your `Cargo.toml`:\n\n```toml\n[dependencies]\nnum-dual = \"0.7\"\n```\n\n## Example\n\n### Python\n\nCompute the first and second derivative of a scalar-valued function.\n\n```python\nfrom num_dual import second_derivative\nimport numpy as np\n\ndef f(x):\n return np.exp(x) / np.sqrt(np.sin(x)**3 + np.cos(x)**3)\n\nf, df, d2f = second_derivative(f, 1.5)\n\nprint(f'f(x) = {f}')\nprint(f'df/dx = {df}')\nprint(f'd2f/dx2 = {d2f}')\n```\n\n### Rust\nThis example defines a generic function that can be called using any (hyper) dual number and automatically calculates derivatives.\n```rust\nuse num_dual::*;\n\nfn f<D: DualNum<f64>>(x: D, y: D) -> D {\n x.powi(3) * y.powi(2)\n}\n\nfn main() {\n let (x, y) = (5.0, 4.0);\n // Calculate a simple derivative using dual numbers\n let x_dual = Dual64::from(x).derivative();\n let y_dual = Dual64::from(y);\n println!(\"{}\", f(x_dual, y_dual)); // 2000 + [1200]\u03b5\n\n // or use the provided function instead\n let (_, df) = first_derivative(|x| f(x, y.into()), x);\n println!(\"{df}\"); // 1200\n\n // Calculate a gradient\n let (value, grad) = gradient(|v| f(v[0], v[1]), SMatrix::from([x, y]));\n println!(\"{value} {grad}\"); // 2000 [1200, 1000]\n\n // Calculate a Hessian\n let (_, _, hess) = hessian(|v| f(v[0], v[1]), SMatrix::from([x, y]));\n println!(\"{hess}\"); // [[480, 600], [600, 250]]\n\n // for x=cos(t) and y=sin(t) calculate the third derivative w.r.t. t\n let (_, _, _, d3f) = third_derivative(|t| f(t.cos(), t.sin()), 1.0);\n println!(\"{d3f}\"); // 7.358639755305733\n}\n```\n\n## Documentation\n\n- You can find the documentation of the rust crate [here](https://docs.rs/num-dual/).\n- The documentation of the python package can be found [here](https://itt-ustutt.github.io/num-dual/).\n\n### Python\n\nFor the following commands to work you have to have the package installed (see: installing from source).\n\n```\ncd docs\nmake html\n```\nOpen `_build/html/index.html` in your browser.\n\n## Further reading\n\nIf you want to learn more about the topic of dual numbers and automatic differentiation, we have listed some useful resources for you here:\n\n- Initial paper about hyper-dual numbers: [Fike, J. and Alonso, J., 2011](https://arc.aiaa.org/doi/abs/10.2514/6.2011-886)\n- Website about all topics regarding automatic differentiation: [autodiff.org](http://www.autodiff.org/)\n- Our paper about dual numbers in equation of state modeling: [Rehner, P. and Bauer, G., 2021](https://www.frontiersin.org/article/10.3389/fceng.2021.758090)\n\n## Cite us\n\nIf you find `num-dual` useful for your own scientific studies, consider [citing our publication](https://www.frontiersin.org/article/10.3389/fceng.2021.758090) accompanying this library.\n\n```\n@ARTICLE{rehner2021,\n AUTHOR={Rehner, Philipp and Bauer, Gernot},\n TITLE={Application of Generalized (Hyper-) Dual Numbers in Equation of State Modeling},\n JOURNAL={Frontiers in Chemical Engineering},\n VOLUME={3},\n YEAR={2021},\n URL={https://www.frontiersin.org/article/10.3389/fceng.2021.758090},\n DOI={10.3389/fceng.2021.758090},\n ISSN={2673-2718}\n}\n```\n\n",
"bugtrack_url": null,
"license": "MIT OR Apache-2.0",
"summary": "Generalized (hyper) dual numbers for the calculation of exact (partial) derivatives",
"version": "0.9.1",
"project_urls": {
"Homepage": "https://github.com/itt-ustutt/num-dual",
"Source Code": "https://github.com/itt-ustutt/num-dual"
},
"split_keywords": [
"mathematics",
" numerics",
" differentiation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6cd2391f28e86539dc1cb07f94921f98c142948c71871b1606ebef3c0d8e127a",
"md5": "cc074d82dd5a343b5085400dc25ab09d",
"sha256": "2a7dae62b238572c84604e21d42b6f24d9b6771eb66e770c8a04149fe8684190"
},
"downloads": -1,
"filename": "num_dual-0.9.1-cp37-abi3-macosx_10_7_x86_64.whl",
"has_sig": false,
"md5_digest": "cc074d82dd5a343b5085400dc25ab09d",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 3242965,
"upload_time": "2024-04-16T09:32:56",
"upload_time_iso_8601": "2024-04-16T09:32:56.573221Z",
"url": "https://files.pythonhosted.org/packages/6c/d2/391f28e86539dc1cb07f94921f98c142948c71871b1606ebef3c0d8e127a/num_dual-0.9.1-cp37-abi3-macosx_10_7_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fca1b8fa57c12b0d75b56d7c8e9c4d81123e562ca5454beda1a26c50b8875df4",
"md5": "18e81cd935f4b09737fb4a121322270e",
"sha256": "8e97f95dd260e144f4344444c056d43cce7afbfc4dac2f58697bead89f23c137"
},
"downloads": -1,
"filename": "num_dual-0.9.1-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl",
"has_sig": false,
"md5_digest": "18e81cd935f4b09737fb4a121322270e",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 5977116,
"upload_time": "2024-04-16T09:32:58",
"upload_time_iso_8601": "2024-04-16T09:32:58.449913Z",
"url": "https://files.pythonhosted.org/packages/fc/a1/b8fa57c12b0d75b56d7c8e9c4d81123e562ca5454beda1a26c50b8875df4/num_dual-0.9.1-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f78066ed8d027628817fb0a7b781bebd0acda4216225daee8e80f959c768b26b",
"md5": "ccb3833c409bfe2e701e41bff2367ecd",
"sha256": "bcb626b120ef11ec9d6c093759d898385ba46421968c4f69df21ac8f69904a28"
},
"downloads": -1,
"filename": "num_dual-0.9.1-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "ccb3833c409bfe2e701e41bff2367ecd",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 3111912,
"upload_time": "2024-04-16T09:33:01",
"upload_time_iso_8601": "2024-04-16T09:33:01.247465Z",
"url": "https://files.pythonhosted.org/packages/f7/80/66ed8d027628817fb0a7b781bebd0acda4216225daee8e80f959c768b26b/num_dual-0.9.1-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5c44a27016f62decc390652ef0ba8b4dfa58c435f49ed4191c47b3bcb144cadc",
"md5": "64caf912bf47d09eeea64920e568ab02",
"sha256": "45b95118173f371eccc7b900433430c43af68c2a934afd6bd27d8012d183512b"
},
"downloads": -1,
"filename": "num_dual-0.9.1-cp37-abi3-win32.whl",
"has_sig": false,
"md5_digest": "64caf912bf47d09eeea64920e568ab02",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 3053672,
"upload_time": "2024-04-16T09:33:03",
"upload_time_iso_8601": "2024-04-16T09:33:03.671462Z",
"url": "https://files.pythonhosted.org/packages/5c/44/a27016f62decc390652ef0ba8b4dfa58c435f49ed4191c47b3bcb144cadc/num_dual-0.9.1-cp37-abi3-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e765b9e31fd63d8ffbbbc6f16c024c75562581d9a12e83805920fa95ce355d1c",
"md5": "592b1fe9d3eba07765fa3e605b40d554",
"sha256": "081e97a1121e0bfc7f4e2321ee551a1c86ccba31704b09d3e8022d25f07ef1ec"
},
"downloads": -1,
"filename": "num_dual-0.9.1-cp37-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "592b1fe9d3eba07765fa3e605b40d554",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 3354411,
"upload_time": "2024-04-16T09:33:06",
"upload_time_iso_8601": "2024-04-16T09:33:06.056499Z",
"url": "https://files.pythonhosted.org/packages/e7/65/b9e31fd63d8ffbbbc6f16c024c75562581d9a12e83805920fa95ce355d1c/num_dual-0.9.1-cp37-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-16 09:32:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "itt-ustutt",
"github_project": "num-dual",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "num-dual"
}
JSON
