4.9. Magnetic Background Field

Certain application cases allow the utilization of a constant magnetic background field. This background field can either be supplied via .csv (1D) or .h5 (2D axisymmetric/3D) file, however, in this case the field must be based on an equidistant Cartesian mesh. Another method is to use the built-in tool superB, which is also available as stand-alone executable to generate magnetic fields based on magnets or coils, which results in the creation of a .h5 file containing the field data based on a PICLas (PyHOPE) mesh file. Both methods can be combined through super-position to include an external read-in with a superB-generated magnetic field. The following two sections give an overview of using the different methods.

4.9.1. Read-in of an External Field

One-, two- and three-dimensional magnetic fields can be used as fixed background fields for certain equation systems (full Maxwell and Poisson with the Boris-Leapfrog time discretization). The read-in variable for either .csv (only for 1D along \(z\)-direction) or .h5 (only for 2D axis symmetric \(z\)-direction or fully 3D) files is set via

PIC-variableExternalField = X.csv, X.h5

Examples are located within the regression test directory

regressioncheck/CHE_PIC_maxwell_RK4/gyrotron_variable_Bz
regressioncheck/CHE_PIC_maxwell_RK4/2D_variable_B
regressioncheck/CHE_PIC_maxwell_RK4/3D_variable_B
regressioncheck/WEK_PIC_poisson_Boris-Leapfrog/EBeam_2D-axisym-with-B-field

for 1D, 2D and 3D fields, respectively. Note that 1D currently only allows magnetic fields of type \(B_{z}(z)\) and 2D only allows the components \(B_{r}(r,z)\) and \(B_{z}(r,z)\) that comprise a rotationally symmetric vector field \(\textbf{B}\).

The first example (1D and .csv file) uses data via

PIC-variableExternalField = variable_Bz.csv

which contains comma-separated values in the form

-0.00132,2.7246060625
-0.000217551020408,2.700481016
0.0008848979591837,2.6762685135
0.0019873469387755,2.6519260266
0.0030897959183674,2.6274128336
....

and the second (2D and .h5 file)

PIC-variableExternalField = reggie-linear-rot-symmetry.h5

that is read from a .h5 file. The data structure in the .h5 file must be of the form (dataset is labelled “data”) and contains

r1 z1 Br1 Bz1
r2 z2 Br2 Bz2
r3 z3 Br3 Bz3
r4 z4 Br4 Bz4
r5 z5 Br5 Bz5
....

where for each data point one row is required. The ordering of the data is also important. It is only allowed that the first \(N\) rows have the same \(r\) value and varying \(z\)-components (\(r\) is the outer loop variable and \(z\) is the inner loop variable when unrolling the data into an array). This is automatically checked by comparing the distances in \(r\) and \(z\) direction, which must be equidistant. In addition, the attributes r, z, Br and Bz, which contain the indices of the corresponding column number in “data”.

Axisymmetric external fields can be utilized in a 3D simulation. For this purpose the axis in the 3D domain that corresponds to the rotational axis has to be defined:

PIC-variableExternalFieldSymAxis = 1        ! 1: x, 2: y, 3: z

Axisymmetric simulations, which are per definition in the x-y-plane, will correctly interpolate the external field without additional user input.

Three-dimensional fields must be supplied in the following format

x1 y1 z1 Bx1 By1 Bz1
x2 y1 z1 Bx2 By2 Bz2
x1 y2 z1 Bx3 By3 Bz3
x2 y2 z1 Bx4 By4 Bz4
x1 y1 z2 Bx5 By5 Bz5
x2 y1 z2 Bx6 By6 Bz6
....

where the data (dataset is labelled “data” in the .h5 file) is sorted in lines in ascending coordinates, where first the \(x\)-, then \(y\)- and finally the \(z\)-coordinate is varied.

4.9.2. Calculation with superB

The magnetic field resulting from certain types of coils (using the Biot-Savart law or Jefimenko’s equations) and permanent magnets (using the magnetic potential) can be calculated during the initialization within PICLas or with the standalone tool superB (see Section Compiler options for compilation). The latter can solely be used to create a .h5 file that contains the B-field data via

superB parameter_superB.ini

For usage in PICLas, the background field can be enabled by

PIC-BG-Field = T

The first option is to use a background field that was previously calculated with superB. It can be read-in with

PIC-BGFileName     = BField.h5 ! Path to a .h5 file that contains the B-field data
PIC-NBG            = 1         ! Polynomial degree of the B-field
PIC-BGFieldScaling = 1.        ! Scaling factor for the B-field

Additionally, the polynomial degree for the background field can be set by PIC-NBG and might differ from the actually read-in polynomial degree that is used to represent the numerical solution for the field solver. Optionally, the read-in field can be scaled by the last of the three parameters above.

The second option is to calculate the magnetic field during the initialization, which will produce an output .h5 file of the field. The field will automatically be calculated from the supplied parameters, if the corresponding .h5 file does not exist. For this purpose, different coil and permanent magnet geometries can be defined. For visualization purposes, the geometry of the respective coils and permanent magnets can be directly written out as a VTK with

