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
Rust
Add this to your Cargo.toml:
[dependencies]
num-dual = "0.15"
Example
Python
Compute the first and second derivative of a scalar-valued function.
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.
use num_dual::*;
use nalgebra::SMatrix;
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.
- The documentation of the python package can be found here.
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
- Website about all topics regarding automatic differentiation: autodiff.org
- Our paper about dual numbers in equation of state modeling: Rehner, P. and Bauer, G., 2021
Cite us
If you find num-dual useful for your own scientific studies, consider citing our publication 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}
}
Release files for num-dual 0.15.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| num_dual-0.15.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| num_dual-0.15.0-cp310-abi3-manylinux_2_34_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.34+ x86-64 | Details |
| num_dual-0.15.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| num_dual-0.15.0-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 18.4 MB
Release files / num_dual-0.15.0-cp310-abi3-win_amd64.whl
| Download URL | num_dual-0.15.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 4.6 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
62aa3a2297fcbf8c6c6d50c50183590be20708ac7de8a1885c0d4adf20eabc1b
|
|
BLAKE2b-256 checksum How to use checksums |
14122685ae88776b5999502e06af929a25c3f133301fc4c3b2a0e2824ebd6f69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / num_dual-0.15.0-cp310-abi3-manylinux_2_34_x86_64.whl
| Download URL | num_dual-0.15.0-cp310-abi3-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 4.3 MB |
| Tags | CPython 3.10 Linux glibc 2.34+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
e6ce17dc44f09e940a243dca999ac078b1e47c1784dfb870fb556e512b395361
|
|
BLAKE2b-256 checksum How to use checksums |
5846901c43bf8235c4cd1d4622c188d7f24502c67fb9ce4a7b2177dbc5d91489
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / num_dual-0.15.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | num_dual-0.15.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 4.6 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
02cd63a17e6b08bc1f29f7e65b64b02c88071dd9e83cc97a87917dd2fded02d1
|
|
BLAKE2b-256 checksum How to use checksums |
dbe7bba3cfbb2731442606ba0a7f92a8bdac87a83fa701b6ed177041c617ca2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / num_dual-0.15.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | num_dual-0.15.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 4.9 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
4f210f8b488431833db845f73c9bfbc8ca1f10b13f3198f8a9b3ba2d83fa3980
|
|
BLAKE2b-256 checksum How to use checksums |
3409573e821839cfed10308adb9ef31f0e426658aa3d4d68cd43e07aee34377f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
