# `oersted`

Approximate Biot-Savart Law integration to calculate magnetic fields in near-linear time using octrees and the Barnes Hut algorithm.

[Documentation](https://retkins.github.io/oersted) | [Rust API](https://docs.rs/oersted/0.1.0/oersted/)

![Timing Results](docs/figs/benchmarks.svg)

## Installation

`oersted` can be installed via pypi:
```bash
pip install oersted
```


### Example
```python
import oersted 

# Assume the following NumPy arrays are already defined: 
# centroids: Nx3 element centroid locations
# vol: N-length, volume of each element 
# jdensity: Nx3 elemental current-density vectors 
# targets: Nx3 target point locations in 3D space 

theta = 0.25        # B-H accuracy parameter

# Compute the magnetic flux density at each target
b = oersted.bfield_octree(
    centroids, vol, jdensity, targets, theta=theta
)
```

## Background

*This is a prototype code and not meant for production applications.*  

The Biot-Savart Law is widely used to calculate the magnetic fields of electromagnets by summing the contributions of many small magnetic field sources at a large number of target points. This calculation, in its simplest form, has time complexity of `O(M x N)`, where `M` is the number of source points and `N` is the number of target points. 

### Barnes-Hut Algorithm
This code applies the [Barnes Hut algorithm](https://en.wikipedia.org/wiki/Barnes%E2%80%93Hut_simulation) for large-N interaction problems to achieve linear time complexity of the same calculation while maintaining reasonable (<1%) error relative to the full ("direct") calculation.  

Effectively, the program uses an octree, which is a tree structure that divides the problem space recursively into 8 octants. Each octant hosts a collection of source points, which are summed together at each node. If the distance between the node and a target point is far enough away such that treating the many source points within the node as one large "super source", the node is 'accepted' and an approximate calculation is performed. If the node is too close, then it is recursively subdivided and the same acceptance criteria is applied again. In practice, an acceptance criteria of `phi = node_size/distance = 0.5` has been found to be effective for self-fields problems. 

See [https://jheer.github.io/barnes-hut/](https://jheer.github.io/barnes-hut/) for an excellent demo of the algorithm applied to gravitational problems. 

### Intended Problems

The intended problem for this code is a finite element mesh of a *solenoidal* collection of current-carrying 3D bodies. The magnetic field generated by these currents can either be computed on the bodies themselves (self-field) or at a collection of points not on the bodies. Each element is treated as a component of a finite sum approximation to the Biot Savart integral. 

Problem sizes typically solved on a workstation computer (i.e. finite element meshes of <10M elements) are considered for testing of this code. 


## License
[MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option.