#mathematics #numerics #differentiation

num-dual

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

8 releases (4 breaking)

0.5.2 May 23, 2022
0.5.1 Mar 9, 2022
0.4.1 Dec 20, 2021
0.3.0 Aug 10, 2021
0.1.0 Jul 7, 2021

#29 in Math

Download history 120/week @ 2022-04-20 68/week @ 2022-04-27 167/week @ 2022-05-04 168/week @ 2022-05-11 86/week @ 2022-05-18 67/week @ 2022-05-25 141/week @ 2022-06-01 389/week @ 2022-06-08 34/week @ 2022-06-15 93/week @ 2022-06-22 107/week @ 2022-06-29 86/week @ 2022-07-06 180/week @ 2022-07-13 35/week @ 2022-07-20 157/week @ 2022-07-27 255/week @ 2022-08-03

628 downloads per month
Used in fewer than 6 crates

MIT/Apache

215KB
3K SLoC

num-dual

crate documentation minimum rustc 1.51 documentation PyPI version

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.5"

Example

Python

Compute the first and second derivative of a scalar-valued function.

from num_dual import derive2
import numpy as np

def f(x):
    return np.exp(x) / np.sqrt(np.sin(x)**3 + np.cos(x)**3)

x = derive2(1.5)
result = f(x)
print('f(x)    = {}'.format(result.value))
print('df/dx   = {}'.format(result.first_derivative))
print('d2f/dx2 = {}'.format(result.second_derivative))

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
    let x_dual = Dual64::from(x).derive();
    let y_dual = Dual64::from(y);
    println!("{}", f(x_dual, y_dual));                      // 2000 + [1200]ε
    // Calculate a gradient
    let xy_dual_vec = StaticVec::new_vec([x,y]).map(DualVec64::<2>::from).derive();
    println!("{}", f(xy_dual_vec[0], xy_dual_vec[1]).eps);  // [1200, 1000]
    // Calculate a Hessian
    let xy_dual2 = StaticVec::new_vec([x,y]).map(Dual2Vec64::<2>::from).derive();
    println!("{}", f(xy_dual2[0], xy_dual2[1]).v2);         // [[480, 600], [600, 250]]
    // for x=cos(t) and y=sin(t) calculate the third derivative w.r.t. t
    let t = Dual3_64::from(1.0).derive();
    println!("{}", f(t.cos(), t.sin()).v3);                 // 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:

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

Dependencies

~0.1–5.5MB
~90K SLoC