NAME

SIMION::PA (v. 2.00beta1) - Perl module for reading/writing/modifying SIMION potential arrays.

SYNOPSIS

 use SIMION::PA;
 
 #-- read an existing array
 my $pa = new SIMION::PA(file => 'buncher.pa#');
 # print header parameters the simple way
 print $pa->header_string;

 #-- create an array from scratch
 my $pa2 = new SIMION::PA(nx => 100, ny => 20,
                          symmetry => 'cylindrical');
 my $z = 0;
 for my $x (0..$pa2->nx-1) {
 for my $y (0..$pa2->ny-1) {
     my $inside = ($x + $y) < 10;
     if($inside) {
         $pa2->point($x, $y, $z, 1, 5.0); # electrode, 5V
     }
 }}
 $pa2->save('myarray.pa#');

 #-- create a magnetic field from scratch
 my $pa3 = new SIMION::PA(nx => 50, ny => 50, field_type => 'magnetic');
 my $z = 0;
 for my $x (0..$pa3->nx-1) {
 for my $y (0..$pa3->ny-1) {
     my $ex = $x;
     my $ey = $y**2;
     my $ez = 0;
     $pa3->field($x, $y, $z, $ex, $ey, $ez);
 }}
 $pa3->save('mag1.pa');

DESCRIPTION

This module is for manipulating SIMION potential array (PA/PA?) files (including creating, loading, modifying, and saving). See Appendix D-5 of the SIMION 7.0 manual for the PA file format specification.

This modules is intended to be very robust and has been put through an extensive test suite. It is also intended to be simple to use and very Perl-ish. The module is, however, not as fast as the corresponding C++ implementation, even though speed has been considered, so use the C++ implementation if speed is critical.

Methods

Construction Methods

• new(...)
  
Create a new array. To load an array from a file, do

  my $pa = new SIMION::PA(file => 'buncher.pa#');

To create an array from scratch (with all points initially set to 0V non-electrodes) do

  my $pa = new SIMION::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.
  );

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:

  my $pa = new SIMION::PA();
  my $pa = new SIMION::PA(nx => 100, ny => 20, field_type => 'magnetic');

• header_string()
  
Returns a string containing PATXT-formatted header for the current array. For example, for SIMION's QUAD.PA# file, the result is

 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.

• load($path)
  
Loads a potential array from a file.

  $pa->load('myfile.pa#');

Note: Arrays can also be loaded in the new method.

• save($path)
  
Saves potential array to a file.

  $pa->save('myfile.pa#');

Accessor Methods

• fast_adjustable($fast_adjustable)
  
Gets or sets whether the array is fast adjustable.

  $pa->fast_adjustable(1);
  print $pa->fast_adjustable;

• field_type($field_type)
  
Gets or sets the field type as a string. This is either ``electrostatic'' or ``magnetic''. Dies on error.

  $pa->field_type('magnetic');
  print $pa->field_type;

• max_voltage($max_voltage)
  
Gets or sets the max voltage value. Dies on error.

  $pa->max_voltage(100000);
  print $pa->max_voltage;

• mirror($mirror)
  
Gets or sets the full mirroring information. This is a string containing a subset of the letters ``xyz''. Dies on error.

  $pa->mirror('yz');
  print $pa->mirror;

Provides an error is not thrown, the above is equivalent to

  $pa->set(mirror_y => 1, mirror_z => 1);

• mirror_x($mirror_x)
  
Gets or sets a Boolean indicating whether the mirroring is enabled in the x direction. Dies on error.

  $pa->mirror_x(1);
  print $pa->mirror_x;

• mirror_y($mirror_y)
  
Gets or sets a Boolean indicating whether the mirroring is enabled in the y direction. Dies on error.

  $pa->mirror_y(1);
  print $pa->mirror_y;

• mirror_z($mirror_z)
  
Gets or sets a Boolean indicating whether the mirroring is enabled in the z direction. Dies on error.

  $pa->mirror_z(1);
  print $pa->mirror_z;

Here is an example of failure:

  my $pa = new SIMION::PA(symmetry => 'cylindrical');
  $pa->mirror_z(1); # dies: z mirroring not allowed in cylindrical symmetry.

