# A Tour of the SIMION Demo¶

By David J. Manura

## Introduction¶

• How do I use the demo version of SIMION?
• Could you provide an overview of using SIMION’s capabilities?

This article is written in the form of a tutorial, providing a quick general idea of what SIMION is about. Detailed explanations and theory are given instead in the print manual (e.g. Chapter 2: SIMION Basics), and SIMION 2020 Supplemental Documentation. More advanced features, such as those added in SIMION® 8.1, are also detailed elsewhere.

## Overview of the Demo¶

For a hands-on introduction to SIMION, you may request the SIMION demo software and follow along in this tutorial. Alternately, you may wish to just read, and you won’t miss too much since ample screenshots are provided.

The demo version behaves much like the full version of SIMION except that important functions are omitted, like creating/refining/saving your own arrays. Therefore, you can view the prebuilt examples but you can’t simulate your own projects (which is likely what you eventually want to do). The demo version also does not come with the full printed manual, which explains much of what you need to know to effectively use SIMION.

## Startup¶

When you start the program (simiondemo.exe), the Welcome screen displays and some introductory notes are also shown separately in a web browser. Click OK to close the Welcome screen.

On startup, the above Main Menu is displayed from which you can reach all SIMION functionality.

The typical steps that one goes through when creating a SIMION simulation are as follows:

• Create one or more potential arrays via the New, Modify and Save functions. In SIMION, a Potential Array is a 2D or 3D matrix of points that defines your electrode geometries and potentials within a volume of space. It is like a bitmap image for potentials (rather than for color intensities).
• Given the potentials on the electrodes in each potential array, use the Refine function (which solves the Laplace Equation) to calculate the potentials on space points in the potential array.
• Optionally, make final adjustments of the potentials on each electrode with the Fast Adjust function. This function can be performed even after Refine, and even during the simulation, due to the Law of Superposition. This saves computation time.
• Use the View/Load Workbench function to create a workspace, place one or more instances of refined potential arrays on workspace, and fly particle trajectories.

In this demo version, the Refine function is removed. All examples distributed with the demo come pre-refined and pre-flown so that you can at least see what the output looks like.

One initial point of guidance is worth stressing. If you have a question on any button or graphical control in SIMION, hover your mouse button over it and/or press F1, which will display a quick tooltip help.

## Einzel example¶

Now, lets look at our first example, the Einzel lens. All the initial steps of creating the potential arrays, refining the arrays, and setting up the workbench have been done for you, so all you need to do is load it up and view it.

To do so, click the View/Load Workbench button to load an existing SIMION Ion Optics Workbench (“IOB”) file. “IOB file?” ask. In SIMION, each project is stored in its own directory and consists of multiple files. The “IOB” file is the project file that links all these other files together.

Select the Einzel workbench file (`examples\einzel\einzel.iob`).

After it loads click the Fly’m button to calculate particle trajectories. The above shows what Einzel lens simulation results looks like after it is loaded and the Fly’m has run. It doesn’t currently look like much, but this is an X-Y cross sectional view of a three-electrode cylindrical lens with ion paths (blue) shown flying axial through it.

To see this better, click the 3D Iso button. This shows a 3D “isometric” view of the system.

To make the above picture look slightly better, the display quality was also increased from 3 to 8 by right-clicking the up arrow five times next to the Qual (Display Quality) field on the right of the screen. (You may need to resize the SIMION window to see this, as shown in the above figure.)

It’s a little small to see. Let’s zoom in. Make a “box selection” around the area to zoom in on by holding the left mouse button on one corner of your zoom area, dragging the mouse to the second corner of your zoom area, and releasing your left mouse button as such:

To now zoom in on this selection box, press your right mouse button.

What we might like to know now is what the potentials are on each of the three rings and between them. To do, so we can press the PE button. This is currently grayed out because you must first select the XY, ZY, or XY orientation. So, let’s press the XY button and then press PE. Below is the result (after again performing the “zoom” procedure mentioned above to make things bigger).

This demonstrates one of the main design goals of SIMION. SIMION aims to develop intuition and promote understanding. This potential energy map shows that the middle electrode has a higher electrostatic potential than the two outer electrodes. The “saddle”-like potential surface indicates why incoming electrons (upper-right) on parallel trajectories are pushed toward a focal point after flying through the lens. The PE view makes electrons appear to behave like balls rolling up and down a hill (a very familiar concept).

But what are the exact potentials on each electrode? To find out, click the PAs tab and then click Fast Adjust Voltages….

The voltages on the three electrodes are displayed and point to their respective electrodes on a cross-sectional view. This screen also allows you to adjust the voltages on these electrodes. For example, as shown above, click in the first box (labeled “1”), and change this value to 50. Then press Fast Adjust to activate this.

