Add iota calclulation from field line integration of a coilset/magnetic field

[dpanici]

When doing field line integration from a magnetic field, would be useful to also get out the iota values. Multiple ways to do this but the easiest to implement initially is probbaly to just do the literal definition for iota,

$$ \iota = \lim_{n\rightarrow \infty} \frac{1}{n} \sum_1^n \Delta \theta_n$$

where $\Delta \theta_n$ is the change in poloidal angle in the $\phi=0$ plane from the $n-1$ toroidal transit to the $n$ th toroidal transit, which could be calculated as $arctan(\frac{Z-Z_{axis}}{R-R_{axis}})$

Where iota is calculated in FOCUS, as an example

https://github.com/PrincetonUniversity/FOCUS/blob/be28c104bebc1b4ea281547b03fc1e9fab34e8e2/sources/poinplot.f90#L113

[dpanici]

Need rootfind to compute axis location

[dpanici]

Or can just supply any centroid etc as long as it is inside the surface the field line covers

[rahulgaur104]

theta_unwrapped = np.unwrap(theta_values)
phi_unwrapped = np.unwrap(phi_values)
iota = (theta_unwrapped[-1] - theta_unwrapped[0]) / (
    phi_unwrapped[-1] - phi_unwrapped[0]
)

Once you have your theta, zeta along a fieldline, the above logic will account for the sudden jumps from -pi to pi and give you the averaged iota. Note that the fieldline must be long enough for this to work.

[YigitElma]

@dpanici, did you want this to be a utility function? I think this is doable but I am not sure if this has enough use cases to have it in master (like besides post-processing, I don't think this is computationally viable). I mean you can find theta values using the magnetic axis from the Equilibrium, and phi is already an input to the field_line_integrate. One only needs to use a really high ntransit for the integration, and I think having this in CI will take too much time.

[dpanici]

CI could use a simple field like field from an on-axis wire current and a ToroidalMagneticField, and that should converge almost immediately

I think it is a very useful utility function as comparing iota of a vacuum eq to the vacuum field iota is a good way of checking accuracy of the eq solution