Flint 2.4: The User Guide

Flint 2.4 supports the following standard languages of models:

• PHML (including its precursor ISML [5])
• SBML
• CellML

Flint 2.4 supports the following algorithms to solve ODEs numerically:

• Euler method
• Runge-Kutta 4th-order method
• Adaptive stepsize Runge-Kutta method, based on the ARKode solver of SUNDIALS [6]

Flint 2.4 also supports the following algorithms to solve SDEs numerically:

• Euler-Maruyama method [7]

Please download the installer package Flint-2.4.0-windows.x86_64.msi at https://sourceforge.net/projects/flintproject/files/Flint/. Double-clicking the .msi package will start the installation process. If installed successfully, Flint’s executable program will be found at C:\Program Files\Flint\flint.exe.

Please download the installer package Flint-2.4.0-mac.dmg at https://sourceforge.net/projects/flintproject/files/Flint/. The .dmg archive for macOS contains Flint 2.4’s .pkg file; extracting and double-clicking it to start an application bundle called Flint.app.

Please download Flint-2.4.0-el7.x86_64.zip or Flint-2.4.0-el8.x86_64.zip at https://sourceforge.net/projects/flintproject/files/Flint/, depending on the major version of your OS. Unzipping the archive, run the following command on a bash-like shell to install RPM packages in it:

unzip Flint-*-el*.x86_64.zip
cd Flint-*-el*.x86_64
sudo rpm -Uvh --replacepkgs flint-*.rpm

Once installed, Flint’s executable will be found at /opt/flint/bin/flint.

In principle Flint 2.4 runs on any Linux distribution coming up with GTK 2 or 3. You can build Flint from its source tarball, available at https://github.com/flintproject/Flint/archive/Flint-2.4.0.tar.gz, by following the instructions in INSTALL.org found in the archive.

Users have to choose a solver method for ordinary differential equations or stochastic differential equations at the “Integration method” combobox. An error will occur at simulation time when choosing any method except the Euler-Maruyama method for a model including SDEs.

Users must specify the total length of simulation time at the “Simulation Length” field; the given number is interpreted in terms of the selected time unit.

Similarly to “Simulation Length”, users can specify the time step at the “Simulation Time Step” field.

Users can specify when (in the sense of simulation time) output starts from at this field. By default, simulation process produces output from time 0.

This setting is for determining how often the result data are written in. Note that the sampling rate does not affect the calculation for simulation.

Before starting simulations for a loaded model, users may want to choose a limited number of variables for output among available variables. Filtering output variables will reduce the burden of writing output, and thus may improve the simulation performance. The “Output Variables” panel (Fig. 11) allows user to select output variables by matching one of their properties with a given string. The possible target properties depend on the format of the model file, and are summarized in Table 1. With the “Filter Column” combo box one can choose the target. The “Filter Pattern” combo box chooses the way to interpret the given string: as a regular expression (default), or just as a fixed string.

By default, Flint runs a single simulation job for each loaded model. It is also possible to start a simulation batch for each model with different values of parameters. A batch of simulations can result in multiple different trajectories of variables in the same model. Hereafter, we simply call each result from an element in the batch a trajectory.

In order to explain the feature to parameterize constants found in a model, let’s define some technical terms as follows. In Flint’s terminology, named numeric constants in the model are called shortly “constants”. For example, some of CellML’s variable=s have attribute =initial_value, which is assigned to a constant number. In PHML there is an element called static-parameter specifying a constant, as well as initial-value. SBML’s parameter element has attribute value assigned to a number. All of them are constants in Flint’s context, and they are potential targets for changing their values by some parameters. However, make sure that a constant in the above sense is not a parameter itself in Flint. Rather, a constant can be parameterized by zero or more parameters.

In Flint’s terminology, a parameter is a named object assigned to a specific number for each trajectory. Let \(\mathcal{P}\) be the set of parameters. To configure a batch, every parameter is bound to its own set of possible values, called value-set. Let \(\mathcal{V}(p)\) be the value-set of parameter \(p\) in \(\mathcal{P})\). The whole set of possible tuples of multiple parameters is defined as the Cartesian product of multiple value-sets, i.e., \(\prod_{p \in \mathcal{P}} \mathcal{V}(p)\). (It is also possible to custom how to construct the whole set of value tuples for an advanced setting. Please read 3.4.7.4.) From now on, a pair \((\mathcal{P}, \mathcal{V})\) is called the parameter set as it determines the parameterization of a batch completely.

Given the parameter set of a batch, Flint will run as many simulations for the given model as the cardinality of the Cartesian product, i.e., \(\lvert \prod_{p \in \mathcal{P}} \mathcal{V}(p) \rvert\), by changing the assigned values from a tuple to another. In other words, each trajectory corresponds to a value tuple of the parameters.

Users can see and modify numeric values of constants in a loaded model, such as the initial values of ordinary differential equations and values of =static-parameter=s of PHML, at the “Parameters” panel. The table at the “Parameters” consists of each row corresponding to a constant element in the model; the “Expression” field of the row accepts an algebraic formula defining the parameterized value of the constant. The following 3.4.7.1 summarizes available operators in the formula, which semantics conforms to MathML 3 in principle, except infix operators such as +, *, etc. For example, given parameters p and q, you can build a formula like “2.5 * max(p, 1) - cos(q)”.

There is another way to cancel running jobs; pushing the cross mark on the control panel (see Fig. 17), which cancels a job i.e. all of its tasks together.

