Skip to main content

Diff Studio

Datagrok Diff Studio solves ordinary differential equations (ODEs) right within your web browser, and provides interactive exploration of their solution.

Differential equations play a crucial role in modeling complex systems in diverse fields, from chemical engineering and drug design to environmental studies and financial modeling.

Using Diff Studio, you can create mathematical models, build interactive visualizations, develop platform applications and combine them with other features of Datagrok.

Key benefits and features:

  • Enhanced mathematical modeling: Diff Studio can model and analyse complex multi-equation systems.
  • Ease of use: Diff Studio intuitive interface makes it accessible and useful to both beginners and experts in mathematical modeling.
  • Rapid design: The collection of built-in model templates and examples speeds up model design.
  • Streamlined integration: In a single click, you can convert formulas to the platform script, implementing no-code development.
  • Broad application scope: Diff Studio usage ranges from pharmacokinetics and hybrid antibody formation simulation to queues modeling.

Using Diff Studio

Running Diff Studio

To run Diff Studio:

  • Go to Apps and run Diff Studio. You will see the default code template with one simple differential equation.
  • Go to Run tab and you will get UI for interactive model exploration.
  • Go to Model tab, edit formulas or add new ones.
  • Press F5 or go to Run tab to re-run calculations and see updated data.

Run Diff Studio

Loading and saving data

  • To save model, click the Save icon on the ribbon. The context menu opens:
    • Click Save as Local File... to save model to a local file. Find the ivp-file in Downloads. You can open and edit this file using any text editor.
    • Click Save to My Files... to save model to your platform files (Browse > Files > My files).
  • To load model from a local file, click the Load... on the ribbon, choose From file... option and choose a local file to upload.
  • Drag-n-drop your ivp-file to Datagrok. Diff Studio will open it and load formulas. You can open ivp-files stored in the platform.

Browse and share models

Go to Browse > Apps and expand the Diff Studio group:

  • Check model templates from Templates. Use them as a backbone of your model.
  • Click Examples and explore built-in models. They cover all Diff Studio capabilities.
  • Find recently opened models in Recent.

Diff Studio Browsing

In Browse, click any ivp-file. Model preview opens. Modify inputs and check results. Use URL to share computations:

Diff Studio Sharing

By using a URL, you can share model runs from the Templates, Examples and Recent groups.

Sensitivity analysis

Explore the relationship between inputs and outputs of your model using the Sensitivity Analysis feature. Run it directly from Diff Studio:

  • Click Run sensitivity analysis icon
  • Apply one of the following methods:
  • Analyze model evaluations

Run Sens Analysis

Parameter Optimization

Find input conditions leading to the specified output constraints using the Parameter Optimization feature. It finds input values that minimize deviation measured by loss function. Run it directly from Diff Studio:

  • Click Run fitting inputs icon
  • In the Fit block, use switchers to specify inputs to be found:
    • Set min and max values for each selected item. They define the variation range
    • Set values of all other inputs
  • In the Target block, specify output constraints:
    • Set dataframe with expected output values (in the table input)
    • Set column with values of the independent variable (in the argument field)
  • Specify settings of fitting:
    • Choose numerical optimization method (in the method field), and set loss function type (in the loss field)
    • Specify number of points to be found (in the samples field)
    • Set the maximum scaled deviation between similar fitted points (in the similarity field): the higher the value, the fewer points will be found
  • Click Run fitting icon. You will get a grid containing
    • loss function values
    • fitted inputs
    • line charts visualizing the goodness of fit and showing the loss function minimization
  • Open Context panel (F4). You will get the simulation run corresponding to the selected grid row

Run fitting

Creating a custom differential equation model

Basic model

A minimal model defining and solving ordinary differential equations contains name, differential equations, initial values and argument specifications.

Use the #name keyword to define the name of your model:

#name: Problem1

Place differential equations in the #equations block. You can add as many equations as you want. Diff Studio automatically recognizes all identifiers that you use. You can use one-letter or multi-letter identifiers.

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

Define the argument, its initial value, final value, and grid step in the #argument block. Datagrok provides a numerical solution within the range [initial, final] with the specified grid step.

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

Define initial values of the functions in the #inits block:

#inits:
x = 2
y = 5

Advanced model

Use the advanced features to improve your model.

Use #comment block to write a comment in any place of your model

#comment:
You can provide any text here. Diff Studio just ignores it.

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

Specify constants in the #constants block and parameters in the #parameters block.

Diff Studio treats constants and parameters exactly the same way. However, when you export equations to the platform script, Diff Studio creates input UI only for parameters and leave constants hardcoded inside the script.

#constants:
C1 = 1
C2 = 3

#parameters:
P1 = 1
P2 = -1

Define auxiliary computations in the #expressions block. The expression is any mathematical function containing constants, parameters, argument, and other functions. The only difference is that expressions functions are defined directly and don't require solving of differential equations. You can use expressions to separate part of the calculations and simplify your differential equations.

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

To customize the computation output, select columns and their captions in the output block:

#output:
t {caption: Time, h}
A1 {caption: Central}
A2 {caption: Periferal}

Customize output

Set tolerance of the numerical method in the #tolerance-line:

#tolerance: 0.00005

Cyclic process simulation

Datagrok provides special capabilities for modeling cyclic processes.

Use the #loop feature to specify several modeling cycles. Define the number of repetitions in the mandatory count variable and use any mathematical expression to modify functions and parameters. You can set new values for parameters and change values for functions.

#equations:
dy/dt = -y + sin(N*t) / t

#parameters:
N = 1

#loop:
count = 3
N += 2

Multi-stage model - loop

Multistage model

Use the #update feature to construct models with multiple sequential processes (stages).

