JSPM – @thi.ng/dual-algebra@0.1.0

Package Exports

@thi.ng/dual-algebra

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@thi.ng/dual-algebra) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

npm downloads

This project is part of the @thi.ng/umbrella monorepo.

About
- Status
Installation
Dependencies
API
Authors
License

About

Multivariate dual number algebra, automatic differentiation.

Dual numbers are an elegant solution to compute precise⁽¹⁾ derivatives of functions which otherwise require complex & brittle numerical solutions. Furthermore, multivariate dual numbers can be used to obtain (in parallel) derivatives of multiple variables within a single function execution.

In this package, dual numbers are encoded as vanilla JS arrays with the internal structure: [real, d1 .. dn], where real is the real-valued part of the number and d1..dn multivariate derivatives. At minimum, at least d1 exists, but the number (of derivatives) depends on usage and the number of variables in a function one wishes to compute derivatives for.

⁽¹⁾ Here "precise" within the realm of IEEE-754

Some examples (see further below for code example):

[Math.PI, 0] // the scalar π as 1-dual number
[Math.PI, 1] // π as the current value of a 1-dual variable

[5, 1, 0] // 5 as first variable in 2-variable function
[3, 0, 1] // 3 as second variable in a 2-var function

[5, 1, 0, 0] // 1st var in 3-var fn
[3, 0, 1, 0] // 2nd var in 3-var fn
[2, 0, 0, 1] // 3rd var in 3-var fn

Alternatively, use convenience fns to create dual numbers:

$(5)     // [5, 0]
$(5, 1)  // [5, 1]

$2(5)    // [5, 0, 0]
$2(5, 2) // [5, 0, 1]

$3(5)    // [5, 0, 0, 0]
$3(5, 2) // [5, 0, 1, 0]

dual(5, 6)    // [5, 0, 0, 0, 0, 0, 0]
dual(5, 6, 4) // [5, 0, 0, 0, 1, 0, 0]

The following operations are available so far. Each operation takes one or more multivariate dual number(s) and computes the actual real-valued results as well as the 1st derivatives. Each op has an optimized/loop-free impl for 1-dual numbers.

add(a, b)
sub(a, b)
mul(a, b)
div(a, b)
neg(a)
abs(a)

Exponentials:

pow(a, k) (k = scalar)
sqrt(a)
exp(a)
log(a)

Trigonometry:

sin(a)
cos(a)
tan(a)
atan(a)

Status

ALPHA - bleeding edge / work-in-progress

Installation

yarn add @thi.ng/dual-algebra

// ES module
<script type="module" src="https://unpkg.com/@thi.ng/dual-algebra?module" crossorigin></script>

// UMD
<script src="https://unpkg.com/@thi.ng/dual-algebra/lib/index.umd.js" crossorigin></script>

Package sizes (gzipped, pre-treeshake): ESM: 911 bytes / CJS: 1.02 KB / UMD: 1.07 KB

Dependencies

@thi.ng/api

API

Generated API docs

import { $2, add, mul, neg, sin, evalFn2 } from "@thi.ng/dual-algebra";

// compute the actual result and derivatives of X & Y
// of this function with 2 variables:
// z = -x^2 + 3 * sin(y)

const f = (x: number, y: number) => {
    // convert to multivariate dual numbers
    const xx = $2(x, 1);
    const yy = $2(y, 2);
    // compute...
    return add(neg(mul(xx, xx)), mul($2(3), sin(yy)));
}

// `evalFn2()` is higher order fn syntax sugar to simplify
// dealing w/ scalars, here same with that wrapper:
const g = evalFn2(
    (x, y) => add(neg(mul(x, x)), mul($2(3), sin(y)))
);

f(0, 0);
// [0, 0, 3] => [f(x,y), dFdx(f(x,y)), dFdy(f(x,y))]

f(1, Math.PI);
// [-0.9999999999999997, -2, -3]

Authors

Karsten Schmidt

@thi.ng/dual-algebra