There is the possibility (under certain conditions) to load an external magnetic field, instead of calculating it with the included BEM magnetic field solver. There are the following two possibilities:

• Magnetic field with few datapoints and unstructured arrangement
• Magnetic field with many datapoints and structured arrangement in a box

To activate this feature, the following line of the parameter file has to be uncommented:

BFIELDFILE = "external_field.txt";

There are two file formats for the unstructured magnetic field supported, text and binary format. The format is determined during runtime, independent of the file extension. The conditions for the text format are the following:

• an entry consists of 6 values, three values for the x-y-z-position and three values for the Bx-By-Bz-strength at that point
• only one entry per line
• the separators for the values are either tabulators or spaces

and the conditions for the binary format are:

• an entry consists of 6 values, three values for the x-y-z-position and three values for the Bx-By-Bz-strength at that point
• no separators between the values or the entries
• the values have to be double precision floating point numbers

Additionally the following conditions are valid for both formats:

• the position values of the external field have to be in the same coordinate system as the mesh in [m]
• the values for the strength of the external field have to be given in tesla [T]
• the volume covered by the external field has to be greater or equal to the simulation volume

The resolution of the external field compared to the simulation resolution does not matter because the magnetic field is interpolated, but not extrapolated (see point above).

Important notes:

• The coordinates have to be given in meter [m] irrespective of the used mesh unit given in the parameter file for the simulation volume.
• The order and structure of the coordinate points can be completely arbitrary, however the interpolation routine scales with the product of coordinate points in the simulation volume and data points in the TXT file. Thus, for large B field datasets the time for reading and interpolating the B field data can become unreasonable.

The second method of importing a magnetic field is available since version 2.4.3.5 and was implemented for large datasets, where the point coordinates are aligned in a rectangular box. This simplifies the interpolation of the magnetic field data on the simulation grid points and thus, this method is much faster in case of very large B field files.

The import command of “rastered B field files” is implemented as a method of the PICMC object and can be activated via the user block in the parameter file. To use it, leave the parameter #BFIELDFILE commented out, uncomment the User_Block: at the end of the parameter file and use the following commands:

block User_Block: {
  bfieldfile = "large-bfield-file.txt";
  message = "Reading rastered external Bfield from $(bfieldfile)";
  console "** $(message) **\n";
  write_logentry(message);
  S.read_bfield_raster(bfieldfile, -300, -884, 14,   300, 884, 210,   151, 443, 50,   1e-4);
};

The syntax of the command is

S.read_bfield_raster(bfieldfile, x0, y0, z0, x1, y1, z1, nx, ny, nz, factor);

The parameters have the following meaning:

• bfieldfile = Filename of the file containing the magnetic field data (path relative to the *.par file)
• x0, y0, z0 = Lower coordinates of the rectangular box
• x1, y1, z1 = Upper coordinates of the rectangular box
• nx, ny, nz = Number of data points in X, Y, and Z direction
• factor = Factor, by which the magnetic field vector shall be multplied (in case if the magnetic field in the TXT file is not given in Tesla units, the above example uses a factor of 10^-4 for converting from Gauss to Tesla)

Important notes:

• The format of the TXT file is six columns with (X,Y,Z) coordinates in the first three columns and (Bx, By, Bz) field vector in the columes 4-6. The separator between the columns shall be one or more blank spaces.
• The ordering of the coordinate points in the TXT file does not matter. It is only required that all nx*ny*nz points are included exactly once, otherwise an error message will be displayed.
• Unlike the older B field import method mentioned above, all coordinates here are sensitive to the mesh unit specified in the simulation volume. This also applies for the coordinate points in the TXT file.
• The interpolation of the B field values onto the simulation grid is performed via trilinear interpolation. It is required that the simulation grid (as specified in the simulation volume) either has the same size as the magnetic field box or fits within.