As in Fig. 18, users can pause jobs at any time during simulation by using the menu “Control”→“Pause”. Resuming paused jobs can be done with the menu “Control”→“Resume”. Note that this operation affects all of alive jobs simultaneously.

In order to draw a line graph, users have to specify the abscissa and ordinates by checking an X column as well as either Y1 or Y2 column. Immediately after choosing abscissa and ordinates, Flint calls gnuplot in the background to draw a line graph. Thus users have to install gnuplot in advance, and to specify the location of the gnuplot executable (see section 3.12).

Flint can export the result data into a CSV file. The header column contains the variable names as well as their unit name if any.

The procedure is as follows:

1. Open the “Detail” window
2. Select as many tasks as you would like to save.
3. Push button “Export”
4. Choose a target directory in the file dialog (see Fig. 20)

The names of files saved in the target directory are of form “(ID).csv.”

Flint can also export the result data into a ISD file. The ISD file format is a binary file format for preserving multi-variate data.

The procedure is as follows:

1. Open the “Detail” window
2. Select as many tasks as you would like to save.
3. Push button “Export”
4. Choose a target directory in the file dialog (see Fig. 20)

The names of files saved in the target directory are of form “(ID).isd.”

To calculate the RSS against a simulation, Flint needs the reference time course as an ISD file, which must have at least two columns. The first column must be “time”. The second column must be one of the output variables, and so are the rest, if any. The column name of a variable, except “time”, in the ISD file must be prefixed with an appropriate UUID. Table 2 summarizes the column name’s format for each modeling language. Each row of the ISD file represents the value of the variable at a specified simulation time.

Program csv2isd helps to obtain an ISD file from the data in CSV. Read section 5.2 for details about the program.

Please check “Enable parameter fitting by the method of least-squares” in the “Objective” tab, and select the ISD file in the below form (See Fig. 21).

The way to specify a parameter set in fitting parameters is the same as running a simulation batch. Please go to “Parameters” tab, and click the “Edit parameter set” button to launch a dialog to edit parameters and their value-sets.

Push the “Run” button once you have done with the parameter set. Then a batch of simulations will start. Note that some of simulations will finish before reaching the end of simulation time as it turns out that they cannot be the ones having the minimum RSS among the batch.

You will find the resulting RSS for each simulation in the same way for a normal simulation batch. Click the “Detail” of the job. Then a table will pop up. Each row of the table displays the RSS of a simulation as well as the corresponding value tuple of the parameters.

If you proceed to show the plot of the target variable i.e. included in the ISD file, the reference values also are shown as a point of mark x (see Fig. 22).

To export C code from a model,

1. Load a model
2. Select the menu “File”→“Export to C” (see Fig. 23)
3. Choose a target filename via the file dialog that follows.

Then a dialog will appear to tell whether it is done successfully or not.

Please note that the numerical method used in the exported code is the one specified in the original model, e.g., Euler or Runge-Kutta 4th-order method; the ARKode solver of SUNDIALS has not been supported yet.

Once a C source file exported, what to do next is building the program by a C compiler conforming C99 standard.

If, for example, gcc is available, then invoking the following code

gcc -O3 -std=c99 -o simulate exported.c

will produce an executable named simulate from the C source file exported.c.

Finally,

./simulate output.isd

will run a simulation, writing the whole output into output.isd.

The concurrency hint helps Flint run multithread simulation with an optimized number of concurrent threads. By default Flint automatically detects the number of cores and preset it for the hint.

Flint must find the gnuplot executable when rendering line graphs. Giving a proper path to the gnuplot program through this option is mandatory on Windows and macOS. On the other hand, Flint try /usr/bin/gnuplot, if omitted, on Linux. Select the path of gnuplot (or gnuplot.exe on Windows), e.g., /usr/bin/gnuplot. If macOS users have, say, /Applications/gnuplot.app as an application bundle of gnuplot, its value should be /Applications/gnuplot.app/bin/gnuplot.

Both Esc and Ctrl+W (or Command+W on Mac) can close an active subwindow in which there is no dedicated button to close it.

It is possible to launch Flint with the command open(1) of macOS as follows:

open Flint.app

Note that it does nothing but launches the graphical user interface of Flint. In a cmd session on Windows,

flint.exe

has a similar effect.

If filenames of models are given in the command line on Windows:

flint.exe model1 model2 ...

or, on macOS:

open Flint.app model1 model2 ...

then Flint tries to open them immediately after launching the GUI.

On Windows:

flint.exe -help

On macOS:

./Flint.app/Contents/MacOS/flint -help

On Windows:

flint.exe -headless input output [-e file] [-g n] [-s file]

On macOS:

./Flint.app/Contents/MacOS/flint -headless input output [-e file] [-g n] [-s file]

Load a model at input, simulation it with the default configuration, and leave the result at output. The following suboptions are available:

-e file

save error messages during simulation as file.

-g n

specify output sampling rate i.e. 1 output per n step.

-s file

specify output variables with file.

This program reads an ISD file of filename path, and converts and writes it in the CSV format to the standard output. It reads the standard input if path is omitted.

--output, -o

write to file at output instead of stdout.

--ignore-prefixes, -P

ignore variable prefixes.

--ignore-units, -U

ignore units.

--maximum-precision, -M

request the maximum number of decimal

digits to print double-precision floating-point numbers.

--progress

send progress in percentage to given UDP port.

--help, -h

show help.

This program reads a CSV file of filename input, and converts and writes it into an ISD file of filename output. The first line of input must be the header naming the columns.

--help, -h

show help.