1. Welcome to the NSR Physiome Project!
  2. Physiome JSim
  3. The JSim Documentation Set
  4. JSim User Reference Manual

JSim User Reference Manual

Introduction

This reference describes options for launching JSim and controlling its appearance and basic behaviour. It assumes the user is somewhat familiar with JSim. Contents:

  • Starting JSim
  • Getting help
  • The user preferences file
  • Command-line switches
  • JSim environmental variables
  • Comments or Questions?

Give feedback

Starting JSim

JSim may be launched in three ways:

  1. Double-clicking on the JSim icon. In this case, you may control JSim's launch behavior only through environmental variables .
  2. Typing "jsim" at the command line. In this case, you may control JSim's launch behaviour through either environmental variables or command line switches .
  3. Pointing your browser to a JSim-enabled web-site. In this case, the web-site administrator, not the user, has control of JSim's launch behavior. See Administering a JSim Web Site for further information.

Getting help

The JSim documentation set, of which this document is but a small part, provides the most detailed description of JSim's functionality. In addition, context-sensitive popup help is available for many of JSim's menus and controls. When the help system is activated, pointing the mouse at many JSim menus, controls or model variables will pop up a small window containing a brief description.

"Hover" help (activated by default) pops up after ~1.5 seconds without mouse motion over a documented item. Hover help may be toggled on and off via the F1 key. "Fast" help (inactive by default) appears immediately when the mouse is over a documented item. Fast help may be toggled on and off via the shift-F1 key. Fast help can be useful if you're looking at lot of help popups and get impatient waiting for hover help to appear.

JSim applet users should note that the (plain) F1 keystroke is intercepted by most browsers for their internal help systems. In this case, once hover help is deactivated by the user (via shift-F1), it may not be reactivated within that JSim session.

The user preferences file

Some JSim appearance issues are inherently individual. An optimal font size will be larger for those with less acute vision, smaller for those with more acute. Preferred background color may be affected by aesthetics, color-blindness, eye contrast sensitivity, or monitor brightness. Such user preferences are stored in a JSim user's preferences file.

When JSim starts, user preferences from the file $USERHOME/.jsim/local/preferences.xml are loaded. If the file is missing or corrupt, default settings are used. User preferences may be reset at run-time in the "Project" tab's "Preferences" menu. Currently available preferences are:

  • Background color: This is a light blue by default. Several fixed colors are available in the "Preferences" menu, as well as a "Custom color" option for picking any possible color. If the selected color is too dark, it will be rejected and the default color reinstated. This preference may be overridden via the -rgb switch .
  • Base font size: This is a 12-point font by default. Several font sizes are used in JSim for clarity. All are scaled relative to this base font size. This preference may be overridden via the -fs switch . Keyboard shortcuts Cntl-Plus and Cntl-Minus (Command- for MacOS) for increasing and decreasing the current font size are available not only in the "Project" tab, but throughout the application.
  • Window size: This is the initial size of a project window (900x600 pixels by default). A project window may be resized using standard GUI mechanisms. When preferences are saved, the current window size is stored. This preference may be overridden via the -ws switch .
  • Backup project file: (JSim v2.19 and above) When set it will backup the last successfully run project file and store it in the current working directory labeled as "modelName_LastRun.proj", where "modelName" was the original project file name.

Modified preferences are not automatically saved. Selecting "Save preferences" from the "Preferences" menu will save your currently active settings (also note "Window size", above). The -noprefs switch represses loading of the preferences file. If your preferences file causes unworkable JSim behavior, restarting JSim with the -noprefs switch and then saving preferences will get you back to the default settings.

Command-line switches

Usage: jsim [ switches ]

Switches:
  -f file ...             load project, model and other files
  -v                      verbose mode
  -userurl url            load -f files relative to URL
  -userdir dir            set user directory
  -path path              set search path
  -server name            connect to remote server
  -plugin file ...        load optional plugin
  -usage                  print usage message and exit
  -stack                  print stack dump on error
  -noscrub                don't scrub build directory at exit
  -sandbox [path [path]]  run application is safe sandbox
  -nosandbox              don't use sandbox (default)
  -securityMgr class-name install security manager
  -mp N                   enable up to N processor multiprocessing        
  -noprefs                ignore user preferences file
  -rgb REDxGREENxBLUE     specify base color (0-255)
  -fs size                specify base font size (points)
  -ws WIDTHxHEIGHT        specify project window size (pixels)
  -popout                 create initial project in new frame (applet only)
  -demo [ expr ... ]      compile model, show model and plot tabs
  -sbwregister            register with SBW broken and exit
  -sbwmodule              run JSim as an SBW module

