Frequently Asked Questions (FAQ)

Installation

Which operating systems can SIMION run on? Are Mac OS and Linux supported?

SIMION is a native 32-bit Windows program that can run on all modern versions of Windows (Windows 2000 and above are formally supported). SIMION is also formally supported under Linux via Wine and Mac OS X via CrossOver, provided your CPU is Intel x86 compatible (including x86-64), in which case SIMION runs at native speeds. Virtualization is another option though less seamless. If your CPU is not Intel x86 compatible (e.g. PowerPC, Sun MIPS, etc.), then you’ll likely have much less luck since an emulator would be required, which is undesirable on a heavy number crunching application like SIMION. For further details, System Requirements.

I’m a beginner. Where do I start learning to use SIMION?

Here’s some pointers:

• Overview SIMION: Chapter 2 of the SIMION manual has a overview of SIMION and guides you through setting up a simple simulation. A copy of this chapter is also online.
• Familiarize with the GUI: Appendix C “SIMION GUI” of the version 8 SIMION manual (Appendix F in SIMION 7) has a basic overview of the GUI. This is more important for the older version 7.
• Explore examples: Appendix D “Sample Runs” of the version 8 SIMION manual (or Appendix C in SIMON 7) guides you through running a few of the examples. Once you know how to run examples, you can explore other examples in SIMION as well. Instructions are in the README.html files in each example.
• A couple screencasts of SIMION operation can be viewed.
• Chapters 3-8 of the manual describe in more detail the major components of SIMION. It can be useful to read this straight through, after getting a general overview of SIMION from the points above, but it can also be used as a reference.
• See the SIMION Frequently Asked Questions (this file). For other specific topics see SIMION Supplemental Documentation.
• The SIMION “short” and “advanced” courses may be of some help, though these are older (for version 7). These are in the “courses” folder inside SIMION’s program directory. Another SIMION-related course is at http://hipirms.org/ .
• For any questions, ask us.

Are SIMION 6.0/7.0 files compatible with 8.0?

Nearly all 6.0 and 7.0 files will run as is in SIMION 8.0. The only known difference, which is easy to fix, is

• In SIMION 6.0 PRG files, static variables used in initialize and terminate segments need to be changed to adjustable variables in SIMION 7.0 or above.

On the other hand, SIMION 8.0 files will not necessary run in earlier version (though some files do).

Features

How can I input geometries?

There are a variety of methods. See Geometry Input Methods.

Can collisional effects of ions flying through non-vacuum conditions be simulated?

See Ion-Gas Collisions.

Can space-charge effects be handled?

It has some capabilities for estimating the onset of space-charge. See Space Charge.

Can I write user programs in other languages?

SIMION version 8.0 supports Lua scripting, which is incorporated into SIMION itself. It also supports calling code written in other languages through the Lua interfaces (e.g. C/C++ can be compiled as a DLL and called from Lua as shown in the “examples” example or by compiling it as an EXE and running it via the os.execute or io.popen Lua functions). For compatibility, SIMION 8.0 also supports SIMION 7.0 PRG scripting, which is a more primitive language.

You can of course also utilize any programming language (including Excel) to post-process SIMION data recording output files, build initial particle definitions (.ION files), or invoke SIMION commands via the batch mode interface.

Older notes (SIMION 7.0): Technically, SIMION 7.0 can only run PRG user programs, and there is no built-in extension mechanism for running other languages. However, the SL Toolkit add-on (since merged into SIMION 8.0) works around this in two ways, both within the bounds of PRG code. The first is to translate a high-level SL program into PRG code with the SL Compiler and then have SIMION run the PRG code. The second is to write an SL program that remotely communicates with a running C++ program (using the SL Remote libraries). SL Remote (use v.1.0.2 or above) achieves this essentially via remote procedure calls (implemented internally using some obscure, but largely hidden from the user, workarounds using named pipes pretending to be array files). The one downside is that remote procedure calls add some ~10x-100x time overhead if you’re doing thousands or millions of individual calls, one or more per each simulation time-step (rather than batching them). SIMION 8.0 avoids these complications.

How can a short movie of a SIMION simulation be created?

See Movie Files.

Using Features

How can the PA grid scaling be changed to other than 1 mm per grid unit?

A potential array (PA) file in itself doesn’t have physical dimensions like mm. It is simply 2D or 3D rectangular array (a.k.a. grid or matrix) of points that could be scaled to any physical size. The real physical dimensions of the array are not assigned until you position (i.e. translate, scale, and rotate) an instance of the array into the workbench (IOB file) via the View screen.

The scaling factor is controlled from the View screen, PAs tab, Positioning panel, Scale “mm/gu” (mm per grid unit) field. This defines the distance in mm that each gap between successive grid units (grid units) corresponds to. The default is 1 mm/gu, but it can be increased or decreased. You can assign a different scaling to each PA instance in your workbench, and multiple instances of the same PA file can be assigned different scaling factors as well.

Note that if you reduce the scaling factor, you may want to click the “Min” button on the Workbench tab. This will shrink the workbench size to more tightly fit around the now smaller potential array instance it contains. This avoids a lot of empty space in your workbench that may make viewing difficult.

