Skip to main content

Computing a magnetic field with the BEM solver

Status: beta. The Python interface of the field solver ships with release 26. Its keywords follow the classes BEM_Solver and BEM_Boundary and can still change within the 2.x series. The solver itself is the same one the bem binary uses.

A plasma case with a fixed magnetic assembly (permanent magnets, iron yoke) needs the static magnetic field of that assembly. It is computed once per geometry by a boundary element method, written to a binary file and then read by the simulation. In the parameter file route the setup is a .bem file plus the bem binary (see Magnetic fields from a fixed assembly); from Python the same solver is available as PICMC.BEM_Solver, and the .bem file is replaced by BEM_Boundary objects.

Computing the field and simulating the plasma remain two separate runs: the solver writes a field file, and the simulation reads it with read_magnetic_field (see Loading an external field).

How a run is organised​

The solver uses the same two-program pattern as Sim: exactly one Python rank drives the solver, and the bem workers do the computation - including the MPI option --bind-to none and the "one task more than workers" rule, see How the two processes cooperate.

export PICMCPATH=/path/to/picmc-26
export PYTHONPATH=$PICMCPATH/lib
export LD_LIBRARY_PATH=$PICMCPATH/lib:/lib64:$LD_LIBRARY_PATH

mpiexec --bind-to none -np 1 python3 magnet_bem.py \
: -np 8 $PICMCPATH/bin/bem

On a SLURM cluster the run is submitted with the Python wrapper, and one option selects the worker program: -b makes the -n workers the bem binary instead of picmc.

python3 $PICMCPATH/py/pysubmit.py magnet_bem.py -n 8 -c IST_EPYC -b -t 1:00:00
Do not forget the -b flag

-b is not optional here: without it the wrapper starts picmc workers. Those do not answer the solver's messages: the driving rank waits in its first receive, the workers wait for a command that never comes, and <script>-out.txt stops after its first two lines. The job then holds its nodes until the time limit without a single progress line.

A minimal script​

import PICMC

geo = PICMC.Geometry(
mesh_file = "magbar90.msh",
mesh_unit = 1e-3,
BB = (
(-37.5, 505.0, 180.0), # -x, -y, -z
( 37.5, 1195.0, 540.0) # +x, +y, +z
),
NX = [25],
NY = [23] * 10,
NZ = [10] * 12
)

R = 1.24 # remanence of the magnets in T
codecs = {
"M1centBottom": PICMC.BEM_Boundary(icodec = 183, type = "interface",
val = -R, domain = 1, neighbourdomain = 0),
"M1centTop": PICMC.BEM_Boundary(icodec = 184, type = "interface",
val = R, domain = 1, neighbourdomain = 0),
"M1centSide": PICMC.BEM_Boundary(icodec = 191, type = "interface",
val = 0, domain = 1, neighbourdomain = 0),
# ... one entry per physical surface of the magnet mesh
"M1yoke": PICMC.BEM_Boundary(icodec = 192, type = "interface",
val = 0, domain = 2, neighbourdomain = 0)
}

solver = PICMC.BEM_Solver(
Geometry = geo,
Domains = [1, 1.05, 1000],
Codecs = codecs
)

try:
solver.init()
solver.solvepoisson(batchname = "magbar90")
solver.write_vectorfield("BEM_field.pos")
solver.write_scalarfield("BEM_potential.pos")
solver.write_binaryfield("B-Field.bin")
solver.write_textfield("B-Field.txt")
solver.exit()
except Exception:
import traceback
traceback.print_exc()
solver.exit()

solver.exit() in the handler has the same reason as in a case script: an exception leaves the workers waiting.

Keyword arguments​

classkeywords
BEM_Solverrequired: Geometry, Domains, Codecs
BEM_Boundaryrequired: icodec, type, val, domain, neighbourdomain

