JSim Batch Processing Manual (old version)

Introduction

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

This document applies to JSim releases 1.6.70 and earlier. See here for more recent information.

Prerequisites:

Introduction to the JSim GUI (required)
Introductory Survey of MML (required)
JSim Projects (recommended)
Data Files and Project Data Sets (recommended)

Overview

jsbatch is a command-line driven, text-based program that loads JSim projects, builds and runs the associated model(s) to produce numeric results, and writes those 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 their operating system. jsbatch is primarily a tool for model writers and debuggers.

Command line synopsis

jsbatch [ switches ]

Switches:

        -f file ...             load or import project file(s)
        -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
        -maxBuildTime #         set model build time-out (seconds)
        -sandbox [path [path]]  run application is safe sandbox
        -nosandbox              don't use sandbox (default)
        -v                      verbose mode
        -mp N                   enable up to N processor multiprocessing

        -i var=expr ...         assign 1 or more model inputs or controls
        -func model:name ...    create 1 or more function generator
        -plot name ...          create 1 or more plot pages
        -rtml name:file ...     load 1 or more model RTML files
        -img name:file ...      load 1 or more images
        -lpar model:name        load project par set into model
        -lxpar model:file       load XSim par set into model
        -iproj proj:name ...    import content from other projects      
        -spar model:name        store model par set in project

        -q [var ...]    query only, no model run
        -nruns #        # runs for each model
        -optim          run optimizer first
        -loops          loops run instead of normal run
        -fwdIC [t=val ...] forward ICs after (each) run
        -initNaN        initialize variable caches to NaNs
        -trace var ...  trace variable calcutions
        -traceNaN       trace all NaN calculations
        -abortNaN       abort at first NaN calculation

        -o expr ...     output 1 or more expressions
        -oplot          take output data from plots
        -odataset name  take output data from specified dataset
        -ortml name     take output from specified model's RTML
        -out file       write output to file instead of stdout
        -odim #         select data of specified dimension
        -ofmt line      write output in LineDataFormat (default)
        -ofmt pretty    write output in PrettyDataFormat
        -ofmt TAC       write output in TacDataFormat
        -ofmt JSML      write output in JSMLDataFormat
        -ofmt column    write output in ColumnDataFormat
        -ofmt i4bull    write output in I4BullDataFormat
        -ofmt matlab    write output in MatlabDataFormat
        -ofmt name      write output in plugin DataFormat
        -oblocked mn mx 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 format-specific output encoding
        -ocrash         write output even if run crashes
        -oreport        prepend optimization report

        -oplan  [variant]   write model plan(s) to output (if available)
        -omathml            write model MathML to output
        -omml               write MML model(s) to output (if available)
        -oflat              write flat model(s) to output (if available)
        -ojava              write java model(s) to output (if available)
        -oproj [name ...]   write project content to output
        -sdata name         store output in project dataset

Standard operation

jsbatch performs the following operation sequence:

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.
All models in the project are built.
Any model inputs and other project variables values specified via the -i switch, are assigned.
All models are run.
Values for all model variables are printed on the standard output;
Program exits with status 0 (normal).

All temporary build files are written the the session work directory ($HOME/.jsim/work*).

Input Switches

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

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

.proj JSim project file
.mod JSim model (MML) file
.flat JSim flattened model file
.java JSim .java model (extends JSim.mml.RTModel)
.tac XSim TAC file
.jsml JSim JSML data file
.cdata Columnar text data file

This switch also accepts complete URLs in version 1.6.58 and later.

-userurl url

Feature under development, not yet documented.

-userdir dir

Feature under development, not yet documented.

-path path

Overrides default value of environment variable JSIMPATH.

-server name

Connect to remote computational server .

-plugin file ...

Load one or more optional plugins .

-path path

Print usage message and exit.

-stack

Print stack trace if abnormal exit.

-maxBuildTime number

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

-sandbox [ path [ path ] ]

Run application in the JSim sandbox .

-nosandbox

Run application without the JSim sandbox (default).

-v

Specifies verbose mode. Writes a multitude of fascinating arcana to the standard error while jsbatch is working. This can be especially useful to model writers wondering why the Planner barfs on their model files.

-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. This feature is available in JSim versions 1.6.67 and above.

-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 assignments may not create circular dependencies amoung the input variables. 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

Note that the order of input assignments in the command line does not matter, so long they have no circular dependencies.

-func model:name ...

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

-plot name ...

Creates one or more plot pages within the project.

-rtml model:file ...

Imports custom RTML from the named file into the named 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. This switch available in JSim version 1.6.57 and above.

-img name:file ...

Load one or more images into a project image set. Image formats supported include GIF, JPEG and PNG. "name" here refers to imagesetname.imagename. RTML writers should note that image associated with model "drelb" is "drelb.images". The following example loads image leg.gif into the image set for model "axon" with name "Leg":

        jsbatch -f axon.mod -img axon.images.Leg:leg.gif -oproj

-lpar model:parset

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

-lxpar model:file

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

-spar model:parset

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

Output Switches

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

-q

Query mode. Before the models are run, the names, assigned units (if any) and default values of all input variables and the names and assigned units (if any) of all output variables are dumped to the standard output, and jsbatch exits.

-nruns #

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

-optim

Run optimizer before model run.

-loops

Run loops instead of single model run.

-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. JSim version 1.6.65 and above support the domain=value arguments, with which the domain value which is forwarded may be adjusted.

-initNaN

Initialize variable caches to NaNs. This can be useful in debugging code sequence errors in the JSim planner. For properly sequenced models, this switch should have no effect on output.

-trace var1 var2 ...

Trace values of specified variables to standard error. Available for JSim 1.6.59 and above.

-traceNaN

Trace values of any NaN's calculated to standard error. Available for JSim 1.6.59 and above.

-abortNaN

Abort model run at, or near, first calculated NaN. Available for JSim 1.6.59 and above.

-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

-oplot

Output data are taken from project plot pages. Overrides -o.

-odataset name

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

-ortml name

Output the RTML from the named 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 line

Writes output variables in LineDataFormat . This format is the default.

-ofmt pretty

Writes output variables in PrettyDataFormat instead.

-ofmt TAC

Writes output variables in TacDataFormat instead.

-ofmt JSML

Writes output variables in JSMLDataFormat instead.

-ofmt column

Writes output variables in ColumnDataFormat instead.

-ofmt i4bull

Writes output variables in I4BullDataFormat instead.

-ofmt matlab

Writes output variables in MatlabDataFormat instead.

-ofmt ...

Writes output variables in a custom pluggable DataFormat .

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

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

-oflat

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

-ojava

Writes resultant mode Java code. 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. Note that the "name" option is available only in JSim versions 1.6.57 and later.

-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. This in important to JSIMPATH, see above.

[This page was last modified 03Mar08, 3:11 pm.]

Model development and archiving support at physiome.org provided by the following grants: 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.