Typically, one first selects any grid size that is appropriate in terms of computational quality and memory/time requirements. Then, one sets the scaling factor in the IOB file so that the PA is of the correct physical dimensions.

If using geometry files, see the “courses_gem_suggestions folder and corresponding Appendix A of the “courses_notes.pdf”. Files. Suggestions” section from the included Advanced SIMION course. In particular, to make things easier, it is typically recommended that you specify an appropriate scale in the “locate” command such that dimensions in your GEM file correspond exactly to physical dimensions.

; note: gu = "grid unit"
 Pa_define(11,11,11,p,xyz)    ; 0.025 in/gu  or 0.635 mm/gu
;Pa_define(26,26,26,p,xyz)    ; 0.010 in/gu  or 0.254 mm/gu
;Pa_define(51,51,51,p,xyz)    ; 0.005 in/gu  or 0.127 mm/gu
;Pa_define(101,101,101,p,xyz) ; 0.0025 in/gu or 0.0635 mm/gu
 Locate(0,0,0,40)  ; 0.025 in/gu  or 0.635 mm/gu
;Locate(0,0,0,100) ; 0.010 in/gu  or 0.254 mm/gu
;Locate(0,0,0,200) ; 0.005 in/gu  or 0.127 mm/gu
;Locate(0,0,0,400) ; 0.0025 in/gu or 0.0635 mm/gu
{
E( 0){fill{within{sphere(0,0,0,0.250)}}}
}

Older SIMION 7.0 notes: See View screen, PAs tab, Edit function, blue “mm/gu” (mm per grid unit) field. On the SIMION 7.0 install CD, see the ” SIMION Class Files. Suggestions” section of the Advanced SIMION course.

Why do Modify and View screen dimensions seem to differ by one grid point?

It is important to understand this distinction so that your electrode positions are not off by one grid unit.

The Modify function represents the points on the vertices of the grid cells. The electrode material fills the interior of those grid cells when the surrounding vertex points are marked as electrode points. The View screen visualizes that actual electrode material. If in doubt, the View screen is what you should rely on for physical measurements.

The following picture illustrates this. Each section of electrode plate (green) is defined by five grid points (red) but is of width 4 grid units and height 0 grid units (infinitely thin, 100% transmission ideal grid). The spacing between the two grid sections is 2 grid units. By default, each grid unit corresponds to 1 mm unless you change the mm/gu scaling factor (see above).

How can particle flight performance be increased? I want to disable screen redrawing and writing the large ion trajectory file (traj*.tmp).

In View, Particles tab, reduce the trajectory quality (TQual) from the default +3 to 0 (see the Computational Methods appendix of the printed user manual for details on the trajectory quality factor). Time-step sizes can also be controlled via user programs (tstep_adjust segments).

Disable data recording, or reduce the amount of data generated.

In View, Particles tab, uncheck the View box to disable displaying trajectories and uncheck the View box next to it to disable writing the traj*.tmp file (which stores trajectories for viewing purposes). In lieu of the traj*.tmp file, you can use the data recording or user programming features to more flexibly record only the data you need. The size of the trj*.tmp file is an additional concern on older file systems and libraries having a 4GB file size limit. If you do generate a trj*.tmp, make sure its on a fast disk (e.g. not a remote network share).

See also Calculation Time.

Older SIMION 7.0 Notes: In View, on the “Normal” tab, the “V” and “R” buttons control this.

I want to record the initial and final positions of a particle on the same line of an output file.

One approach is to attached a user program to your workbench as follows:

-- mysystem.lua, SIMION 8.0
simion.workbench_program()
local xs = {}
function segment.initialize()
  xs[ion_number] = ion_px_mm
end
function segment.terminate()
  print(xs[ion_number], ion_time_of_flight)
end

Here, xs is a table that stores data keyed by particle number. It is consulted when outputting data upon particle splats.

An alternate approach is to post-process your output file. I’ll assume that you have Data Recording options set to record to the file “out.txt” and that “ion number” is checked under “What data to record”. Now, in your project folder containing your IOB file, create a file named “postprocess.lua” containing the following code:

-- postprocess.lua, SIMION 8.0

-- open files
collectgarbage()  -- ensure unused files are closed
local fin = assert(io.open("out.txt"))
local fout = assert(io.open("out2.txt", "w"))

-- read and merge lines based on first integer
-- on line (presumably ion number)
local saved = {}
for line in fin:lines() do
  local n = line:match("%d+")
  if n then
    saved[n] = (saved[n] and saved[n].." , " or "") .. line
  end
end

-- output file
for _,v in pairs(saved) do
  fout:write(v, "\n")
end
fin:close()
fout:close()

print "done"

Do a Fly’m to generate the “out.txt” file. Then to generate a text file “out2.txt” in the format you want, enter this in the command bar at the bottom of the SIMION window:

dofile "postpocess.lua"

P3270

How can I Data Record periodically, such as for an FFT calculation?

The easiest way is to enable Time Markers (on the View screen Particles tab) for a given period in microseconds and then in Data Recording set When to Record to All Markers. Time markers force time steps to end precisely on multiples of the given period and can also be used as a Data Recording event.

