cfsem 2.0.4__cp39-none-win_amd64.whl

cfsem/__init__.py

@@ -0,0 +1,536 @@
+"""Physics calculations shared between various magnet models"""
+
+from typing import Tuple
+import numpy as np
+from numpy.typing import NDArray
+from interpn import MulticubicRectilinear
+
+from cfsem.types import Array3xN
+
+from cfsem.bindings import (
+    flux_circular_filament,
+    flux_density_biot_savart,
+    flux_density_circular_filament,
+    gs_operator_order2,
+    gs_operator_order4,
+    inductance_piecewise_linear_filaments,
+    filament_helix_path,
+    rotate_filaments_about_path,
+)
+
+from ._cfsem import ellipe, ellipk
+
+MU_0 = 4.0 * np.pi * 1e-7 * (1.0 + 5.5e-10)
+"""
+Vacuum permeability with slight correction from latest measurements per NIST CODATA 2019 (SP-961),
+https://www.physics.nist.gov/cuu/pdf/wall_2018.pdf .
+"""
+
+__all__ = [
+    "flux_circular_filament",
+    "flux_density_biot_savart",
+    "flux_density_circular_filament",
+    "gs_operator_order2",
+    "gs_operator_order4",
+    "filament_helix_path",
+    "inductance_piecewise_linear_filaments",
+    "self_inductance_piecewise_linear_filaments",
+    "mutual_inductance_piecewise_linear_filaments",
+    "flux_density_ideal_solenoid",
+    "self_inductance_lyle6",
+    "mutual_inductance_of_circular_filaments",
+    "mutual_inductance_of_cylindrical_coils",
+    "filament_coil",
+    "self_inductance_circular_ring_wien",
+    "self_inductance_annular_ring",
+    "self_inductance_distributed_axisymmetric_conductor",
+    "ellipe",
+    "ellipk",
+    "rotate_filaments_about_path",
+]
+
+
+def self_inductance_piecewise_linear_filaments(xyzp: Array3xN) -> float:
+    """
+    Estimate the self-inductance of one piecewise-linear current filament.
+
+    Uses Neumann's Formula for the mutual inductance of arbitrary loops
+    for non-self-pairings, zeroes-out the contributions from self-pairings
+    to resolve the thin-filament self-inductance singularity, and replaces the
+    segment self-inductance term with an analytic value from [3].
+
+    Assumes:
+
+    * Thin, well-behaved filaments
+    * Uniform current distribution within segments
+        * Low frequency operation; no skin effect
+          (which would reduce the segment self-field term)
+    * Vacuum permeability everywhere
+    * Each filament has a constant current in all segments
+      (otherwise we need an inductance matrix)
+
+    References:
+        [1] “Inductance,” Wikipedia. Dec. 12, 2022. Accessed: Jan. 23, 2023. [Online].
+            Available: <https://en.wikipedia.org/w/index.php?title=Inductance>
+
+        [2] F. E. Neumann, “Allgemeine Gesetze der inducirten elektrischen Ströme,”
+            Jan. 1846, doi: [10.1002/andp.18461430103](https://doi.org/10.1002/andp.18461430103)
+
+        [3] R. Dengler, “Self inductance of a wire loop as a curve integral,”
+            AEM, vol. 5, no. 1, p. 1, Jan. 2016, doi: [10.7716/aem.v5i1.331](https://doi.org/10.7716/aem.v5i1.331)
+
+    Args:
+        xyzp: [m] 3xN point series describing the filament
+
+    Returns:
+        [H] Scalar self-inductance
+    """
+    x, y, z = xyzp
+    xyzfil = (x[:-1], y[:-1], z[:-1])
+    dlxyzfil = (x[1:] - x[:-1], y[1:] - y[:-1], z[1:] - z[:-1])
+
+    self_inductance = inductance_piecewise_linear_filaments(
+        xyzfil, dlxyzfil, xyzfil, dlxyzfil, True
+    )  # [H]
+
+    return self_inductance  # [H]
+
+
+def mutual_inductance_piecewise_linear_filaments(
+    xyz0: Array3xN,
+    xyz1: Array3xN,
+) -> float:
+    """
+    Estimate the mutual inductance between two piecewise-linear current filaments.
+
+    Uses Neumann's Formula for the mutual inductance of arbitrary loops, which is
+    originally from [2] and can be found in a more friendly format on wikipedia.
+
+    Assumes:
+
+    * Thin, well-behaved filaments
+    * Vacuum permeability everywhere
+    * Each filament has a constant current in all segments
+      (otherwise we need an inductance matrix)
+    * All segments between the two filaments are distinct; no identical pairs
+
+    References:
+        [1] “Inductance,” Wikipedia. Dec. 12, 2022. Accessed: Jan. 23, 2023. [Online].
+            Available: <https://en.wikipedia.org/w/index.php?title=Inductance>
+
+        [2] F. E. Neumann, “Allgemeine Gesetze der inducirten elektrischen Ströme,”
+            Jan. 1846, doi: [10.1002/andp.18461430103](https://doi.org/10.1002/andp.18461430103)
+
+    Args:
+        xyz0: [m] 3xN point series describing the first filament
+        xyz1: [m] 3xM point series describing the second filament
+
+    Returns:
+        [H] Scalar mutual inductance between the two filaments
+    """
+
+    x0, y0, z0 = xyz0
+    xyzfil0 = (x0[:-1], y0[:-1], z0[:-1])
+    dlxyzfil0 = (x0[1:] - x0[:-1], y0[1:] - y0[:-1], z0[1:] - z0[:-1])
+
+    x1, y1, z1 = xyz1
+    xyzfil1 = (x1[:-1], y1[:-1], z1[:-1])
+    dlxyzfil1 = (x1[1:] - x1[:-1], y1[1:] - y1[:-1], z1[1:] - z1[:-1])
+
+    inductance = inductance_piecewise_linear_filaments(
+        xyzfil0, dlxyzfil0, xyzfil1, dlxyzfil1, False
+    )  # [H]
+
+    return inductance  # [H]
+
+
+def flux_density_ideal_solenoid(
+    current: float, num_turns: float, length: float
+) -> float:
+    """
+    Axial B-field on centerline of an ideal (infinitely long) solenoid.
+
+    This calc converges reasonably well for coil L/D > 20.
+
+    Args:
+        current: [A] solenoid current
+        num_turns: [#] number of conductor turns
+        length: [m] length of winding pack
+
+    Returns:
+        [T] B-field on axis (in the direction aligned with the axis)
+    """
+    b_on_axis = MU_0 * num_turns * current / length
+    return b_on_axis  # [T]
+
+
+def self_inductance_lyle6(r: float, dr: float, dz: float, n: float) -> float:
+    """
+    Self-inductance of a cylindrically-symmetric coil of rectangular
+    cross-section, estimated to 6th order.
+
+    References:
+        [1] T. R. Lyle,
+        “IX. On the self-inductance of circular coils of rectangular section,”
+        Philosophical Transactions of the Royal Society of London.
+        Series A, Containing Papers of a Mathematical or Physical Character,
+        vol. 213, no. 497-508, pp. 421-435, Jan. 1914, doi: [10.1098/rsta.1914.0009](https://doi.org/10.1098/rsta.1914.0009)
+
+    Args:
+        r: [m] radius, coil center
+        dr: [m] radial width of coil
+        dz: [m] cylindrical height of coil
+        n: number of turns
+
+    Returns:
+        [H] self-inductance
+    """
+
+    # Guarantee 64-bit floats needed for 6th-order shape term
+    a = np.float64(r)
+    b = np.float64(dz)
+    c = np.float64(dr)
+
+    # Build up reusable terms for calculation of shape parameter
+    d = np.sqrt(b**2 + c**2)  # [m] diagonal length
+    u = ((b / c) ** 2) * 2 * np.log(d / b)
+    v = ((c / b) ** 2) * 2 * np.log(d / c)
+    w = (b / c) * np.arctan(c / b)
+    ww = (c / b) * np.arctan(b / c)
+
+    bd2 = (b / d) ** 2
+    cd2 = (c / d) ** 2
+    da2 = (d / a) ** 2
+    ml = np.log(8 * a / d)
+
+    f = (
+        ml
+        + (1 + u + v - 8 * (w + ww)) / 12.0  # 0th order in d/a
+        + (
+            da2
+            * (
+                cd2 * (221 + 60 * ml - 6 * v)
+                + 3 * bd2 * (69 + 60 * ml + 10 * u - 64 * w)
+            )
+        )
+        / 5760.0  # 2nd order
+        + (
+            da2**2
+            * (
+                2 * cd2**2 * (5721 + 3080 * ml - 345 * v)
+                + 5 * bd2 * cd2 * (407 + 5880 * ml + 6720 * u - 14336 * w)
+                - 10 * bd2**2 * (3659 + 2520 * ml + 805 * u - 6144 * w)
+            )
+        )
+        / 2.58048e7  # 4th order
+        + (
+            da2**3
+            * (
+                3 * cd2**3 * (4308631 + 86520 * ml - 10052 * v)
+                - 14 * bd2**2 * cd2 * (617423 + 289800 * ml + 579600 * u - 1474560 * w)
+                + 21 * bd2**3 * (308779 + 63000 * ml + 43596 * u - 409600 * w)
+                + 42 * bd2 * cd2**2 * (-8329 + 46200 * ml + 134400 * u - 172032 * w)
+            )
+        )
+        / 1.73408256e10  # 6th order
+    )  # [nondim] shape parameter
+
+    self_inductance = MU_0 * (n**2) * a * f
+
+    return self_inductance  # [H]
+
+
+def mutual_inductance_of_circular_filaments(rzn1: NDArray, rzn2: NDArray) -> float:
+    """
+    Analytic mutual inductance between a pair of ideal cylindrically-symmetric coaxial filaments.
+
+    This is equivalent to taking the flux produced by each circular filament from
+    either collection of filaments to the other. Mutual inductance is reflexive,
+    so the order of the inputs is not important.
+
+    Args:
+        rzn1 (array): 3x1 array (r [m], z [m], n []) coordinates and number of turns
+        rzn2 (array): 3x1 array (r [m], z [m], n []) coordinates and number of turns
+
+    Returns:
+        float: [H] mutual inductance
+    """
+
+    m = mutual_inductance_of_cylindrical_coils(
+        rzn1.reshape((3, 1)), rzn2.reshape((3, 1))
+    )
+
+    return m  # [H]
+
+
+def mutual_inductance_of_cylindrical_coils(f1: NDArray, f2: NDArray) -> float:
+    """
+    Analytical mutual inductance between two coaxial collections of ideal filaments.
+
+    Each collection typically represents a discretized "real" cylindrically-symmetric
+    coil of rectangular cross-section, but could have any cross-section as long as it
+    maintains cylindrical symmetry.
+
+    Args:
+        f1: 3 x N array of filament definitions like (r [m], z [m], n [])
+        f2: 3 x N array of filament definitions like (r [m], z [m], n [])
+
+    Returns:
+        [H] mutual inductance of the two discretized coils
+    """
+    r1, z1, n1 = f1
+    r2, z2, n2 = f2
+
+    # Using n2 as the current per filament is equivalent to examining a 1A reference current,
+    # which gives us the flux per amp (inductance)
+    m = np.sum(
+        n1 * flux_circular_filament(n2, r2, z2, r1, z1)
+    )  # [H] total mutual inductance
+
+    return m  # [H]
+
+
+def filament_coil(
+    r: float, z: float, w: float, h: float, nt: float, nr: int, nz: int
+) -> NDArray:
+    """
+    Create an array of filaments from coil cross-section, evenly spaced
+    _inside_ the winding pack. No filaments are coincident with the coil surface.
+
+    Args:
+        r: [m] radius, coil center
+        z: [m] axial position, coil center
+        w: [m] width of coil pack
+        h: [m] height of coil pack
+        nt: turns
+        nr: radial discretizations
+        nz: axial discretizations
+
+    Returns:
+        (nr*nz) x 3, (r,z,n) of each filament
+    """
+
+    # Build a 2D mesh of points evenly spaced in the interior of the bounding rectangle
+    rs = np.linspace(r - w * (nr - 1) / nr / 2, r + w * (nr - 1) / nr / 2, nr)  # [m]
+    zs = np.linspace(z - h * (nz - 1) / nz / 2, z + h * (nz - 1) / nz / 2, nz)  # [m]
+    rmesh, zmesh = np.meshgrid(rs, zs, indexing="ij")  # [m]
+
+    # Number of turns attributed to each point is not necessarily an integer
+    n = np.full_like(rmesh.flatten(), float(nt) / (nr * nz))
+
+    # Pack filament locations and number of turns into an array together
+    filaments = np.dstack([rmesh.flatten(), zmesh.flatten(), n]).reshape(nr * nz, 3)
+
+    return filaments  # [m], [m], [dimensionless]
+
+
+def self_inductance_circular_ring_wien(
+    major_radius: NDArray, minor_radius: NDArray
+) -> NDArray:
+    """
+    Wien's formula for the self-inductance of a circular ring
+    with thin circular cross section.
+
+    Uses equation 7 from reference [1].
+
+    References:
+        [1] E Rosa and L Cohen, "On the Self-Inductance of Circles,"
+        Bulletin of the Bureau of Standards, 1908.
+        [Online]. Available:
+        <https://nvlpubs.nist.gov/nistpubs/bulletin/04/nbsbulletinv4n1p149_A2b.pdf>
+
+    Args:
+        major_radius: [m] Major radius of the ring.
+        minor_radius: [m] Radius of the ring's cross section.
+
+    Returns:
+        [H] self-inductance
+    """
+    ar = major_radius / minor_radius  # [], a / rho, dimensionless
+    ra2 = (minor_radius / major_radius) ** 2  # [], (rho / a)^2, dimensionless
+    # Equation 7 in Rosa & Cohen lacks the factor of 1e-7
+    # because it is not in SI base units.
+    self_inductance = (
+        MU_0 * major_radius * ((1 + 0.125 * ra2) * np.log(8 * ar) - 0.0083 * ra2 - 1.75)
+    )  # [H]
+    return self_inductance  # [H]
+
+
+def self_inductance_distributed_axisymmetric_conductor(
+    current: float,
+    grid: Tuple[NDArray, NDArray],
+    mesh: Tuple[NDArray, NDArray],
+    b_part: Tuple[NDArray, NDArray],
+    psi_part: NDArray,
+    mask: NDArray,
+    edge_path: Tuple[NDArray, NDArray],
+) -> Tuple[float, float, float]:
+    """
+    Calculation of a distributed conductor's self-inductance from two components:
+
+    * External inductance: the portion related to the poloidal flux exactly at the conductor edge
+    * Internal inductance: the portion related to the poloidal magnetic field inside the conductor,
+      where the filamentized method used for coils does not apply due to the parallel arrangement
+      and variable current density.
+
+    Note: the B-field and flux inputs are _not_ the total from all sources - they are only the
+    contribution from the distributed conductor under examination.
+
+    This calculation was developed for use with tokamak plasmas, but applies similarly to
+    other kinds of distributed axisymmetric conductor.
+
+    Assumptions:
+
+    * Cylindrically-symmetric, distributed, single-winding, contiguous conductor
+    * No high-magnetic-permeability materials in the vicinity
+    * Isopotential on the edge contour
+        * This is slightly less restrictive than isopotential on the section,
+          but notably does _not_ allow the calc to be used with, for example,
+          large, shell conductors where different regions are meaningfully
+          independent of each other.
+    * Conductor interior does not touch the edge of the computational domain
+        * At least one grid cell of padding is needed to support finite differences
+
+    References:
+        [1] S. Ejima, R. W. Callis, J. L. Luxon, R. D. Stambaugh, T. S. Taylor, and J. C. Wesley,
+            “Volt-second analysis and consumption in Doublet III plasmas,”
+            Nucl. Fusion, vol. 22, no. 10, pp. 1313-1319, Oct. 1982,
+            doi: [10.1088/0029-5515/22/10/006](https://doi.org/10.1088/0029-5515/22/10/006)
+
+        [2] J. A. Romero and J.-E. Contributors, “Plasma internal inductance dynamics in a tokamak,”
+            arXiv.org. Accessed: Dec. 21, 2023. [Online]. Available: https://arxiv.org/abs/1009.1984v1
+            doi: [10.1088/0029-5515/50/11/115002](https://doi.org/10.1088/0029-5515/50/11/115002)
+
+        [3] J. T. Wai and E. Kolemen, “GSPD: An algorithm for time-dependent tokamak equilibria design.”
+            arXiv, Jun. 22, 2023. Accessed: Sep. 15, 2023. [Online]. Available: https://arxiv.org/abs/2306.13163
+            doi: [10.48550/arXiv.2306.13163](https://doi.org/10.48550/arXiv.2306.13163)
+
+    Args:
+        current: [A] total toroidal current in this conductor
+        grid: [m] (1 X nr) grids of (R coords, Z coords)
+        mesh: [m] (nr X nz) meshgrids of (R coords, Z coords)
+        b_part: [T] (nr X nz) Flux density (R-component, Z-component) due to this conductor
+        psi_part: [V-s] or [T-m^2] (nr X nz) this conductor's poloidal flux field
+        mask: (nr X nz) positive mask of the conductor's interior region
+        edge_path: [m] (2 x N) closed (r, z) path along conductor edge
+
+    Returns:
+        (Lt, Li, Le) Total, internal, and external self-inductance components
+    """
+    # Unpack
+    rgrid, zgrid = grid  # [m]
+    rmesh, zmesh = mesh  # [m]
+    br, bz = b_part  # [T]
+
+    # Set up
+    nr = rgrid.size
+    nz = zgrid.size
+    psi_interpolator = MulticubicRectilinear.new([rgrid, zgrid], psi_part.flatten())
+
+    # Same-length diffs assuming last grid cell is the same size
+    # as the previous one. In general the conductor can't touch the
+    # edge of the computational domain without breaking the solver,
+    # so it's ok to allow some potential error at the last index.
+    drmesh = np.zeros_like(rmesh)  # [m]
+    drmesh[: nr - 1, :] = np.diff(rmesh, axis=0)
+    drmesh[-1, :] = drmesh[-2, :]
+
+    dzmesh = np.zeros_like(zmesh)  # [m]
+    dzmesh[:, : nz - 1] = np.diff(zmesh, axis=1)
+    dzmesh[:, -1] = dzmesh[:, -2]
+
+    # Toroidal volume of each cell in the mesh.
+    #
+    # Ideally we'd use a two-sided difference for
+    # calculating dr and dz in order to properly handle cell volume
+    # for nonuniform grids, but (1) that's a lot of extra array handling
+    # for minimal real benefit and (2) the grid is almost always uniform
+    volmesh = 2.0 * np.pi * rmesh * drmesh * dzmesh  # [m^3]
+
+    # Stored poloidal magnetic energy inside the conductor volume.
+    #
+    # Because E ~ B^2 and B = sqrt(Br^2 + Bz^2 + Btor^2) -> B^2 = Br^2 + Bz^2 + Btor^2,
+    # the components of magnetic energy (and induction) due to a current on different axes
+    # are separable, and we can ignore the toroidal field entirely when treating the
+    # poloidal inductance.
+    #
+    # That doesn't mean there isn't store energy related to the conductor's toroidal field,
+    # only that it can be separated from the poloidal inductance.
+    wmag_pol = (1.0 / (2.0 * MU_0)) * np.sum((br**2 + bz**2) * volmesh * mask)  # [J]
+
+    # Internal inductance.
+    #
+    # Because E = (1/2) * L * I^2, we can superpose multiple inductance terms
+    # for a given current-carrying element, and say E = (1/2) * (Li + Le) * I^2 .
+    #
+    # Now that we have the internal stored magnetic energy, we can calculate
+    # the part of the self-inductance related to that energy directly.
+    internal_inductance = 2.0 * wmag_pol / current**2  # [H]
+
+    # External inductance.
+    #
+    # This is a hack based on Poynting's Theorem relating surface conditions to
+    # magnetic energy.
+    #
+    #   Do weighted average of flux along the edge contour
+    #   to adjust for the length of individual segments
+    edge_dr = np.diff(edge_path[0])  # [m]
+    edge_dz = np.diff(edge_path[1])  # [m]
+    edge_dl = (edge_dr**2 + edge_dz**2) ** 0.5  # [m] length of each segment
+    edge_length = np.sum(edge_dl)  # [m] total length of conductor limit contour
+    edge_psi = psi_interpolator.eval([x[:-1] for x in edge_path])  # [V-s]
+    edge_psi_mean = np.sum(edge_psi * edge_dl) / edge_length  # [V-s]
+    #   Take the inductance
+    external_inductance = edge_psi_mean / current  # [H]
+
+    # Total inductance.
+    total_inductance = internal_inductance + external_inductance  # [H]
+
+    return (
+        float(total_inductance),
+        float(internal_inductance),
+        float(external_inductance),
+    )
+
+
+def self_inductance_annular_ring(r: float, a: float, b: float) -> float:
+    """
+    Low-frequency self-inductance of a thick-walled tube bent in a circle.
+
+    Uses Wien's method, per the 1912 NIST handbook [1], Eqn. 64 on pg. 112,
+    with a correction to a misprint in term 5 and a unit conversion factor
+    in the final expression.
+
+    This is an approximation that drops terms of order higher than `(a/r)^2`
+    and `(b/r)^2`.
+
+    References:
+        [1] E. B. Rosa and F. W. Grover, “Formulas and tables for the calculation of mutual and self-inductance (Revised),”
+            BULL. NATL. BUR. STAND., vol. 8, no. 1, p. 1, Jan. 1912,
+            doi: [10.6028/bulletin.185](https://doi.org/10.6028/bulletin.185)
+
+    Args:
+        r: [m] major radius of loop
+        a: [m] inner minor radius (tube inside radius)
+        b: [m] outer minor radius (tube outside radius)
+
+    Returns:
+        [H] self-inductance [H]
+    """
+
+    if not ((r > 0.0) and (a > 0.0) and (b > 0.0)):
+        raise ValueError("All radii must be positive and nonzero.")
+    if not (a < b):
+        raise ValueError("Inner minor radius must be less than outer minor radius.")
+    if not (b < r):
+        raise ValueError("Outer minor radius must be less than major radius.")
+
+    term1 = (1.0 + (a**2 + b**2) / (8.0 * r**2)) * np.log(8.0 * r / b)
+    term2 = -1.75 + (2.0 * b**2 + a**2) / (32.0 * r**2)
+    term3 = -0.5 * a**2 / (b**2 - a**2)
+    term4 = (a**4 / ((b**2 - a**2) ** 2)) * (1.0 + a**2 / (8.0 * r**2)) * np.log(b / a)
+    term5 = -(a**4 + a**2 * b**2 + b**4) / (48.0 * r**2 * (b**2 - a**2))
+
+    self_inductance = MU_0 * r * (term1 + term2 + term3 + term4 + term5)  # [H]
+
+    return self_inductance  # [H]

