## num-dual

Generalized (hyper) dual numbers for the calculation of exact (partial) derivatives

### 13 releases(7 breaking)

 0.8.1 Oct 20, 2023 May 31, 2023 Jan 20, 2023 Nov 11, 2022 Jul 26, 2021

#23 in Math

Used in 9 crates (8 directly)

MIT/Apache

240KB
5.5K SLoC

# 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.7"
``````

## 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::*;

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

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.

If you want to learn more about the topic of dual numbers and automatic differentiation, we have listed some useful resources for you here:

## 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}
}
``````

~2.7–8.5MB
~75K SLoC