(docs-forcecomp)=
# Force Computation (F, T)

## Computation Idea

Force and torque computation in Magpylib stands in contrast to the analytical models used for magnetic field computation. They are based on a numerical approach that solves the force integrals over the target objects by discretization, see also [Physics and Computation](guide-physics-force-computation).

-------------------------------------
## Force Interface

Force and torque are computed in the [object-oriented interface](docs-fieldcomp-oo) via the top level function **`getFT()`**

```python
F, T = magpylib.getFT(
    sources,
    targets,
    pivot="centroid",
    squeeze=True,
    meshreport=False,
    eps=1e-5,
)
```

where F is the force in units (N) and T is the torque in units (N*m) acting on the `targets` via the magnetic field generated by the `sources`. F and T are NumPy arrays of shape (s, p, t, 3), where s is the number of sources, p is the path length, and t is the number of targets.

- **`sources`**: single or 1D list of magnetic field generators
- **`targets`**: single or 1D list of targets (all Magpylib currents, magnets, and `Dipole`). All targets with exception of `Dipole` and `Sphere` objects must have the `meshing` parameter set (see below).
- **`pivot`**: The torque is always defined relative to a pivot point $\vec{r}_\text{piv}$, and the force adds to it via $\vec{T}_F = \vec{F} \times (\vec{r}_\text{piv} - \vec{r}_\text{pos})$. For a freely floating magnet this would be the barycenter (= centroid when the density is homogeneous). If `pivot='centroid'` the centroid is selected as the pivot point for all targets. If `pivot=None` no pivot is used. This will give nonphysical results. If `pivot` is array-like of shape (3,) the same pivot is used for all targets. Alternatively one can provide an individual pivot point for each target.
- **`eps`**: finite difference step size for computation of the magnetic field gradient (only needed for magnet targets). A good number is 1e-6 * characteristic source size.
- **`meshreport`**: Set to `True` for printing the number of mesh points of each target giving you an idea of the involved computation effort.
- **`return_mesh`**: Set to `True` for returning the mesh instead of F and T. In this case, a list of mesh dictionaries will be returned which have keys `"pts"`, `"moments"` (only magnets), and `"cvecs"` (only currents).

Each target must have the **`meshing`** parameter set to define the mesh discretization finesse. This is an integer number which defines the target number of mesh points. The meshing algorithms will not always create exactly the given target number, but aim to create uniform meshes with aspect ratio = 1 cells.

```{warning}
F and T are computed in SI units (N) for F and (N*m) T. Note that [scaling invariance](guide-docs-io-scale-invariance) does not hold for force computations! Be careful to provide the correct input units!
```

The following minimal example computes the force acting on a current loop, generated by a cuboid magnet.

```python
import numpy as np
import magpylib as magpy

cube = magpy.magnet.Cuboid(dimension=(1, 1, 1), polarization=(0.1, 0.2, 0.3))
loop = magpy.current.Circle(
    diameter=2,
    current=1e3,
    position=(0, 0, 1),
    meshing=40,
)
F, T = magpy.getFT(cube, loop)

print(f"force: {np.round(F, decimals=2)} N")
# force: [ 13.67  27.33 -82.  ] N

print(f"torque: {np.round(T, decimals=2)} N*m")
# torque: [-8.54  4.27  0.  ] N*m
```