Mees Ambiguity resolution - Standard Code

	Barry LaBonte   August 17, 2000


ivm_current.pro: IDL Currents Magnetograms

This procedure is a slight modification of the procedure current.pro
written by Tom Metcalf for the Haleakala Stokes Polarimeter data.
A description of the operation and use of the code follows.

The program "imv_current.pro" is ready for use.  It reads a magnetic field FITS
file, resolves the 180 degree ambiguity and computes the vertical current.

The first step in the ambiguity resolution is to resolve the ambiguity
using the potential field calculated from the observed normal field.  The
next step uses the acute angle method: vectors are flipped iteratively
until they make an acute angle with their neighbors.  The final step in
the ambiguity resolution is to minimize the current in weak field regions
and to minimize the divergence of the field in the stronger field regions.
The divergence is computed with the observed dBx/dx and dBy/dy but with 
dBz/dz from the potential field calculation.

This final minimization step usually helps, but not always.  To turn off
the minimization of Jz and div B, use the "no_minimization" keyword.  The
program will then stop after the acute angle calculation.

Once the current is computed, the field and the current are displayed in
one window and a second "zoom" window is created.  Click the left mouse
button in the non-zoomed window to select a zoomed region.  A zoomed image
appears in the "zoom" window centered on the spot you clicked.   Click the
left button in the zoomed window to move the center of the zoomed image
and the middle mouse button to flip a vector:  point the cursor to the
base of the vector and click.   The right button exits the zoom window and
passes you back to the unzoomed window.  Press the right button to exit,
the middle button to flip a vector, or the left button to pick a new
zoomed image. 

It is possible that the program will get "stuck" and keep flipping the
same vectors back and forth.  The program checks for this and stops the
iteration in this case.  The raster points included in the "region of
conflict" are printed and displayed as red "blobs".

Procedure:
==========

1) Compile the necessary routines with ivm_current_compile.pro

2) Run ivm_current.pro:  the input is the name of a magnetic FITS file to 
   be read and analyzed.  The output is a new magnetic field structure
   with the resolved field and the current.

3) You will be prompted for one quantity:  the radiant point.  This
   is the point at which the ambiguity starts and it moves out radially
   from this point.  It is very important to pick a good point, preferably
   one where you feel the field is correctly resolved from the comparison
   with the potential field.  The center of a spot often works, and the 
   darkest point in the image is printed out to help with the selection.

WARNING: This program can get confused and you should always think very hard 
         about the results.


Keywords:
=========

  scale = sets the size of the plots: 1.0 is the default, 1.2 is 20% larger etc.
  integral_structure = passes a magnetic field structure to be merged with
                       the structure read by current.pro.  This is useful if 
                       current.pro reads the field computed with the Unno code 
                       and you want to merge the integral method results in the 
                       places where the Unno code did not compute the field.
  no_minimize = turn *off* the current/divergence minimization


Examples:
=========

Resolve ambiguity and compute vertical current

IDL> @ivm_current_compile
IDL> B = ivm_current('IMGM980618.1839')

Resolve ambiguity and compute vertical current, without the current/divB
minimization.  


IDL> @ivm_current_compile
IDL> B = ivm_current('B891020.1741',/no_min)