The SIMION .FLY2 Particle Definition File Description

WARNING: The following describes an older (beta) version of FLY2. FLY2 is currently supported in SIMION 8. Refer to the SIMION 8 manual for the latest FLY2 specification.

Overview

Figure: Randomized ions generated from a FLY2 file.

The FLY2 format is the proposed successor to the FLY format of SIMION 7.0. Like the FLY format, FLY2 format makes it easy to specify initial ion parameters for a large number of ions without defining each ion individually (as in the SIMION ION format).

The original FLY format has significant limitations though. In a FLY file, ion parameters are defined as an arithmetic sequence (using deltas). This makes it easy to set up a linear sequence of particles but does not facilitate setting up more complex beam shapes such as a cylindrical/conical beam or a beam with randomized (e.g. Gaussian) parameters. The FLY format is also a binary format that is not simple to generate from external programs (e.g. Excel). In such cases, SIMION users have instead used ION files or user programs (e.g. PRG), which are entirely flexible but not as simple and convenient as FLY files.

The FLY2 format overcomes all of the above points, and it provides a far greater degree of flexibility. A FLY2 file is text file that is analogous to and resembles a SIMION GEM file. Many common types of beam parameters can be expressed by combining a small set of primitives. The FLY2 format is actually even more flexible than the GEM format since you can use variables and extend it with custom code (a level of flexibility often not needed but good to have available).

FLY2 is largely implemented already, but the interface could still change as the syntax is finalized. There is a utility to convert a FLY2 file to a standard SIMION ION file for use in SIMION 6 or above--you can try it online. The FLY2 format is proposed for inclusion in a future version of SIMION and may more immediately be included in the SIMION SL Toolkit. A future version of SIMION could provide a basic graphical user interface for reading/writing FLY2 files (similar to "define ions by groups" for FLY files in SIMION 7.0).

Basic Syntax

A .FLY2 file is an ASCII text file with the file name extension .FLY2 (e.g. "myions.fly2") and having a certain syntax for defining initial parameters for any number of particles. Here is a simple example:

-- Create single ion (very simple example)
standard_beam_define {
  tob    = 0,    -- time of birth, usec
  mass   = 100,  -- mass, amu
  charge = 1,    -- charge, e
  x      = 0,    -- position, gu or mm
  y      = 0,
  z      = 0,
  ke     = 0.1,  -- kinetic energy, eV
  az     = 0,    -- azimuth angle, deg
  el     = 0,    -- elevation angle, deg
  cwf    = 1,    -- charge weighting factor, unitless
  color  = 0     -- color index
}

Logically, the FLY2 file consists of any number of particle beam definitions (standard_beam_define), which defines a set (group) of related particles. Parameters for the particle beam are given within the curly braces "{}" and are separated by commas. There are a few basic things you should know: whitespace is ignored, names are case sensitive, comments start with "--", and the order of parameters usually does not matter. The precise syntax follows the Lua programming language, and in fact a FLY2 file is a Lua program, but you don't need to know anything about programming in Lua to create a FLY2 file. You can find most of what you need to know by looking at the examples given here.

Beam parameters have default values that can be omitted, and you can define multiple beams in the FLY2 file:

-- Create an ion using all default values (same as above)
standard_beam_define {
}
-- Create two more ions
standard_beam_define {
  mass = 100, charge = 1, x = 0, y = 0, z = 0, ke = 0.1
}
standard_beam_define {
  mass = 35, charge = -1, x = 1, y = 0, z = 0, ke = 0.1
}

There are alternate ways to express certain parameters such as position and direction. Use whichever method is convenient:

-- These two beams are identical
standard_beam_define {
  az = 0, el = 90,          -- polar angles
  x = 3, y = 5, z = 7       -- individual coordinates
}
standard_beam_define {
  direction = {0, 1, 0},    -- directional vector along +y
  position = {3, 5, 7}      -- position vector
}

Sequences and Distributions

