SIMION®
The field and particle trajectory simulator
Industry standard charged particle optics software
Refine your design: model > simulate > view > analyze > program > optimize it.
News: SIMION v8.1.3.4-TEST posted - EA with new GEM features! | ASMS 2017 posters
About | Documentation | Community/Support | Downloads | Ordering

SIMION 8.0 Command-Line Interface Reference

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. For the latest version of this see the printed SIMION 8.0 manual (Appendix M and/or the Supplemental Help file)

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

Any comments on this web page? (will be sent to SIS SIMION Support)
[Optional] Your name: email: phone/fax: