PhysioDesigner
A modeling tool for multilevel physiological systems

Create a simple PHML model


This document shows how to create a simple model on PhysioDesigner. Let’s take the Bonhoeffer–van der Pol (BVP) model as an example, which is a very simple neuron model reproducing the membrane potential dynamics.

The BVP model is described by two ordinary differential equations:

bvp

where x and y represent, respectively, the membrane potential and refractoriness. z represents an external current stimulus.
We’ll use the following parameter values: a = 0.7, b = 0.8, c = 3.0, z = −1.



1. Consider the structure of the model


First of all, we need to consider the basic structure of the model. Even though the structure can be changed during the modeling process, it’s best to give it some thought beforehand.

In our example case, there are two dynamic variables, x and y, and basically there are two methods of modeling: we can either put both variables in a single module, or we can set the variables separately in two different modules.
Pasted Graphic  or  Pasted Graphic 1

Since this is a very simple model, there is little difference between the methods. However, considering a much more complicated model, such as one with 50 dynamic variables, it is better to think about how to introduce a structure according to the physiological meaning of every equation.

Here, both methods are shown, starting with the simpler case where both equations are set in the same module.



2 Create a model containing only one module


2.1 Create a module


On a white PhysioDesigner canvas, click the right mouse button to show the context menu. Select "Make a Functional-Unit Module...".
Pasted Graphic 2

In the dialog that appears, input the name of the module.
Pasted Graphic 3

We now have a function module named "BVP".
Pasted Graphic 4


2.2 Define a physical quantity "x"


On the module, click the right mouse button and select "Edit Physical quantity..." from the menu.
Pasted Graphic 5

The following dialog appears:
Pasted Graphic 7

First, let’s define a dynamic variable x, for which the dynamics is described by an ODE.

Select "State" for the type and set "x" in the Name field in the “Basic setting” tab. Selecting "State" is your declaration that this physical quantity is one of the variables defining the system's state; thus you will need to define its derivative later.

Pasted Graphic 8

The unit must be selected from the combo box. Otherwise, click the “Edit” button to add a new user-defined unit.
How to edit a new unit is explained in other document.

Once you provide the type and name, you can go to other tabs such as “Initial value”, “Domain”, “Implementation” and so on. According to the type of physical quantity, the tabs in which information is required are activated.

Pasted Graphic 9

In the case of ODEs, you need to define at least "Initial value" and "Implementation". It is suggested that a "Description" is written for this physical quantity as an explanatory reminder in the future.

"Domain" and "Problem condition set" are used for defining PDEs. For now, we are not using these tabs.


2.3 Define Implementation of x


Let’s go to the "Implementation" tab, which is where the ODE for x is defined. In this tab, you need to first select the type of equation that you are going to define. It can be an ODE, PDE, or Conditional, meaning respectively, an ordinary differential equation, partial differential equation, and conditional equation which is similar to the IF … Else IF … Else syntax of programming languages.

Pasted Graphic 10

Here, let’s select "ode" from the combo box.
The default equation is automatically provided.

Pasted Graphic 11

Now you can edit the equation in two ways. If you are familiar with writing equations in C language style, such as "c*(y+x-x*x*x/3+z)", then you can use the "Equation" text box at the bottom of the window.

Input "c*(y+x-x*x*x/3+z)" in the text box and click the Enter key. You will see that the rendered equation is updated.

Pasted Graphic

Or, you can use the equation editor by clicking the button labeled "Math editor".

Pasted Graphic 1

Details on using the equation editor are explained in other document. After editing the equation here, click "Apply" and then "Close" to reflect the revision in the main window.


2.3 Define Initial value of x


The “Initial value” tab opens up with “x=0” as default information. Since this information is necessary for solving the ODE, we must provide it and modify if necessary.

Pasted Graphic 4

At the bottom of window is the "Equation" text box, in which the initial value can be input in equation form, such as x = 0. Clicking the return key shows the rendered equation.

Pasted Graphic 3


2.3 Define Description of x


It is always best to provide a description for the physical quantity that you are defining so that there will be a future reminder of its meaning.

Pasted Graphic 5

The above settings are all for the state x. Now we can go on to other physical quantities.



2.4 Define a physical quantity "y"


Let’s now define the other state, y. The procedure is the same as that for x. We declare the type and name of y, and define the implementation and initial value.

To define a new physical quantity, click the next row in the table at the head of the window.

Pasted Graphic 7

The "Basic setting" tab automatically opens with empty fields.
Again, we set "state" for the type, and input "y" in the Name field.

Pasted Graphic 8

We then go to the “Implementation” tab and set an ODE dy/dt=−(x−a+b*y)/c.

Pasted Graphic 9

Next is the initial value. Here, let’s put 1 for y.

Pasted Graphic 10

Last is the description.

Pasted Graphic 11



2.5 Define parameters


There are four parameters: a, b and c and external input to the model z. We declare these as "static-parameters".
Taking ‘a’ as an example, let’s continue to create this model. First, set the Type and Name.