cfsem/bindings.py

@@ -0,0 +1,362 @@
+"""
+Symmetric bindings for backend calcs.
+
+This fulfills the function of typing stubs, while also guaranteeing arrays are
+passed as contiguous and reallocating into contiguous inputs if necessary.
+"""
+
+from cfsem.types import Array3xN
+
+from numpy import ascontiguousarray, float64, zeros_like
+from numpy.typing import NDArray
+
+from ._cfsem import flux_circular_filament as em_flux_circular_filament
+from ._cfsem import flux_density_biot_savart as em_flux_density_biot_savart
+from ._cfsem import flux_density_circular_filament as em_flux_density_circular_filament
+from ._cfsem import gs_operator_order2 as em_gs_operator_order2
+from ._cfsem import gs_operator_order4 as em_gs_operator_order4
+from ._cfsem import (
+    inductance_piecewise_linear_filaments as em_inductance_piecewise_linear_filaments,
+)
+from ._cfsem import filament_helix_path as em_filament_helix_path
+from ._cfsem import rotate_filaments_about_path as em_rotate_filaments_about_path
+
+
+def flux_circular_filament(
+    ifil: NDArray[float64],
+    rfil: NDArray[float64],
+    zfil: NDArray[float64],
+    rprime: NDArray[float64],
+    zprime: NDArray[float64],
+) -> NDArray[float64]:
+    """
+    Flux contributions from some circular filaments to some observation points,
+    which happens to be the Green's function for the Grad-Shafranov solve.
+
+    This represents the integral of $\\vec{B} \\cdot \\hat{n} \\, dA$ from the z-axis to each
+    (`rprime`, `zprime`) observation location with $\\hat{n}$ oriented parallel to the z-axis.
+
+    A convenient interpretation of the flux is as the mutual inductance
+    per secondary coil current between a filament at (`rfil`, `zfil`) and a secondary
+    filament at (`rprime`, `zprime`); this can be used to get the mutual inductance
+    between two filamentized coils as the sum of I1 * I2 * flux_from_coil_1_to_coil_2.
+    Because mutual inductance is reflexive, the order of the coils can be reversed and
+    the same result is obtained.
+
+    This function is fairly well-optimized and runs about >10x faster than an
+    equivalent implementation in numpy+scipy, with lower RAM usage
+    (O(n) in number of observation locations) than what would be required
+    for a tiled implementation. Numba does not have an implementation of
+    elliptic integrals and will not accept scipy's.
+
+    Args:
+        ifil: [A] filament current
+        rfil: [m] filament R-coord
+        zfil: [m] filament Z-coord
+        rprime: [m] Observation point R-coord
+        zprime: [m] Observation point Z-coord
+
+    Returns:
+        [T-m^2] or [V-s] psi, poloidal flux at each observation point
+    """
+    ifil = ascontiguousarray(ifil)
+    rfil = ascontiguousarray(rfil)
+    zfil = ascontiguousarray(zfil)
+    rprime = ascontiguousarray(rprime)
+    zprime = ascontiguousarray(zprime)
+    psi = em_flux_circular_filament(ifil, rfil, zfil, rprime, zprime)
+    return psi  # [T-m^2] or [V-s]
+
+
+def flux_density_circular_filament(
+    ifil: NDArray[float64],
+    rfil: NDArray[float64],
+    zfil: NDArray[float64],
+    rprime: NDArray[float64],
+    zprime: NDArray[float64],
+) -> tuple[NDArray[float64], NDArray[float64]]:
+    """
+    Off-axis Br,Bz components for a circular current filament in vacuum.
+
+    Near-exact formula (except numerically-evaluated elliptic integrals)
+    See eqns. 12, 13 pg. 34 in [1], eqn 9.8.7 in [2], and all of [3].
+
+    Note the formula for Br as given by [1] is incorrect and does not satisfy the
+    constraints of the calculation without correcting by a factor of ($z / r$).
+
+    References:
+        [1] D. B. Montgomery and J. Terrell,
+            “Some Useful Information For The Design Of Aircore Solenoids,
+            Part I. Relationships Between Magnetic Field, Power, Ampere-Turns
+            And Current Density. Part II. Homogeneous Magnetic Fields,”
+            Massachusetts Inst. Of Tech. Francis Bitter National Magnet Lab, Cambridge, MA,
+            Nov. 1961. Accessed: May 18, 2021. [Online].
+            Available: <https://apps.dtic.mil/sti/citations/tr/AD0269073>
+
+        [2] 8.02 Course Notes. Available:
+        <https://web.mit.edu/8.02t/www/802TEAL3D/visualizations/coursenotes/modules/guide09.pdf>
+
+        [3] Eric Dennyson, "Magnet Formulas". Available:
+        <https://tiggerntatie.github.io/emagnet-py/offaxis/off_axis_loop.html>
+
+    Args:
+        ifil: [A] filament current
+        rfil: [m] filament R-coord
+        zfil: [m] filament Z-coord
+        rprime: [m] Observation point R-coord
+        zprime: [m] Observation point Z-coord
+
+    Returns:
+        [T] (Br, Bz) flux density components
+    """
+    ifil = ascontiguousarray(ifil)
+    rfil = ascontiguousarray(rfil)
+    zfil = ascontiguousarray(zfil)
+    rprime = ascontiguousarray(rprime)
+    zprime = ascontiguousarray(zprime)
+    Br, Bz = em_flux_density_circular_filament(ifil, rfil, zfil, rprime, zprime)
+    return Br, Bz  # [T]
+
+
+def flux_density_biot_savart(
+    xyzp: Array3xN,
+    xyzfil: Array3xN,
+    dlxyzfil: Array3xN,
+    ifil: NDArray[float64],
+    par: bool = True,
+) -> Array3xN:
+    """
+    Biot-Savart law calculation for B-field contributions from many filament segments
+    to many observation points.
+
+    This calc is fairly well-optimized under the constraint to keep peak RAM usage to
+    O(n) in n observation points, which precludes tiling. It comes out about 20% faster
+    than an equivalent implementation in numba, which is about 4x faster than an
+    equivalent implementation in numpy.
+
+    Args:
+        xyzp: [m] x,y,z coords of observation points
+        xyzfil: [m] x,y,z coords of current filament origins (start of segment)
+        dlxyzfil: [m] x,y,z length delta of current filaments
+        ifil: [A] current in each filament segment
+        par: Whether to use CPU parallelism
+
+    Returns:
+        [T] (Bx, By, Bz) magnetic flux density at observation points
+    """
+    xyzp = (
+        ascontiguousarray(xyzp[0]),
+        ascontiguousarray(xyzp[1]),
+        ascontiguousarray(xyzp[2]),
+    )
+    xyzfil = (
+        ascontiguousarray(xyzfil[0]),
+        ascontiguousarray(xyzfil[1]),
+        ascontiguousarray(xyzfil[2]),
+    )
+    dlxyzfil = (
+        ascontiguousarray(dlxyzfil[0]),
+        ascontiguousarray(dlxyzfil[1]),
+        ascontiguousarray(dlxyzfil[2]),
+    )
+    ifil = ascontiguousarray(ifil)
+    return em_flux_density_biot_savart(xyzp, xyzfil, dlxyzfil, ifil, par)
+
+
+def inductance_piecewise_linear_filaments(
+    xyzfil0: Array3xN,
+    dlxyzfil0: Array3xN,
+    xyzfil1: Array3xN,
+    dlxyzfil1: Array3xN,
+    self_inductance: bool = False,
+) -> float:
+    """
+    Estimate the mutual inductance between two piecewise-linear current filaments,
+    or estimate self-inductance by passing the same filaments twice and setting
+    `self_inductance = True`.
+
+    It may be easier to use wrappers of this function that are specialized for self- and mutual-inductance
+    calculations:
+    [`self_inductance_piecewise_linear_filaments`][cfsem.self_inductance_piecewise_linear_filaments]
+    and [`mutual_inductance_piecewise_linear_filaments`][cfsem.mutual_inductance_piecewise_linear_filaments].
+
+    Uses Neumann's Formula for the mutual inductance of arbitrary loops, which is
+    originally from [2] and can be found in a more friendly format on wikipedia.
+
+    When self_inductance flag is set, zeroes-out the contributions from self-pairings
+    to resolve the thin-filament self-inductance singularity and replaces the
+    segment self-inductance term with an analytic value from [3].
+
+    Assumes:
+
+    * Thin, well-behaved filaments
+    * Uniform current distribution within segments
+        * Low frequency operation; no skin effect
+          (which would reduce the segment self-field term)
+    * Vacuum permeability everywhere
+    * Each filament has a constant current in all segments
+      (otherwise we need an inductance matrix)
+
+    References:
+        [1] “Inductance,” Wikipedia. Dec. 12, 2022. Accessed: Jan. 23, 2023. [Online].
+            Available: <https://en.wikipedia.org/w/index.php?title=Inductance>
+        
+        [2] F. E. Neumann, “Allgemeine Gesetze der inducirten elektrischen Ströme,”
+            Jan. 1846, doi: [10.1002/andp.18461430103](https://doi.org/10.1002/andp.18461430103)
+        
+        [3] R. Dengler, “Self inductance of a wire loop as a curve integral,”
+            AEM, vol. 5, no. 1, p. 1, Jan. 2016, doi: [10.7716/aem.v5i1.331](https://doi.org/10.7716/aem.v5i1.331)
+
+    Args:
+        xyzfil0: [m] Nx3 point series describing the filament origins
+        dlxyzfil0: [m] Nx3 length vector of each filament
+        xyzfil1: [m] Nx3 point series describing the filament origins
+        dlxyzfil1: [m] Nx3 length vector of each filament
+        self_inductance: Whether this is being used as a self-inductance calc
+
+    Returns:
+        [H] Scalar inductance
+    """
+    xyzfil0 = (
+        ascontiguousarray(xyzfil0[0]),
+        ascontiguousarray(xyzfil0[1]),
+        ascontiguousarray(xyzfil0[2]),
+    )
+    dlxyzfil0 = (
+        ascontiguousarray(dlxyzfil0[0]),
+        ascontiguousarray(dlxyzfil0[1]),
+        ascontiguousarray(dlxyzfil0[2]),
+    )
+    xyzfil1 = (
+        ascontiguousarray(xyzfil1[0]),
+        ascontiguousarray(xyzfil1[1]),
+        ascontiguousarray(xyzfil1[2]),
+    )
+    dlxyzfil1 = (
+        ascontiguousarray(dlxyzfil1[0]),
+        ascontiguousarray(dlxyzfil1[1]),
+        ascontiguousarray(dlxyzfil1[2]),
+    )
+    return em_inductance_piecewise_linear_filaments(
+        xyzfil0, dlxyzfil0, xyzfil1, dlxyzfil1, self_inductance
+    )
+
+
+def gs_operator_order2(rs: NDArray[float64], zs: NDArray[float64]) -> Array3xN:
+    """Build second-order Grad-Shafranov operator in triplet format.
+    Assumes regular grid spacing.
+
+    Args:
+        rs: [m] r-coordinates of finite difference grid
+        zs: [m] z-coordinates of finite difference grid
+
+    Returns:
+        Differential operator as triplet format sparse matrix
+    """
+    rs = ascontiguousarray(rs)
+    zs = ascontiguousarray(zs)
+    return em_gs_operator_order2(rs, zs)
+
+
+def gs_operator_order4(rs: NDArray[float64], zs: NDArray[float64]) -> Array3xN:
+    """
+    Build fourth-order Grad-Shafranov operator in triplet format.
+    Assumes regular grid spacing.
+
+    Args:
+        rs: [m] r-coordinates of finite difference grid
+        zs: [m] z-coordinates of finite difference grid
+
+    Returns:
+        Differential operator as triplet format sparse matrix
+    """
+    rs = ascontiguousarray(rs)
+    zs = ascontiguousarray(zs)
+    return em_gs_operator_order4(rs, zs)
+
+
+def filament_helix_path(
+    path: Array3xN,
+    helix_start_offset: tuple[float, float, float],
+    twist_pitch: float,
+    angle_offset: float,
+) -> NDArray[float64]:
+    """
+    Filamentize a helix about an arbitrary piecewise-linear path.
+
+    Assumes angle between sequential path segments is small and will fail
+    if that angle approaches or exceeds 90 degrees.
+
+    The helix initial position vector, helix_start_offset, must be in a plane normal to
+    the first path segment in order to produce good results. If it is not in-plane,
+    it will be projected on to that plane and then scaled to the magnitude of its
+    original length s.t. the distance from the helix to the path center is preserved
+    but its orientation is not.
+
+    Description of the method:
+
+    1. Translate [filament segment n-1] to the base of [path segment n]
+        and call it [filament segment n]
+    2. Take cross product of [path segment n] with [path segment n-1]
+    3. Rotate [filament segment n] segment about the axis of that cross product
+        to bring it into the plane defined by [path segment n] as a normal vector
+    4. Rotate [filament seg. n] about [path seg. n] to continue the helix orbit
+
+    Args:
+        path: [m] 3xN Centerline points
+        helix_start_offset: [m] (3x1) Initial position of helix rel. to centerline path
+        twist_pitch: [m] (scalar) Centerline length per helix orbit
+        angle_offset: [rad] (scalar) Initial rotation offset about centerline
+
+    Returns:
+        [m] 3xN array of points on the helix that twists around the path
+    """
+
+    # Make sure input is contiguous, reallocating only if necessary
+    path = ascontiguousarray(path)
+
+    # Allocate output
+    helix = zeros_like(path)  # [m]
+
+    # Calculate, mutating output
+    em_filament_helix_path(
+        (*path,),
+        helix_start_offset,
+        twist_pitch,
+        angle_offset,
+        (*helix,),
+    )
+
+    return helix  # [m]
+
+
+def rotate_filaments_about_path(
+    path: Array3xN, angle_offset: float, fils: Array3xN
+) -> NDArray[float64]:
+    """
+    Rotate a path of point about another path.
+
+    Intended for rotating a helix generated by [`filament_helix_path`][cfsem.filament_helix_path]
+    about the centerline that was used to generate it.
+
+    Args:
+        path: [m] x,y,z Centerline points
+        angle_offset: [rad] (scalar) Initial rotation offset about centerline
+        fils: [m] x,y,z Filaments to rotate around centerline
+
+    Returns:
+        [m] 3xN array of points on the helix that twists around the path
+    """
+
+    # Make sure input is contiguous, reallocating only if necessary
+    path = ascontiguousarray(path)
+
+    new_fils = ascontiguousarray(fils).copy()
+
+    em_rotate_filaments_about_path(
+        (*path,),
+        angle_offset,
+        (*new_fils,),
+    )
+
+    return new_fils  # [m]