The following two sections address defining more than one particle per beam, where the particles follow some identified pattern. Large numbers of particles can be defined easily in this way.

Sequences

Instead of assigning a simple number to a beam parameter (e.g. z), you can assign it a sequence of numbers:

--Create five ions with z=1..5.
standard_beam_define {
  mass = 100,
  x = 10,
  y = 20,
  z = linear_sequence {first = 1, last = 5, step = 1}
}

A sequence is an ordered list of values. In the above example, the "linear_sequence" expression defines a certain sequence of five numbers: the integers 1 to 5. A particle is created for each value in the sequence, so five particles are created having the z values 1 through 5 and having all other parameters the same.

A linear_sequence (often called an arithmetic sequence) is one of the simplest types of sequences. The difference between successive values is always some constant step (delta). Linear sequences can be expressed in various ways:

-- All three sequences below are identical to 3, 2.5, 2, 1.5, 1.
linear_sequence {first = 3, last = 1, step = -0.5}
linear_sequence {first = 3, last = 1, n = 5}
linear_sequence {first = 3, step = -0.5, n = 5}

If more than one parameter is given a sequence, then a particle is generated for each combination:

-- Create 25 ions with y=1..5 and z=1..5, forming a square beam.
standard_beam_define {
  mass = 100, x = 0,
  y = linear_sequence {first = 1, last = 5},
  z = linear_sequence {first = 1, last = 5}
}

In the above case, there are actually five times five (i.e. 25) ions, with initial positions (y,z) = (1,1), (2,1), ..., (5,1), (1,2), ..., (5,2), ..., (5,5). Note that this behavior is much different and more interesting than in a regular FLY file, where the above type of thing would generate only five ions with the initial positions (y,z) = (1,1), (2,2), ..., (5,5).

Sequences need not only contain numbers. The "position" and "direction" parameters expect a 3D vector, so you can assign then a sequence of 3D vectors. Here, the "position" attribute is assigned a sequence of 3D points equidistant along a line segment:

-- Create 10 ions along a 3D line segment.
standard_beam_define {
  position = linear3d_sequence {
    first = {1, 3, 5},
    last  = {10,-6, 7},  -- or specify "step = {1,-1,2/9}"
    n     = 10
  }
}

The following positions ions equidistant around the circumference of a circle (useful for the envelope of a cylindrical beam):

-- Create 10 ions equidistant around circle circumference
standard_beam_define {
  position = circle_sequence {
    center_position = {3, 5, 7}, axis_direction = {0, 1, 0}, radius = 3,
    n = 10
  }
}

The particle directions can be sequenced as well. This following directs ions around the edge of a cone (useful for the envelope of a conical beam):

--Create 10 particles directed around cone edge
standard_beam_define {
  direction = cone_edge_sequence {
    axis_direction = {1, 0, 0},
    vertex_angle = 45,
    n = 10
  }
}

You can also concatenate multiple sequences into a single sequence:

-- Create 20 particles from two sequences
standard_beam_define {
  position = combined_sequence {
    linear3d_sequence {
      first = {1, 3, 5}, last = {10, -6, 41}, n = 10
    },
    linear3d_sequence {
      first = {10, -6, 41}, last = {19, -6, 41}, n = 10
    }
  }
}

Distributions

Besides sequences, you can also generate random distributions of ions. These are random variables generated from a probability distribution (e.g. normal Gaussian distribution).

-- Create 10 particles with x, y, and z normally distributed.
standard_beam_define {
  n = 500,
  x = gaussian_distribution {mean = 0,  stdev = 3},
  y = gaussian_distribution {mean = 10, stdev = 1},
  z = gaussian_distribution {mean = 10, stdev = 1}
}

Unlike sequences, which have a certain number of elements, you need to specify the number of randomized particles to generate (n).

If you mix sequences and distributions, the default number of particles is determined by the sequences. You may still explicitly provide a "n" different than the default, in which case the sequence will be cut-off or repeated.

