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

JSim Memory Usage

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


JSim allows users to create arbitrarily large models, which can tax a computer's memory and cause various problems. There are two methods for dealing with these problems - either by increasing the total memory available to JSim or by reducing the memory needed during a model run via every Nth point storage. This document provides information about these two approaches.



General Memory Considerations

Writers of large JSim models may need to be aware of system memory limitations. Real data in JSim models occupy 8 bytes per grid point, thus a model with 3 variables u(t), v(t), w(t) where t has 1000 grid points will occupy 3 x 8 x 100 = 24KB of storage. Variables with multiple dimensions quickly eat up memory. A variable u(x,t), where x and t both have 1000 grid points will occupy 8 x 1000 x 1000 = 8MB. Model runs with multiple inner and outer loops cause storage requirements to grow with the number of model runs.

Running a JSim model when insufficient memory is available will result in various failures. Often failures will occur during a model run, or when attempting to display large amounts of tabular data text. In these common cases, JSim should give a coherent error message, allowing you to save your work and restart JSim with more memory. However, memory overflow in a severely taxed system may occur in any part of the program, causing inexplicable crashes and/or freezes, so if you have reason to believe you are bumping your head on the memory ceiling, it is a good idea to restart with more memory to give JSim ample work space.

Setting JSim's Memory Ceiling

JSim runs inside the Java Virtual Machine(JVM), which defines at startup the maximum amount of memory that may be used. JSim, by default, starts the JVM with enough memory to run most models. This amount is a maximum of 1500MB on Linux and Macintosh and 1200MB on Windows. (Most Windows installations can run successfully with 1500MB, but at least one machine tested failed when more that 1200MB were requested). Memory is dynamically assigned, so having a large maximum will not necessarily monopolize system resources. However, if the memory assigned exceeds the system's physical memory, thus requiring paging to virtual memory, JSim performance can sag noticably. Also, placing an unrealistically large limit can allow renegade models to monopolize system resources. In severe cases, this can crash or freeze your operating system. Therefore, you should be cautious changing JSim's memory allocation.

The mechanisms for setting JSim's memory ceiling are different for each operating system:

Setting JSim' Memory Ceiling on Linux Systems

JSim memory usage is controlled by the JSIMMEM environment variable, which represents the maximum number of megabytes of memory allowed. The default value is 1500 (600 in JSim 2.06 and earlier). Here is an example for the C-shell setting JSim's memory allocation to 3GB:

      setenv JSIMMEM 3000

Further information on Unix environment variables .

Setting JSim's Memory Ceiling on MacIntosh Systems

When running from the command line, the above comments for Linux apply. Memory for the double-click JSim application is set via the Java "VMOptions" directive in Info.plist. Info.plist may be found in the Contents subdirectory of the JSim application directory. To change the default allocation, exit JSim, open the command-line tool, cd to the JSim application directory (it will have suffix .app), cd to Contents and use your favorite text editor to change the default value of "-Xmx1500m" (1500 MB) to a more appropriate value.

Setting JSim's Memory Ceiling on Windows Systems

JSim memory usage is set by JSIMMEM variable inside your jsim.bat or jsbatch.bat executables. These files are located in the win32\bin (or win64\bin) directory in your JSim installation directory. If you are not sure where JSim is installed on your system, consult your system administrator. You may edit these batch files in a text editor, changing the following line, as is appropriate:

      set JSIMMEM=1200  

Using Every Nth Point Storage

Every Nth Point Storage (ENPS) may be selected in a model's "Memory" tab, which available in JSim version 2.09 and above. The "Data storage" switch is set to "all points" by default. When the user changes the switch to "every Nth point", an integer control becomes visible for every realDomain in the model. This control has a default value of 1, meaning that all points for the domain are returned. If the value for domain x is set to N, then only every Nth point of that domain is stored, thus reducing the needed memory for variables with domain x by a factor of N.

ENPS implementation has changed over recent JSim versions. While the ideal is to only store every Nth point (thus reducing run-time memory requirements) some MML constructs (described below) are, as present, incompletely supported. To ensure uniform user operation, JSim currently switches automatically between run-time ENPS and query-time ENPS. Run-time ENPS store only every Nth point during run-time, while query-time ENPS stores all points internally, but only returns every Nth point to the user (e.g. for graphing). Implementation of run-time vs. query-time ENPS varies across recent JSim versions:

The following MML constructs are currently problematic for run-time ENPS:

We continue to work on the JSim run-time engine. It is our hope that, with further improvement, some or all the above problematic constructs can be rendered unproblematic. Note: We have found one model that shows very minor differences (at the 8th digit of significance) in results when ENPS is activated. It is possible this points to a larger problem. We continue to examine this issue.

ENPS controls are part of a JSim Parameter Set. The name for the "Data storage" switch is "memory.storeGrids" and the name for the Nth control for domain "t" is "memory.t.nth". These values may be viewed in any parameter set tab saved in release 2.09 or above. If you wish to loop over the Nth value, it is recommended you first use the GUI to set the "Data storage" switch to "every Nth point", and then loop over the parameter "memory.t.nth" (adjusted for the name of the domain).

Comments or Questions?

[This page was last modified 07Jun17, 12:50 pm.]

Model development and archiving support at 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.