[deutsch]

Integrating ordinary differential equations (ODE)

The function kontrast.integrateODE numerically integrates ordinary differential equations (ODEs).

The function can work with a single ODE or with a multidimensional set of ODEs. The ODE may arbitrarily depend on various parameters. Particularly, the solver is not limited to linear problems. The numerical algorithm that is being used is a fourth-order Runge-Kutta method.

The solver works with numerical problems that can be written in the form:

\dot{\vec f}(t, \vec x, \dot{\vec x})

The set of functions f_i may depend on a one-dimensional parameter t, the values x_i and the derivatives \dot x_i.

Derivative input

There are two different ways of specifying the set of differential equations to the solver: You can use a derivative callback function or use the Kontrast math parser.

The advantage of the derivative callback is that you can re-use existing JavaScript code and you can easily handle complex conditional logic. However, you can only use the solver to solve a real set of equations, not a complex set. Moreover, you can only use the solver in the blocking mode.

Using the math parser has the advantage of integrating the differential equations in the background (when using the callback or promise modes). Moreover, by setting the numberType property to 'complex' you can integrate differential equations directly in the complex plane.

Using a derivative callback

The example below solves the differential equation

\frac{\partial N}{\partial t} = -k N\,.

The solution is the quantity N as function of time t in the interval 0\leq t\leq 10, evenly distributed among 1001 values (1000 plus 1, because the starting point is included) that are returned as arrays of numbers for both t and N.

Using the Kontrast math parser

The example solves the same differential equation as above and outputs the exact same quantities.

Interactive code example

Input

The function is called as kontrast.integrateODE(options), where options is an object with the following properties:

  • quantities: object
    A description of the quantities used in the function. The property names are used as names for the quantities.
  • numberType: 'real' | 'complex' (default value: 'real')
    This switch determines whether the calculation is using real numbers or complex numbers.
  • algorithm: 'runge-kutta-4' (default value: 'runge-kutta-4')
    The used algorithm. Currently, only the Runge-Kutta (fourth order) algorithm is implemented.
  • derivativeCallback: function (optional)
    A callback function in which you can specify the derivative for each quantity. If specified, this function is invoked multiple times per simulation step. If you specify a derivative callback, you must not specify the property derivative of the dependent quantities.
  • mode: 'block' | 'promise' | 'callback' (default value: 'block')
    In mode 'block', the function performs the calculation and returns when the calculation is finished. In mode 'callback', the function returns immediately and calls the callbacks resolve and reject, when it has finished. In mode 'promise', the function returns a promise that resolves with the result.
  • resolve: function
    This function is called when the mode is 'callback' and the function succeeded. The result object is passed as a single argument.
  • reject: function
    This function is called when the mode is 'callback' and the function failed.

Quantities

Each quantity specifies a variable or constant for the integration of the ODE. You need to specify one (and only one) quantity of type 'independent', whereas you can specify as many 'dependent' and 'constant' quantities as your problem requires. Quantities are specified as objects with the properties described below.

  • type: 'independent' | 'dependent' | 'constant'
    Type of the quantity. Note that there can be only one independent quantity and that there must be at least one dependent quantity.
  • initial: number | complexNumber
    Initial value. Required for the independent quantity and all dependent quantities.
  • final: number
    Final value. Required for the independent quantity.
  • count: number
    The number of points between the initial and final value. Required for the independent quantity.
  • maxStepSize: number (default value: Infinity)
    The largest value for the step size within the independent quantity. If this value is omitted, the step size is determined by (final - initial) / start.
  • includeInitial: boolean (default value: true)
    With true, this includes the initial value of all quantities in the output. Thus, the output is of length count + 1.
  • derivative: string
    Derivative with respect to the independent quantity. This property is only applicable for dependent quantities. Moreover, this property must not be specified if you specified a derivative callback function instead.
  • value: number | complexNumber
    This property is required for constant quantities and defines their value.

Output

The function returns an object with the following properties:

  • quantities: object
    An object containing the resulting data for each quantity.
  • stepSize: number
    The step size used for the independent quantity in the algorithm (same as the input parameter).
  • numberType: string
    The number type used in the algorithm (this is the same as the input parameter).
  • algorithm: string
    The used algorithm (same as input parameter).