Diff Grok

A lightweight TypeScript library for solving initial value problem (IVP) for ordinary differential equations (ODEs) using numerical methods. The primary solvers are LSODA — a variable-order method that automatically detects stiffness and switches between Adams (non-stiff) and BDF (stiff) formulations — and CVODE — a variable-order, variable-step solver from the SUNDIALS suite supporting both Adams and BDF methods.

Features

• Solving both stiff and non-stiff equations
• Fast computations
• Automatic stiffness-detecting method:
  • LSODA - variable-order Nordsieck-based solver with automatic switching between Adams (non-stiff) and BDF (stiff) methods (Petzold, 1983; Hindmarsh, 1983). Ported to TypeScript from the C library liblsoda
• Variable-order multistep method:
  • CVODE - variable-order, variable-step solver from the SUNDIALS suite with BDF (stiff) and Adams (non-stiff) modes (Hindmarsh et al., 2005; Cohen & Hindmarsh, 1996). Ported to TypeScript from SUNDIALS CVODE v7.5.0
• Implicit methods (for stiff ODEs) - Rosenbrock–Wanner type:
  • The modified Rosenbrock triple (MRT)
  • The ROS3PRw method
  • The ROS34PRw method
• Explicit methods (for non-stiff ODEs):
  • Runge-Kutta type:
    • The Bogacki-Shampine 3(2) method (RK3)
    • The Runge-Kutta-Fehlberg method (RK4)
    • The Dormand-Prince 5(4) method (RKDP)
  • Adams-Bashforth type:
    • The predictor-corrector method of order 4 (AB4)
    • The predictor-corrector method of order 5 (AB5)
• Scripting:
  • declarative specification of models
  • auto-generated JavaScript code
• Integration with the Datagrok platform
• Zero dependencies

Installation

To install via npm:

npm install diff-grok
Copy

Minimal "Hello World" example:

// example.ts

import {ODEs, cvode} from 'diff-grok';

const task: ODEs = {
  name: 'Example',
  arg: {name: 't', start: 0, finish: 1, step: 0.1},
  initial: [1],
  func: (t: number, y: Float64Array, output: Float64Array) => {
    output[0] = y[0] - t;
  },
  tolerance: 1e-7,
  solutionColNames: ['y(t)'],
};

const solution = cvode(task);

console.log('t:', solution[0]);
console.log('y(t):', solution[1]);
Copy

Solving

General

To find numerical solution of a problem:

$$\frac{dy}{dt} = f(t, y)$$ $$y(t_{0}) = y_0$$

on the segment $[t_0, t_1]$ with the step $h$:

1. Import ODEs and a desired numerical method:

   Automatic method:

   • lsoda - LSODA variable-order solver with automatic switching between Adams (non-stiff) and BDF (stiff)

   Variable-order multistep method:

   • cvode - CVODE variable-order BDF solver from the SUNDIALS suite

   Implicit methods (for stiff ODEs):

   • mrt - the MRT method
   • ros3prw- the ROS3PRw method
   • ros34prw - the ROS34PRw method

   Explicit methods (for non-stiff ODEs) — Runge-Kutta type:

   • rk3 - the Bogacki-Shampine 3(2) method
   • rk4 - the Runge-Kutta-Fehlberg 4(5) method
   • rkdp - the Dormand-Prince 5(4) method

   Explicit methods (for non-stiff ODEs) — Adams-Bashforth type:

   • ab4 - the predictor-corrector method of order 4
   • ab5 - the predictor-corrector method of order 5

2. Specify ODEs object that defines a problem:

   • name - name of a model

   • arg - independent variable specification. This is in object with fields:

     • name - name of the argument, $t$
     • start - initial value of the argument, $t_0$
     • finish - final value of the argument, $t_1$
     • step - solution grid step, $h$

   • initial - initial values, $y_0$

   • func - right-hand side of the system, $f(t, y)$. This is a function (t: number, y: Float64Array, output: Float64Array) => void:

     • t - value of independent variable $t$
     • y - values of $y$
     • output - output values of $f(t, y)$

   • tolerance - numerical tolerance

   • solutionColNames - names of solutions, i.e. names of the vector $y$ elements

