User-defined magnetic fields.


See also general note on magnetic fields.


An example of a routine for a user-defined magnetic field (and also time-dependent voltages) is supplied with the CPO3D package. It is called ‘user3d.cpp’ and is written in C++. A read-only version, called use3copy.cpp is also included in the package.


A compiled version of this routine, called ‘user3d.dll’ is also supplied with the package.


In this example the magnetic field components are interpolated from a grid of values that have been pre-calculated by the user. The pre-calculated values could be obtained for example by using the 'grid' option, or the pre-calculated values could be deduced from known axial values using the program given in the set of analysis programs.


The user-defined routine can of course also be quite different, not using interpolation from a grid.


To use the present grid example make sure that ‘user3d.dll’ is in the same directory as the CPO3D program (this directory is usually called CPO).

To use this example for a magnetic field:

(1) Create a file (in txt format) that must be called ‘grid.dat’ and must be in the same directory as the CPO3D program. An example (for a uniform magnetic field) is given with the CPO package. This file has the following format (but without the comments at the end of each line):

16 16 16 (Number of points in x, y and z directions)

-200.0 -150.0 -150.0 20.0 (start coordinates x0,y0,z0 and step size, all in mm)

0.0 0.0 1.0 (x,y,z field components, in Teslas)

0.0 0.0 1.0



The first line gives the numbers of grid points in the x,y and z directions. These numbers must be integers. The minimum value of each is 3.

The second line gives the coordinates x0,y0,z0 of the origin point of the grid, followed by the distance (in millimetres) between neighbouring grid points.

The remaining lines give the values of the field components Bx,By,Bz (in Teslas) at the grid points. The number of these lines is obviously the product of the 3 integers in the first line (i.e. 4096 in the present example). The ordering of these lines is such that the values of z change most quickly, and those of x change most slowly. Therefore in the present example the first of the lines gives (Bx,By,Bz) at (x,y,z) = (-200,-150,-150), the 2nd at (-200,-150,-130), the 16th at (-200,-150, 150), the 17th at (-200,-130,-150), etc, up to the last at (+100,+150,+150).

(2) In the input data file enter ‘o’, as explained in the relevant note, followed 3 dummy lines, as explained in the relevant note, the first 2 of these containing 6 numbers each and the third 3 numbers.

The interpolation is bilinear -that is, the values of (Bx,By,Bz) at the 8 corners of the grid box that encloses the point (x,y,z) are used.

The main program gives the coordinates (x,y,z) and then the routine calculates the values of (Bx,By,Bz) and returns them to the main program.


To create a new routine to define a magnetic field and/or time-dependent voltages, either edit ‘user3d.cpp’ or write your own. To compile the new routine, follow the instructions given in ‘user3d.cpp’ in the set of miscellaneous programs, or the more recent instructions given for the scattering routine. The 9th value in the array param (see below) is available for an error number.


For information on editing or re-compiling the present example file, or using completely new routines, see the set of miscellaneous programs.