DerivativeNumber | SuperCollider 3.13.0 Help

Description

DerivativeNumber implements forward automatic differentiation.

It follows Jerzy Karczmarczuk 1998, "Functional differentiation of computer programs".

In order to find the derivative of a function, there are three approaches:

Numerical differentiation: one calls the function nearby and calculates the slope. This is often not reliable.
Symbolic differentiation: one applies the rules of calulus to rewrite the function definition. This may lead to very large expression and may not work for iterative procedures.
Automatic differentiation: one defines a new mathematical object that is both a value and its change (derivative). All operations are lifted to calulate both the value and, applying the chain rule, the derivative.

NOTE: This is a reasonably well-tested, but preliminary version. Names (like instance variables or argument names) and functionality may change.

Calling operations on derivatives apply the chain rule and keep track of resulting reals and derivatives:a = DerivativeNumber(4, 1); b = a.squared.cos; b.real; // cos(4 * 4) b.derivative // neg(sin(4 * 4)) * (2 * 4)

This is valid for Arrays:a = DerivativeNumber((-100..100)/100 * pi, 1); b = a.squared.cos; [b.real, b.derivative].plot(separately:true);

It is also valid for UGens:( { var a, b; a = DerivativeNumber(Line.ar(-pi, pi, 0.01), 1); b = a.squared.cos; [b.real, b.derivative] }.plot )

Class Methods

.new

Return a new instance.

Arguments:

real	The real part of the number, which may be any number class or a UGen.
derivative	The derivative part of the number, which may be any number class or a UGen.a = DerivativeNumber(2.5, -3.652); a.real; a.derivative;

.approximate

Approximate a derivative numerically where no automatic method is implemented yet. Numerical approximation may fail to converge well in some cases, so you can't rely on it.d = (0..100).normalize(-1, 1); // approximate a range of numbers a = DerivativeNumber(d, 1); b = DerivativeNumber.approximate({ |x, y, z| x.cylBesselJ(y, z) }, [a, 2, 2]); [b.real, b.derivative].plot

Instance Methods

.real

Return the real part of the number, which carries the result of any past operations.a = DerivativeNumber(2, 0.6).squared.real; // 4

.derivative

Return the derivative part of the number, which carries the derivative that follows from all past operations.a = DerivativeNumber(2, 0.6).squared.derivative; // 2.4, which is (2 * 2 * 0.6)

<

Returns true if the real part of the receiver is smaller than the real part of the argument.

.differentiationStep

A delta that can be used for approximating a derivative numerically where no automatic method is implemented yet. It can be adjusted to improve this approximation.( var steps = [0.0001, 0.001, 0.01, 0.1, 0.5]; d = (0..100).normalize(-1, 1); // approximate a range of numbers a = steps.collect { |each| DerivativeNumber(d, 1).differentiationStep_(each) }; c = a.collect { |each| DerivativeNumber.approximate({ |x, y, z| x.cylBesselJ(y, z) }, [each, 0.1, 2]) }; c.collect { |each| each.derivative }.plot.superpose_(true); )

Conversions

.asDerivative

Convert receiver to a DerivativeNumber. In this case, it is already one, so return this. For other classes, it returns DerivativeNumber(receiver, 0)// applied in mixed expressions 5 * DerivativeNumber(2, 0.3); // DerivativeNumber(10, 1.5) [1, 3, 5] * DerivativeNumber(2, 0.3); // DerivativeNumber([2, 6, 10], [0.3, 0.9, 1.5])

.asComplex

Returns a Complex with the real part as the receiver, and the imaginary part as DerivativeNumber(0, 0).// applied in mixed expressions DerivativeNumber(2, 0.3) * Complex(5, 2); // DerivativeNumber(Complex(10.0, 4.0), Complex(1.5, 0.6)) DerivativeNumber(2, 0.3) * Complex([1, 3, 5], 2); // DerivativeNumber(Complex([2.0, 6.0, 10.0], [4.0, 4.0, 4.0]), Complex([0.3, 0.9, 1.5], [0.6, 0.6, 0.6]))

.asPolar

Returns a Complex with rho (radius) as the receiver and theta as DerivativeNumber(0, 0).DerivativeNumber(2, 0.3).asPolar; // Polar(DerivativeNumber(2, 0.3), DerivativeNumber(0, 0)) // applied in mixed expressions, it returns a Complex (default in sclang) Polar(5, 0) * DerivativeNumber(2, 0.3); // DerivativeNumber(Complex(10.0, 0.0), Complex(1.5, 0.0))

.asPoint

Returns a Point with the x coordinate as the receiver and the y coordinate as DerivativeNumber(0, 0).// applied in mixed expressions Point(5, 9) * DerivativeNumber(2, 0.3); // Point(DerivativeNumber(10, 1.5), DerivativeNumber(0, 0))

Examples

// let's assume we have a composite function f of one variable x
f = { |x| (sin(x)/x) + (sin((x - pi).squared / 42pi) / 3) };
// a domain of values
d = (-100..100)/100 * 6pi;
// plot it
f.(d).plot;

// now, we want to automatically find the derivative

// for probing, we use a seed with derivative 1.0
a = DerivativeNumber(2.0, 1.0);
// at 2.0, the real part is 2^3 = 8.0 and the derivative is 3 * (2.squared) = 12:
b = cubed(a);
// test the difference: zero
b.derivative - (3 * a.real.squared)

// the real and derivatives can be arrays:
d = (-100..100)/100 * 6pi;
a = DerivativeNumber(d, 1);
// evaluate the function above for each value of the domain d
// this results in a DerivativeNumber of arrays
b = f.(a);

// plot it
[b.real, b.derivative].plot

// the same with UGens ...
(
{
    a = DerivativeNumber(Line.ar(-6pi, 6pi, 0.01), 1);
    b = f.(a);
    [b.real, b.derivative]
}.plot;
)

// ... and arrays of UGens
(
{
    a = DerivativeNumber(Line.ar(-6pi, 6pi, 0.01) * (1..3), 1);
    b = f.(a);
    [b.real, b.derivative].lace
}.plot;
)

Unit tests

You need the UnitTest class to run these.( UnitTest.runTest("TestDerivativeNumber:test_unaryOps_invariants"); UnitTest.runTest("TestDerivativeNumber:test_binaryOps_invariants"); UnitTest.runTest("TestDerivativeNumber:test_mappingOps_invariants"); UnitTest.runTest("TestDerivativeNumber:test_unaryOps_sanityCheckWithNumerical"); UnitTest.runTest("TestDerivativeNumber:test_binaryOps_sanityCheckWithNumerical"); UnitTest.runTest("TestDerivativeNumber:test_mappingOps_sanityCheckWithNumerical"); UnitTest.runTest("TestDerivativeNumber:test_chainRuleN_withPow"); UnitTest.runTest("TestDerivativeNumber:test_parametricCurve_1"); UnitTest.runTest("TestDerivativeNumber:test_parametricSurface_1"); UnitTest.runTest("TestDerivativeNumber:test_partialDerivatives"); UnitTest.runTest("TestDerivativeNumber:test_specialTrigonometric_invariants"); )

helpfile source: HelpSource/DerivativeNumber.schelp
link::DerivativeNumber/DerivativeNumber::

DerivativeNumberExtension