3. Call numerical method. It returns Float64Array-arrays with values of an argument and approximate solutions.

Diff Grok is designed to provide fast computations. Check performance for the details.

Example

Consider the following problem:

$$\begin{cases} \frac{dx}{dt} = x + y - t \ \frac{dy}{dt} = x y + t \ x(0) = 1 \ y(0) = -1 \end{cases}$$

To solve it on the segment $[0, 2]$ with the step $0.01$ using LSODA with the tolerance $10^{-7}$, we start with imports:

import {ODEs, lsoda} from 'diff-grok';
Copy

Next, we create

const task: ODEs = {
    name: 'Example', // name of your model
    arg: {
        name: 't',  // name of the argument
        start: 0,   // initial value of the argument
        finish: 2,  // final value of the argument
        step: 0.01, // solution grid step
    },
    initial: [1, -1], // initial values
    func: (t: number, y: Float64Array, output: Float64Array) => { // right-hand side of the system
      output[0] = y[0] + y[1] - t; // 1-st equation
      output[1] = y[0] * y[1] + t; // 2-nd equation
    },
    tolerance: 1e-7, // tolerance
    solutionColNames: ['x', 'y'], // names of solution functions
};
Copy

Finally, we call the specified numerical method to solve task:

const solution = lsoda(task);
Copy

Currently, solution contains:

• solution[0] - values of $t$, i.e. the range $0..2$ with the step $0.01$
• solution[1] - values of $x(t)$ at the points of this range
• solution[2] - values of $y(t)$ at the points of the same range

Find this example in basic-use.ts.

Performance

The following classic problems are used to evaluate efficiency of Diff Grok methods:

• Rober
  • a stiff system of 3 nonlinear ODEs
  • describes the kinetics of an autocatalytic reaction given by Robertson
  • robertson.ts
• HIRES
  • a stiff system of 8 non-linear equations
  • explains the `High Irradiance Responses' (HIRES) of photomorphogenesis on the basis of phytochrome, by means of a chemical reaction involving eight reactants
  • hires.ts
• VDPOL
  • a system of 2 ODEs proposed by B. van der Pol
  • describes the behaviour of nonlinear vacuum tube circuits
  • vdpol.ts
• OREGO
  • a stiff system of 3 non-linear equations
  • simulates Belousov-Zhabotinskii reaction
  • orego.ts
• E5
  • a stiff system of 4 non-linear ODEs
  • represents a chemical pyrolysis model
  • e5.ts
• Pollution
  • a stiff system of 20 non-linear equations
  • describes a chemical reaction part of the air pollution model designed at The Dutch National Institute of Public Health and Environmental Protection
  • pollution.ts

The LSODA, CVODE, MRT, ROS3PRw and ROS34PRw methods demonstrate the following time performance (AMD Ryzen 5 5600H 3.30 GHz CPU):

* E5 is skipped for CVODE: the extremely stiff rate constants (spanning 20 orders of magnitude) cause convergence failures with the dense direct linear solver.

Maximum absolute deviations (MADs) from the reference solutions obtained using SciPy (Radau) are summarized in the table below:

Run check-methods.ts to reproduce these results (see here how to run scripts standalone).

The following charts compare the Diff Grok and Radau solutions for the van der Pol system:

The following graphs present a comparison of the Diff Grok and Radau solutions for the Pollution model, highlighting a portion of the functions:

Scripting

The library provides tools for declarative specifying models defined by IVPs. This feature enables a development of "no-code" modeling tools seamlessly integrated with the Datagrok platform.

Model components and syntax

Each model has a simple declarative syntax.

Core blocks

These blocks define the basic mathematical model and are required for any model:

1. #name: Add a model identifier

   #name: Problem
   Copy

2. #equations: Define the system of ODEs to solve. Diff Grok supports any number of equations with single or multi-letter variable names

   #equations:
     dx/dt = x + y + exp(t)
     dy/dt = x - y - cos(t)
   Copy

3. #argument: Defines

   • independent variable
   • its initial value (initial)
   • final value (final), and
   • grid step (step)

   The solver calculates values at each step interval across the specified [initial,final] range.

   #argument: t
     initial = 0
     final = 1
     step = 0.01
   Copy

4. #inits: Defines initial values for functions being solved

   #inits:
     x = 2
     y = 5
   Copy

Comments

• #comment: Write a comment in any place of your model

  #comment:
    You can provide any text here. The lib ignores it.
  Copy

• Place comments right in formulas using //

  #equations:
    dx/dt = x + y + exp(t) // 1-st equation
    dy/dt = x - y - cos(t) // 2-nd equation
  Copy

Model parameters

These blocks define values used in equations. Choose type based on intended use:

• #parameters: Generate UI controls for model exploration

  #parameters:
    P1 = 1
    P2 = -1
  
  Copy

• #constants: Use for fixed values in equations that don't require UI controls

  #constants:
    C1 = 1
    C2 = 3
  Copy

Auxiliary calculations

This block defines mathematical functions using #parameters, #constants, #argument, and other functions. These are direct calculations (no ODEs involved). Use them to break down complex calculations and simplify your equations.

• #expressions

  #expressions:
    E1 = C1 * t + P1
    E2 = C2 * cos(2 * t) + P2
  Copy

JS-code generation

To transform any model to JavaScript code with an appropriate specification of ODEs object, follow the steps:

1. Import the parsing and code generating tools:

import {getIVP, getJScode} from 'diff-grok';
Copy

2. Define a string with a model specification, use a simple model syntax:

const model = `
#name: Example
#equations:
  dx/dt = x + y - cos(t)
  dy/dt = x - y + sin(t)
