Skip to main content

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

Project description

num-dual

crate documentation minimum rustc 1.81 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.10"

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

    // 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:

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

num_dual-0.10.3-cp37-abi3-win_amd64.whl (3.7 MB view details)

Uploaded CPython 3.7+ Windows x86-64

num_dual-0.10.3-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ x86-64

num_dual-0.10.3-cp37-abi3-macosx_11_0_arm64.whl (2.9 MB view details)

Uploaded CPython 3.7+ macOS 11.0+ ARM64

num_dual-0.10.3-cp37-abi3-macosx_10_12_x86_64.whl (3.4 MB view details)

Uploaded CPython 3.7+ macOS 10.12+ x86-64

File details

Details for the file num_dual-0.10.3-cp37-abi3-win_amd64.whl.

File metadata

  • Download URL: num_dual-0.10.3-cp37-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.7 MB
  • Tags: CPython 3.7+, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for num_dual-0.10.3-cp37-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 6352c4c5a44ad23dab99ff7fa5e8009fb2bd76de4ca59db20337291165ed6308
MD5 fcb7b67de0ae5fe6791d954e1dd25281
BLAKE2b-256 7a64ad768978ee9eb4e9c68e5a0af14e0d53007cd8dc52564cc5afc584025819

See more details on using hashes here.

File details

Details for the file num_dual-0.10.3-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for num_dual-0.10.3-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 34025851a906e44531f9b571113e39abd24df4b5c7213b20bb9ead2a0373c9d8
MD5 1e257e87616b2d6877684addbcb3a909
BLAKE2b-256 283bd8f5332339014b3bd09c892b53bfb01bcad0cc909c8f57b5d84be16bb351

See more details on using hashes here.

File details

Details for the file num_dual-0.10.3-cp37-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for num_dual-0.10.3-cp37-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c7714e8c52a2c17ab6404e5a5684413b817536be9c9ac01e87ddf32da5a36fe8
MD5 e76fa3a373ba2300a6a1fadc33d39e0d
BLAKE2b-256 3936a26199b3bfae17bc7bdbadf48d32d0eab7c858f023d40ecc4f7e7f4de3dc

See more details on using hashes here.

File details

Details for the file num_dual-0.10.3-cp37-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for num_dual-0.10.3-cp37-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e2353e79df5a6fe9feb6895e5750af79313d1328081ed838015667ae42a9c9e2
MD5 f1e0e536fdc28b08a877a8793d5c4872
BLAKE2b-256 be432784e296bb60a014114972703c732a5e93b91c7897f61b8b9bcc7bb1b3b4

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page