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 ion-gas collision model with non-zero 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 Biot-Savart 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, nx-1], [0, ny-1], and [0, nz-1].

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('example-v', 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


[Optional] Your name:	email:	phone: