Fb1_ODEintdef | SuperCollider 3.13.0 Help

Description

For the optional definition of ODE integration procedures that can then be used with Fb1_ODE. This is an advanced feature, the built-in symplectic procedures should suffice for most use cases. See the source code in Fb1_ODEintdef.sc for the way integrators are defined and Fb1_ODE for general information about Fb1 ODE integrator UGens.

HISTORY AND CREDITS: Big credit to David Pirrò from IEM Graz for pointing me to the symplectic integration methods, which are essential for audifying ODEs, as they help to ensure numeric stability in the long run (e.g. to avoid drifts of oscillations that are mathematically expected to be regular). See the chapter on integration in his dissertation [2], pp 135-146. You might also want check David Pirròs optimized ODE compiler named Henri [3]. Big credit also to Nathaniel Virgo who brought up the buffering strategy used in Fb1, which is Fb1_ODE's working horse.

WARNING: Especially with self-defined ODEs the usage of this class is – inherently – highly experimental. Be careful with amplitudes, as always with feedback it can become loud! Sudden blowups might result form the mathematical characteristics of the ODE systems or they might come from parameter changes on which ODEs can react extremely sensitive to, they can also stem from numerical accumulation effects. It is highly recommended to take precautionary measures, e.g. by limiting/distorting operators (tanh, clip, softclip, distort) with the compose option (See Fb1_ODE Examples 5) and/or external limiting and/or using MasterFX from the JITLibExtensions quark.

NOTE: Fb1_ODE in its plain form (without tMul modulation, use of compose etc.) produces audio data as a numerical integration of an ODE initial value problem, defined by Fb1_ODEdef and a numerical procedure, defined by Fb1_ODEintdef. This of course supposes well-defined ODE systems and it should be kept in mind that the Fb1_ODE framework doesn't perform any mathematical checks regarding the principal existence and uniqueness of a solution of a given Fb1_ODEdef.

NOTE: The convenience of direct definition of the ODE relation comes with the price of a large number of UGens involved. You might want to allow a higher number of UGens with the server option numWireBufs. For a nice workflow I'd recommended to take reduced blockSizes (e.g. 1, 2, 4, 8, 16) while experimenting as compile time is shorter, but once you have finished the design of a SynthDef it might pay going back to blocksize 32 or 64 for runtime efficiency, especially if many kr UGens are involved.

References

Trefethen, Lloyd N.; Birkisson Ásgeir; Driscoll, Tobin A. (2017): Exploring ODEs. SIAM - Society for Industrial and Applied Mathematics. Free download from: https://people.maths.ox.ac.uk/trefethen/Exploring.pdf
Pirrò, David (2017). Composing Interactions. Dissertation. Institute of Electronic Music and Acoustics, University of Music and Performing Arts Graz. Free download from: https://pirro.mur.at/media/pirro_david_composing_interactions_print.pdf
https://git.iem.at/davidpirro/henri

Class Methods

.new

Creates a new Fb1_ODEintdef object and stores it in a Dictionary for further usage with Fb1_ODE.

Arguments:

name	The name of the integration procedure, expects a Symbol. Default Fb1_ODEintdefs cannot be overwritten.
function	The implementation of the Function ("stepper") which describes the numeric procedure. It must take the arguments odeDef, t, y, dt and ... args for further ODE args and must return the new integration value(s). For evaluating the ODE function the method Fb1_ODEdef.value is used which performs the evaluation depending on its first argument.
stepDepth	Integer. Values greater than one are for multi-step procedures. Defaults to 1.
sizeFactor	Integer. 1 means that the procedure buffers only integration values, 2 means that the differential is buffered too. Defaults to 1.

.at

Returns the Fb1_ODEintdef instance of the Symbol key if it exists.

Arguments:

key

Symbol.

.keys

Returns an array of all keys of currently stored Fb1_ODEintdefs.

.postAll

Posts all keys of currently stored Fb1_ODEintdefs.

.remove

Removes the Fb1_ODEintdef of the Symbol key from the Dictionary.

Arguments:

key

Symbol.

.reset

Removes all Fb1_ODEintdefs other than the predefined ones from the Dictionary.

Instance Methods

.name

Getter for the Fb1_ODEintdef's name.

.function

Getter for the Fb1_ODEintdef's function.

.stepDepth

Getter for the Fb1_ODEintdef's stepDepth.

.sizeFactor

Getter for the Fb1_ODEintdef's sizeFactor.

Examples

// This shows how the classical 4-step Runge-Kutta is implemented,
// quite straight it follows its mathematical definition.

// t: old time
// y: old state (array)
// dt: integration step
// size: size of the ODE (not used here, but needs to be there)
// ... args is for further args of the ODE

// The odeDef argument expects the Fb1_ODEdef object.
// The evaluation of the ODE function is implemented by odeDef::value.
// This method takes a first argument i which determines the kind of evaluation:
// For i == nil it returns the evaluation value(s) as Array,
// for a number it only returns the ith component.
// The distinction is necessary as the symplectic procedures refer to
// the single components of the ODE system.

// There exist also symplectic Runge-Kutta procedures which I didn't test so far.
// they would probably also need that option.

Fb1_ODEintdef(\rk4,
    { |odeDef, t, y, dt, size ... args|
        var k1 = odeDef.(nil, t, y, *args);
        var k2 = odeDef.(nil, dt * 0.5 + t, k1 * dt * 0.5 + y, *args);
        var k3 = odeDef.(nil, dt * 0.5 + t, k2 * dt * 0.5 + y, *args);
        var k4 = odeDef.(nil, dt + t, k3 * dt + y, *args);
        ((k2 + k3) * 2 + k1 + k4) * dt / 6 + y
    }, 1, 1);

// The same procedure as '_d' variant which stores the differential
// The argument y is now passed an array of doubled size with the
// last differential values in the second half of it.
// Finally the new differential value is calculated and appended to the integration.

Fb1_ODEintdef(\rk4_d,
    { |odeDef, t, y, dt, size ... args|
        var k1, k2, k3, k4, yy, ff, yNew, fNew;
        yy = y[0..size-1];
        ff = y[size..2*size-1];
        k1 = ff;
        k2 = odeDef.(nil, dt * 0.5 + t, k1 * dt * 0.5 + yy, *args);
        k3 = odeDef.(nil, dt * 0.5 + t, k2 * dt * 0.5 + yy, *args);
        k4 = odeDef.(nil, dt + t, k3 * dt + yy, *args);
        yNew = ((k2 + k3) * 2 + k1 + k4) * dt / 6 + yy;
        fNew = odeDef.(nil, t + dt, yNew, *args);
        yNew ++ fNew
    }, 1, 2);

helpfile source: HelpSource/Classes/Fb1_ODEintdef.schelp
link::miSCellaneous_lib/Classes/Fb1_ODEintdef::

Fb1_ODEintdefExtension

Description

References

Class Methods

.new

Arguments:

.at

Arguments:

.keys

.postAll

.remove

Arguments:

.reset

Instance Methods

.name

.function

.stepDepth

.sizeFactor

Examples

Fb1_ODEintdef
Extension