This document describes SIMION's command-line interface. The command line interface is important for controlling SIMION in batch mode (e.g. from an external program). (See also Wikipedia: command-line interface). Note: This API pertains to SIMION 8.0 beta and may change in the final release.
Contents
- Basic Usage
- SIMION Return Value
- SIMION Options
- --help
- --version
- --nogui
- --quiet
- --reserved-memory=size
- --default-num-points=num
- --default-num-particles=num
- --temp-path=path
- --editor=path
- SIMION Commands
- gem2pa
- refine
- fastadj
- fly
- lua
- SIMION Environment Variables
- SIMION_EDITOR
Basic Usage
simion [simion options] [command] [command options]
SIMION Return Value
On success, returns exit code 0. On failure, returns exit code 1.
SIMION Options
--help
Displays help message and immediately exits.
--nogui
Disables SIMION GUI (uses command-line, console mode instead).
Output and messages will be sent to standard output.
--quiet [FIX-NOT IMPLEMENTED]
Quiet mode
Only useful when "--nogui" is also specified. This causes verbose output to not be displayed. NOTE: Possibly an option could be added here to selectively disable certain output (e.g. status messages).
--reserved-memory=size
Reserves a certain number of bytes of contiguous memory for SIMION PAs before SIMION starts. This can be useful when creating PAs larger than ~1 GB since it may extend the maximum size of PA you can create.
Motivation: Without this switch, Windows can fragment SIMION's memory space (do to DLL loading). Fragmentation limits the maximum size of PA you can create since a PA must be stored in a contiguous region of memory in SIMION. Therefore, you might only be able to allocate approximately ~1.3G (under Windows XP), even if you have at least 2G free memory. With this switch, SIMION will reserve a contiguous region of memory of the given size upon startup (before loading DLLs) for use solely by PAs, and this region will never get fragmented, so you will be able to allocate a PA of at least that size if memory is available. The maximum limit imposed by 32-bit versions of Windows is 2G, but the practical limit is ~1.85G since some memory is required by SIMION itself. If this value is made too large (e.g. 2G), then DLLs will not load properly, typically causing SIMION to crash on startup with an error message. Reserved memory does not consume operating system memory until it is used, so if you may load multiple instances of SIMION, each with --reserved-memory=1.5G, and the total memory consumed will be near zero until you load a PA. The reserved memory region will, however, consume memory address space in each SIMION instance, thereby limiting memory allocation elsewhere in SIMION (e.g. ion memory).
Values: The default is 0. Maximum is near 2G in theory but realistically around 1.85G (under Windows XP). The value is specified in bytes unless units are appended: "K" (kilobytes), "M" (megabytes), or "G" (gigabytes) (e.g. "--reserved-memory=1.5G").
Note on /3GB switch on XP: Windows XP has a /3GB switch that can extend the user space from 2G to 3G. This switch has not been officially tested on SIMION, but with this switch set, the maximum reserved memory value will still be 2G due to a restriction in Windows (certain critical system DLLs load at 2G and therefore fragment the memory space at 2G). So, with the /3GB switch, you won't be able to create a 3G PA, but you might (though it's not officially tested) be able to create ~2GB and ~1GB PAs that exist simultaneously.
Note on 64-bit Windows: SIMION should run under 64-bit Windows, but it is currently only a 32-bit application and therefore will be limited to 4G. SIMION has not been officially tested on 64-bit Windows, and it is not known to what extent, if at all, it can take advantage of the extra 2G RAM.
--default-num-points=num
Sets the default number of grid points to allocate for PAs.
Default is 100,000.
Compatibility notes: In SIMION 7.0, this was specified as simple number on the command-line: "simion 100000".
--default-num-particles=num
Sets the default number of particles to allocate.
Default is 500.
Compatibility notes: In SIMION 7.0, this was specified as follows on the command-line: "simion #500".
--temp-path=path [FIX-NOT IMPLEMENTED]
Sets the default file system directory in which to save any temporary files (e.g. trajectory images).
By default, SIMION stores temporary files in the current project folder, but this would not work if that folder is read-only.
Compatibility notes: In SIMION 7.0, similar functionality was specify as follows on the command-line: "simion !". SIMION will use the TMP, TEMP, or Windows directory (in that order).
--editor=path
Specifies the path to the text editor for SIMION to use. This should be a program in the system PATH or an absolute (not relative) path (e.g. "c:\windows\notepad.exe").
See also notes on SIMION_EDITOR environment variable, which this value overrides.
SIMION Commands
Command: gem2pa
Converts a GEM file to a PA file, or writes a GEM file into an existing PA file.
simion gem2pa [gem2pa options] [gemfile] [pafile]
Example: simion --nogui gem2pa esa.gem
Example: simion --nogui gem2pa --x=3 --y=4 --z=5 --scale=2 --azimuth=10 --elevation=20 --rotation=30 --merge esa.gem out.pa
--x=value,--y=value,--z=value
(x,y,z) translation. Default is (0,0,0)
--scale=value
scaling value. Default is 1.
--azimuth=value, --elevation=value, --rotation=value
azimuth, elevation, and rotation angles. Default are 0 for all. Angles are in units of degrees
--merge
Merge GEM file into existing PA file instead of creating a new PA file.
gemfile
name of GEM file to use. This is a relative or absolute path.
pafile
name of PA file to use. This is a relative or absolute path. The default is to use gemfile with a ".PA" extension (e.g. "test.gem" becomes "test.pa").
Additional Notes
Any coordinate transformation (rotation, scaling, and translation) is applied in the same order as the GEM file LOCATE command (see GEM LOCATE command documentation for details).
Command: refine
Refine a PA.
simion refine [refine options] [pafile]
Example: simion --nogui refine --convergence=1e-7 test.pa
--help
Displays this help.
--version
Displays SIMION version and copyright info.
--max-iterations=num
Maximum number of iterations. Terminates prematurely if this limit is reached. Default is 20000.
--convergence=value
Convergence objective in potential (volts or mags). Default is 0.005.
--max-overrelaxation=value
Maximum overrrelaxation. Default is 0.9. This is an advanced option and is typically left unchanged.
--historical-memory-factor=value
Historical memory factor. Default is 0.7. This is an advanced option and is typically left unchanged.
Additional notes
See SIMION manual for details on the refine options.
Command: fastadj
Fast adjusts a PA0 file.
simion fastadj [fastadj options] [pafile] [potentials]
Example: simion --nogui fastadj ICR.PA# 1=200,2=250
--help
Display this help.
pafile
Name of PA0 (or PA#) file to fast adjust. If PA# file it specified, then it creates a new PA0 file and fast adjusts it.
potentials
Comma-delimited list of index-potential pairs. For example, "0=300,1=200,2=250" sets the fast scalable electrodes (0) to 300V, fast adjustable electrode #1 to 200V, and fast adjustable electrode #2 to 250V.
Command: fly
Load a workbench (IOB file) and fly particles.
simion fly [fly options] [iobfile]
Example: simion --nogui fly --recording-output=out.txt einzel.iob
--help
Display this help.
--adjustable name=value
Sets an adjustable variable. Variable name is case insensitive. Example:
simion --nogui fly --adjustable percent_energy_variation=0 --adjustable cone_angle_off_vel_axis=10 RANDOM.IOB
--grouped=b
Whether to fly particles grouped (1=yes, 0=no). Default is no.
--markers=d
Enable time markers every d microseconds. Default is markers disabled.
--marker-color=n
Color of time markers (if any). 1-15. Default is 1.
--particles=path
Name of .ION or .FLY file defining particles to use. By default uses FLY file or ION file (if any) associated with IOB (uses ION file if both ION and FLY files exist).
--programs=b
Enable (1) or disable (0) user programs (if any). Default is to enable any user programs.
--recording=path
Name of data recording (REC) file to use. By default uses REC file (if any) associated with IOB. A REC file specified here will override any associated with the IOB.
--recording-enable=b
Whether to enable data recording (1=yes,0=no). Default is yes if a REC file is defined, else no. If data recording is enabled with no REC file defined, then a blank REC definition is used, in which case only messages by user programs are sent to data recording.
--recording-output=path
File to save data recording output to. Default is NUL (i.e. record only to screen or standard output). Use of this option implicitly implies --recording-enable=1.
--repulsion=method
Repulsion method: "none", "beam", "coulomb", or "factor". Must be "none" if --grouped is 0. Default is "none".
--repulsion-amount=f
Repulsion amount. Not available when --repulsion is set to "none". Default is 1.00e-12A for "beam", 1.00e-17C for "coulomb", and 1.00 for "factor".
--rerun=b
Whether rerun fly'm is enabled (1=yes, 0=no). Default is no.
--retain-trajectories=b
Whether to retain trajectories on disk (1=yes,0=no). Default is yes.
--trajectory-quality=n
Trajectory quality factor. Default is +3.
--view-trajectories=b [FIX-NOT IMPLEMENTED]
Whether to view trajectories (1=yes,0=no). Default is yes in GUI mode and no in non-GUI mode.
iobfile
Name of IOB workbench file.
Command: lua
Runs the Lua interpreter. For details on Lua see www.lua.org. A Lua interpreter is embedded inside the SIMION executable.
simion lua [lua options]
Example: simion --nogui lua test.lua
All arguments after "lua" are passed transparently to the Lua interpreter, so the syntax and options supported are identical to the Lua interpreter. Refer to the Lua documentation for full details.
This can be a convenient method to invoke SIMION batch mode programs written in Lua.
SIMION Environment Variables
See also Wikipedia: Environment variable for background information.
SIMION_EDITOR
SIMION will use the text editor program specified in --editor command line option. If that is not specified, it will use program in the "SIMION_EDITOR" environment variable. If that is not specified it will use the program associated with ".txt" files in the Windows file associations. If the text editor program is not in the system PATH, then an absolute (not relative) path should be used (e.g. "c:\windows\notepad.exe").
If the editor program is [c:\windows\notepad.exe] and the file to edit is [c:\sim7\Geometry\DEMO.GEM], SIMION will invoke the command ("c:\windows\notepad.exe" "c:\sim7\Geometry\DEMO.GEM"). The quoting allows spaces in the paths.
Compatibility notes: In SIMION 7.0, similar functionality was provided via the GUI_EDITOR environment variable, which is still supported and is equivalent in function to SIMION_EDITOR but is deprecated in SIMION 8.0 in favor of SIMION_EDITOR. SIMION 7.0 also supported a "GUI_FILENAMES=LONG_FILENAMES" variable to turn on long file names. This is now ignored since long names are always passed in SIMION 8.
Possible Extensions [FIX-NOT IMPLEMENTED]
--nobeep - disable beeps
painfo - display PA header info (maybe fast adjust voltages too)
iobinfo - display IOB header info, e.g. PAs and adjustable vars
stl2pa - STL to PA, like in SL Tools.
rename "--recording-enable" option?
(c) 2006 Scientific Instrument Services, Inc.
David Manura
