|
| 1 | +--- |
| 2 | +orphan: true |
| 3 | +jupytext: |
| 4 | + text_representation: |
| 5 | + extension: .md |
| 6 | + format_name: myst |
| 7 | + format_version: 0.13 |
| 8 | + jupytext_version: 1.13.7 |
| 9 | +kernelspec: |
| 10 | + display_name: Python 3 |
| 11 | + language: python |
| 12 | + name: python3 |
| 13 | +--- |
| 14 | + |
| 15 | +(docs-magpylib-force)= |
| 16 | +# Magpylib Force v0.3.1 |
| 17 | + |
| 18 | +The package `magpylib-force` provides an addon for magnetic force and torque computation between magpylib source objects. |
| 19 | + |
| 20 | +## Installation |
| 21 | + |
| 22 | +Install `magpylib-force` with pip: |
| 23 | + |
| 24 | +```console |
| 25 | +pip install magpylib-force |
| 26 | +``` |
| 27 | + |
| 28 | +## API |
| 29 | + |
| 30 | +The package provides only a single top-level function <span style="color: orange">**getFT()**</span> for computing force and torque. |
| 31 | + |
| 32 | +```python |
| 33 | +import magpylib_force as mforce |
| 34 | +mforce.getFT(sources, targets, anchor, eps=1e-5, squeeze=True) |
| 35 | +``` |
| 36 | + |
| 37 | +Here `sources` are Magpylib source objects that generate the magnetic field. The `targets` are the objects on which the magnetic field of the sources acts to generate force and torque. With current version 0.3.1 only `Cuboid`, `Cylinder`, `CylinderSegment`, `Polyline`, and `Circle` objects can be targets. The `anchor` denotes an anchor point which is the barycenter of the target. If no barycenter is given, homogeneous mass density is assumed and the geometric center of the target is chose as it's barycenter. `eps` refers to the finite difference length when computing the magnetic field gradient and should be adjusted to be much smaller than size of the system. `squeeze` can be used to squeeze the output array dimensions as in Magpylib's `getB`, `getH`, `getJ`, and `getM`. |
| 38 | + |
| 39 | +The computation is based on numerically integrating the magnetic field generated by the `sources` over the `targets`, see [here](docs-force-computation) for more details. This requires that each target has a <span style="color: orange">**meshing**</span> directive, which must be provided via an attribute to the object. How `meshing` is defined: |
| 40 | + |
| 41 | +For all objects as an integer, which defines the target number of mesh-points. In some cases an algorithm will attempt to come close to this number by splitting up magnets into quasi-cubical cells. Exceptions are: |
| 42 | + |
| 43 | +- `Cuboid`: takes also a 3-vector that defines the number of equidistant splits along each axis resulting in a rectangular regular grid. Keep in mind that the accuracy is increased by cubical aspect ratios. |
| 44 | +- `PolyLine`: defines the number of equidistant splits of each PolyLine segment, not of the whole multi-segmented object. The total number of mesh-points will be number of segments times meshing. |
| 45 | + |
| 46 | +The function `getFT()` returns force and torque as `np.ndarray` of shape (2,3), or (t,2,3) when t targets are given. |
| 47 | + |
| 48 | +The following example code computes the force acting on a cuboid magnet, generated by a current loop. |
| 49 | + |
| 50 | +```python |
| 51 | +import magpylib as magpy |
| 52 | +import magpylib_force as mforce |
| 53 | + |
| 54 | +# create source and target objects |
| 55 | +loop = magpy.current.Circle(diameter=2e-3, current=10, position=(0,0,-1e-3)) |
| 56 | +cube = magpy.magnet.Cuboid(dimension=(1e-3,1e-3,1e-3), polarization=(1,0,0)) |
| 57 | + |
| 58 | +# provide meshing for target object |
| 59 | +cube.meshing = (5,5,5) |
| 60 | + |
| 61 | +# compute force and torque |
| 62 | +FT = mforce.getFT(loop, cube) |
| 63 | +print(FT) |
| 64 | +# [[ 1.36304272e-03 6.35274710e-22 6.18334051e-20] # force in N |
| 65 | +# [-0.00000000e+00 -1.77583097e-06 1.69572026e-23]] # torque in Nm |
| 66 | +``` |
| 67 | + |
| 68 | +```{warning} |
| 69 | +[Scaling invariance](guide-docs-io-scale-invariance) does not hold for force computations! Be careful to provide the inputs in the correct units! |
| 70 | +``` |
| 71 | + |
| 72 | +(docs-force-computation)= |
| 73 | +## Computation details |
| 74 | + |
| 75 | +The force $\vec{F}_m$ acting on a magnetization distribution $\vec{M}$ in a magnetic field $\vec{B}$ is given by |
| 76 | + |
| 77 | +$$\vec{F}_m = \int \nabla (\vec{M}\cdot\vec{B}) \ dV.$$ |
| 78 | + |
| 79 | +The torque $\vec{T}_m$ which acts on the magnetization distribution is |
| 80 | + |
| 81 | +$$\vec{T}_m = \int \vec{M} \times \vec{B} \ dV.$$ |
| 82 | + |
| 83 | +The force $\vec{F}_c$ which acts on a current distribution $\vec{j}$ in a magnetic field is |
| 84 | + |
| 85 | +$$\vec{F}_c = \int \vec{j}\times \vec{B} \ dV.$$ |
| 86 | + |
| 87 | +And there is no torque. However, one must not forget that a force, when applied off-center, adds to the torque as |
| 88 | + |
| 89 | +$$\vec{T}' = \int \vec{r} \times \vec{F} \ dV,$$ |
| 90 | + |
| 91 | +where $\vec{r}$ points from the body barycenter to the position where the force is applied. |
| 92 | + |
| 93 | +The idea behind `magplyib-force` is to compute the above integrals by discretization. For this purpose, the target body is split up into small cells using the object `meshing` attribute. The force and torque computation is performed for all cells in a vectorized form, and the sum is returned. |
0 commit comments