-f file ...

Loads a project file or one or more files into the current project. Only a single project file is allowed. Files are loaded based on their extensions:

  • JSim project files - extension .proj;
  • JSim model files - extensions .mod .flat and .java ;
  • JSim importable data files - extensions .tac .jsml .csv .cdata and .bul.

Load -f switch files relative the the specified URL, rather than from the local file system.

This switch also accepts complete URLs.

-v

Verbose mode. Write lots of tedious detail to standard error

-userdir directory

Overrides the environmental variable JSIMUSERDIR .

-path path

Overrides the environmental variable JSIMPATH .

-server name

Perform model calculations on a remote JSim server rather than on the local machine.

-plugin file ...

Load one of more JSim plugins .

-usage

Prints a list of available command line switches, and exits.

-stack

Prints a complete stack dump if any unexpected errors occur. This information can be useful when forwarding bug reports to the JSim development team.

-maxBuildTime number

Specifies the model compile timeout in seconds. The default is 120 seconds.

-securityMgr class-name

Installs custom security manager (for developers only).

-sandbox [ path [ path ] ]

Run application in the JSim sandbox .

-nosandbox

Run application without the JSim sandbox (default).

-mp N

Use a maximum of N processors for parallizable run-time calculations. If N is greater that the number of system processors, the lower number is used. By default, only one processor is used.

-noprefs

Ignore the user preferences file . User preferences are set to system defaults.

-rgb REDxGREENxBLUE

Sets the background color of JSim project windows where RED, GREEN and BLUE are integers between 0(darkest) and 255(brightest). If not specified, the color is drawn from the user preferences file .

-fs size

Sets the base font size (in points) for all windows. If not specified, the font size is drawn from the user preferences file .

-ws WIDTHxHEIGHT

Sets the initial size of project windows, in pixels. If not specified, the window size is drawn from the user preferences file .

-popout

Create initial project in new frame rather than the HTML page itself. Valid for applet usage only. JSim icon will appear in HTML page applet or object tag while applet is running. When JSim terminates, the JSim icon will be cleared.

-demo [ expr ... ]

Demo mode. At program launch first model and first plotpage tabs are pushed forward and the model is compiled. If optional expressions are specified, a plotpage containing those expressions is pushed forward instead. If the expressions are not found in any existing plot page, they are added to an existing blank plotpage or a new plotpage is created to hold them. If single numeric expression (N) is specified, the first N 1-dimensional model output variables are plotted. Switch can be useful for web tutorials, especially those for new users unfamiliar with navigating the JSim GUI.

JSim environmental variables

Environmental variables that control JSim are listed below. These are normally set to installation appropriate values by the system administrator. However, the user may override these values by various operating system specific mechanisms.

JSIMUSERDIR - points to the directory from which user will initially select files to import into or export from JSim. This directory then changes dynamically as the user operates the program. Two special values are:

HOME - sets JSIMUSERDIR to the user's home directory. This is the default when double-clicking on the JSim icon.

CURRENT - sets JSIMUSERDIR to the current directory. This is the default when launching JSim from the command line.

JSIMHOME - points to the directory where JSim is installed. On a Macintosh, JSIMHOME points to JSim.app/Contents/Resources. This is normally not changed, unless you have multiple JSim installations on your system.

JSIMPATH - describes an ordered set of directories where JSim searches for files it needs during a model build. These files include:

model files specified by the MML import command;

java class libraries and native libraries specified in MML functions and procedures;

scripts allowing access to native compilers, such as C and Fortran.

� The directory components in a path are separated by colons under Linux and semi-colons under Windows. If JSIMPATH is not explicitly set, it defaults to:

USERHOME/.jsim/local

JSIMHOME/local

JSIMHOME/common

. (the current directory at launch time)

Setting environment variables

Under Linux

Under Linux, or other Unix-like operating systems, the syntax depend on the Unix shell you are using.

For Bourne shell and derivatives (sh, bash, ...):

           VARIABLE=VALUE; export VARIABLE

For C-shell and derivatives (csh, tcsh, ...):

           setenv VARIABLE VALUE

Each Unix shell has initialization files that allow you to set environmental variables automatically each time you login. Mechanisms vary by shell and installation. See documentation for your shell, or contact your system administor for further information.

Under Windows

No information yet available.

Under MacOS

No information yet available.

Comments or Questions?

Give feedback

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.