JSim users normally use the Graphic User Interface(GUI) for routine modeling work. However, for debugging and batch processing, it is sometimes useful to run JSim models via the command line. The program jsbatch provides this functionality and is described in this document.

Prerequisites:

• Introduction to the JSim GUI (required)
• Introductory Survey of MML (required)
• JSim Projects (recommended)
• Data Files and Project Data Sets (recommended)
• Familiarity with command-line tools in Unix user environment (recommended).

Contents:

• Overview
• Command line synopsis
• Switches
• A detailed example using jsbatch
• Environment Variables

• Comments or Questions?
  Give feedback

Overview

jsbatch is a command-line driven, text-based program that loads JSim projects, builds and runs models and writes results in various formats. This approach to modeling can be useful for batch processing, or for debugging models or JSim internals. jsbatch provides no graphics or data-analysis facilities. Users requiring those abilities should use the JSim GUI. This document describes running jsbatch on Unix systems. Microsoft Windows users should make appropriate translations for that operating system.

The general sequence of jsbatch operation follows. This general sequence may be altered somewhat by switch selection.

1. If a project file (extension .proj) is specified via the -f switch, the project file is loaded. Otherwise, a new, empty project is created.
2. Any additional files specified via the -f, -func or -plot switches are loaded into the project.
3. The first model within the project is selected (unless overridden by the -model switch).
4. The selected model is built.
5. Any model inputs and other project variables values specified via the -i switch, are assigned.
6. The selected model is run.
7. Values for all model variables are printed on the standard output;

Command line synopsis

The following switches modify standard program behavior before the models are run.

Usage: jsbatch [ switches ]

Switches:
  -f file ...             load project, model & 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
  -builddirsfx suffix     force build directory suffix (experts only!)
  -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        
  -i var=expr ...         assign 1 or more model inputs or controls
  -func name ...          create 1 or more function generator
  -plot name ...          create 1 or more plot pages
  -rtml file ...          load model RTML from file
  -img file ...           load 1 or more model image files
  -lmod name              load source code into model
  -lpar name              load project par set into model
  -lxpar file             load XSim .par file into model
  -spar name              store model par set in project
  -filter dataset ...     filter 1 or more project datasets
  -iproj proj:name ...    import content from other projects
  -c name=value ...       set model compiler options

  -model name        specify which model (if multiple)
  -q [var ...]       query variable constraints
  -loops             loops run instead of normal run
  -sens              sensitivity analysis instead of normal run
  -optim             run optimizer instead of normal run
  -monte             run Monte-Carlo analysis instead of normal run
  -nruns #           # runs for each model
  -fwdIC             forward ICs after (each) run

  -o expr ...        output selected model expressions
  -oplot             output data from plots
  -ofgenprev         output data from function generator preview
  -odataset name     output data from specified dataset
  -ortml name        output selected model's RTML
  -out file          write output to file instead of stdout
  -odim #            select data of specified dimension
  -ofmt name         write output in named format
  -oblocked mn mx    write blocked output (if ofmt supported)
  -osingle           write single-precision output (default)
  -odouble           write double-precision output
  -oprec #           write custom precision output
  -ozero #           write small output data as 0
  -oencoding code    write format-specific output encoding
  -ocrash            write output even if run crashes
  -oreport           write optimization or Monte-Carlo report
  -oreports          write all optimization reports from Monte-Carlo run

  -oplan [variant]   write model plan to output (if available)
  -omathml           write model MathML to output
  -omml              write MML model to output (if available)
  -oxmml [variant]   write XMML informatics file to output
  -osbml [variant]   write SBML file to output
  -ocellml           write CellML file to output
  -oantimony         write Antimony model to output
  -omatlab           write Matlab .m model to output
  -oflat             write flat model to output (if available)
  -ojava             write java model to output (if available)
  -oproj [name ...]  write project content to output
  -oprofile          write run-time profile to output
  -opar name         write .par file to output
  -sdata name        store output in project dataset

Switches

-f file ...

Loads project, model and data files or URL contents into the current project. Only a single project file is allowed. Files are loaded based on their extensions:

• Project files: .proj
• Model files: .mod .xml .cellml .sbml .txt .java
• Data files: various, see recommended data file extensions here

