TIMSSim

Simulates the trajectories of charged particles in a Trapped Ion Mobility Spectrometry (TIMS) Device, including background gas interaction, ion chemistry and space charge. A TIMS device consists of a set of electrodes forming three regions: the entrance funnel, the TIMS tunnel and the exit funnel. Ions are trapped by an electric field which counteract the drag force of a flow of gas. The magnitude of the axial electric field is progressively decreased, allowing for ions to be diluted from the device.

The electrode geometry and potentials are defined through SIMION potential arrays.

There are four different electric potentials which can be applied to the electrodes:

  • DC: Static voltages which are not changing throughout the whole simulation

  • RF: High frequency RF field (sine) for radial ion confinement

  • Scan ramp: Potential which is linearly ramped to a final value, for mobility scan

  • Gate: Potential to gate ions into TIMS region, gate voltage is switched on after a delay time and is held for a gate open time

Those electric potentials are configured in a separate CSV file for every individual potential array. See Potential Array and Voltages Configuration for details.

Ions start uniformly distributed in a configurable start zone. The interaction between background gas and the ions can be described with different collision models. Electric ion-ion interaction (space charge) can be modeled with a parallelized version of a Barnes-Hut tree.

The modeled ions are chemically reactive. The temperature dependent reactions of the individual chemical species are simulated with RS. The reactions are defined in an RS configuration file. To simulate chemically inert ions, an RS configuration without reactions between the species has to be defined.

Simulation configuration description

General Parameters

sim_time_stepsinteger

Number of simulation time steps

dt_sfloat

Time step length in seconds

concentrations_write_intervalinteger

Interval, in time steps, between the writes of the species concentration .

trajectory_write_intervalinteger

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

trajectory_write_velocitiesboolean

if true: Particle velocities are written to the auxiliary data in the trajectory result file.

space_charge_factorfloat

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

reaction_configurationfile path

Path to a RS configuration file, defining the chemical reaction system for the simulation. This file path is interpreted relatively to the simulation run configuration file.

n_particlesvector of integers

Number of particles of the discrete chemical substances defined in the reaction configuration. The order in this vector is the same as the order of discrete substances defined in the reaction configuration.

Example: If the [SUBSTANCES] block in the reaction configuration is

[SUBSTANCES]
Cl_1 discrete 19 1 3.57e-4  4.00000000e-10
Cl_2 discrete 37 1 2.76e-4  5.17391304e-10
Cl_3 discrete 55 1 2.35e-4  6.07659574e-10

the n_ions vector [100, 50, 10] will initalize the simulation with 100 particles of Cl_1, 50 of Cl_2 and 10 of Cl_3.

start_box_dimensions_mmVector of floats

x-, y-, and z-dimensions (in mm) of the ion start zone.

start_box_position_mmVector of floats

x-, y-, and z-coordinates (in mm) of the corner of the ion start zone.

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]]

Potential Array and Voltages Configuration

The electrode geometry and electric field shape of the TIMS analyzer are defined through SIMION potential arrays. The potential arrays and actual voltages applied to the individual electrodes are defined in a separate CSV file (given in potential_configuration).

This file has the following form:

# potential name; static DC potential; RF factor; ramp gradient factor; gate factor
tims_geometry.pa1;  0;    1; 0.1; 0
tims_geometry.pa2; -2.5; -1; 0.2; 0
tims_geometry.pa3; -5.0;  1; 0.1; 0
tims_geometry.pa4; -7.5; -1; 0.2; 0

The individual columns are:

  • potential name: Name / Paths of the potential array (PA) file. The file paths are relative to the simulation run configuration file.

  • static DC potential \(U_{\text{dc}}\): Static (DC), absolute potential for this PA

  • RF factor \(f_{\text{RF}}\): RF amplitude for this PA, given as factor relative to the absolute RF amplitude defined in confining_RF_amplitude_V

  • ramp gradient factor \(f_{\text{Ramp}}\): Amplitude of the linear scan ramp for this PA, given as factor relative to the absolute scan ramp amplitude defined by gradient_voltage_V and gradient_ramp_velocity_V/ms

  • gate factor \(f_{\text{Gate}}\): Amplitude of the gate voltage for this PA, given as factor relative to the absolute gate voltage defined by gate_voltage_V

Typically, SIMION potential arrays generated with the fast adjust option are used for the electrode definitions. 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 total voltage for a PA, \(U_{\text{PA}}\), is calculated by:

