This material is based upon work supported by the National Science Foundation
under Grants No.~0454610 and 0519107.

The code in this directory implements:

    "Green's Function for Potential Field Extrapolation" (G. Barnes)

Can be run as a self-contained Fortran (90) program, or can
be compiled as a shared object usable by IDL via call_external.
Compatible with Intel's "ifort" Fortran compiler, and Gnu's "gfortran"
compiler, either of which can be used via specifying an appropriate
"make" target.

-------------------------------------------------------------------------------

FILES:

 -- MAIN:

     IDL-calling-Fortran:

	fgfftest.pro  - IDL program to call fgff.pro, and run test case
			To run:  IDL> fgfftest

	fgff.pro      - IDL function, calls Fortran fgff_sub() indirectly
			To use:  IDL> f = fgff(bz, Nz)  (shortcut optional)

     Fortran-calling-Fortran:

	fgfftest.F90 - FORTRAN program calls fgff_sub(); runs test case

	fgff.F90 - Contains fgff_sub() subroutine, and the fgff wrapper
		function which facilitates use by IDL, via call_external
	  -fgff_sub() - Calls gff to get the Green's function field on the 6
	  	walls, and then calls fff6 to derive the potential field.

 -- MODULES:

    	gff_m.F90 - Green's function code

	  -gff() - called by fgff_sub; calls green_field
	  -green_field() - called by gff
             Set compiler flag according how to compute Bz term:
		"-DBzAtanX2" - Eqn 11 terms combined for two atan calls
		(default, no compiler flags) - Terms combined for 1 atan call
			This was observed to be slower in many cases.

    	fff_m.F90 - FFT-based code 

	  -fff6() - called by fgff_sub; calls fff1
	  -fff1() - called by fff6

    	constants.F90 - contains constants such as PI, dPI, etc.

    	fftw_m.F90
	  -fftw2D() - 2D FFTW3 wrapper subroutine
	  -dfftw2D() - As above, but double precision throughout (no conversion)
	  -fftw() - 1D Wrapper function for FFTW3 library; IDL-style calling.
	  	    Real arguments; converts to, and back from, double
	  -dfftw() - As above, but double precision throughout (no conversion)

    	findgen_m.F90 - functions to roughly reproduce similar IDL functions
	  -findgen()
	  -dfindgen()
	  -lindgen()
	  -lindgen2D()

 -- Makefile

      By default, typing "make" compiles a shared object w/ Intel compiler.

      Fortran program targets:	[e.g., "make itest"]
	-itest - make "fgfftest_i" Intel-fortran-compiled binary for test case
	-gtest - make "fgfftest_g" Gnu-fortran-compiled binary for test case

      Shared object targets:	[e.g., "make intel"]
	-intel - build fgff.so (used in fgffrun.pro) with Intel compiler
	-gnu   - build fgff.so (used in fgffrun.pro) with Gnu compiler

      Other targets:		[e.g., "make clean"]
	-clean - remove *.mod, *.o, *.out *.so
	-tar - create a tar ball of README, Makefiles, code - stored in TARDIR

 -- README - this file

 -- gfp.pdf - Paper on which this code is based

 -- idl2ftn.pro - IDL routine to save data to a Fortran-readable .dat file

 -- test_field.sav - test case IDL sav file

 -- test_field.dat - test case in fortran-readable form, read by fgfftest.F90
 			(use idl2ftn.pro to get this from test_field.sav)

-------------------------------------------------------------------------------
AUTHOR:  Coded by Eric Wagner, Aug-Sep 2009, with due credit to
	 G. Barnes, T. Metcalf for ideas/code taken from their IDL version.
-------------------------------------------------------------------------------
NOTES:

 Suffix descriptions:
    pro - IDL function/procedure
    sav - IDL save file - a recoverable dump of variable(s) in memory
    F90 - Fortran90 code, run through C pre-processor (for #include #if etc.)
    f90 - Regular Fortran90 code
    mod - Fortran module files that appear at compilation - remove at will

-------------------------------------------------------------------------------

TEST CASE DATA: 		20090818 - from GB

/data/cora/SOLMAG/ANALYSIS/POTENTIAL/test_field.sav

IDL save set containing a potential field array, b,
with dimensions nx=128, ny=128, nz=128, 3, in

/data/cora/SOLMAG/ANALYSIS/POTENTIAL/test_field.sav.

Access in IDL with:

        restore,/verbose,'test_field.sav'

The boundary condition which is input to the Green's function code is the
two-dimensional array b[*,*,0,2]. From this, the Green's function code
should be able to very accurately reconstruct the full array, where by
very accurately, I mean the differences should be something like 10-4. As
a test, you can always use the IDL version of the code.

This test case is more or less an ideal case, where all the assumptions
that are made in calculating the field should be very good. At some point,
we may try some harder cases, to see how things start to fail, but
hopefully this will get you started.

-------
B(50,50,0,2) is the/a maximum value, of .856509

-------------------------------------------------------------------------------

Running in double precision:

    Set -DDPRECISION on the compile line.

    Affects these files:
	    constants.F90
	    fff_m.F90
	    gff_m.F90
	    fgff.F90
	    fgffmain.F90

    You will see the following (or similar) near the head in each file:
	#ifdef DPRECISION
	#define float double precision
	#define flt dble
	#define complex double complex
	#define cmplx dcmplx
	#define alog dlog
	#define atan datan
	#define sqrt dsqrt
	#define fftw2d dfft2d
	#else
	#define float real
	#define flt real
	#endif
-------------------------------------------------------------------------------