Notice that the first electrode in the potential energy map has moved higher as expected. You would typically next press the Fly’m button to instantly re-fly the ions under this new potential energy condition to see how this affect the ion paths. (This button may be grayed-out in some demo versions.)

## More Viewing¶

Another useful feature in SIMION is the ability to see inside a geometry. First, let’s get back to the 3D isomeric view (press the 3D Iso button, and then zoom in on an area):

We might like to see what the ions are doing behind the front surface. SIMION makes it easy to remove a part of the surface for display. First, we need to select parts of the surface to peal-off. Press the ZY button to display a Z-Y cross-sectional view. Then make a box selection as shown around the part you want to keep (lower-right surfaces):

Now press the +Z3D button to zoom in and discard all surfaces outside of this area of the cross-section. To view the result, press the 3D Iso button (and then perform a normal zoom to make things bigger).

We can now easily see the ion flight path within the cylindrical rings.

### Contours¶

Now let’s draw some contour maps of the electrostatic field. First, press the -Z3D to remove the 3D zoom created earlier. Then click the XY button to get back to the normal X-Y cross-sectional view. Also zoom in. This gives us a nice view to draw contours on:

Now open the PE/Contours tab, select the box to the right of “Auto” and enter “10” for 10 contour lines. Then press the Auto button to automatically draw contours.

All points on a contour line have the same potential. You can observe this by hovering your mouse over multiple points, in which case the corresponding X-Y positions, potential, and potential gradient are displayed on the bottom status bar.

Instead of potential contours, you might instead want to display contours on the gradient (derivative-like) of potential. To do so, press Clear (and Yes) and then press the Potentials drop-down and change this to Gradients. Then click on a point on the graphical display area where you want to calculate the contour at and press the Use button (this is on the right of the screen and you may need to expand the SIMION window). Do this multiple times for each contour line you desire. Notice that the highest gradients are near the gaps between electrodes.

## Defining ion flights¶

So how are the initial particle positions and trajectories defined? We saw a series of ions entering the lens at parallel trajectories. How was this defined? To see, click the Particle tab and then click the Define… button. This shows particle trajectory starting conditions:

In this example, there are two groups of ions, only the first of which is displayed above (“Group1”). This first group contains six ions starting at position (x,y,z)=(-99.9990,0,0) and each incremented in series by 1 grid unit in the y direction. All have an azimuth angle and elevation angle of 0 degrees and an initial kinetic energy of 2E+2 eV. This is a fairly straightforward example. (More complex definitions are available via the .FLY2 option.)

Instead of defining ions in groups as above, you can also define each ion individually with the Individually (.ION) radio button. This is useful, for example, if the initial trajectories for many ions do not follow a simple pattern or if the ion trajectories are defined in some external ASCII text file. Click OK to exit out of here.

Another useful feature is Data Recording. When Data Recording is enabled, various statistics are recorded (to the screen or to an external text file) when particles are flying. You’d often use this when you care more than just having pretty pictures but want to know, for example, the exact positions and energies of ions at various points in time. To see this, on the Particles tab, click the Data Recording button.

Just as a few examples, the What Data Elements to Record shows that you can record the kinetic energy, velocities, accelerations, observed fields, and mass/charge of each of your ions during flight. The When to Record These Data Elements allows you to specify when the above stats are recorded. You might want to record these statistics only when an ion is created, an ion dies (“splats” against an electrode), or crosses a certain X, Y, or Z plane. This data is recorded in a format you specify (the “Delimited” format is useful if you wish to export data to Excel). Click the OK button to exit this screen.

### Flying ions as dots¶

Instead of viewing ion trajectories as static lines, you can view then as moving dots. To do so, let’s first get back to the X-Y cross-sectional view by pressing the XY button. Now, open the Particles tab and check the Dots check box. As seen, ions will display moving through the lens. This is example is somewhat boring, but think of what could be shown in an RF ion trap. Uncheck the Dots checkbox to disable this.

### Summary of the “View” Function¶

Let’s summarize everything so far by describing what the main parts of the “View” function do. The Workbench tab defines your overall project, including loading/saving the workbench and changing the bounds of the workbench volume. Another very useful feature on the Workbench tab is the Doc… button which display the documentation for the current workbench project. Click Doc… to see this for the Einzel lens example. The “PAs” tab represent the positioning of the potential arrays (PA’s) in your workbench. PA’s represent your electrodes and fields. This tab is especially useful in more complicated examples consisting of multiple potential arrays that need to be positioned relative to each other (e.g. a source, a magnet, and a detector). (SIMION can also simulate combined electrostatic and magnetic fields, something that this example does not demonstrate.) The PE/Contours tab draws field contours. The Variables tab contains adjustable parameters for the particular example (variables only exist for examples that have user programs, which this example does not have). The Display tab contains viewing options. The Log tab contains output from the Data Recording function described earlier.

