4.7. 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) 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 (HOPR) mesh file. The following two sections give an overview of using the different methods.

4.7.1. Variable External Field

One-, two- and three-dimensional magnetic fields can be used as fixed background fields for certain time discretization methods (full Maxwell time discs and the Poisson Boris-Leapfrog scheme) 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

Three 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

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 is csv-based data in the form (the delimiter is actually not a comma)

-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”.

Three-dimensional fields must be supplied in the following format

x1 y1 z1 Bx1 By1 Bz1
x2 y2 z2 Bx2 By2 Bz2
x3 y3 z3 Bx3 By3 Bz3
x4 y4 z4 Bx4 By4 Bz4
x5 y5 z5 Bx5 By5 Bz5
....

where the data (dataset is labelled “data” in the .h5 file) is sorted in lines in ascending coordinates. For everything to work, the order must be like this

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 first the \(x\)-coordinate changes, then \(y\) and finally the \(z\).

4.7.2. superB

The magnetic field resulting from certain types of coils and permanent magnets can be calculated during the initialization within PICLas or with the standalone tool superB (see Section Compiler options for compilation), which can be used to solely 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 previously calculated background field. 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 [29] are presented.

4.7.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.7.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.7.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.