generalTrapSim

Ion trajectory simulation in an RF ion trap device with arbitrary geometry considering space charge and hard sphere collisions with neutral background gas particles. The electrode geometry is defined by SIMION potential arrays.

FT detection

There are different detection modes in ion traps. Commonly, ions are ejected mass selectively from the trap, e.g. by resonant excitation, and detected by a particle detector.

Alternatively, the trapped ions can be excited with an excitation signal on the cap electrodes, which induces an oscillation of the ions in the trap. This oscillation can be detected by the induced mirror charge on detection electrodes. A mass spectrum can be calculated from the recorded mirror charge signal (“transient”) by a Fourier transformation.

The simulation app supports the simulation of this FT detection mode.

Simulation configuration description

integrator_modeKeyword:[verlet, parallel_verlet, full_sum_verlet, RK4, full_sum_RK4], optional: [FMM3D_verlet, ExaFMM_verlet]

Selects the trajectory integrator

verlet: Serial (non parallelized) Velocity Verlet integrator with Barnes Hut Tree for space charge calculation
parallel_verlet: Parallelized Velocity Verlet integrator with Barnes Hut Tree for space charge calculation
full_sum_verlet: Parallelized Velocity Verlet integrator with full sum between all particles for space charge calculation
RK4: Parallelized Runge-Kutta 4 integrator with Barnes Hut Tree for space charge calculation
full_sum_RK4: Parallelized Runge-Kutta 4 integrator full sum between all particles for space charge calculation

With activated FMM libraries (Exa-FMM and or FMM3D) two FMM integrators are also available:

FMM3D_verlet: Velocity Verlet with Fast Multipole space charge calculation with FMM3D library

ExaFMM_verlet: Velocity Verlet with Fast Multipole space charge calculation with Exa-FMM library

sim_time_stepsinteger

Number of simulation time steps

trajectory_write_intervalinteger

Interval, in time steps, between writes to the trajectory result file.

dtfloat

Time step length in seconds

space_charge_factorfloat

Multiplication factor for particle-particle interaction (space charge).

background_gas_pressure_Pafloat

Pressure of the neutral background as in Pa.

background_gas_temperature_Kfloat

Temperature of the background gas in K.

collision_gas_mass_amufloat

Molecular mass of the particles of the background gas in amu.

collision_gas_diameter_angstromfloat

Effective collision diameter of the particles of the background gas in angström.

simulation_domain_boundariesvector of vector of floats

Defines the outer boundaries of the simulation domain around the coordinate system origin, where ions are terminated. Is defined as vector of three two component vectors, defining the minimum and maximum in the spatial dimensions:

[[x low, x high], [y low, y high], [z low, z high]]

Ion / simulated particle configuration

The particles to simulate can be defined in the simulation configuration file or a predefined particle ensemble can be used which is given as ion cloud file in CSV format.

Ion Cloud File

A predefined ion configuration can be specified by

ion_cloud_init_filefile path: Path to an ion cloud initialization / definition file

Ion definition in simulation configuration file

If no ion cloud file is used, the following configuration parameters define the ion ensemble to simulate:

n_ionsVector of integers: Number of ions of the ionic species defined by the the masses defined in ion_masses.
ion_massesVector of float: Ion masses in amu.
ion_chargesVector of float: Ion charges in elementary charges.
ion_collision_gas_diameters_angstromVector of float: Effective hard sphere collision diameters of the ionic species in angström.
ion_time_of_birth_range_sfloat: Time range in which ions are generated, in seconds. The specified number of ions are generated uniformly in this time range.
ion_direction_vectorVector of three floats: Initial direction of motion of the ions. This vector is only a direction vector, the initial velocity of the defined ions is set by ion_kinetic_energy_eV.
ion_kinetic_energy_eVfloat: Start energy of the ions in electronvolts, the initial ion velocity is in the direction of ion_direction_vector.

Ion start configuration

The initial positions of the simulated ions can be a cubic box with faces parallel to the spatial axes or a rotatable and translatable cylinder. The position of the ion start zone is defined by ion_start_base_position_m. This partameter defines the center of a box start zone or the position of the center of the bottom face of a cylinder start zone.

ion_start_geometryKeyword:[box, cylinder]

Sets the ion start geometry.

boxIon start zone is a box

The ion start zone is a cubic box with faces parallel to the spatial axes, randomly filled with particles. It is defined by

ion_start_box_size_m: Vector of three floats: Size of the box in x, y, z direction
ion_start_base_position_m: Vector of three floats: Position of the box center

cylinderIon start zone is a cylinder

The ion start zone is a rotatable and translatable cylinder. The cylinder is defined by