A similar thing can alternately be done with user programming by executing print statements at the appropriate times (ion_time_of_flight) in an other_actions segment. Care, however, is required to ensure that the data output occurs on the precise times. other_actions is only executed at the end of time-steps, so you want to ensure that time-steps end at the precise times in which you want to print data, such as by using a tstep_adjust segment. Note, however, that numerical error (e.g. 0.9999999999999 does not equal 1) may require introducing a small tolerance factor in time calculation in a tstep_adjust segment. If you don’t want to deal with the tstep_adjust segment, just set the trajectory quality factor (TQual) to some sufficiently high value to make the time-steps very small to minimize error.

What are PA/PA#/PA0/PA1/PA2/PA3 files? How do they differ?

See :doc:potential_array_types`.

How does the trajectory quality factor (TQual) relate to time-step sizes?

The formulas are given in the Computational Methods Appendix of the SIMION 8 and 7 manuals (e.g. “H.23 How Trajectory Quality is Controlled” and prior sections in the SIMION 8.0 manual). For example:

• A value of 0 indicates a step distance of 1 grid unit (gu).
• A value of -9 would indicate a step distance of 1/(1 + abs(-9)) = 0.1 gu.
• A value of 109 would indicate a step distance of 1/(1 + abs(109-100)) = 0.1 gu, but in addition time-steps may be dynamically reduced in certain regions to improve accuracy.
• Values between 0 and 99 inclusive indicate a step distance of 1 gu, but in addition (for values > 0) time-steps may be dynamically reduced in certain regions to improve accuracy. The default value is +3 (or 0 for grouped/charge-repulsion flying).

You can confirm this behavior by enabling Data Recording to record X position at Ion’s Every Time Step for a particle traveling in the X direction. This is more easily seen in regions of zero fields and away from electrode surfaces since otherwise (for values > 0) the dynamically adjusting time steps may kick into effect.

Furthermore, if you enable time markers (on the Particles tab), time-steps will be reduced to coincided with those markers. This can be a quick way to force time-steps to be below a certain size in units of microseconds (rather than just grid units). It can also be useful to ensure data is recorded at exact time-intervals (e.g. as some have needed for computing an FFT for ICR work).

If you need greater control over time-steps, you may define ion_time_step explicitly in a tstep_adjust segment of a user program. Some examples that apply RF waveforms (e.g. “quad”) do this to ensure that time-steps are, for example, below a given fraction of the RF period. Others like the “buncher” example do this to ensure time-step boundaries coincide precisely on voltage transitions. Some collision models (e.g. HS1) do this to ensure time-step sizes are below a given fraction of the expected collision frequency.

How can I force particles to stop at a certain location or time?

You can attach a user program like this to your workbench (IOB):

simion.workbench_program()
function segment.other_actions()
  if ion_px_mm >= 50 then  -- or "ion_time_of_flight" for time in microseconds
    ion_splat = 1
  end
end

Note however that it’s likely that a time-step staddles the position x = 50 mm, in which case your particle will stop slightly after 50 mm (which might not be ok with you). A simple way to reduce that small skip is to just increase your trajectory quality (TQual) factor. Or you could write a tstep_adjust segment to ensure that time steps end exactly at the desired end positions. More simply, you can use the test plane library (see SIMION Example: test_plane) available in 8.1 (or 8.0 Check for Updates), which handles this all for you.

Yet another solution, which involves no user programming and avoids the time-step inaccuracies, is to add a “stopper electrode” to your workbench. To do so, create a small PA file that contains only electrode points (no empty space) and add it to your workbench at the location where you want to splat ions. The PA must have the highest priority number in the PA Instances list on the PAs tab on the View screen; otherwise your particles might never see it. This stopper electrode, thankfully, will not affect your fields in the rest of your system because fields between PA instances do not interact in SIMION, so your particles will (correctly) not observe any effects from the stopper electrode until they actually hit it.

Another possibility is to refine your PA and then use the Modify Find/Replace functions to convert some non-electrode points to electrode points. However, be careful never to refine the array again, even if SIMION prompts you, because this electrode will affect the fields around it if you re-refine. Therefore, this approach may be error prone. Setting simion.pas pa.refinable to false can suppress the prompts to refine though.

How can a fast_adjust segment control electrodes in multiple arrays?

You can differentiate between PA instances using the ion_instance reserved variable, which contains the sequence number of the PA instance that the current particle is contained in:

simion.workbench_program()
function segment.fast_adjust()
  if ion_instance == 1 then
    adj_elect01 = 20
    adj_elect02 = 30
  elseif ion_instance == 2 then
    adj_elect01 = 20
    adj_elect02 = sin(ion_time_of_flight)
  end
end

The above causes Electrodes 1 and 2 of the first PA instance to have potentials of 20 and 30 V respectively. In the second PA instance, Electrode 1 is set to 20 V and Electrode 2 is set to a sinusoidal waveform.

The way this works is that whenever SIMION wants to know the electrode potentials, it sets various reserved variables (including ion_instance) for the state of the particle it is currently calculating, it calls the fast_adjust segment, and then it reads the electrode voltages that the segment set.

The code can also be used in an init_p_values segment. The only difference is that ion_instance takes a more general meaning here: it is the “number of the PA instance that SIMION wants to determine electrode potentials for”, making no mention about particles since init_p_values is not called in the context of particle flying but rather is typically is called before any particles fly.

In a multiple-PA system, you may find simpler to not reuse electrode numbers. In the above example, the second array could instead have Electrodes 3 and 4. As of SIMION 8.0.4, PA# file electrode numbers need not start at 1 nor be sequential (Issue-I414). However, sharing electrode numbers is convenient if an electrode (e.g. #1) spans multiple arrays, for then you can set the adj_elect01 variable regardless of PA instance number:

simion.workbench_program()
function segment.fast_adjust()
  adj_elect01 = 20  -- same regardless of ion_instance
  if     ion_instance == 1 then adj_elect02 = 30
  elseif ion_instance == 2 then adj_elect02 = sin(ion_time_of_flight) end
end

How does fast_adjust differ from init_p_values and the Fast Adjust button?

Fast adjusting an array changes the potentials in the array to reflect a new set of electrode voltages, without needing to re-refine the array. It does this by consulting the electrode solution arrays.

There are a few slightly different ways to accomplish this.

The Fast Adjust button in SIMION will update all points in your array. In doing this, it streams all necessary electrode solution arrays from disk, which is relatively so but doesn’t use much additional RAM though.

The init_p_values segment in a user program behaves somewhat like the Fast Adjust button, except that it loads any necessary electrode solution arrays entirely into RAM, so it will consume more RAM but doesn’t need to reload electrode solution arrays from disk if the segment is called twice. This segment is called during the beginning of a run, including (if reruns are enabled) the beginning of each rerun.

The fast_adjust segment is called every time SIMION needs to know the field at some particle position (which can be multiple times per time-step). Like init_p_values, it loads any necessary electrode solution array into RAM. However, it doesn’t update an .pa0 array; rather, it just computes fields that would exist at only the current particle location with the electrode voltages defined by the latest call to the fast_adjust segment. This process can be quite fast, as it needs to be if it is to be called so frequently. The fast_adjust segment is usually necessary if you need to have time-dependent electrode voltages during a single run (e.g. RF or pulsed voltages). For static voltages, both fast_adjust or init_p_values could be used (or none at all if the potentials set via the Fast Adjust button are fine), but one of the methods may be faster. See Appendix L.2 “User Programming / Workbench User Programs” of the SIMION 8.0 manual for further discussion.

In SIMION 8.1 (or 8.1 early access), arrays in memory can also be fast adjusted programmatically from Lua, like pa:fast_adjust{[1]=10, [3]=30} or using the optional table argument pa:potential_vc or pa::field_vc, which provides even more flexibility, basically allowing you to invoke any of the techniques above at any time. See Issue-I422.

How can a custom distribution be added to a FLY2 file?

The FLY2 file must be edited as text since this cannot be done via the GUI. Set some parameter to a distribution object whose parameter is your own Lua function that returns random numbers. The following example FLY2 file defines a chi-square distribution in terms of a Guassian distribution and uses this in the particle definitions:

local STAT = require "simionx.Statistics"

function chi_square3()
  local stdev = 1
  local mean = 5
  return (STAT.gaussian_rand()^2 + STAT.gaussian_rand()^2 + STAT.gaussian_rand()^2)
         * stdev + mean
end

particles {
  standard_beam {
    n = 10,
    ke = distribution(chi_square3)
  }
}

To check this is working properly, temporarily change “How are particles defined?” to “Individually (.ION)” on the particle definition screen and examine the definition of each particle. Make sure that the KE parameter is properly randomized.

There are techniques as well as pre-existing routines for generating random variables according to various distributions. The rand() function returns returns uniformly distributed random numbers between 0 and 1. The STAT.gaussian_rand() function used above returns Gaussianly distributed random numbers with mean 0 and standard deviation 1. Some distributions like chi_square() can be written in terms of others or generated by various algorithms. Consult Wikipedia for details on specific distributions.

Further information is Post 3325 and Post 1618.

Another approach is to use an ION file with individual particle definitions generated from external software. See Particle Initial Conditions.

In CAD import (STL to PA), all electrodes are set to 1V.

By default when an STL file is converted to a PA, all electrodes in the generated PA are set to 1V. This is because STL files do not store electrode voltages.

One way around this is to use multiple STL files, one per electrode, rather than a single STL file. Some CAD softwares can export one STL file per electrode (or “component”). For example, in SolidWorks, when exporting the STL file uncheck the box “Save all components in an assembly to a single file”, and this will save multiple STL files (e.g. tof-1.stl, tof-2.stl, and tof-3.stl). SL Tools can convert the set of STL files all at once, assigning each electrode a different voltage, according to the section titled “multiple electrode systems” in http://simion.com/sl/tools_tut.html#v2pa . In the example above, you will need to specify “tof-%.stl” as the input file name, which will select all matching STL files (where “%” is a wildcard that matches all numbers). This relies on the assumption that the coordinate system in all the STL files is the same, as is usually in CAD softwares (if not there may be some ways to force it, such as adding a common box around all components).

If you can’t get your CAD software to do that, an alternate approach is, after conversion of STL to PA, to fix up the voltages of your PA in the SIMION Modify function using Find+Replace functions as shown in this screencast ( http://simion.com/screencast/find-replace ) and further described in Chapter 5 of the manual.

How can I export data from a SIMION PA into a text file? or import (write) PA data?

There are a number of ways to do this:

• Data recording along particle path trick. This is a convenient approach for exporting data in the limited case along a line or path. It works in SIMION 7.0 and 8.0. Use SIMION Data Recording to record potentials or potential gradients on every time step or (with time markers enabled) on every marker. Set the output to a file in “delimited” (not “verbose”) format. Make a particle follow a path you want to record data on. Particles with zero charge can be useful here since they always fly in a straight line. You can also use a user program (Lua or PRG) to force the particle to follow a certain path (like in this article), but there are better ways noted below to do this in SIMION 8.0.
• Export the entire array to a text file using SL Tools. This can be done via the Converting a PA File to ASCII Text conversion function in the SL Tools (sltools.exe) utility included in SIMION 8.0 (and previously in the SL Toolkit SIMION 7.0 add-on package). If you need even more flexibility, use the SL Libraries or Lua PA API below.
• Use the SL Libraries to programmatically read or write a PA file from languages like C++, Perl, and Python. Warning: only the C++ implementation of SL Libraries can handle very large arrays consuming near the 2 GB memory limit. You can also program this yourself according to the PA file format specification near the end of the “Files used by SIMION” appendix of the SIMION user manual (7.0 or 8.0). See also the “pa2text” and “swirl” examples included in SIMION 8.0 (or the older SL Toolkit).
• Use the Lua PA API (SIMION 8.1). It is similar to the SL Libraries technique but accesses in-memory SIMION arrays directly inside the running SIMION process and does so using Lua. It can even be accessed from the bottom SIMION command bar for quick one-liners. This offers additional flexibility.
• If you need to access only a few specific points, you may manually read/write points using the SIMION Modify screen. This may be sufficient in limited cases.

How can I combine electric and magnetic fields?

See Combining electric and magnetic fields.

Errors

My PA contains a single electrode, but no fields are shown.

In short, in order for a non-zero field to be calculated inside a PA, the PA must contain at least two electrodes of dissimilar potentials. All space potentials computed inside the array will be bounded between the minimum and maximum electrode potentials.

The underlying reason for this rooted in the properties of the Laplace equation, upon which the SIMION field solver (Refine) is based. The Laplace equation can be uniquely solved only if suitable boundary conditions are specified over some surface enclosing the volume containing your field. Points with known potential, such as electrode surfaces, define one type of boundary conditions (Dirichlet boundary conditions). A sure way to obtain a reliable field is to completely enclose your field region with electrode surfaces of known potential. This is typically done by surrounding the entire system with a “ground cage”. This isolates the internal fields from the external world (providing a controlled environment), enhances safety, and offers sufficient required conditions to solve that field via the Laplace equation.

If the boundary points on your PA are not electrode points, SIMION assumes, for lack of better direction from the user, that these points have roughly Neumann boundary conditions (derivative of potential along the direction normal to the boundary surface is zero). Neumann conditions are required over mirror symmetry planes wherever Dirichlet conditions are lacking. They can also be useful if a field has approximately 2D symmetry along the direction perpendicular to the boundary. For example, the Einzel lens in “examples.pa#” approximates the condition of the first and third cylinders being infinitely long. To do this, Neumann boundary conditions are specified at approximately field-free regions of the end cylinders, which occur at sufficient distance into the end cylinders. In this case, the boundary points are approximately field-free and have known constant potential, so a Dirichlet condition may alternately be used here. A better example is “examples.pa#”, where the rods are cut with a Neumann boundary plane at a location sufficiently deep into the rods so that the field in the axial direction is zero. Here, traverse components to the fields still do exist, so a Dirichlet condition would not be as easy to specify. This cutting allows the central rod region (quad.pa#) to be solved separately from and at higher accuracy than the quadin.pa# region. In the einzel.pa# example, Neumann boundary conditions are also used outside the gaps between cylindrical electrodes. This roughly approximates the condition of the tubes being surrounded by empty space. In this case, the gaps are very small, so the fields outside the lens can’t significantly leak into the lens, and even if they do they are relatively small in magnitude compared to the transverse field due to the potential difference between lens elements. That is, the boundary conditions outside the lens are not that important, and to the extent that they do have an effect, a Neumann condition may be more representative of infinite surrounding empty space than a Dirichlet condition. If you do care about fringe effects near open PA boundaries, it is better to add much more empty space near that boundary as shown in the sector magnet example (“examples90.pa#”) so that the fields can more properly expand into that empty space.

See First Uniqueness Theorem for more details.

My PA has nz=1 and no symmetry, but in ISO View it looks like a brick 100 units thick.

A PA with nz=1 (i.e. one grid point, or zero width, in the Z dimension) is treated specially by SIMION as a system with 2D planar symmetry with the geometry in the XY plane projected infinitely down the z axis. When the array is placed into a workbench, you can limit the extent of this z projection to a finite value (SIMION 8.0: View screen, PAs tab, Positioning panel, “nz use” field in grid units) (SIMION 7.0: Ion Optics Workbench | PAs | Edit | nz use” field). The “examples.pa#” array is an example of this, which represents a 2D cross-section of infinitely long rods.

You may have an electrode like a metal plate or a wire mesh that might itself be representable on a 2D plane, and you might be tempted to model it using a 2D PA. However, the field in-front or in-back of the plate likely lacks 2D symmetry, so you need a 3D array to represent this field. Using a 3D array with the smallest number of points in the Z direction (e.g. nz=2) is still insufficient: You must include sufficient extra space and other electrical conductors facing the plate inside the array in order for the SIMION Refine function (Laplace solver) to properly calculate and represent the fields in the regions facing the plate. See Grid and First Uniqueness Theorem for further details on this.

My initialize and terminate user programming segments are not executed.

The initialize and terminate segments are called each time a particle is respectively created or terminated inside the volume of a potential array instance. When all particles are outside potential array instances, or even on boundaries, the segments are not called. When a particle is inside both electric and magnetic PA instances, these segments are called twice per particle inside. This actually holds true for most segment types: segments only execute within the context of particles and potential array instances.

Sometimes you want code to be executed exactly one regardless, so the initialize and terminate segments are less than convenient. Therefore, SIMION 8.1.0.32 adds new segment.initialize_run() and segment.terminate_run() segments that are called exactly once per run regardless. These new segments are simpler and more robust for execting code that must be called exactly once before and/or after each run. (The initialize/terminate segments, however, remain convenient for accessing particle parameters because these segments gain read/write access to data on each particle and PA instance via reserved variables through a series of calls.)

In SIMION versions prior to 8.1.0.32, you can, with care, achieve an effect similar to these new segments using techniques like this:

simion.workbench_program()
function segment.initialize()
    if ion_instance == 1 and ion_number == 1 then
        print 'this should execute once'
    end
    -- warning: This SIMION 8.0 workaround fails if particle #1 is
    --          not created inside PA instance #1.
end

If you need to ensure initialize/terminate segments are called, take care in defining your particle starting points and make sure your particles don’t exit your potential arrays and then splat outside. Clicking the “Min” button on the Workbench tab will shrink your workbench volume to more tightly surround your potential arrays and may eliminate dead-volume. You may need to force your particles to terminate inside the array volume. For example, a user program to keep ions approximately within a certain box volume can look like this:

simion.workbench_program()
function segment.other_actions()
   if not(ion_px_mm > 10 and ion_px_mm < 20 and
          ion_py_mm > 10 and ion_py_mm < 20 and
          ion_pz_mm > 10 and ion_pz_mm < 20)
   then
       ion_splat = 1
   end
end

Alternately, you may add electrodes, or an entire ground cage, that act as stoppers. Extra electrodes do affect fields, but you can avoid this by creating a larger array of solid electrode points that contains your real array but is at a lower priority number in the PAs tab PA Instances list, in which case the particles only see the larger array if they exit the smaller array, and on entering the larger array they will immediately splat.

To confirm whether initialize and terminate segments are being called, you may add print statements in a user program:

simion.workbench_program()
function segment.initialize()
    print('initialize', ion_instance, ion_number)
end
function segment.terminate()
    print('terminate', ion_instance, ion_number)
end

fast_adjust segment behaves oddly with Grouped flying enabled or ion_time_of_flight reverses direction

fast_adjust segments should be written carefully to avoid them being dependent upon a certain order of execution. SIMION is free to call fast_adjust segments in any order, so wrongly assuming a particular order may lead to situations where a fast_adjust segment seemingly works in one situation but fails in another.

To see this, note that the user program

simion.workbench_program()
function segment.fast_adjust()
  print(ion_number, ion_time_of_flight)
end
function segment.other_actions()
  print('*')
end

with two particles might print results like

1 0.000   1 0.000   1 0.025   1 0.025   1 0.050   1 0.000   *
1 0.050   1 0.075   1 0.075   1 0.101   1 0.050   *
1 0.101   1 0.126   1 0.126   1 0.151   1 0.101   *
...
2 0.000   2 0.000   2 0.025   2 0.025   2 0.050   2 0.000   *
2 0.050   2 0.075   2 0.075   2 0.101   2 0.050   *
2 0.101   2 0.126   2 0.126   2 0.151   2 0.101   *
...

and with Group mode flying enabled might print results like

1 0.000   2 0.000   1 0.000   1 0.025   1 0.025   1 0.050
 1 0.000   2 0.000   2 0.025   2 0.025   2 0.050   2 0.000   *   *
1 0.050   1 0.075   1 0.075   1 0.101   1 0.050   2 0.050
 2 0.075   2 0.075   2 0.101   2 0.050   *   *
1 0.101   1 0.126   1 0.126   1 0.151   1 0.101   2 0.101
 2 0.126   2 0.126   2 0.151   2 0.101   *   *
...

and with overlapping magnetic and electric PAs, you might see twice the number of ‘*’ markers, and if sim_update_pe_surface = 1 is further added to the other_actions segment with PE viewing enabled, you might see results like this:

1 0.000   2 0.000   1 0.000   1 0.025   1 0.025   1 0.050   1 0.000
 2 0.000   2 0.025   2 0.025   2 0.050   2 0.000   *   1 0.000   *   *  2 0.000   *
1 0.050   1 0.075   1 0.075   1 0.101   1 0.050   2 0.050   2 0.075
 2 0.075   2 0.101   2 0.050   *   1 0.050   *   *   2 0.050   *
1 0.101   1 0.126   1 0.126   1 0.151   1 0.101   2 0.101   2 0.126
 2 0.126   2 0.151   2 0.101   *   1 0.101   *   *   2 0.101   *
...

As seen, the order in which fast_adjust segments are executed is not always obvious. The ‘*’ markers above indicate that the fast_adjust segment is evaluated multiple times per time-step per particle. Typically it evaluates five times, though sometimes it is more or less, such as when approaching boundaries. Within each time-step, the fast adjust times are not entirely in chronological order, particularly on the fifth and sometimes later evaluations. When flying ions individually (Grouped checkbox disabled), each time a new particle trace is started the time is reset to the current particle’s time-of-birth (typically zero). When Grouped mode is enabled, the fast adjustments in each time step are evaluated concurrently for all flying particles. When reruns are enabled, the time is reset to zero upon the start of each rerun. In other occasions, like with sim_update_pe_surface set, additional fast_adjust calls may be made. See also the updated flow diagram (Issue-I304) to further understand the behavior.

The lesson learned from this is that you should not rely on the fast_adjust segment being executed in any particular order. The fast_adjust segment should make its voltage adjustments using only the information in the reserved variables passed to it, such as ion_time_of_flight, ion_number, ion_instance, etc. It should not make its adjustments based on “side-effects” from other variables external to the current invocation of the fast_adjust function. For example, to define a square waveform, don’t do something like this:

-- bad
simion.workbench_program()
local offset = 0  -- state external to the function call
function segment.fast_adjust()
  if ion_time_of_flight - offset > 3 then
    adj_elect01 = -10
    if ion_time_of_flight - offset > 10 then
      offset = offset + 10 -- warning! modifies external state
    end
  else
    adj_elect01 = 10
  end
end

The effect of this segment depends on the previous value of offset, which in turn depends on how the segment was previously called. Write it instead like this:

-- good
simion.workbench_program()
function segment.fast_adjust()
  local fraction = ion_time_of_flight % 10
  local Vmax = ion_number * 10
  if fraction < 3 then
    adj_elect01 = Vmax
  else
    adj_elect01 = -Vmax
  end
end

Not only is this second version more correct, but it is also easier to understand. Its behavior in how it sets adj_elect01 depends solely on the current values of ion_time_of_flight and ion_number (even if time reverses in direction or is random).

If you need to write logic that depends on strictly increasing time, put this logic in an other_actions segment instead, and if necessary reset any state prior to flying new particles or starting new reruns. Enable Grouped flying on the Particles tab is you want all particles to fly simultaneously rather than one after the other.

“Failed saving PA file: Access is denied” error on refining or flying in Windows Vista/7

Windows Vista or 7 file permissions by default do not allow standard (non-administrator) users to save or modify files in the c:\Program Files (or c:\Program Files (x86)) folder. If you attempt to refine or fly examples contained in these folders (e.g. under c:\Program Files\SIMION-8.1\examples), you may receive an error such as Failed saving PA file: Access is denied. It is recommended to copy the example folders to some personal location where you have full permissions (e.g. your My Documents folder) prior to running them in SIMION. This approach is recommended over simply granting yourself permissions to the c:\Program Files\SIMION-8.1\examples folder because it preserves a copy of the original versions in case you ever want to go back to them, and it is also more secure on a multi-user system.

Refining PA# arrays, flying with trajectory retaining enabled, or using Data Recording with an output file are a few cases where SIMION may attempt to write files to same directory.

Errors - SIMION 7.0

Fails to install SIMION 7.0 on a 64-bit system

SIMION 7.0 is a 32-bit program, which runs fine on 64-bit Windows. However, the installer for SIMION 7.0 was 16-bit, which 64-bit Windows can’t run. The workaround is to install SIMION 7.0 on a 32-bit system, copy the program folder to your 64-bit system, and then uninstall it from your 32-bit system.

I get the error “Directories Missing: More than a Total of 3000 in Drive” or “Directory File Too Big to Totally Load” error in File Manager or don’t see all directories...

This issue affects version 7.0. It it is fully resolved in version 8.0, which replaces the GUI File Manager with a regular Windows File Open dialog box. This issue is somewhat resolved in version 7.0.2 and later, which improves the GUI File Manager a few ways. We recommend SIMION 7.0.0 users download the free upgrade to the latest 7.0.x version’‘’ to mitigate this problem.

In version 7.0.0, there were three known workarounds, which we no longer generally recommend but still provide here mainly for historical reference. The resolution incorporated into 7.0.3 is effectively similar to Solution #1 below but is simpler and does not do an actual drive mapping.

• Old Solution #1 - Download and save the simion.bat program file. Add this file to your start menu or desktop. Now, always start SIMION by double clicking this simion.bat program rather than the regular SIMION program icon. Notes: If your system does not have an unused “S:” disk drive letter or your SIMION program directory is not “c:7”, then simion.bat should fail. To correct this, you will have to edit the simion.bat file to set these these two variables to values compatible with your particular system configuration. Technical details: simion.bat is merely a wrapper around the standard SIMION program (simion.exe) and creates a “virtual drive” for the SIMION program folder using the DOS command “subst S: c:7”). When SIMION’s GUI file manager then starts up, it will only scan the files in this virtual drive rather than all files on your main hard disk. (tested on Windows NT and XP).
• Old Solution #2: Rename any directory you need to access from SIMION by prepending and underscore (“_”) character to it. For example, you might rename the Sim7 directory to _Sim7. The directory should then be visible, but the error will still display.
• Old Solution #3: Put all your SIMION related files on separate disk drive or partition that has fewer files (if you do have such a drive or partition). Alternately, create a “virtual” drive by creating a Windows network share on your SIMION directory and then assigning that share a drive letter (which is what solution #1 above does). Then access your files in SIMION from that drive letter. This can also be done via “Tools | Map Network Drive” in Windows Explorer.

“Initializing Random Number Generator” is displayed and program freezes with CPU at 100% during SIMION 7.0 startup.

This issue affects SIMION 7.0.0 to 7.0.2. It is fixed in version 7.0.3. We recommend you download and install the latest 7.0.x version of simion.exe, which is a free upgrade from 7.0.0.

This error happens in 7.0.0 if the system is not rebooted for ~24 days or more. If you have updated 7.0.0, a quick fix is to simply reboot your system. Another solution in 7.0.0 has been to disable the reinitialization of SIMION’s random number generator (p. E-15 of the SIMION 7.0 manual).

Viewing

Can I change the coordinate system so that particles move along Z rather than X?

A convention in SIMION is that electrodes with 2D planar or 2D cylindrical (i.e. axially symmetric) symmetry are drawn onto a 2D array mapped to the XY plane, where X is the axis of symmetry in the 2D cylindrical case. Therefore, the general direction of a particle beam though a cylindrical lens would normally be defined as the X axis. 3D arrays don’t have such restrictions, but the initial view for the array still defaults to displaying the XY plane, so the same preference for the X axis is often kept.

You can, however, orient arrays and particles however you want into a workbench, so you are not limited to the above convention. You could, for example, position a 2D cylindrical array into a workbench such that the axis of rotation in the array (x) is aligned to the Z axis in the workbench. This is done via “View > PAs > Positioning > Rotation” (in SIMION 8.0/8.1). Your particle definitions can be defined relative to either the PA coordinates or to these (rotated) workbench coordinates (“View > Particles > Define... > Coordinates relative to”). Likewise, the coordinates displayed on the View screen are normally in these workbench coordinates (“View > Display > Location > mm”), as are Data Recording output and many programming variables (ion_px_mm). You can rotate the view to whichever plane you want via the XY, ZY, XZ, or 3D Iso buttons or by dragging the “globe”. Therefore, if you prefer particle beams to be aligned to the Z axis and analyzed as such, you can do so.

Note also: when using GEM files, some commands have a preference for a certain axis, but you can also surround these commands with a locate statement that does a rotation.

Other

How do I run Lua code in SIMION?

How do I disable relativistic effects?

How do values of adustable variables in the Variables tab interact with those in the program?

In code like this:

adjustable x = 1
x = 2
function segment.initialize()
  x = 4
end
x = 3

The order of execution is as follows:

• The user clicks Fly’m.

• The Lua program is compiled and checked for syntax errors. Any adjustable variables (x) detected in compilation are added to the Variables tab, if they aren’t already, but are otherwise treated as Lua local variables.

• The Lua program is then executed from top to bottom:

  • x is set to 1.
  • x is set to 2.
  • The initialize function segment is created and stored in the segment table.
  • x is set to 3.

• Any adjustments made by the user in Variables tab are now applied. For example, if x is 10 on the Variables tab, x is now set to 10.

• SIMION executes segments functions like initialize. Here, initialize sets x to 4.

Testing the following workbench user program may make things clearer:

simion.workbench_program()
adjustable x = 1
print('A', x)
x = 2
print('B', x)
function segment.initialize()
  print('C', x)
  x = 4
  print('D', x)
end
x = 3
print('E', x)

How can I make markers different colors, like when particles hit electrodes or test planes?

Set the marker color on the View screen Particles tab to 15. The value 15 (transparent) takes special meaning: it tells SIMION to use the same color for the marker as for the particle. Particles in turn can be colored individually via the Define Particles screen. (Note: Prior to SIMION 8.0.7-TEST8, you may need to temporarily enable time markers on the View screen Particles tab to change the marker color.)

Additional Notes

For additional topics, see SIMION Supplemental Documentation.

Is something missing from this FAQ? Questions or requests for clarification are most welcome.