cfsem/types.py

@@ -0,0 +1,7 @@
+from typing import Tuple, Union
+from numpy.typing import NDArray
+from numpy import float64
+
+Array3xN = Union[
+    NDArray[float64], Tuple[NDArray[float64], NDArray[float64], NDArray[float64]]
+]

cfsem-2.0.4.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.3
+Name: cfsem
+Version: 2.0.4
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: numpy >=2
+Requires-Dist: interpn >=0.2.2
+Requires-Dist: pytest >=7.1.3 ; extra == 'dev'
+Requires-Dist: coverage >=6.5.0 ; extra == 'dev'
+Requires-Dist: ruff >=0.4.2 ; extra == 'dev'
+Requires-Dist: pyright >=1.1.331 ; extra == 'dev'
+Requires-Dist: scipy >=1.8 ; extra == 'dev'
+Requires-Dist: mkdocs >=1.6.0 ; extra == 'dev'
+Requires-Dist: mkdocs-material >=9.5.25 ; extra == 'dev'
+Requires-Dist: mkdocstrings[python] >=0.25.1 ; extra == 'dev'
+Requires-Dist: matplotlib >=3.9 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Quasi-steady electromagnetics including filamentized approximations, Biot-Savart, and Grad-Shafranov.
+Author-email: jlogan@cfs.energy
+License: MIT
+Requires-Python: >=3.9, <3.13
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# cfsem
+
+[Docs - Rust](https://docs.rs/cfsem) | [Docs - Python](https://cfsem.readthedocs.io/)
+
+Quasi-steady electromagnetics including filamentized approximations, Biot-Savart, and Grad-Shafranov.
+
+## Installation
+
+Requirements
+
+* Python 3.9-3.12 and pip
+* Don't worry about this:
+  * This info provided for troubleshooting purposes:
+  * If on an x86 processor, you will need a CPU that supports SSE through 4.1, AVX, and FMA.
+  * This should be true on any modern machine.
+
+```bash
+pip install cfsem
+```
+
+## Development
+
+Requirements
+
+* [Rust](https://www.rust-lang.org/tools/install)
+
+To install in the active python environment, do
+
+```bash
+pip install -e .[dev]
+```
+
+To build the Rust bindings only, do
+
+```bash
+maturin develop --release
+```
+
+No part of installation requires root. If access issues are encountered, this can likely be resolved by using a virtual environment.
+
+Some computationally-expensive calculations are written in Rust. These calculations and their python bindings are compiled during installation with no intervention from the user. Symmetric bindings with docstrings are available in the `bindings.py` module and re-exported at the library level.
+
+To build with all of the optimizations available on your local machine, you can do:
+
+```bash
+RUSTCFLAGS="-Ctarget-cpu=native" maturin develop --release
+pip install -e .[dev]
+```
+
+## Contributing
+
+Contributions consistent with the goals and anti-goals of the package are welcome.
+
+Please make an issue ticket to discuss changes before investing significant time into a branch.
+
+Goals
+
+* Library-level functions and formulas
+* Comprehensive documentation including literature references, assumptions, and units-of-measure
+* Quantitative unit-testing of formulas
+* Performance (both speed and memory-efficiency)
+  * Guide development of performance-sensitive functions with structured benchmarking
+* Cross-platform compatibility
+* Minimization of long-term maintenance overhead (both for the library, and for users of the library)
+  * Semantic versioning
+  * Automated linting and formatting tools
+  * Centralized CI and toolchain configuration in as few files as possible
+
+Anti-Goals
+
+* Fanciness that increases environment complexity, obfuscates reasoning, or introduces platform restrictions
+* Brittle CI or toolchain processes that drive increased maintenance overhead
+* Application-level functionality (graphical interfaces, simulation frameworks, etc)
+
+## License
+
+Licensed under the MIT license ([LICENSE](LICENSE) or http://opensource.org/licenses/MIT) .
+

cfsem-2.0.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+cfsem-2.0.4.dist-info/METADATA,sha256=HBjZT0DVx0JtWcRp5McLcmP0RdKdLnX2_KCi3QnLe8M,3649
+cfsem-2.0.4.dist-info/WHEEL,sha256=iLyJQhiiBYwo5FdZQS-97uaKimQdR9d5M5S1bVJlIxM,94
+cfsem-2.0.4.dist-info/license_files/LICENSE,sha256=Z0UP8fLqfO3bA_i2g9fzRBRjwB7lHUsnAB3jmtIW2PU,1105
+cfsem/bindings.py,sha256=1moqLIQUbikQOW4Av4S4ePK13prKsHIYIoEE9Tb4B3A,13698
+cfsem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cfsem/types.py,sha256=rr8VSLL4VkEZVmV4lSh9e6SO_MLBPTUcKME5nrIiS1Q,201
+cfsem/__init__.py,sha256=EK8b36_CPGgrTkYRRyQG56Zx3lHCHUnND654xv-4lKY,20536
+cfsem/_cfsem.cp39-win_amd64.pyd,sha256=Yu99cdcGpFylbEUrGkudxORt54yx6BdxnLxJfKQoG-A,486400
+cfsem-2.0.4.dist-info/RECORD,,

cfsem-2.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.7.0)
+Root-Is-Purelib: false
+Tag: cp39-none-win_amd64

cfsem-2.0.4.dist-info/license_files/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Commonwealth Fusion Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.