• mode($mode)
  
Gets or sets the mode number. Currently, this is always -1. Dies on error.

  $pa->mode(-1);
  print $pa->mode;

• ng($ng)
  
Gets or sets the ng magnetic scaling factor.

  $pa->ng(100);
  print $pa->ng();

• num_points()
  
Gets the number of grid points. This is nx() * ny() * nz().

  my $pa = new SIMION::PA(nx => 3, ny => 4);
  print $pa->num_points();   # prints 12

• num_voxels()
  
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).

  my $pa = new SIMION::PA(nx => 3, ny => 4);
  print $pa->num_voxels();   # prints 6

• nx($nx)
  
Gets or sets the number of grid points in the x direction. Point data is cleared on resizing. Dies on error.

  $pa->nx(100);
  print $pa->nx;

• ny($ny)
  
Gets or sets the number of grid points in the y direction. Point data is cleared on resizing. Dies on error.

  $pa->ny(100);
  print $pa->ny;

• nz($nz)
  
Gets or sets the number of grid points in the z direction. Point data is cleared on resizing. Dies on error.

  $pa->nz(100);
  print $pa->nz;

• pasharp($pasharp)
  
Gets or sets the PA# associated with this PA0 (if any). undef if none. This is only intended for PA0 arrays. The PA# information is needed to properly save a PA0 file.

  my $pasharp = new SIMION::PA(file => "test.pa#");
  my $pa0 = new SIMION::PA();
  # ... add code to create pa0 array here.
  pa0->pasharp(&pasharp);
  pa0->save("test.pa0");

• set(...)
  
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.

  $pa->set(nz => 1, symmetry => 'cylindrical');

• size($nx, $ny, $nz)
  
Gets or sets the size for the array in grid points. Point data is cleared on resizing. Dies on error.

  $pa->size(10, 20, 30);
  my($nx, $ny, $nz) = $pa->size;

• symmetry($symmetry)
  
Gets or sets the symmetry. This is either 'planar' or 'cylindrical'. Dies on error.

  $pa->symmetry('cylindrical');
  print $pa->symmetry;

Boundary Methods

• inside($x, $y, $z)
  
Returns a Boolean indicating whether the given integer point is located within the array.

  print 'inside' if $pa->inside(10, 20, 30);

• inside_real($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.

  print $pa->inside(-10.1, 20.2, 30.3);

• voxel_inside($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.

  print $pa->voxel_inside(10, 20, 30);

Point Manipulation Methods

• electrode($x, $y, $z, $is)
  
Gets or sets the Boolean electrode state at the given integer point. Dies on error.

  $pa->electrode(10, 20, 30, 1);
  print $pa->electrode(10, 20, 30);

• field($x, $y, $z)
  
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. The setting function also 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), ...). Dies on error.

  # set
  for my $z (0..$pa->nz-1) {
  for my $y (0..$pa->ny-1) {
  for my $x (0..$pa->nx-1) {
      my $ex = $x;
      my $ey = $y**2;
      my $ez = 0;
      $pa->field($x, $y, $z, $ex, $ey, $ez);
  }}}

  my($ex, $ey, $ez) = $pa->field(10, 20, 30);  # get

• field_real($x, $y, $z)
  
Gets the electrostatic or magnetic field vector ($ex, $ey, $ez) at the given real (i.e. floating-point) point, taking symmetry and mirroring into account. Dies on error.

  my($ex, $ey, $ez) = $pa->field_real(-10.3, 20.2, 30.7);  # assuming mirror_x

• point($x, $y, $z, $is, $potential)
  
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);
  my($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);

• potential($x, $y, $z, $potential)
  
Gets or sets the potential at the given integer point. Dies on error.

  $pa->potential(10, 20, 30, 2.15);
  print $pa->potential(10, 20, 30);

• potential_real($x, $y, $z)
  
Get the potential at the given real (i.e. floating-point) 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. Dies on error.

  print $pa->potential(10.3, 20.2, 30.7);

• raw($x, $y, $z, $val)
  
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. Dies on error.

  $pa->raw(10, 20, 30, 100002.15);
  print $pa->raw(10, 20, 30);

