Importing and Exporting Field and Potential Array Data

This page outlines ways to export (i.e. output or read) potential and field data from SIMION, as well as import (i.e. input or write) back such data into SIMION. You may need this for analyzing or building a field entirely within SIMION or for converting a field to or from a format used by another program.

Exporting Data

There are a number of ways to export field and PA data:

  • View screen: The View screen also has built-in visualization capabilities, including contours and PE surfaces. Hovering your mouse over a point on the View screen will display field data in the status bar. Also see SIMION Example: contour (greatly improved in 8.1) for even more flexible programmatic plotting of fields on the View screen.

  • Modify screen: If you need to access only a few specific points, you may manually read/write points using the SIMION Modify screen. Unlike the View screen, the Modify screen accesses the raw array data (e.g. no interpolation is done between grid points) and allows editing that data too. This may be sufficient in limited cases.

  • Data recording along particle path trick. This is a convenient approach for exporting data in the limited case along a line or path. It works in SIMION 7.0 or above. Use SIMION Data Recording to record potentials or potential gradients on every time step or (with time markers enabled) on every marker. Set the output to a file in “delimited” (not “verbose”) format. Make a particle follow a path you want to record data on. Particles with zero charge can be useful here since they always fly in a straight line. (Additional details on the file formatting are at Exporting “data recording” results to text file. User programs can also access field data along particle paths (e.g. ion_volts, ion_dvoltsx_mm, and ion_dvoltsx_gu reserved variables within initialize and other_actions segments) or on test planes (SIMION Example: test_plane). You can also use a user program (Lua or PRG) to force the particle to follow a certain path (like in this old article), but the programming APIs described below are preferred in SIMION 8.0 or above.

    • An even more flexible technique is to start particles at each desired recording point along that path and set Data Recording “When to Record” to “Ion’s Start” (rather than “Ion’s Every Time Step”). It doesn’t matter where the particles go after their starting point.

  • SL Tools: Export (or import) the entire PA to (or from) a text file using SL Tools. This can be done via the Converting a PA File to ASCII Text conversion function in the SL Tools (sltools.exe) utility included in SIMION 8.0 (and previously in the SL Toolkit add-on package for 7.0). If you want to export only part of the array, you may with to crop the array first (Crop function on Modify screen in 8.0.4 or simion.pas pa:crop() API function in 8.1). If you need even more flexibility, use the programming APIs below.

  • Programming APIs: There are multiple different functions here depending on data and coordinate system you want to read and/or write.

    • To read electric or magnetic potentials or fields at an arbitrary point (x,y,z) in workbench coordinates (mm) within a workbench (IOB), use any of the Lua functions simion.wb:epotential(), simion.wb:efield(), simion.wb:bpotential(), and simion.wb:bfield(). These will only read from the electric of magnetic PA instance of the highest priority among those containing the given point, just like a particle being flown does, but any efield_adjust/mfield_adjust segments are ignored because those can be time dependent. This is also similar to the field information displayed in the status bar when you hover your mouse over the View screen. Example: ex,ey,ez = simion.wb:efield(x,y,z). Requires SIMION 8.1.1.0 or above. You may define helper functions like this:

      -- prints potentials and fields along a line divided into n segments.
function line_potentials(x1,y1,z1, x2,y2,z2, n)
  for i=0,n do
    local x,y,z = x1+(x2-x1)*i/n, y1+(y2-y1)*i/n, z1+(z2-z1)*i/n
    local v = simion.wb:epotential(x,y,z)
    local ex,ey,ez = simion.wb:efield(x,y,z)
    print(i, x,y,z, v, ex,ey,ez)
  end
end

    • To read electric or magnetic potentials or fields at an arbitrary points (x,y,z) in workbench coordinates (mm) within a specific PA instance in a workbench (IOB), use any of the Lua functions simion.wb instance:potential_wc() and simion.wb instance:field_wc(). Example: ex,ey,ez = simion.wb.instances[1]:field_wc(x,y,z). Requires SIMION 8.1.1.0 or above. There is also SIMION Example: field_dump (fielddumplib library) in version 2017-01-14 or above to simplify exporting this data to the log, CSV file, Excel, or gnuplot.

    • To read electric or magnetic potentials or fields at an arbitrary point (x,y,z) in PA volume coordinates (gu or mm) within a specific PA (which need to exist within an IOB), use any of the Lua functions simion.pas pa:potential_vc() or simion.pas pa:field_vc(). Example: v = simion.pas[1]:potential_vc(x,y,z) (accesses first PA in memory, as listed on the SIMION main screen) or v = simion.wb.instances[1].pa:potential_vc(x,y,z) (accesses first PA instance in the workbench, as listed on the View screen PAs tab). Requires SIMION 8.1.0 or above.

    • To read (or write) electric or magnetic potentials or electrode point status at an arbitrary integer grid point (x,y,z) in PA array coordinates (gu), accessing directly from the array object (ignoring symmetry, mirroring and interpolation), use any of the Lua functions simion.pas pa:potential(), simion.pas pa:electrode(), or (for both) simion.pas pa:point(). This is more low-level than the previous method but is required for writing. Example: v = simion.pas[1]:potential(xg,yg,zg) (accesses first PA in memory, as listed on the SIMION main screen) or v = simion.wb.instances[1].pa:potential(xg,yg,zg) (accesses first PA instance in the workbench, as listed on the View screen PAs tab). Requires SIMION 8.1.0 or above. For writing, see also SIMION Example: swirl.

    • To read (or write) data from PA’s that are not loaded into SIMION’s memory and do so using C++, Perl, or Python languages, use the SL Libraries. This is similar to the above Lua methods but reads the PA files outside of SIMION, which might be less efficient, not utilize all the features of SIMION, and be less convenient, so it’s typically less preferred, but it can suitable for some needs outside of SIMION. Warning: only the C++ implementation of SL Libraries can handle very large (e.g. gigabyte or larger) arrays. Requires SIMION 8.0.0 or above (or the older SL Toolkit). See SIMION Example: pa2text and SIMION Example: swirl. You can also program some things yourself according to the PA file format specification near the end of the “Files used by SIMION” appendix of the SIMION user manual (7.0/8.0/8.1).

    • Also see SIMION Example: gauss_law (simionx.FieldAnalysis - Integration over Fields) and SIMION Example: multipole_expansion.

Importing Data

There are a number of ways to import field and PA data:

  • Some of the methods described above for exporting fields can also be used for importing. These include SL Tools and the programming APIs. There are also Geometry Input Methods, but those are primarily concerned with inputing electrode geometries into a PA and then having SIMION calculate the field in that PA.

  • Segments: efield_adjust and mfield_adjust user programming segments can define a field from a user function, including an analytic equation. See SIMION Example: rfdemo (area.iob uses an efield_adjust for an analytic RF field), SIMION Example: mfield_adjust (mfield_adjust example), SIMION Example: surface_enhancement (8.1.1 compares PA calculated field to analytical one), and SIMION Example: quad (8.1.1.14 or above has an optional efield_adjust segment).

  • SIMION Example: field_array (8.0) loads field data from a CSV text file for use in a workbench user program. Note: in 8.1 you can instead use regular PA objects for field data accessed programmatically (see the solenoid_pa.iob sub-example), which is more efficient and also affords the ability to position them on the workbench via the PAs tab and visualize them.

  • Computational Fluid Dynamics (CFD) has notes specific to gas flow import.

See Also