-userurl url

Process command line files relative to this URL.

-userdir dir

Process command line files relative to this directory.

-path path

Overrides default value of environment variable JSIMPATH.

-server name

Use a remote computational server instead of the local one.

-plugin file ...

Load one or more optional plugins .

-usage

Print usage message and exit.

-stack

Print stack trace if program aborts.

-noscrub

Do not delete work files in temporary build directory ($HOME/.jsim/work*) after use (developers only).

-builddirsfx SUFFIX

Specify the temporary build directory as $HOME/.jsim/workSUFFIX. The specified build directory must NOT EXIST, or else JSim will exit with an error. This switch is for expert use only. It was added to prevent large numbers of simultaneous JSim jobs getting confused about whose build directory is whose. When using this switch, the user is responsible that no two JSim jobs are using the same build directory at the same time, lest unexpected (read bad) results occur. This switch is available in JSim 2.09 and above.

-sandbox [ path [ path ] ]

Run application in the JSim sandbox .

-nosandbox

Run application without the JSim sandbox (default).

-securityMgr class-name

Install custom security manager (developers only).

-sbwregister

Register JSim with SBW broker and exit.

-sbwmodule

Run JSim as an SBW module, allowing the SBW broker to send models to it.

-v

Run in verbose mode. Writes a multitude of fascinating arcana to the standard error while jsbatch is working (developers only).

-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.

-i var=expr ...

Assigns model input or project variables to constants or algebraic expressions. Extern variables have no default, and so must be set via this switch or the model will not run. Input variables are assigned to algebraic expressions of numeric constants, domain variables and/or other input variables. The order of input assignments in the command line does not matter, so long they create no circular dependencies. MML algebraic expression syntax is used. Since some MML operators will be interpreted by the Unix shell, the user must make use of quotes when appropriate. In the following example1, u, v(t), w(t) are input parameters:

jsbatch -i u=5 "w=u*v" "v=t^2" -f example1.mod

JSim (version 2.01 and above) replaces at signs (@) in -i arguments by spaces. This is helpful when specifying united constants which require spaces, because embedded spaces are not well preserved by jsbatch:

jsbatch -i "u=(1@meter)" -f example1.mod # processed as u=(1 meter)

Conditional expression:

jsbatch -i "P_t=(if(t<1@or@t>5)fvalue@else@0)" -f example1.mod 
   processed as: "P_t=(if(t<1 or t>5)fvalue else 0)" where P_t is a function of domain t 

-func name ...

Creates one of more function generators within the selected model(s).

A complicated example to give you a sense of the overall usage of jsbatch. This example simulation uses a data file (data.csv) as input for the function generator and the JSim model 'myModel.mod':

jsbatch -o Cout -f data.csv myModel.mod -func f1 -i t.max=10 Cin=f1 f1.domain0=t f1.which=DataCurve 
 f1.DataCurve.dataSet=data f1.DataCurve.name=exp1

 

Details:

• '-o Cout': Only output variable Cout.
• '-f data.csv myModel.mod' : Use data file 'data.csv' and model 'myModel.mod' for the simulation
• '-func f1' : define function 'f1' , this is used next to specify values for the input parameters.

What follows are values assigned to parameters (inputs):

-i t.max=10 Cin=f1 f1.domain0=t f1.which=DataCurve f1.DataCurve.dataSet=data f1.DataCurve.name=Cin

• 't.max=10' : specify run time of 10 (domain is t).
• 'Cin=f1' : Sets the external input variable 'Cin' to the function 'f1'

For the input function (uses a Function generator as input):

• 'f1.which=DataCurve' : Specifies that you want to use a data curve for the function generator.
• 'f1.domain0=t' : specifies the domain to use (corresponds to the first column of data)
• 'f1.DataCurve.dataSet=data' : Name of data set, corresponds to file name without extension.
• 'f1.DataCurve.name=exp1' : name of the second column of data set.

 

The two example files can be downloaded here:

 

-plot name ...

Creates one or more plot pages within the project. Note that this does not generate graphics, which are not currently part of jsbatch.

-rtml file

Imports custom RTML from the named file into the selected model.

-iproj projfile:name ...

