API Reference

bfieldtools – Main package

bfieldtools:

Surface mesh field calculations

bfieldtools.mesh_conductor:

Contains a class used for wrapping a mesh (in the form of a Trimesh object) together with some convenient functions and properties.

MeshConductor([verts, tris, mesh_file, …])	Class that is used for surface mesh field calculations.
CouplingMatrix(parent, function)	General-use class that contains a data array (a coupling matrix) and a bookkeeping list of computed points.
StreamFunction(input_array[, mesh_conductor])	Class for representing stream function(s) on a MeshConductor

Surface mesh calculus

bfieldtools.mesh_calculus:

Contains functions for computing vector calculus quantities on triangle surface meshes. These include the gradient, rotated gradient, divergence, curl, Laplacian and mass matrices.

laplacian_matrix(mesh[, material_param])	Sparse Laplace-Beltrami operator.
mass_matrix(mesh[, lumped])	Computes mass matrix of a mesh.
gradient_matrix(mesh[, rotated])	Calculate a (rotated) gradient matrix for hat basis functions (stream functions) in a mesh.
gradient(vals, mesh[, rotated])	Applies mesh (rotated) gradient matrix operator on vector that is defined in the vertex locations of the mesh.
divergence_matrix(mesh)	Divergence of tangential vector field on mesh faces as a linear mapping.
divergence(vecs, mesh)	Divergence mapping applied to tangential vector field ‘vecs’
curl_matrix(mesh)	Adjoint curl of tangential vector field.
curl(vecs, mesh)	Curl applied to tangential vector field

Mesh impedance

bfieldtools.mesh_impedance:

Contains functions for computing the resistance and inductance matrices of triangle surface meshes. Includes both self- and mutual-inductance.

resistance_matrix(mesh, sheet_resistance)	Resistance matrix of a mesh.
self_inductance_matrix(mesh[, Nchunks, …])	Calculate a self inductance matrix for hat basis functions (stream functions) in a mesh.
mutual_inductance_matrix(mesh1, mesh2[, …])	Calculate a mutual inductance matrix for hat basis functions (stream functions) between two surface meshes.
mesh2line_mutual_inductance(mesh, line_vertices)	Mutual inductance of a closed line segment loop (last segment connecting to first) and a triangle mesh.

Stream function magnetic couplings

bfieldtools.mesh_magnetics:

Contains functions for calculating the coupling of surface current density in a triangle mesh to magnetic field as well as scalar and vector potentials.

magnetic_field_coupling(mesh, r[, Nchunks, …])	Computes the coupling matrix which gives the magnetic field at target points due to currents (stream function) on a surface mesh.
magnetic_field_coupling_analytic(mesh, r[, …])	Computes the coupling matrix which gives the magnetic field at target points due to currents (stream function) on a surface mesh using analytical formulas.
scalar_potential_coupling(mesh, r[, …])	Coupling matrix from a stream function on a mesh to scalar potential using analytic integrals.
vector_potential_coupling(mesh, r[, …])	Compute vector potential coupling matrices from a linear stream function on a mesh using analytic integrals.

Line currents

bfieldtools.line_conductor:

This module includes a convenience class for working with polyline currents

LineConductor([loops, mesh, scalars])

Class that inherits Trimesh.path.Path3D for handling discretized current loops.

bfieldtools.line_magnetics:

Functions for working with current polylines, e.g. for calculating the magnetic field and potentials as well as the inductance

Convex optimization of stream functions

bfieldtools.coil_optimize:

Includes files for coil optimization (stream function optimization) using either a numerical solver or regularized least squares

optimize_streamfunctions(mesh_conductor, …)	Quadratic optimization of coil stream function according to a specified objective.
optimize_lsq(mesh_conductor, …[, reg, …])	Optimization of coil stream function according to a specified objective using least-squares.
cvxpy_solve_qp(P, G, h[, solver, tolerance])	Bare-bones quadratic programming solver function for CVXPY.
cvxopt_solve_qp(P, q[, G, h, A, b, tolerance])	Use cvxopt (without CVXPY wrapper) for quadratic programming.

Analytical integrals for fields and potentials

bfieldtools.integrals:

Analytic integral for vectorized field / potential computation

gamma0(R[, reg, symmetrize])	1/r integrals over the edges of a triangle called gamma_0 (line charge potentials).
omega(R)	Calculate the solid angle of a triangles
triangle_potential_uniform(R, tn[, planar])	1/r potential of a uniform triangle
triangle_potential_approx(Rcenters, ta[, reg])	1/r potential of a uniform triangle using centroid approximation
potential_dipoles(R, face_normals, face_areas)	Approximate the potential of linearly varying dipole density by
potential_vertex_dipoles(R, vertex_normals, …)	Approximate the potential of linearly varying dipole density by
triangle_potential_dipole_linear(R, tn, ta)	Potential of dipolar density with magnitude of a linear shape function on a triangle, “omega_i” in de Munck’s paper

