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.
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).
- Click
- 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.
In Browse, click any ivp-file. Model preview opens. Modify inputs and check results. Use URL to share computations:
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
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
andmax
values for each selected item. They define the variation range - Set values of all other inputs
- Set
- 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 theloss
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
- Choose numerical optimization method (in the
- 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
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}
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
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:
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}
Loading templates and examples
To load a template, click the Load... on the ribbon, select Templates and choose one of the following templates:
Template | Features |
---|---|
Basic | Minimum project with one differential equation |
Advanced | Extra math features: expressions, constants, parameters and tolerance specification |
Extended | The 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
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
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.
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.
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
Acid production
Acid production
models gluconic acid production by Aspergillus niger. This example shows the usage of the update
feature for multistage simulation
Nimotuzumab
The Nimotuzumab
example simulates population pharmacokinetic for nimotuzumab. It demonstrates the output
feature
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.
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.
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:
Method | Value |
---|---|
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:
x | y | ... | |
---|---|---|---|
Set 1 | 1 | 2 | ... |
Set 2 | 3 | 4 | ... |
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:
See also