0.4.70 • Published 11 days ago

@thi.ng/dual-algebra v0.4.70

Weekly downloads
4
License
Apache-2.0
Repository
github
Last release
11 days ago

dual-algebra

npm version npm downloads Twitter Follow

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

About

Multivariate dual number algebra, automatic differentiation.

(Package name with hat tip to @paniq)

Dual numbers are an elegant solution to compute precise(1) 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.

(1) 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)

Polynomials:

  • quadratic(x, a, b, c)ax^2 + bx + c
  • cubic(x, a, b, c, d)ax^3 + bx^2 + cx + d
  • quartic(x, a, b, c, d, e)ax^4 + bx^3 + cx^2 + dx + e

For each polynomial, there're scalar versions available too, taking only rational numbers as arguments (rather than dual numbers already). These versions are suffixed with S (for "scalar"): quadraticS, cubicS and quarticS...

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Related packages

Installation

yarn add @thi.ng/dual-algebra

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/dual-algebra"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const dualAlgebra = await import("@thi.ng/dual-algebra");

Package sizes (gzipped, pre-treeshake): ESM: 1.00 KB

Dependencies

Usage examples

Several demos in this repo's /examples directory are using this package.

A selection:

ScreenshotDescriptionLive demoSource
Compute cubic spline position & tangent using Dual NumbersDemoSource

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))]

g(0, 0);
// [0, 0, 3]

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

Polynomial example (see interactive graph of this function):

import { add, mul, pow, cubicS } from "@thi.ng/dual-algebra";

// compute the cubic polynomial: f(x) = 2x^3 - 3x^2 - 4x + 5

// using `cubicS()` polynomial helper
const f1 = (x: number) => cubicS(x, 2, -3, -4, 5);

// ...or expanded out
const f2 = (x: number) =>
    add(
        add(
            add(
                mul([2, 0], pow([x, 1], 3)),
                mul([-3, 0], pow([x, 1], 2))
            ),
            mul([-4, 0], [x, 1])
        ),
        [5, 0]
    );

f2(0) // [5, -4] [f(x), dFdx(f(x))]
f2(1) // [0, -4]
f2(2) // [1, 8]

Authors

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-dual-algebra,
  title = "@thi.ng/dual-algebra",
  author = "Karsten Schmidt",
  note = "https://thi.ng/dual-algebra",
  year = 2020
}

License

© 2020 - 2021 Karsten Schmidt // Apache Software License 2.0

0.4.70

11 days ago

0.4.69

14 days ago

0.4.68

23 days ago

0.4.67

26 days ago

0.4.66

1 month ago

0.4.65

2 months ago

0.4.64

2 months ago

0.4.63

2 months ago

0.4.62

2 months ago

0.4.61

2 months ago

0.4.60

2 months ago

0.4.59

2 months ago

0.4.58

2 months ago

0.4.57

3 months ago

0.4.54

3 months ago

0.4.55

3 months ago

0.4.56

3 months ago

0.4.52

3 months ago

0.4.51

3 months ago

0.4.49

4 months ago

0.4.50

4 months ago

0.4.48

5 months ago

0.4.47

5 months ago

0.4.46

5 months ago

0.4.45

5 months ago

0.4.44

5 months ago

0.4.42

6 months ago

0.4.43

5 months ago

0.4.40

6 months ago

0.4.39

6 months ago

0.4.37

9 months ago

0.4.38

8 months ago

0.4.35

9 months ago

0.4.36

9 months ago

0.4.33

9 months ago

0.4.32

11 months ago

0.4.31

12 months ago

0.4.30

1 year ago

0.4.28

1 year ago

0.4.29

1 year ago

0.4.27

1 year ago

0.4.26

1 year ago

0.4.25

1 year ago

0.4.23

1 year ago

0.4.20

1 year ago

0.4.21

1 year ago

0.4.22

1 year ago

0.4.19

1 year ago

0.4.17

1 year ago

0.4.18

1 year ago

0.4.15

2 years ago

0.4.16

1 year ago

0.4.13

2 years ago

0.4.14

2 years ago

0.4.12

2 years ago

0.4.11

2 years ago

0.4.9

2 years ago

0.4.8

2 years ago

0.4.10

2 years ago

0.4.7

2 years ago

0.4.6

2 years ago

0.4.5

2 years ago

0.4.4

2 years ago

0.3.8

2 years ago

0.4.1

2 years ago

0.4.0

2 years ago

0.4.3

2 years ago

0.4.2

2 years ago

0.3.7

3 years ago

0.3.6

3 years ago

0.3.4

3 years ago

0.3.0

3 years ago

0.3.2

3 years ago

0.3.1

3 years ago

0.3.3

3 years ago

0.2.0

3 years ago

0.1.18

3 years ago

0.1.16

3 years ago

0.1.17

3 years ago

0.1.15

3 years ago

0.1.14

3 years ago

0.1.13

3 years ago

0.1.12

3 years ago

0.1.10

3 years ago

0.1.11

3 years ago

0.1.8

3 years ago

0.1.9

3 years ago

0.1.7

3 years ago

0.1.6

3 years ago

0.1.5

3 years ago

0.1.4

3 years ago

0.1.3

3 years ago

0.1.2

3 years ago

0.1.1

4 years ago

0.1.0

4 years ago