Scalar function contouring

bfieldtools.contour:

Functions for creating contours (isolines) of a scalar function defined on a triangle mesh surface. Also contains functions for modifying the generated contours.

scalar_contour(mesh, scalars[, N_contours, …])	Computes contour loops (isolines) for a scalar function defined on a mesh.
simplify_contour(c[, min_edge, …])	Simplifies contours by merging small (short) segments and with only a small angle difference.

Spherical harmonics

bfieldtools.sphtools:

Functions for constructing real spherical harmonics (Ylms), their gradients and related magnetic field ‘basis vectorfunctions’ (Wlms for r**l components, Vlms for r**(-l) components).

Uses notations and definitions by Plattner and Simons (2014; https://arxiv.org/pdf/1306.3201.pdf) and the same normalization conventions.

Integration over a surface of unit sphere is used as the inner product <C,D> = int C dot D dOmega.

Also has many of functions for spherical <-> cartesian transformations.

lpmn_em(l, m, x)	Computes associated Legendre function (Plm) of the first kind of order m and degree l.
ylm(l, m, theta, phi)	Real spherical harmonics as defined by Plattner and Simons (2014); see Eqs.
Wlm(l, m, theta, phi)	Vector basis function (Wlm) for r**l component of the magnetic field.
Vlm(l, m, theta, phi)	Vector basis function (Vlm) for r**(-l) component of the magnetic field.
basis_potentials(p, lmax[, normalization, R])	Computes inner/outer basis functions for magnetic scalar potential.
basis_fields(p, lmax[, normalization, R])	Computes magnetic field of each sph coefficient.
potential(p, acoeffs, bcoeffs, lmax[, …])	Computes magnetic scalar potential from the sph coefficients.
field(p, acoeffs, bcoeffs, lmax[, …])	Computes magnetic field at some point from the sph coefficients.
compute_sphcoeffs_mesh(mesh, lmax[, …])	Computes multipole moment (spherical harmonics coefficient) transformation from the mesh.

Surface harmonics

bfieldtools.suhtools:

Tools for calculating the surface harmonic representation of the magnetic field. Surface harmonics can represent of any stream function as a series.

Surface harmonics == Laplace-Beltrami eigenfunctions

SuhBasis(obj[, Nc, boundary_condition, …])

Class for representing magnetic field using surface harmonics

Thermal noise

bfieldtools.thermal_noise:

Contains functions for computing thermal noise in conductive thin objects.

compute_current_modes(obj, T, resistivity, …)	Calculates the (AC or DC) Johnson noise current modes on the conducting surface.
noise_covar(B_coupling, vl[, Nmodes])	Calculates (AC or DC) magnetic noise covariance along x, y and z from the modes vl.
noise_var(B_coupling, vl[, Nmodes])	Calculates (AC or DC) magnetic noise variance along x, y and z from the modes vl.
noise_covar_dir(B_coupling, vl[, Nmodes])	Calculates (AC or DC) magnetic noise covariance between x, y and z directions from the modes vl.
visualize_current_modes(mesh, vl, Nmodes, scale)	Visualizes current modes up to Nmodes.

Visualization and plotting

bfieldtools.viz:

Visualization functions tailored for bfieldtools. Mainly wrappers and convenience helpers around mayavi and matplotlib functions

plot_mesh(mesh[, cull_front, cull_back, …])	Plot the mesh surface in mayavi.
plot_3d_current_loops(current_loops[, …])	Plot current loops (e.g.
plot_cross_section(X, Y, data[, axes, cmap, …])	Plot scalar data on a plane
plot_data_on_vertices(mesh, data[, figure, …])	Plot scalar data defined on the vertices of a mesh.
plot_data_on_faces(mesh, data[, figure, …])	Plot any data determined on the faces of a mesh

Utilities

bfieldtools.utils:

This module contains miscellaneous utility functions used across bfieldtools.

combine_meshes(meshes)	Combine two or more non-overlapping Trimesh meshes without any dependency requirements.
get_quad_points(verts, tris[, method, …])	Get quad points and weights from quadrature rules implemented in quadpy
get_line_quad_points(line_vertices[, …])	Get quad points and weights from quadrature rules implemented in quadpy
dual_areas(tris, ta)	Calculate (dual) areas for each node in inds
find_mesh_boundaries(mesh)	Finds the open boundaries of a mesh by finding the edges that only belong to a single triangle.
load_example_mesh(mesh_name[, process])	Convenience function used load example meshes included with the package
fix_normals(mesh[, origin])	Attempts to fix face windings and normals such that normals are always “pointing out” from the origin.
inner2vert(mesh, inner_vertices, holes)	Linear mapping of the inner (free) weights in the stream function discretization to weights in all vertices
vert2inner(mesh, inner_vertices, holes)	Linear mapping of the all weights in the stream function discretization to inner (free) weights
MeshProjection(mesh, quad_degree)	Class for constructing projection of an arbitrary function to the hat functions of the given mesh