SIMION® Industry standard charged particle optics simulation software.
Newsflash: SIMION 8.1.0 is here.
About | Documentation | Community/Support | Downloads | Ordering

SL Libraries -- Python

The SIMION SL™ Toolkit (version 1.2.1.0 - 2004-11-09)
Package SIMION :: Module PA :: Class PA
[show private | hide private]
[frames | no frames]

Class PA


This is a Python class for reading/writing/modifying SIMION potential arrays.
Method Summary
  check(self, mode, field_type, symmetry, mirror, mirror_x, mirror_y, mirror_z, nx, ny, nz, fast_adjustable, max_voltage, ng, enable_points, file)
Checks whether the given combination of attributes is valid.
  check_field_type(self, field_type)
Checks whether the given field type is valid.
  check_max_voltage(self, max_voltage)
Checks whether the given max voltage values is valid.
  check_mirror(self, mirror)
Check whether the given mirroring string is valid.
  check_mode(self, mode)
Checks whether the given mode is valid.
  check_ng(self, ng)
Checks whether the given ng magnetic scaling factor is valid.
  check_nx(self, nx)
Checks whether the given grid dimension in the x direction is valid.
  check_ny(self, ny)
Checks whether the given grid dimension in the y direction is valid.
  check_nz(self, nz)
Checks whether the given grid dimension in the z direction is valid.
  check_size(self, nx, ny, nz)
Checks whether the given set of grid dimensions in the x, y, and z directions is valid as a whole.
  check_symmetry(self, symmetry)
Checks whether the given symmetry is valid.
  error(self)
Get last error message generated by one of the check calls.
  pasharp(self, pasharp)
Gets or sets the PA# associated with this PA0 (if any).
    Construction and Serialization
  __init__(self, mode, symmetry, max_voltage, nx, ny, nz, mirror, mirror_x, mirror_y, mirror_z, field_type, ng, fast_adjustable, enable_points, file)
Constructor.
  header_string(self)
Returns a string containing PATXT-formatted header for the current array.
  load(self, filepath)
Loads a potential array from a file.
  save(self, filepath)
Saves potential array to file.
    Attribute Getters/Setters
  field_type(self, field_type)
Gets or sets the field type as a string.
  fast_adjustable(self, fast_adjustable)
Gets or sets whether the array is fast adjustable.
  max_voltage(self, max_voltage)
Gets or sets the max voltage value.
  mirror(self, mirror)
Gets or sets the full mirroring information.
  mirror_x(self, mirror_x)
Gets or sets a Boolean indicating whether the mirroring is enabled in the x direction.
  mirror_y(self, mirror_y)
Gets or sets a Boolean indicating whether the mirroring is enabled in the y direction.
  mirror_z(self, mirror_z)
Gets or sets a Boolean indicating whether the mirroring is enabled in the z direction.
  mode(self, mode)
Gets or sets the mode number.
  ng(self, ng)
Gets or sets the ng magnetic scaling factor.
  num_points(self)
Gets the number of grid points.
  num_voxels(self)
Gets the number of voxels (2D or 3D pixels).
  nx(self, nx)
Gets or sets the number of grid points in the x direction.
  ny(self, ny)
Gets or sets the number of grid points in the y direction.
  nz(self, nz)
Gets or sets the number of grid points in the z direction.
  set(self, mode, symmetry, max_voltage, nx, ny, nz, mirror, mirror_x, mirror_y, mirror_z, field_type, ng, fast_adjustable, enable_points, file)
Sets multiple attributes at once.
  size(self, nx, ny, nz)
Gets or sets the size for the array in grid points.
  symmetry(self, symmetry)
Gets or sets the symmetry.
    Boundary and Coordinates
  inside(self, x, y, z)
Returns a Boolean indicating whether the given integer point is located within the array.
  inside_real(self, x, y, z)
