Installation and getting started

Requirements

Microcubed requires Python 3.12 or newer. Its runtime dependencies are NumPy, SciPy, and Matplotlib.

Installation

From a local checkout:

cd microcubed
python -m pip install .

For development and testing:

python -m pip install -e ".[dev]"
pytest

From a checkout, the locked environment can be used reproducibly:

uv run --frozen --extra dev pytest

Binary distributions include the integrated Rust backend. See Calculation backends for selection and source-build details:

python -m pip install microcubed

A first magnet

import numpy as np
from microcubed import Magnet

cube = Magnet(
    size=[100, 100, 100],
    center=[0, 0, 0],
    magnetization=[0, 0, 8e5],
)

points = np.array(
    [
        [0, 0, -75],
        [50, 0, -100],
        [100, 30, -150],
    ]
).T

B = cube.Bfield(points)
print("Field shape:", B.shape)
print("Field (T):\n", np.round(B, 6))

Field shape: (3, 3)
Field (T):
 [[ 0.       -0.063093 -0.017691]
 [ 0.        0.       -0.005228]
 [ 0.252455  0.081343  0.013553]]

Each column index identifies one point; the first axis contains Bx, By, and Bz.

Unit convention

Microcubed does not implement a unit system. Three rules apply:

  1. size, center, and points must use the same length unit.

  2. magnetization is specified in A/m.

  3. Bfield returns tesla; dBfield returns tesla per chosen length unit.

For geometry expressed in nanometres, the gradient is therefore in T/nm. For geometry expressed in metres, it is in T/m. Hfield and dHfield similarly return A/m and A/m per length unit.

Warning

Do not mix length units. A magnet defined in nanometres and points supplied in metres produce formally computable but physically incorrect results.

Point input

The following inputs are reshaped to (3, N):

for points in ([0, 0, -150], [[0, 10], [0, 0], [-150, -150]]):
    print(cube.Bfield(points))

[[0.        ]
 [0.        ]
 [0.04560013]]
[[ 0.         -0.00430062]
 [ 0.          0.        ]
 [ 0.04560013  0.04507234]]

A single Magnet masks points inside and on the boundary of the cuboid with NaN. For an Arrangement, no automatic interior check is performed for performance reasons; callers must exclude those points themselves.

Next steps