PIC-CalcBField-OutputVTK = T

In the following the parameters for different coils and permanent magnets based on the implementation by Hinsberger [41] are presented.

4.9.2.1. Magnetic Field by Permanent Magnets

First, the total number of permanent magnets has to be defined and the type selected. Options are cuboid, sphere, cylinder and conic.

NumOfPermanentMagnets = 1
PermanentMagnet1-Type = cuboid
                        sphere
                        cylinder ! also used for hollow cylinders
                        conic

All options require the input of a base/origin vector, a number of discretization nodes (results in a different number of total points depending on the chosen geometry) and a magnetisation in [A/m]

PermanentMagnet1-BasePoint = (/0.,0.,0./)
PermanentMagnet1-NumNodes = 10
PermanentMagnet1-Magnetisation = (/0.,0.,1./)

The geometries require different input parameters given below

! Three vectors spanning the cuboid
PermanentMagnet1-BaseVector1 = (/1.,0.,0./)
PermanentMagnet1-BaseVector2 = (/0.,1.,0./)
PermanentMagnet1-BaseVector3 = (/0.,0.,1./)
! Radius required for a spherical, cylindrical and conical magnet
PermanentMagnet1-Radius = 1.
! Height vector required for a cylindrical and conical magnet
PermanentMagnet1-HeightVector = (/0.,0.,1./)
! Second radius only required for a conical magnet or a hollow cylinder with inner radius
! 'Radius2' and outer radius "Radius1'
PermanentMagnet1-Radius2 = 1.

4.9.2.2. Magnetic Field by Coils

The total number of coils and the respective type of the cross-section (linear,circle,rectangle,custom) is defined by

NumOfCoils = 1
Coil1-Type = linear
             circle
             rectangle
             custom

All options require the input of a base/origin vector, a length vector (vector normal to the cross-section of the coil) and the current in [A]

Coil1-BasePoint = (/0.0,0.0,0.0/)
Coil1-LengthVector = (/0.0,1.0,0.0/)
Coil1-Current = 1.

The first option linear represents a simple linear conductor (e.g. a straight wire) and requires only the input of a number of discretization points

Coil1-NumNodes = 5

The other three types, which are actually coils, are described by the number of loops and the number of discretization points per loop

Coil1-LoopNum = 10
Coil1-PointsPerLoop = 10

The cross-section of the coil is defined in a plane normal to the -LengthVector. A circular coil cross-section requires simply the input of a radius whereas a rectangular coil cross-section is spanned by two vectors (-RectVec1 and -RectVec2) and an additional vector, which must be orthogonal to the -LengthVector to define the orientation of the cross-section (-AxisVec1). In these two cases, the base/origin vector defines the middle point of the cross-section.

! Circular coil cross-section
Coil1-Radius = 1.
! Rectangular coil cross-section
Coil1-RectVec1 = (/1.0,0.0/)
Coil1-RectVec2 = (/0.0,1.0/)
Coil1-AxisVec1 = (/0.0,0.0,1.0/)

The last cross-section type custom allows the definition of a cross-section as a combination of multiple linear (line) and circular (circle) segments and also requires an additional vector to define the orientation of the cross-section (-AxisVec1)

Coil1-AxisVec1 = (/0.0,0.0,1.0/)
Coil1-NumOfSegments = 3
! Linear segment defined by
Coil1-Segment1-SegmentType = line
Coil1-Segment1-NumOfPoints = 5
Coil1-Segment1-LineVector = (/1.0,1.0/)
! Circular segment connected to the previous segment
Coil1-Segment2-SegmentType = circle
Coil1-Segment2-NumOfPoints = 5
Coil1-Segment2-Radius = 1.
Coil1-Segment2-Phi1 = 90.
Coil1-Segment2-Phi2 = 0.
! Linear segment connected to the previous segment, closing the cross-section
Coil1-Segment3-SegmentType = line
Coil1-Segment3-NumOfPoints = 5
Coil1-Segment3-LineVector = (/-2.0,0.0/)

The -NumOfPoints controls the number of discretization points per segment. A linear segment is simply described by a vector in the cross-section plane. The circular segment is defined by a radius and the initial as well as final angle of the segment. It should be noted that the base point defines the start of the first segment as opposed to the circular and rectangular cross-sections, where it is the middle point of the cross-section.

4.9.2.3. Time-dependent Magnetic Coils

A time-dependent magnetic field can be created by a time-varying electric current running through a coil. Time-dependent coils can be combined with an arbitrary number of permanent magnets and coils (with a constant current). Currently, all time-dependent coils must use the same frequency but can have different phases. The time-dependent settings are required in addition to the ones used for a standard coil

Coil1-TimeDepCoil      = T
Coil1-CurrentFrequency = 1e6
Coil1-CurrentPhase     = 0.0
nTimePoints            = 11

where the frequency and phase of the sin function that is used for the electric current as well as the number of points in time for the interpolation of the current is required. In piclas, times between two interpolation points are determined by linear interpolation from the stored solution.