Readme updated March 8, 2017

This is a field line follower for general geometry. Originally designed for
HSX it can handle any arbitrary 3d geometry. Input currently can be in the
form of coils where the integration is a biot-savart integration over the coil
segments, or from a precomputed magnetic grid (currently input in text form,
.nc support from mgrid files to be coming shortly.)

Input is in the form of a namelist, currently must be named 'flf.namelist' the
parameters will be included below. The main section of the namelist is
designated with flf flag, and there may be additional sections. A description
of the namelist parameters and necessary auxiliary files are below.

The output is in two forms. The output file gives limited information for each
point usually in the form of where it started, where it stopped, and whether
it hit anything. In addition most versions of the code print out to the screen
more detailed information, including position at each step. 

--------NAMELIST PARAMETERS-----------

general_option (default 1): This is the type of operation for the code. The
following options are currently available.

1 - field line following (default)
2 - no following is done, the magnetic field components Bx, By, Bz along with
the |B| are output for each input point
3 - calculation of epsilon effective. This is slow unless a magnetic grid is
specified.
0 - Tests - requires HSX coil, vessel and divertor files.

output_coils: (default 0) If set to 1, the code will write a coils.out file
with a representation of all the coils and the associated currents. Useful for
debugging to make sure that all the coils are being replicated properly and
the currents are going in the correct directions.

points_file: (default 'points.in') Name of the file to load the starting
points, see below for the description of the format for this file.

points_number: (default 1) Number of points to load

n_iter: (default 1) for options 1 (field line following) and 3 (epsilon
effective) this is the number of iterations to call. This is unused for
magnetic field output.

points_dphi: distance in phi to travel for each iteration.

follow_type: there are different options for following the field
follow_type=1: use phi as the independent variable
follow_type=2: use arclength as the independent variable
follow_type=3: use chi = dl dot B as the independent variable
follow_type=4: use gboozer (?) as the independent variable

in all cases points_dphi represents the follow distance in the appropriate variable. dphi is a legacy name and it will be changed at some point

field_type: This specifies the input type for the field, there are three options:
field_type='coils' is coil files (see below for format), 
field_type='ascii' is an ASCII magnetic grid file (see below for format)
field_type='netcdf' is a .nc file created by xgrid 

in the case of 'ascii' or 'netcdf' files num_main_coils should be set to 0

num_main_coils: (necessary) This is the number of coil files. If 1 or greater
a &coils section must be included with the names of the coil files in the
namelist. If 0, then mgrid_file must be set. See below for formatting
information for both of these.

mgrid_file: Name of the mgrid file, needed if num_main_coils is 0 or less.

num_periods: (default 4) Number of periods. Coil files or mgrid files only
need to be included for one period. The code will replicate for other periods.

is_mirrored: (default 0) For 4 period machines there is an option to only
include half a period worth of coils. (this does not work for different
periodicities.) Set this to 1 for mirroring.

skip_value: (default 1) For large coil files it is sometimes useful to not
read in every segment in order to speed up computation. Set this to N to only
read in every Nth point.

main_winding: (default 1) Use if the coil file includes multiple
windings. This is necessary for proper calculation of aux coils which tend to
have currents scaled to total values of the main current. See the description
for aux_percent in the coil section for an explanation of how this works.

vessel_file: (default '') Set to a vessel file name in order to activate
vessel termination. If a vessel file is included, the code will check at each
step to verify that the point is inside the vessel. If it is found outside,
the point will terminate and the termination location will be reported.

results_file: (default 'results.out') Place to store the point beginning and
termination output.

num_aux_coils: (default 0) Number of auxiliary coils to include. If this is
set to nonzero an aux_file must be included.

aux_file: file to read the aux coils. See below for format information

num_divertors: (default 0) Number of divertors to include. If set to greater
than 0, a &div section must be included in the namelist. See below.

mag_axis: (default '') Must be included if divertors are set (or Boozer
diffusion is set, see below). Gives the location of a magnetic axis file.

num_limiters: (default 0) Number of limiters, if set a &lim must be included.

use_diffusion (default 0): Set to 1 or 2 to include diffusion. 1 is random
perpendicular diffusion and 2 is boozer's spiraling out method. 

diffusion_species: (default 0): 0 for protons, 1 for electrons, used for
diffusion option 1.

d_perp: For diffusion option 1, this is the perpendicular diffusion parameter
in units of m^2/s

temperature: For diffusion option 1, this is the temperature of the particle
in eV

boozer_step: For diffusion option 2, this is how large to spiral out on each
spiral out attempt.

