This page will look better in a graphical browser that supports web standards, but is accessible to any browser or internet device.

Served by Samwise.

Cardiac Physiome Society workshop: November 6-9, 2017 , Toronto

Connecting JSim and Matlab

This page is for the current JSim version 2.0. Click here for the earlier JSim 1.6 version.

Matlab is a matrix-based computational system distributed by The MathWorks(Natick, MA) and widely used for scientific computation. This document discusses several ways to use JSim and Matlab in conjunction to solve scientific problems. Both JSim and Matlab offer possibilities for graphic data display, however this document will focus on combining the computational power of the two products.

Prerequisites

Contents

Exporting JSim models to Matlab

JSim (version 2.07 and above) allows you to export JSim models to Matlab .m files. In the JSim GUI, select the model "Debug" tab and then select "View Matlab" from the "View" menu. Select "Export text..." from the "File" menu to write the Matlab text to a file, which should have extension ".m". For command-line translation, use the jsbatch -omatlab switch, for example:

jsbatch -f input.proj -omatlab > output.m
jsbatch -f input.mod -omatlab > output.m
jsbatch -f input.sbml -omatlab > output.m

Here is an example of how to use the Matlab model export. Consider the following model:


(Java plugin required)

Launch the applet above, or download the model and, using either JSim or jsbatch (version 2.07 and above), follow the instructions above to generate Matlab output in file "mytest.m".

To run the model in Matlab, you must write Matlab code that calls "mytest.m" with parameters for the time span you want the model to run, the name of the ODE solver, and options for the ODE solver. Choices for the ODE solver are ode45, ode23, ode13 for non-stiff problems and ode15s, ode23s, ode23t, and ode23tb for stiff problems. If you wish to plot the results, you must write explicit Matlab commands to do so. See Matlab help for details. For example:

options = odeset('RelTol',1e-12,'AbsTol',1e-9);
[t x rInfo] = mytest( linspace(0,1,101),@ode23,options);
clf;
plot(t,x,'k')
title('Exponential Decay')
xlabel('Time, sec')
ylabel('Concentration, mM')

Limitations: JSim Matlab export is currently implemented by translating JSim model code first to SBML, and then using the sbml2matlab tool to translate SBML to Matlab. There is potential for information loss in both translation stages. Limitations of the JSim to SBML translation process are described here, while limitations of sbml2matlab are described here. At present, JSim Matlab output works best for single-domain ODE models with no events or implicit equations. Note that only the default values of model parameters are exported.

Windows users: If you are receiving errors from JSim concerning libSBML and Matlab code generation, please see Installing JSim under MS Windows: SBML, Antimony, and Matlab.

Exporting JSim data to Matlab

JSim model numeric data may be exported as Matlab .m format. See details in Data Files and Project Data Sets.

Programatic interaction between JSim and Matlab

There is no single "best" way to connect two software products, such as JSim and Matlab, that is best in all circumstances. Different approaches have different strengths and weaknesses in terms of simplicity, flexibility, performance and long-term viability. The importance of such tradeoffs will vary depending upon the problem at hand and the resources (time, compute power, personnel) available. This document will examine several approaches to JSim/Matlab connectivity, their strengths and weaknesses, and illustrate each approach with working examples. All the examples here require you have both JSim and Matlab installed on your computer. The examples do not work via JSim WWW applets.

Understanding numeric data file formats is vital to making many JSim/Matlab connections. JSim supports a variety of data formats. It is often simplest to write "columnar data format" (AKA tab-separated text) from Matlab for import into JSim, and write either "columnar data format" or "Matlab (.m) format" from JSim for import into Matlab. See Data Files and Project Data Sets for further information on supported data formats.

For long automated analyses, it is usually best to dispense with the engine's graphic user interface(GUI), which can take a signficant time to initialize. The jsbatch program provides command-line access to the JSim engine. The user should study the various jsbatch switches to understand the available options. The -nosplash and -nodesktop switches provide access to Matlab without starting the GUI. For further details, see the Matlab user documentation.

Computational analyses utilizing JSim and Matlab may be classified based upon who is the master, and who is the slave. The master may be either JSim, Matlab or an external agent (for example, the user). For further information, see the design of interest:

External master, JSim and Matlab slaves

In this design, the user (or some program acting as his/her agent) launches JSim and Matlab alternately, passing the output files of one program to the input of the other. This design is is very simple and quick to implement, although performance may not be ideal due to the multiple launches of the two engines.

Example using bash script as master

This example models a cell with two genes (gene1 and gene2) and two chemical species (A and B). Gene1 controls the concentration of B, given the concentration of A. Gene2 control the concentration of A, given the concentration of B. The problem is to find the equilibrium concentration when both genes are active.

The bash script below alternately calls the gene1 and gene2 to models, passing the results back and forth, until the concentrations stabilize.


Gene1 is a JSim model, calculating B from A.


Gene2 is a Matlab model, calculating A from B.


Notes:

JSim master, Matlab slave

In this design, a JSim MML model embeds procedural code to call a Matlab process to solve some model variables. The MML constructs for this embedding are called functions and procedures. For information on writing Matlab-specific functions and procedures see here.

Matlab Master, JSim slave

In this design, Matlab will control the JSim computational engine be using either the jsbatch program or JSim's external API.

In the jsbatch scenario, Matlab will generate JSim readable model and/or numeric data files and pass them, via switch setting to a jsbatch run. When jsbatch terminates, the Matlab then reads the appropriate jsbatch output files for further processing.

The JSim external API scenario is more complex, but (potentially) more computationally efficient. In this scenario a JSim engine in instantiated via a Matlab Java or C API, and is then called multiple times by subsequent Matlab processing. This approach saves the overhead of loading Java, jsbatch and compiling the model before each model run. The JSim API for doing this is undergoing an overhaul at present, due to the desire to make additional JSim functionality to various external software systems (especially finite-element and CFD modeling). A complete working example of the JSim API scenario will be provided once this overhaul is complete (expected fall 2008).

Example calling jsbatch from Matlab for Monte Carlo analysis

This example performs a simple Monte Carlo analysis. A Matlab mfile generates a set of sinusoidal data curves containing a small amount of random noise. Each curve is sent to jsbatch, which optimizes a model(monte1.proj) to best fit the data curve by varying the sinusoidal amplitude (parameter amp). After each optimization, Matlab collects the optimized values into an array and performs simple statistical analyses on them (calculating mean and variance).

The Matlab control script is as follows:


The JSim project, containing the model and optimization configuration my be downloaded below.

Notes:

Example calling JSim engine API from Matlab

This example will be provided once revisions to the JSim API are complete (expected Fall 2008).

Comments or Questions?

[This page was last modified 06Jul12, 3:12 pm.]

Model development and archiving support at physiome.org provided by the following grants: NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.