Returns a Boolean indicating whether the given real (i.e.
  voxel_inside(self, x, y, z)
Returns a Boolean indicating whether the given integer voxel is located within the array.
    Point Setters/Getters
  clear_points(self)
  electrode(self, x, y, z, is_electrode)
Gets or sets the Boolean electrode state at the given integer point.
  field(self, x, y, z, ex, ey, ez)
Gets or sets the field (potential gradient) vector at the given point.
  field_real(self, x, y, z)
Gets the electrostatic or magnetic field vector (ex, ey, ez) at the given real point, taking symmetry and mirroring into account.
  point(self, x, y, z, is_electrode, potential)
Gets or sets the Boolean electrode state and the potential at the given integer point.
  potential(self, x, y, z, potential)
Gets or sets the potential at the given integer point.
  potential_real(self, x, y, z)
Get the potential at the given real point, taking symmetry and mirroring into account.
  solid(self, x, y, z, is_electrode)
Gets or sets the solid electrode state for the given integer voxel.
  raw(self, x, y, z, val)
Gets or sets the raw value at the given integer point.

Method Details

__init__(self, mode=None, symmetry=None, max_voltage=None, nx=None, ny=None, nz=None, mirror=None, mirror_x=None, mirror_y=None, mirror_z=None, field_type=None, ng=None, fast_adjustable=None, enable_points=None, file=None)
(Constructor)

Constructor. Creates a new array.

To load an array from a file, do
>>> pa = PA(file = 'buncher.pa#')
To create an array from scratch (with all points initially set to 0V non-electrodes) do
>>> pa = PA(
mode = -1,               # mode (always -1)
symmetry = 'planar',     # symmetry type: 'planar' or 'cylindrical'
max_voltage = 100000,    # this affects the interpretation
                         #   of point values
nx = 100,                # x dimension in grid units
ny = 100,                # y dimension in grid units
nz = 1,                  # z dimension in grid units
mirror = '',             # mirroring (subset of "xyz")
field_type =             # field type: 'electrostatic' or 'magnetic'
    'electrostatic',     #
ng = 100,                # ng scaling factor for magnetic arrays.
fast_adjustable = 0,     # Boolean indicating whether is fast-adj.
enable_points = 1        # Enable data points.
)
See p. 2-10 of the SIMION 7.0 manual for details on these parameters. The parameters given above are default values, and any/all can be omitted:
>>> pa = PA();
>>> pa = PA(nx = 100, ny = 20, field_type = 'magnetic')

header_string(self)

Returns a string containing PATXT-formatted header for the current array.

For example, for SIMION's QUAD.PA# file, the result is as such:
   begin_header
       mode -1
       symmetry planar
       max_voltage 20000
       nx 77
       ny 39
       nz 1
       mirror_x 0
       mirror_y 1
       mirror_z 0
       field_type electrostatic
       ng 100
       fast_adjustable 1
   end_header
This method is also very useful for debugging to quickly display the information on a given potential array.
Returns:
string containing header information as text.

load(self, filepath)

Loads a potential array from a file.

Note: Arrays can also be loaded in the new method. Example:
>>>  pa.load('myfile.pa#')
Parameters:
filepath - string containing relative or absolute path to file.

save(self, filepath)

Saves potential array to file.
>>> pa.save('myfile.pa#')
Parameters:
filepath - relative or absolute path to file.

field_type(self, field_type=None)

Gets or sets the field type as a string.

This is either "electrostatic" or "magnetic".
>>> pa.field_type('magnetic')
>>> print pa.field_type()
Parameters:
field_type - string containing field type identifier (if setting).
Returns:
field_type (if getting)

fast_adjustable(self, fast_adjustable=None)

Gets or sets whether the array is fast adjustable.
>>> pa.fast_adjustable(1)
>>> print pa.fast_adjustable()
Parameters:
fast_adjustable - Boolean indicating whether array is fast adjustable (if setting)
Returns:
fast_adjustable (if getting)

max_voltage(self, max_voltage=None)

Gets or sets the max voltage value.
>>> pa.max_voltage(100000)
>>> print pa.max_voltage()
Parameters:
max_voltage - number containing max voltage value (if setting).
Returns:
max_voltage (if getting).

mirror(self, mirror=None)

Gets or sets the full mirroring information.
>>> pa.mirror('yz')
>>> print pa.mirror()
The above is equivalent to
>>> pa.set(mirror_y = 1, mirror_z = 1)
Parameters:
mirror - string containing a subset of the letters "xyz". (if setting)
Returns:
mirror (if getting)

mirror_x(self, mirror_x=None)

Gets or sets a Boolean indicating whether the mirroring is enabled in the x direction.
>>> pa.mirror_x(1)
>>> print pa.mirror_x()

mirror_y(self, mirror_y=None)

Gets or sets a Boolean indicating whether the mirroring is enabled in the y direction.
>>> pa.mirror_y(1)
>>> print pa.mirror_y()

mirror_z(self, mirror_z=None)

Gets or sets a Boolean indicating whether the mirroring is enabled in the z direction.
>>> pa.mirror_z(1)
>>> print pa.mirror_z()

mode(self, mode=None)

Gets or sets the mode number.

Currently, this is always -1.
>>> pa.mode(-1)
>>> print pa.mode()
Parameters:
mode - integer containing mode number (if setting).
Returns:
mode (if getting).

ng(self, ng=None)

Gets or sets the ng magnetic scaling factor.
>>> pa.ng(100)
>>> print pa.ng()
Parameters:
ng - integer containing the magnetic scalaing factor (if setting).
Returns:
ng (if getting)

num_points(self)

Gets the number of grid points.

This is nx() * ny() * nz().
>>> pa = PA(nx = 3, ny = 4)
>>> print pa.num_points()   # prints 12
Returns:
integer containing number of grid points.

num_voxels(self)

Gets the number of voxels (2D or 3D pixels).

Each voxel is surrounded by four (2D arrays) or eight (3D arrays) grid points. For 2D arrays, this is (nx()-1) * (ny()-1). For 3D arrays, this is (nx()-1) * (ny()-1) * (nz()-1).
>>> pa = PA(nx = 3, ny = 4)
>>> print pa.num_voxels()   # prints 6
Returns:
integer containing number of voxels.

nx(self, nx=None)

Gets or sets the number of grid points in the x direction.

Point data is cleared on resizing.
>>> pa.nx(100)
>>> print pa.nx()
Parameters:
nx - integer containing x dimension in grid points (if setting).
Returns:
nx (if getting).

ny(self, ny=None)

Gets or sets the number of grid points in the y direction.

Point data is cleared on resizing.
>>> pa.ny(100)
>>> print pa.ny()
Parameters:
ny - integer containing y dimension in grid points (if setting).
Returns:
ny (if getting).

nz(self, nz=None)

Gets or sets the number of grid points in the z direction.

Point data is cleared on resizing.
>>> pa.nz(100)
>>> print pa.nz()
Parameters:
nz - integer containing z dimension in grid points (if setting).
Returns:
nz (if getting).

set(self, mode=None, symmetry=None, max_voltage=None, nx=None, ny=None, nz=None, mirror=None, mirror_x=None, mirror_y=None, mirror_z=None, field_type=None, ng=None, fast_adjustable=None, enable_points=None, file=None)

Sets multiple attributes at once.

This can take the same set of parameters as the new() method. This method is useful when the attributes are interdependent. Asserts on error.
>>>  pa.set(nz = 1, symmetry = 'cylindrical')
See the individual setter methods for details on each parameter.

size(self, nx=None, ny=None, nz=None)

Gets or sets the size for the array in grid points.

Point data is cleared on resizing.
>>> pa.size(10, 20, 30)
>>> (nx, ny, nz) = pa.size()
Parameters:
nx - integer containing x dimension in grid points (if setting).
ny - integer containing y dimension in grid points (if setting).
nz - integer containing z dimension in grid points (if setting).
Returns:
(nx, ny, nz) tuple (if getting)

symmetry(self, symmetry=None)

Gets or sets the symmetry.
>>> pa.symmetry('cylindrical')
>>> print pa.symmetry()
Parameters:
symmetry - string containing symmetry identifier (if setting). This is either 'planar' or 'cylindrical'.
Returns:
symmetry (if getting).

inside(self, x, y, z)

Returns a Boolean indicating whether the given integer point is located within the array.
>>> if pa.inside(10, 20, 30): print 'inside'
Parameters:
x - integer containing x position in grid points (zero indexed).
y - integer containing y position in grid points (zero indexed).
z - integer containing z position in grid points (zero indexed).
Returns:
Boolean indicating whether point is inside.

inside_real(self, x, y, z)

Returns a Boolean indicating whether the given real (i.e. floating-point) point is located within the array, taking symmetry and mirroring into account. Note that inside($x, $y, $z) implies inside_real($x, $y, $z), although the converse is not necessarily true.
>>> if pa.inside(-10.1, 20.2, 30.3): print 'inside'
Parameters:
x - real number containing x position in grid points.
y - real number containing y position in grid points.
z - real number containing z position in grid points.
Returns:
Boolean indicating whether point is inside.

voxel_inside(self, x, y, z)

Returns a Boolean indicating whether the given integer voxel is located within the array.

The voxel is specified by its most negative grid point corner--for example, (2, 3, 4) represents the voxel contained in the box [2..3, 3..4, 4..5]. Note that voxel_inside(x, y, z) implies inside(x, y, z), although the converse is not necessarily true.
>>> if pa.voxel_inside(10, 20, 30): print 'inside'
Parameters:
x - integer containing x position in grid points.
y - integer containing y position in grid points.
z - integer containing z position in grid points.
Returns:
Boolean indicating whether voxel is inside.

electrode(self, x, y, z=0, is_electrode=None)

Gets or sets the Boolean electrode state at the given integer point.
>>> pa.electrode(10, 20, 30, 1)
>>> print pa.electrode(10, 20, 30)
Parameters:
x - integer containing x position in grid points.
y - integer containing y position in grid points.
z - integer containing z position in grid points.
Returns:
Boolean indicating whether point is an electrode.

field(self, x, y, z=0, ex=None, ey=None, ez=None)

Gets or sets the field (potential gradient) vector at the given point.

The setting function internally performs the numerical integration on the given field vectors to generate the corresponding scalar potentials that must be stored in the PA file. Dies on error.

Warning: The setting function has some special calling requirements. First, the all points must initially be zero volt, nonelectrodes. Second, the field setting method must be called for all points in the array in lexographic order (e.g. (0,0,0), (0,0,1), ... (0,0,nx()-1), (0,1,0), (0,1,1), (0,1,nx()-1), ...).
>>> # set
>>> for z in range(0,pa.nz()):
...    for y in range(0,pa.ny()):
...        for x in range(0,pa.nx()):
...            ex = x
...            ey = y**2
...            ez = 0
...            pa.field(x, y, z, ex, ey, ez)
>>> (ex, ey, ez) = pa.field(10, 20, 30)  # get

field_real(self, x, y, z=0)

Gets the electrostatic or magnetic field vector (ex, ey, ez) at the given real point, taking symmetry and mirroring into account.
>>> # assuming mirror_x
>>> (ex, ey, ez) = pa.field_real(-10.3, 20.2, 30.7)
Parameters:
x - real number containing x position in grid points.
y - real number containing y position in grid points.
z - real number containing z position in grid points.
Returns:
(ex, ey, ez) tuple, where ex, ey, and ez are real numbers containing the x, y, and z components of the field vector respectively.

point(self, x, y, z=0, is_electrode=None, potential=None)

Gets or sets the Boolean electrode state and the potential at the given integer point.

This is identical to calls to both the potential and electrode methods. Dies on error.
>>> pa.point(10, 20, 30, 1, 2.15)
>>> (is_electrode, potential) = pa.point(10, 20, 30)
The first line above is the same as
>>> pa.electrode(10, 20, 30, 1)
>>> pa.potential(10, 20, 30, 2.15)
Parameters:
x - integer containing x position in grid points.
y - integer containing y position in grid points.
z - integer containing z position in grid points.
is_electrode - Boolean indicating whether the point is an electrode (if setting).
potential - real number containing the potential value (if setting).
Returns:
(is_electrode, potential) tuple (if getting).

potential(self, x, y, z=0, potential=None)

Gets or sets the potential at the given integer point.
>>> pa.potential(10, 20, 30, 2.15)
>>> print pa.potential(10, 20, 30)
Parameters:
x - integer containing x position in grid points.
y - integer containing y position in grid points.
z - integer containing z position in grid points.
potential - real number containing potential value (if setting).
Returns:
potential (if getting).

potential_real(self, x, y, z=0)

Get the potential at the given real point, taking symmetry and mirroring into account.

Interpolation is applied between grid points, as described on page E-7 os the SIMION 7.0 manual, except that the current version of this module does not perform special handling near electrode edges.
>>> print pa.potential(10.3, 20.2, 30.7)
Parameters:
x - real number containing x position in grid points.
y - real number containing y position in grid points.
z - real number containing z position in grid points.
Returns:
real number containing interpolated potential value.

solid(self, x, y, z=0, is_electrode=None)

Gets or sets the solid electrode state for the given integer voxel.

For a voxel to be a solid electrode (rather than a ideal grid electrode), all four (for 2D arrays) or eight (for 3D arrays) surrounding grid points must be electrode points. Dies on error.
>>> pa.solid(10, 20, 30, 1)
>>> print pa.solid(10, 20, 30)
Parameters:
x - integer containing x position in grid points.
y - integer containing y position in grid points.
z - integer containing z position in grid points.
is_electrode - Boolean indicating whether voxel is a solid electrode point (if setting)
Returns:
is_electrode (if getting)

raw(self, x, y, z=0, val=None)

Gets or sets the raw value at the given integer point.

The raw value is what is stored internally in the array at each data point and is not normally used directly. It is defined as potential(x,y,z) + is_electrode(x,y,z) ? 2 * max_voltage() : 0.
>>> pa.raw(10, 20, 30, 100002.15)
>>> print pa.raw(10, 20, 30)
Parameters:
x - integer containing x position in grid points.
y - integer containing y position in grid points.
z - integer containing z position in grid points.
Returns:
real number containing raw value.

check(self, mode=None, field_type=None, symmetry=None, mirror=None, mirror_x=None, mirror_y=None, mirror_z=None, nx=None, ny=None, nz=None, fast_adjustable=None, max_voltage=None, ng=None, enable_points=None, file=None)

Checks whether the given combination of attributes is valid.

Any subset of the above named parameters may be specified, and the named parameter 'mirror' containing a subset of the string 'xyz' may be specified as an alternative to the mirror_x, mirror_y, and mirror_z named parameters. The set method is useful in cases when the attributes are interdependent. For example, all of these fail:
>>> if not util.check(symmetry = 'cylindrical', nz = 2):
...     print util.error()
>>> if not util.check(mirror_z = 1, nz = 1):
...     print util.error()
>>> if not util.check(symmetry = 'cylindrical, mirror = 'xz'):
///     print util.error()
Refer to the individual 'check' functions for details on the parameters.
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_field_type(self, field_type)

Checks whether the given field type is valid.

Example:
>>> if not util.check_field_type("magnetic"): print util.error()
Parameters:
field_type - string containing field type identifier. Valid identifiers are "electrostatic" and "magnetic".
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_max_voltage(self, max_voltage)

Checks whether the given max voltage values is valid.

Example:
>>> if not util.check_max_voltage(100000): print util.error()
Parameters:
max_voltage - number containiner votlage value.
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_mirror(self, mirror)

Check whether the given mirroring string is valid.
>>> if not util.check_mirror("yz"): print util.error()
Parameters:
mirror - string containing the mirroring identifier. Valid strings are an ordered subset of "xyz".
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_mode(self, mode)

Checks whether the given mode is valid.

Currently, the only valid mode is -1. Example:
>>> if not util.check_mode(-1): print util.error()
Parameters:
mode - integer mode number.
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_ng(self, ng)

Checks whether the given ng magnetic scaling factor is valid.

Example:
>>> if not util.check_ng(100): print util.error()
Parameters:
ng - integer containing ng number
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_nx(self, nx)

Checks whether the given grid dimension in the x direction is valid.

Example:
>>> if not util.check_nx(100): print util.error()
Parameters:
nx - integer containing x dimension in number of grid points.
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_ny(self, ny)

Checks whether the given grid dimension in the y direction is valid.

Example:
>>> if not util.check_ny(100): print util.error()
Parameters:
ny - integer containing y dimension in number of grid points.
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_nz(self, nz)

Checks whether the given grid dimension in the z direction is valid.

Example:
>>> if not util.check_nz(100): print util.error()
Parameters:
nz - integer containing z dimension in number of grid points.
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_size(self, nx, ny, nz=1)

Checks whether the given set of grid dimensions in the x, y, and z directions is valid as a whole.

Note that check_nx(nx) and check_ny(ny) and check_nz(nz) implies check_size(nx, ny, nz), although the converse is not necessarily true. Example:
>>> if not util.check_size(3, 3, 1): print util.error()
Parameters:
nx - integer containing x dimension in number of grid points.
ny - integer containing y dimension in number of grid points.
nz - integer containing z dimension in number of grid points.
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

check_symmetry(self, symmetry)

Checks whether the given symmetry is valid.

Example:
>>> if not util.check_symmetry("cylindrical"): print util.error()
Parameters:
symmetry - string containing symmetry identifier. Valid strings include "planar" and "cylindrical".
Returns:
(ok, err), where ok is a Boolean indicating validity, and err is a string containing any error message.

error(self)

Get last error message generated by one of the check calls.

pasharp(self, pasharp=None)

Gets or sets the PA# associated with this PA0 (if any). None if none. This is only intended for PA0 arrays. The PA# information is needed to properly save a PA0 file.
>>> pasharp = PA(file = "test.pa#")
>>> pa0 = PA()
>>> # ... add code to create pa0 array here.
>>> pa0.pasharp(pasharp)
>>> pa0.save("test.pa0")
Parameters:
pasharp - PA# potential array object @return PA# potential array object

Generated by Epydoc 2.1 on Mon Nov 8 17:23:15 2004 http://epydoc.sf.net
Please report any errors/comments regarding this web page:
  Name/e-mail/phone (optional):
 
The SIMION SL Toolkit™ and documentation is (c) 2003-2004 Scientific Instrument Services, Inc. All Rights Reserved.
Any comments on this web page? (will be sent to SIS)
[Optional] Your name: email: phone/fax:
The SL Tookit™ and documentation is (c) 2003 Scientific Instrument Services, Inc. All Rights Reserved.
(c) 2003-2006 Scientific Instrument Services, Inc. (SIS). Contact SIS.