boozer_phi: For diffusion option 2, this is how many iteration steps to take
before spiraling outward.  

lcfs_file (default 1): A description of the last closed flux surface. If this
is set the code will calculate the distance from the LCFS for each point and
record that instead of the magnetic field in the logged output.

In addition to the main section of the namelist additional sections are
required if coils, divertors or limiters are to be included. These sections
are separated because the size of the various arrays need to be initialized
based on values in the main namelist. This provides a convenient separation.

&coils section (needed if num_main_coils >= 1)

main_files: A list of all the coil files to load. The length must match that
given in num_main_coils

main_current_repeat (default 0): Set to 1 if all main coils have the same
current, then only a single value is needed for the main_current entry.

main_current: A list of the currents (in amps) for each of the main coils, or
a single value if main_current_repeat is set

aux_percent: A list of the percentage of current for each of the aux coils,
scaled to the current in coil 1, multiplied by the value in main_winding. For
example, if coil one in main_current has 1kA and main_winding is set to 10,
then an aux_percent of 1.0 would give 10kA in the aux coils, and aux_percent
of 0.01 would give 100 Amps. The length of aux_percent must match the number
in num_aux_coils

&div section

div_files: This is the only entry, it is a list of files for the divertor
plates. The number of entries must match the number in num_div_files. This is
only read if num_div_files >= 1

&lim section

lim_files: Similar to div_files.

----------------DESCRIPTION OF FILE INPUTS------------

POINTS INPUT FILE

This is the file referenced in points_file in the namelist. There
are two forms, one for the generic field line following, and one for the
epsilon effective calculation.  For field line following points are provided
in r,z,phi (in meters) with phi in radians. Example of two lines

1.45 0.0 0.0
1.46 1.0 3.14

Two points are given the first at r = 1.45, z = 0.0 and phi = 0.0, the second
at r = 1.46, z = 1.0 and phi = pi.

For epsilon effective, the calculation only works for points at the outboard
side of the symmetry midplane. (The code assumes phi=0 is a symmetry plane,
some modifications are required if that's not true.) The input is two columns
per line, the first is the radial value and the second is a calculation of
dpsi/dr (dpsi/dz and dpsi/dphi are both zero).

COIL FILES

These are used if num_main_coils is greater than 1

Coil files all have the following form. The first line is the number of points
in the coil file. The rest of the lines are the coordinates for each
consecutive coil vertex in x,y,z (meters). Format similar to points input.

AUXILIARY COIL FILES

If num_aux_coils are greater than 1, then an aux file needs to be
specified. The format is similar to the coil files, except only one file is
given for all the aux coils. The first line in the file is the number of coils
altogether. This needs to be greater than the value of num_aux_coils to read in.

MAGNETIC GRID FILES

Reading a .nc mgrid is not yet supported. Instead an ascii representation is
given. The grid is a r,z,phi grid with uniform spacing in each direction.  The
format is as follows.  First the r coordinates are given, from smallest to
largest, one per line. Then the Z coordinates are given, from smallest to
largest, one per line. Then the phi coordinates are given from smallest to
largest one per line.

Then all the Br values are given, then all the Bz values, then all the bphi
values. For each the values are given as Br(phi0, z0, r0), Br(phi0, z0, r1)
... Br(phi0, z0, rn), Br(phi0, z1, r0), Br(phi0, z1, r1) ... Br(phi0, zn, rn),
Br(phi1, z0, r0) and so on.

VESSEL FILE
  
A vessel needs to span the exact same range as the coils. So if num periods is
four the vessel needs to span from 0 to pi/2. The first line of the vessel
file is the number of phi slices, then the number of poloidal slices. This is
followed by all the vessel points in x,y,z. Ordering first goes through all
points on one phi slice, then the next one. It is important that the first
point and the last point match (the vessel closes on itself) and that the
vessel values are as close as possible to the preceding one (since
slices of intermediate phis are formed by interpolation).

DIVERTOR FILE

This file input is a bit different because it uses the same input format as
EMC3 divertor files. First line is not used. Second line has 5 parameters,
only the first two are used. The first is the number of toroidal slices, the
second is the amount of points in each slide. This is then followed by each
toroidal slice in order. The toroidal slices look like toroidal position in
degrees, then R and Z value (in cm!). 

MAGNETIC AXIS FILE

Like the vessel, the magnetic axis must span the entire toroidal range. The
first line is the number of toroidal slices, this is followed by that number
of lines with R and Z values of the magnetic axis for each slice.

LCFS FILE

This is the same format as the vessel file.

LIMITER FILE

At some point I'll ask Laurie to write this part up.