## The Modify function¶

We’ve looked fairly extensively at how the View function is used to view the results of a SIMION simulation. The question we now turn to is how to define electrode geometries with the Modify function. This is a large subject in its own right (Chapter 5 and Appendix I of the SIMION 8.0/8.1 printed manual discuss this in detail). Here, however, we’ll look at how the Einzel lens geometry was defined and then look at a slightly more complicated example just to provide the reader a general idea of how electrode geometries are defined in SIMION.

Lets first exist out of the “View” function in the Einzel lens example. Press the Quit button and then press Yes.

We’re now back in the Main Menu. The Einzel example is still loaded, however, and notice that `einzel.pa0` displays the right side of the screen.

`einzel.pa0` is the name of your refined potential array. It contains the potentials of each electrode point and (because it was refined via the Refine function) the potentials of the non-electrode points solved via the Laplace equation. Notice also that einzel.pa0 is selected. To modify the selected potential array, click the Modify button. Ignore the warning about “einzel.pa0 is a base solution file” (just press OK). (Sidenote: If you were really going to modify this geometry, you would heed this warning and instead load the unrefined `einzel.pa#` file so that your changes would be preserved after subsequently refining, but we’ll ignore this point for now.)

Notice that this initially shows a 2-D grid. Black points are electrodes. White points are non-electrodes. By hovering the mouse over an electrode, the voltage on that point will display.

Notice also that `cylindrical` is displayed at top. This indicates that your electrode geometry is generated by rotating the displayed bitmap pattern according to cylindrical symmetry around the x axis. This forms the three-concentric cylinders you saw before in the View function. The example could have instead defined the geometry as a full 3-D array of pixels with no symmetry. However, it can be computationally simpler (and more precise) to take advantage of any symmetry in your system.

The various buttons on the left allow you to draw lines, hyperbolas, boxes, and circles. These shapes can be 3D or 2D. 2D shapes can be rotated to generate 3D volumes of rotation via the RotCpy button.

In case of 3D geometries, you can view various cross-sections using the XY, ZY, and ZY buttons or view a 3D isometric view with the XYZ button. When in a 2D cross-sectional view, you can scroll through each cross-sectional layer by scrolling value in Layer Z= box on the far right of the window.

In particular, the 3D button provides a nice 3D view of the geometry (OpenGL graphics), as shown above, which you can rotate and examine.

## Geometry files¶

As mentioned above, one way to draw geometries is to use the GUI editor features in the Modify function. There are various other ways such as CAD import noted in Geometry Input Methods. Another major way of creating geometries, and the one often used for complex examples due to its great flexibility, is what SIMION calls “geometry files.” Let’s look at one example created from a geometry file:

This potential array consists of three parts. On the left, there is a plate with a hole in the center. In the middle is a dynode consisting of three sides of a box. On the right is a detector. Although hidden in this view, the detector consists of two concentric solid cylinders stacked together. The front cylinder (near the plate and which forms the detective surface) has a cone shape cut out of it. The back cylinder is held at ground potential.

Here is the geometry file that fully generates the above geometry. This geometry file is based on an example distributed with SIMION but modified slightly for clarity.

```; DETECT.GEM -- SIMION Geometry for creating a simple detector
;               with dynode as fast adjust potential array.

; define array sizes
pa_define(101,71,71,planar,non_mirror)

; center in 3d array 10 back in x
locate(10,35,35)
{
; create entrance plane electrode (0V)
e(0)
{
fill{
; create plane
within{centered_box(0,0,2,70)}

; cut hole in entrance plane
notin{locate(,,,,-90){circle(0,0,5)}}
}
}
; create dynode electrode (#1)
e(1)
{
locate(5,-8) ;offset location for dynode
{            ;+5 in x and -8 in y
fill{
; create bottom plate of dynode
within{box3d(0,0,-10,40,1,10)}

; create back plate of dynode
within{box3d(0,0,-10,40,10,-9)}

; create front plate of dynode
within{box3d(0,0,9,40,10,10)}
}
}
}
; create detector electrode (#2)
e(2)
{
locate(20)      ; shift detector aiming location +20 in x
{
locate(,,,,,30) ; elevate 30 degrees (revolve detector)
{
locate(20)      ; shift detector +20 from point of rotation
{
; create front half of detector as a cylinder minus cone
rotate_fill()
{
; create rectangle
within{box(0,0,15,10)}

; cut off one edge
notin{polyline(0,0    12,0  0,8)}
}
; create back half of detector as a cylinder (0V)
e(0)
{
; by rotating a box
rotate_fill()
{
within{box(16,0,35,10)}
}
}
}
}
}
}
}
```