Add name of the first stage in the #argument block:

#argument: t, 1-st stage
t0 = 0.01
t1 = 15
h = 0.01

Add the #update block. Enter name of the stage and set its duration. Add lines with model inputs updates. Use any valid mathematical expression to define them.

#update: 2-nd stage
duration = 23
p = p * 2

You can add any number of update blocks. Simulation stages are marked with a color:

Multi-stage model - update

Usability improvements

For all Diff Studio parameters, you can add annotations described in functional annotations. When you convert your model into the Datagrok script, Diff Studio converts it to the script input annotations, allowing Datagrok to automatically create rich and self-explaining UI.

Define the desired captions for the input parameters. If no caption is provided, Datagrok will use variable name.

#argument: t
start = 0 {caption: Initial time}
finish = 2 {caption: Final time}
step = 0.01 {caption: Calculation step}

Group inputs by specifying their category:

#parameters:
P1 = 1 {category: Parameters}
P2 = -1 {category: Parameters}

Add units:

#inits:
x = 2 {units: C; category: Initial values}
y = 0 {units: C; category: Initial values}

Provide tooltips in brackets [ ]:

  P1 = 1 {category: Parameters} [P1 parameter tooltip]

Specify min, max and step values to get sliders and clickers for the rapid model exploration:

#inits:
x = 2 {min: 0; max: 5}
y = 0 {min: -2; max: 2; step: 0.1}

Using input annotations

Loading templates and examples

To load a template, click the Load... on the ribbon, select Templates and choose one of the following templates:

TemplateFeatures
BasicMinimum project with one differential equation
AdvancedExtra math features: expressions, constants, parameters and tolerance specification
ExtendedThe annotating feature for extended UI generation

To load an example, click the Load... on the ribbon, select Examples and choose a one.

Examples

Diff Studio has built-in examples. They cover all Diff Studio capabilities. Get access to them via the Load... button on the ribbon and use as a template.

Chem reactions

The Chem react example simulates deterministic mass-action kinetics given in the network

add-to-workspace

This example illustrates annotation of model inputs.

Robertson model

Robertson’s chemical reaction model is a well-known example of stiff equations. It describes the process

add-to-workspace

Numerical solution of stiff problems is a complicated task. Diff Studio provides solution of both stiff and non-stiff equations.

Fermentation

The Fermentation example illustrates the kinetics of the biochemical reactions in fermentation.

add-to-workspace

PK

Pharmacokinetics (PK) studies how the body absorbs, distributes, metabolizes, and excretes drugs over time. The PK example simulates this process. It demonstrates the usage of the meta.solver feature for numerical solver management.

add-to-workspace

PK-PD

PK-PD modeling simulates pharmacokinetics (PK), pharmacodynamics (PD), and their relationship. It is used in drug discovery and development. The PK-PD example illustrates the usage of the loop feature for dosing specification

add-to-workspace

Acid production

Acid production models gluconic acid production by Aspergillus niger. This example shows the usage of the update feature for multistage simulation

add-to-workspace

Nimotuzumab

The Nimotuzumab example simulates population pharmacokinetic for nimotuzumab. It demonstrates the output feature

add-to-workspace

Bioreactor

The Bioreactor example models the kinetic mechanism of controlled Fab-arm exchange for the formation of bispecific immunoglobulin G1 antibodies. It shows how to use the meta.inputs feature to specify a table with pre-defined model inputs.

add-to-workspace

Pollution

The Pollution example describes a chemical reaction part of the air pollution model. It consists of 25 reaction and 20 reacting compounds. This example illustrates the capability of Diff Studio to solve large systems of stiff equations.

add-to-workspace

Datagrok's ODEs suite has tools for solving both stiff and non-stiff equations. Combine Diff Studio with viewers and compute tools to explore complex models.

Platform script generation

You can convert any Diff Studio project to the Datagrok script:

  • Click the JS button on the top panel
  • Click the SAVE button to save generated script

Find the created Javascript script in the platform Scripts.

Use #tags: model to add your model to the Model Catalog. Provide a description in the #description line:

#name: Bioreaction
#tags: model
#description: Complex bioreaction simulation

The export feature provides an extension of your project with scripting tools. Apply it to get:

  • non-elementary and special functions' use
  • Datagrok packages' functions call

Solver settings

Manage the solver of ODEs to improve performance. Specify its settings in the #meta.solver-line:

  • the numerical method (method)
  • the maximum number of iterations (maxIterations)
  • the maximum computation time (maxTimeMs)

Diff Studio implements the following Rosenbrock–Wanner methods for solving ODEs:

MethodValue
The modified Rosenbrock triple'mrt'
The ROS3PRw method'ros3prw'
The ROS34PRw method'ros34prw'

By default, Diff Studio uses ROS34PRw and alerts you if computations take too long. The default time limit is 5 seconds. To customize it, set the maximum computation time (in milliseconds):

#meta.solver: {method: 'mrt'; maxTimeMs: 50}

Set the maximum number of iterations to debug formulas in complex models.

Lookup tables

Lookup tables are pre-defined sets of model input values. They're organized as follows:

xy...
Set 112...
Set 234...

To use a lookup table:

  • Create a CSV file with your table and add it to your project
  • Add the #meta.inputs-line to your model and specify a CSV file with a lookup table:
#meta.inputs: table {choices: OpenFile("System:AppData/DiffStudio/inputs.csv")}
  • To improve usability, define caption, category and a tooltip:
#meta.inputs: table {choices: OpenFile("System:AppData/DiffStudio/inputs.csv"); caption: Mode; category: Settings} [Hint]

Use the interface to select inputs and compare model runs:

table-lookups

See also