JSim Batch Processing Manual
This page is for the current JSim version 2.0. Click here for the earlier JSim 1.6 version.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
- Environment Variables
- Comments or Questions? /ul>
- If a project file (extension .proj) is specified via the -f switch, the project file is loaded. Otherwise, a new, empty project is created.
- Any additional files specified via the -f, -func or -plot switches are loaded into the project.
- The first model within the project is selected (unless overridden by the -model switch). The selected model is built.
- Any model inputs and other project variables values specified via the -i switch, are assigned.
- The selected model is run.
- Values for all model variables are printed on the standard output;
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.
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 -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)
-func name ...
Creates one of more function generators within the selected model(s).
-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.
-lmod file
Load model source code from file.
-lpar parset
Load the named parameter set into the selected model before running the model or processing the -i switch.
-lxpar 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.
-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.
-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?[This page was last modified 12Sep12, 3:55 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.
