Command Line Interface

DESCRIPTION

Various SIMION function like Refine and Fly’m can be invoked from the command-line interface. See the “Command Line Interface” appendix of the SIMION User Manual [8.0/8.1] for details. Some additional functions involing PA conversion can also be invoked from the SL Tools utility command-line (see SL Tools Tutorial).

The command line interface is more limited than the Lua API’s (see Programming API for SIMION), but it is also possible to invoke a Lua script from the command-line API (simion.exe --nogui lua example.lua).

You can also invoke the same command-line interface within Lua via the simion.command() function. This executes within the same SIMION process, not creating a new SIMION process (unlike using os.execute() or io.popen() on simion.exe which creates a new SIMION process). However as of SIMION 8.1, the new Lua API’s are often more flexible or at least can avoid writing to disk (e.g. simion.pas pa:refine() rather than the refine batch mode command).

New Command Line Options

The Appendix M - “Command Line Interface” in the 8.0/8.1 SIMION User Manual lists the SIMION command line options. Below are recent additions to the command line interface not mentioned in the manual.

–lua <code>

simion.exe --lua <arg> [command] - Executes the given Lua string or file (if <arg> is preceeded by a @). The execution occurs after opening SIMION and executing any SIMION startup script (simion.lua) and prior to running any given command. The --lua option can also be specified multiple times.

Example: simion.exe --lua "print('test')"

Example: simion.exe --lua "@c:/temp/test.lua" --lua "x=1" fly quad.iob

Another approach is to use a SIMION startup script (simion.lua file in the same folder as simion.exe).

Added in 8.1.2.8.

–quiet

Disables printing of status messages.

simion.exe --nogui --quiet refine drag.pa#

Disables output:

status,Refining...
status2,step=  1,##################################################
status,Refine completed: Iterations 1, Delta=1e-100 V in 0.00 Sec

Added in 8.1.2.28.

fly –remove-pas=d

Normally SIMION removes all PAs from RAM before and after flying an IOB. This option can suppress that. Values for d are

  • 0 - never remove
  • 1 - remove before flying
  • 2 - remove after flying
  • 3 - remove before and after flying (the default behavior)

One place where this is used is to fly with PAs already in RAM (see RAM-only PA# Refine)…

pa = simion.pas:open('quad.pa#')
pa:refine{convergence=5e-7, disk=false} -- does not save to disk
pa = simion.pas:open('quadin.pa#')
pa:refine{convergence=5e-7, disk=false}
pa = simion.pas:open('quadout.pa#')
pa:refine{convergence=5e-7, disk=false}
simion.command 'fly --remove-pas=0 quad.iob'

fly –disk=d

Whether to refine any PA# files entirely in RAM (0) or allow writing to disk (1 - the default). Note: Any PA0 files that are on disk, will be loaded from disk though. See RAM-only PA# Refine.

simion.exe --nogui --noprompt fly --disk=0 quad.iob

Requires SIMION 8.2EA-20141213.

fly –refine-convergence=d

Sets the Refine convergence objective (in Volts or Mags) for any potential arrays automatically refined upon loading the IOB. This is equivalent to the refine --convergence=d parameter.

Added in 8.1.2.21.

refine –resume

Whether to resume refining, reusing any existing .pa[0-9] files. 1 (yes), 0 (no), or if omitted will prompt.

simion.exe --nogui refine --resume=0 drag.pa#
simion.exe --nogui refine --resume=1 drag.pa#

Added in 8.1.2.28.

Filtering Output

When the command line interface runs, various data will output to standard output. Although some of this output can be controlled from the SIMION side, it is also possible to filter the output from the DOS “find” command or PowerShell “where” command, as shown respectively below for removing all lines containing the text “status2”:

simion.exe –nogui –noprompt fly example.iob | find /V “status2” simion.exe –nogui –noprompt fly example.iob | where {!$_.contains(“status2”)}

See also the --quiet command line option. –quiet.

Setting Command-Line Arguments and Environment Variables

You can invoke SIMION with special command-line options using a DOS command prompt (cmd.exe) or similar shell (e.g. PowerShell or Cygwin) or from an external program (which is outside the scope of this article).

Another convenient method is via a windows shortcut:

_images/command_args_shortcut.png

or from the SIMION command-bar even to launch a new SIMION process:

_images/command_args_bar.png

Environment variables can be set system-wide via the Windows System Control Panel too:

_images/command_args_env.png

Changes