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

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.11.2-cp39-abi3-win_amd64.whl (3.8 MB view details)

Uploaded CPython 3.9+Windows x86-64

num_dual-0.11.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.7 MB view details)

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

num_dual-0.11.2-cp39-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

num_dual-0.11.2-cp39-abi3-macosx_10_12_x86_64.whl (3.8 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file num_dual-0.11.2-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: num_dual-0.11.2-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.8 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.12

File hashes

Hashes for num_dual-0.11.2-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4ac15dcd34cb44877bc2bd82a2cffc5e12f1ddee2e41106238014f6c23d0caf5
MD5 4685bfae79c7b1eaeb8f8e7583eba82f
BLAKE2b-256 36102ca0fcd39eae2dd1c75e78939ba2bbfa63d7ff9d7bb3ec615b8b78056b42

See more details on using hashes here.

File details

Details for the file num_dual-0.11.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for num_dual-0.11.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2465d17022b9a8d4d3f40f23814cc85df078c25a8adaf34680682ac5e99512b0
MD5 a6e103a9457085e38fec525ea5c3676b
BLAKE2b-256 9ce08a28512ea57e729b89b1017e8bde478e9663be9c2381650472e12817c8e4

See more details on using hashes here.

File details

Details for the file num_dual-0.11.2-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for num_dual-0.11.2-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 bd04a9c39627b987fbc29fe53be142e6965058b4b6eb1104d98e4583cb4d3ebe
MD5 d04b030b40cdaa932d5d4118eaf77d7f
BLAKE2b-256 ef6a97fa56732e1588df163493137e892ed426285f15b939d25922179465ab57

See more details on using hashes here.

File details

Details for the file num_dual-0.11.2-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for num_dual-0.11.2-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ed1b8dc02d3f3b4c9d4cd017354cf627a417f2c267ea0dae4c9e6d4460793c90
MD5 f6c1c4465acfe3280ae92d2ce32e07b5
BLAKE2b-256 57d2685adabbbb515e8a3e8336657a91ee423af8fb83aaecb263737f0000d8d5

See more details on using hashes here.

Supported by

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