-- Create 10 particles with x=1..10 and y and z normally distributed.
standard_beam_define {
  x = linear_sequence {first=1, last=10},
  y = gaussian_distribution {mean = 10, stdev = 5},
  z = gaussian_distribution {mean = 10, stdev = 5}
}

The below example defines particle directions randomly within a cone. This is similar to SIMION 7.0's _Random example (RANDOM.PRG/SL). (One slight difference is that FLY2 takes special care to ensure that the direction vectors are uniformly distributed within the cone.) Use "cone_edge_distribution" instead if you only want the envelope (similar to "cone_edge_sequence").

-- Create randomized conical beam.  Velocity vectors are
-- uniformly randomly distributed within the cone
standard_beam_define {
  n = 100,
  position = {0, 0, 0},
  direction = cone_distribution {
    axis_direction = {1, 0, 0},
    vertex_angle = 20
  }
}

Below, we create a beam starting at uniformly random points on a disc. Use "circle_distribution" instead if you only want random points only on the circumference of the disk (similar to "circle_sequence").

-- Create particles at random points on disc
standard_beam_define {
  n = 300,
  direction = {0, 0, 1},
  position = disc_distribution {
    center_position = {0, 0, 5},
    axis_direction  = {0, 0, 1},
    radius = 10
  }
}

Distributions can be combined (probability weighted) as well (similar to combined_sequence for sequences):

--Merge two distributions with weights 0.3 and 0.7
standard_beam_define {
  x = combined_distribution {
    0.3, gaussian_distribution {mean = -2, stdev = 1},
    0.7, gaussian_distribution {mean =  2, stdev = 1}
  }
}

Pupils

Another way to define a beam is by two apertures (a source aperture and pupil aperture). For each point on the source aperture and each point on the pupil aperture, a ray originates at the source point and is directed toward the pupil point.

In the following example, the apertures are defined via distributions (usually the disc):

-- Create randomized circular beam with window and pupil.
standard_beam_define {
  n = 100,
  position = disc_distribution {
    center_position = {0, 0, 0},
    axis_direction = {0, 1, 0},
    radius = 2
  },
  pupil_position = disc_distribution {
    center_position = {0, 10, 0},
    axis_direction = {0, 1, 0},
    radius = 1
  }
}

The next example defines the apertures using sequences. At each source point, an ion is directed toward each pupil point (giving 4 * 4 = 16 ions total).

-- Generates 16 ions.
standard_beam_define {
  position = linear3d_sequence {
    first = {0, 1, 0},
    last  = {0, 4, 0},
    n = 4
  },
  pupil_position = linear3d_sequence {
    first = {5, 1, 0},
    last  = {5, 4, 0},
    n = 4
  }
}

Additional Examples

Here's a more complex example combining multiple effects.

-- Complex example combining multiple effects.
standard_beam_define {
  n = 100,
  mass = 100,
  charge = linear_sequence {first = 95, last = 105},
  x = gaussian_distribution {mean = 10, stdev = 1},
  y = gaussian_distribution {mean = 10, stdev = 1},
  z = gaussian_distribution {mean = 10, stdev = 1},
  ke = uniform_distribution {min = 5, max = 10},
  direction = cone_distribution {
    axis_direction = {1, 1, 1},
    vertex_angle = 20
  }
}

The next example generates ions with random positions and completely and uniformly random directions (using a cone with 180 degrees vertex angle).

-- Particles in random position, direction, and energies.
standard_beam_define {
  n = 500,
  x = gaussian_distribution {mean = 0, stdev = 1},
  y = gaussian_distribution {mean = 0, stdev = 1},
  z = gaussian_distribution {mean = 0, stdev = 1},
  ke = gaussian_distribution {mean = 10, stdev = 5},
  direction = cone_distribution {
    axis_direction = {1, 1, 1},
    vertex_angle = 180
  }
}

Reference

The section may be used as a reference for the various primitives in the FLY2 file.

[TO DO - This reference section could be more detailed. For now, refer to the examples given above.]