Geometry is an ordinary PICMC.Geometry, but it describes the magnet mesh, not the plasma mesh: mesh_file and mesh_unit of the magnet geometry, plus BB, NX, NY and NZ of the box the field is evaluated in. BORDER_TYPES is not needed - the boundary description of the field solver is Codecs.

Domains is the list of relative permeabilities; Codecs maps a name to one BEM_Boundary per physical surface of the magnet mesh. The names are free, icodec is not: it is the tag of the physical surface in the mesh, and it has to match exactly (see the mesh).

What the entries mean​

  • type = "interface" marks a surface between two magnetic materials. val is the remanent flux density in T along the surface normal, so the sign gives the magnetisation direction: the pole faces of a bar magnet get +R and -R, the lateral surface gets 0.
  • type = "dirichlet" fixes the magnetic scalar potential to val; type = "neumann" sets its normal derivative to val. A coil described as a surface current uses a neumann surface and two dirichlet faces at +1 and -1 (see Coil current computation with BEM).
  • domain and neighbourdomain are indices into Domains, not mesh tags. 0 is the surrounding vacuum, 1 the magnet material and 2 the yoke in the example above. A codec with domain = neighbourdomain or neighbourdomain = 0 needs no second material.
  • Every physical surface of the magnet mesh needs an entry, including the ones that contribute nothing (val = 0). Surfaces left out are not constrained.

The mesh​

The magnet assembly gets its own Gmsh mesh, generated like any other (see From STEP to a Gmsh mesh). Only the surfaces of the assembly are meshed and given physical groups: the magnet mesh of the example is nothing but the 20 surfaces of the two bar magnets and their yokes, without an air volume and without an outer boundary. Their tags become the icodec values, and they are independent of the numbering of the plasma mesh - it is a different file with its own groups.

Output​

methodresult
write_binaryfield(filename)the binary field for read_magnetic_field(filename, file_type = "checkpoint")
write_textfield(filename)the same field as text, for read_magnetic_field(filename, file_type = "external_unstructured")
write_vectorfield(filename)B as a .pos view, for a check in Gmsh or ParaView
write_scalarfield(filename)the magnetic scalar potential as a .pos view
write_boundaryconditions(qfile, ufile, jfile)the Neumann and Dirichlet boundary conditions and the ICP source field as .pos; all three names are optional, without a name that file is not written

solvepoisson(batchname = "name") takes the name of the run. The argument corresponds to Batchfile in the parameter file and is currently only accepted, not evaluated - it does not change the result.

Reusing the field on a different plasma mesh​

write_binaryfield writes the field quad by quad, in the layout of the solver's Geometry. A plasma case that resolves the field differently - other BB, other NX, NY, NZ - cannot read that binary. For that case write_textfield writes the same field points as plain text, one line per point:

x y z Bx By Bz

That is the format of the unstructured external field file, so the plasma case loads it with BFIELDFILE or read_magnetic_field(filename, "external_unstructured") and interpolates it onto its own grid. The two cases are then independent: the field solver only has to cover the volume, not the resolution.

Two conditions come from the reader and not from the solver. The field points have to span the whole simulation volume, because the reader interpolates between them but never extrapolates; and the coordinate columns are compared with the nodes of the plasma mesh in metres, while write_textfield divides them by the mesh_unit of the solver's geometry - the same scaling the .pos views of the run use. Check the numbers when the magnet mesh is not in metres.

In the parameter file route the text file is written together with the binary: write_binaryfield in the .bem block writes B-Field.txt next to B-Field.bin.

Differences to the parameter file route​

  • No .bem file. The block Boundary NAME = {icodec = ...; type = ...; val = ...; domain = ...; neighbourdomain = ...;}; becomes one BEM_Boundary with the same five keywords, Domains and R become the Domains list and a plain Python variable.
  • BEMMESH in the parameter file has no counterpart; the magnet mesh is the mesh_file of the solver's Geometry.
  • The solver is a separate script, not part of the case script. Field computation and plasma run stay two runs, as with bem and picmc.