...
`;
Copy

3. Parse formulas:

const ivp = getIVP(model);
Copy

The method getIVP parses formulas and returns IVP object specifying a model.

4. Generate JS-code:

const lines = getJScode(ivp);
Copy

The method getJScode transforms IVP object to JavaScript code. It returns an array of strings with this code.

Find this example in scripting.ts.

Pipelines

Diff Grok pipeline is a powerful feature for complex process simulation and model analysis in webworkers. It wraps the main solver with a set of actions that perform pre- and post-processing of a model inputs & outputs. In addition, they provide an output customization.

1. Start with imports:

import * as DGL from 'diff-grok';
Copy

2. Define your model:

const model = `#name: My model
#equations:
  dx/dt = ...
  dy/dt = ...
  ...

#inits:
  x = 2
  y = 3
  ...
Copy

3. Generate IVP-objects:

• for the main thread computations:

const ivp = DGL.getIVP(model);
Copy

• for computations in workers:

const ivpWW = DGL.getIvp2WebWorker(ivp);
Copy

4. Set model inputs:

const inputs = {
  x: 2,
  y: 30,
  ...
};
Copy

5. Create typed input array:

const inputVector = DGL.getInputVector(inputs, ivp);
Copy

6. Get a pipeline:

const creator = DGL.getPipelineCreator(ivp);
const pipeline = creator.getPipeline(inputVector);
Copy

You can pass pipeline, ivpWW, and inputVector to webworkers.

7. Apply pipeline to perform computations:

const solution = DGL.applyPipeline(pipeline, ivpWW, inputVector);
Copy

Find complete examples in these files:

• pipeline-use.ts - A basic example demonstrating pipeline usage
• model-updates.ts - A simulation of a multi-stage process using pipelines
• cyclic-model.ts - A simulation of a cyclic process using pipelines

Integration with Datagrok

Datagrok is a platform enabling powerful scientific computing capabilities. It provides next-generation environment for leveraging interactive visualizations, data access, machine learning, and enterprise features to enable developing, publishing, discovering, and using scientific applications.

The library is seamlessly integrated to Datagrok via the Diff Studio package. It provides

• Numerical solving IVPs directly in the browser
• "No-code" models development
• Solving both stiff and non-stiff systems of ODEs
• Automatic generation of user interfaces
• Interactive visualization and model exploration
• Sensitivity analysis and parameters optimization
• Sharing models and computational results

Run the Diff Studio app and check interactive modeling:

