This page is for the current JSim version 2.0 and higher. Click here for the earlier JSim 1.6 version.
This tutorial take a new user through the process of launching JSim , running a simple model, and plotting results.
Starting JSim and loading an example model
JSim may be run by either installing it on your computer, or by connecting to a JSim enabled WWW site (such as this one). This tutorial works for either method.
To run JSim on your computer
- If you have not already done so, download and install JSim on your computer.
- Start JSim by double-clicking on the jsim icon (Windows or MacIntosh) or typing "jsim" on the command line (Linux).
- to your computer. This is the example model file you'll be using.
- Select "Import model file..." from the "Add" menu under the "Project" tab and select the intro1.mod you just downloaded.
The JSim GUI
Assuming all the above went well, you should now be looking at the JSim GUI (graphical user interface). On the GUI left-hand side (LHS) are tabs labeled "Project" (the table of contents) and "intro1" (the model you just loaded). On the right-hand side (RHS) are tabs labeled "Message" (progress and error messages) and "plotpage_1" (the first of perhaps multiple plot pages). In general, the JSim GUI LHS configures the models and the RHS displays numeric results.
Click on the LHS "intro1" tab. The model source code should now be visible (as indicated by the highlighted "Source" tab at the bottom). JSim model calculations are usually specified in MML (for Mathematical Modeling Language, more info), although the SBML and CellML formats are also supported. This model calculates tracer concentration in plasma(Cp) and interstitial fluid(Cisf) as driven by an inflow(Cin). The code should be fairly easy to comprehend if you are familiar with ordinary differential equations (ODEs) and note that the colon (:) operator represents differentiation (e.g. Cp:t means dCp/dt). The "extern" clause in the "Cin" declaration indicates that "Cin" values are supplied externally by the JSim, rather that within MML.
Compiling the model
Before models can be run, they must be compiled, which means translating the MML source code into an executable java code. Do this by clicking the "Compile" button. Compilation should take a few seconds, depending upon the speed of your computer. Compilation checks the completeness and consistency of model calculations and will abort with an error message if there is a problem. There should be no problem here unless you've inadvertently modified the MML source code or perhaps loaded the wrong model.
Running the model
When a model is successfully compiled, JSim switches from the model "Source" subtab to the model "Run Time" subtab, which lets users adjust parameter values and run the model. The JSim compiler classifies MML variables as either inputs (settable by the user) or outputs (calculated during a model run). JSim "parameters" refer collectively to MML input variables, numerical solver controls(more info) and function generator controls(more info). User-settable values are displayed with a light-colored background, immutable values with dark-colored one. Model "domains" represent the independent variables of the system(e.g. time & space). Here, domain "t" represents time. The sub-variables t.min and t.max represent the minimum and maximum values of time for a model run. t.ct represents the number of points in the time grid, and t.delta represents the time grid point separation.
A model run is initiated by pressing the "Run" button on the model "Run Time" subtab menubar. If you do that now, an error message will tell you that the input variable Cin has not been given a value. If you examine the "Model Inputs" block you can verify this is the case because the Cin(t) assignment box is blank. This is because the MML specified Cin as "extern", meaning its value would be assigned by JSim rather than within the MML itself. For this introduction, let's enter a constant value for Cin (e.g. 1). An alternate to a constant value here (as elsewhere in JSim) is to use an algebraic expression of model variables. However, since this model has "unit conversion on", getting the algebraic expression unitarily correct is somewhat tricky, so we'll avoid that complication for now (see Using Physical Units in MML for details). A second alternative is to drive Cin with a function generaton (see Using Function Generators in JSim for details).
Now, press the "Run" button again, wait a few seconds, and a status message will be printed indicating the model run completed successfully. Not much will have changed visually, because we have not set up to plot any results yet, but if you look carefully you'll notice the output variables now shows a numeric value from the completed run. Variables Cp(t) and Cisf(t) vary over time. The value displayed for them is the one last calculated. To view the entire time courses for Cp and Cisf, we will use JSim plot pages.
Plotting Model Data
One plot page, named "plotpage_1", is created when you start a new JSim project. More can be created, but one will serve for this introduction. Plot pages appear as tabs on the righthand side of the JSim project window. Select the plotpage_1 tab to take a look. The upper half of a plot page contains the "Plot Configurator" which is a set of controls for what data will be plotted, and how it will be rendered. The lower portion of the page is currently blank, but will contain the plot graphics once we've set up the plot. To make maximum area available for graphics, the plot configurator packs a large amount of functionality into a small screen area. This currently results in a rather dense and cryptic arrangement of controls. NSR continues to work on balancing clarity, functionality, and space considerations in the plot configurator.
Let's plot some data. The controls we'll discuss are all on the second line of the plot configurator, which starts with the label "Data". The first box to the right of "Data" shows the source of the data to be plotted, which can be a model or a data set. Here, since we have a single model and no data sets, there is only one possibility, so "intro1" is automatically selected. In more complex situations, with multiple models or data sets, you must select the data source manually. The blank box to the right of intro1 is the data from within intro1 to be plotted. Let's type "Cin" (don't type the quote marks) into that box and hit the enter key. The box should blacken (indicating that Cin is a valid expression within model intro1) and a graph of Cin should appear in the formerly blank graphics area. If the box does not blacken, double check your typing. If the box blackens, but no graph appears, it may be that the model run was not successfully completed. In that case, try again pressing the "Run" button on the intro1 "Run Time" subtab menubar.
Log and Linear Scaling
We now see a plot of Cin versus time, which should look like exponential decay. We can verify it is, in fact, exponential decay by checking the "Log" checkbox which will set log scaling on the Y axis. With log scaling on, Cin should appear as a straight line. Now uncheck the "Log" checkbox so that Cin appears as a curve under linear scaling.
Selecting Data to Plot
The interesting variables in intro1 are the outputs Cp and Cisf. You can display them by either typing them into the data selection box that currently holds Cin, or selecting them from the menu that is attached to the down arrow button to the right of the data selection box. You may also type algebraic expressions into the data selection box. In intro1, Cp+Cisf, Cp-Cisf, 0.5*Cin might be interesting possibilities.
Plotting Multiple Data Curves
It is often useful to see multiple data curves on a single plot. Let's plot Cp and Cisf. First, use what you've learned to get plain old Cp onto the current plot. To add a 2nd curve to the plot, click the button to the right of the label "Curve" and select "2" from the menu that pops up. The 2nd (and 3rd) lines of the plot configurator now reflect the second, rather than the first curve. We can specify what we'd like to see in the second curve just as we did in the first: by selecting Cisf in the data selection box. Now both Cp and Cisf should appear on your plot page. You can adjust the color, symbol, and line rendering characteristics for each curve with the 5 right-most controls on line 3. For instance, clicking on the solid colored button popups up a color menu.
Saving your work
At this point, we'll save our work. A JSim project file saves the complete state of a JSim GUI window so it can be reestablished in a single operation at a later time. To do this, activate the "Project" tab on the GUI LHS. Select the "Save" option from the "File" menu there. A standard file selection popup will appear allowing you to name your project file and save it in the directory of your choice. The suffix ".proj" will be automatically appended to the file name. If you select a directory that you don't have write permission for, an error message will alert you to this fact. In that case, you'll need to find a directory you do have write permission for. A message at the bottom of the project window will indicate a successful save. Remember the location and name of the project file you've saved.
JSim (version 2.19 and greater) also allows you to automatically save the project file associated with the last successfully run simulation, optimization, loops run, and sensitivity analysis. This backup can be useful when working on a very complicated model and for whatever reason the model stops working or JSim crashes unexpectedly during a long simulation. The backup file will be called "ModelName_LastRun.proj", where "ModelName" was the original project file name. To enable this feature go to the "Preferences" drop down menu of the "Project" tab. Choose "Auto backup project file" and chose "Yes". To make this change permanent, go back to the "Preferences" drop down menu and chose "Save preferences" at the bottom. This will save your preferences locally in the .jsim/local/preferences.xml file.
Reloading a project file
We'll now exit JSim and reload the project file you just created.
Select "Exit program" from the Project tab's "File" menu, and then restart JSim. Under the Project tab's File menu, select "Open project file". A file selection box will appear in which you should select the project file you just created. A new Project will open containing the project you just created. JSim allows multiple projects to be open at one time and allows you to paste content between the projects in a natural way. That is not covered in this introduction, however.
The reloaded project should contain an intro1 model tab. Clicking on this tab, you will see that the project load has reestabished the model source code, the compile state, and the assigned value of Cin. It does not reestablish the intro1 model run because, for large models, this might be unnecessary and very time consuming. In our case, the model run is quick, so click the Run button and check that the model run has completed (do you remember how? hint: Cp(t)). Clicking on the plotpage_1 tab, you should now see the plot page data and rendering in the same state you left it when you saved the project file.
Where to next?
To see what else JSim can do, select topics from Running JSim.
To write your own JSim models, start with Introductory Survey of MML and then select topics from Writing JSim models.
To find models of interest, visit the JSim Models Page.
Comments or Questions?
Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, 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.