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

Contents:

  • Comments or Questions?
  • 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:

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

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

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

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

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

    [This page was last modified 09May17, 5:01 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.