Learn more

• Diff Studio application docs
• Diff Studio example models
• Parameters optimization
• Sensitivity analysis

Environment Requirements

Development & Build

• Node.js ≥ 19.3.0 (required for development and building the library)
• npm or yarn package manager

Runtime Environments

Server-Side (Node.js)

• Node.js ≥ 16.0.0 (for server-side usage)
  • Requires support for ES modules
  • Float64Array and typed arrays support (available since Node.js 0.10+)

Operating Systems

• Windows (x64, ARM64)
• macOS (Intel & Apple Silicon)
• Linux (most common distributions)

Browser Support

The library runs in all modern browsers with ES2015+ support. Key requirements:

• ES Modules (native import/export)
• Typed Arrays (Float64Array, Uint8Array)
• WebWorkers (for pipeline computations)
• ArrayBuffer support

Browser Feature Requirements:

• ES2015 (ES6) JavaScript support
• Native ES modules (<script type="module">)
• Float64Array and other typed arrays
• WebWorker API (for parallel computations)
• Promise support
• Math object with standard functions (exp, sin, cos, etc.)

Notes:

• For older browsers, consider using a transpiler (Babel) and bundler (Webpack/Rollup)
• TypeScript compilation target should be ES2015 or higher
• WebWorker support is required for pipeline computations; without it, computations run on the main thread

Bundler Configuration

When bundling for browsers, ensure:

• ES module output format is preserved or properly transformed
• TypedArray polyfills are not included (not needed for target browsers)
• WebWorker files are properly handled by your bundler

Polyfills

No polyfills required for target environments. All required features are natively supported in the minimum browser versions listed above.

Examples

Diff Grok contains a set of examples located in the folder src/examples:

npm install --save-dev typescript
Copy

npx tsc --init
Copy

{
  "compilerOptions": {
    "target": "es6",
    "lib": ["ES2022", "dom"],
    "sourceMap": true,
    "strict": true,
    "moduleResolution": "node",
    "types": ["jest", "node"],
    "esModuleInterop": true,
    "skipLibCheck": true,
  }
}
Copy

tsc src/examples/basic-use.ts
Copy

node src/examples/basic-use.js
Copy

References

• L. Petzold, "Automatic Selection of Methods for Solving Stiff and Nonstiff Systems of Ordinary Differential Equations," SIAM J. Sci. Stat. Comput., 4(1), 136–148, 1983. doi:10.1137/0904010
• A. C. Hindmarsh, "ODEPACK, A Systematized Collection of ODE Solvers," Scientific Computing, R. S. Stepleman et al. (eds.), North-Holland, Amsterdam, pp. 55–64, 1983. link
• The LSODA solver is ported to TypeScript from the C library liblsoda
• A. C. Hindmarsh et al., "SUNDIALS: Suite of Nonlinear and Differential/Algebraic Equation Solvers," ACM Trans. Math. Softw., 31(3), 363–396, 2005. doi:10.1145/1089014.1089020
• S. D. Cohen and A. C. Hindmarsh, "CVODE, a Stiff/Nonstiff ODE Solver in C," Computers in Physics, 10(2), 138–143, 1996. doi:10.1063/1.4822377
• The CVODE solver is ported to TypeScript from SUNDIALS CVODE v7.5.0
• T. Rang and L. Angermann, "New Rosenbrock W-Methods of Order 3 for Partial Differential Algebraic Equations of Index 1," BIT Numer. Math., 45, 761–787, 2005. doi:10.1007/s10543-005-0035-y
• E. Hairer and G. Wanner, Solving Ordinary Differential Equations II: Stiff and Differential-Algebraic Problems, Springer, 1996. doi:10.1137/S1064827594276424

Contributing

We welcome contributions of all kinds - bug reports, feature requests, documentation updates, and pull requests.

Before contributing, please read our Contributing Guidelines.

License

This project is licensed under the MIT License.

The LSODA solver is a TypeScript port of liblsoda. The CVODE solver is a TypeScript port of SUNDIALS CVODE. See THIRD_PARTY_LICENSES for details on third-party code provenance.