Imports content from other project files. "projfile" here refers to the name of a project file. If the optional "name" and preceding colon are present, only the top-level project content (e.g. model, parameter set, plot page, data set, notes) with the corresponding name is imported, otherwise all top-level project content is imported. If imported content has the same name as existing content, the existing content is removed before import.

-c name=value ...

Sets various model compilation options. Options available are:

• maxBuildTime (integer): maximum compile time, in seconds. Default =120;
• initNaN (boolean): if true, initialize all variable caches with NaNs instead of zeroes. Useful to developers for compiler debugging. Default=false;
• traceNaN (boolean): if true, print message to console whenever a model variable is calculated as NaN. Option supported only on a local JSim server. Default=false;
• abortNaN (boolean): if true, abort model run whenever a model variable is calculated as NaN. Default=false;
• traceVars (String): Comma separated list of model variables to trace. Trace messages are printed on console as model runs. Default=empty;

-img file ...

Load one or more images into the selected model's image set. Image formats supported include GIF, JPEG and PNG.

-Imod file

Load model source code from file.

-Ipar parset

Load the named parameter set into the selected model before running the model or processing the -i switch.

-Ixpar file

Load the named XSim parameter file into the selected model before running the model or processing the -i switch.

-spar parset

Save the specified model parameters, after the -i switch has been processed, into the named parameter set.

The following switches affect the output printed by the program after the models have been run.

-model name

Selects the named model to run. If not specified, the first model in the project (if any) is selected. This switch is needed only for projects with more than one model.

-q [var ...]

Variable query. Queries properties and constraints of named variables. If no variables specified, all variables are queried. jsbatch then exits without running the model.

-loops

Run loops instead of single model run.

-sens

Run sensitivity run instead of a single model run.

-optim

Run optimizer instead of single model run.

A detailed example (all one line):

jsbatch -oreport -f myModel.mod data.csv -optim -func f1 -i f1.which=Gaussian 
f1.domain0=t Cin=f1 Vp=0.2 myModel.optim.optpar0.par=Vp myModel.optim.optpar0.min=0.1 
myModel.optim.optpar0.max=2 myModel.optim.optpar0.step=0.01 myModel.optim.maxCalls=10 
myModel.optim.optpar0.enabled=true myModel.optim.optmatch0.src=data 
myModel.optim.optmatch0.data=exp1 myModel.optim.optmatch0.expr="Cp(t,L)" 
myModel.optim.optmatch0.enabled=true

 

•  -oreport

  Generates an optimization report

•  -f myModel.mod data.csv

  Optimization uses JSim mml model file 'myModel.mod' and data set 'data.csv'

•  -optim

  Run an optimization in JSim.

•  -func f1 -i f1.which=Gaussian f1.domain0=t Cin=f1 Vp=0.2 

  Create a function 'f1'. Specifiy the inputs using '-i' flag. Specify the value of the inputs. Here we describe the function, f1, then assign it to variable Cin. Parameter 'Vp' is assigned a value of '0.2'.

• myModel.optim.optpar0.par=Vp myModel.optim.optpar0.min=0.1 
  myModel.optim.optpar0.max=2 myModel.optim.optpar0.step=0.01

  Vary parameter 'Vp' between 0.1 and 2 with step size '0.01'. Note: to specify optimization parameters you must prefix them with 'model name' followed by label 'optim'.

•  myModel.optim.maxCalls=10 

  Run optimization 10 times.

• myModel.optim.optpar0.enabled=true 

  Confirm you want to use specified parameter.

• myModel.optim.optmatch0.src=data myModel.optim.optmatch0.data=exp1 

  Specify dataset and dataset curve

• myModel.optim.optmatch0.expr="Cp(t,L)" myModel.optim.optmatch0.enabled=true

  This specifies which model expression to minimize against the data curve. In this case it is variable 'Cp' for all 't' at x=L. Cp is a function of domains t and x.

The two example files can be downloaded here:

 

For more optimization parameter names that you may want to vary, please set up an optimization in the JSim gui then save the parameter set. Next, view the plain-text parameter set from within JSim. This lists all of the parameter names available.

-monte

Run Monte Carlo analysis instead of single model run. In this case, the default output is the values of the optimized parameters. Alternative output is available via the -oreport or -oreports switches.

-nruns #