\[U_{\text{PA}} = U_{\text{dc}} + f_{\text{RF}} \, U_{RF}(t) + f_{\text{Ramp}} \, U_{Ramp}(t)+ f_{\text{Gate}} \, U_{Gate}(t)\]

with the time dependent RF, ramp and gate voltages \(U_{RF}(t)\), \(U_{Ramp}(t)\), \(U_{Gate}(t)\).

potential_array_scalefloat

Geometric scaling factor for the potential arrays specified in potential_arrays.

potential_configurationfile path

Path to the potential definition CSV file

RF Field Configuration

confining_RF_amplitude_Vfloat

Peak-to-peak amplitude (in V) of the confining voltage meant to reduce radial ion drift.

confining_RF_frequency_Hzfloat

Frequency (in Hz) of the confining voltage.

Scan Ramp / Gradient Configuration

The scan ramp / gradient is a linear potential ramp, which starts after a delay time and increases with a fixed rate to the end value.

gradient_start_time_sfloat

Delay time until the scan gradient starts (in seconds)

gradient_ramp_velocity_V/msfloat

Slope of the scan gradient / scan ramp (in volts per milliseconds)

gradient_voltage_Vfloat

End voltage of the scan gradient ramp (volt)

Gate Configuration

The gate voltage is applied after a delay time and is kept for a gate open duration time

gate_open_time_sfloat

Delay time until the gate is opened (in seconds)

gate_open_duration_sfloat

Opening time of the gate (in seconds)

gate_voltage_Vfloat

Voltage applied in the “gate open” state (volt)

Collision models and background gas interaction

The simulation has different modes to model the interactions between ions and the background gas which are suitable for different background gas pressure ranges. The model can use external flow fields (mostly from fluid dynamic simulations) or simple uniform or parabolic flow profiles can be assumed. The external flow fields are imported from flow data in SIMION potential array (PA) files. Such files can be generated from CFD solver data with conversion scripts (e.g. comsol_to_pa.lua) provided by the SIMION distribution.

Note

It is planned to integrate other file formats for CFD solution import.

The collision model mode is controlled by the collision_model parameter:

collision_modelkeyword [SDS, HS, MD, none]

Sets the used collision / background gas interaction model:

  • SDS: Statistical Diffusion Simulation model

  • HS: Hard Sphere model

  • MD: Molecular Dynamics model

  • none: No background gas interaction (mostly for testing purposes)

collision_gas_mass_amufloat

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

collision_gas_diameter_nmfloat

Effective collision diameter of the particles of the background gas in nm.

flow_mode: keyword [uniform, parabolic]

Sets the background gas flow mode:

  • uniform: Uniform flow velocity in x direction (default value)

  • parabolic: Parabolic flow velocity profile in x direction

  • static_field: External, static, flow profile (mostly from CFD solution)

The parameter is optional, if it is omitted, uniform flow profile is assumed.

Uniform / parabolic background gas flow profiles

Uniform or simple parabolic flow profiles are defined by the following parameters:

background_pressure_Pafloat

Isotropic pressure of the neutral background gas in Pascal.

background_temperature_K: float

Background gas temperature in Kelvin.

background_velocity_x_ms-1float

Background gas velocity in x direction (meter per second). For uniform flow this is the uniform background gas velocity in x direction. For parabolic flow, this is the average flow velocity. The maximum flow velocity in the center of the parabolic flow profile is a factor of two higher (2 * background_velocity_x_ms-1).

flow_profile_maximum_radius_mfloat

For parabolic flow profile only: With of the parabolic flow profile in y-z direction (in meter).

External flow profiles (CFD solutions)

Imported flow fields can be full 3d or 2d axialsymmetric. In the 2d axial symmetric case, the x axis is the symmetry axis and the flow PAs have to have the correct symmetry.

flow_field: Vector of file paths

Flow velocity component fields. For 3d case: x, y and z components in three separated potential array files. For a 2d axial symmetric case x and r (the radial flow component) as two separatd potential array files.

The PAs are assumed to be in meter per second (m/s).

pressure_field: Vector of file paths

Pressure field in Pascal (Pa).

temperature_field: Vector of file paths

Temperature field in Kelvin (K).

Note

The pressure and temperature fields have to be provided in a vector (within square brackets) even if they are single PA files.