Cookbook of SIMION User Programming Examples

This is a collection of common SIMION user programming techniques. See also Lua Cookbook.

• Lua Variables - Lua variables and visibily of variables

• Particle Trajectory Calculations - many programming examples dealing with particle trajectories and data recording.

• Lua Cookbook - I/O and time functions in standard Lua

• Programming API for SIMION - full API documentation

Additional Examples

Periodically update potential energy display

This code causes the potential energy (PE) view to update every update_pe_period microseconds. This is useful in conjunction with a fast_adjust segment that changes electrode potentials during the fly’m.

SIMION 8.0 example (Lua):

simion.workbench_program()
local pe_update_period_usec = 0.010  -- microseconds
local last_pe_update = 0
function segment.other_actions()
  if abs(ion_time_of_flight - last_pe_update) >= pe_update_period_usec then
    last_pe_update = ion_time_of_flight
    sim_update_pe_surface = 1  -- require PE update
  end
end

SIMION 7.0 example (not exactly equivalent):

; PRG example
DEFA update_pe_period 0.010  ; microseconds
DEFS next_pe_update_time 0

SEG other_actions
  ; if ion_time_of_flight >= next_pe_update_time
  RCL ion_time_of_flight RCL next_pe_update_time X>Y GTO skip1
    ; next_pe_update_time = ion_time_of_flight + update_pe_period
    RCL ion_time_of_flight RCL update_pe_period + STO next_pe_update_time
    ; update_pe_surface = 1
    1 STO update_pe_surface
  LBL skip1

# SL example
adjustable update_pe_period = 0.010  # microseconds
static next_pe_update_time = 0

sub other_actions
  if ion_time_of_flight >= next_pe_update_time
    next_pe_update_time = ion_time_of_flight + update_pe_period
    update_pe_surface = 1
  endif
endsub

Print Electrode Values

function segment.init_p_values()
  local pa = simion.wb.instances[ion_instance].pa
  print(pa)
  for _,electrode_number in ipairs(pa.electrode_numbers) do
    print('POTENTIAL', ion_instance, adj_elect[electrode_number])
  end
end

efield_adjust

Q: Within ``segment.efield_adjust``, both the potential (``ion_volts``) and potential gradient (``ion_dvoltsx_mm``, i.e. negative E field) are available to change. Should both always be updated? What happens if only the gradient is changed?

True, ion_volts is not used for the particle trajectory calculation. You can omit it. Someone might want to set it though if they are, for example, recording voltage in Data Recording and want to ensure the voltages are recorded are correctly.

Suppress fringe fields or compare to ideal field

Q: I am trying to understand how much fringe fields are affecting my beam. Is there a way to turn it off just to compare?

One way this is sometimes done is with an efield_adjust segment in a user program. The efield_adjust segment can override the field within the simulation (or some region within the simulation) with a user defined equation.

An efield_adjust segment like that is included (but commented out) in SIMION Example: quad to allow one to compare results of the real quadrupole field with an idealized quadrupole field. That may be more complex than what you need. Your code might be as simple as this:

simion.workbench_program()
function segment.efield_adjust()
  if ion_px_mm < 50 and ion_px_mm < 100 then
    -- define grad V = - E
    ion_dvoltsx_gu = 200
    ion_dvoltsy_gu = 0
    ion_dvoltsz_gu = 0
  end
end

(Click User Program on the Particles table, paste that into the text file, and Save the text file.)

That applies a uniform E field (-200 V/mm) in the X direction with a certain X range in mm.