This may look like a lot, but consider: The way geometry files are structured largely reflects the steps one might take to machine the part. How might you machine the above part?

• To create the entrance electrode, first create a plate. Then cut a hole in the plate.
• To create the dynode, obtain three plates and place these together at 90 degree angles.
• To create the detector, create the two halves. The front half if constructed by drawing a rectangle, chopping an edge off of the rectangle to form a trapezoid, and then generating the volume of revolution from that trapezoid. The back half is constructed by generating the volume of revolution of a simple rectangle.

The rest is in the details of the exact positioning and dimensions.

Let’s examine what the main parts of the geometry file mean. Geometry files are organized hierarchically, with sections encloses in pairs of braces { }. (If you’ve ever used a programming language like C, then this is the same concept). Comment lines begin with a semicolon (;) and are ignored. The `e(0)`, `e(1)`, and `e(2)` define the three main electrodes with their electrode number or voltage inside the parenthesis. The stuff inside the braces under each of these respectively defines how each of these electrodes is constructed. Primitives like `box3d`, `box`, and `polyline` actually draw something. These are enclosed within `within` or `notin` statements to respectively either add material within the enclosed volume shape or to subtract (cut) that material. The various `locate` statements define positional frames of reference (angles and positions relative to where you add or cut out material) and can be stacked on top of each other.

Now that you’ve taken a tour through SIMION, you may want to check out some additional examples. Additional pre-run examples are bundled with the SIMION demo under various subdirectories of SIMION.

To explore an example, the basic steps are

• Select Remove All Arrays from RAM to remove any current example from memory.
• Click View/Load Workbench to load the workbench (IOB) file of one of the examples.
• Select one of the IOB files in the example directories (e.g. “buncher”, “drag”, “magnet”, …) or a README file.
• On the Workbench tab, click the Doc… button for documentation (README) on using this example.
• Explore!

If you prefer not to use the fully hands-on approach, screenshots and descriptions of a number of the demos that comes with SIMION are given in Examples.

## User Programming¶

Before we go, one powerful feature of SIMION that deserves mentioning is user programs. User programs allow you to add custom logic to the SIMION simulation. For example, you can oscillate the voltages on electrodes (as in a quadrupole or ion trap), apply viscosity effects to ions (as in the “DRAG” example), respond to events, perform custom calculations, initialize ion trajectories according to custom logic, automate multiple runs and generate a spectrum, or completely change SIMION’s equations of motion. Quite a few SIMION examples utilize user programs to do unique things. On the View screen, open the Particles tab and click User Program… to view (or create) a user program.

Most of the following additional examples can be tested in the demo version of SIMION.

• Buncher: An example of having a user program to model an ion buncher. The problem is to slow a packet of ions so that they converge in time. The trick is to have them decelerate in a linear field and then (when they are in the middle of it) chop the field to zero. Thus the leading ions will be going slower than the trailing ions and they will bunch together at some point down stream.
• Drag: These files provide a simple example of applying Stokes’ law viscosity to ion motions via an acceleration adjust user program. A simple three element fast adjust lens is provided for demonstration.
• Magnet: These files provide examples of modeling magnetic effects: mag90.iob demonstrates z focusing effects of offset beam entry. magnet1.iob demonstrates combined electrostatic and magnetic focusing effects on ions of opposite charge.
• Trap: These files provide an example of having user programs model an RF ion trap. There are three demos - each with its own user program file and fly files. See screenshots.
• group–demonstrates motions of groups of ions in the trap - ions form patterns and shells due to charge repulsion and gas cooling (simulated by Stoke’s law)
• inject–demonstrates injection of ions external to the trap and the effects of collision gas (simulated by mean free path collisional cooling)
• tickle–demonstrates ejection of ions using resonant end cap voltage techniques. Includes the effects of collision gas (simulated by mean free path collisional cooling)
• Tune: These files provide an example of having user programs tune a lens. It serves as a moderately complex control problem and should be studied for tricks of the trade. See screenshots.
• Icrcell: These files provide an relatively complete example of having user programs model an ICR Cell. This demo creates 20 random ions to the left of the icr cell. These ions enter the cell and are decelerated by a buncher type field. When they are around the middle of the trap the RF sweep starts (ions turn red). After The rf sweep finished the ions turn green and the end caps are set to trap the ions. The PE Surface Views of the Z =0 plane can be used to view the various voltage forcing functions (PE surfaces are updated). See screenshots.

Additional examples are listed in the `examples\README.html` file included in the demo. Many more examples are included in the full version, and the examples are further expanded in SIMION® 8.1.