simionx.FieldArray  3D vector field¶
simionx.FieldArray  3D vector field (e.g. Magnetic or electric) interpolated from data arrays.
See also Field Functions Library (simion.experimental.field_array) for a newer implementation based on SIMION PA objects (also SIMION Example: field_array).
SYNOPSIS¶
local FieldArray = require "simionx.FieldArray"
 Create a field array
local fa = FieldArray {
nx=10, ny=10, nz=1,
dx_mm=1, dy_mm=1, dz_mm=1,
scale=2,
x=0, y=0, z=0,
symmetry = "cylindrical"
}
 and define a magnetic field via an equation.
fa:read(function field(x,y,z)
return 10*x, 0.1*y^2, 0
end)
 or alternately, load it from a data file:
 local fa = FieldArray('myarray.csv')
 Test: Get field on grid point, with symmetry.
local bx,by,bz = fa(2,0,0.5)
print(bx,by,bz,"")
assert(bx == 20 and by == 0.025 and bz == 0)
 Test: Get field between grid points (interpolate)
local bx,by,bz = fa(2.01,0.51,0)
print(bx,by,bz) > 20.1 0.0265 0
print(field(2.01,0.51,0)) > 20.1 0.02601 0
(can differ slightly)
DESCRIPTION¶
This module is used to represent “field arrays,” which are analogous to SIMION “potential arrays” but represent field vectors rather than scalar potentials at each grid point. Methods are provided to interpolate fields between grid points, take into account symmetry (e.g. cylindrical or planar), and load/save arrays in a file.
You may use this for any other type of vector field. Typical usage of
this module would be to load a measured magnetic field from an ASCII
text file and represent that field in a SIMION workbench via an
mfield_adjust
user program segment. The SIMION field_array example
demonstrates that. Another usage would be for an iongas collision
model with nonzero background gas velocity that varies with position,
in which case the velocity could be represented with a field array).
This module may also be useful to speed up BiotSavart magnetic field calculations by caching computed values on nearby field array grid points once (slow) and then interpolating between those grid points many times thereafter (fast). The SIMION solenoid example has an option that demonstrates that.
Field arrays are implemented as sparse arrays, so memory is not wasted if large regions of an array are unused.
SIMION 8.1 note:
This module was originally designed prior to SIMION 8.1.
In SIMION 8.1, rather than use this module,
it often can be preferrable to store fields in
regular SIMION PA objects and access them via the simion.pas API.
PA objects have the advantage that they can be viewed an manipulated in
SIMION in the usual way (e.g. added/positioned in the workbench in View,
visualized in View, and edited in Modify).
The fa:convert_to_pas()
function can be used to convert a FieldArray
into a series of SIMION PA files, one for each component of the vector field.
Note
This page is abridged from the full SIMION "Supplemental Documentation" (Help file). The following additional sections can be found in the full version of this page accessible via the "Help > Supplemental Documentation" menu in SIMION 8.1.1 or above: INTERFACE
Methods¶

fa:read
()¶
fa:read(src)
Read field data from src. src can be filename, file handle, or
function. If a function is provided, the function must return the
field components (bx, by, bz)
at the given point (x,y,z)
as
follows:
bx,by,bz = func(x,y,z)
Example #1 (filename):
fa:read("data.csv")
Example #2 (file handle):
local fh = assert(io:open("data.csv"))
fa:read(fh)
fh:close()
Example #3 (function):
local function func(x,y,z) return x*2, 0, 0 end
fa:read(func)
For format, see output of fa:write()
.

fa:write
()¶
fa:write(dest)
Write field data to destination dest
. dest can be filename or file
handle.
Example #1 (filename):
fa:write("data.csv")
Example #2 (file handle):
local fh = assert(io.open("data.csv", "w"))  write mode
fa:write(fh)
fh:close()

fa:get
()¶
bx,by,bz = fa:get(x,y,z)
Gets the field components (bx,by,bz)
at the given system coordinate
point (x,y,z)
. Units can be anything, but typically SIMION units
would be used (e.g. mm, V/mm, or Gauss). Linearly interpolates
between grid points.
If point (x,y,z)
is outside the bounds of fa
, then it returns
(0,0,0)`.
fa:get(x,y,z)
is equivalent to the terser fa(x,y,z)
.
There is no corresponding fa:set
function–use fa:seti()
instead.
Example #1:
bx,by,bz = fa:get(10.23,11.9,2.3)
Example #2 (equivalent function call style):
bx,by,bz = fa(10.23,11.9,2.3)

fa:geti
()¶
Gets the field components (bx,by,bz)
at the given array point
(xi,yi,zi)
(before applying symmetry, interpolation, and coordinate
transformation).:
bx,by,bz = fa:geti(xi,yi,zi)
xi
, yi
, and zi
are integer grid unit
values in the ranges [0, nx1], [0, ny1], and [0, nz1].
Example:
bx,by,bz = fa:geti(5,0,0)

fa:seti
()¶
fa:seti(xi,yi,zi, bx,by,bz)
Sets the field components (bx,by,bz)
at the given array point
(xi,yi,zi)
(before applying symmetry, interpolation, and coordinate
transformation). See fa:geti()
.
Example:
fa:seti(5,0,0, 20,10,0)

fa:convert_to_pas
()¶
xpa, ypa, zpa = fa:convert_to_pas( basename, save )
Converts the field array object to SIMION PAs. This returns three new
PA objects (see simion.pas), one for each scalar component of
the velocity vector. The arrays are by default named “x.pa”, “y.pa”, and “z.pa”
but will be prefixed by the string basename
if specified (not nil
).
If save
is true
rather than false
or unspecified (nil
),
the PA files will be saved to disk.
Example:
fa:convert_to_pas()
fa:convert_to_pas('examplev', true)
Changes¶
 20120410  minor: fix to error message when .csv file has wrong number of data points.
 20120313  Added dx_mm, dy_mm, dz_mm parameters (for anisotropically scaled cells)
 20120215  Added fa:convert_to_pas.
SOURCE¶
version: 20120410