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:
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.
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...".
In the dialog that appears, input the name of the module.
We now have a function module named "BVP".
2.2 Define a physical quantity "x"
On the module, click the right mouse button and select "Edit Physical quantity..." from the menu.
The following dialog appears:
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.
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.
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.
Here, let’s select "ode" from the combo box.
The default equation is automatically provided.
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.
Or, you can use the equation editor by clicking the button labeled "Math editor".
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.
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.
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.
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.
The "Basic setting" tab automatically opens with empty fields.
Again, we set "state" for the type, and input "y" in the Name field.
We then go to the “Implementation” tab and set an ODE dy/dt=−(x−a+b*y)/c.
Next is the initial value. Here, let’s put 1 for y.
Last is the description.
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.
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".
By default, "a = 0" is automatically set. You can change the value at the Equation text box.
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.
Now, let’s perform a simulation of this model.
Select “Simulation > Flint“ from the menu.
When the dialog appears asking if you want to save the model, please save it.
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.
Select Flint.app (for MacOSX. Flint.exe for Windows). If necessary, download it from this site and install it first.
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.
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.
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.
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.
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".
Then, input the name of the port in the "Name" field. Here, we used "port_y" as its name.
Click the "Add" button.
Then "port_y" appears in the text box. Select it by clicking the name.
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.
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.”
Input the port name in the Name field and click the “Add” button. Here, let’s use "port_x" as the name.
By selecting port_x in the list box, the physical quantity is assigned to this out-port.
Press the OK button. You will see the out-port on the right side of module x.
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.
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.
Do not forget to prepare for outputting the value of y by associating it with an out-port.
4.5 Linking edges
We now have two modules with in- and out-ports.
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.
An edge is spanned between the two ports.
Similarly, link the two ports named port_y using an edge.
To show another way, right-click on an edge and select "To Orthogonal".
The edges appear as shown below.