Specify number of times to run each model or to run models loops job. This is useful for developers checking for numeric agreement between runs.

-fwdIC [ domain=value ... ]

Forward ODE ICs after (each) model run. Forwarding applies only to 1-dimensional ODE state variables with user-set ICs. With no arguments, the previous run value at the domain maximum is forwarded.

-o expr ...

Specifies variables and algebraic expressions to write to the standard output. In its absence, all variables are output. Comments on algebraic expressions for the -i switch apply here as well. For example:

        jsbatch -o u v "u*v" example1.mod

JSim (version 2.01 and above) replaces at signs (@) in -o arguments by spaces. This is helpful when specifying united constants which require spaces, because embedded spaces are not well preserved by jsbatch:

jsbatch -o "u/(1@meter)" -f example1.mod # processed as u/(1 meter)

-oplot

Output project plot page data. Overrides -o.

-osensmat

Output sensitivity correlation coefficients for expressions specified by -o switch. If -o not present, uses all output variables from selected model. Requires -sens.

-fgenprev

Output function generators preview data (developers only). Overrides -o.

-odataset name

Output data are taken from the project data set of the name specified. Overrides -o.

-ortml

Output the RTML from the selected model. Overrides -o.

-out filename

Writes output data to a file, instead of standard output.

-odim number

Selects only data of specified dimension. Useful for format such as TacFileFormat, which only supports 1-D curves.

-ofmt format

Writes output data in various formats. Values for format follow. See Data Files and Project Data Sets for the details about supported data formats.

• line = Line Data Format (default)
• column = Columnar Data Format
• csv = Comma Separated Value Data Format
• pretty = Pretty Data Format
• TAC = TAC Data Format
• jsml = JSML Data Format
• matlab = Matlab Data Format
• i4bull = I4 Bullseye Data Format

-oblocked min max

Writes subset of output lines. This options is valid only if the DataWriter supports blocking. Currently, only PrettyDataFormat supports blocking.

-osingle

Writes output variables in single precision format (default).

-odouble

Writes output variables in double precision format instead.

-oprec #

Writes output variables to precision specified by user. -oprec 8 is equivalent to -osingle. -oprec 19 is equivalent to -odouble.

-ozero #

Writes output variables with absolute values less than # as 0. This can be useful when comparing two data sets.

-oencoding code

Changes DataWriter output encoding from default. Currently, this is supported only by JSMLDataFormat.

-ocrash

Writes output even if model run crashes. Many values will be NaN's, but other values can help model debugging.

-oreport

Prepends optimization report to output (requires -optim).

-oplan

Writes model planning information, rather than output variables. Models are not run.

-omathml

Writes MathML translation of model to output. Models are not run.

-omml

Writes model MML source code, if available. Overrides -o.

-oxmml [variant]

Writes model XMML model output. Overrides -o.

-osbml

Outputs the model translated into SBML. Overrides -o.

-ocellml

Outputs the model translated into CellML. Overrides -o. Available in JSim version 2.06 and above.

-oantimony

Outputs the model translated into Antimony. Overrides -o. Available in JSim version 2.03 and above.

-omatlab

Outputs the model translated into a Matlab .m file. Overrides -o. Available in JSim version 2.07 and above.

-ographml

Writes model browser GraphML output. Overrides -o.

-oflat

Writes flattened model MML code (developers only). Overrides -o.

-ojava

Writes JSim model Java code (developers only). Overrides -o.

-oproj [name ...]

Write final project content to output. Overrides -o. "name" here refers to the name of top-level project content (e.g. model, parameter sets, ...). If no names are specified, all project output is written.

-oprofile

Write run-time profile report to output.

-opar filename

Write parameter file (.par) to output. Overrides -o. This feature availabe in JSim 2.05 and above.

-sdata name

Stores output variables in the named project data set. Use with -oproj.

Environment Variables

JSIMPATH specifies the set of directories used when searching for files during the MML import command (e.g. import nsrunit). If not specified, the default is $HOME/.jsim/local:$JSIMHOME/local:$JSIMHOME/common:.

JSIMHOME specifies JSim's installation directory. On a Macitosh, JSIMHOME specifies the Resources directory inside the JSim application bundle. This is important to JSIMPATH, see above.

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.