ion_start_radius_m: float: Radius of the cylinder in m.
ion_start_length_mfloat: Distance from bottom face of the cylinder to the top face of the cylinder (cylinder length).
ion_start_cylinder_normal_vector: Vector of three floats: Normal vector of the bottom face of the cylinder, defining the rotation of the cylinder. The normal vector is also the directon of the axis of rotational symmetry of the cylinder (e.g. [1,0,0] means the cylinder axis is parallel to the x-axis).
ion_start_base_position_m: Vector of three floats: Position of the center of the bottom face of the cylinder

Potential Array Configuration / Trap Field Configuration

frequency_rffloat: Frequency of the RF trapping field in Hz.

Trap field RF voltage

The RF trap field voltage (ground to peak) can be static or can be ramped during the simulation.

A static trap field voltage is set by V_rf:

V_rffloat: Static ground to peak trap field amplitude in volt.

If V_rf_start and V_rf_end are set, the trap field voltage is ramped linearly during the simulation from V_rf_start to V_rf_end:

V_rf_startfloat: Ground to peak trap field amplitude in volt at the begin of the trap field voltage ramp.
V_rf_endfloat: Ground to peak trap field amplitude in volt at the end of the trap field voltage ramp.

Potential Arrays and DC / RF Potentials

potential_arraysVector of file paths

Paths to the SIMION potential array files defining the electric potentials and electrode geometry in the trap. Typically, SIMION potential arrays generated with the fast adjust option are used for potential definition.

The potential arrays have to have the same geometric extend and are assumed to be normalized. The total potential at a location is calculated by a linear combination of the individual potentials.

The file paths are relative to the simulation run configuration file.

potential_array_scalefloat

Geometric scaling factor for the potential arrays specified in potential_arrays.

dc_potentialsVector of float

Invariant (DC) potentials on the electrodes defined by the potential arrays in potential_arrays in V.

rf_potential_factorsVector of float

Factors defining the applied RF amplitude on the electrodes defined by the potential arrays in potential_arrays.

The applied voltage on the individual electrode is

\[U = U_{\text{DC}} + \cos(\omega \cdot t) \cdot V_{\text{RF}} \cdot F_{\text{RF}}\]

with

\(t\) the current time in the simulation
\(V_{\text{RF}}\) given by V_rf (or the current \(V_{\text{RF}}\) in the ramp between V_rf_start and V_rf_end)
the angular frequency \(\omega\), given by \(2\pi\cdot\) frequency_rf
\(F_{\text{RF}}\) given by rf_potential_factors.

Excitation Field Configuration

A ion excitation field can be applied on selected electrodes. There are two modes of ion excitation:

Pulsed excitation with a rectangular excitation pulse of defined length and amplitude applied at the begin of the simulation run.
Excitation with a given sampled waveform read from a waveform file.

excite_potential_factorsVector of floats

Excitation field factors for the individual electrodes, specified by the potential arrays in potential_arrays. The excitation potential is multiplied with these factors to get the excitation field applied to the individual electrodes.

excite_waveform_csv_fileFile path

File path to a file with a sampled excitation waveform. If this parameter is present, the excitation mode is “sampled waveform”.

The waveform file contains one sample per time step and is not looped, it is replayed only once at the begin of the simulation run. The sampled waveform is assumed to be normalized, the waveform data is multiplied with “excite_pulse_potential” to calculate the applied excitation potential.

This file path is relative to the simulation run configuration file.

excite_pulse_potentialfloat

When in excitation pulse mode (excite_waveform_csv_file not present in simulation run configuration): Amplitude of rectangular excitation pulse in volt.

When in sampled waveform excitation mode: Multiplication factor for sampled waveform data specified by excite_waveform_csv_file in volt.

excite_pulse_lengthfloat: Length of the rectangular excitation pulse in pulsed excitation mode in seconds.

FT detection configuration

The FFT result records the total induced mirror current of the simulated ion ensemble on a set of detection electrodes, specified by detection_potential_factors.

fft_write_intervalinteger

Interval, in time steps, between samples for the FFT result file, which records a simulated transient for Fourier transformation.

fft_write_modeKeyword:[unresolved, mass_resolved]

Selects the mode in which the FFT result file is written.

unresolved: The FFT transient signal is calculated from the whole simulated particle ensemble. This is the signal which would be detectable in a physical experiment.
mass_resolved: Currently not implemented

detection_potential_factorsVector of float

Mirror charge detection factors. The induced mirror current on the electrodes which are described by the potential arrays in potential_arrays, is multiplied by this factor to get the contribution to the total induced mirror current.