Pasted Graphic

In the case of a static-parameter, it is not necessary to set the initial value; hence the “Initial value” tab is inactivated.
Moving on to the “Implementation” tab, select "ae" for Definition-type, which represents "algebraic equation".

Pasted Graphic 1

By default, "a = 0" is automatically set. You can change the value at the Equation text box.

Pasted Graphic 3

Input a = 0.7 here, and press the Return key. The view is updated.
Parameter ‘a’ is now defined. Similarly, b, c and z can be defined. The values are b = 0.8, c = 3.0, z = −1.

When all the static-parameters have been defined, click the OK button at the bottom right of the window.



3 Simulation



Now, let’s perform a simulation of this model.
Select “Simulation > Flint“ from the menu.

Pasted Graphic 2

When the dialog appears asking if you want to save the model, please save it.

Pasted Graphic 1

Flint is launched. If this is the first time that you are launching Flint, a dialog will appear asking for the location of Flint in your system.

Pasted Graphic 8

Select Flint.app (for MacOSX. Flint.exe for Windows). If necessary, download it from this site and install it first.

Pasted Graphic 9

The Flint window shows a dialog for setting the simulation parameters such as the duration, time step, and so on. Here, just click the “Run” button to start the simulation.

Pasted Graphic 7

Once the simulation finishes, move to the “Plot” tab. Move the name tag "x" at the leftmost box to the second box from the left. A graph of x is then drawn in the middle pane.

Pasted Graphic 10

Note that if you wish to run a simulation with a different parameter value, it is not necessary to close and relaunch Flint.
Simply return to PhysioDesigner, change the value on the Physical quantity dialog, and save the file. Then come back to Flint, and click the “Run” button in the Simulation tab. Flint automatically reloads the model, and performs a simulation with the new parameter value.


4 Create a model containing two modules


4.1 Create modules


Let’s start by creating two empty modules.

Pasted Graphic

Right-click on module x, and select “Edit Physical quantity...” from the menu. As we saw above, we define x as a state and c, z as static-parameters in module x.
On the right-hand side of the ODE for x (which is c*(y+x-x*x*x/3+z)), there is y as well, which must be defined. Since we decided to define y in the other module, we must import the value of y from the other module.
For this step, we define y as a variable-parameter that is assigned to an in-port. Let’s do this below.



4.2 Define a variable-parameter assigned to an in-port


We define y as a variable-parameter as follows.

Pasted Graphic

Then, we assign this physical quantity to an in-port. But since we don’t yet have any ports, we’ll create an in-port now.
At the right side of this tab, select the "In" radio button under "Link to a port".

Pasted Graphic 1

Then, input the name of the port in the "Name" field. Here, we used "port_y" as its name.

Pasted Graphic 2

Click the "Add" button.

Pasted Graphic 3

Then "port_y" appears in the text box. Select it by clicking the name.

Pasted Graphic 4

Through this procedure, this physical quantity is assigned to the in-port named "port_y".
Now press the OK button at the bottom right of the dialog window.

You can see that module x now has an in-port.
Pasted Graphic 5


4.3 Define an association between a variable-parameter and an out-port


Since the equation for y defined in module y requires the value of x, we need to prepare to output the value of x from module x.
Right-click on module x, and select “Edit Physical quantity...” from the menu.

Select the row for x in the table. Then select the “Out” radio button under “Link to a port.”

Pasted Graphic

Input the port name in the Name field and click the “Add” button. Here, let’s use "port_x" as the name.

Pasted Graphic 1

By selecting port_x in the list box, the physical quantity is assigned to this out-port.

Pasted Graphic 2

Press the OK button. You will see the out-port on the right side of module x.

Pasted Graphic 3

If you select “Edit Ports...” from the context menu that appears by right-clicking on module x, you can confirm (and edit) the association between ports and physical quantities.

Pasted Graphic


4.4 Define the other module for y


Similarly, we can define a state y in module y (which is diff(y, time) = -(x-a+b*y)/c).
We also need to define static-parameters a, b, c (a = 0.7, b = 0.8, c = 3.0).
x must be defined as a variable-parameter assigned to an in-port.

Pasted Graphic 1

Do not forget to prepare for outputting the value of y by associating it with an out-port.

Pasted Graphic 2


4.5 Linking edges


We now have two modules with in- and out-ports.
Pasted Graphic 3

Let’s input the value x from the out-port "port_x" of module x to the in-port "port_x" of module y. For this step, simply click the out-port "port_x" and, while keeping the mouse button pressed, drag it to the in-port "port_x" of module y.

PhysioDesignerScreenSnapz002

An edge is spanned between the two ports.
Pasted Graphic 4

Similarly, link the two ports named port_y using an edge.
Pasted Graphic 5
To show another way, right-click on an edge and select "To Orthogonal".
PhysioDesignerScreenSnapz003
The edges appear as shown below.
Pasted Graphic 6