• solid($x, $y, $z, $is)
  
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);

The first line above is the same as

  $pa->electrode(10, 20, 30, 1);
  $pa->electrode(10, 20, 31, 1);
  $pa->electrode(10, 21, 30, 1);
  $pa->electrode(10, 21, 31, 1);
  $pa->electrode(11, 20, 30, 1);
  $pa->electrode(11, 20, 31, 1);
  $pa->electrode(11, 21, 30, 1);
  $pa->electrode(11, 21, 31, 1);

The second line above is analogous, requiring all eight points to be electrodes.

Check Methods

• check(mode => $mode, max_voltage => $max_voltage, field_type => $field_type, $ng => $ng, fast_adjustable => $fast_adjustable, nx => $nx, ny => $ny, nz => $nz, mirror_x => $mirror_x, mirror_y => $mirror_y, mirror_z => $mirror_z, symmetry => $symmetry)
  
Returns a Boolean indicating 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. This method is useful in cases when the attributes are interdependent. For example, all of these fail:

  $pa->check(symmetry => 'cylindrical', nz => 2) or die $pa->{error};
  $pa->check(mirror_z => 1, nz => 1); or die $pa->{error};
  $pa->check(symmetry => 'cylindrical, mirror => 'xz') or die $pa->{error};

• check_field_type($field_type)
  
Returns a Boolean indicating whether the given field type string is valid. Valid strings are ``electrostatic'' and ``magnetic''. On false, the error string ($pa->{error}) is also set.

  $pa->check_field_type('magnetic') or die $pa->{error};

• check_max_voltage($voltage)
  
Returns a Boolean indicating whether the given max voltage value is valid. On false, the error string ($pa->{error}) is also set.

  $pa->check_max_voltage(100000) or die $pa->{error};

• check_mirror($mirror)
  
Returns a Boolean indicating whether the given mirroring string is valid. Valid strings are an ordered subset of ``xyz''. On false, the error string ($pa->{error}) is also set.

  $pa->check_mirror('yz') or die $pa->{error};

• check_mode($mode)
  
Returns a Boolean indicating whether the given mode is valid. Currently, the only valid mode is -1. On false, the error string ($pa->{error}) is also set.

  $pa->check_mode(-1) or die $pa->{error};

• check_ng($ng)
  
Returns a Boolean indicating whether the given ng magnetic scaling factor is valid. On false, the error string ($pa->{error}) is also set.

  $pa->check_symmetry(100) or die $pa->{error};

• check_nx($nx)
  
Returns a Boolean indicating whether the given grid dimension in the x direction is valid. On false, the error string ($pa->{error}) is also set.

  $pa->check_nx(100) or die $pa->{error};

• check_ny($ny)
  
Returns a Boolean indicating whether the given grid dimension in the y direction is valid. On false, the error string ($pa->{error}) is also set.

  $pa->check_ny(100) or die $pa->{error};

• check_nz($nz)
  
Returns a Boolean indicating whether the given grid dimension in the z direction is valid. On false, the error string ($pa->{error}) is also set.

  $pa->check_nz(100) or die $pa->{error};

• check_size($nx, $ny, $nz)
  
Returns a Boolean indicating whether the given set of grid dimensions in the x, y, and z directions is valid as a whole. Note that check_nx($nx) && check_ny($ny) && check_nz($nz) implies check_size($nx, $ny, $nz), although the converse is not necessarily true. On false, the error string ($pa->{error}) is also set.

  $pa->check_size(3, 3, 1) or die $pa->{error};

• check_symmetry($symmetry)
  
Returns a Boolean indicating whether the given symmetry string is valid. Valid strings are ``planar'' and ``cylindrical''. On false, the error string ($pa->{error}) is also set.

  $pa->check_symmetry('cylindrical') or die $pa->{error};

• error()
  
Returns the error string of the last error (or undef). $pa->error() is equivalent to $pa->{error}.

AUTHOR

David Manura (c) 2003-2004 Scientific Instrument Services, Inc. Licensed under the terms of the SIMION SL Toolkit. $Revision: 1.3 $ $Date: 2004/07/17 20:36:32 $ Created 2003-11.