Merge branch 'master' of https://github.com/archermarx/LoopFieldCalc.jl into master

Author: archermarx

README.md

@@ -1,6 +1,140 @@
 # LoopFieldCalc
 
-[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://archermarx.github.io/LoopFieldCalc.jl/stable)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://archermarx.github.io/LoopFieldCalc.jl/dev)
 [![Build Status](https://travis-ci.com/archermarx/LoopFieldCalc.jl.svg?branch=master)](https://travis-ci.com/archermarx/LoopFieldCalc.jl)
 [![Coverage](https://codecov.io/gh/archermarx/LoopFieldCalc.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/archermarx/LoopFieldCalc.jl)
+
+Compute the magnetic field due to current-carrying loops at arbitrary locations.
+
+## Example 1: Field due to a single loop
+
+We define a current loop as follows
+
+```julia
+# Define current loop with radius of 50 cm, current of 1 A, centered at the origin
+loop = LoopFieldCalc.CurrentLoop(
+  radius = 0.5,         # radius in meters
+  current = 1.0,        # current in Amperes
+  center = LoopFieldCalc.CartesianPoint(0.0, 0.0, 0.0)    # cartesian coordinates of the loop center
+)
+```
+
+Loop center coordinates can be specified using either cartesian coordinates or cylindrical coordinates.
+
+```julia
+# Define current loop with radius of 50 cm, current of 1 A, centered at the origin
+loop = LoopFieldCalc.CurrentLoop(
+  radius = 0.5,         # radius in meters
+  current = 1.0,        # current in Amperes
+  center = LoopFieldCalc.CylindricalPoint(0.0, 0.0, 0.0)    # cartesian coordinates of the loop center
+)
+```
+
+To compute the magnetic field components at a given point, use the `field_at_point` function. The loop normal vector is assumed to be parallel to the `z` axis.
+
+```julia
+# Define the point at which the magnetic field is computed in Cartesian space
+point_to_compute = LoopFieldCalc.CartesianPoint(1.0, 1.0, 1.0)  
+
+# Compute the field strength, stream function, and scalar potential
+Bx, By, Bz, stream_func, scalar_potential = LoopFieldCalc.field_at_point(loop, point_to_compute)
+```
+
+If you want to compute the magnetic field at many points, you can broadcast `field_at_point` over a `Vector` of `CartesianPoints`
+
+```julia
+
+# Define equally-spaced points along the z-axis
+points = [LoopFieldCalc.CartesianPoint(0.0, 0.0, z) for z in 0.0:0.1:2.0]
+
+# Compute the field at these points
+fields = LoopFieldCalc.field_at_point.(loop, points)
+
+```
+
+If your points form a regularly-spaced grid, you can use the `field_on_grid` function to compute the magnetic field due to multiple loops at the grid points
+
+```julia
+# Define grid points along x, y, and z axes. We have a 2D grid of points in the y-z plane.
+xs = 0.0:0.0
+ys = -1.0:0.01:1.0
+zs = -2.0:0.01:2.0
+
+# Define current loops. Here, we only have the single loop, defined above
+loops = [loop]
+
+# Compute the magnetic field components
+Bx, By, Bz = LoopFieldCalc.field_on_grid(loops, xs, ys, zs)
+```
+
+You can write output of this function to a Tecplot-compatible ASCII data format
+```julia
+LoopFieldCalc.write_field("examples/example_1.dat", ys, zs, By[1, :, :], Bz[1, :, :])
+```
+
+We can visualize this in Tecplot:
+
+![](https://github.com/archermarx/LoopFieldCalc.jl/blob/master/examples/example_1.png)
+
+
+## Example 2: 2D magnetic field due to offset concentric coils
+
+This example computes the field generated by the magnetic coil configuration below
+
+![](https://github.com/archermarx/LoopFieldCalc.jl/blob/master/examples/example_2_setup.png)
+
+```julia
+using LoopFieldCalc
+
+# Define grid on which we compute magnetic field strength.
+# This is a 2D grid in the y-z plane
+xs = 0.0:0.0
+ys = -0.4:0.005:0.4
+zs = -0.3:0.005:0.3
+
+# Define number of wire turns per coil
+nturns = 10
+
+# Define geometry of inner coil
+inner_coil_radius = 0.1
+inner_coil_width = 0.15
+inner_coil_offset = -0.1
+inner_coil_current = 1.0
+
+# Generate loops for inner coil
+inner_coil = [
+    LoopFieldCalc.CurrentLoop(
+        radius = inner_coil_radius,
+        current = inner_coil_current / nturns,
+        center = LoopFieldCalc.CylindricalPoint(inner_coil_offset + z, 0.0, 0.0)
+    )
+    for z in LinRange(0.0, inner_coil_width, nturns)
+]
+
+# Define geometry for outer coil
+outer_coil_radius = 0.25
+outer_coil_width = 0.15
+outer_coil_offset = -0.15
+outer_coil_current = 0.3 * inner_coil_current
+
+# Generate loops for outer coil
+outer_coil = [
+    LoopFieldCalc.CurrentLoop(
+        radius = outer_coil_radius,
+        current = outer_coil_current / nturns,
+        center = LoopFieldCalc.CylindricalPoint(outer_coil_offset + z, 0.0, 0.0)
+    )
+    for z in LinRange(0.0, outer_coil_width, nturns)
+]
+
+# Combine inner and outer coil loops into a single vector and compute field
+loops = [outer_coil; inner_coil]
+Bx, By, Bz = LoopFieldCalc.field_on_grid(loops, xs, ys, zs)
+
+# Write output. By reversing z and y and transposing the magnetic field matrices, we
+# can rotate the output so that the loop axis is aligned with the x axis
+LoopFieldCalc.write_field("examples/example_2.dat", zs, ys, Bz[1, :, :]', By[1, :, :]')
+```
+
+The result (visualized in Tecplot) is below
+
+![](https://github.com/archermarx/LoopFieldCalc.jl/blob/master/examples/example_2.png)